持久化

LangGraph 的持久化层通过检查点器为智能体提供短期记忆，通过存储提供长期记忆。

持久化让 LangGraph 应用能够在单次图运行之外保留有用的信息。当智能体需要继续对话、在中断后恢复、从故障中恢复，或跨交互记住信息时，这就显得很重要。

LangGraph 提供两套互补的持久化系统：

• 检查点器 将线程的图状态持久化为检查点。将它们用于短期的、线程作用域内的记忆，包括对话连续性、人在回路工作流、时间旅行和容错。
• 存储 在图形状态之外持久化应用定义的数据。将它们用于长期的、跨线程的记忆，包括用户偏好、事实和共享知识。

大多数应用可以两者都用：一个检查点器跟踪当前线程，而一个存储跨线程跟踪持久化信息。

快速开始

使用检查点器、存储或两者来编译你的图：

from langgraph.checkpoint.memory import InMemorySaver
from langgraph.store.memory import InMemoryStore

checkpointer = InMemorySaver()
store = InMemoryStore()

graph = builder.compile(checkpointer=checkpointer, store=store)

result = graph.invoke(
    {"messages": [{"role": "user", "content": "Hi, my name is Bob."}]},
    {"configurable": {"thread_id": "thread-1"}},
)

INFO

Agent Server 会自动处理持久化 使用 Agent Server 时，你无需手动实现或配置检查点器或存储。服务器会在幕后处理持久化基础设施。

检查点器与存储的对比

	检查点器	存储
持久化内容	图状态快照	应用定义的键值数据
作用域	单个线程	跨线程
记忆类型	短期、线程作用域内的记忆	长期、跨线程的记忆
用于	对话连续性、人在回路、时间旅行和容错	用户偏好、事实和共享知识
访问模式	在图配置中传入 thread_id	从节点或应用代码中读写条目
完整指南	检查点器	存储

排查常见问题

PostgresSaver：thread_id 过长

使用 PostgresSaver（或 AsyncPostgresSaver）时，thread_id 存储在一个长度有限的列中。如果你的 thread_id 超过该列大小，就会看到数据库错误。

修复： 让 thread_id 值保持在 255 个字符以内。如果需要确定性 ID，请使用 UUID 或哈希：

import uuid

config = {"configurable": {"thread_id": str(uuid.uuid4())[:255]}}

MemorySaver 在重启之间不会持久化

MemorySaver 和 InMemorySaver 将检查点存储在 RAM 中。当进程重启时，所有检查点都会丢失。

修复： 为生产环境使用持久化的检查点器：

• PostgresSaver：支持异步的 PostgreSQL
• SqliteSaver：用于开发的本地文件存储

检查点无限增长

在长对话中，检查点会不断累积。这可能会增加延迟和存储成本。

修复： 定期清理旧检查点或设置保留策略：

from langgraph.checkpoint.postgres import PostgresSaver

checkpointer = PostgresSaver.from_conn_string("postgresql://...")
checkpointer.setup()  # Creates tables with indexes
# Consider adding a cron job to delete checkpoints older than N days

从父图到子图的状态访问

当子图更新状态时，父图可能不会立即看到这些更改。这是因为每个子图都管理自己的检查点命名空间。

修复： 对于需要跨越图边界的数据，请使用通过 Store 共享状态，或者配置你的子图以写入父检查点。

后续步骤

• 使用检查点器来持久化并检查线程状态。
• 使用存储来跨线程持久化持久数据。

---