Controllable-RAG-Agent

复杂问答的终极解法：给大模型装上"可控大脑"

想象这样一个场景：你想问一本 1000 页的技术手册：「第三章关于性能优化的部分，和第五章关于缓存策略的内容，在解决高并发问题上有什么关联？」

传统的 RAG（检索增强生成）方式会怎么回答？它会把问题拆成两个独立查询，分别从向量数据库里捞出相关段落，再拼给大模型。这种「问答对」模式，对于「A 和 B 有什么关联」这类跨章节、需多步推理的问题，几乎无能为力——因为它根本不理解「查询」背后的真实意图，也不知道如何组织多轮检索。

Controllable-RAG-Agent 解决的就是这个问题：它给大模型装上了一个「可控的大脑」——一套基于 LangGraph 的确定性有向图工作流，让模型像人类专家一样，先规划、再分解、边执行边调整。

项目起源：为何需要「可控」的 RAG Agent？

本项目作者 Nir Diamant 是 AI 教育领域的活跃创作者，在 LinkedIn 和 Substack 上拥有大量关注者。他长期专注于 LLM 应用工程，产出过多个 RAG 相关的高星开源项目。

!

核心动机：当用户提出复杂问题（如「X 与 Y 的关系是什么」「A 导致 B 的原因是什么」）时，简单的向量相似度检索无法理解问题的语义结构。模型需要：

• 先理解问题本质（而非字面匹配）
• 制定执行计划（Plan）
• 按计划分步执行（Retrieve / Answer）
• 根据中间结果动态调整（Replan）

这些能力，正是 LangGraph 这类有向状态图框架的强项。项目以此为核心，构建了一个端到端的复杂问答 Agent。

架构解析：LangGraph 有向图工作流

!

图1：Controllable-RAG-Agent 的核心工作流架构（来源：项目 README）

整个系统的「大脑」是一条由 LangGraph 驱动的有向图，包含以下关键节点：

问题预处理阶段

• Anonymize Question（匿名化问题）：用变量替换问题中的实体（如人名、地名），防止 LLM 用预训练知识「作弊」
• Planner（规划器）：基于匿名化后的问题，生成高层回答计划
• De-anonymize Plan（去匿名化）：将计划中的变量还原为真实实体
• Break Down Plan（分解计划）：将计划拆解为可执行的原子任务（Retrieve / Answer）

执行阶段

• Task Handler（任务处理器）：根据任务类型分发到不同检索器
• Retrieve Chunks（检索段落）：从文档块向量库检索相关段落
• Retrieve Summaries（检索摘要）：从章节摘要向量库检索高层次上下文
• Retrieve Book Quotes（检索引文）：从书籍引文向量库检索精确引述

验证与回答阶段

• Answer（生成回答）：基于检索到的上下文，链式思考（Chain of Thought）生成回答
• Replan（重新规划）：根据当前执行结果判断是否需要调整计划
• Can Be Answered Already：检查是否已有足够信息生成答案
• Get Final Answer（最终回答）：输出带引用来源的最终答案

技术栈：LangChain 全家桶 + FAISS + Ragas

项目采用经典的生产级 Python 数据科学技术栈：

组件	技术选型	作用
LLM 框架	LangChain + LangGraph	Agent 状态管理与工作流编排
向量数据库	FAISS (Facebook AI Similarity Search)	高效语义检索
Embedding	OpenAI text-embedding-ada-002	语义向量化
Web UI	Streamlit	实时可视化 Agent 执行流程
评估框架	Ragas	5 项指标：答案正确性、忠实度、相关性、召回率、相似度
图形可视化	PyVis + NetworkX	有向图实时渲染
PDF 处理	PyPDF2	文档解析与章节分割
环境管理	python-dotenv	API Key 安全配置

多 LLM 支持：不仅支持 OpenAI GPT 系列，还支持 Groq（低成本推理）等其他 Provider，仅需修改 .env 配置即可切换。

核心创新：防止幻觉的 8 条启发式策略

项目 README 明确列出了 8 条核心设计原则，每条都对应一个工程实践：

1. 三层检索编码：同时对文档块、章节摘要、精确引文建立向量库。摘要提供高层语义，精确引文提供事实锚点，文档块提供细节上下文。三者配合，比单一 chunk 检索精确得多。

2. 问题匿名化：这是最关键的一步。如果直接问「哈利·波特如何打败伏地魔的助手」，GPT-4 很可能基于预训练知识回答。但把问题改成「X 如何打败 Y 的助手」，模型就只能依赖检索到的内容回答——从而强制 grounded 生成。

3. 任务分解与自定义函数：每个原子任务由独立的 Python 函数处理，而非全部交给 LLM 端到端生成。这种「可控函数调用」比纯 prompt engineering 更稳定。

4. 内容蒸馏（Distilling）：对检索结果进行二次压缩，去除噪声，保留核心信息，降低 LLM 的推理负担。

5. 链式思考（Chain of Thought）：Answer 节点同时提供正例和负例，引导模型「先思考再回答」，而非直接给出结论。

6. Self-RAG 风格的内容验证：验证生成内容是否扎根于原始上下文，参考了 Self-RAG 论文。

7. 动态重规划（Replan）：每完成一步任务，Agent 会重新评估：「还需要做什么？计划是否需要调整？」——这比一次性生成完整计划更适应复杂场景。

8. Ragas 指标评估：用 Ragas 框架量化评估回答质量，覆盖答案正确性、忠实度、相关性等维度，而非仅靠人工主观判断。

上手体验：Harry Potter 示例足够惊艳

项目的示例数据是《哈利·波特》第一部。作者选择这本书的理由很巧妙：大多数人都熟悉剧情，可以轻易判断模型是否在「用预训练知识答题」而非「检索书中内容答题」。

使用方式：

• Jupyter Notebook 教程（sophisticated_rag_agent_harry_potter.ipynb）：逐步体验每一步的输入输出
• Streamlit 实时可视化（streamlit run simulate_agent.py）：在浏览器中实时看到 Agent 执行到哪个节点、检索到了什么内容

项目还提供了完整的 docker-compose.yml，一行命令即可启动 Streamlit 服务：

git clone https://github.com/NirDiamant/Controllable-RAG-Agent.git
cd Controllable-RAG-Agent
cp .env.example .env
# 编辑 .env 填入 OPENAI_API_KEY
docker-compose up --build
# 访问 http://localhost:8501

图2：项目作者 Nir Diamant 的 Substack 通讯

局限性与使用门槛

主要局限：

• 向量库需预先构建：项目附带了预构建的 chunks_vector_store、chapter_summaries_vector_store 等目录，但如果用自己的 PDF 数据，需要先跑预处理脚本（涉及章节分割、向量化）——这部分有一定技术门槛
• API Key 依赖：运行需要 OpenAI/Groq API Key，调用有成本（虽然 Groq 免费额度较充足）
• 不支持中文文档开箱即用：预处理依赖 PyPDF2 和英文分词规则，中文 PDF 需自行调整
• Python 3.8+ 环境：不支持纯 Web 使用，需要本地 Python 环境

使用门槛评估：

• 对于有 LangChain / LangGraph 使用经验的开发者，上手非常顺畅
• 对于纯新手，Notebook 教程足够详细，但需要理解向量检索的基本概念

行业意义：复杂问答 RAG 的工程范式

项目增长轨迹：2024-04 创建，2025 年初达到 1000+ stars，目前 1615 stars，增长稳定。反映出市场对「复杂 RAG」解决方案的持续需求。

代表趋势：从 2023 年的「简单 RAG」（embedding + top-k 检索 → 直接 LLM 生成），演进到 2024-2025 年的「高级 RAG」（Query 改写 / 路由 / Agentic RAG），本项目是 Agentic RAG 路线的一个优秀范例。

可复用的设计模式：

• 匿名化问题 → 强制 grounded 生成
• 三层向量库 → 覆盖不同粒度的信息需求
• 有向状态图 → 可视化 + 可调试的 Agent 逻辑

这三个模式均可独立复用到其他 RAG 项目中，是本项目最大的技术价值所在。

总结

一句话评价：Controllable-RAG-Agent 是复杂问答 RAG 场景的工程标杆，它用 LangGraph 有向图将「规划-分解-执行-验证」流程固化为可复用、可视化的代码实现，对高级 RAG 开发者极具参考价值。

适合人群：有 LangChain 基础、需要在私有文档上进行复杂问答的 AI 开发者。

核心亮点：问题匿名化防幻觉策略 + 三层向量库检索 + 实时 Streamlit 可视化，三者组合在同类项目中独树一帜。