KNOWLEDGE NOTE / AI · LangGraph

LangGraph(资料整编)

用 State、Node、Edge 理解 LangGraph 的状态图、控制流、持久化和中断恢复。

创建
2026年9月24日
更新
2026年10月15日

LangGraph(资料整编)

摘要

LangGraph 用图结构描述带状态的应用流程:State(状态)保存共享数据,Node(节点)执行一步逻辑,Edge(边)决定下一步。它适用于需要分支、循环、并行、持久化、人工介入或恢复执行的 Agent 与工作流。理解图运行时,比死记某个版本的 API 更重要。

1. 基本结构

  • State 描述运行当前掌握的信息,如问题、消息、检索结果、工具返回值和错误。只放后续节点需要的数据,不放密钥或无关日志。
  • Node 通常是函数或子图,读取状态、执行一步工作并返回部分更新。节点职责应清晰,外部副作用要能审计和安全重试。
  • Edge 表示固定流转或条件路由;可组成顺序、分支、并行、汇聚和循环。

2. 状态更新与图运行

节点一般返回局部更新而不直接改写全局状态。多个节点并行更新同一字段时,需要 reducer(归并函数)定义合并规则,例如追加消息,或执行自定义合并。规则错误可能导致重复或丢失数据。

课程以 superstep(超步)解释运行:运行时先安排本轮节点;被安排的节点基于本轮可见状态并行执行;全部完成后再统一合并更新进入下一轮。因此并行节点不应假设能即时读取同轮其他节点刚产生的更新。

3. 常见控制流模式

  • 固定链:步骤明确,按顺序执行。
  • Router(路由):分类后选择处理路径。
  • Parallelization(并行):互不依赖的子任务同时运行,之后汇总。
  • Orchestrator-worker(编排器—工作节点):先拆任务,再动态派发工作节点。
  • Evaluator-optimizer(评估器—优化器):检查结果,不合格时回到生成步骤,必须设置最大轮数。
  • Agent loop(智能体循环):模型提出工具调用,执行后根据结果继续,直到满足停止条件。

能用固定流程解决时优先固定流程。循环必须有步数上限、超时和错误出口,避免无限运行或成本失控。

4. 持久化与检查点

编译图时可以配置 checkpointer(检查点保存器),并用 thread_id 等会话标识保存状态快照。检查点可支持多轮状态延续、失败恢复、人工审批后继续、历史状态调试或重放。

内存检查点适合本地示例,进程重启后通常不保留;数据库后端适合持久运行,但需做好访问控制、保留期限、备份和删除。会话标识必须隔离用户,不能让一个用户读取另一个用户的检查点。

Replay(重放)按已有路径复现,Fork(分叉)从旧状态开启新路径。检查点不会自动撤销已经发生的外部副作用。

5. 中断与人工审批

动态中断可以暂停图,把待确认信息交给人,再通过恢复操作继续。适用于高风险工具审批、编辑草稿或补充信息。

  • 中断前的外部副作用在恢复时可能再次运行,要保证幂等,或把副作用放在确认之后。
  • 恢复输入要对应暂停时的状态。
  • 审批界面不是安全边界,服务端仍需检查身份与操作权限。

6. 可靠性与可观测性

  • 重试只用于可能暂时恢复的错误;非幂等操作盲目重试会重复扣款或创建。
  • 超时限制单个节点或整次流程最长运行时间。
  • 缓存只用于输入可识别、结果可复用且不会泄漏私有数据的节点。
  • 错误处理应区分可恢复错误、业务拒绝和程序缺陷。
  • 流式输出可展示状态更新、消息片段或事件;界面要区分中间结果与最终结果。
  • 子图封装可复用流程;需明确状态共享范围和是否跨调用保留。

7. Graph API 与 Functional API

Graph API 显式定义 State、Node、Edge,适合复杂分支、共享状态、并行和可视化。Functional API 用函数组织流程,适合从现有函数逐步加入持久化与恢复。选择时看流程复杂度、状态边界、调试需求和团队可读性,不必把简单脚本强行改造成图。

8. 与 LangChain 的关系

LangChain 提供模型、工具、消息和 Agent 等应用抽象;LangGraph 负责图式控制流和运行时能力。课程将 LangChain Agent 高层入口建立在 LangGraph 运行能力之上。需要精细控制节点、检查点与审批时直接设计图;简单 Agent 可从高层抽象开始。API 会变化,运行代码前核对安装版本。

9. 状态更新与运行时序

9.1 节点不是随意改写共享对象

节点接收当前状态视图并返回局部更新。运行时依据每个 State 字段的 reducer 决定如何合并。没有指定 reducer 的字段通常采用覆盖;列表、消息等累积字段需要专门的合并规则。把一个包含全部旧状态的大对象重新返回,容易无意覆盖别的节点结果。

例如 state 中 retry_count 为 1,节点返回 retry_count 为 2,覆盖规则得到 2;若 messages 字段配置追加 reducer,节点返回一条新消息会与原列表合并。若需要编辑已有消息,而不是简单追加,要使用能按消息 ID 更新的消息 reducer,否则可能出现重复历史。

并行节点同时写一个 reducer 字段时,归并顺序和并行执行顺序不能当作业务规则。涉及多写者的字段应使用可交换/可预测的归并逻辑,或让节点分别写独立字段,再由专门汇总节点解决冲突。

9.2 超步和并行语义

LangGraph 文档用 superstep(超步)描述运行阶段,概念借鉴 Pregel 消息传递:本轮被激活的节点可并行执行,完成后将更新提交到 State,再激活下一轮节点。因此:

  • 同一轮的节点读取的是本轮开始时可用的数据,不应期待读到另一个并行节点刚写出的更新。
  • Fan-out 后需要明确汇聚条件和部分失败处理;“启动两个分支”不自动意味着对两者结果按某个业务优先级合并。
  • 对同一字段的多个写入要配置 reducer;对可独立的任务尽量分字段记录。
  • 循环必须有可验证的终止条件、最大步数和超时/降级方案。

10. 控制流模式与排错示例

以“处理一条用户支持请求”为例:

  1. 接收节点保存 request_id、用户问题和来源。
  2. 分类节点产生 intent 与 confidence。
  3. 条件边按意图选择知识检索、账户查询或人工队列;未知标签进入兜底节点。
  4. 需要多个独立资料源时并行检索,之后由汇总节点去重、排序并保留出处。
  5. 答案节点只依据已授权的资料草拟回答。
  6. 置信不足或涉及账号变更时转人工;其他情况才结束并返回结果。

诊断某个分支没执行时,依次检查:路由函数实际返回值、节点名是否拼对、分支是否被加入图、输入 State 中路由字段是否存在、并行汇聚是否等待了错误的上游,以及是否触发递归/步骤上限。不要只查看最终文本;先检查各节点的状态更新和 trace。

10.1 Graph API 与 Functional API

Graph API 将状态 Schema、节点和边显式化,方便检查拓扑、并行和条件路由。Functional API 以函数为主组织程序步骤,可在较少改变原有代码结构的情况下加入持久化执行能力。两者最终都要面对检查点、错误、幂等和数据安全;选择取决于是否需要看清图拓扑和共享状态,不取决于 API 名称的新旧。

11. 状态、检查点和长期数据

11.1 三种数据层次

数据生命周期例子主要治理
临时局部变量单次节点执行网络连接对象、临时解析缓存不跨节点使用;不可序列化对象不要直接持久化
Graph State/Checkpoint一条 thread 的流程生命周期当前消息、分类结果、待审批草稿授权访问、保留策略、敏感字段最小化
Store 或业务数据库可跨 thread 和请求用户偏好、工单、业务配置租户隔离、业务主键、审计和删除流程

Checkpoint(检查点)保存一条流程在特定时刻的状态,便于继续、恢复、检查历史或从旧状态开启新路径。它不是“全局记忆”,也不是数据库事务日志。

Store 保存由应用定义的长期数据,适合跨会话复用。LangGraph 官方文档将 checkpointer 与 store 区分为 thread-scoped(线程范围)短期流程状态和跨线程的长期数据;实际项目也可以让业务数据库承担权威数据源,不需要把所有数据都塞进 Store。

11.2 thread_id 不是身份认证

thread_id 只是流程状态的定位标识。若客户端可以任意指定别人的 thread_id,而服务端直接恢复执行或读取 checkpoint,就可能形成跨用户数据泄漏。因此每次访问前都要:

  1. 从已验证的登录会话取得当前用户 ID,不接受客户端自报身份。
  2. 在服务端检查 thread_id 与当前用户/租户的所有权关系。
  3. 对恢复命令检查当前可执行操作和审批权限。
  4. 对状态里保存的敏感内容做最小化、加密/访问控制和生命周期清理。

11.3 私有 Schema 与流式数据泄露

输入 Schema、输出 Schema 和内部 Schema 可以帮助限制图的边界,但“内部字段不出现在 invoke 最终输出”不代表它不会通过调试/流式接口泄露。官方 Graph API 文档特别提醒,全状态 values 流可能包含内部私有频道;需要限制 output keys 或只流式输出受控字段。不要把内部 Schema 理解为数据脱敏功能。

12. Interrupt 与恢复的真实执行语义

一个中断流程必须保存可恢复状态,并在恢复时指向同一个 thread。中断值是发给外部调用方的暂停说明;恢复值会成为节点中 interrupt 调用的返回值。它可支持审批、编辑草稿、补齐字段和确认工具调用。

特别重要:LangGraph 当前官方文档说明,节点恢复时会从含 interrupt 的节点开头重新执行。中断前执行过的代码也会再跑。因此外部副作用要放在中断后,或使用幂等键和已执行状态检查。

安全的审批流程不是“前端点了通过就执行”,还应做到:

  • 待审批内容先形成不可混淆的摘要或版本号。
  • 审批身份、资源归属和操作权限由服务端验证。
  • 实际执行参数必须与审核时展示的参数一致。
  • 通过后执行端再次检查状态并应用幂等约束。
  • 拒绝、超时、重复审批和审批期间内容变化都有明确分支。

Static Breakpoint(静态断点)适合开发调试;依赖业务条件的暂停与人工审批应建模为业务中断,且都不取代服务端授权。

13. 可靠运行:重试、副作用、流式与子图

13.1 重试与幂等

重试只针对确实可能暂时恢复的故障,如短暂网络错误或限流。权限拒绝、Schema 错误和程序缺陷通常不应原样重试。发送邮件、创建工单、付款等副作用应有幂等键;“图状态只保存一次”不代表外部 API 只执行一次。

13.2 流式执行

常见流模式可能提供完整状态 values、每个节点更新 updates、模型消息片段 messages,或执行调试事件;准确名称、事件形状和版本参数会变化。选择流模式之前先回答:前端是否只需要最终答案?哪些中间字段可见?是否包含私密状态或工具参数?如何处理任务失败、中断和取消?

界面应区分中间输出与最终答案,不将“已经输出一个 token”显示成任务已经完成。完整状态快照更适合可信调试环境,不宜直接转发给不受信任的浏览器。

13.3 子图

子图能把一段流程封装为可复用组件;通过父图节点调用或把子图直接嵌入父图,具体共享状态和检查点命名空间行为因用法/版本而异。跨图需要长期共享的事实宜存入明确的 Store/业务数据层,不要假设子图内部状态会自动同步给所有上游节点。

14. 常见错误及其表现

现象可能原因检查/修复
列表越跑越重复reducer 追加,重试或恢复重复写入去重键、幂等更新或消息 ID 语义
并行节点互相看不到结果误把同一超步当成顺序执行加汇聚节点,明确下一轮读取时机
恢复审批后前置操作重复中断节点从开头重跑将副作用移到 interrupt 后或幂等
进程重启后没有状态使用内存 checkpointer改用持久实现并配置备份/保留
用户读到别人的会话把 thread_id 当成授权凭据服务端校验用户、租户、线程所有权
私有字段出现在流里全状态 values/debug 事件被直接暴露输出字段白名单、服务端投影和脱敏
Agent 一直循环路由永远回到原节点,没有预算/退出条件增加步数上限、超时和部分结果兜底
重放后外部对象再次创建checkpoint 不回滚外部系统使用业务幂等键、唯一约束和审计

15. 来源交叉核对与版本提示

课程材料对 State、Node、Edge、控制流、持久化、人机协同和工具节点提供了很多 Python 示例。本笔记保留稳定概念,并将运行时细节与版本相关调用方式分开;任何 API 名称、流式事件和类型注解都应对照项目当前锁定版本验证。

同目录的 05-LangGraph高级特性.md 与 05-LangGraph高级特性_backup.md 的 SHA-256 不同,文件长度也不同,不能声称完全重复。两者在流式和子图主题有大量相同结构;本轮以主文件为主要依据,仅交叉核对备份的相关章节,不删除、覆盖或公开原始资料。

官方参考:

相关笔记

  • LangChain(资料整编)
  • Agent、MCP与Skill
  • RAG检索增强生成
  • 评测幻觉与多模态
  • Prompt与编排框架面试题库

参考资料

  • 尚硅谷 LangGraph《基础入门》《控制流与节点执行》《持久化与记忆管理》。
  • 尚硅谷 LangGraph《中断与工具与部署》《高级特性》。
  • 同目录主文件和备份文件不是字节级重复;本稿以主文件为主,并把备份作为补充核对来源,不删除原始文件。
  • 课程示例中的连接密码、API Key 和环境配置未复制到公开笔记。

原始来源文件

以下列出本篇整理所依据的代表性原件;同主题重复版本与完整状态请查阅 source-manifest.csv。

  • Raw sources/尚硅谷LangGraph/1、笔记/1.笔记/01-LangGraph基础入门.md
  • Raw sources/尚硅谷LangGraph/1、笔记/1.笔记/02-LangGraph控制流与节点执行.md

放弃未保存的修改?

有未保存的修改,离开会丢失这些内容。