Agentic RAG 傻瓜式构建指南
用 LangGraph 快速搭建模块化、带记忆和人工确认的检索增强生成智能体。
- Star 数
- ★ 4.3k
- 最近更新
- 1 天前
- License
- MIT
- 主语言
- Jupyter Notebook
- FA 评分
- 51/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 开发者希望快速学习并实践 Agentic RAG 架构，借助 Jupyter 笔记本和示例文档逐步理解。
- 不适合
- 需要开箱即用、不想配置向量库和本地模型的团队
- 硬件较弱、无法运行 8B 以上本地模型的用户
- 需要完整 Docker 部署文档的生产环境
这个 Agent 能做什么，适合哪些场景？
该项目提供了一个基于 LangGraph 的模块化 Agentic RAG 系统，包含对话记忆、查询改写与澄清、多智能体并行检索、上下文压缩和自动纠错等完整流程。它采用父子分块的分层索引，结合稠密与稀疏向量的混合检索（Qdrant），并默认使用 Ollama 本地模型，同时兼容 OpenAI、Anthropic、Google 等云服务商。项目提供交互式 Jupyter 笔记本用于学习，以及可扩展的 Python 项目结构和 Gradio 聊天界面。此外，还包含基于 RAGAS 的评估工具和 Langfuse 可观测性集成。
该仓库演示了如何构建一个 Agentic RAG 系统。它接收用户提问，通过对话摘要和查询改写理解上下文，并在必要时请求澄清。系统将复杂问题分解为多个子问题，并行运行多个智能体子图，每个子图调用 search_child_chunks 和 retrieve_parent_chunks 工具进行分层检索，并根据需要对结果进行压缩和自纠错。最后，聚合所有子答案生成最终回答，并通过 Gradio 界面展示。整个过程由 LangGraph 状态图协调，支持使用 Qdrant 向量数据库和多种 LLM 提供商。
- 开发者希望快速学习并实践 Agentic RAG 架构，借助 Jupyter 笔记本和示例文档逐步理解。
- 技术团队需要构建一个可定制、模块化的 RAG 系统，以便嵌入到自己的文档问答应用中。
- 需要处理大量 PDF 文档，并希望通过分层索引和混合检索提升答案的准确性和上下文相关性。
- 希望本地运行 LLM（如 Ollama）控制成本，同时保留切换云服务商（OpenAI、Anthropic 等）的灵活性。
- 研发人员想要评估检索和回答质量，使用内置的 RAGAS 指标对系统进行量化评测。
如何安装或部署这个 Agent？
- 克隆仓库：git clone https://github.com/GiovanniPasq/agentic-rag-for-dummies
- 安装依赖：pip install -r requirements.txt 或 uv pip install -r requirements.txt
- 可选：安装 Ollama 并拉取模型：ollama pull granite4.1:8b
- 将 PDF 文件放入 docs/ 目录（可下载示例 PDF）。
如何使用这个 Agent？
选项1（快速测试）：在 Google Colab 中打开 notebooks/agentic_rag.ipynb，运行所有单元格，并上传 PDF 到 docs/。
选项2（完整项目）：运行 python project/app.py 启动 Gradio 界面，然后在浏览器中打开本地 URL（如 http://127.0.0.1:7860）进行对话。
需注意：Ollama 是默认 LLM 提供商，若使用云端模型，请在代码中替换为 OpenAI/Anthropic/Google 的示例。
这个 Agent 有哪些优点和局限？
- 提供两种使用路径：交互式笔记本学习概念，模块化项目便于生产集成。
- 架构高度模块化，LLM 提供商、嵌入模型、分块策略、工作流均可独立替换。
- 内置多智能体并行处理、查询澄清、上下文压缩、自纠错等高级 RAG 特性。
- 支持混合检索（稠密+稀疏），并默认使用 Ollama 本地模型，降低成本和隐私风险。
- 需要 Python 3.11+ 环境，并安装 Qdrant、LangGraph 等依赖，对轻量级使用来说较重。
- 默认使用本地 Ollama 模型，效果依赖硬件性能，文档建议使用 8B+ 参数模型以保证工具调用可靠。
- 文档中未提供 Docker 部署的完整细节，需参阅项目内 README。
- 评估和可观测性集成（RAGAS、Langfuse）需要额外配置，可能增加使用复杂度。
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Agentic RAG 傻瓜式构建指南 当前 | 51 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 4.3k | 1 天前 | Jupyter Notebook | — |
| RAGLight | 63 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 673 | 2 天前 | Python | OpenAI API |
| LangChain 生成式 AI 实战 | 52 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 1.4k | 2 个月前 | Jupyter Notebook | OpenAI API · Claude API |
| Dynamiq 智能体编排框架 | 61 · 存在缺口 | 代码库 / SDK免费 + 模型费 | ★ 1.1k | 2 天前 | Python | OpenAI API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：README 描述了查询澄清阶段的人工介入（human-in-the-loop），但未提供用户确认机制的具体实现；数据流透明度有限，仅提及 Langfuse 可观测性；敏感数据处理未明确说明；依赖固定版本但未提供安全审计；外部效果包括本地文件写入和向量数据库操作，但未说明权限范围；无回滚机制；来源归属仅通过元数据中的 source 字段，未提供完整溯源。扣分原因：缺乏最小权限原则的明确说明，用户确认仅作为功能描述，数据流透明度不足，敏感数据处理未涉及，依赖安全未审计，外部效果未明确权限，无回滚，来源归属不完整。
证据显示：代码内部逻辑一致，如父/子块大小校验；依赖版本固定，但未验证可用性；错误处理提供了部分返回信息（如 RETRIEVAL_ERROR）。扣分原因：依赖可用性未验证，失败消息覆盖不全面。
证据显示：README 明确面向学习者和开发者，提供两种使用路径；能力边界通过功能表说明；触发精度通过查询重写和澄清机制体现；环境适配支持多种 LLM 提供商和本地/云端部署。扣分原因：能力边界描述不够详细，环境适配未覆盖所有可能场景。
证据显示：README 结构清晰，包含安装和使用说明；命名稳定，如 CHILD_COLLECTION；提供示例和故障排除；MIT 许可证明确；但缺少版本历史和变更日志，维护责任未明确。扣分原因：无版本控制信息，维护责任未说明。
证据显示：输出可用性通过示例和演示体现；边际价值在于提供模块化架构和多种功能；成本效益通过本地 Ollama 选项降低门槛。扣分原因：未提供性能基准或成本分析。
证据显示：README 中的功能声明部分有代码支持，但未提供独立验证；跨来源佐证有限，仅依赖单一仓库；事实与推断未明确区分。扣分原因：缺乏独立验证和事实/推断分离。
- 源码中未见：回滚或恢复路径运行前先备份，或在 git 分支、快照上操作，确保改动可以撤销。
- 依赖版本固定但未提供安全审计，建议使用前进行漏洞扫描。
- 敏感数据处理未明确，若处理个人数据需额外评估。
- 无回滚机制，索引操作可能覆盖现有数据，建议备份。
- 外部效果（文件写入、向量库操作）权限未明确，需在部署环境中限制。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
New Features: 1. Quickstart Scripts & Modern uv Setup • Added start.sh (Linux/macOS) and start.bat (Windows) for one-click environment setup and launch. • Added pyproject.toml support enabling direct execution with uv run project/app.py. • Automatic fallback to standard Python venv with built-in checks for .env setup and local Ollama availability. Bug Fixes: 1. Dotted PDF Filename Preservation • Fixed an issue where filenames containing multiple dots (e.g., guide.v1.pdf and guide.v2.pdf) mapped to the same output name due to pathlib.Path.stem suffix handling. …在 GitHub 查看 ↗ -
发布说明摘录
New Features: 1. Compact Chat Memory • Added rolling conversation summary with the last two user/assistant exchanges. • Older raw messages are removed to prevent context growth. • Conversation memory is configurable through MAIN_HISTORY_MESSAGES_TO_KEEP. 2. Execution Logging • Added optional terminal logs for graph steps, routing decisions, tool calls, and outputs. • Added colored and truncated state previews for easier debugging. • Logging can be enabled from the project configuration. 3. Updated Model Defaults • Switched the default main LLM to granite4.1:8b. …在 GitHub 查看 ↗ -
发布说明摘录
New Features: 1. RAGAS Evaluation • Added dedicated evaluation.ipynb notebook to evaluate retrieval and answer quality with RAGAS metrics. • Evaluation outputs can be saved and reused without rerunning the RAG pipeline. • Added support for a separate local judge model through Ollama's OpenAI-compatible API. 2. Updated Retrieval Defaults • Switched the default embedding model to Qwen/Qwen3-Embedding-0.6B. • Updated retrieval defaults to threshold 0.4 and k=7. Bug Fixes: 1. Project Cleanup • Cleaned dependencies, generated files, and notebook outputs. …在 GitHub 查看 ↗