1. 核心概念StateGraph / Node / Edge / CheckpointerStateGraph状态图StateGraph 是一种基于状态机的图编排框架。所有节点共享同一份State通常定义为TypedDict节点之间并不直接传递数据而是通过读写这份全局状态来完成通信。Node节点工作流中的执行单元每个节点只负责单一职责的业务逻辑如数据清洗、LLM 调用、工具执行。节点接收当前 State返回需要更新的字段。复杂场景下可使用子图SubGraph封装。Edge边节点之间的连接通道。分两种直接边无条件从一个节点到下一个节点。条件边Conditional Edge纯函数根据 State 的内容决定下一步路由到哪个节点。关键原则重试、分支等控制逻辑应该通过条件边实现而不是在节点内部写while循环。节点内循环会阻塞执行且无法被 Checkpointer 记录中间状态导致无法中断恢复。Checkpointer检查点/快照在每个 super-step调度步骤边界自动保存当前 State 完整快照的存储器。按thread_id隔离不同任务的历史记录。用途包括断点恢复、人工干预Human-in-the-loop、历史回溯Time Travel和审计。2. State 定义陷阱、Checkpointer 使用注意State 定义陷阱陷阱一State 过大导致存储爆炸Checkpointer 每次保存的是整个 State 的序列化快照。如果在 State 中直接存放大文件、超长文本、DataFrame 等快照体积会迅速膨胀。解法大对象只存指针如 OSS/S3 的 URL、数据库 ID真实数据放在外部存储中。陷阱二重试计数器字段膨胀每个需要重试的节点都定义一个retry_count_A、retry_count_B……字段会越来越多State 变得臃肿。解法用一个字典字段 Reducer 机制统一管理。定义attempts: Annotated[dict, operator.add]节点失败时返回{attempts: {node_name: 1}}框架自动累加无限节点扩展也不会新增字段。Checkpointer 使用注意super-step 边界落盘并非每次节点完成都存而是在一个调度步骤边界统一提交。并行节点在同一 super-step 内一起落盘。(用人话说就是一个节点内写三次循环这一起是一个快照通过判断反复进入这个节点三次会有三个快照interrupt 恢复会重跑节点节点内调用interrupt()挂起后恢复时该节点从头重新执行而不是从挂起点继续。节点逻辑需保证幂等或在 State 中记录已完成的子步骤避免重复副作用。thread_id 设计使用 UUID 或user_id:session_id格式不同用户/任务严禁复用否则状态串台。快照清理长期运行会产生海量快照需配置 TTL 或定期调用delete_thread清理。子图挂载只在外层父图挂 Checkpointer子图不重复挂载避免命名空间冲突和冗余存储。3. 为什么需要 CheckpointerMemorySaver 为什么不能上生产为什么需要 Checkpointer多轮/跨调用记忆同一thread_id多次 invoke自动延续上下文无需手动传递整份 State。Human-in-the-loop节点内interrupt()暂停人工审批后通过Command(resume...)从断点继续。审计与回放get_state_history(config)获取全部历史快照可定位问题、复现 bug、合规审计。容错恢复某节点失败后从上一 checkpoint 恢复已成功节点的结果不会重复执行。MemorySaver 为什么不能上生产MemorySaver或InMemorySaver官方定位仅为调试和测试用硬伤如下问题说明进程重启即丢数据存在 RAM 中容器重建、Pod 重启后所有任务状态清零多实例不共享多 worker / K8s 多副本部署时各进程内存隔离同一thread_id请求被路由到不同实例会失忆内存膨胀长任务、大量 thread 会持续占用 RSS无淘汰机制无持久化/加密不适合生产环境的多租户、PII 数据和合规要求生产选型单机轻量用SqliteSaver分布式/高可用用PostgresSaver官方推荐高性能缓存层可用RedisSaver需开启 AOF/RDB 持久化。
