LangGraph 运行时与可靠性:状态、检查点、中断
1. 用 State、Node、Edge 描述流程
LangGraph 不只是画流程图的 UI。Graph API 把共享状态、执行节点和路由边作为程序结构,编译后交给运行时执行。它适合确定性节点与模型决策节点混合、并行汇聚、循环、持久化和人工介入等场景。
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基础入门.mdRaw sources/尚硅谷LangGraph/1、笔记/1.笔记/02-LangGraph控制流与节点执行.mdRaw sources/尚硅谷LangGraph/1、笔记/1.笔记/03-LangGraph持久化与记忆管理.mdRaw sources/尚硅谷LangGraph/1、笔记/1.笔记/04-LangGraph中断与工具与部署.mdRaw 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控制流与节点执行.mdRaw sources/尚硅谷LangGraph/1、笔记/1.笔记/03-LangGraph持久化与记忆管理.md