Controllable-RAG-Agent：用确定性图约束 RAG 智能体的推理路径
This repository provides an advanced Retrieval-Augmented Generation (RAG) solution for complex question answering. It uses sophisticated graph based algorithm to handle the tasks.
秒懂
- 它是什么？
- 这个仓库用一个确定性图作为智能体的「大脑」，把复杂问答拆成可规划的步骤，并声称答案只来自自有数据。它更像一份可拆解的参考实现，而不是一个装好即用的库。
- 适合谁用？
- 如果你要处理的是多跳、需要引用原文的问题，并且愿意按 notebook 逐步改造，这个仓库值得作为起点；如果你的场景只是单跳检索问答，用 LangChain 的常规检索链更省事。上手前先确认三件事：notebook 里对 OpenAI 密钥和向量库的具体配置项、Ragas 评测依赖的指标口径，以及你能否接受把整本书按章节摘要再入库带来的预处理开销。
- 能商用吗？
- 可以。Apache-2.0 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库在最近一天内有新的提交。
- 用什么语言写的？
- 主要是 Jupyter Notebook（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它要解决的不是「检索不到」，而是「一次检索不够」
常规 RAG 的做法是：把问题编码成向量，取回最相似的若干片段，交给模型生成答案。这套流程在问题本身就是一个完整语义单元时够用，比如「第三章讲了什么」。但一旦问题需要跨章节串联，比如先定位某个人物，再找他做过的某件事，最后引用原话，单次相似度检索就会漏掉中间环节。README 开篇把目标写得很直白：处理「simple semantic similarity-based retrieval cannot solve」的复杂问题。
目标读者也比较清楚。仓库主体是 Jupyter Notebook，不是打包好的 pip 包，说明它假设使用者愿意读代码、改代码。README 里同时挂了作者的书、课程和另外两个仓库的链接，这种组织方式透露出它的定位：教学与参考实现优先，工程封装其次。如果你想要的是 import 一个类就能跑起来的东西，这里不是。
确定性图作为大脑，规划与执行分离
README 反复强调一个词：deterministic graph。它把图描述为智能体的「brain」，负责复杂推理。与之相对的是让大模型自由决定下一步调用什么工具的做法，那种方式每一步都由模型即兴判断，路径不可预测。这里把控制流写进图里，模型只在图规定的节点内做生成或判断。
README 的 Key Features 列出了几个能力：多步推理把复杂查询拆成子任务，自适应规划根据新信息持续更新计划，以及声称的幻觉预防，即答案只基于提供的数据。这三条其实互相牵制：规划要更新，就意味着图里存在回环或条件分支；答案要限定在数据内，就意味着生成节点必须拿到检索到的原文或摘要作为上下文。README 没有给出节点级别的完整定义，具体分支条件需要看 notebook 里的图构建代码。
仓库的图片资源里有一张 graphs/final_graph_schema.jpeg，README 把它放在 How It Works 一节，作为整体流程的示意。这是理解控制流的第一手材料，比文字描述更可靠。
数据流：从 PDF 到章节摘要，再到两个向量库
README 的 How It Works 把处理链条拆成五步，顺序是明确的。第一步加载 PDF 并按章节切分，注意切分单位是 chapter，不是固定长度的 chunk。第二步做文本预处理，为后续的摘要和编码做准备。第三步用大模型为每个章节生成较长的摘要。第四步单独建一个「Book Quotes Database」，README 的说法是，它服务于那些需要访问书中原话的问题。第五步把书籍内容和章节摘要分别编码进向量库。
这里有两处设计值得注意。其一，摘要和原文走的是不同的存储路径，这意味着检索时可能先命中摘要定位到章节，再回到原文取细节，而不是一次性在扁平索引里找相似片段。其二，引文库被单独拿出来，说明作者认为「引用原句」和「语义检索」是两类不同的访问模式，前者对字面匹配的要求高于语义相似。
代价也在这里。整本书要过一遍大模型做章节摘要，这一步的 token 消耗和时间成本随书的体量线性增长，README 没有给出任何耗时或成本数字。
跑起来需要你自己补齐的部分
README 没有提供安装命令，也没有列出 requirements.txt 或 pyproject.toml 的内容。可以确认的依赖方向来自仓库的 topics 标签：langchain、langgraph、openai、python。也就是说，图编排大概率基于 LangGraph，模型调用走 OpenAI。
这意味着环境准备需要你自己动手：建虚拟环境，安装 Jupyter，再按 notebook 里第一条 import 单元格缺什么补什么。API 密钥方面，README 没有展示任何环境变量名，也没有 .env 示例。按 OpenAI 生态的惯例，通常是 OPENAI_API_KEY，但这是推测，不是仓库给出的配置项，实际键名要以 notebook 里的读取代码为准。
评测环节是少数有明确名字的部分：README 说使用 Ragas 指标做质量评估。Ragas 有自己的指标定义和依赖，跑之前需要单独安装。至于向量库用的是哪一种、持久化到哪里，README 的可见部分没有交代。
确定性带来可控，也带来写死的路径
把控制流固化在图里，好处是每一步可审计、可复现，出问题时能定位到具体节点。坏处同样直接：图覆盖不到的提问方式，智能体不会自己绕过去。用户问了一个设计时没预料到的组合，规划节点可能给出一个看似合理但走不通的路径，然后卡在某个检索节点返回空结果。
README 声称的幻觉预防也需要打个折扣理解。「答案只基于提供的数据」在工程上通常等于「上下文里只放检索到的内容，并在提示词里约束模型」。这能降低编造概率，但不能消除。如果检索本身没召回正确章节，模型面对的是不完整甚至无关的上下文，此时它要么拒答，要么在有限材料上做出错误归纳。README 没有描述拒答机制。
另一个现实约束是数据形态。整条流水线从 PDF 加载开始，按章节切分。如果你的知识源是 API 返回的 JSON、数据库表或者网页，前两步就不适用，需要自己替换加载和切分逻辑。把它当成通用 RAG 框架来用会失望。
和 LangChain 常规检索链的差别在哪
最直接的对照是 LangChain 里的检索问答链：一次检索，一次生成，链式结构固定且通常没有回环。它便宜、快、容易调试，在问题与文档片段语义对齐时表现稳定。Controllable-RAG-Agent 走的是另一条路，用 LangGraph 这类支持状态和分支的图编排，允许规划节点根据中间结果调整后续步骤。
差别不在检索算法本身，而在控制层。前者把「检索什么」交给一次向量查询决定，后者把「先查什么、再查什么」显式建模成图上的节点序列。对于「先找到 A，再根据 A 查 B」这类问题，后者的结构天然匹配；对于「这段话什么意思」，前者的开销小得多。
选择时要诚实评估问题的跳数。如果绝大多数线上查询都是单跳，引入图编排只会增加延迟和调试面积，收益接近于零。
维护成本与 Apache-2.0 的实际含义
仓库没有发布任何 release，也没有版本号可依赖。默认分支 main，最近一次推送时间在 2026 年 9 月。这意味着升级方式是直接拉取 main，而不是锁定一个语义化版本。对使用者来说，notebook 里的代码随时可能变动，把它的逻辑抄进生产代码后，跟进上游改动需要人工比对。
notebook 作为主要载体还有一层影响：它不易被测试覆盖，也不易被当作库来 pin 版本。如果要把这套流程产品化，实际做法是把 notebook 里的图定义和节点函数抽成模块，这一步的工作量 README 没有涉及。
许可证是 Apache-2.0，允许商用和修改，附带专利授权条款，要求保留版权与许可声明，并对修改过的文件作出说明。README 里大量指向作者个人书籍、课程和订阅的链接属于内容层面的推广，不影响代码许可。以上是对许可证文本的一般性描述，不构成法律意见，涉及分发或商用前应自行核对完整条款。
什么时候该用它，什么时候该绕开
适合的场景：你手里有一本或一批结构清晰的 PDF，问题经常需要跨章节串联，并且你希望推理路径可复现、可逐步排查。这种情况下，仓库提供的章节摘要加引文库的双轨设计，比扁平索引更贴合需求。
不适合的场景：数据源不是 PDF，或者查询以单跳为主。前者需要重写加载与切分，后者用不上图编排。另外，如果团队没有意愿维护 notebook 派生出来的代码，把它当成一次性实验可以，当成长期依赖不合适。
动手前建议先打开 graphs/final_graph_schema.jpeg 和主 notebook，确认图的节点数量和分支条件是否符合你的问题形态，再决定是否投入预处理成本。
编辑结论
如果你要处理的是多跳、需要引用原文的问题，并且愿意按 notebook 逐步改造，这个仓库值得作为起点；如果你的场景只是单跳检索问答，用 LangChain 的常规检索链更省事。上手前先确认三件事：notebook 里对 OpenAI 密钥和向量库的具体配置项、Ragas 评测依赖的指标口径，以及你能否接受把整本书按章节摘要再入库带来的预处理开销。
社区笔记