qmd Local Search

核心用法

qmd 是一款专为本地知识库设计的全文检索工具，替代传统 find 命令实现智能文件发现。其核心工作流分为三步：

1. 索引构建 —— 通过 qmd collection add 将文件夹注册为集合，支持 *.md,*.py 等自定义掩码过滤
2. 多模检索 —— 提供三种查询模式：

3. 内容提取 —— qmd get 支持行号定位与多文件批量获取，--json/--md 格式化输出便于下游处理

• qmd search：BM25 关键词匹配（速度优先）
• qmd vsearch：向量语义搜索（理解意图）
• qmd query：混合检索 + LLM 重排序（质量优先）

显著优点

• 全本地执行：embedding、reranker、生成模型均自动下载到本地，无需 OpenAI/Anthropic API 密钥，彻底杜绝数据外泄风险
• 检索架构先进：BM25 + 向量 + LLM 三重排序，在学术评测框架（如 BEIR）中被验证优于单一策略
• 性能优化：针对大型目录避免 find 式的遍历挂起，索引后查询毫秒级响应
• 开发者友好：代码片段定位（--line-numbers）、YAML/JSON 结构化输出、glob 批量获取，完美适配 AI 编程助手上下文注入场景

潜在缺点与局限

• 冷启动成本：首次运行 qmd embed 需数分钟下载 300M 参数模型并构建向量索引，GB 级文档库耗时显著
• 资源占用：embedding 与重排序模型常驻内存，低配设备（<8GB RAM）可能出现卡顿
• 增量更新限制：qmd update 需手动触发，无实时监控文件变更的守护进程机制
• 格式覆盖偏科：对 PDF、Office 等非 Markdown 二进制格式原生不支持，需前置转换

适合人群

• 隐私敏感型开发者（医疗、金融、法律领域知识库检索）
• 离线环境或内网隔离场景下的技术文档管理
• 需要向 LLM 注入精准上下文的 AI 编程工作流用户
• Obsidian/Logseq 等本地笔记工具的进阶检索插件替代方案

常规风险

• 模型供应链：自动下载的 embeddinggemma-300M、qwen3-reranker 等模型来自第三方 HuggingFace 镜像，需校验哈希完整性防止投毒
• 索引泄露：向量索引文件（通常存储于 ~/.qmd/）包含文档语义指纹，共享设备需加密存储
• 结果幻觉：LLM 重排序虽提升相关性，但 0.6B 参数模型对复杂查询的理解力有限，极端情况下可能过滤有效结果

核心用法

qmd 是一款面向 Markdown 笔记、文档和代码的本地全文搜索工具，通过 CLI 封装提供三种检索模式：

| 模式 | 命令 | 适用场景 |

|------|------|---------|

| 关键词搜索 | `qmd search "query"` | 精确匹配文件名或内容 |

| 语义搜索 | `qmd vsearch "query"` | 理解自然语言含义的相关性搜索 |

| 混合重排序 | `qmd query "query"` | 结合 BM25 + 向量 + LLM  rerank 的最高质量结果 |

关键工作流：
1. 创建索引集合 qmd collection add /path --name project
2. 生成向量嵌入 qmd embed（一次性，约数分钟）
3. 执行搜索时始终指定集合 -c name 以限定范围
4. 文件变更后运行 qmd update 刷新索引

显著优点

• 完全本地：embedding、reranking、generation 三模型均本地运行（Gemma 300M/Qwen3 0.6B），零 API 费用零隐私泄露
• 智能检索：语义搜索突破关键词字面匹配局限，适合模糊查找
• 性能优异：专为大规模目录设计，避免 find 在万级文件时的卡顿
• 输出灵活：支持 --files 快速发现、--json 结构化数据、--md 格式化文档
• 精准定位：支持行号提取 qmd get file:line -l count 快速获取上下文

潜在局限

• 首次成本：向量嵌入需一次性计算，大知识库耗时较长
• 存储开销：本地模型与索引占用磁盘空间（预估数 GB）
• 硬件依赖：CPU 运行小模型，复杂 reranking 速度受限
• 生态封闭：仅支持 qmd 自身索引格式，无法直接对接现有搜索引擎
• 维护风险：个人开发者维护，长期更新保障存疑

适合人群

• 技术写作者、开发者笔记管理者
• 需要离线工作且敏感文档不愿上云的团队
• 已积累大量 Markdown/代码片段的知识管理用户
• 对检索召回质量有高要求、愿接受本地部署成本的用户

常规风险

• 来源可信度：T3 级别个人项目，建议 fork 后自主维护生产环境使用
• 工具链依赖：功能依赖外部 qmd CLI，需确保二进制来源可信
• 索引滞后：忘记 update 可能导致搜索结果不包含最新文件