三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

LangGraph与LangChain实战：构建多智能体RAG系统的完整指南

发布时间：2026/8/16 9:31:35 三亩地 编程学习日记
LangGraph与LangChain实战：构建多智能体RAG系统的完整指南

这类教程最值得先看的不是它覆盖了多少个技术名词，而是学完之后，你能不能真的动手搭出一个能跑起来的、有实际用处的智能体应用。很多人学了一堆概念，但一到自己动手，就卡在环境、依赖、数据流和任务编排上。

这套教程的核心价值，在于它把 LangChain、LangGraph、Agent、RAG、MCP 这几个当下最热的开发框架和概念，串成了一个从零到一、再到生产级优化的完整实战路径。它适合两类人：一是想从传统后端或数据开发转向 AI 应用开发的工程师，二是已经了解过一些 AI 模型 API 调用，但不知道如何构建复杂、稳定、可维护的智能体系统的开发者。

最关键的一点是，它不只是教你怎么调用 API，而是教你如何用 LangGraph 来设计和控制多个智能体之间的协作流程，如何用 RAG 给智能体装上“知识库”避免胡说八道，以及如何通过 MCP 这种新兴协议来扩展工具能力。下面，我就以一个过来人的视角，拆解一下如果要跟着这套教程实战，你需要关注的核心环节、避坑点以及如何验证自己的学习成果。

1. 先理清核心概念：LangChain、LangGraph、Agent、RAG、MCP 各自管什么

在动手之前，如果概念是模糊的，代码就会写得混乱。这几个词经常被混在一起讲，但它们职责不同。

LangChain更像是一个“粘合剂”和“工具箱”。它的主要作用是：

  • 标准化流程：把调用大模型、处理输入输出、连接外部工具（如搜索、数据库）的步骤，抽象成一个个可复用的“链”（Chain）。
  • 提供常用组件：比如各种文本分割器、向量化接口（Embedding）、文档加载器。你用它来快速搭建一个基于提示词（Prompt）的问答流程会很方便。
  • 管理上下文（Context）：帮助处理长文本，解决模型有限的输入长度问题。

但 LangChain 在处理需要循环、分支、多角色协作的复杂 Agent 逻辑时，会显得有点力不从心，代码容易变成“面条代码”。

LangGraph就是来解决这个问题的。你可以把它理解为在 LangChain 之上的一套“流程图”或“工作流引擎”。

  • 核心是“图”：把智能体的每个步骤（节点）和步骤之间的流转条件（边）定义清楚。比如“先让 Agent A 分析问题，如果问题是关于财务的，就转给 Agent B 处理，否则转给 Agent C”。
  • 管理状态（State）：在整个流程中，有一个全局的状态对象在节点间传递和修改，这比用一堆全局变量要清晰和可靠得多。
  • 支持循环和中断：可以实现“思考-行动-观察”的循环，直到任务完成或满足某个条件退出。这就是实现复杂 Agent 的关键。

所以，LangChain 和 LangGraph 不是二选一，而是组合使用。LangChain 提供基础的模型调用、工具封装能力；LangGraph 则用这些基础能力作为节点，来编排高级的、有状态的协作流程。

Agent（智能体）在这里是一个抽象概念，指的是能理解目标、调用工具（思考/行动）、并从结果中学习（观察）来完成任务的程序单元。一个 LangGraph 流程里，可以包含多个不同职责的 Agent。

RAG（检索增强生成）是给智能体“喂资料”的关键技术。它解决的核心问题是：大模型的知识可能过时或不包含你的私有数据，直接问它会胡编乱造（幻觉）。

  • 流程：把你的文档（PDF、Word、网页等）切片、向量化后存入向量数据库（如 Milvus、Chroma）。当用户提问时，先从向量库中检索出最相关的文档片段，和问题一起交给大模型，让它基于这些“证据”来生成答案。
  • 在教程里的角色：教程里提到的“基于LangGraph多Agent对公信贷尽职调查报告生成系统”，RAG 很可能就是用来让 Agent 能够查询内部信贷政策、企业财报等非公开文档的。

MCP（Model Context Protocol）是一个比较新的协议，可以把它看作是“工具扩展的标准化接口”。

  • 传统问题：给 Agent 开发新工具（比如连接一个内部业务系统），需要写很多适配代码，而且不同项目之间工具难以复用。
  • MCP 的思路：定义一套标准协议，任何符合 MCP 的服务（Server）都可以像插件一样，被支持 MCP 的客户端（比如某些 Agent 框架）发现和调用。教程里提到的 Figma MCP、蓝湖 MCP，就是指为 Figma、蓝湖这类设计协作平台提供了标准化的工具接口，你的智能体可以直接通过协议调用它们的功能，而不需要为每个平台写专属的爬虫或 API 封装代码。

理清了这些，你就知道教程的每一部分在解决哪个层面的问题，学习时目标会更明确。

2. 环境准备与依赖管理：避开第一个大坑

很多人卡在第一步：环境跑不起来。教程如果是2026年的，很可能基于较新的 Python 和库版本。你需要有策略地搭建环境。

2.1 核心环境清单

  • Python 版本：建议直接使用 Python 3.10 或 3.11。3.12+ 可能存在一些第三方库的兼容性问题。使用pyenv或conda管理多版本 Python 是很好的习惯。
  • 包管理工具：强烈建议使用poetry或uv。它们能更好地处理依赖冲突和锁定版本。如果教程提供了requirements.txt或pyproject.toml，就用它初始化环境。
  • 关键依赖：除了langchain,langgraph这些核心库，你一定会用到：
    • 一个大模型 SDK：如openai(用于 GPT)、anthropic(用于 Claude) 或国内模型的 SDK。注意：教程中提到的langchain支持deepseek的第几个版本，这需要你查看 LangChain 官方文档或 DeepSeek 的集成说明，确认兼容的 SDK 版本。
    • 向量数据库客户端：如pymilvus(用于 Milvus)、chromadb。
    • 文档加载器：langchain-community中包含了大量加载器（如PyPDFLoader,UnstructuredFileLoader）。
    • 嵌入模型：可以是 OpenAI 的text-embedding-3-small，也可以是开源的如BAAI/bge-small-zh-v1.5，后者需要sentence-transformers库。

2.2 依赖安装的实战建议

不要一次性安装所有依赖。按模块来：

  1. 基础骨架：先只安装langchain-core,langchain,langgraph。跑一个最简单的“Hello World”链，确认基础环境 OK。
  2. 模型接入：再安装 OpenAI 等模型 SDK，并设置好 API Key 环境变量。写一个简单的提示词链，测试模型调用是否成功。
  3. RAG 模块：接着安装文档加载器、嵌入模型库和向量数据库客户端。尝试加载一个本地 PDF，切片，生成向量，存入 Milvus 或 Chroma。
  4. 高级工具：最后再根据教程进度，引入 MCP 客户端或其他特定工具库。

这样做的好处是，一旦报错，你能快速定位是哪个模块的依赖出了问题。常见的坑点包括：

  • Protobuf 版本冲突：某些向量数据库客户端和 TensorFlow 等库可能对 protobuf 版本有要求。如果遇到ImportError相关 protobuf，尝试固定一个兼容版本，如protobuf==3.20.*。
  • CUDA 与 torch 版本不匹配：如果你使用本地部署的嵌入模型或 LLM，需要安装 PyTorch。务必去 PyTorch 官网根据你的 CUDA 版本生成安装命令，不要直接pip install torch。
  • 网络问题：下载某些大型模型文件（如 sentence-transformers）或连接海外 API 可能超时。对于模型文件，可以考虑配置镜像源或手动下载。对于 API，确保网络环境允许。

3. 从单智能体到多智能体：用 LangGraph 构建工作流

理解了概念，搭好了环境，接下来就是核心实战：如何用 LangGraph 把东西串起来。

3.1 单智能体任务拆解

不要一开始就想复杂的多 Agent 系统。先从 LangChain 构建一个单 Agent 开始：

  1. 定义工具：用@tool装饰器定义一个简单的函数，比如计算器、网络搜索（需要 API Key）、查询数据库。
  2. 创建 Agent：使用create_react_agent或类似的函数，将大模型和你定义的工具绑定。这个 Agent 的核心逻辑是“思考-行动-观察”循环。
  3. 运行测试：用一个简单问题测试，例如“北京现在的天气怎么样？”，观察 Agent 是否会正确调用搜索工具。

这个阶段，你可能会遇到：

  • 工具描述不清：模型无法理解何时该调用你的工具。需要仔细编写工具的name、description和参数args_schema。
  • 无限循环：Agent 可能陷入“思考-调用无关工具-再思考”的死循环。需要设置max_iterations参数来限制循环次数。
  • 解析错误：模型返回的内容不符合工具调用的格式（JSON）。需要检查提示词模板，并做好错误处理（try...catch）。

3.2 引入 LangGraph 实现状态管理

当单 Agent 能工作后，引入 LangGraph 来让它更健壮、更可控。

  1. 定义状态（State）：这是一个 Pydantic 模型，定义了在整个工作流中需要传递的所有数据。比如question,analysis,tools_called,final_answer。
  2. 定义节点（Nodes）：每个节点是一个函数。比如：
    • agent_node: 运行你的单智能体，更新状态中的analysis。
    • tool_node: 根据 Agent 的决定，执行具体的工具调用，更新tools_called。
    • judge_node: 判断工具返回的结果是否足够回答question，决定下一步是继续循环还是结束。
  3. 定义边（Edges）和条件流转：使用conditional_edge。例如，从agent_node出来后，如果 Agent 决定调用工具，就流向tool_node；如果决定直接回答，就流向end。
  4. 编译并运行图：graph = StateGraph(...).compile()，然后graph.invoke({"question": "你的问题"})。

关键点：LangGraph 的“图”是静态定义的（对应热词langgraph 静态循环），但执行路径是动态的。这比用if-else硬编码逻辑要清晰和强大得多。

3.3 扩展到多智能体协作

这是教程的进阶部分。多 Agent 系统的设计核心是分工和路由。

  • 分工：设计不同专长的 Agent。例如，一个“分析员”Agent 负责理解用户意图和拆解任务；一个“研究员”Agent 专精调用 RAG 知识库；一个“执行员”Agent 负责调用具体的 API 工具；一个“审核员”Agent 负责检查最终输出的质量和合规性。
  • 路由：在 LangGraph 中，可以设计一个“路由节点”。这个节点根据当前状态（比如问题的领域、复杂度），决定下一个应该激活哪个 Agent。这可以通过一个简单的分类器（甚至是用大模型本身）来实现。

教程案例“对公信贷尽职调查报告生成系统”就是一个典型的多 Agent 应用：

  1. 查询解析 Agent：理解用户要生成关于哪家公司、什么类型的报告。
  2. 数据收集 Agent：调用 RAG 从内部知识库查信贷政策，也可能通过 MCP 工具调用外部企查查 API 获取企业公开信息。
  3. 报告生成 Agent：将收集到的信息按照固定模板，生成报告草稿。
  4. 风险审核 Agent：检查报告草稿中的数据是否矛盾，风险提示是否充分。
  5. 格式整理 Agent：将最终报告输出为 Word 或 PDF 格式。

整个流程由 LangGraph 编排，状态中传递着企业名称、收集到的数据、报告草稿、审核意见等。

4. RAG 系统搭建：让智能体“有据可查”

RAG 听起来简单，但搭建一个效果好的 RAG 系统有很多细节。教程里应该会覆盖从文档处理到检索的全流程。

4.1 文档处理流水线

这是影响效果的基础，不能马虎。

  1. 加载：使用合适的DocumentLoader。对于 PDF，PyPDFLoader是基础选择，但对于复杂排版，UnstructuredFileLoader效果更好，但依赖较重。
  2. 分割：不要简单按固定字符数切割。优先尝试：
    • 递归字符分割：RecursiveCharacterTextSplitter，它会尝试按段落、句子、单词的层级来分割，尽量保证语义完整。
    • 基于标记的分割：对于代码、Markdown，使用LanguageSplitter或MarkdownHeaderTextSplitter。
    • 关键参数：chunk_size(如 500-1000)、chunk_overlap(如 100-200)。重叠部分能避免答案被切碎。
  3. 向量化：
    • 选择嵌入模型：中文场景，BAAI/bge系列是很好的开源选择。英文或双语，text-embedding-3-small效果稳定且便宜。
    • 本地部署考量：如果选开源模型，要考虑模型大小和推理速度。bge-small-zh-v1.5约 100MB，在 CPU 上也可用，适合入门。
  4. 存储：
    • Milvus：功能强大，适合生产环境，但部署稍复杂。教程中“spring boot + milvus + langchain4j 实现 rag 问答”提到了 Java 生态的集成。
    • Chroma：轻量，纯 Python，支持内存和持久化模式，非常适合开发和原型验证。注意：Chroma 的持久化路径如果设置不当，重启后数据可能丢失，务必确认persist_directory参数正确使用。

4.2 检索与生成优化

存进去之后，怎么高效准确地查出来？

  • 检索器：最基本的vectorstore.as_retriever()。可以调整search_type（如similarity相似度搜索、mmr最大边际相关性，后者在保证相关性的同时增加多样性）和search_kwargs（如k=4返回前4个片段）。
  • 重排序：初级 RAG 直接返回 top-k 片段。高级 RAG 可以引入一个“重排序”模型，对初步检索出的片段进行更精细的相关性打分，重新排序，只把最相关的几个片段送给大模型。这能显著提升答案质量，但会增加延迟。
  • 提示词工程：给大模型的提示词至关重要。必须清晰指示：“请严格根据以下上下文回答问题，如果上下文不包含答案，请说‘根据已知信息无法回答’。” 这能有效减少幻觉。

避坑点：

  • 数据预处理不干净：PDF 中的页眉页脚、无关图片的标注文字等，如果不清理，会成为噪声，影响检索精度。
  • 分割不合理：chunk_size太大，可能包含多个不相关主题；太小，可能把完整答案切碎。需要根据你的文档类型做测试。
  • “中文分句”问题：一些分割器对中文句号“。”的识别不如英文句号“.”好，可能导致句子被不合理切断。可以自定义分割符号列表。

5. MCP 集成：扩展智能体的工具能力

MCP 是让智能体能力“可插拔”的关键。教程如果涉及2026年的 MCP 开发实战，可能会教你如何创建和使用 MCP Server。

5.1 MCP 的基本使用

对于智能体开发者（客户端），使用 MCP 相对简单：

  1. 确保你的 Agent 框架（如某些支持 MCP 的 LangChain 版本或专用框架）支持 MCP 客户端。
  2. 启动或连接一个 MCP Server。例如，一个提供了“查询天气”工具的 Server。
  3. 你的 Agent 就能像调用本地函数一样，通过标准协议调用这个“查询天气”工具，无需关心 Server 是用什么语言实现的。

5.2 MCP Server 开发初探

如果你需要为自己公司的内部系统暴露工具，可能需要开发 MCP Server。核心步骤：

  1. 定义工具：明确你的 Server 提供哪些工具，每个工具的输入输出格式。
  2. 实现 Server：根据 MCP 协议规范，实现一个 HTTP 或 stdio 服务器，监听请求。请求和响应都是特定的 JSON 格式。
  3. 注册工具：在 Server 启动时，向客户端宣告自己提供的工具列表。
  4. 处理调用：当客户端发起工具调用请求时，执行相应的内部逻辑（如查询数据库、调用内部 API），并将结果按协议格式返回。

关键理解：MCP 协议类似于一个更智能、更面向 LLM 的“API 网关”或“RPC 协议”。它让工具的定义和调用标准化了。教程里提到的 Figma MCP、蓝湖 MCP，就是设计软件公司官方或社区提供的标准 Server，让你的智能体可以直接操作设计稿。

6. 面试题准备与项目复盘：从“会做”到“会讲”

教程如果包含面试题，那价值就不仅仅是技术了，更是思路的整理。面对“LangChain 和 LangGraph 区别？”“如何设计一个多 Agent 系统？”“RAG 效果不好怎么排查？”这类问题，你需要有结构化的回答。

6.1 概念辨析类问题

  • LangChain vs LangGraph：如前所述，LangChain 是组件库和链式编排，适合线性流程；LangGraph 是基于状态图的工作流引擎，适合有循环、分支、多角色的复杂 Agent。它们常结合使用。
  • Agent 架构：可以从“感知-规划-执行-学习”框架去谈，并结合 LangGraph 的节点和状态管理来解释具体实现。
  • RAG 框架：核心是“索引-检索-生成”三阶段。可以谈向量检索、图检索、混合检索等不同方案的选择。

6.2 设计类问题

  • 设计一个多 Agent 系统：遵循“单一职责-定义接口-设计路由-状态共享-错误处理”的思路。先拆分子任务，为每个任务设计专用 Agent；定义清晰的消息格式或共享状态；设计一个路由中心（可以是规则，也可以是小模型）；考虑 Agent 间通信和异常处理（如某个 Agent 失败后的重试或降级方案）。
  • 基于LangGraph多Agent对公信贷系统：这就是一个完美的设计案例。可以详细阐述你如何设计数据流、如何利用 RAG 注入知识、如何用 MCP 连接外部数据源、如何设计审核节点控制风险。

6.3 实战排查类问题

  • RAG 效果差：提供一个排查漏斗：
    1. 检索阶段：检查检索到的片段是否真的相关？可以人工评估。如果不相关，检查嵌入模型是否合适、向量索引是否构建正确、chunk_size是否合理。
    2. 生成阶段：如果检索片段相关，但答案不对。检查提示词是否明确要求“基于上下文”，上下文的格式是否清晰（如用### 上下文：包裹），模型本身的能力是否足够。
    3. 数据阶段：如果以上都 OK，回溯到数据预处理，检查文档加载和分割是否丢失或扭曲了关键信息。
  • Agent 陷入循环：检查工具描述是否清晰；检查max_iterations参数；在 LangGraph 中，可以在判断节点设置更严格的终止条件。
  • 系统速度慢：定位瓶颈。是嵌入模型计算慢（考虑量化、用小模型）？向量检索慢（考虑索引类型、硬件）？还是大模型响应慢（考虑模型规格、缓存）？

6.4 项目复盘要点

学完教程后，最好的巩固是做一个自己的小项目。复盘时问自己：

  • 目标：我做的这个智能体解决了什么问题？
  • 架构图：我能画出数据流和组件图吗？（LangGraph 的图本身就是很好的素材）
  • 技术选型理由：为什么用 Chroma 不用 Milvus？为什么用这个嵌入模型？
  • 遇到的坑：哪个问题最难解决？最后怎么解决的？（例如，处理 PDF 表格提取不准，换用了unstructured库）
  • 效果评估：如何衡量我的系统是有效的？是人工评测，还是设计了自动化测试用例？
  • 后续优化：如果时间再多点，我会在哪个环节投入？（例如，引入重排序、实现 Agent 的记忆机制、做更全面的错误处理和日志）

把这些想清楚、讲明白，无论是应对面试，还是在实际工作中推进项目，你都会更有底气。这套教程的价值，最终要体现在你能独立完成一个闭环的、可运行的智能体应用，并且能清晰地解释其中的每一个技术决策。

编程学习 学习日记 实战经验
← 返回列表