站点图标 高效码农

Agentic RAG终极指南：7步构建LangGraph智能问答系统

高效码农

从零搭建智能问答系统：基于LangGraph的Agentic RAG实战指南

Agentic RAG for Dummies Logo

你是否曾希望拥有一个能够理解对话上下文、在模糊时主动询问、并能像人类一样并行处理复杂问题的文档问答助手？今天，我们将深入探讨如何利用 「Agentic RAG（智能体驱动的检索增强生成）」 和 「LangGraph」 框架，构建一个生产级的智能问答系统。本文不仅是一份教程，更是一张通往下一代人机交互体验的蓝图。

为什么现有的RAG系统不够用？

在开始之前，让我们先看看大多数RAG（检索增强生成）教程的现状。它们通常演示了基础概念：上传文档，拆分文本，建立索引，然后回答问题。这听起来不错，但在实际使用中，你很快会遇到瓶颈：

  • 「上下文失忆」：每次问答都是独立的，系统无法记住你刚才问了什么，导致对话不连贯。
  • 「“垃圾进，垃圾出”」：如果问题表述模糊或有歧义，系统会试图回答，结果往往不尽人意。
  • 「非黑即白」：要么搜索极其精确但丢失上下文的小片段，要么获取大段文本但包含无关信息。
  • 「固化僵硬」：整套流程被焊死，难以根据你的具体需求（比如法律或医疗领域）进行定制。
  • 「单线程思考」：面对一个包含多个子问题的复杂查询时，系统只能线性处理，效率低下。

那么，有没有更好的解决方案？答案是肯定的。本文将介绍一个集成了「对话记忆、智能查询澄清、层次化检索和并行多智能体处理」的现代化RAG系统。它就像为你的文档库配备了一位有耐心、善思考、能同时处理多项任务的研究助理。

认识我们的核心工具：Agentic RAG与LangGraph

首先，让我们澄清几个关键概念：

  • 「RAG是什么？」 你可以把它想象成一个“开卷考试”的AI。当被问到问题时，它不是仅凭记忆（即预训练的知识）回答，而是会先去“翻阅”你提供的文档（检索），然后结合找到的信息（增强）来组织答案（生成）。
  • 「“Agentic”（智能体驱动）又是什么意思？」 这意味着系统被赋予了自主决策和行动的能力。它不再是一个被动的问答机器，而是一个能主动判断“这个问题是否清晰？”、“是否需要查阅更多上下文？”、“这个问题包含几个部分？”的智能体。
  • 「LangGraph的作用」：它是LangChain框架的一部分，专门用于构建「有状态的、多步骤的智能体工作流」。你可以把它看作是一个可视化的工作流设计器，能够清晰定义智能体思考、决策和行动的逻辑回路。

下面这张图概括了我们即将构建的系统工作流程：

系统核心：四大智能阶段揭秘

我们的智能问答系统将用户查询的处理分解为四个紧密衔接的智能阶段，下面我们逐一拆解。

阶段一：对话理解——让AI拥有“记忆力”

想象一下，你问助手：“如何安装SQL？”，得到答案后紧接着问：“那怎么更新它呢？”。一个优秀的助手应该能理解“它”指的是SQL。这就是「对话记忆」的功能。

我们的系统会持续分析对话历史，提取关键话题、提及的实体和未解决的疑问，并浓缩成一两句话的摘要。这个摘要不会机械地重复所有聊天记录，而是聚焦于核心语境，并在后续提问中被用来消除歧义。例如，将“如何更新它？”结合上下文，重写为清晰的“如何更新SQL软件？”。

阶段二：查询澄清——从“听懂问题”开始

并非所有问题生来就是清晰的。本阶段，系统像一位细心的访谈者，对用户查询进行深度分析和优化：

  1. 「解析指代」：自动将“它”、“那个东西”等代词关联到上下文中明确的实体。
  2. 「拆分复杂问题」：将“什么是JavaScript和Python？”自动拆解为“什么是JavaScript？”和“什么是Python？”两个独立查询，为并行处理做准备。
  3. 「识别模糊查询」：检测无意义、侮辱性或过于宽泛的问题。
  4. 「请求人工澄清（关键特色）」：当系统判定问题意图不清时，会「主动暂停流程」，通过界面询问用户以获取更多细节。这是“人在回路”（Human-in-the-Loop）理念的体现，能有效防止基于错误理解的无效检索。
  5. 「优化检索语句」：将口语化的问题（如“跟我讲讲区块链是啥”）改写成更适合检索的关键词丰富语句（如“区块链技术基本原理与定义”）。

阶段三：智能检索——精度与广度的双重奏

这是系统的“查找资料”环节，我们采用了一种巧妙的「层次化索引」策略和强大的「多智能体并行处理」架构。

「层次化索引：大小搭配，干活不累」
在文档预处理时，我们对每份文档做两次拆分：

  • 「父文档块」：根据Markdown标题（H1， H2， H3）划分出的大段内容。它们保留了完整的逻辑和上下文。
  • 「子文档块」：从每个父文档块中进一步切分出的、固定长度的小片段。它们小巧精确，利于搜索定位。

检索时，系统先搜索「子文档块」以获得高精度的匹配片段。如果发现信息不足，再根据子片段对应的parent_id去提取完整的「父文档块」，从而获得充足的背景信息。这就像先用搜索引擎找到相关文章的特定段落，再打开整篇文章深入阅读。

「多智能体Map-Reduce：让思考并行起来」
当阶段二识别出多个子问题（无论是用户明确提出的，还是从一个复杂问题中分解出的），系统就会启动“多智能体并行处理”模式。

利用LangGraph的 Send API，系统会为每个子问题「同时唤醒一个独立的智能体子流程」。每个智能体都独立执行完整的检索-评估-回答工作流。最后，所有智能体的答案被汇总到一个统一的回复中。

「例如」：处理“解释JavaScript和Python的异同”时，可能会并行激活两个智能体，一个专攻JavaScript，一个专攻Python，最后将两者的发现合并对比。这大大加快了处理复合型问题的速度。

阶段四：响应生成——从信息到答案

本阶段，系统综合所有检索到的信息（可能来自单个智能体，也可能来自多个并行智能体的汇总），生成一个连贯、准确且针对用户原始问题的最终答案。对于并行处理的结果，有一个专门的“聚合”节点负责融合各子答案，去重，并组织成结构清晰的回应。

动手实践：一步步构建你的智能问答系统

理论说得差不多了，让我们看看如何用代码实现它。以下是一个简化的步骤概览，完整代码可在文末提供的项目中找到。

第一步：环境与模型配置——选择你的“大脑”

系统的设计是「模型提供商无关的」。你可以根据需求自由选择“大脑”：

  • 「本地部署（推荐开发）」：使用「Ollama」运行开源模型（如qwen3:4b），完全免费，但需要本地计算资源。

    ollama pull qwen3:4b-instruct-2507-q4_K_M

    from langchain_ollama import ChatOllama
llm = ChatOllama(model="qwen3:4b-instruct-2507-q4_K_M", temperature=0)

  • 「云端API（推荐生产）」：使用「Google Gemini」、「OpenAI GPT」或「Anthropic Claude」，性能强大，按使用量计费。

    from langchain_google_genai import ChatGoogleGenerativeAI
import os
os.environ[“GOOGLE_API_KEY”] = “your-api-key”
llm = ChatGoogleGenerativeAI(model=“gemini-2.0-flash-exp”, temperature=0)

「只需更改初始化LLM的这一行代码，其余所有流程代码完全一致。」

第二步：文档处理——从PDF到知识网络

任何RAG系统的基石都是高质量的文档处理。我们的流程始于将PDF转换为结构化的Markdown文本。

def pdf_to_markdown(pdf_path, output_dir):
    # 使用PyMuPDF4LLM库进行转换
    doc = pymupdf.open(pdf_path)
    md = pymupdf4llm.to_markdown(doc)
    # ... 保存处理后的Markdown文件

转换完成后，就进入前面提到的「层次化索引」环节：

  1. 用MarkdownHeaderTextSplitter按标题切割，生成「父文档块」。
  2. 用RecursiveCharacterTextSplitter将每个父块切分为小的「子文档块」。
  3. 将所有子文档块的向量（同时包含「密集向量」用于语义理解，和「稀疏向量」用于关键词匹配）存入「Qdrant」向量数据库。
  4. 将父文档块以JSON格式保存到本地文件系统，并通过parent_id与子文档块关联。

第三步：定义智能体的“技能”——检索工具

我们为智能体装备了两个核心工具函数：

  • search_child_chunks(query)：在向量数据库中进行混合搜索，返回最相关的子文档块。
  • retrieve_parent_chunks(parent_ids)：根据子块中携带的parent_id，从文件系统中提取完整的父文档块。
@tool
def search_child_chunks(query: str， k: int = 5) -> List[dict]:
    """搜索最相关的K个子文档块"""
    # ... 调用向量数据库进行混合检索

第四步：构建智能工作流——LangGraph大显身手

这是最核心的部分。我们用LangGraph定义了两个层级的图：

「1. 智能体子图（处理单个问题）」
这是一个简单的“思考-行动”循环：

开始 -> 思考（调用LLM判断是否需要搜索）-> [如果需要工具] -> 执行工具（搜索/获取父块） -> 返回结果给思考节点 -> [如果信息足够] -> 提取最终答案 -> 结束

「2. 主控图（协调整个会话）」
这是系统的大脑中枢，流程如下：

新消息 -> 总结对话历史 -> 分析并重写查询 -> {查询清晰吗？}
         |
         |-- 不清晰 -> 暂停，等待人工澄清 -> 返回分析节点
         |
         |-- 清晰 -> 拆分为N个子问题 -> [并行发送到N个智能体子图] -> 等待所有子图完成 -> 聚合所有答案 -> 生成最终回复 -> 结束

这个架构的精妙之处在于，「并行化处理对于简单问题是可选的」。单个问题会走单智能体流程，而复杂多部分问题则会自动触发并行处理，最大化利用资源。

第五步：创建交互界面——与你的助手对话

最后，我们使用「Gradio」快速构建一个带有对话历史功能的Web界面。

import gradio as gr

def chat_with_agent(message， history):
    # 将用户消息输入LangGraph工作流
    result = agent_graph.invoke({“messages”: [HumanMessage(content=message)]}， config)
    # 返回助手的最终答复
    return result[‘messages’][-1].content

# 创建聊天界面
demo = gr.ChatInterface(fn=chat_with_agent)
demo.launch()

运行后，你将在浏览器中看到一个简洁的聊天窗口，可以与你的文档库进行智能对话了。

如何开始使用？

我们提供了三种途径，满足从快速体验到生产部署的不同需求。

方案一：快速体验（Google Colab笔记本）

最适合初学者和想快速尝鲜的用户。只需点击项目首页的“Open in Colab”徽章，按笔记本中的说明上传你的PDF文档，逐块运行代码即可。几分钟内就能看到效果。

方案二：本地开发（完整的Python项目）

如果你想深入研究、定制功能，或集成到自己的应用中，这是最佳选择。

# 1. 克隆项目
git clone https://github.com/your-repo/agentic-rag-for-dummies.git
cd agentic-rag-for-dummies

# 2. 创建虚拟环境并安装依赖
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows
pip install -r requirements.txt

# 3. 将你的PDF文档放入 `docs/` 文件夹

# 4. 运行应用
python app.py
# 然后在浏览器中打开 http://localhost:7860

方案三：Docker一键部署

适合希望快速部署或环境统一的用户。确保Docker有至少8GB的内存分配。

# 构建镜像
docker build -f project/Dockerfile -t agentic-rag .

# 运行容器
docker run --name rag-assistant -p 7860:7860 agentic-rag
# 访问 http://localhost:7860

常见问题与调优指南

在构建和使用过程中，你可能会遇到一些典型情况。这里有一个快速排查表：

遇到的现象 可能的原因 尝试的解决方案
「答案无视文档，凭空捏造」 1. LLM能力不足。
2. 系统提示词未强制要求检索。		 1. 换用更强大的模型（如7B参数以上）。
2. 检查并强化rag_agent_prompt，明确要求“必须优先搜索”。
「检索不到相关文档」 1. 查询改写偏离原意。
2. 块尺寸不合适。
3. 嵌入模型不匹配领域。		 1. 调整query_analysis_prompt，减少过度“发挥”。
2. 增大子块大小(chunk_size)以提高召回率。
3. 尝试领域专用的嵌入模型。
「答案零散，缺乏上下文」 父文档块太小，无法提供足够背景。 在document_chunker.py中增加max_parent_size。
「处理速度慢」 1. 本地模型推理慢。
2. 块过多，检索耗时。		 1. 考虑使用云端API模型。
2. 适当增加块大小，减少总块数。
「并行处理未触发」 查询分析节点未成功拆分问题。 检查get_query_analysis_prompt()中关于拆分的规则部分。

总结：你获得了什么？

通过本文的旅程，你已经不是仅仅了解了一个RAG项目，而是掌握了一套构建「下一代交互式问答系统」的模块化蓝图。这个系统的核心价值在于：

  • 「更人性化的交互」：拥有记忆，懂得澄清，对话自然流畅。
  • 「更聪明的检索」：层次化索引兼顾精度与广度，并行处理提升复杂问题解决效率。
  • 「强大的可定制性」：从LLM、嵌入模型到工作流节点，每个组件都可按需更换，轻松适配法律、医疗、技术等不同垂直领域。
  • 「生产就绪的架构」：提供了从实验笔记本到模块化项目再到Docker部署的完整路径。

技术的最终目的是服务于人。这个Agentic RAG系统所做的，正是通过让机器更理解人的意图和语境，来缩小信息与人之间的鸿沟。现在，轮到你动手，将这些模块组合起来，为你自己的知识库注入智能的灵魂了。

本文所描述的项目“Agentic RAG for Dummies”遵循MIT开源协议，所有代码均可自由用于学习和商业项目。欢迎在项目仓库中提出问题和贡献代码。

退出移动版