qmd

qmd - 快速 Markdown 搜索

用于搜索 Markdown 笔记、文档和知识库的本地搜索引擎。索引一次，快速搜索。

适用场景（触发短语）

• “搜索我的笔记 / 文档 / 知识库”
• “查找相关笔记”
• “从我的文档集中检索 Markdown 文档”
• “搜索本地 Markdown 文件”

默认行为（重要）

• 优先使用 qmd search（BM25）。它通常能即时返回结果，应作为默认选项。
• 仅在关键词搜索失败且需要语义相似度时使用 qmd vsearch（冷启动时可能非常慢）。
• 除非用户明确要求获得最高质量的混合搜索结果且能接受较长的运行时间或超时，否则避免使用 qmd query。

搜索模式

模式	命令	速度	适用场景
BM25（默认）	qmd search	即时	关键词匹配
向量	qmd vsearch	冷启动约 1 分钟	语义相似度
混合	qmd query	最慢	大模型重排（除非有要求，否则跳过）

常用命令

qmd search "query"              # default - fast keyword search
qmd search "query" -c notes     # search specific collection
qmd search "query" -n 10        # more results
qmd search "query" --json       # JSON output
qmd search "query" --all --files --min-score 0.3

实用选项

• -n <num>：结果数量
• -c, --collection <name>：将范围限定为某个文档集
• --all --min-score <num>：返回所有高于阈值的匹配项
• --json / --files：适合 Agent 使用的输出格式
• --full：返回完整的文档内容

检索文档

qmd get "path/to/file.md"       # Full document
qmd get "#docid"                # By ID from search results
qmd multi-get "journals/2025-05*.md"
qmd multi-get "doc1.md, doc2.md, #abc123" --json

维护

qmd status                      # Index health
qmd update                      # Re-index changed files
qmd embed                       # Update embeddings

设置（如果尚未安装）

# Install
bun install -g https://github.com/tobi/qmd

# Create collection
qmd collection add /path/to/notes --name notes --mask "**/*.md"
qmd context add qmd://notes "Description of this collection"  # optional
qmd embed  # one-time to enable vector + hybrid search

性能说明

• qmd search 通常能即时返回结果
• qmd vsearch 冷启动时可能需要约 1 分钟（会加载本地大模型以扩展查询）
• qmd query 会在 vsearch 的基础上增加大模型重排，因此速度更慢

常见问题

搜索查询过于宽泛（结果不相关）

问题：“笔记”或“项目”等宽泛查询会返回数百条相关性较低的匹配项。

解决方案：

• 使用具体关键词：qmd search "Python async context managers"，而不是 qmd search "Python"
• 组合关键词：qmd search "deadline March quarterly review"
• 使用引号匹配确切短语：qmd search "exact phrase match"
• 检查结果分数：使用 qmd search "query" --all --min-score 0.5 过滤低置信度匹配项

索引未更新（缺少最近的文件）

**问题：**新建或最近修改的文件没有出现在搜索结果中。

解决方案：

# Check index status
qmd status

# Re-index all changed files
qmd update

# Full re-index if update doesn't help
qmd collection remove <name>
qmd collection add /path/to/notes --name <name> --mask "**/*.md"
qmd embed  # if vector search enabled

路径过滤器错误（排除了相关目录）

**问题：**由于文档集掩码范围太窄或文档集路径错误，搜索找不到文件。

解决方案：

# List current collections
qmd status

# Verify collection path matches your notes location
# If path changed, re-add collection:
qmd collection remove <old-name>
qmd collection add /path/to/notes --name <name> --mask "**/*.md"

# Common issue: subdirectories excluded by mask
# If notes are in journals/2025/*, use: --mask "**/*.md"
# Not: --mask "*.md" (which only matches top level)

在大型库中搜索超时（性能问题）

**问题：**在大型知识库（1000 个以上文件）中，qmd query 或 qmd vsearch 会卡住或超时。

解决方案：

• 避免在大型库中使用 qmd query（大模型重排速度太慢）
• 改用 qmd search（即使在庞大的文档集中，BM25 也很快）
• 如果需要语义搜索，使用 qmd vsearch 并添加 -n 5 以限制结果数量
• 使用 -c <collection> 限定搜索范围，只搜索一个文档集，而不是全部：

  qmd search "query" -c notes -n 5  # faster than searching all collections
  

• 如果库中的文件超过 5000 个，可考虑拆分为多个文档集

缺少配置（qmd 尚未初始化）

问题：qmd status 显示“No collections”，或 qmd search 没有返回结果。

解决方案：

# Install qmd if missing
bun install -g https://github.com/tobi/qmd

# Set up a collection
qmd collection add /path/to/notes --name notes --mask "**/*.md"

# Enable vector search (optional but recommended)
qmd embed

# Verify setup
qmd status  # Should show your collection with file count

语义搜索返回不相关的结果（vsearch/query）

**问题：**向量搜索能匹配主题，却没有找到你实际需要的内容。

解决方案：

• 回退到 qmd search（对于具体词语，BM25 关键词匹配更加精准）
• 重新措辞查询，加入实际关键词：不要问“我的目标是什么？”，而是搜索“目标 季度回顾 目的”
• 如果可以使用 qmd query，可尝试使用（它会增加大模型重排），但只有在能接受较慢的运行时间时才使用
• 使用 -n 3，从向量搜索中获取更少、置信度更高的匹配项