【LangGraph】langgraph.checkpoint.redis.RedisSaver 类：将状态图的检查点保存到 Redis 数据库

langgraph.checkpoint.redis.RedisSaver 是 LangGraph 库中 langgraph.checkpoint.redis 模块的一个检查点保存器类，继承自 BaseCheckpointSaver，用于将状态图的检查点保存到 Redis 数据库中。LangGraph 是 LangChain 生态的扩展框架，专注于构建复杂、有状态的 AI 系统，通过状态图（StateGraph）管理节点和边，支持动态路由、循环和状态管理。检查点（Checkpoint）是 LangGraph 的核心功能，用于在图执行的每一步保存状态，支持状态持久化、恢复和多轮交互。RedisSaver 使用 Redis 作为后端存储，支持同步操作，适合生产环境中的高并发场景。

---

1. 定义与功能

1.1 类定义

RedisSaver 是 BaseCheckpointSaver 的子类，定义如下：

from langgraph.checkpoint.redis import RedisSaver

class RedisSaver(BaseCheckpointSaver):
    """
    使用 Redis 数据库存储检查点的检查点保存器（同步操作）。

    参数：
        connection: Redis 连接对象（redis.Redis）。
        serde: 可选的序列化器，默认为 JsonPlusSerializer。
        ttl_config: TTL 配置，指定检查点存活时间和读取行为。

    示例：
        from redis import Redis
        from langgraph.checkpoint.redis import RedisSaver

        redis_client = Redis.from_url("redis://localhost:6379")
        checkpointer = RedisSaver(connection=redis_client)
        checkpointer.setup()
    """

• 继承：继承自 BaseCheckpointSaver，实现其抽象方法，提供 Redis 存储逻辑。
• 依赖：使用 redis 库（Python Redis 客户端）与 Redis 数据库交互，需 RedisJSON 和 RediSearch 模块支持。
• 作用：将检查点数据持久化存储到 Redis，支持生产级应用的高并发和快速访问。

1.2 核心功能

• 持久化存储：将检查点保存到 Redis，数据在应用重启后仍可恢复。
• 线程隔离：通过 thread_id 管理多线程，确保不同会话的状态独立。
• 同步操作：提供同步方法（如 get、put），适合同步编程环境。
• 索引管理：通过 setup() 方法创建 Redis 索引（如 Checkpoints Index、Channel Values Index），优化查询。
• TTL 支持：支持 Time-To-Live（TTL）配置，自动过期旧数据，减少存储占用。
• 序列化支持：通过 serde 参数支持自定义序列化，默认使用 JsonPlusSerializer。
• 高性能：利用 Redis 的内存数据库特性，支持快速读写和高并发。

1.3 使用场景

• 生产环境：需要持久化存储的 AI 应用，如聊天机器人、自动化工作流。
• 多轮对话：保存对话历史，支持上下文连续性。
• 高并发场景：Redis 的高性能支持大规模并发访问。
• 状态恢复：从中断点恢复任务，确保工作流连续性。
• 同步编程：适合同步操作环境，需高性能存储的场景。

---

2. 参数与初始化

2.1 初始化参数

• connection：
  • 类型：redis.Redis
  • 描述：Redis 连接对象，必需，用于与 Redis 数据库交互。
  • 示例：

    from redis import Redis
    redis_client = Redis.from_url("redis://localhost:6379")
    

• serde：
  • 类型：Optional[SerializerProtocol]
  • 默认值：None（使用 JsonPlusSerializer）
  • 描述：序列化器，处理检查点数据的序列化和反序列化，支持 LangChain 和 LangGraph 原生类型。
• ttl_config：
  • 类型：dict
  • 默认值：{"default_ttl": 60, "refresh_on_read": True}
  • 描述：TTL 配置，包含：
    • default_ttl：检查点存活时间（分钟），默认 60 分钟。
    • refresh_on_read：读取时是否刷新 TTL，默认 True。
  • 示例：

    ttl_config = {"default_ttl": 120, "refresh_on_read": False}
    

2.2 初始化方法

• 直接初始化：

  from redis import Redis
  from langgraph.checkpoint.redis import RedisSaver
  
  redis_client = Redis.from_url("redis://localhost:6379")
  checkpointer = RedisSaver(connection=redis_client, ttl_config={"default_ttl": 120})
  

• 使用连接字符串：

  checkpointer = RedisSaver.from_conn_string("redis://localhost:6379")
  

2.3 索引初始化

• 方法：setup()
  • 描述：创建必要的 Redis 索引（如 Checkpoints Index、Channel Values Index），首次使用时必须调用。
  • 调用：

    checkpointer.setup()
    

  • 注意：
    • 确保 Redis 实例支持 RedisJSON 和 RediSearch 模块。
    • Redis < 8.0 需使用 Redis Stack 或单独安装模块。

---

3. 使用方法

3.1 安装与环境准备

1. 安装依赖：

   pip install langgraph-checkpoint-redis
   

   • 必需依赖：redis>=5.2.1、redisvl>=0.5.1、langgraph-checkpoint>=2.0.24。
   • 可选：安装 Redis Stack 以支持 RedisJSON 和 RediSearch。
2. Redis 配置：
   • 确保 Redis 服务器运行，推荐版本 8.0+，或使用 Redis Stack。
   • 配置连接信息（主机、端口、数据库、密码）。
   • 验证 RedisJSON 和 RediSearch 模块是否启用：

     redis-cli MODULE LIST
     

3. 连接设置：
   • 创建 Redis 连接时，建议配置连接池：

     from redis import Redis
     redis_client = Redis.from_url("redis://localhost:6379", max_connections=20)
     

3.2 集成到状态图

1. 创建状态图：

   from langgraph.graph import StateGraph
   
   builder = StateGraph(int)
   builder.add_node("add_one", lambda x: x + 1)
   builder.set_entry_point("add_one")
   builder.set_finish_point("add_one")
   

2. 编译图：

   from langgraph.checkpoint.redis import RedisSaver
   from redis import Redis
   
   redis_client = Redis.from_url("redis://localhost:6379")
   checkpointer = RedisSaver(connection=redis_client)
   checkpointer.setup()
   graph = builder.compile(checkpointer=checkpointer)
   

3. 运行图：

   config = {"configurable": {"thread_id": "thread-1"}}
   result = graph.invoke(1, config=config)
   print(result)  # 输出: 2
   

3.3 操作检查点

• 获取检查点：

  checkpoint = checkpointer.get_tuple(config)
  print(checkpoint)  # 输出: CheckpointTuple(...)
  

• 列出检查点：

  checkpoints = list(checkpointer.list(config))
  for cp in checkpoints:
      print(cp)
  

• 保存检查点：由状态图自动调用 put，无需手动操作。

3.4 完整示例：多轮对话

以下示例展示如何使用 RedisSaver 实现多轮对话：

from typing import List
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START
from langgraph.checkpoint.redis import RedisSaver
from langchain_core.messages import HumanMessage
from redis import Redis

# 定义状态
class State(TypedDict):
    messages: List[dict]

# 定义节点
def agent_node(state: State) -> State:
    last_message = state["messages"][-1]["content"]
    return {"messages": state["messages"] + [{"role": "assistant", "content": "Echo: " + last_message}]}

# 创建 Redis 连接
redis_client = Redis.from_url("redis://localhost:6379")

# 初始化 RedisSaver
checkpointer = RedisSaver(connection=redis_client, ttl_config={"default_ttl": 120, "refresh_on_read": True})
checkpointer.setup()

# 构建状态图
builder = StateGraph(State)
builder.add_node("agent", agent_node)
builder.add_edge(START, "agent")
builder.set_finish_point("agent")

# 编译图
graph = builder.compile(checkpointer=checkpointer)

# 运行多轮对话
config = {"configurable": {"thread_id": "thread-1"}}
result1 = graph.invoke({"messages": [{"role": "user", "content": "Hello"}]}, config=config)
print(result1["messages"][-1]["content"])  # 输出: Echo: Hello

result2 = graph.invoke({"messages": [{"role": "user", "content": "How are you?"}]}, config=config)
print(result2["messages"][-1]["content"])  # 输出: Echo: How are you?

解析

• 状态：State 包含消息列表，模拟对话历史。
• 检查点：RedisSaver 将状态保存到 Redis，thread_id 确保连续性，TTL 配置控制数据存活时间。
• 结果：对话历史持久化存储，支持跨会话访问。

3.5 异步替代

• 限制：RedisSaver 仅支持同步操作。
• 替代方案：使用 AsyncRedisSaver（需 redis.asyncio），支持异步操作：

  from langgraph.checkpoint.redis import AsyncRedisSaver
  from redis.asyncio import Redis
  redis_client = Redis.from_url("redis://localhost:6379")
  checkpointer = AsyncRedisSaver(connection=redis_client)
  

---

4. 实现原理

4.1 Redis 存储

• 数据结构：
  • 使用 Redis 键值对存储检查点，组织为多个索引：
    • Checkpoints Index：存储元数据（如 thread_id、版本）。
    • Channel Values Index：存储通道特定数据（如节点输出）。
    • Writes Index：跟踪待写入状态。
  • 数据以序列化形式存储，推荐使用 RedisJSON 模块支持复杂对象。
• 键命名：基于 thread_id 和 checkpoint_ns 生成唯一键，防止冲突。

4.2 线程隔离

• 使用 thread_id 区分会话，存储在 Redis 中，确保状态隔离。
• checkpoint_ns 支持命名空间管理，组织复杂工作流。

4.3 序列化

• 默认使用 JsonPlusSerializer，支持 LangChain 和 LangGraph 原生类型。
• 可自定义 serde，如 PickleCheckpointSerializer，但需注意反序列化安全。

4.4 TTL 管理

• 检查点数据设置 TTL（默认 60 分钟），通过 ttl_config 配置。
• refresh_on_read=True 时，读取操作刷新 TTL，延长数据存活时间。

4.5 同步操作

• 使用 redis.Redis 客户端执行同步操作，适合同步编程环境。
• Redis 的内存数据库特性确保快速读写。

---

5. 适用场景与限制

5.1 适用场景

• 生产环境：需要持久化存储和高性能的 AI 应用，如聊天机器人、自动化工作流。
• 多轮对话：保存对话历史，支持上下文连续性。
• 高并发：Redis 的内存数据库支持大规模并发访问。
• 状态恢复：从中断点恢复任务，确保工作流连续性。
• 同步编程：适合同步操作环境，需快速存储的场景。

5.2 限制

• Redis 依赖：需要 Redis 服务器，增加部署复杂性。
• 模块要求：需 RedisJSON 和 RediSearch 模块，Redis < 8.0 需使用 Redis Stack。
• 初始化：首次使用需调用 setup() 创建索引。
• 异步支持：仅同步，异步需求需用 AsyncRedisSaver。
• 存储成本：Redis 内存占用可能较高，需合理配置 TTL。

---

6. 对比其他检查点保存器

特性	RedisSaver	InMemorySaver	PostgresSaver
存储位置	Redis 数据库	内存	PostgreSQL 数据库
适用场景	生产环境、高并发、同步操作	调试、测试、短期实验	生产环境、长期运行
持久化	是	否（重启后丢失）	是
安装要求	需 langgraph-checkpoint-redis	无需额外安装	需 langgraph-checkpoint-postgres
异步支持	否（需 AsyncRedisSaver）	是	是

选择建议：

• 开发阶段：使用 InMemorySaver，快速迭代。
• 生产环境：根据需求选择 RedisSaver（高并发、快速访问）或 PostgresSaver（复杂查询、事务支持）。RedisSaver 更适合内存密集型应用。

---

7. 注意事项

1. Redis 配置：
   • 确保 Redis 版本 >= 8.0，或使用 Redis Stack 启用 RedisJSON 和 RediSearch。
   • 配置连接池以优化性能，生产环境建议启用持久化（AOF 或 RDB）。
2. 初始化：
   • 调用 setup() 创建索引，确保 Redis 支持必要模块。
   • 检查 Redis 权限，确保可写入索引。
3. 序列化安全：
   • 默认 JsonPlusSerializer 安全可靠。
   • 使用 PickleCheckpointSerializer 时，仅反序列化可信数据。
4. 性能优化：
   • 配置适当的 TTL（如 default_ttl=120），减少过期数据占用。
   • 使用 Redis 连接池（如 max_connections=20）优化并发。
   • 监控 Redis 内存使用，避免溢出。
5. 调试技巧：
   • 启用 debug=True 查看检查点日志。
   • 使用 redis-cli 或 Redis 管理工具（如 RedisInsight）检查键值对和索引。
   • 调用 get_tuple 验证检查点数据。
6. 版本兼容性：
   • 确保 langgraph-checkpoint-redis>=0.0.2 和 LangGraph 版本匹配（建议 0.2+）。
   • 参考 LangGraph 文档 和 RedisSaver GitHub。

---

8. 学习建议

• 基础知识：掌握 LangGraph 的状态图、检查点和 Redis 基础（如键值存储、RedisJSON）。
• 文档：
  • 阅读 LangGraph 检查点文档。
  • 查看 RedisSaver GitHub 和 Redis 博客。
• 实践：
  • 搭建本地 Redis 服务器（或使用 Docker：docker run -d -p 6379:6379 redis/redis-stack）。
  • 测试简单状态图，验证检查点持久化。
  • 实现多轮对话，调整 TTL 配置。
• 社区：加入 LangChain Discord，查看 GitHub 示例。
• 调试：使用 redis-cli、日志和可视化工具（如 graph.get_graph().to_dot()）分析检查点。

---

9. 总结

langgraph.checkpoint.redis.RedisSaver 是 LangGraph 的检查点保存器，基于 Redis 数据库实现同步持久化存储，适合生产环境中的高并发场景。它继承自 BaseCheckpointSaver，支持 TTL 配置、索引管理和序列化，通过 setup() 初始化 Redis 索引。核心功能包括线程隔离、状态恢复和高性能存储，适用于多轮对话、自动化工作流和分布式系统。相比 InMemorySaver，它提供持久化优势；相比 PostgresSaver，更适合内存密集型、高并发场景。通过示例和实践，开发者可以快速掌握其用法，构建高效、可靠的 AI 应用。

---

关键引用：

• Redis 开发者 LangGraph Redis 集成
• LangGraph Redis 检查点保存器 PyPI
• Redis 博客：LangGraph 与 Redis
• LangGraph 官方文档