QMD 项目概览
项目背景和设计目标
QMD (Query Markup Documents) 是一个本地混合搜索引擎，专为 Markdown 文档设计。它解决了个人知识管理中的一个核心问题：如何在大量笔记、文档和会议记录中快速找到相关信息。
设计目标
- 完全本地运行 - 所有数据和模型都在本地，保护隐私
- 混合搜索 - 结合关键词搜索（BM25）和语义搜索（向量）的优势
- LLM 增强 - 使用本地 LLM 进行查询扩展和结果重排序
- Agent 友好 - 提供结构化输出（JSON/XML/CSV），便于 AI Agent 集成
- MCP 支持 - 原生支持 Model Context Protocol，与 Claude 等工具深度集成
核心功能和技术特点
核心功能
| 功能 | 描述 |
|---|
| Collection 管理 | 将不同目录组织为命名集合，支持 glob 模式匹配 |
| Context 系统 | 为集合或路径添加描述性上下文，帮助搜索理解内容 |
| 三种搜索模式 | search (BM25), vsearch (向量), query (混合+重排序) |
| 智能分块 | 900 tokens/chunk，15% 重叠，优先在 Markdown 标题处切割 |
| 虚拟路径 | qmd://collection/path 格式，统一访问所有文档 |
| MCP 服务器 | 提供 HTTP 和 stdio 两种传输方式 |
技术特点
- BM25 + 向量融合：使用 Reciprocal Rank Fusion (RRF) 算法融合两种搜索结果
- 查询扩展：使用 fine-tuned Qwen3 模型生成查询变体
- 位置感知混合：Top 1-3 结果 75% 依赖 RRF，Top 11+ 60% 依赖重排序器
- 智能缓存：LLM 响应缓存，避免重复计算
架构图
┌─────────────────────────────────────────────────────────────────────────────┐
│ QMD Hybrid Search Pipeline │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ User Query │
└────────┬────────┘
│
┌──────────────┴──────────────┐
▼ ▼
┌────────────────┐ ┌────────────────┐
│ Query Expansion│ │ Original Query│
│ (fine-tuned) │ │ (×2 weight) │
└───────┬────────┘ └───────┬────────┘
│ │
│ 2 alternative queries │
└──────────────┬──────────────┘
│
┌───────────────────────┼───────────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Original Query │ │ Expanded Query 1│ │ Expanded Query 2│
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
┌───────┴───────┐ ┌───────┴───────┐ ┌───────┴───────┐
▼ ▼ ▼ ▼ ▼ ▼
┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
│ BM25 │ │Vector │ │ BM25 │ │Vector │ │ BM25 │ │Vector │
│(FTS5) │ │Search │ │(FTS5) │ │Search │ │(FTS5) │ │Search │
└───┬───┘ └───┬───┘ └───┬───┘ └───┬───┘ └───┬───┘ └───┬───┘
│ │ │ │ │ │
└───────┬───────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└────────────────────────┼───────────────────────┘
│
▼
┌───────────────────────┐
│ RRF Fusion + Bonus │
│ Original query: ×2 │
│ Top-rank bonus: +0.05│
│ Top 30 Kept │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ LLM Re-ranking │
│ (qwen3-reranker) │
│ Yes/No + logprobs │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ Position-Aware Blend │
│ Top 1-3: 75% RRF │
│ Top 4-10: 60% RRF │
│ Top 11+: 40% RRF │
└───────────────────────┘
与同类项目的对比
| 特性 | QMD | Obsidian Search | ripgrep + fzf | Elasticsearch |
|---|
| 本地运行 | ✅ 完全本地 | ✅ 本地 | ✅ 本地 | ❌ 需要服务器 |
| 语义搜索 | ✅ 向量+重排序 | ❌ 仅关键词 | ❌ 仅关键词 | ⚠️ 需配置 |
| LLM 集成 | ✅ 内置 | ❌ 无 | ❌ 无 | ⚠️ 需外部 |
| MCP 支持 | ✅ 原生 | ❌ 无 | ❌ 无 | ❌ 无 |
| 隐私保护 | ✅ 数据不出境 | ✅ 本地 | ✅ 本地 | ⚠️ 依赖部署 |
| 设置复杂度 | 低 | 低 | 中 | 高 |
| 资源占用 | 中（需 GPU/CPU） | 低 | 低 | 高 |
独特优势
- Context 系统：通过
qmd context add 为集合添加描述，这是 QMD 的关键特性，让 LLM 能做出更好的上下文选择
- Query Document：v1.1.0 引入的多行查询格式，支持
lex:, vec:, hyde: 等子查询类型
- 智能分块：不是简单的固定长度切割，而是寻找 Markdown 结构的自然断点
- 位置感知融合：根据结果排名动态调整 RRF 和重排序器的权重
技术栈
- 运行时: Bun >= 1.0.0 或 Node.js >= 22
- 数据库: SQLite + FTS5 + sqlite-vec
- LLM 推理: node-llama-cpp (GGUF 模型)
- 模型:
- Embedding: embeddinggemma-300M-Q8_0 (~300MB)
- Reranking: qwen3-reranker-0.6b-q8_0 (~640MB)
- Generation: qmd-query-expansion-1.7B-q4_k_m (~1.1GB)
相关文档