rule-based-retrieval

背景：RAG 应用的「大海捞针」困境

想象一个场景：你手头有一份 500 页的法律合同，需要问 LLM 一个高度专业化的问题——"这份合同中关于违约金的上限是多少？"普通 RAG（Retrieval Augmented Generation）会怎么做？它把问题转成向量，在整个文档库里做语义搜索，返回最相关的片段。听起来没问题，但问题在于：LLM 可能从错误的地方"捞"到答案，尤其是当向量数据库里有成百上千份文档时。

这正是 Rule-based Retrieval 试图解决的核心痛点：让检索变得可控、可预测，而不只是依赖向量相似度的玄学匹配。

项目起源与核心定位

Rule-based Retrieval（后简称 RBR）由独立开发者 Tom Smoker 创建，是一个 Python 包，定位为 RAG 应用的结构化检索层。它最初聚焦于 Pinecone 作为向量数据库，后来逐步扩展支持 Milvus 和 Qdrant，形成了完整的多后端支持矩阵。

项目采用标准的 Python 包结构（src/whyhow_rbr/），代码量约 5000 行，遵循 MIT 许可证，作者维护活跃，配有完整的 mkdocs 文档站。截至 2024 年 10 月已有 248 颗 GitHub Stars。

核心机制：Rule 是什么？

RBR 的灵魂是一个叫 Rule 的数据结构。每一个 Rule 代表一条明确的检索规则，包含三个维度：

1. 文件名过滤（filename） 指定只从哪个 PDF 文件中检索。例如 filename="contract.pdf"，RBR 就会把向量搜索范围限定在这个文件内，而不是在整个向量数据库里漫无目的地搜索。

2. 页码过滤（page_numbers） 进一步精确到特定页面。当你知道答案在第 40 页时，可以直接写 page_numbers=[40]，避免向量搜索在其他无关页面"漂移"。这在处理长文档时特别有价值。

3. 关键词触发（keywords） 这是一个可选但极其强大的功能。当用户问题中包含某些关键词时，RBR 会自动激活对应的规则。比如问"Harry Potter 喜欢吃什么？"时，关键词 ["food", "favorite"] 会触发专门检索食物相关段落的规则，而不是让向量相似度"猜"一个答案。

这三个维度组合起来，就形成了一个 "精确制导"的检索系统——不是靠向量相似度"猜"答案，而是靠规则"锁定"答案。

技术架构拆解

RBR 的代码架构非常清晰，核心模块如下：

在查询阶段，Client.query() 的执行流程如下：

1. 关键词触发判断（可选）：如果开启 keyword_trigger=True，则根据用户问题中的关键词筛选激活哪些 Rule
2. 向量搜索 + 规则过滤：将问题转为向量，在向量数据库中执行带过滤条件的相似度搜索
3. 多规则处理：process_rules_separately=True 时每个 Rule 独立执行再合并结果，False 时所有规则联合查询
4. 上下文拼接：将匹配到的文本片段作为上下文，喂给 OpenAI Chat API 生成答案
5. 结果返回：返回 answer（回答）、matches（检索到的文档片段）、used_contexts（实际用到的片段索引）

值得注意的是，RBR 并没有魔改 LangChain——它大量复用 LangChain 的组件（langchain_core、langchain_community、langchain_openai），只是在上层封装了一个规则过滤的抽象层。这种设计策略很聪明：站在巨人的肩膀上，专注于自己擅长的检索规则逻辑。

代码质量评估

从 pyproject.toml 可以看出项目在工程实践上有较高追求：

• 类型安全：使用 Pydantic v2 做数据校验，mypy 开启严格模式（strict_equality、disallow_untyped_defs 等），强制标注所有函数签名类型
• 代码风格：Black + isort + flake8 完整覆盖，行长度 79 字符（偏执但一致）
• 测试覆盖：pytest + pytest-cov，GitHub Actions 里有 CI 流水线
• 文档工具：mkdocs + mkdocstrings，为每个公开 API 生成文档

RBR 的代码质量评分可以给到 85/100，主要扣分项是没有 Docker 支持（部署依赖较多外部服务），以及开源社区活跃度有限。

适用场景

RBR 最适合以下几类场景：

• 结构化文档问答：合同、论文、手册等有明确页码和章节的文档，需要精确检索的场景
• 多文档 RAG：当向量数据库中同时管理多份文档，且需要按文档/页码隔离检索时
• 规则驱动的工作流：有明确的业务规则（比如"关于第X章的问题必须查第X章"）的场景

以下场景则不太适合：

• 开放式问答：问题没有明确的文档归属，难以设计规则
• 实时更新的知识库：规则需要人工维护，对动态数据不够友好
• 低成本方案：OpenAI API + Pinecone 的成本对于小规模应用可能偏高

局限与争议

RBR 最大的局限在于规则维护成本。每增加一个新的文档或查询维度，就需要新增或修改 Rule。对于有几十上百份文档的场景，Rule 的管理工作会变成新的瓶颈。

此外，项目对向量数据库的选择偏向商业化方案（Pinecone 是收费服务，Milvus 和 Qdrant 虽然有开源版，但配置复杂度不低）。对于只是想快速验证 RAG 想法的开发者而言，门槛仍然偏高。

最后，RBR 尚未支持图片、表格等多模态内容检索，这在大模型上下文窗口越来越大的当下，是一个值得关注的进化方向。

行业意义

Rule-based Retrieval 代表了 RAG 领域的一个细分流派：从"向量相似度至上"向"结构化可控检索"的范式转变。随着 LLM 的能力越来越强，检索层的精确度和可控性反而变得更加重要——你不想让 LLM"自由发挥"去猜答案，而是要确保它看到的上下文就是正确的。

这类结构化 RAG 的思路与 LangChain 的 LangGraph、LlamaIndex 的 Node Parser 等工具形成互补。整个 RAG 生态正在从"把文档塞进去、问问题出来"的粗暴模式，向更精细化的检索-理解-生成流水线演进。RBR 站在了这个演进路径的一个有意义的位置上。