QMD 深度调研：本地知识库搜索引擎的产品与技术拆解
QMD 把 SQLite FTS5、sqlite-vec、LLM 重排和 AST-aware chunking 组合成一条本地混合检索链路，适合知识库与 Agent 工作流。
QMD 深度调研：本地知识库搜索引擎的产品与技术拆解
项目概览
QMD（Query Markup Documents）是一个面向 Markdown 文档、会议记录、知识库和“agentic flows”的本地搜索引擎。它的定位不是“再做一个全文检索工具”，而是把 BM25 全文检索、向量语义检索和 LLM 重排 组合成一条完整的本地检索链路，让个人知识库和文档库可以直接被 AI 助手调用。
从产品角度看，它的生态位很清晰：位于 本地知识管理 / 私有 RAG / Agent 检索层 这个交叉区域。它既能当 CLI 工具，也能当 SDK、MCP server，甚至可以嵌到 Claude Code / Claude Desktop 这样的工作流里。
从热度和维护活跃度看，QMD 不是一个“实验性脚本仓库”，而是一个增长很快的成熟项目：仓库约 2.0 万 star、1,250 fork、292 open issues，最新 release 为 v2.1.0（2026-04-05），最近一次 push 也在 2026-04-09。这说明它已经形成了比较强的社区关注和持续迭代节奏。
架构拆解
QMD 的架构可以理解成四层：数据入口层、索引层、检索层、接口层。
1）数据入口层
QMD 通过 collection 配置来定义索引范围，支持：
- 路径映射
- glob pattern
- ignore 规则
- collection context
includeByDefault- per-collection model 配置
这层的设计很像“知识库的路由系统”：不同 collection 可以有不同的上下文、不同的模型配置，说明它不是只面向单一目录，而是面向多个语义域。
2）索引层
底层存储是 SQLite，但不是单一用途的 SQLite，而是同时承载：
- 文档元数据
- 内容哈希
- FTS5 索引
- 向量索引（sqlite-vec）
- LLM 缓存
- collection / context 配置同步
这套设计的好处是：部署简单、数据一致性好、可迁移性强。缺点则是：它对本机环境和 native 扩展要求比较高，平台兼容性和安装体验会直接影响第一印象。
3）检索层
QMD 的检索不是“先 BM25 再向量”这么简单，而是一个比较完整的多阶段管线：
- 先做 BM25 probe，判断是否存在 strong signal
- 决定是否做 query expansion
- 跑 lexical search + vector search
- 做 RRF（Reciprocal Rank Fusion）融合
- 对候选文档做 chunking
- 在 chunk 上做 rerank
- 再把位置权重和 rerank 分数混合
4）接口层
QMD 同时提供：
- CLI：适合终端用户和脚本
- SDK：适合程序化调用
- MCP server：适合接入 Claude Desktop / Claude Code / 其他 agent
这点很重要，因为它让 QMD 不只是一个工具，而是一个 “可被代理系统调用的检索底座”。
核心机制
1）混合检索：BM25 + 向量 + 重排
QMD 的核心不是某一个模型，而是把三种信号统一起来：
- BM25 负责精确词匹配和高召回
- 向量检索 负责语义相似
- LLM rerank 负责最终排序判断
它用 RRF 先把不同信号融合，再把 top candidates 拉去 rerank，最后做 position-aware blending。这种做法很符合真实检索系统的工程经验：前面靠召回，后面靠精排。
2）强信号绕过 + intent 纠偏
在 hybridQuery() 里，QMD 会先做一次 BM25 probe：如果某个关键词命中非常强，它会跳过 query expansion，避免浪费 LLM 成本。
但如果用户提供了 intent，它又会主动关闭这个“强信号绕过”。这说明 QMD 很清楚一件事：用户真正想要的，不一定是字面匹配最强的那个结果。
这是一种很成熟的检索产品思维：不是盲目追求“更智能”，而是把“智能”和“效率”放在同一个决策框架里。
3）AST-aware chunking
QMD 2.1.0 的一个重要升级，是对代码文件引入了 tree-sitter 驱动的 AST chunking：
- 支持 TypeScript / JavaScript / Python / Go / Rust
- 代码按 function / class / import 边界切块
- Markdown 仍然按传统规则切块
- AST breakpoints 会和 regex breakpoints 合并
这意味着 QMD 不只是“能搜 markdown”，而是在向 代码知识库 + 技术文档库 进一步靠拢。对技术资料来说，按语义边界切块比按字数切块更接近人类阅读习惯，也更利于 rerank 和 snippet 提取。
4）上下文树
QMD 的 context 不是简单注释，而是可按路径组织的树状上下文。collection context + global context 的设计，让搜索结果可以携带更强的领域语义。
这对 agent 场景很关键：当检索对象从“文件”变成“可供模型使用的知识片段”时，context 不是附属品，而是信息质量的一部分。
优势与不足
商业 / 产品价值
优势：
- 定位清晰：本地知识库搜索 + agent 检索层
- 差异化强：all-local、MCP、SDK、hybrid search 同时具备
- 社区热度高：star / fork / issue 体量已经形成
- 生态位明显：贴近 personal knowledge base、local RAG、agent workflows
- 增长信号强：最新 release 很新，社区 PR 也活跃，功能持续上新
不足：
- 目标用户偏“重度用户”，不是开箱即用型 SaaS
- 本地模型、SQLite 扩展、平台差异会提高上手门槛
- 目前更偏技术圈和 AI 工具用户，普通知识管理用户未必愿意承担配置成本
技术研究价值
优势：
- 架构层次清楚，CLI / SDK / MCP 三条接口线分离良好
- SQLite + FTS5 + sqlite-vec 的组合非常实用，工程上克制
- RRF、rerank、chunk selection、intent steering 组成了一套完整检索策略
- AST-aware chunking 说明它在认真处理“代码文档化”问题
- 缓存和弱网/弱算力降级思路比较成熟
不足：
- 依赖本地 LLM / embedding / rerank 模型，部署体验受硬件影响明显
- 平台兼容和 native 依赖会让“可移植性”成为长期挑战
- 本地索引一旦复杂起来，调试和可观测性成本会上升
适合谁
QMD 特别适合下面几类人：
- 有大量 Markdown、会议纪要、技术文档的人
- 想把个人知识库接入 Agent 的开发者
- 需要本地、隐私友好检索方案的团队
- 想研究 hybrid retrieval / local RAG / MCP integration 的技术人员
- 能接受一定安装和模型配置成本的重度用户
不太适合：
- 只想“装上就用”的普通用户
- 不想碰本地模型和数据库配置的人
- 完全不需要 agent 集成、只追求简单云搜索的人
我的判断
QMD 不是一个“把搜索做出来就结束”的项目，而是在认真把 本地知识检索 做成一个可供 Agent 调用的基础设施。它最有价值的地方，不是单点功能，而是把 产品位、检索工程、模型调用、接口层 串成了一条闭环。
从商业/产品角度看，它踩中了一个越来越确定的需求：个人与团队正在把知识库从“存档工具”升级成“可检索、可推理、可被 Agent 使用的工作层”。从技术角度看，它是一个值得研究的混合检索范本，尤其适合观察：
- 本地 SQLite 如何承载复杂检索系统
- 如何在性能、质量和可维护性之间做平衡
- 如何把 AST chunking、RRF、rerank、intent steering 组合成一条可用链路
如果你关心的是“未来本地知识库该怎么跟 Agent 工作流结合”，QMD 是一个非常值得长期跟踪的项目。