文章目录
- QMD：本地运行的智能文档搜索引擎
- 混合搜索是它的核心能力
- 接入方式
- 安装和使用
- 本地模型
- 适合什么场景
- 其他细节
QMD：本地运行的智能文档搜索引擎
最近 GitHub 上出现了一个挺有意思的项目，叫 QMD，Star 数已经到了 2.7 万。它做的事情很明确，把你的 Markdown 笔记、会议记录、技术文档全部索引起来，然后用关键词或者自然语言去搜。
混合搜索是它的核心能力
QMD 最大的特点不是单纯的全文检索，而是把三种搜索方式揉到了一起：BM25 全文检索、向量语义搜索、LLM 重排序。这三样东西全部跑在本地，通过 node-llama-cpp 加载 GGUF 模型实现，不需要联网。
搜索流程大概是这样的：你输入一个查询，QMD 先用微调过的 1.7B 参数模型自动扩展查询词，然后同时跑关键词搜索和语义搜索，再用 RRF（Reciprocal Rank Fusion）把结果合并，最后交给 reranker 模型做精排。整个过程对用户来说就是一条命令的事。
实际使用的时候有三种模式可选。search是纯关键词搜索，速度最快。vsearch是向量语义搜索，适合你记不清原文措辞的场景。query是混合搜索加重排序，效果最好，但需要加载模型，第一次运行会慢一些。
接入方式
除了命令行直接用，QMD 还提供了 MCP Server，可以接入 Claude Desktop 或者 Claude Code。它暴露了四个工具：query（混合搜索）、get（获取单个文档）、multi_get（批量获取）、status（查看索引状态）。
如果你是做开发的，也可以把 QMD 当成 Node.js 库来用。npm 装完之后，几行代码就能创建索引、执行搜索、获取文档。SDK 的设计比较干净，支持内联配置、YAML 配置文件，也可以直接打开已有的数据库。
安装和使用
装起来很简单，Node 或者 Bun 环境下全局安装就行：
npm install -g @tobilu/qmd装好之后，先建几个 collection，把你的文档目录加进去：
qmd collection add ~/notes --name notes qmd collection add ~/work/docs --name docs然后跑一次qmd embed生成向量索引。之后就可以搜索了：
qmd search "project timeline" qmd query "quarterly planning process"query命令会自动扩展查询词，同时跑关键词和语义搜索，最后用 reranker 精排。如果你只想快速找关键词匹配，用search就够了。
本地模型
QMD 用到三个 GGUF 模型，首次使用时自动从 HuggingFace 下载。embedding 模型大概 300MB，reranker 大概 640MB，查询扩展模型大概 1.1GB。模型下载后缓存在~/.cache/qmd/models/目录下。
默认的 embedding 模型是 embeddinggemma-300M，英文效果不错。如果你主要搜中文、日文或者韩文内容，可以换成 Qwen3-Embedding-0.6B，支持 119 种语言，MTEB 排名靠前。换模型之后需要重新跑一次qmd embed -f。
适合什么场景
QMD 比较适合两种人。一种是笔记很多、经常需要翻找历史记录的。把所有 Markdown 文件加进 collection，以后搜东西就不用翻文件夹了。另一种是做 AI Agent 开发的。QMD 的--json输出格式可以直接喂给 LLM，--files模式可以批量导出匹配的文件路径。
搜索结果会显示文件路径、标题、上下文描述和相关度分数。路径在终端里是可以点击的超链接，支持 VS Code、Cursor、Zed 等编辑器。
其他细节
QMD 支持 AST 感知的代码分块，对 TypeScript、JavaScript、Python、Go、Rust 这几种语言，会按函数、类、import 边界来切分，而不是按固定字符数切。这对搜代码场景有帮助。
它还支持给 collection 设置上下文描述，搜到子文档的时候会把上下文一起返回，帮 LLM 做更好的判断。另外 collection 可以配置update命令，每次qmd update之前自动执行，比如git pull --rebase，保持文档和远程仓库同步。
项目是 MIT 协议，代码全在 GitHub 上。如果你手头有大量 Markdown 文档需要管理，或者在做 AI 项目需要本地知识库，可以试试。
协议，代码全在 GitHub 上。如果你手头有大量 Markdown 文档需要管理，或者在做 AI 项目需要本地知识库，可以试试。
