如果你像我一样,每天都在 Markdown 笔记、会议纪要、项目文档之间跳来跳去,却总是找不到那条关键信息,那么 QMD 可能会成为你的新宠。

QMD(Query Markup Documents)是一个完全本地运行的混合搜索引擎,专门为 Markdown 知识库设计。它把 BM25 关键词检索、向量语义搜索和 LLM 重排序结合在一起,所有模型和索引都在你自己的机器上完成,数据不会离开本地。

开发者使用本地知识库搜索工作场景

本地优先的知识库检索工作流

PART 1:快速安装

QMD 支持 Node.js 和 Bun,推荐使用全局安装:

# 使用 npm
npm install -g @tobilu/qmd

# 或者使用 Bun(更快)
bun install -g @tobilu/qmd

安装完成后直接运行 qmd 就能看到帮助。首次使用语义搜索或重排序时,它会自动下载约 2GB 的 GGUF 模型到 ~/.cache/qmd/models/,之后就完全离线了。

提示:如果你只是想快速体验关键词搜索,可以先跳过 qmd embed,直接用 qmd search。

PART 2:建立你的第一个知识库

QMD 用「Collection」来组织文档。把笔记、会议记录、文档目录分别加入不同的 collection:

qmd collection add ~/notes --name notes
qmd collection add ~/Documents/meetings --name meetings
qmd collection add ~/work/docs --name docs

更强大的是 Context 功能——给每个 collection 添加描述,这些描述会在搜索结果中返回,帮助你(或 AI Agent)快速判断上下文:

qmd context add qmd://notes "个人想法、灵感和日常记录"
qmd context add qmd://meetings "会议纪要与决策记录"
qmd context add qmd://docs "工作文档与技术资料"

QMD 混合检索架构示意图

QMD 的混合检索流程:关键词 + 向量 + 重排序

PART 3:三种搜索模式实战

先生成向量嵌入(只需要执行一次,后续增量更新即可):

qmd embed

然后根据需求选择搜索方式:

  • 关键词搜索(最快):qmd search "项目时间线"
  • 语义搜索:qmd vsearch "如何部署到生产环境"
  • 混合搜索 + 重排序(质量最高):qmd query "季度规划流程"

QMD 终端搜索结果示例

终端中的混合搜索结果,带分数与片段预览

常用参数:

# 限制结果数量和最低分数
qmd query -n 10 --min-score 0.4 "API 设计模式"

# 只在某个 collection 中搜索
qmd search "认证流程" -c notes

# 输出 JSON,方便脚本或 Agent 处理
qmd query --json "错误处理最佳实践"

# 直接获取完整文档
qmd get "#abc123"
qmd get "meetings/2024-11-15.md" --full

PART 4:与 AI Agent 无缝集成

QMD 原生支持 MCP(Model Context Protocol),可以让 Claude Code、Cursor 等工具直接调用你的本地知识库。

最简单的启动方式:

qmd mcp

在 Claude Desktop 的配置文件中添加:

{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}

之后你就可以直接对 AI 说:「帮我查一下上周关于部署方案的会议记录」,它会自动调用 QMD 检索并返回相关内容。

常见坑:
1. 首次 qmd embed 会下载模型,确保磁盘空间充足(建议预留 3GB)。
2. 如果搜索结果不理想,先检查 collection 是否正确添加,并用 qmd status 查看索引状态。
3. Windows 用户如果遇到路径问题,建议使用 Bun 安装或检查 Node 版本(推荐 20+)。

总结

QMD 把复杂的混合检索技术封装成了简单的 CLI 命令,特别适合个人知识管理、团队文档检索,以及给 AI Agent 提供可靠的本地上下文。它开源、本地优先、支持 MCP,是目前我见过最实用的 Markdown 搜索工具之一。

项目地址:github.com/tobi/qmd

上一篇: 当前是最后一篇了

相关推荐

随机推荐

  1. Qoo10趣天日本广告投标助手
  2. 西西趣天采集插件2.0升级版
  3. 西西电商图片下载助手
  4. 西西趣天韩国批量上货助手最新版
  5. 西西趣天日本批量上货助手最新版
  6. 本地知识库秒级检索:用 QMD 打造个人 Markdown 搜索引擎
  7. 终端效率翻倍:用 Yazi 秒级管理文件
  8. 把 AI 干活的成本砍到 1/20:混元 Hy4 flash
  9. Handy:按一下快捷键,说话就变成文字的免费离线语音输入
  10. 一个把 Photoshop 从零重写了一遍,一个把电视里的广告拆干净
  11. 录音 60 分钟,转写只要一次
  12. Filee:不用打开软件,拖一下就转好的免费格式转换器
  13. HeidiSQL_12.12绿色版
  14. WPS office 10.1.0.7311精简版(无联网功能)无广告超级好用
  15. dupeGuru – 电脑重复文件查找工具,支持跨平台使用!