企业官网建设流程全解析

qmd 命名索引：如何用 --index 在多套知识库索引之间切换

【免费下载链接】qmdmini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local项目地址: https://gitcode.com/GitHub_Trending/qmd1/qmd

当你同时维护个人笔记、工作文档、项目 wiki 等不同来源的内容时，把它们混在同一个 qmd 索引里会让每次搜索都要靠-c限定集合。qmd 的--index <name>参数提供了更彻底的隔离方式：每个命名索引拥有自己独立的配置文件和 SQLite 数据库，相当于在本机维护多套互不干扰的知识库索引，通过一条前缀命令即可切换。本文演示如何用--index创建并切换到一套独立的work索引，完成建库、索引、嵌入、搜索和验证。

先理解命名索引的文件布局

qmd 的集合配置、上下文、模型覆盖统一存放在 YAML 配置文件里，索引数据存放在 SQLite 文件中。默认索引和命名索引的落盘规则是：

也就是说qmd --index work …会读取/写入work.yml，其集合、context、models 与默认索引完全隔离；不带--index的命令则继续操作默认索引。配置目录会遵循XDG_CONFIG_HOME（此时为$XDG_CONFIG_HOME/qmd/index.yml）以及QMD_CONFIG_DIR；缓存目录同样受XDG_CACHE_HOME影响。一个完整的带注释的起始模板可参考仓库中的 example-index.yml。

前提条件

• 已通过npm install -g @tobilu/qmd（或bun install -g @tobilu/qmd）安装 qmd，也可用npx @tobilu/qmd .../bunx @tobilu/qmd ...直接运行。
• 有一套你想独立检索的目录（下文用~/work/docs作为示例）。
• 默认索引（index.yml/index.sqlite）是自动创建的，无需额外初始化；命名索引第一次被--index work命令读写时也会自动落盘对应的work.yml和work.sqlite。

为 work 索引添加集合并灌入数据

所有集合管理命令都会作用于当前选定的索引。下面每条命令都带上--index work，把~/work/docs挂进work索引：

# 1. 把目录添加为 work 索引下的集合 qmd --index work collection add ~/work/docs --name work-docs # 2. 添加上下文描述（搜索结果会随匹配的文档一并返回） qmd --index work context add qmd://work-docs "Work documentation" # 3. 重新索引集合 qmd --index work update # 4. 生成向量嵌入（语义搜索 vsearch / 混合搜索 query 依赖它） qmd --index work embed

注意第 3 步：直接编辑work.yml会改变 qmd 使用的目录和模型，但不会自动重建索引。文档明确说明，修改path、pattern、ignore后需要运行qmd update；修改models.embed后需要重新运行qmd embed。所以"改完配置 → update → embed"是保持数据一致的固定顺序。

如果某个集合配置了update钩子（例如git pull --ff-only），qmd update会先在集合自己的目录下执行该钩子再重建索引；钩子非零退出会中止整次运行，后面的集合不再重建。

在两套索引之间切换搜索

--index放在qmd和子命令之间，对search、vsearch、query、get、status等子命令生效：

# 默认索引（~/.config/qmd/index.yml + ~/.cache/qmd/index.sqlite） qmd search "quarterly reports" # work 索引（~/.config/qmd/work.yml + ~/.cache/qmd/work.sqlite） qmd --index work search "quarterly reports"

README 给出的官方示例正是这种用法：qmd --index work search "quarterly reports"用于"为不同知识库使用独立索引"。同一套搜索选项在两索引下均可用：-n <num>控制结果数（默认 5），-c <collection>按集合名过滤，--format json|csv|md|xml|files控制输出格式；query还支持--filter <json>元数据过滤、--explain输出打分细节。

结果路径形如work-docs/guide.md:42 #a1b2c3，其中#a1b2c3是 docid，可用同一索引取回全文：

qmd --index work get "#a1b2c3"

验证切换是否生效

逐条核对以下检查点，确认命令确实落在了work索引上：

# 查看索引状态：集合、上下文、文档总数（输出末尾会给出 SQLite 索引的存放位置） qmd --index work status # 查看 work 索引已配置的集合 qmd --index work collection list # 用文档诊断安装与配置（runtime、sqlite-vec、嵌入指纹、GPU 探测） qmd --index work doctor

判断依据：

• status/collection list列出的集合应该是你在work索引下添加的（如work-docs），而默认索引里添加的其他集合不会出现；反过来，不带--index的qmd collection list看到的仍只是默认索引的集合。两边的集合名不一致，正说明配置是隔离的。
• 对同一个查询词分别在两套索引下执行qmd search与qmd --index work search，默认索引查不到work索引里的文档，结果应体现各自索引的内容范围。
• 若doctor报告index.yml解析失败或无集合，先修复 YAML 再重跑qmd doctor。

边界与替代路径

• 显式--index优先于项目本地索引：qmd 还支持qmd init在项目目录创建本地索引（.qmd/index.yml+ 项目内index.sqlite），在树内运行时会自动覆盖全局配置/缓存路径；但如果你显式传了--index <name>，会以该命名索引为准。此外项目本地.qmd/index.yml中的update钩子、指向项目外的集合路径、自定义模型 URI 默认不被信任，需要qmd trust审批（CI 可设QMD_TRUST_LOCAL_CONFIG=1跳过），这与--index本身无关，但混用两种索引方式时要留意。
• MCP 服务同样支持按索引切换：qmd mcp --index <name>会让前台和守护 HTTP 服务都使用选定索引；qmd --index <name> mcp --http --daemon的 PID/日志文件也按索引名隔离，避免多个索引的守护进程互相覆盖。
• 每套索引的嵌入要单独生成：embed只作用于当前选定的索引。新命名索引建库后如果跳过qmd --index work embed，vsearch和带向量通路的query就没有可用数据，而qmd status也会提示有待嵌入的文档。

完成上述步骤后，你就拥有两套（或更多）完全独立的本地索引，日常用qmd …操作默认知识库，用qmd --index work …操作工作知识库，互不串扰。

【免费下载链接】qmdmini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local项目地址: https://gitcode.com/GitHub_Trending/qmd1/qmd