本地 Markdown 极速混合搜索

本地 Markdown 笔记混合搜索引擎，支持 BM25 关键词搜索与语义向量检索，适合个人知识库管理，索引一次即可快速查询。

基本信息

• 技能名称?QMD - Quick Markdown Search
• 中文名称?本地 Markdown 极速混合搜索
• 作者?emcmillan80
• 分类?专业技能
• 版本?1.0.0
• 标签?local-search, markdown, knowledge-base, bm25, vector-search, notes, privacy, bun

使用方法

使用说明
核心用法
qmd 是一款专为 Markdown 笔记和文档设计的本地搜索引擎，采用混合检索架构。用户通过 qmd collection add 添加笔记目录，执行 qmd embed 完成向量化索引后，即可使用三种搜索模式：
qmd search （默认）：基于 BM25 的关键词搜索，响应极快，适合日常使用
qmd vsearch ：语义相似度搜索，依赖本地 LLM 进行查询扩展，冷启动较慢
qmd query ：混合搜索 + LLM 重排序，质量最高但速度最慢，容易超时
支持指定集合( -c )、调整结果数量( -n )、JSON 输出( --json )等灵活选项，并提供 qmd get / multi-get 进行文档检索。
显著优点

1. 完全本地化 ：数据不出设备，使用本地 GGUF 模型，隐私性极强
2. 速度分层设计 ：BM25 搜索几乎瞬时响应，语义搜索按需启用
3. 内容智能分块 ：自动按语义段落切分，无需严格 Markdown 结构
4. 增量更新友好 ： qmd update 快速同步变更， qmd embed 按需刷新向量
5. 输出格式丰富 ：支持纯文本、JSON、文件路径等多种机器可读格式
   潜在缺点与局限性
   冷启动成本高 ：语义搜索需加载本地模型（如 Qwen3-1.7B），首次运行可能耗时约 1 分钟
   非代码搜索工具 ：不适用于源代码仓库检索，专注 Markdown 内容
   依赖 Bun 运行时 ：需安装 Bun >= 1.0.0，对 Node.js 用户增加环境负担
   macOS 额外依赖 ：需单独安装 SQLite 扩展
   维护 overhead ：需配置 cron 或定时任务保持索引新鲜，否则搜索结果可能过时
   适合人群
   本地优先的笔记用户（Obsidian、Logseq、Bear 等导出 Markdown 的用户）
   需要离线搜索的知识库管理者
   对数据隐私敏感、不愿使用云端笔记搜索的用户
   已使用 Bun 生态的开发者
   常规风险
   模型下载 ：首次自动下载 GGUF 模型，需确保网络可访问 Hugging Face 等源
   索引体积 ：大型笔记库的向量化索引可能占用显著磁盘空间
   路径配置 ：需确保 $HOME/.bun/bin 在 PATH 中，否则命令不可用
   性能预期管理 ：用户可能误将 vsearch / query 作为默认，导致体验卡顿