qmd 核心能力与验证

技术研究人工智能 LLM

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

2.1 功能特性详解

搜索模式

qmd 提供三种搜索模式，适用于不同场景：

命令	模式	适用场景	速度	准确性
`qmd search`	BM25 全文搜索	关键词精确匹配	极快	中等
`qmd vsearch`	向量语义搜索	语义相似度查询	快	高
`qmd query`	混合搜索 + 重排	复杂查询，最佳质量	中等	最高

集合（Collection）管理

qmd 使用集合来组织文档：

# 创建集合
qmd collection add ~/notes --name notes
qmd collection add ~/Documents/meetings --name meetings

# 支持自定义文件匹配模式
qmd collection add ~/work/docs --name docs --mask "**/*.md"

# 列出所有集合
qmd collection list

# 删除和重命名集合
qmd collection remove myproject
qmd collection rename old-name new-name

上下文（Context）管理

上下文帮助搜索理解你的内容：

# 为集合添加描述性上下文
qmd context add qmd://notes "个人笔记和想法"
qmd context add qmd://docs "工作文档和API说明"

# 添加全局上下文（适用于所有集合）
qmd context add / "我的项目知识库"

# 查看所有上下文
qmd context list

文档检索

# 通过路径获取文档
qmd get "docs/api-reference.md"

# 通过 docid 获取（搜索结果显示 docid）
qmd get "#abc123"

# 获取特定行范围
qmd get notes/meeting.md:50 -l 100

# 批量获取文档（支持 glob 模式）
qmd multi-get "journals/2025-05*.md"
qmd multi-get "doc1.md, doc2.md, #abc123"

2.2 MCP 服务器支持

qmd 内置 MCP（Model Context Protocol）服务器，支持与 AI Agent 的深度集成：

暴露的工具

工具名	功能描述
`qmd_search`	BM25 关键词搜索（支持集合过滤）
`qmd_vsearch`	向量语义搜索（支持集合过滤）
`qmd_query`	混合搜索 + 重排（支持集合过滤）
`qmd_get`	通过路径或 docid 检索文档
`qmd_multi_get`	批量检索文档（支持 glob、列表、docids）
`qmd_status`	查看索引状态和集合信息

MCP 配置示例

Claude Desktop 配置 (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Claude Code 配置 (~/.claude/settings.json):

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

2.3 数据存储架构

qmd 使用 SQLite 作为后端存储，所有数据存储在 ~/.cache/qmd/index.sqlite：

数据表结构

表名	用途
`collections`	索引的目录，包含名称和 glob 模式
`path_contexts`	虚拟路径的上下文描述 (qmd://…)
`documents`	Markdown 内容和元数据，docid（6字符哈希）
`documents_fts`	FTS5 全文索引
`content_vectors`	Embedding 向量块（哈希、序号、位置、800 tokens）
`vectors_vec`	sqlite-vec 向量索引（hash_seq 键）
`llm_cache`	缓存的 LLM 响应（查询扩展、重排分数）

嵌入模型配置

qmd 使用三个本地 GGUF 模型（首次使用时自动下载）：

模型	用途	大小	HuggingFace URI
`embeddinggemma-300M-Q8_0`	向量嵌入	~300MB	`hf:ggml-org/embeddinggemma-300M-GGUF/...`
`qwen3-reranker-0.6b-q8_0`	重新排序	~640MB	`hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/...`
`qmd-query-expansion-1.7B-q4_k_m`	查询扩展（微调）	~1.1GB	`hf:tobil/qmd-query-expansion-1.7B-gguf/...`

模型缓存在 ~/.cache/qmd/models/ 目录。

2.4 评分系统与解释

qmd 使用多阶段评分系统：

后端原始分数

后端	原始分数	转换	范围
FTS (BM25)	SQLite FTS5 BM25	`Math.abs(score)`	0 到 ~25+
Vector	余弦距离	`1 / (1 + distance)`	0.0 到 1.0
Reranker	LLM 0-10 评分	`score / 10`	0.0 到 1.0

最终分数解释

分数	含义
0.8 - 1.0	高度相关
0.5 - 0.8	中等相关
0.2 - 0.5	somewhat 相关
0.0 - 0.2	低相关

2.5 技术限制与边界

系统要求

Bun >= 1.0.0（运行环境）
macOS: 需要 Homebrew 安装的 SQLite（扩展支持）
```
brew install sqlite
```

文件格式限制

目前主要针对 Markdown 文件优化
支持通过 glob 模式自定义文件匹配
大型文件（超过 10KB）在 multi-get 时可能被跳过（可配置）

模型依赖

首次运行需要下载约 2GB 的 GGUF 模型
需要本地下载和存储空间
模型通过 HuggingFace 下载，需要网络连接

性能特征

索引速度: 取决于文档数量和大小
搜索速度:
- search: 毫秒级
- vsearch: 百毫秒级
- query: 秒级（包含重排）
内存占用: 主要取决于模型加载，约 2-3GB

2.6 可行性验证

已验证能力 ✅

本地运行: 完全本地化，无需云端 API（除首次下载模型）
MCP 支持: 内置 MCP 服务器，可与 Claude、Cursor 等集成
多种输出格式: 支持 JSON、CSV、Markdown、XML 输出
集合隔离: 支持多个知识库，可按集合过滤搜索
Agent 友好: --json 和 --files 输出专为 Agent 工作流设计

潜在限制 ⚠️

仅支持 Markdown: 对其他格式（PDF、Word 等）支持有限
Bun 依赖: 需要 Bun 运行时环境
模型下载: 首次使用需要下载大模型文件
单用户设计: 非多用户系统，适合个人或小型团队

参考资料

QMD GitHub - Architecture - 架构图和数据流说明
QMD GitHub - MCP Server - MCP 集成文档
Awesome MCP Servers - MCP 服务器生态系统