AI Agent / 系统课时

持久化线程并验证断点恢复

持久化线程并验证断点恢复

这一节把“能继续跑”变成可验证的工程能力:用持久化 checkpointer 保存工单线程,在进程退出后以同一个 thread_id 恢复,并同时检查图状态与外部副作用,避免只恢复了状态却重复执行通知、扣费等动作。

学习目标

  • 为 LangGraph 工单图接入磁盘持久化 checkpointer,并理解 thread_id 的恢复作用
  • 模拟两个独立进程之间的断点续跑,验证恢复后的状态与下一节点
  • 用幂等键约束外部副作用,识别 checkpoint 与 exactly-once 副作用之间的边界

可恢复线程必须同时满足三个条件

LangGraph 的 checkpoint 保存的是图执行状态和待执行位置。要让一个工单在进程重启后继续,至少要同时满足:checkpointer 本身跨进程持久化、恢复时继续使用原来的 thread_id、节点依赖的外部副作用能够安全重试。

thread_id 可以理解为一条工作流实例的稳定身份。新进程重新编译同一张图后,只要连接同一个 checkpoint 存储并传入相同的 thread_id,就能读取该线程最近一次已提交的状态。若改了 thread_id,系统会把它视为另一条独立线程。

工单线程从中断到恢复的状态与副作用链路

构造可跨进程恢复的工单图

下面使用文件型 SQLite checkpointer 演示跨进程恢复。prepare 节点只更新图状态;close_ticket 模拟外部通知,并用唯一 effect_key 写入另一份 SQLite 表,从而把副作用是否重复变成可检查的数据。

首次演练应在没有 checkpoints.sqlite 和 effects.sqlite 的空目录中运行。需要预先安装 langgraph 与 langgraph-checkpoint-sqlite。下面脚本是完整可运行示例,保存为 ticket_graph.py。

python
from __future__ import annotations

import argparse
import sqlite3
from typing import NotRequired, TypedDict

from langgraph.checkpoint.sqlite import SqliteSaver
from langgraph.graph import END, START, StateGraph

CHECKPOINT_DB = "checkpoints.sqlite"
EFFECT_DB = "effects.sqlite"
THREAD_ID = "ticket-1001"

class TicketState(TypedDict):
    ticket_id: str
    status: NotRequired[str]
    side_effect_key: NotRequired[str]

def prepare(state: TicketState) -> dict:
    return {
        "status": "prepared",
        "side_effect_key": f"notify:{state['ticket_id']}",
    }

def write_effect_once(effect_key: str, payload: str) -> bool:
    # 外部副作用单独持久化,并用主键把重复执行压成一次写入。
    with sqlite3.connect(EFFECT_DB) as conn:
        conn.execute(
            "CREATE TABLE IF NOT EXISTS effects ("
            "effect_key TEXT PRIMARY KEY, payload TEXT NOT NULL)"
        )
        cursor = conn.execute(
            "INSERT OR IGNORE INTO effects(effect_key, payload) VALUES (?, ?)",
            (effect_key, payload),
        )
        return cursor.rowcount == 1

def close_ticket(state: TicketState) -> dict:
    inserted = write_effect_once(
        state["side_effect_key"],
        f"ticket {state['ticket_id']} closed",
    )
    print(f"effect_inserted={inserted}")
    return {"status": "closed"}

def count_effects() -> int:
    with sqlite3.connect(EFFECT_DB) as conn:
        conn.execute(
            "CREATE TABLE IF NOT EXISTS effects ("
            "effect_key TEXT PRIMARY KEY, payload TEXT NOT NULL)"
        )
        return conn.execute("SELECT COUNT(*) FROM effects").fetchone()[0]

def build_graph(checkpointer: SqliteSaver):
    builder = StateGraph(TicketState)
    builder.add_node("prepare", prepare)
    builder.add_node("close_ticket", close_ticket)
    builder.add_edge(START, "prepare")
    builder.add_edge("prepare", "close_ticket")
    builder.add_edge("close_ticket", END)
    # 静态断点停在副作用节点之前,便于用第二个进程继续。
    return builder.compile(
        checkpointer=checkpointer,
        interrupt_before=["close_ticket"],
    )

def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument("mode", choices=["start", "resume", "inspect"])
    args = parser.parse_args()
    config = {"configurable": {"thread_id": THREAD_ID}}

    with SqliteSaver.from_conn_string(CHECKPOINT_DB) as checkpointer:
        graph = build_graph(checkpointer)

        if args.mode == "start":
            graph.invoke(
                {"ticket_id": "T-1001", "status": "new"},
                config=config,
            )
        elif args.mode == "resume":
            graph.invoke(None, config=config)

        snapshot = graph.get_state(config)
        next_node = snapshot.next[0] if snapshot.next else "END"
        print(
            f"status={snapshot.values['status']} "
            f"next={next_node} effects={count_effects()}"
        )

if __name__ == "__main__":
    main()

在两个独立命令中先启动、再恢复;第三条命令只重新读取持久化结果。每次执行 python 都会启动一个新进程,因此这里确实覆盖了进程退出后的恢复。

bash
python ticket_graph.py start
python ticket_graph.py resume
python ticket_graph.py inspect

预期输出

text
status=prepared next=close_ticket effects=0
effect_inserted=True
status=closed next=END effects=1
status=closed next=END effects=1

实际运行耗时和 checkpoint 内部 ID 可能不同,但这里不依赖这些动态值。关键验收点是:第一次进程停在 close_ticket 之前;第二个进程恢复后进入 closed;第三个进程仍能读到同一线程;副作用记录始终只有 1 条。

为什么只接 checkpointer 还不够

Checkpoint 只能证明“图状态已经提交到哪里”,不能自动把外部 API、消息发送或数据库扣款变成 exactly-once。最危险的窗口是:节点已经完成外部副作用,但进程在新的 checkpoint 提交前崩溃。恢复后该节点可能重放,于是外部动作被再次调用。

生产节点因此应把幂等键设计成业务协议的一部分,例如用 ticket_id + action 生成稳定键,让下游数据库唯一约束、支付接口幂等键或 outbox 表负责去重。不要把“节点没有报错”等同于“副作用已经且只执行一次”。

恢复验证应检查哪些证据

恢复测试至少保留三类证据:graph.get_state(config) 能读到预期业务状态;snapshot.next 指向预期下一节点或为空;外部系统中的副作用条数与业务预期一致。三者同时成立,才能说明这条线程不仅“看起来恢复了”,而且执行位置和外部世界也保持一致。

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

目录与阅读设置

阅读设置

17

记录一个想法

持久化线程并验证断点恢复

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

登录哪都通