GiovanniPasq/agentic-rag-for-dummies

A modular Agentic RAG built with LangGraph — learn Retrieval-Augmented Generation Agents in minutes.

面向初学者的智能体 RAG 指南

它是什么 – 一个基于 LangGraph 构建的模块化、智能体驱动的检索增强生成（RAG）系统的最小代码示例。它展示了如何将分层文档索引、对话记忆、查询澄清和多智能体映射归约推理整合到一个可扩展的单一管道中。

核心思想

步骤 作用
文档准备 PDF 被转换为 Markdown，然后进行两次拆分：大的父块（按 Markdown 标题）用于上下文，小的子块用于精确检索。
对话记忆 滚动摘要 + 最近的对话轮次保持对话连贯，而不会使 LLM 上下文过大。
查询澄清 系统重写模糊问题，拆分多部分查询，并可暂停以向用户询问缺失的细节。
多智能体映射归约 每个子查询在自己的 LangGraph 子图（并行智能体）中运行。每个智能体搜索子块，提取对应的父块，如果结果不佳则自我纠正，并压缩上下文以保持在令牌限制内。
聚合 所有智能体的答案被合并为一个流畅的响应。

主要功能（如 README 中所列）

  • 分层索引 – 从小块中获得精确性，从大父节中获得丰富性。
  • 对话记忆 – 上下文在轮次之间持续存在。
  • 人在环中的澄清 – 系统可以在继续之前向用户请求澄清。
  • 智能体编排 – LangGraph 协调整个工作流程。
  • 映射归约并行性 – 多个子查询同时处理。
  • 自我纠正 – 当置信度低时，智能体自动重新查询。
  • 上下文压缩 – 保持工作记忆精简。
  • 可观测性 – 与 Langfuse 集成，记录 LLM 调用、工具使用和图执行。
  • 评估 – 提供一个笔记本，使用 RAGAS 指标套件对答案进行评分。

技术栈

  • Python ≥ 3.11
  • LangGraph（v1.2+）用于基于图的智能体编排
  • Qdrant 向量存储，支持混合稠密 + 稀疏搜索（稠密通过 HuggingFace 嵌入，稀疏通过 FastEmbed BM25）
  • LLM 提供商 – 默认是 Ollama（本地模型 granite4.1:8b），但代码也适用于 OpenAI、Anthropic、Google Gemini 或任何与 LangChain 兼容的聊天模型。
  • Chunky（可选）– 一个用于 PDF 转 Markdown 转换和块检查的辅助工具包。
  • Langfuse – 可选的可观测性仪表板。
  • RAGAS – 用于对检索和答案质量进行定量评估。

快速入门（高层概述）

  1. 安装依赖 – pip install -r requirements.txt（包括 LangGraph、LangChain、Qdrant 客户端等）。
  2. 设置向量数据库 – 仓库创建本地 Qdrant 实例（client = QdrantClient(path="qdrant_db")）。
  3. 添加文档 – 将 PDF 放入 docs/，运行笔记本或脚本将其转换为 Markdown（pdfs_to_markdowns）。
  4. 索引 – index_documents() 函数构建父/子块并将子块存储在 Qdrant 中；父元数据保存为 JSON 文件。
  5. 选择 LLM – 编辑 llm = ChatOllama(...) 行，或在设置相应的 API 密钥后替换为 ChatOpenAI、ChatAnthropic 等。
  6. 运行演示 – 打开 notebooks/agentic_rag.ipynb（或启动 Colab 徽章）并与聊天界面交互。
  7. 评估 – 使用 notebooks/evaluation.ipynb 计算生成答案的 RAGAS 分数。

适用人群

  • 学习者：希望获得逐步讲解智能体 RAG 管道每个组件的笔记本。
  • 开发者：寻找一个现成的、模块化的架构，可以分叉并适应自己的数据、LLM 或工具。
  • 研究人员：对尝试多智能体检索、自我纠正或混合稠密-稀疏搜索感兴趣。

优势

  • 模块化 – 每个部分（嵌入模型、向量存储、PDF 转换、智能体图）都是独立的，便于替换。
  • 提供商无关 – 可与任何 LangChain 聊天模型配合使用，不局限于单一供应商。
  • 可观测性 – 可选的 Langfuse 集成有助于调试和监控 LLM 调用。
  • 内置评估 – RAGAS 笔记本提供定量反馈。
  • 人在回路 – 查询澄清减少了由模糊提示引起的幻觉。

局限 / 待改进点

  • 需要本地 Qdrant 实例和支持 GPU 的环境来运行默认的 Ollama 模型；云替代方案需要额外设置。
  • 分层索引逻辑相当复杂；新手可能需要阅读辅助函数才能理解合并/重新平衡步骤。
  • 自我纠正阈值（RETRIEVAL_SCORE_THRESHOLD = 0.4）是硬编码的；针对不同的语料库可能需要进行调整。
  • 演示侧重于 PDF/Markdown 来源；其他文档类型需要额外的预处理代码。

快速开始代码片段

from langchain_ollama import ChatOllama
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_qdrant.fastembed_sparse import FastEmbedSparse
from qdrant_client import QdrantClient

# LLM（本地 Ollama）
llm = ChatOllama(model="granite4.1:8b", temperature=0, seed=42)

# 嵌入（稠密 + 稀疏）
emb_dense = HuggingFaceEmbeddings(model_name="Qwen/Qwen3-Embedding-0.6B")
emb_sparse = FastEmbedSparse(model_name="Qdrant/bm25")

# 向量存储
client = QdrantClient(path="qdrant_db")
# … 创建集合、索引文档，然后按照笔记本中的说明启动 LangGraph 聊天循环。

底线 – 面向初学者的智能体 RAG 指南 是一个具体、可运行的参考实现，展示了一个复杂的 RAG 系统，结合了分层分块、记忆、澄清和多智能体推理，全部基于开源工具构建。它是一个扎实的学习资源，也是构建生产级智能体检索管道的良好起点。

适用人群

  • 学习者：希望获得一个逐步讲解智能体 RAG 管道每个组件的笔记本。
  • 开发者：寻找一个现成的、模块化的架构，可以分叉并适配自己的数据、LLM 或工具。
  • 研究人员：对多智能体检索、自我纠正或混合稠密-稀疏搜索实验感兴趣。

优势

  • 模块化 – 每个组件（嵌入模型、向量存储、PDF 转换、智能体图）都是独立的，便于替换。
  • 提供商无关 – 可与任何 LangChain 聊天模型配合使用，不局限于单一供应商。
  • 可观测性 – 可选的 Langfuse 集成有助于调试和监控 LLM 调用。
  • 内置评估 – RAGAS 笔记本提供定量反馈。
  • 人在回路 – 查询澄清减少了由模糊提示引起的幻觉。

局限 / 待改进点

  • 需要本地 Qdrant 实例和支持 GPU 的环境来运行默认的 Ollama 模型；云替代方案需要额外设置。
  • 分层索引逻辑相当复杂；新手可能需要阅读辅助函数才能理解合并/再平衡步骤。
  • 自我纠正阈值（RETRIEVAL_SCORE_THRESHOLD = 0.4）是硬编码的；针对不同的语料库可能需要进行调整。
  • 演示侧重于 PDF/Markdown 来源；其他文档类型需要额外的预处理代码。

快速开始代码片段

from langchain_ollama import ChatOllama
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_qdrant.fastembed_sparse import FastEmbedSparse
from qdrant_client import QdrantClient

# LLM（本地 Ollama）
llm = ChatOllama(model="granite4.1:8b", temperature=0, seed=42)

# 嵌入（稠密 + 稀疏）
emb_dense = HuggingFaceEmbeddings(model_name="Qwen/Qwen3-Embedding-0.6B")
emb_sparse = FastEmbedSparse(model_name="Qdrant/bm25")

# 向量存储
client = QdrantClient(path="qdrant_db")
# … 创建集合、索引文档，然后按照笔记本中的说明启动 LangGraph 聊天循环。

底线 – 面向初学者的智能体 RAG 指南 是一个具体、可运行的参考实现，展示了一个复杂的 RAG 系统，结合了分层分块、记忆、澄清和多智能体推理，全部基于开源工具构建。它是一个扎实的学习资源，也是构建生产级智能体检索管道的良好起点。

SUMMARY: 一个教程风格的开源 Python 项目，展示了如何使用 LangGraph 构建模块化、智能体驱动的检索增强生成系统，包括分层分块、对话记忆、查询澄清、多智能体映射归约、自我纠正以及通过 RAGAS 进行评估。支持 Ollama、OpenAI、Anthropic、Google Gemini、Qdrant 向量存储，以及可选的 Langfuse 可观测性。

TITLE: 使用 LangGraph 构建模块化多智能体 RAG 管道 – 完整代码、笔记本和评估

相关

  • 项目
    LightningRAG/LightningRAG

    一个具备可视化代理编排画布与 Webhook 连接器，可用于将 AI 代理部署到第三方消息平台的功能全栈 RAG 框架。

  • 项目
    rag-web-ui/rag-web-ui

    一个智能对话系统，允许用户通过将自己的文档知识库与大型语言模型（LLM）结合使用检索增强生成（RAG）来构建自定义问答服务。

  • 项目
    langflow-ai/openrag

    一个由智能代理驱动的文档搜索平台，能够让用户通过聊天界面上传、处理并使用 RAG 查询文档。

  • 项目
    Marker-Inc-Korea/AutoRAG

    AutoRAG Agent 是一个基于 Node 的本地运行 RAG 系统，可将您的计算机变成一个可搜索的知识库。它使用 BM25 和内置嵌入模型索引文件（PDF、Office、HWP、图像等），支持多种外部聊天源，并以带编号引用的方式回答自然语言问题。它提供 CLI、交互式终端 UI、桌面 Electron 应用和 TypeScript 库，强调隐私（数据不离开机器）和易用性（无需设置向量数据库）。

  • 项目
    SaiAkhil066/CORTEX-AI-SUPER-RAG

    Cortex AI SUPER RAG 是一款本地、开源的 RAG 应用，可让您上传 PDF/Word 文档、以自然语言提问，并获得带有精确引用的答案。它结合了 BM25 关键词搜索、FAISS 向量搜索、可选的重排序、实体图扩展，以及多种基于 LLM 的技巧——全部可通过 Ollama 运行，无需云 API。该仓库包含 Streamlit UI、完整的评估工具（例如 FinanceBench 基准测试）以及 Docker 支持。