KNOWLEDGE NOTE / AI · LangGraph

LangGraph 运行时与可靠性:状态、检查点、中断

用最小 Graph API 例子解释 Reducer、超步、持久化、中断恢复与副作用幂等。

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

LangGraph 运行时与可靠性:状态、检查点、中断

1. 用 State、Node、Edge 描述流程

LangGraph 不只是画流程图的 UI。Graph API 把共享状态、执行节点和路由边作为程序结构,编译后交给运行时执行。它适合确定性节点与模型决策节点混合、并行汇聚、循环、持久化和人工介入等场景。

python
from typing import Literal
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END

class State(TypedDict):
    question: str
    route: str
    answer: str

def classify(state: State):
    route = "billing" if "账单" in state["question"] else "general"
    return {"route": route}

def answer_billing(state: State):
    return {"answer": "先核对账单明细,再说明计算依据。"}

def answer_general(state: State):
    return {"answer": "根据当前资料回答;不足时说明不确定。"}

def choose(state: State) -> Literal["billing", "general"]:
    return state["route"]

builder = StateGraph(State)
builder.add_node("classify", classify)
builder.add_node("billing", answer_billing)
builder.add_node("general", answer_general)
builder.add_edge(START, "classify")
builder.add_conditional_edges("classify", choose)
builder.add_edge("billing", END)
builder.add_edge("general", END)
graph = builder.compile()
result = graph.invoke({"question": "这笔账单为什么多了?", "route": "", "answer": ""})

节点读取当前状态并返回部分更新。图 Schema 是状态契约,不代表每个节点都应读取或改写全部字段。将 question、授权上下文、私密数据和展示结果分离,能减少意外泄漏。

2. Reducer:状态更新如何合并

未配置 reducer 的字段常按覆盖更新;累积字段需要显式归并规则。例如消息列表一般应追加新消息或按消息 ID 修改,而不是把所有历史重复追加。使用 MessagesState / add_messages 等消息 reducer 时,应理解它的合并规则。

并行节点在同一个 superstep(超步)中基于本轮可见状态执行,更新在节点都结束后统一提交。两个节点同轮写入同一普通字段,不应依赖其完成先后决定业务结果。更可靠的做法是分别写 billing_candidates、policy_candidates,再由显式汇总节点做去重、排序和冲突处理。

3. 控制流模式和终止条件

  • Sequential(顺序):步骤固定,用边连接,不必让模型每步重新选择。
  • Router(路由):分类或规则选一个处理节点;未知值要有 fallback。
  • Parallel fan-out / join(并行分发与汇聚):互不依赖的任务并行,明确等待、部分失败和结果融合。
  • Orchestrator-worker(编排器—工作节点):先计划,再按计划派生任务;限制并发与总预算。
  • Evaluator-optimizer(评估—优化):设定可测标准、最大循环次数和失败出口。
  • Agent loop(智能体循环):模型可重复选择工具;限制迭代步数、调用次数、令牌和墙钟时间。

任何循环都应能回答“什么条件下一定结束?”以及“超预算后怎样保留部分结果?”不要把模型生成的 done=true 作为唯一终止保障。

4. Checkpoint 与 thread_id

Checkpointer 在图执行时保存线程状态快照,使同一线程可以延续、恢复、检查历史或从旧检查点分叉。短期状态属于 thread;跨 thread 的用户偏好、业务记录通常应放在受权限保护的 Store 或业务数据库,不要把 checkpoint 当成万能长期记忆。

本地 demo 常用内存保存器;进程重启后它通常不保留状态。生产要配置持久后端、备份、清理/保留策略、加密和访问控制。thread_id 是状态定位符,不是登录凭证:每次恢复前,服务端要确认此线程归当前用户/租户所有。

5. 中断、人机审批与副作用

interrupt 适合暂停后等待用户补充或审批,再用恢复命令继续。重要陷阱是:恢复可能从包含中断的节点开头重新执行;中断之前的代码有可能再次运行。因此不要在暂停前直接重复创建订单、扣费或发送邮件。将副作用放在已确认之后,或使用业务幂等键、唯一约束和外部事务记录。

服务端还必须在恢复时重新检查调用者身份和操作授权。界面上的“审批按钮”不是安全边界;客户端提交的恢复负载也可能被篡改。应记录审批人、对象、操作、原状态版本和审计事件。

6. 重试、故障和幂等

区分瞬时错误、业务拒绝与程序缺陷:仅对可能恢复的网络错误做有上限的指数退避;校验错误不应盲目重试。对外部写操作设计幂等键,使重复请求返回同一业务结果;checkpoint 只记图状态,不会回滚远端支付、数据库提交或邮件发送。

建议把节点设计为可观察的小单元:输入字段、输出字段、开始/结束时间、重试次数和脱敏错误码。日志和 Trace 不要把完整私密消息或 API Key 直接输出给普通用户。

7. 流式输出和子图

Streaming 可以传递完整状态、节点更新、消息 token 或自定义事件。流式 UI 应区分“中间思考/候选/工具执行状态”和“最终可交付结果”,并只推送允许展示的字段。不要默认把内部调试状态、系统提示或私密工具结果发给浏览器。

Subgraph(子图)让可复用流程组合起来,但要明确调用级状态与线程级持久化的边界。多个父节点共享一个状态子图时要避免线程标识碰撞;父子图的字段映射应显式并通过测试固定。

8. 线上排查清单

症状可能原因验证方法
节点没有运行边/路由标签不一致、状态键缺失看 trace 的实际边和路由返回值
并行结果丢失同字段无 reducer 或 reducer 覆盖记录节点更新,再测归并规则
对话没有历史未配置 checkpointer 或换了 thread_id同一配置下连续调用并检查快照
用户之间串会话客户端可指定任意 thread_id设计跨租户负向授权测试
恢复后发生重复操作中断前副作用重跑、重试不幂等用同一个幂等键故障注入测试
无限循环缺少硬上限或终止条件依赖模型强制设置最大步数/超时并测降级
内部数据泄漏到 UI流式完整状态被直接序列化服务端投影字段并做脱敏测试

9. 何时选 Graph API 或 Functional API

Graph API 明确展示 Schema、节点和边,适合复杂条件分支、并行、团队协作和需要看拓扑的系统。Functional API 更接近普通函数调用,适合已有线性/轻分支代码想逐步获得任务持久化能力。二者使用同一类运行时能力;选择依据是流程的可读性与状态边界,不是“越高级越好”。

来源依据与版本核对

  • Raw sources/尚硅谷LangGraph/1、笔记/1.笔记/01-LangGraph基础入门.md
  • Raw sources/尚硅谷LangGraph/1、笔记/1.笔记/02-LangGraph控制流与节点执行.md
  • Raw sources/尚硅谷LangGraph/1、笔记/1.笔记/03-LangGraph持久化与记忆管理.md
  • Raw sources/尚硅谷LangGraph/1、笔记/1.笔记/04-LangGraph中断与工具与部署.md
  • Raw sources/尚硅谷LangGraph/1、笔记/1.笔记/05-LangGraph高级特性.md
  • LangGraph Graph API 官方文档
  • LangGraph Persistence 官方文档
  • LangGraph Interrupts 官方文档

相关笔记

  • LangGraph(资料整编)
  • LangChain现代API与旧课件迁移
  • Agent协议边界与安全设计
  • AI应用项目设计与案例面试题库

原始来源文件

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

  • Raw sources/尚硅谷LangGraph/1、笔记/1.笔记/02-LangGraph控制流与节点执行.md
  • Raw sources/尚硅谷LangGraph/1、笔记/1.笔记/03-LangGraph持久化与记忆管理.md

放弃未保存的修改?

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