AI Agent / 系统课时
选择子图持久化策略
选择子图持久化策略
子图是否“记住上一次调用”会直接改变多轮行为、故障恢复能力和并发约束。本篇把 checkpointer=None、True、False 对应到一次性调用、多轮子代理和完全无状态三类需求,并用一个计数子图验证它们的实际差异。
学习目标
- 解释三种
checkpointer取值对应的状态寿命与恢复能力 - 根据一次性任务、多轮子代理和无状态函数式调用选择持久化模式
- 用同一
thread_id验证子图是否跨调用保留私有状态
先按状态要活多久来选
最关键的问题不是“要不要存”,而是子图内部状态应该活到什么时候。一次性检索、摘要、分类等子任务通常只需要在当前调用中可恢复;多轮子代理需要在同一 thread 的后续调用中延续历史;纯计算型子图则可能完全不需要 checkpoint。

理解三种 checkpointer 行为
| 子图编译方式 | 状态寿命 | interrupt / 恢复 | 典型用途 |
|---|---|---|---|
checkpointer=None 或省略 |
每次子图调用独立;当前调用可借助父图 checkpointer 持久化 | 支持 | 一次性工具调用、独立子任务 |
checkpointer=True |
同一 thread_id 下跨调用累积 |
支持 | 需要连续上下文的多轮子代理 |
checkpointer=False |
不保存子图 checkpoint | 不支持 | 纯函数式、可随时从头重算的步骤 |
None 是多数子图的默认选择。它不是“完全不持久化”,而是让每次调用从干净的子图状态开始,同时在父图具备 checkpointer 时保留单次调用内的 durable execution 能力。True 才表示子图自己的状态要沿同一 thread 延续。False 则彻底关闭子图 checkpoint。
用计数子图验证状态寿命
下面的示例给子图一个父图看不到的私有字段 calls。连续两次使用同一个 thread_id 调用父图:如果子图是 per-thread 模式,第二次会从上一次的 calls 继续累加;另外两种模式都会重新从 0 开始。
from typing import TypedDict
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import END, START, StateGraph
class ParentState(TypedDict, total=False):
delta: int
observed: int
class ChildState(TypedDict, total=False):
delta: int
calls: int
observed: int
def build_parent(mode):
def count_call(state: ChildState):
# calls 是子图私有状态;observed 只是把结果暴露给父图。
calls = state.get("calls", 0) + state.get("delta", 1)
return {"calls": calls, "observed": calls}
child_builder = StateGraph(ChildState)
child_builder.add_node("count", count_call)
child_builder.add_edge(START, "count")
child_builder.add_edge("count", END)
child = child_builder.compile(checkpointer=mode)
parent_builder = StateGraph(ParentState)
parent_builder.add_node("worker", child)
parent_builder.add_edge(START, "worker")
parent_builder.add_edge("worker", END)
# 父图提供 thread 级 checkpoint,便于比较子图三种模式。
return parent_builder.compile(checkpointer=InMemorySaver())
modes = [
("per-invocation", None),
("per-thread", True),
("stateless", False),
]
for label, mode in modes:
graph = build_parent(mode)
config = {"configurable": {"thread_id": f"demo-{label}"}}
first = graph.invoke({"delta": 1}, config)["observed"]
second = graph.invoke({"delta": 1}, config)["observed"]
print(f"{label}: {first} -> {second}")预期输出
per-invocation: 1 -> 1
per-thread: 1 -> 2
stateless: 1 -> 1这里最容易误判的是 None 与 False:两者都不会把 calls 延续到下一次调用,但前者仍可依赖父图 checkpointer 支持当前调用内的中断和恢复,后者没有这层能力。
把模式和协作方式一起设计
一次性子代理通常选 None,既保留 durable execution,又避免旧状态污染下一次任务。需要连续对话、逐轮积累研究材料或长期推进同一局部任务的子代理,才选 True,并确保后续调用复用相同 thread_id。
True 还会带来更强的命名空间和调用约束。同一个持久化子图实例如果在同一父节点中被重复或并行调用,可能争用同一 checkpoint namespace;这种“一次节点里多次调用同一子图”的模式优先改为 per-invocation,或把不同子代理包装成具有稳定唯一节点名的独立子图。
只有当子图完全可以从输入重算,而且不需要中断、恢复、历史检查时,False 才是合适的简化。持久化策略本质上是在确定子图状态的生命周期:默认先选 None,确认存在跨调用记忆需求再升级为 True,确认连单次恢复都不需要时才降为 False。