qmd 是一款全本地运行的智能搜索工具，支持关键词、语义与 LLM 重排序混合检索，专为个人知识库和 AI 代理工作流设计，隐私安全、高效精准。
一款名为 qmd 的开源工具正在悄悄改变技术人管理个人知识的方式。它不依赖任何云端服务，完全在本地运行，能将你散落在各处的笔记、文档、会议记录一键变成可高效检索的知识库。无论是关键词匹配还是语义理解，甚至结合大模型重排序，qmd 都能搞定，而且全部离线完成。
对于注重隐私、追求效率、又不想被 SaaS 工具绑架的开发者和知识工作者来说，这几乎就是梦中情“搜”。
作者是谁？极简主义下的硬核工程
qmd 由开发者 tobi 创建，这位作者以打造轻量但功能完整的命令行工具著称。他没有堆砌花哨界面，而是聚焦于底层搜索质量与系统集成能力。qmd 的设计哲学非常清晰：用最精简的架构实现最先进的本地检索体验。项目采用 Bun 作为运行时，基于 SQLite 构建索引，通过 node-llama-cpp 调用 GGUF 格式的量化模型，在普通笔记本上就能流畅运行。
这种“小而美+强技术底座”的组合，正是它能在 GitHub 上迅速收获上千星的关键。
不只是全文搜索，而是三层混合智能检索
很多人以为本地搜索就是 Ctrl+F 或 grep，但 qmd 完全跳出了这个框架。它提供三种搜索模式，分别对应不同场景的需求。第一种是传统的关键词全文搜索，基于 BM25 算法，速度快、准确率高，适合精确查找术语或代码片段。第二种是语义向量搜索，即使你问“怎么部署服务”，它也能找到写有“上线流程”或“发布指南”的文档，因为背后的嵌入模型理解了语义相似性。第三种也是最强的——混合查询模式，它会先用小型语言模型扩展原始问题，生成多个变体，然后并行执行全文和向量搜索，再用重排序模型对结果打分，最后通过一套精细的位置感知融合策略输出最终列表。
这套流程堪比企业级搜索系统，却全部跑在你自己的电脑上。
模型全部本地化，首次使用自动下载
qmd 默认使用三款来自 HuggingFace 的 GGUF 量化模型，全部自动缓存在用户目录下，无需手动配置。其中一款约 300 兆的嵌入模型负责生成文本向量，两款约 640 兆的小型 Qwen3 模型分别用于查询扩展和结果重排序。这些模型虽小，但在本地任务中表现惊人。更重要的是，所有推理过程都不联网，既保护隐私，又避免 API 调用费用和延迟。
对于经常处理敏感项目文档的工程师、咨询师或研究者来说，这种“数据不出门”的设计极具吸引力。
命令行即生产力，专为智能代理工作流打造
qmd 的接口设计明显考虑到了未来的人机协作场景。它不仅支持人类直接使用，还内置了 MCP（模型上下文协议）服务器，可无缝对接 Claude Desktop、Claude Code 等智能代理环境。这意味着你可以让 AI 助手直接调用 qmd 来查找你的私人知识，而无需复制粘贴或手动翻找。此外，qmd 的输出格式高度结构化，支持 JSON、CSV、纯文本、Markdown 等多种形式，配合 --files 和 --min-score 参数，能精准筛选出相关度高于阈值的文件列表，非常适合喂给下游 LLM 作为上下文。
这种“为代理而生”的理念，让它远超普通笔记搜索工具。
知识组织靠“集合”和“上下文”双引擎
qmd 并不要求你把所有文件塞进一个文件夹。它引入了“集合”（collection）的概念，允许你将不同来源的内容分别索引，比如 ~/notes、~/work/docs、~/meetings 各成一体。更聪明的是“上下文”（context）功能——你可以为每个集合甚至子路径添加描述性文本，例如给“会议记录”集合标注“包含所有项目周会和客户沟通纪要”。这些上下文信息不会参与索引，但会在搜索结果中显示，并可能被重排序模型参考，从而提升相关性判断的准确性。
这种元数据驱动的设计，让知识库更有层次感，也更贴近人类的记忆逻辑。
文档处理细节拉满，兼顾速度与精度
qmd 对 Markdown 文件的解析非常细致。它会自动提取标题（优先使用一级标题，否则用文件名），为每篇文档生成唯一的六位哈希 ID（docid），方便后续引用。为了平衡长文档的检索效果，它将内容按 800 个词元分块，并保留 15% 的重叠区域，确保关键信息不会因切分而丢失。每个块都会单独生成向量并存入 SQLite 的 vec 扩展表中。全文索引则交给 FTS5 引擎处理，支持高效的 BM25 排序。
整个索引数据库就存放在 ~/.cache/qmd/index.sqlite，干净整洁，易于备份或迁移。
搜索结果不只是列表，而是可操作的知识单元
当你执行一次 qmd query，返回的不仅是文件路径，还包括标题、上下文描述、相关度分数（0 到 1 之间）、高亮片段，以及 docid。颜色编码让高相关结果一目了然：绿色代表高度相关（>70%），黄色为中等相关（40%-70%），其余则灰显。你可以直接用 docid 快速获取完整文档，比如 qmd get "#a1b2c3"。如果需要批量处理，multi-get 支持通配符、逗号分隔列表甚至混合 docid，还能限制单文件大小或行数，防止大文件拖慢代理流程。
这种细粒度控制，让 qmd 成为自动化脚本的理想组件。
安装与初始化只需几分钟，跨平台友好
在 macOS 上，只需先通过 Homebrew 安装支持扩展的 SQLite（brew install sqlite），
然后用 Bun 全局安装 qmd：
bun install -g https://github.com/tobi/qmd。
Linux 用户只要系统有兼容的 SQLite 和 Bun 环境即可。Windows 用户可通过 WSL 使用。初始化过程极其简单：添加几个文件夹作为集合，运行 qmd embed 生成向量，马上就能开始搜索。
整个流程无需图形界面，命令行几行搞定，符合开发者“越快越好”的习惯。
为什么混合搜索要这么复杂？答案藏在细节里
有人可能会问：
既然有向量搜索，为什么还要 BM25？
既然有重排序，为什么还要 RRF 融合？
qmd 的设计文档给出了明确解释：单一方法各有盲区。
纯向量搜索可能漏掉关键词完全匹配但语义稍偏的文档；
纯关键词搜索则无法处理同义替换。
而如果完全依赖重排序模型，又可能把高置信度的精确匹配结果排到后面。
因此 qmd 采用“RRF 融合 + 位置感知加权”策略：前 3 名结果以原始检索为主，保留精确命中；11 名之后则更信任重排序模型的判断。同时，原始查询被赋予双倍权重，且排名第一的文档额外加分，确保核心结果不被稀释。
这套机制看似复杂，实则是多年搜索工程经验的结晶。
不止是工具，更是人机协作的基础设施
qmd 的真正野心不在“替代 Everything”或“取代 Obsidian 搜索”，而在于成为智能代理时代的记忆中枢。当你的 AI 助手需要回忆上周会议提到的 API 设计原则，它不再需要你手动粘贴，而是直接调用 qmd_query 获取结构化结果。
这种“AI 主动查你本地知识”的能力，才是下一代工作流的核心。qmd 提供的 MCP 协议支持、JSON 输出、文件过滤等特性，都是为此铺路。
它不炫技，不搞 UI，只专注一件事：让机器能像你一样“记得住、找得快、说得准”。
实战示例：从零搭建个人知识搜索引擎
假设你有一个 ~/my-notes 目录，里面全是 Markdown 笔记。
首先添加集合：qmd collection add ~/my-notes --name notes。
接着添加上下文帮助理解：qmd context add qmd://notes "我的技术笔记、读书摘要和项目复盘"。
然后生成嵌入：qmd embed。
完成后，就可以用 qmd search "React 性能优化" 快速定位关键词，或用 qmd vsearch "如何让前端更快" 获取语义相关结果。
若想获得最高质量答案，直接 qmd query "前端性能瓶颈分析"。结果中会显示文件路径、标题、分数和高亮段落。若需喂给 AI，加上 --json 参数即可输出标准格式。
开源免费，MIT 协议，社区活跃
qmd 采用 MIT 开源协议，意味着你可以自由使用、修改甚至商用。项目代码结构清晰，核心逻辑集中在 src/ 目录，模型配置、索引流程、搜索管道均有详细注释。GitHub 仓库持续更新，issue 区响应及时，已有不少用户贡献了使用脚本和集成方案。对于喜欢掌控工具底层逻辑的技术人来说，这比闭源 SaaS 产品可靠得多。