企业官网建设流程全解析

快速搭建本地文档搜索引擎：qmd 离线检索 5 分钟上手指南

【免费下载链接】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

你的会议记录、项目文档散在十几个文件夹，想找"上周提到的部署方案"翻不到？qmd 是跑在本地的文档搜索引擎，索引 markdown 后，用混合检索加 LLM 重排序给出答案，适合管个人知识库的人。

🚀 为什么值得花5分钟装它

先说清楚为什么值得花这 5 分钟：你的数据一步都不出门。

• 全本地运行：索引就是一个 SQLite 文件，三个 GGUF 小模型（合计约 2GB）经 node-llama-cpp 本地推理，无云 API、无需 GPU
• 混合检索：BM25 关键词、向量语义、LLM 重排序三条路并行，精确词和相近意思都接得住
• 对 agent 友好：自带 MCP server 与 --json/--files 输出，能直接喂进 LLM 工作流
• 维护轻：没有常驻服务，改完文件一条 qmd update 重建索引

环境要求很轻：Linux 或 macOS、Node.js ≥ 22（或 Bun ≥ 1.0）、git 三样。macOS 用户若向量检索报错，用 Homebrew 补一个 sqlite 即可。

⚡ 从零到跑通：5分钟搭好你的本地索引

这一步的目标：装好源码、写最小配置，让第一条搜索命令出结果。

先克隆仓库并装依赖、构建。qmd 是 TypeScript 写的，构建后才会生成 dist/ 下的可执行入口：

git clone https://gitcode.com/GitHub_Trending/qmd1/qmd && cd qmd bun install # 没有 bun 就用 npm install bun run build # 编译源码到 dist/

构建产物由仓库根目录的 bin/qmd 启动器调用，它会自己挑对运行时。接下来写配置：qmd 只认一个 YAML 文件（默认 ~/.config/qmd/index.yml），建好目录后把这份最小配置存进去：

# ~/.config/qmd/index.yml collections: notes: # 集合名，后面用它限定搜索范围 path: ~/Documents/notes # 要索引的目录 pattern: "**/*.md" # 只收 markdown 文件 context: "/": "个人笔记和会议记录" # 集合描述，随结果一起返回

配置就位，让 qmd 扫文件、建索引、算向量。update 建全文索引，embed 跑嵌入模型，首次会自动下载约 2GB 模型，耐心等它跑完：

./bin/qmd update # 扫描 collections，建 SQLite 索引 ./bin/qmd embed # 生成向量；首次运行下载模型

最后跑通验证，发一条混合检索——质量最高的一档：

./bin/qmd query "部署方案"

看到带路径、行号和相关度百分比的结果，本地搜索链路就通了；再跑一次 ./bin/qmd doctor 可以确认各组件状态。

🔍 它底层在做什么：混合检索到底怎么排

这一节讲清"结果为什么靠谱"。一句话总述：小模型先把查询扩写成变体，关键词与向量双路粗筛，重排序模型收尾。

1. 查询扩展：本地 1.7B 微调 Qwen3 把查询改写成关键词式（喂 BM25）和语义式/HyDE 式（喂向量检索）变体，原查询权重 ×2
2. 并行搜索：SQLite FTS5 的 BM25 抓精确词，sqlite-vec 向量检索抓意思相近的段落
3. RRF 融合：Reciprocal Rank Fusion 按名次合并各结果列表（k=60），留前 30 候选
4. LLM 重排：0.6B 的 qwen3-reranker 逐一打分，再按位置混合——前 3 名 75% 信检索分，11 名后 60% 信重排分

仓库没有现成架构图，但 README 开头的 mermaid 流程图完整画了这条链路。简单说：先双路粗筛，再用 LLM 把"字面像"和"意思像"分开。想看融合细节，src/ 里的 store.ts 与 llm.ts 是核心，配置字段全貌参考 example-index.yml。

🎯 三个真实场景，试试这些命令

命令通了，换三个真实用法试试手。

场景一：一两百篇 markdown 里找一句话，不想抠关键词。直接自然语言问：

./bin/qmd query "分布式事务里的超时怎么处理"

输出按相关度排好，Top 1 通常就是目标段落；--min-score 0.3 可过滤弱相关。

场景二：多个集合混在一个索引里，只想搜某个目录。-c 指定集合名即可：

./bin/qmd search "API 设计" -c notes -n 10

只搜 notes 集合，-n 控制条数；这条走纯 BM25，快，适合你记得原词的情况。

场景三：结果不对，想看分数怎么来的。加 --explain：

./bin/qmd query "季度汇报" --json --explain

每条结果附 BM25 分、向量分和 RRF 融合明细；嫌慢可加 --no-rerank 跳过重排。

🛠 卡住了？看这里

安装和首次运行最常卡在这几处，对号入座：

• 第一次搜索慢得吓人：正在自动下载约 2GB 的三个 GGUF 模型到 ~/.cache/qmd/models/，第二次起走缓存
• Node 版本报错：engines 要求 Node ≥ 22，旧版本会在 better-sqlite3 等原生模块上失败，升级 Node 或换 bun
• 改了配置没生效：编辑 index.yml 不会重建索引，跑 qmd update；换嵌入模型后要 qmd embed -f
• 环境有疑点：qmd doctor 逐项检查运行时、sqlite-vec、模型指纹与 GPU，按输出修

延伸两处：finetune/ 是查询扩展模型的微调数据与训练脚本，好奇它怎么来的看这里；test/eval-docs/ 是一小份测试语料，想复现官方 benchmark 可以直接用。

别停在读了——挑一个放着 markdown 的桌面文件夹加进配置，跑第一条搜索。

【免费下载链接】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