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. 控制流模式与排错示例
以“处理一条用户支持请求”为例:
- 接收节点保存 request_id、用户问题和来源。
- 分类节点产生 intent 与 confidence。
- 条件边按意图选择知识检索、账户查询或人工队列;未知标签进入兜底节点。
- 需要多个独立资料源时并行检索,之后由汇总节点去重、排序并保留出处。
- 答案节点只依据已授权的资料草拟回答。
- 置信不足或涉及账号变更时转人工;其他情况才结束并返回结果。
诊断某个分支没执行时,依次检查:路由函数实际返回值、节点名是否拼对、分支是否被加入图、输入 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,就可能形成跨用户数据泄漏。因此每次访问前都要:
- 从已验证的登录会话取得当前用户 ID,不接受客户端自报身份。
- 在服务端检查 thread_id 与当前用户/租户的所有权关系。
- 对恢复命令检查当前可执行操作和审批权限。
- 对状态里保存的敏感内容做最小化、加密/访问控制和生命周期清理。
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 不同,文件长度也不同,不能声称完全重复。两者在流式和子图主题有大量相同结构;本轮以主文件为主要依据,仅交叉核对备份的相关章节,不删除、覆盖或公开原始资料。
官方参考:
- Graph API(State、Node、Edge、Reducer 和并行执行)
- Persistence(Checkpointer 与 Store)
- Interrupts(暂停与恢复)
- Thinking in LangGraph(从业务问题设计状态图)
相关笔记
- LangChain(资料整编)
- Agent、MCP与Skill
- RAG检索增强生成
- 评测幻觉与多模态
- Prompt与编排框架面试题库
参考资料
- 尚硅谷 LangGraph《基础入门》《控制流与节点执行》《持久化与记忆管理》。
- 尚硅谷 LangGraph《中断与工具与部署》《高级特性》。
- 同目录主文件和备份文件不是字节级重复;本稿以主文件为主,并把备份作为补充核对来源,不删除原始文件。
- 课程示例中的连接密码、API Key 和环境配置未复制到公开笔记。
原始来源文件
以下列出本篇整理所依据的代表性原件;同主题重复版本与完整状态请查阅 source-manifest.csv。
Raw sources/尚硅谷LangGraph/1、笔记/1.笔记/01-LangGraph基础入门.mdRaw sources/尚硅谷LangGraph/1、笔记/1.笔记/02-LangGraph控制流与节点执行.md