可控复杂 RAG 智能体
用确定性图规划、检索并验证复杂的多步问答。
README 清楚说明了 PDF、摘要、向量存储、检索、验证和外部 LLM API 的主要数据流，并对 Self-RAG、Plan-and-Solve、babyagi 和顾问作了来源说明。安装仅要求在 .env 中配置服务密钥，体现了有限的权限意识；但没有权限模型、调用前确认、密钥保护与日志隐私说明，也未说明遥测、数据保留、外部提供商传输边界、可撤销操作或回滚机制。依赖清单虽大量固定版本，但若干核心包未固定，且没有漏洞扫描、更新策略或供应链控制证据。
README、架构步骤和依赖清单大体描述同一套 RAG 工作流，但“deterministic”与持续由 LLM 规划并存，且“hallucination prevention”“solely based”“hallucination-free”等绝对表述没有所给评测结果支撑。依赖数量庞大，核心 LangChain 系列、pyppeteer 和 urllib3 等未固定版本，削弱可用性保障；安装章节还有重复标题和编号。没有错误处理、重试结果、降级路径或面向用户的失败消息证据。
材料面向希望分析自有长文档和复杂问题的 Python/RAG 用户，给出 Harry Potter 示例、Docker 与非 Docker 路径、OpenAI/Groq 选择及图式工作流。扣分在于能力边界和适用限制不清：没有定义文档规模、支持格式、模型兼容范围、任务终止条件或不适用场景。检索与回答之间的任务路由仅作概念描述，缺少可静态核查的精确触发规则。
README 具备功能、架构、用例、安装、使用、技术、贡献和致谢等基本结构，并提供 notebook 与 Streamlit 入口；完整 Apache-2.0 正文使许可处理充分。扣分项包括 Docker/非 Docker 小节组织和编号混乱、缺少 FAQ 与明确已知限制、没有版本发布或变更日志、核心依赖命名未稳定固定。维护路径仅泛指 PR、issue、社交和社区渠道，未说明负责人、支持承诺或更新政策；发布者身份未知本身未被当作安全或质量扣分。
多阶段分解、双层检索材料、重新规划和 Ragas 指标设计，相比简单相似度检索具有合理的潜在增量价值；教程、可视化入口和最终答案工作流也使输出具有普通使用价值。由于没有提供实际输出样本、量化评测表、基线比较或失败案例，效果只能部分确认。多次 LLM 摘要、规划、蒸馏和验证可能产生明显费用与延迟，但没有令牌、时间、基础设施成本或收益权衡说明。
架构步骤、依赖文件、许可证和研究引用为部分主张提供了可追踪依据，但关键质量主张没有附带评测数值、测试文件、实验配置或结果制品。不同来源间的佐证主要限于 README 与 requirements/LICENSE 的一致性，无法独立支持推理质量和防幻觉效果。营销性绝对主张、设计意图和已验证事实没有清楚分层，因此仅给予薄弱的事实—推断分离分数。
- 不要把“防止幻觉”或“仅依据所提供数据”等表述视为已验证保证；所给材料没有评测结果或测试制品支持这些绝对主张。
- 运行前应审查发送给 OpenAI、Groq 或其他提供商的文档内容、遥测和保留政策，并为 API 密钥、日志及敏感 PDF 建立独立保护措施。
- 部署前锁定未固定的核心依赖并执行当前漏洞与兼容性审查；庞大且版本策略混合的依赖集合可能导致安装漂移。
- 先在非敏感、小规模语料上测量答案质量、调用费用和延迟，并自行设计失败恢复与回滚流程。
这个 Agent 能做什么，适合哪些场景？
这是一个面向自有文档复杂问答的高级 RAG 实现，重点处理单纯语义相似度检索难以解决的问题。系统读取并预处理 PDF，将章节正文、LLM 生成的章节摘要及书中引文编码到向量存储中。其确定性图负责匿名化问题、制定计划、拆分任务、检索或作答、验证内容，并根据新信息持续调整后续步骤。最终输出基于累计上下文生成的答案，同时通过溯源验证降低脱离材料的生成。仓库提供 Jupyter 教程和 Streamlit 实时可视化界面，可在本机 Python 环境或 Docker 中自行部署，并使用 Ragas 指标进行质量评估。
流程首先加载 PDF 并按章节拆分，清洗文本，再调用 LLM 生成详细章节摘要。它把正文分块、章节摘要和书中引文编码到 FAISS Vector Store。收到问题后，系统以变量替换命名实体，针对匿名化问题制定高层计划，再恢复实体并将计划拆分成可检索或可直接回答的任务。每项任务会选择从向量存储检索并提炼信息，或依据已有上下文生成回答；随后检查生成内容是否有原始上下文支撑，并据此重新规划剩余步骤。系统最终汇总上下文生成答案；simulate_agent.py 通过 Streamlit 展示实时执行过程，sophisticated_rag_agent_harry_potter.ipynb 提供逐步教程，Ragas 用于评估正确性、忠实度、相关性、上下文召回率和答案相似度。
- 拥有长篇 PDF 或书籍资料的研究人员，需要回答必须跨章节识别人物、事件和因果关系的问题。
- 构建内部知识问答原型的机器学习工程师，希望明确控制规划、检索、回答和验证的每一步。
- 评估 RAG 质量的团队，需要用 Ragas 同时检查答案正确性、忠实度、相关性、上下文召回率和相似度。
- 教授高级 RAG 的讲师或学习者，希望通过 Jupyter 教程观察问题匿名化、任务拆解、向量检索与重新规划。
- 需要演示智能体执行轨迹的开发者，可用 Streamlit 实时可视化界面展示处理过程。
这个 Agent 有哪些优点和局限？
- 确定性图明确编排规划、任务执行、验证和重新规划，相比单次语义检索提供更细粒度的流程控制。
- 同时索引正文分块、章节摘要和引文，可为不同类型的问题提供多层次检索材料。
- 通过问题匿名化、检索内容提炼及上下文溯源验证，专门针对预训练知识偏置和无依据生成。
- 包含 Ragas 的五类评估指标，不只展示示例答案，也支持系统化衡量质量。
- 同时提供 Jupyter 分步教程、Streamlit 可视化和 Docker 启动方式，便于学习与演示。
- 文档聚焦书籍 PDF 和单个《哈利·波特》案例，没有给出网页、数据库或持续更新知识源的接入证据。
- 需要先调用 LLM 生成章节摘要并建立多个向量存储，带来额外的处理时间、API 调用和存储成本。
- 运行依赖外部 LLM 提供商密钥和网络；示例环境变量仅列出 OpenAI 与 Groq。
- 没有记录认证、并发、监控、持久化服务接口或生产扩缩容方案，采用者需要自行补齐生产工程。
- README 声称支持灵活集成其他 LLM，但未提供各提供商的具体兼容矩阵或功能差异说明。
如何安装或部署这个 Agent？
前置条件：Python 3.8+，以及所选 LLM 提供商的 API 密钥。
本机安装：
git clone https://github.com/NirDiamant/Controllable-RAG-Agent.git
cd Controllable-RAG-Agent在仓库根目录创建 .env，参考 .env.example，按实际提供商填写：
OPENAI_API_KEY=
GROQ_API_KEY=安装依赖：
pip install -r requirements.txt也可以在完成环境变量配置后使用 Docker：
docker-compose up --build如何使用这个 Agent？
逐步了解实现时，打开并运行 sophisticated_rag_agent_harry_potter.ipynb。本机启动实时可视化界面：
streamlit run simulate_agent.py使用 Docker 启动后，在浏览器访问 http://localhost:8501/。仓库示例以《哈利·波特》第一部为数据集，用于观察模型究竟依赖检索内容还是预训练知识；若改用自有数据，需要按该流程准备和处理 PDF。README 没有记录独立的 HTTP API、命令行问答接口或生产服务部署方式。
这个 Agent 与同类方案有什么区别？
与只按语义相似度返回片段的基础 RAG 相比，本项目增加问题匿名化、高层规划、任务拆解、检索内容提炼、上下文验证和动态重新规划，目标是解决需要多步推断的非平凡问题。代价是流程更复杂，并需要额外的 LLM 调用、索引准备和评估工作。README 还将 RAG_Techniques 定位为补充性的多种 RAG 技术指南，而不是本项目的直接替代品。
常见问题
必须使用 OpenAI 吗？
.env 示例中列出 OPENAI_API_KEY 和 GROQ_API_KEY；但没有说明其他提供商的具体配置步骤。它能保证完全没有幻觉吗？
是否提供现成的聊天 API？
streamlit run simulate_agent.py 和 Docker 中的 Streamlit 页面。