前言

一天的 demo 与几个月的系统

RAG 最迷惑人的地方在于：第一个 demo 往往一天就能跑起来。

你把公司文档丢进一个 loader，用默认 splitter 切成 1000 token 一块，调用 Embedding API 得到向量，塞进一个向量数据库，然后写十几行代码：用户提问，向量相似度 top-k，拼进 prompt，让大模型回答。演示时效果很好。问"报销流程是什么"，它能回答；问"某个接口怎么鉴权"，它能从文档里摘出一段；问"请总结这份白皮书"，它看起来也能说得头头是道。

然后系统开始面对真实用户。

用户问的是"上次那个合同模板能不能给法务看"，但知识库里有 17 份合同模板；用户问的是"生产报警怎么处理"，但 runbook 里同一个报警在三个版本中处理方式不同；用户问的是"这个 API 为什么返回 403"，答案散落在 OpenAPI 文档、权限表、服务端代码、历史事故复盘里；用户没有权限看某个部门的文档，但相似度最高的 chunk 偏偏来自那份文档；用户追问"那如果是海外租户呢"，系统忘了上一轮检索到的是国内流程；模型最后生成的答案很流畅，却引用了一个已经废弃的政策。

这时你会发现，RAG 的难点从来不是"怎么把向量查出来"。难点是：

• 知识进入系统时，结构、时间、权限、来源是否还在。
• 用户问题进入系统时，是否被改写成了真正可检索的形式。
• 检索候选返回时，系统是否知道哪些是证据、哪些只是语义相近。
• 上下文被塞给模型时，是否保留了足够的因果链和引用。
• 答案生成之后，系统是否能解释它依赖了哪些材料。
• 线上效果下降时，团队是否知道该调 chunk、embedding、rerank、prompt，还是数据本身。

RAG 从 demo 到生产，差距就在这些边界里。

这本书讲什么

本书讲的是 RAG 工程与检索系统设计。

这里的 RAG 不是一个库、一个框架、一个向量数据库功能，也不是 prompt 里加一句"请根据以下资料回答"。本书把 RAG 看成一个完整的信息系统：它把外部知识转化为可检索的表示，在用户提问时召回证据，再把证据以可控方式交给大模型，最终生成可以追溯、可以评估、可以持续改进的答案。

这条链路可以概括为：

本书每一章都围绕这条链路上的一个工程问题展开。第 5 章讲文档解析时，我们不会停留在"PDF 可以读取文本"这种层面，而会讨论表格、标题层级、页眉页脚、扫描件 OCR、代码仓库路径这些结构如何影响后续检索。第 6 章讲 chunking 时，我们不会只列几个 splitter 参数，而会解释为什么"固定长度 + overlap"会破坏段落语义，为什么结构化分块在技术文档里通常比语义分块更稳定。第 20 章讲评估时，我们不会只说"做 A/B 测试"，而会把召回评估、排序评估、答案评估和幻觉检测拆开，因为这四个问题的诊断方法完全不同。

这本书不是什么

这本书不是某个框架的使用教程。 LangChain、LlamaIndex、Haystack、Dify、Ragas、Qdrant、Milvus、pgvector 都会在合适的地方被讨论，但本书不会按 API 手册逐项讲解。框架 API 会变，工程边界不会变。

这本书不是向量数据库产品评测。 本书会解释 HNSW、IVF、PQ、过滤、分片、副本、写入一致性这些设计如何影响 RAG，但不会给出"哪个数据库最好"这种脱离场景的结论。一个 10 万文档的内部知识库、一个 10 亿 chunk 的多租户 SaaS、一个只部署在 PostgreSQL 里的中小系统，对数据库的要求完全不同。

这本书不是大模型提示词合集。 RAG 的 prompt 很重要，但 prompt 只能消费上游给它的证据。召回错了、权限错了、上下文塞乱了，再精致的 prompt 也只是把错误包装得更自然。

这本书不是搜索引擎内核书。 本书会讲 BM25、倒排索引、向量索引和重排序，但重点是它们如何服务 RAG，不会展开到 Lucene 每一个 segment merge 细节。

本书的方法论

本书遵循四个原则。

第一，先问题，后技术。 每个模块先问它解决什么失败模式，再讲可选方案。比如 rerank 不是因为"业界都在用"，而是因为第一阶段召回必须追求覆盖率，覆盖率提高后候选里必然混入噪声，需要第二阶段用更贵但更准的模型重新排序。

第二，先系统，后组件。 RAG 的许多问题都不是单点故障。答案不准可能来自 chunk 太碎、embedding 模型不适合领域、metadata 丢失、top-k 太小、reranker 输入截断、prompt 没要求引用，或者知识库本身过期。只盯一个组件会把系统调成跷跷板。

第三，先可解释，后自动化。 在生产系统里，"自动优化"必须建立在可观测的指标上。你必须知道某次回答使用了哪些 chunk、这些 chunk 的召回分数和 rerank 分数分别是多少、为什么某些候选被权限过滤、最终上下文为什么丢弃了某段证据。没有这些日志，RAG 调优会变成玄学。

第四，先边界，后规模。 很多团队过早讨论十亿级向量索引，却还没有处理好文档更新、权限、引用和评估。规模问题很难，但边界问题更早杀死系统。一个答错且不可追溯的系统，即使延迟只有 50ms，也不能用于重要场景。

与本系列其他书的关系

这本书处在 AI 应用栈的中间层。

《LangChain 设计与实现》会讲框架如何抽象 Document、Retriever、Runnable；本书会进一步追问：一个 Document 应该保留哪些 metadata，Retriever 的 top-k 为什么不能孤立设置，Runnable 组合出来的链路如何被评估。

《LangGraph 设计与实现》会讲有状态 Agent 工作流；本书第 18 章会把 RAG 扩展到长期记忆，解释什么信息应该进入短期上下文，什么信息应该进入可检索记忆，什么信息应该被遗忘。

《MCP 协议设计与实现》会讲 Agent 如何接入外部工具；本书会把知识库本身也看成一种工具，讨论检索服务如何通过 MCP 暴露给不同 Agent，以及返回结果为什么必须包含来源、权限和置信度。

《Harness Engineering》会讲 Agent 工程方法论；本书是其中"记忆与上下文"这一支柱的深入展开。没有可控检索，Harness 只能依赖上下文窗口里的短期材料；有了 RAG，Agent 才能跨会话、跨文档、跨系统地工作。

信息来源与写作边界

本书会优先引用公开论文、官方文档、开源项目源码和可复现实验。经典参考包括 Lewis 等人在 2020 年提出的 Retrieval-Augmented Generation、Karpukhin 等人在 2020 年提出的 Dense Passage Retrieval、Malkov 与 Yashunin 在 2016 年提出的 HNSW、Robertson 与 Zaragoza 在 2009 年系统总结的 BM25 概率检索框架，以及 ColBERT、RAGAS、GraphRAG 等后续工作。

涉及具体项目实现时，本书会在对应章节标注版本、文件路径和行号；没有验证过的源码细节不会写成事实。涉及性能数字时，只使用论文、官方 benchmark、项目文档或本地可复现实验结果，不用二手博客作为论据。

这意味着本书不会为了显得"全面"而堆砌未经验证的工具清单。RAG 领域变化很快，工具名字会换，工程问题不会换。我们要抓住的是系统结构。

阅读路径

如果你是第一次系统学习 RAG，建议顺序阅读：第 1 到第 4 章建立全局链路，第 5 到第 8 章理解知识如何进入系统，第 9 到第 17 章理解在线检索和生成，第 18 到第 21 章进入生产化。

如果你已经做过 RAG demo，直接从第 3 章开始看失败模式，再按问题回到对应章节：召回差看第 6、9、10、13 章；答案不引用看第 16、17 章；权限和多租户看第 7 章；线上无法评估看第 20 章。

如果你在做 Agent，重点读第 1、4、15、16、18、19 章。Agent 的记忆不是一个聊天记录数组，而是一个带检索、更新、遗忘和权限边界的知识系统。

下一章从最根本的问题开始：为什么大模型已经读过很多知识，我们仍然需要 RAG。