首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >LangGraph 进阶:检查点、中断恢复与流式

LangGraph 进阶:检查点、中断恢复与流式

原创
作者头像
老周聊架构
发布于 2026-11-17 12:42:13
发布于 2026-11-17 12:42:13
350
举报

很多人用 LangGraph,只满足于"图能跑通"。节点连起来、条件边写好,一次 invoke 拿个最终答案,觉得这就算会用。其实 LangGraph 真正值钱的地方不在画图,而在它把流程的每一步都当成可持久化、可暂停、可回放的对象来管理:Checkpointer 把状态落到外部存储,interrupt/resume 给人类留了否决权,stream_events 让前端能看着每一步流水,时间旅行让你回到任意历史节点重新跑分支。这套机制才是 Agent 能上生产的地基——没有它,你的流程只是一次性火柴,烧完即弃。

第一节:检查点——把状态交出去,别攥在手里

LangGraph 的"图"跑起来是有状态的。每一步节点的输出、累加进 State 的字段、走过的边,默认只在进程内存里转一圈。进程一挂,全没了。Checkpointer(检查点)干的事很朴素:把图运行过程中每个关键节点的状态快照,写到外部存储,内存也好、Postgres 也好,让状态与进程解耦。

它同时解决三件事:流程能暂停(不用一次跑完)、能恢复(换进程接着跑)、能重放(回到某一步再看一次)。

写起来不复杂。演示用 MemorySaver,单进程够用;生产直接上 PostgresSaver,进程崩了状态还在库里。

代码语言:python
复制
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import MemorySaver

# 进程内检查点:演示、单进程、单副本时用
builder = StateGraph(State)
# ... 加节点 / 加边 ...
graph = builder.compile(checkpointer=MemorySaver())

# 生产用 Postgres:进程挂了状态还在,多副本共享同一份
from langgraph.checkpoint.postgres import PostgresSaver
import psycopg

with psycopg.connect("postgresql://u:p@host:5432/db", autocommit=True) as conn:
    saver = PostgresSaver(conn)
    saver.setup()                       # 建表,只需跑一次
graph = builder.compile(checkpointer=saver)

# 带 thread_id 跑,状态才落得进去
cfg = {"configurable": {"thread_id": "order-9527"}}
graph.invoke({"input": "退款 200 元"}, config=cfg)

持久化不是可选项,是 Agent 上生产的硬门槛。别等线上跑飞了才想起来补。

第二节:thread_id——一次会话的身份证

Checkpointer 里可以并存成千上万条状态,靠什么区分?thread_id。它标识"一个会话"的状态槽:同一个 thread_id 反复 invoke,拿到的是同一条连续的状态;换个 thread_id,就是全新会话,互不污染。

代码语言:python
复制
cfg = {"configurable": {"thread_id": "order-9527"}}

# 第一轮:跑一半,状态被检查点存下
graph.invoke({"input": "退款 200 元"}, config=cfg)

# 第二轮:同一个 thread_id,自动从检查点续跑,
# 新节点读到的 State 已包含上一轮结果
graph.invoke({"more": "转人工复核"}, config=cfg)

# 换 id = 新会话,干干净净
graph.invoke({"input": "退款 50 元"},
             config={"configurable": {"thread_id": "order-9528"}})

# 不想重跑也能直接读当前状态
snap = graph.get_state(cfg)
print(snap.values, snap.next, snap.config)   # config 里带着 checkpoint_id

工程上几个常见用法:

  • 长对话绑定用户 把 user_id + 会话id 拼成 thread_id,用户下次回来续得上。
  • 并发隔离 每个请求独立 thread_id,天然互不串状态。
  • 审计与回放 get_state 拿到的 config 含 checkpoint_id,出事能定位到具体那一步。

一句话:thread_id 是状态的钥匙,丢了这个 id,就丢了这条会话的全部上下文。

第三节:interrupt/resume——给人类一票否决权

有些节点不能让模型自己拍板:退款、删库、发邮件、动真金白银。这类地方需要人在回路(HITL)。LangGraph 的底层支撑就是 interrupt() 和 resume()。

机制很干脆:节点执行到 interrupt(payload) 这一行,立刻暂停并把控制权交回调用方,图停在断点,状态已落检查点;外部(人也好、另一个系统也好)拿到 payload 做决定,再带着输入用 Command(resume=...) 回来,图从断点继续往下走。

代码语言:python
复制
from langgraph.types import interrupt, Command
from langgraph.graph import StateGraph

class State(TypedDict):
    amount: int
    approved: str

def draft(state):
    return {"approved": ""}

def human_check(state):
    # 跑到这里会暂停,把决策权交出去
    decision = interrupt({"prompt": f"确认退款 {state['amount']} 元?"})
    return {"approved": decision}

def execute(state):
    return {"done": state["approved"] == "yes"}

builder = StateGraph(State)
builder.add_node("draft", draft)
builder.add_node("human_check", human_check)
builder.add_node("execute", execute)
builder.add_edge(START, "draft")
builder.add_edge("draft", "human_check")
builder.add_edge("human_check", "execute")
builder.add_edge("execute", END)
graph = builder.compile(checkpointer=MemorySaver())

cfg = {"configurable": {"thread_id": "refund-1"}}
graph.invoke({"amount": 200}, config=cfg)        # 跑到 human_check 停下
# 外部拿到结果,人工确认后携带输入恢复
graph.invoke(Command(resume="yes"), config=cfg)  # 从断点继续到 execute

interrupt 是"暂停点"不是"返回",resume 是"续传"不是"重来"。图不会从头跑,它精确地从中断的那个节点后面接着走——这正是 HITL 可工程化的核心。

第四节:stream_events——别让用户干等

graph.invoke() 是黑洞:你扔进去,等很久,然后一颗"最终答案"砸出来。用户对着转圈圈干等,体验很差,也难定位卡在哪。

stream_mode="events" 把你从黑洞里救出来。它吐的是细粒度事件流:哪个节点开始了、模型吐了哪段 token、工具调用返回了什么、哪个节点结束了。前端可以边收边渲染,进度条、思考链、工具日志全都能实时上屏。

代码语言:python
复制
cfg = {"configurable": {"thread_id": "t1"}}
for chunk in graph.stream(
    {"amount": 200}, config=cfg, stream_mode="events"
):
    event = chunk["event"]          # on_chain_start / on_chat_model_stream
    name  = chunk.get("name")       # 节点或模型名
    data  = chunk.get("data", {})   # 具体载荷
    print(f"[{event}] {name} -> {data}")
    # 前端按需渲染:token 增量、工具结果、节点状态

对比一下价值:

  • 可观测 哪一步慢、哪个工具报错,事件流里一眼看出来。
  • 可中断 用户中途点取消,你立刻能停,不用等整条跑完。
  • 可渲染 思考过程、工具调用不再藏在最后,体验直接上了一个台阶。

流式不是锦上添花,是 Agent 产品能不能用的分水岭。

第五节:时间旅行——回到历史状态重新跑分支

调试 Agent 最烦的一件事:某一步走错了,但上游已经跑了十几个节点、花了十几秒、烧了几毛钱,你只想改其中一个决策重跑,不想从头来。

checkpoint_id 让这件事变简单。get_state_history 把这趟 thread 经历过的所有检查点翻出来,你挑任意一个,用它的 checkpoint_id 重新 invoke(None, config=...),图就从那个历史节点往后重跑——原路径不动,你只探索新分支。调试、A/B、假设推演全靠它。

代码语言:python
复制
cfg = {"configurable": {"thread_id": "refund-1"}}

# 把这趟会话走过的所有检查点翻出来
for snap in graph.get_state_history(cfg):
    print(snap.config["checkpoint_id"], snap.next, snap.metadata)

# 回到某个历史 checkpoint,换个分支重跑
old_cfg = {"configurable": {"thread_id": "refund-1",
                            "checkpoint_id": "1ef3a2..."}}
graph.invoke(None, config=old_cfg)   # 从这里往后重新执行

时间旅行不是炫技,是给复杂流程一个"安全试错"的旋钮:错了不用推倒重来,回到分叉点换条路再走。

第六节:反例——把状态攥在内存里,确认靠"先返回再手动调"

讲完机制,说几个我见过的真实反模式,每一条都踩过坑。

反模式一:状态全用局部变量存。 有人不接 Checkpointer,把流程状态塞进一个全局 dict 或闭包变量,靠"反正进程不挂"续命。一旦进程重启、部署、OOM、水平扩容到第二个副本,状态当场蒸发,用户做到一半被丢回起点。前面那张图里对比得很清楚——内存变量和进程同生共死,Checkpointer 才是把状态交出去的正道。

反模式二:人工确认靠"先返回结果,再手动再调一次"。 不写 interrupt(),而是在节点里直接 return,让外层代码"记住"当前进度,等人工确认后再手动调用下一步函数,并靠参数把上下文传回去。问题一大堆:

  • 状态不连续 手动传参极易漏字段,断点处的上下文靠人肉拼接,错一个就串味。
  • 无法系统化恢复 进程在"等人工"期间挂了,谁也不知道卡在哪、该传什么。
  • 不可重放不可审计 没有 checkpoint_id,事后查"当时为啥走到这"只能翻日志碰运气。

正确做法就一句话:把"暂停等人类"当成图的一等公民,用 interrupt/resume 表达,而不是在业务代码里手写一套脆弱的"半路返回"。前者是框架托底、状态进检查点、可恢复可审计;后者是自己在沙子上盖楼。

  • 别在节点里偷偷 return 等外部 那是在绕过图的执行模型,迟早还债。
  • Checkpointer 必须接 哪怕是 MemorySaver 起步,也比裸内存强一个量级。
  • HITL 用 interrupt/resume 而非"返回再调" 状态连续、可恢复、可审计三者兼得。

踩完这些坑你会明白:LangGraph 的进阶用法,本质是把"流程的可靠性"从业务代码里剥离出来,交给框架和存储去保证。你只管写节点,断点、恢复、流式、回放,框架替你兜底。

下一篇我们聊 LangGraph 的多智能体编排——怎么把多个子图拼成一条能生产用的流水线。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 第一节:检查点——把状态交出去,别攥在手里
  • 第二节:thread_id——一次会话的身份证
  • 第三节:interrupt/resume——给人类一票否决权
  • 第四节:stream_events——别让用户干等
  • 第五节:时间旅行——回到历史状态重新跑分支
  • 第六节:反例——把状态攥在内存里,确认靠"先返回再手动调"
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档