qmd
本地知识库的混合检索底座——BM25 + 向量检索 + 重排序，让 LLM 在 Markdown 文件系统中精准找到该看的内容
简介
qmd（全名 @tobilu/qmd）是一个面向本地 Markdown 文件知识库的混合检索引擎。它的定位不是全能知识管理系统，而是知识库的检索底座——不负责理解知识，不负责设计知识结构，只负责一件事：当知识库变大之后，帮 LLM 找到该看的东西。
与纯向量数据库（如 Chroma、Pinecone）不同，qmd 同时支持 BM25 词法检索和向量语义检索，并叠加重排序。这种混合策略特别适合技术文章、论文、笔记、代码说明这类材料——精确词（如 CLAUDE.md、raw_sha256、某个论文标题、某个命令名）用 BM25 匹配更可靠，模糊语义问题用向量检索更合适。
qmd 的核心概念是 Collection——一组被索引的文件。一个知识库应该按用途注册多个 Collection（如 sources、concepts、entities、raw），而非粗暴把整个文件夹注册成一个集合。每个 Collection 还需要 context description 来告诉重排序模型”这个集合里装的是什么”，这直接影响跨集合的检索排序质量。
关键信息
- 类型：工具 / 检索引擎
- 领域：知识管理 / 本地知识库 / LLM 辅助检索
- 安装方式：
npm install -g @tobilu/qmd - 核心技术：BM25 词法检索 + 向量语义检索 + 重排序
- 数据格式：Markdown 文件（.md）
- 索引单位：Collection（一组被索引的文件，可按用途划分）
- 相关概念：RAG 知识库、Embedding 嵌入、上下文工程、Claude Code
核心特性
混合检索：BM25 + 向量 + 重排序
只用向量检索会遇到”语义大概能找但精确词不稳”的问题。qmd 的混合策略让两类查询各取所长：
| 查询类型 | 适合的检索方式 | 示例 |
|---|---|---|
| 精确词/专有名词 | BM25 词法检索 | CLAUDE.md、raw_sha256、论文标题、命令名 |
| 模糊语义问题 | 向量语义检索 | ”Transformer 的位置编码怎么工作” |
| 通用查询 | 混合 + 重排序 | 日常搜索，兼顾精确和语义 |
Collection 按用途划分
一个知识库不应该把所有文件注册成一个大集合。正确做法是按文件用途划分：
technical-sources → technical/wiki/sources/*.md # 摘要页
technical-concepts → technical/wiki/concepts/*.md # 概念页
technical-entities → technical/wiki/entities/*.md # 实体页
technical-raw → technical/raw/**/*.md # 原始文档
每个 Collection 加 context description（如”source 页面是一篇文档的摘要”、“raw 是不可修改的原始资料”），告诉重排序模型集合的语义定位。这决定了检索时”用户这个问题更应该去什么类型的页面里找”。
块级检索处理超长文档
对于几十页甚至两百页的长文档，qmd 支持块级检索（search-chunks）——不在全文中搜，而是在 raw 文档的块级索引中按主题找最相关的几个片段。LLM 每次只读几个块，配合 WIP（Work In Progress）文件记录处理进度，实现”处理完一个主题就落盘”的断点续传。
语义化 CLI 封装
qmd 的原始命令比较底层、参数组合多，直接让 LLM 调用容易出错。最佳实践是用 bin/wiki 封装成语义化命令：
| 命令 | 用途 | 说明 |
|---|---|---|
wiki search "关键词" | 日常查询 | 默认搜当前域 wiki 页面 |
wiki search-lex "关键词" | 词法检索 | 专有名词、命令名、文件名 |
wiki search-vec "问题" | 向量检索 | 模糊语义问题 |
wiki search-cross "关键词" | 跨域搜索 | 搜所有域和 shared 层 |
wiki find-related "主题" | ingest 专用 | 阈值更低、返回更多候选 |
wiki search-chunks "主题" -n 5 | 块级检索 | 长文档按主题找相关段落 |
wiki get "路径" | 文档取回 | 读取单个页面 |
wiki bulk "类型" | 批量读取 | lint 时批量检查 |
不同素材中的观点
- 2026-05-28-woshipm-llm-wiki-qmd-architecture（秋孝隱）：qmd 的五条选择理由——Markdown 文件系统天然适配、混合检索解决精确+语义双需求、CLI 封装让 LLM 稳定调用、块级检索处理超长文档、本地轻量可迁移。定位为”检索底座”而非全能引擎，只负责帮 LLM 找到该看的东西，不负责理解知识和设计结构。配套的四层架构（用户→LLM→CLI→系统）和 Collection 按用途注册的实践方案
实用信息
- 快速上手：
npm install -g @tobilu/qmd→ 建目录（raw + wiki）→ 写 bin/wiki CLI 封装核心命令 → 注册 Collection（按用途分开）→ 写 context description →reindex建索引 - 关键配置：Collection 的 context description 直接影响检索质量——告诉重排序模型每个集合的语义定位
- 适用场景：本地 Markdown 知识库、LLM 辅助知识管理、技术文档/论文/笔记检索、需要精确词+语义混合检索的场景
- 不适用场景：非 Markdown 格式为主的知识库、需要实时多人协作的知识库、纯语义问答（RAG 更合适）、文档量极小（<50 篇）不需要专门检索引擎