qmd 工具概述与核心原理

1.1 qmd 是什么

qmd（Query Markup Documents）是由 tobi 开发的一款本地混合搜索引擎，专为 Markdown 文档设计。它可以在你的设备上本地运行，无需依赖云端服务，能够索引和搜索你的笔记、会议纪要、文档和知识库。

qmd 的核心理念是：将检索从 LLM 中移出，放到本地机器上执行。传统上，当我们需要让 AI Agent “记住” 成千上万的文档时，通常的做法是将大量文档内容塞进提示词（prompt）中，这导致 token 消耗巨大且成本高昂。qmd 通过提供高效的本地检索能力，只将最相关的文档片段提供给 LLM，从而显著降低 token 使用量。

qmd 在 GitHub 上获得了超过 6,900 个星标，是一个活跃的开源项目，使用 TypeScript 和 Python 开发。

1.2 核心技术架构

qmd 采用了混合检索架构，结合了三种搜索技术：

BM25 全文搜索（关键词搜索）

• 基于 SQLite FTS5 的 BM25 算法
• 适合精确的关键词匹配
• 搜索速度快，适合实时检索

向量语义搜索

• 使用本地运行的 embedding 模型（embeddinggemma-300M）
• 将文档切分为 800 token 的片段，15% 重叠
• 能够捕捉语义相似性，即使关键词不匹配也能找到相关内容

LLM 重新排序（Re-ranking）

• 使用 qwen3-reranker 模型对搜索结果进行精排
• 通过 yes/no 判断 + logprobs 置信度评分
• 进一步提升搜索结果的相关性

1.3 如何解决 Token 消耗问题

qmd 解决 token 消耗过大的核心策略是**检索增强生成（RAG）**的本地实现：

问题背景

传统的 Agent 工作流程存在严重的 token 浪费：

• 将数千个 Markdown 文件全部塞进上下文窗口
• LLM 需要处理大量无关信息
• 每次查询都重复传输相同的背景文档

qmd 的解决方案

1. 本地索引与检索

用户查询 → 本地索引检索 → 返回最相关的 N 个文档片段 → 仅将这些片段送入 LLM

2. 查询扩展（Query Expansion）

qmd 使用微调的 1.7B 参数模型自动生成查询变体：

• 原始查询（权重 ×2）
• 1-2 个语义变体查询
• 多查询并行检索，提高召回率

3. 智能融合策略（RRF Fusion）

使用 Reciprocal Rank Fusion 算法融合多种搜索结果：

• 原始查询结果获得额外权重（×2）
• 排名第一的文档获得 +0.05 bonus
• 排名 2-3 的文档获得 +0.02 bonus

4. 位置感知混合（Position-Aware Blending）

根据文档排名动态调整检索分数和重排分数的权重：

• 排名 1-3：75% 检索分数 + 25% 重排分数（保护精确匹配）
• 排名 4-10：60% 检索分数 + 40% 重排分数
• 排名 11+：40% 检索分数 + 60% 重排分数（更信任重排器）

Token 节省效果

根据实际使用案例，qmd 可以减少 95% 以上的 token 消耗。例如：

• 原本需要将 10,000 个文档（约 100 万 tokens）塞进上下文
• 使用 qmd 后，只需检索最相关的 5-10 个文档片段（约 5,000-10,000 tokens）
• LLM 只需处理高度相关的精简内容，响应质量反而提升

1.4 应用场景

qmd 特别适合以下场景：

个人知识管理

• 搜索个人笔记、日记、想法
• 快速找到过去的会议纪要
• 跨文档的知识关联发现

开发文档检索

• 技术文档和 API 文档搜索
• 代码库的 README 和文档检索
• 项目 Wiki 和知识库查询

AI Agent 增强

• 为 Agent 提供长期记忆能力
• 让 Agent 能够”回忆”之前的对话和文档
• 构建基于私有知识的问答系统

团队协作

• 团队文档中心的搜索引擎
• 项目文档和规范的快速查找
• 新人 onboarding 的知识库

参考资料

• QMD GitHub 仓库 - 官方仓库，包含完整文档
• QMD: Local hybrid search engine for Markdown - DevSphere 的使用体验分享