AI Agent / 系统课时

选择子图持久化策略

选择子图持久化策略

子图是否“记住上一次调用”会直接改变多轮行为、故障恢复能力和并发约束。本篇把 checkpointer=None、True、False 对应到一次性调用、多轮子代理和完全无状态三类需求,并用一个计数子图验证它们的实际差异。

学习目标

  • 解释三种 checkpointer 取值对应的状态寿命与恢复能力
  • 根据一次性任务、多轮子代理和无状态函数式调用选择持久化模式
  • 用同一 thread_id 验证子图是否跨调用保留私有状态

先按状态要活多久来选

最关键的问题不是“要不要存”,而是子图内部状态应该活到什么时候。一次性检索、摘要、分类等子任务通常只需要在当前调用中可恢复;多轮子代理需要在同一 thread 的后续调用中延续历史;纯计算型子图则可能完全不需要 checkpoint。

LangGraph 子图持久化策略选择流程

理解三种 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 开始。

python
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}")

预期输出

text
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。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

选择子图持久化策略

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通