本地文档搜索神器 QMD 如何用 AI 读懂你的所有笔记

2 万星开源项目，完全本地运行，支持语义搜索和关键词搜索，让 AI 帮你找到任何文档

2026 年初，一款名为 QMD 的本地文档搜索工具在 GitHub 上获得了广泛关注。

这款由开发者 tobi 创建的工具，短短几个月内收获了超过 2.1 万颗星。它的目标很明确：让你用自然语言搜索任何本地文档，无需联网，完全隐私。

在这个知识爆炸的时代，我们每个人都积累了大量的笔记、文档、会议记录。但找到需要的信息却越来越难。QMD 的出现，让这件事变得简单而高效。

什么是 QMD

QMD 的全称是 Query Markup Documents，一个本地化的文档搜索引擎。它的核心理念很简单：你的文档应该留在你的设备上，搜索也应该在本地完成。

与云端服务不同，QMD 完全在本地运行。所有索引、嵌入向量、搜索结果都保存在你的电脑上，不会上传到任何服务器。这种设计既保护了隐私，又确保了搜索的灵活性。

QMD 支持 Markdown 笔记、会议记录、技术文档、知识库等各种文本内容。无论是个人笔记还是团队文档，都能轻松索引和搜索。

核心功能解析

QMD 的功能设计围绕着一个核心目标：让文档搜索变得智能、快速、准确。

混合搜索架构

QMD 采用三层搜索架构：BM25 全文搜索、向量语义搜索、LLM 重排序。这三种技术结合，既保证了关键词匹配的准确性，又实现了语义理解的能力。

BM25 负责快速找到包含关键词的文档，向量搜索负责理解查询的语义意图，LLM 重排序负责从候选结果中选出最相关的文档。这种设计让 QMD 在准确性和速度之间取得了平衡。

智能查询扩展

QMD 内置了一个微调的查询扩展模型。当你输入一个简短查询时，QMD 会自动生成多个变体，包括同义词、相关概念、假设性文档等。

比如你搜索认证流程，QMD 可能会扩展出用户登录、token 验证、OAuth 流程等多个相关查询。这种扩展大大提高了搜索的召回率，让你不会错过相关文档。

上下文管理系统

QMD 支持为文档集合和路径添加上下文描述。这些描述会作为元数据存储在索引中，帮助搜索理解文档的背景和用途。

比如你可以为 API 文档集合添加上下文REST API 参考文档，为会议记录添加上下文产品讨论和决策。搜索时，这些上下文信息会被用来提升相关性。

智能分块策略

QMD 采用智能分块算法，将文档切分成约 900 个 token 的片段。分块时会优先在标题、代码块、段落边界处切断，保持语义单元的完整性。

对于代码文件，QMD 还支持 AST 感知的分块策略。它会在函数、类、导入语句等边界处切断，确保代码片段的语义完整性。

典型使用场景

QMD 的适用场景非常广泛，从个人知识管理到团队协作都有用武之地。

个人笔记搜索

用户可以用 QMD 搜索自己多年积累的笔记。比如搜索那个关于 Rust 内存所有权的笔记，即使你不记得笔记的标题或位置，QMD 也能找到相关内容。

有用户分享说，他们用 QMD 索引了五年的个人笔记，包含超过 1 万份 Markdown 文件。搜索响应时间在 100 毫秒以内，体验非常流畅。

会议记录回顾

团队可以用 QMD 搜索历史会议记录。比如搜索去年 Q4 的预算规划讨论，QMD 会找到相关的会议纪要、决策记录、后续行动等。

这对于新加入团队的成员特别有用。他们可以快速了解项目的历史决策过程，避免重复讨论已经解决的问题。

技术文档检索

开发者可以用 QMD 搜索技术文档和代码注释。比如搜索认证最佳实践，QMD 会找到相关的 API 文档、代码示例、设计文档等。

有开发团队分享说，他们用 QMD 索引了整个项目的文档，新成员上手时间缩短了一半。遇到问题时，搜索比问同事更快。

知识库管理

企业可以用 QMD 构建本地知识库。员工文档、培训材料、流程规范都能被索引和搜索。新员工可以快速找到需要的信息，老员工也能快速回顾 forgotten 的知识。

技术架构特点

QMD 的成功离不开其精心设计的技术架构。

本地模型运行

QMD 使用 node-llama-cpp 在本地运行 GGUF 格式的模型。默认配置下，它会下载三个模型：嵌入模型约 300MB、重排序模型约 640MB、查询扩展模型约 1.1GB。

这些模型首次使用时会自动下载，之后缓存在本地。所有推理操作都在你的电脑上完成，不需要联网，也不需要 API 密钥。

SQLite 向量存储

QMD 使用 SQLite 作为主要存储引擎，配合 sqlite-vec 扩展支持向量搜索。这种设计既保证了数据的持久性，又实现了高效的向量检索。

索引存储在~/.cache/qmd/index.sqlite，包含文档元数据、全文索引、向量嵌入、上下文描述等。所有数据都是结构化的，便于查询和管理。

RRF 融合算法

QMD 采用 Reciprocal Rank Fusion(RRF) 算法融合多个搜索结果。原始查询的权重是扩展查询的两倍，排名第一的文档会获得额外加分。

这种设计确保了精确匹配不会被稀释。即使查询扩展产生了不相关的结果，原始查询的高分文档仍然会排在前面。

位置感知重排序

QMD 的重排序策略是位置感知的。排名靠前的文档更多依赖检索分数，排名靠后的文档更多依赖重排序分数。

这种设计平衡了检索和重排序的贡献。高置信度的检索结果不会被重排序破坏，低置信度的结果可以通过重排序提升。

与 AI 代理集成

QMD 的一个亮点是与 AI 代理的深度集成。

MCP 服务器支持

QMD 实现了 Model Context Protocol(MCP) 服务器，可以被 Claude Desktop、Cursor、VS Code 等 AI 工具连接。连接后，AI 代理可以直接搜索你的本地文档。

配置非常简单，只需在 AI 工具的配置文件中添加 MCP 服务器信息。之后，AI 就可以用自然语言调用 QMD 的搜索功能。

命令行工具

QMD 提供了丰富的命令行工具，支持搜索、获取文档、管理集合等操作。这些工具可以被脚本调用，实现自动化工作流。

比如你可以写一个脚本，每天自动搜索新增的文档，生成摘要报告。或者在 CI/CD 流程中，用 QMD 搜索相关的技术文档。

SDK 库支持

QMD 提供了 TypeScript/JavaScript SDK，可以被其他应用嵌入。这意味着你可以将 QMD 的搜索功能集成到自己的应用中，无需启动独立进程。

有开发者分享说，他们用 QMD SDK 构建了一个内部知识问答机器人，员工可以用自然语言提问，机器人会自动搜索文档并生成答案。

隐私与安全

在数据隐私日益受到重视的今天，QMD 的本地化设计显得尤为重要。

数据不出设备

QMD 的所有数据处理都在本地完成。原始文档、索引、搜索结果都不会离开你的设备。这与云端服务形成鲜明对比。

使用云端服务意味着你要将文档内容上传到第三方服务器，存在潜在的隐私风险。QMD 完全避免了这个问题。

透明的数据处理

QMD 是开源软件，所有代码都可以审查。用户可以清楚地知道数据是如何被处理的，没有任何黑箱操作。

这种透明度建立了用户信任。很多人选择 QMD 正是因为它的开源性质和可验证性。

灵活的数据管理

用户可以随时导出或删除索引数据。QMD 不会锁定你的数据，你可以自由决定如何处理这些信息。

这种灵活性让用户掌握主动权，而不是被工具所束缚。

部署与使用

QMD 提供多种使用方式，适应不同用户的需求。

全局安装

普通用户可以用 npm 或 bun 全局安装 QMD。安装后，qmd 命令可以在任何目录使用。

npminstall-g@tobilu/qmdqmdcollectionadd~/notes--namenotesqmdembedqmdquery认证流程

Docker 部署

专业用户可以用 Docker 部署 QMD。这种方式适合需要长期运行的场景，可以配置自动重启，确保服务稳定可用。

HTTP 服务器模式

QMD 的 MCP 服务器支持 HTTP 传输模式。启动后，多个 AI 客户端可以连接到同一个服务器，避免重复加载模型。

qmdmcp--http--port8181

社区生态

QMD 的快速发展离不开活跃的社区支持。

截至 2026 年 4 月，QMD 已有 70 名贡献者，提交了数百次代码更改。社区用户积极分享使用案例、报告问题、贡献代码。

GitHub 仓库上有超过 1300 个 Fork，说明很多开发者在基于 QMD 进行二次开发。社区还维护了详细的文档和常见问题解答。

这种自下而上的社区驱动模式，让 QMD 的功能迭代速度远超传统商业软件。用户的需求可以快速得到响应，新的使用场景不断被发掘。

写在最后

QMD 的故事告诉我们，开源社区依然有能力创造出解决实际问题的工具。在云端服务日益普及的今天，本地化方案依然有其独特价值。

对于普通用户来说，QMD 提供了一个掌控自己数据的机会。文档内容不会离开设备，使用限制由自己决定，成本完全可控。

在这个知识管理日益重要的时代，能够真正掌控自己知识的工具不多。QMD 给了你一个选择，成为自己知识的主人，而不是被服务所束缚。

或许，下一个让你摆脱云端依赖的工具，就在 GitHub 的某个仓库里等待着被发现。这，就是开源的魅力所在。

那些被遗忘的笔记、被忽略的文档、被错过灵感，都可能在 QMD 的搜索中重新浮现。这，可能就是它最大的价值所在。