【干货收藏】基于LangGraph的多代理RAG系统，程序员必备技能

最新推荐文章于 2025-10-09 10:24:23 发布

原创最新推荐文章于 2025-10-09 10:24:23 发布 · 1k 阅读

CC 4.0 BY-SA版权

文章标签：

这篇文章介绍了基于LangGraph构建的多代理RAG研究工具，专为解决复杂问题设计。该工具融合混合搜索与重排序技术，具备智能路由、任务分步规划、自我纠正等功能。通过查询分析、研究计划生成、文档检索、答案生成和幻觉检查等完整工作流程，有效解决传统RAG的局限性。测试表明，该系统能准确处理复杂多步骤查询，降低幻觉风险，为企业级应用提供可靠解决方案。

一、朴素 RAG 与主动式 RAG 的对比

在本项目中，传统的朴素 RAG 方法难以满足需求，核心局限体现在以下三方面：

复杂查询理解能力不足

：无法将复杂问题拆解为多个可执行的子步骤，仅能对查询进行单层级处理，无法通过分步分析形成统一结论。
缺乏幻觉与错误处理机制

：朴素 RAG 流程中没有响应验证环节，也不具备处理幻觉内容的能力，无法通过重新生成内容来修正错误输出。
不支持动态工具调用

：无法根据工作流场景灵活调用外部 API、第三方工具或与数据库交互，功能扩展性受限。

为解决上述问题，我们构建了多代理 RAG 研究系统。基于代理的框架具备以下核心优势：

智能路由与工具调用

：通过路由代理对用户查询进行分类，将流程导向适配的节点或工具。例如，可根据上下文判断是否需要生成文档总结、是否需补充信息，或识别超出范围的问题并直接响应。
复杂任务分步规划

：针对复杂查询，自动拆解为更小的子步骤，形成清晰的执行路径。以 “对比文档中两个不同部分” 为例，代理会先识别对比需求，分别检索对应信息源，再将结果整合为对比分析结论。
反思与错误修正

：除基础响应生成外，增加验证环节以排查幻觉内容、逻辑错误或未覆盖的查询要点。同时支持人机协同，将人工输入融入自动化流程，大幅提升企业场景下的可靠性（企业应用中 “可靠性” 是核心诉求）。
全局状态共享

：AgentWorkflow 机制实现全局状态共享，简化多步骤间的状态管理，确保多代理协作各阶段的一致性。

二、项目整体架构

该工具的工作流程分为五大核心步骤，各步骤环环相扣形成完整闭环：

查询分析与路由（自适应 RAG）
首先对用户查询进行分类并路由至对应节点：若查询符合处理范围，进入 “研究计划生成” 环节；若信息不完整，触发 “请求补充信息”；若查询超出领域，则直接返回拒绝响应。
研究计划生成
根据查询复杂度，自动生成一步或多步的研究计划，输出具体的执行步骤列表，明确解决问题的路径。
研究子图执行
针对研究计划中的每个步骤，调用专用子图处理：

第一步：通过 LLM 生成 2 个关联查询（扩大检索覆盖范围）；
第二步：利用集成检索器（融合相似度搜索、BM25、MMR 三种算法）检索相关文档；
第三步：通过 Cohere 重排序进行上下文压缩，最终筛选出该步骤下 Top-K 相关文档及对应的相关性分数。

答案生成
基于检索到的相关文档，通过 LLM 生成初步答案。
幻觉检查（人机协同自我纠正 RAG）
增设反思环节：系统分析生成的答案是否有上下文支撑、是否覆盖查询全部要点。若检查失败，流程中断并提示用户：可选择生成修订版答案，或终止当前流程。

此外，向量存储的构建采用 “段落级分块” 策略：通过 Docling 与 LangChain 工具处理文档，最终基于 ChromaDB 构建向量数据库。

三、向量数据库构建流程

向量数据库是 RAG 系统的核心数据底座，其构建分为 “文档解析” 与 “向量存储搭建” 两个阶段。

3.1 文档解析

对于包含复杂表格、特殊布局的 PDF 文档，解析工具的选择直接影响数据准确性 —— 多数传统库在处理此类文档时易出现格式错乱、内容丢失问题。因此，本项目选用开源库Docling，其核心优势包括：

多格式支持：可读取并导出 PDF、DOCX、PPTX、XLSX、图像、HTML、AsciiDoc、Markdown 等主流格式；
高精度解析：能精准识别 PDF 中的表格结构、文本阅读顺序及页面布局，保留原始格式信息；
扫描件处理：支持扫描版 PDF 的 OCR 识别，覆盖更多文档类型。

文档解析实操

首先将 PDF 转换为 Markdown 格式（为后续段落分块做准备），核心代码如下：

from docling.document_converter import DocumentConverter

logger.info("开始文档处理。")
converter = DocumentConverter()
markdown_document = converter.convert(source).document.export_to_markdown()

转换后的文本会保留原始 PDF 的格式（如表格结构），随后通过MarkdownHeaderTextSplitter按标题层级分块，最终生成包含 332 个 LangChain Document 对象的列表，代码如下：

from langchain_text_splitters import MarkdownHeaderTextSplitter

# 定义按标题分块的规则
headers_to_split_on =[
("#","一级标题"),
("##","二级标题")
]

markdown_splitter = MarkdownHeaderTextSplitter(headers_to_split_on)
docs_list = markdown_splitter.split_text(markdown_document)

# 输出示例（文档列表及长度）
# [Document(metadata={'二级标题': '首席可持续发展官和高级副总裁关于学习和可持续性的信件'}, page_content="...."), ...]
# len(docs_list): 332

3.2 向量存储构建

向量存储的核心作用是将分块后的文档转换为向量嵌入并存储，以便后续快速检索。本项目选用 Chroma 作为向量数据库，并将其持久化到本地db_vector目录，核心代码如下：

from langchain_community.vectorstores import Chroma
from langchain_openai import OpenAIEmbeddings

# 初始化OpenAI嵌入模型
embd = OpenAIEmbeddings()

# 从文档列表构建向量存储
vectorstore_from_documents = Chroma.from_documents(
    documents=docs_list,
    collection_name="rag-chroma-google-v1",# 集合名称
    embedding=embd,# 嵌入模型
    persist_directory='db_vector'# 本地持久化路径
)

四、主图（Main Graph）构建

系统包含 “主图” 与 “研究员子图” 两个核心图结构：

研究员子图

：负责生成多组查询，从向量数据库中检索文档并完成重排序，输出 Top-K 相关文档；
主图

：管控整体工作流，包括查询分析、研究计划生成、答案生成、幻觉检查等核心环节。

4.1 核心概念：图状态（Graph State）

LangGraph 的核心是 “状态”—— 每次图执行都会创建一个状态，在各节点间传递并通过节点返回值更新。本项目定义了两类状态类与两种核心数据结构：

1. 核心数据结构

Router（路由器）

：对用户查询进行分类，结果包含logic（分类逻辑）与type（分类类型，取值为"more-info"“需补充信息”、"environmental"“环境相关”、"general"“通用问题”）。
```
from pydantic import BaseModel, Field
from typing import Literal, TypedDict

class Router(TypedDict):
"""对用户查询进行分类"""
    logic:str
type: Literal["more-info","environmental","general"]
```

GradeHallucinations（幻觉分级）

：用二进制分数标识答案是否存在幻觉，binary_score取值为"1"（无幻觉）或"0"（有幻觉）。

class GradeHallucinations(BaseModel):
"""生成答案中是否存在幻觉的二进制分数"""
    binary_score:str= Field(
        description="答案是否基于事实，'1' 或 '0'"
)

2. 状态类

InputState（输入状态）

：存储用户与代理的交互消息列表，对外提供窄接口。
AgentState（代理状态）

：继承 InputState，扩展核心业务字段，包括router（查询分类结果）、steps（研究计划步骤）、documents（检索到的文档列表）、hallucination（幻觉检查结果）。

from dataclasses import dataclass, field
from typing import Annotated
from langchain_core.documents import Document
from langchain_core.messages import AnyMessage
from langgraph.graph import add_messages
from utils.utils import reduce_docs  # 自定义文档合并工具

@dataclass(kw_only=True)
class InputState:
"""表示代理的输入状态，存储消息交互记录"""
    messages: Annotated[list[AnyMessage], add_messages]# 消息列表，支持自动合并

@dataclass(kw_only=True)
class AgentState(InputState):
"""检索图/代理的完整状态"""
    router: Router = field(default_factory=lambda: Router(type="general", logic=""))# 默认通用类型
    steps:list[str]= field(default_factory=list)# 研究步骤列表
    documents: Annotated[list[Document], reduce_docs]= field(default_factory=list)# 检索文档列表（自动去重合并）
    hallucination: GradeHallucinations = field(default_factory=lambda: GradeHallucinations(binary_score="0"))# 默认无幻觉

4.2 节点实现：查询分析与路由

该环节包含两个核心函数：analyze_and_route_query（分析查询并更新 Router 状态）与route_query（根据分类结果确定下一步节点）。

1. 分析查询并分类

通过 LLM 对查询进行分类，更新 AgentState 中的router字段，代码如下：

from langchain_openai import ChatOpenAI
from typing import cast
import logging

async def analyze_and_route_query(
    state: AgentState,*, config: RunnableConfig
)->dict[str, Router]:
"""分析用户查询并确定路由方向"""
# 初始化GPT-4o模型
    model = ChatOpenAI(model=GPT_4o, temperature=TEMPERATURE, streaming=True)
# 构造系统提示与对话历史
    messages =[{"role":"system","content": ROUTER_SYSTEM_PROMPT}]+ state.messages
    logging.info("---ANALYZE AND ROUTE QUERY---")
# 调用模型并返回结构化结果（Router类型）
    response = cast(
        Router,await model.with_structured_output(Router).ainvoke(messages)
)
return {"router": response}# 更新router状态

2. 路由决策

根据router.type的值，将流程导向不同节点，代码如下：

def route_query(
    state: AgentState,
)-> Literal["create_research_plan","ask_for_more_info","respond_to_general_query"]:
"""根据查询分类确定下一步节点"""
    _type = state.router["type"]
if _type =="environmental":# 环境相关查询：生成研究计划
return"create_research_plan"
elif _type =="more-info":# 需补充信息：请求用户补充
return"ask_for_more_info"
elif _type =="general":# 通用问题：直接响应
return "respond_to_general_query"
else:
raise ValueError(f"未知路由器类型 {_type}")

示例：查询 “检索都柏林 2019 年的数据中心 PUE 效率值” 的分类结果：

{
"logic":"这是一个关于2019年都柏林数据中心环境效率的具体问题，与环境报告相关。",
"type":"environmental"  # 导向“生成研究计划”节点
}

4.3 节点实现：补充信息与通用响应

针对 “需补充信息” 和 “通用问题” 两种场景，分别实现ask_for_more_info与respond_to_general_query函数，直接通过 LLM 生成响应并更新消息列表。

1. 请求补充信息

from langchain_core.messages import BaseMessage

async def ask_for_more_info(
    state: AgentState,*, config: RunnableConfig
)->dict[str,list[BaseMessage]]:
"""生成请求用户补充信息的响应"""
    model = ChatOpenAI(model=GPT_4o_MINI, temperature=TEMPERATURE, streaming=True)
# 嵌入分类逻辑到系统提示
    system_prompt = MORE_INFO_SYSTEM_PROMPT.format(logic=state.router["logic"])
    messages =[{"role":"system","content": system_prompt}]+ state.messages
# 生成响应
    response =await model.ainvoke(messages)
return {"messages":[response]}# 更新消息列表

2. 通用问题响应

async def respond_to_general_query(
    state: AgentState,*, config: RunnableConfig
)->dict[str,list[BaseMessage]]:
"""生成通用问题的响应（非环境相关）"""
    model = ChatOpenAI(model=GPT_4o_MINI, temperature=TEMPERATURE, streaming=True)
# 嵌入分类逻辑到系统提示
    system_prompt = GENERAL_SYSTEM_PROMPT.format(logic=state.router["logic"])
    logging.info("---RESPONSE GENERATION---")
    messages =[{"role":"system","content": system_prompt}]+ state.messages
# 生成响应
    response =await model.ainvoke(messages)
return {"messages":[response]}

示例：查询 “阿尔塔穆拉的天气怎么样？” 的处理结果：

分类结果：{"logic":"阿尔塔穆拉的天气怎么样？","type":"general"}
响应内容：“感谢您的提问，但我无法提供有关天气的信息。我的重点是环境报告。如果您有任何与此主题相关的问题，请告诉我，我将很乐意帮助！”

4.4 节点实现：创建研究计划

当查询分类为"environmental"时，流程进入 “创建研究计划” 节点，通过 LLM 生成分步执行计划，更新 AgentState 中的steps字段，代码如下：

async def create_research_plan(
    state: AgentState,*, config: RunnableConfig
)->dict[str,list[str]|str]:
"""为环境相关查询生成分步研究计划"""
# 定义计划的结构化输出格式（仅包含steps列表）
class Plan(TypedDict):
        steps:list[str]

    model = ChatOpenAI(model=GPT_4o_MINI, temperature=TEMPERATURE, streaming=True)
# 构造系统提示（含研究计划生成规则）与对话历史
    messages =[{"role":"system","content": RESEARCH_PLAN_SYSTEM_PROMPT}]+ state.messages
    logging.info("---PLAN GENERATION---")
# 调用模型生成结构化计划
    response = cast(Plan,await model.with_structured_output(Plan).ainvoke(messages))
# 更新steps状态，并清空历史documents（避免干扰新研究）
return {"steps": response["steps"],"documents":"delete"}

示例：查询 “检索都柏林 2019 年的数据中心 PUE 效率值” 的研究计划：

{
"steps":["查找2019年在都柏林的数据中心的PUE（能源使用效率）效率值。"]  # 单步骤计划
}

4.5 节点实现：执行研究（调用研究员子图）

conduct_research函数负责执行研究计划的第一步：调用研究员子图获取相关文档，同时移除已完成的步骤（更新steps列表），代码如下：

async def conduct_research(state: AgentState)->dict[str, Any]:
"""执行研究计划的第一步，调用研究员子图检索文档"""
# 调用研究员子图（传入当前步骤作为question）
    result =await researcher_graph.ainvoke({"question": state.steps[0]})
    docs = result["documents"]# 获取子图返回的文档列表
    step = state.steps[0]
    logging.info(f"\n共检索到{len(docs)}份文档用于执行步骤：{step}.")
# 更新documents状态（添加新检索文档），并移除已完成的步骤
return {"documents": result["documents"],"steps": state.steps[1:]}

4.6 研究员子图（Researcher Subgraph）构建

研究员子图是文档检索的核心，负责 “生成多组查询→检索文档→重排序” 的完整流程，其结构与状态定义如下：

1. 子图状态定义

from dataclasses import dataclass, field
from typing import Annotated
from langchain_core.documents import Document
from utils.utils import reduce_docs

@dataclass(kw_only=True)
class QueryState:
"""子图中“检索文档”节点的私有状态，仅存储当前查询"""
    query:str

@dataclass(kw_only=True)
class ResearcherState:
"""研究员子图的完整状态"""
    question:str# 主图传递的研究步骤（即当前需解决的子问题）
    queries:list[str]= field(default_factory=list)# 生成的多组查询
    documents: Annotated[list[Document], reduce_docs]= field(default_factory=list)# 检索并重排序后的文档

2. 节点 1：生成多组查询

基于研究步骤（question）生成多组多样化查询，扩大检索覆盖范围，代码如下：

async def generate_queries(
    state: ResearcherState,*, config: RunnableConfig
)->dict[str,list[str]]:
"""基于研究步骤生成多组搜索查询"""
class Response(TypedDict):
        queries:list[str]

    logger.info("---GENERATE QUERIES---")
    model = ChatOpenAI(model="gpt-4o-mini-2024-07-18", temperature=0)# 低温度保证查询准确性
# 系统提示：明确生成“多样化、精准”的查询
    messages =[
{"role":"system","content": GENERATE_QUERIES_SYSTEM_PROMPT},
{"role":"human","content": state.question},
]
    response = cast(Response,await model.with_structured_output(Response).ainvoke(messages))
    queries = response["queries"]
    queries.append(state.question)# 将原始步骤也加入查询列表（避免遗漏）
    logger.info(f"查询：{queries}")
return {"queries": response["queries"]}

示例：研究步骤 “检索都柏林 2019 年的数据中心 PUE 效率值” 生成的查询：

{
"queries":[
"查找2019年在都柏林的数据中心的PUE（能源使用效率）效率值。",
"都柏林2019年数据中心PUE效率值",
"都柏林2019年数据中心能源使用效率统计"
]
}

3. 节点 2：检索并重排序文档

文档检索环节采用 “集成检索器 + Cohere 重排序” 的两阶段策略，确保检索准确性：

（1）集成检索器（Ensemble Retriever）

融合三种检索算法的优势，通过 “逆秩融合”（Reciprocal Rank Fusion）合并结果，代码如下：

from langchain.retrievers import BM25Retriever, EnsembleRetriever
from langchain_community.vectorstores import Chroma
from langchain_openai import OpenAIEmbeddings

# 1. 初始化向量存储（复用之前构建的Chroma）
def _setup_vectorstore()-> Chroma:
    embeddings = OpenAIEmbeddings()
return Chroma(
        collection_name=VECTORSTORE_COLLECTION,
        embedding_function=embeddings,
        persist_directory=VECTORSTORE_DIRECTORY
)

vectorstore = _setup_vectorstore()

# 2. 定义三种基础检索器
TOP_K =5# 每个检索器返回Top-5文档
ENSEMBLE_WEIGHTS =[0.4,0.3,0.3]# 权重分配

retriever_bm25 = BM25Retriever.from_documents(docs_list, search_kwargs={"k": TOP_K})# 关键词检索（BM25）
retriever_vanilla = vectorstore.as_retriever(search_type="similarity", search_kwargs={"k": TOP_K})# 相似度检索
retriever_mmr = vectorstore.as_retriever(search_type="mmr", search_kwargs={"k": TOP_K})# 多样性检索（MMR）

# 3. 构建集成检索器
ensemble_retriever = EnsembleRetriever(
    retrievers=[retriever_vanilla, retriever_mmr, retriever_bm25],
    weights=ENSEMBLE_WEIGHTS,
)

（2）Cohere 重排序（Reranking）

第一阶段检索到的文档可能存在相关性偏差，通过 Cohere 重排序模型对文档进行二次筛选，保留 Top-2 最相关文档，代码如下：

from langchain.retrievers.contextual_compression import ContextualCompressionRetriever
from langchain_cohere import CohereRerank

# 初始化Cohere重排序器（保留Top-2文档）
compressor = CohereRerank(top_n=2, model="rerank-english-v3.0")

# 构建“集成检索器+重排序”的压缩检索器
compression_retriever = ContextualCompressionRetriever(
    base_compressor=compressor,
    base_retriever=ensemble_retriever,
)

（3）检索并重排序函数

async def retrieve_and_rerank_documents(
    state: QueryState,*, config: RunnableConfig
)->dict[str,list[Document]]:
"""根据查询检索文档，并通过Cohere重排序"""
    logger.info("---RETRIEVING DOCUMENTS---")
    logger.info(f"检索过程中的查询：{state.query}")

# 调用压缩检索器（集成检索+重排序）
    response = compression_retriever.invoke(state.query)

return {"documents": response}

示例：查询 “检索都柏林 2019 年的数据中心 PUE 效率值” 的检索结果：

[
    Document(metadata={'Header 2':'Endnotes','relevance_score':0.27009502}, page_content="- 1 这个计算基于..."),
    Document(metadata={'Header 2':'数据中心电网区域CFE','relevance_score':0.20593424}, page_content="2023  \n| 国家...")
]

4. 子图编译

通过StateGraph定义子图的节点与边，形成 “生成查询→并行检索→输出文档” 的流程：

from langgraph.graph import StateGraph, START, END

# 初始化子图构建器
builder = StateGraph(ResearcherState)

# 添加节点
builder.add_node("generate_queries", generate_queries)# 生成查询
builder.add_node("retrieve_and_rerank_documents", retrieve_and_rerank_documents)# 检索并重排序

# 定义边：从START到“生成查询”
builder.add_edge(START,"generate_queries")

# 条件边：生成查询后，并行调用“检索”节点（处理多组查询）
builder.add_conditional_edges(
"generate_queries",
    retrieve_in_parallel,# 自定义并行检索逻辑（遍历queries列表，调用检索节点）
    path_map=["retrieve_and_rerank_documents"],
)

# 检索完成后，流程结束
builder.add_edge("retrieve_and_rerank_documents", END)

# 编译子图
researcher_graph = builder.compile()

4.7 节点实现：检查研究是否完成

通过check_finished函数判断研究计划是否全部执行完毕：若steps列表为空，进入 “生成最终响应” 环节；否则继续执行下一个研究步骤，代码如下：

def check_finished(state: AgentState)-> Literal["respond","conduct_research"]:
"""判断研究是否完成：无剩余步骤则响应，否则继续研究"""
iflen(state.steps or[])>0:# 有剩余步骤：继续执行研究
return"conduct_research"
else:# 无剩余步骤：生成最终响应
return "respond"

4.8 节点实现：生成最终响应

基于所有检索到的文档与对话历史，通过 LLM 生成综合答案，代码如下：

async def respond(
    state: AgentState,*, config: RunnableConfig
)->dict[str,list[BaseMessage]]:
"""根据研究结果生成最终响应"""
print("--- RESPONSE GENERATION STEP ---")
# 使用GPT-4o模型（保证答案质量）
    model = ChatOpenAI(model="gpt-4o-2024-08-06", temperature=0)
# 格式化文档（将列表转为字符串，便于LLM读取）
    context = format_docs(state.documents)
# 构造系统提示（明确基于文档生成答案，禁止幻觉）
    prompt = RESPONSE_SYSTEM_PROMPT.format(context=context)
    messages =[{"role":"system","content": prompt}]+ state.messages
# 生成响应
    response =await model.ainvoke(messages)

return {"messages":[response]}

4.9 节点实现：幻觉检查与人机协同

1. 幻觉检查

通过 LLM 分析最终响应是否有文档支撑，生成GradeHallucinations结构化结果，代码如下：

async def check_hallucinations(
    state: AgentState,*, config: RunnableConfig
)->dict[str, Any]:
"""检查响应是否存在幻觉，返回二进制分数"""
    model = ChatOpenAI(model=GPT_4o_MINI, temperature=TEMPERATURE, streaming=True)
# 系统提示：明确检查逻辑（对比响应与文档，判断是否基于事实）
    system_prompt = CHECK_HALLUCINATIONS.format(
        documents=state.documents,
        generation=state.messages[-1]# 最新生成的响应
)

    messages =[{"role":"system","content": system_prompt}]+ state.messages
    logging.info("---CHECK HALLUCINATIONS---")
# 生成结构化幻觉检查结果
    response = cast(GradeHallucinations,await model.with_structured_output(GradeHallucinations).ainvoke(messages))

return {"hallucination": response}

2. 人机协同（人工批准）

若幻觉检查结果为binary_score="0"（存在幻觉），流程中断并等待人工决策：用户可选择 “重新生成响应” 或 “终止流程”，避免自动循环或错误输出，代码如下：

from`langgraph.graph import interrupt

def human_approval(
state: AgentState,
):
“”“人机协同：根据幻觉检查结果决定是否重新生成响应”“”
_binary_score = state.hallucination.binary_score
if _binary_score ==“1”:# 无幻觉：流程结束
return"END"
else:# 有幻觉：中断流程，等待人工输入
retry_generation = interrupt(
{
“question”:“响应存在幻觉，是否重新生成？（输入’y’重新生成，其他终止）”,
“llm_output”: state.messages[-1]# 展示当前有问题的响应
}
)

if retry_generation ==“y”:# 人工选择重新生成：返回“respond”节点
print(“继续重新生成响应”)
return “respond”
else:# 人工选择终止：流程结束
return “END”`