【LangGraph】langgraph.store.postgres.PostgresStore 类：于 PostgreSQL 数据库提供的持久化键值存储（？）

langgraph.store.postgres.PostgresStore 是 LangGraph 库中 langgraph.store.postgres 模块的一个持久化键值存储类，继承自 BaseStore 和 BasePostgresStore，基于 PostgreSQL 数据库实现。LangGraph 是 LangChain 生态的扩展框架，专注于构建复杂、有状态的 AI 系统，通过状态图（StateGraph）管理节点和边，支持动态路由、循环和状态管理。PostgresStore 提供持久化存储功能，支持层次命名空间和可选的向量搜索（通过 pgvector 扩展），适合需要长时记忆的 AI 应用，如聊天机器人或自动化工作流。

---

1. 定义与功能

1.1 类定义

PostgresStore 是 BaseStore 和 BasePostgresStore 的子类，定义如下：

from langgraph.store.postgres import PostgresStore

class PostgresStore(BaseStore, BasePostgresStore[Conn]):
    """
    使用 PostgreSQL 数据库实现的持久化键值存储类。

    参数：
        conn: PostgreSQL 连接或连接池（psycopg.Connection 或 psycopg.Pool）。
        index_config: 可选，索引配置，用于向量搜索。
        serde: 可选的序列化器，默认为 JsonPlusSerializer。
        ttl_config: 可选，TTL 配置，指定数据存活时间。

    示例：
        import psycopg
        from langgraph.store.postgres import PostgresStore

        pool = psycopg.Pool("postgresql://user:password@localhost:5432/dbname")
        store = PostgresStore(conn=pool)
        store.setup()
    """

• 继承：
  • BaseStore：定义键值存储的基本接口。
  • BasePostgresStore[Conn]：提供 PostgreSQL 特定的存储逻辑，支持泛型连接类型。
• 依赖：
  • 使用 psycopg 库与 PostgreSQL 交互。
  • 支持 pgvector 扩展以实现向量搜索。
• 作用：提供持久化键值存储，支持层次命名空间和语义搜索，适合生产级 AI 应用。

1.2 核心功能

• 持久化存储：将数据保存到 PostgreSQL 数据库，数据在应用重启后仍可恢复。
• 层次命名空间：支持分层组织数据，如 ("users", "user1", "profile")，便于管理复杂结构。
• 键值操作：提供 put、get、delete、list_namespaces 等方法，类似字典操作。
• 向量搜索：通过 pgvector 扩展支持语义搜索，基于向量嵌入查找相似数据。
• TTL 管理：支持数据过期机制，通过 start_ttl_sweeper() 定期清理过期数据。
• 同步和异步支持：
  • 同步方法：get、put、delete 等。
  • 异步方法：aget、aput、adelete 等（通过 AsyncPostgresStore）。
• 索引优化：支持向量索引配置（如 HNSW），提升搜索性能。

1.3 使用场景

• 长时记忆：AI 应用需要跨会话保存数据，如聊天机器人存储用户偏好或对话历史。
• 语义搜索：支持基于向量嵌入的内容检索，如推荐系统或知识库查询。
• 复杂工作流：存储中间结果，协调多步骤任务。
• 生产环境：PostgreSQL 的高可靠性支持生产级应用。
• 多轮对话：保存上下文，确保对话连续性。

---

2. 参数与初始化

2.1 初始化参数

• conn：
  • 类型：Union[psycopg.Connection, psycopg.Pool]
  • 描述：PostgreSQL 同步连接或连接池，必需。推荐使用连接池以优化性能。
  • 示例：

    import psycopg
    pool = psycopg.Pool("postgresql://user:password@localhost:5432/dbname")
    

• index_config：
  • 类型：Optional[dict]
  • 默认值：None
  • 描述：向量索引配置，指定索引类型（如 HNSW）及参数。
  • 示例：

    index_config = {"index_type": "hnsw", "m": 16, "ef_construction": 64}
    

• serde：
  • 类型：Optional[SerializerProtocol]
  • 默认值：None（使用 JsonPlusSerializer）
  • 描述：序列化器，处理数据的序列化和反序列化，支持复杂数据类型。
• ttl_config：
  • 类型：Optional[dict]
  • 默认值：None
  • 描述：TTL 配置，包含 default_ttl（分钟）和 refresh_on_read（是否在读取时刷新 TTL）。
  • 示例：

    ttl_config = {"default_ttl": 60, "refresh_on_read": True}
    

2.2 初始化方法

• 直接初始化：

  import psycopg
  from langgraph.store.postgres import PostgresStore
  
  pool = psycopg.Pool("postgresql://user:password@localhost:5432/dbname")
  store = PostgresStore(conn=pool, index_config={"index_type": "hnsw"})
  

• 使用连接字符串：

  store = PostgresStore.from_conn_string("postgresql://user:password@localhost:5432/dbname")
  

2.3 数据库初始化

• 方法：setup()
  • 描述：创建必要的数据库表（如 store、store_vectors），首次使用时必须调用。
  • 同步调用：

    store.setup()
    

  • 异步调用（AsyncPostgresStore）：

    await store.setup()
    

• 表结构：
  • store：存储键值数据，字段包括 prefix（命名空间）、key（键）、value（值）、created_at、updated_at、expires_at、ttl_minutes。
  • store_vectors：存储向量数据，字段包括 prefix、key、field_name（如 embedding）、embedding（向量）、created_at、updated_at。
• 注意：
  • 确保数据库用户有创建表的权限。
  • 向量搜索需启用 pgvector 扩展：

    CREATE EXTENSION IF NOT EXISTS vector;
    

---

3. 使用方法

3.1 安装与环境准备

1. 安装依赖：

   pip install langgraph psycopg[binary,pool] pgvector
   

   • langgraph：LangGraph 核心库。
   • psycopg：PostgreSQL 适配器，支持连接池。
   • pgvector：向量扩展，支持语义搜索。
2. 数据库配置：
   • 确保 PostgreSQL 数据库运行，推荐版本 14+。
   • 启用 pgvector 扩展：

     CREATE EXTENSION IF NOT EXISTS vector;
     

   • 配置连接信息（主机、端口、数据库名、用户名、密码）。
3. 连接设置：
   • 使用连接池优化性能：

     import psycopg
     pool = psycopg.Pool("postgresql://user:password@localhost:5432/dbname", max_size=20)
     

3.2 基本键值操作

• 存储数据：

  store.put(namespace=("users", "user1"), key="profile", value={"name": "Alice", "age": 30})
  

• 获取数据：

  profile = store.get(namespace=("users", "user1"), key="profile")
  print(profile)  # 输出: {'name': 'Alice', 'age': 30}
  

• 删除数据：

  store.delete(namespace=("users", "user1"), key="profile")
  

• 列出命名空间：

  namespaces = list(store.list_namespaces())
  print(namespaces)  # 输出: [('users', 'user1'), ...]
  

3.3 向量搜索

• 存储向量：

  from langchain.embeddings import HuggingFaceEmbeddings
  embeddings = HuggingFaceEmbeddings()
  vector = embeddings.embed_query("I love Italian cuisine")
  store.put(namespace=("food", "pref"), key="user1", value=vector, field_name="embedding")
  

• 语义搜索：

  query = embeddings.embed_query("Italian food")
  results = store.search(namespace=("food",), query=query, k=5)
  for result in results:
      print(result)  # 输出: 匹配的键值对
  

3.4 异步操作

• 使用 AsyncPostgresStore：

  from langgraph.store.postgres import AsyncPostgresStore
  async_store = AsyncPostgresStore.from_conn_string("postgresql://user:password@localhost:5432/dbname")
  await async_store.setup()
  await async_store.put(namespace=("users", "user1"), key="profile", value={"name": "Alice"})
  

3.5 TTL 管理

• 配置 TTL：

  store.start_ttl_sweeper(default_ttl=60, refresh_on_read=True)
  

• 作用：数据默认存活 60 分钟，读取时刷新 TTL。
• 后台清理：sweep_ttl 方法定期删除过期数据。

3.6 完整示例：聊天机器人存储

from typing import List
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START
from langgraph.store.postgres import PostgresStore
import psycopg
from langchain_core.messages import HumanMessage

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

# 定义节点
def agent_node(state: State, store: PostgresStore) -> State:
    user_id = "user1"
    # 获取用户偏好
    profile = store.get(namespace=("users", user_id), key="profile") or {"name": "Guest"}
    last_message = state["messages"][-1]["content"]
    response = f"Hello {profile['name']}, you said: {last_message}"
    return {"messages": state["messages"] + [{"role": "assistant", "content": response}]}

# 创建连接池
pool = psycopg.Pool("postgresql://user:password@localhost:5432/dbname", max_size=20)

# 初始化 PostgresStore
store = PostgresStore(conn=pool)
store.setup()

# 存储用户偏好
store.put(namespace=("users", "user1"), key="profile", value={"name": "Alice"})

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

# 编译图
graph = builder.compile()

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

解析

• 状态：State 包含消息列表，模拟对话历史。
• 存储：PostgresStore 保存用户偏好（如 "profile"），支持跨会话访问。
• 结果：对话使用存储数据生成个性化响应。

---

4. 实现原理

4.1 数据库存储

• 表结构：
  • store：存储键值数据，字段包括：
    • prefix：命名空间路径（如 users.user1）。
    • key：键名。
    • value：序列化值（JSON 格式）。
    • created_at、updated_at：创建和更新时间。
    • expires_at、ttl_minutes：TTL 相关字段。
  • store_vectors：存储向量数据，字段包括：
    • prefix、key、field_name（如 embedding）。
    • embedding：向量（pgvector 类型）。
    • created_at、updated_at。
• SQL 操作：通过 psycopg 执行插入、查询、更新和删除，事务确保一致性。

4.2 层次命名空间

• 命名空间以点分隔字符串存储（如 users.user1），支持分层查询。
• 使用 prefix 字段快速定位数据。

4.3 向量搜索

• 依赖 pgvector 扩展，支持向量索引（如 HNSW）。
• 使用 SQL 查询执行相似性搜索（如 cosine 或 L2 距离）。

4.4 TTL 管理

• 通过 expires_at 和 ttl_minutes 字段控制数据存活时间。
• sweep_ttl 方法定期清理过期数据，start_ttl_sweeper 启动后台任务。

4.5 连接管理

• 支持 psycopg.Connection（单连接）和 psycopg.Pool（连接池）。
• 生产环境推荐连接池以优化并发性能。

---

5. 适用场景与限制

5.1 适用场景

• 长时记忆：AI 应用需要跨会话保存数据，如用户偏好、对话历史。
• 语义搜索：基于向量嵌入的内容检索，如推荐系统或知识库查询。
• 复杂工作流：存储中间结果，协调多步骤任务。
• 生产环境：PostgreSQL 的高可靠性支持生产级应用。
• 多轮对话：保存上下文，确保对话连续性。

5.2 限制

• 数据库依赖：需要 PostgreSQL 数据库，增加部署复杂性。
• 初始化要求：需调用 setup() 创建表，需启用 pgvector 扩展。
• 性能：向量搜索性能依赖索引配置，未优化可能导致延迟。
• 版本兼容性：需确保 LangGraph 和 PostgreSQL 版本匹配（建议 PostgreSQL 14+）。
• 连接管理：单连接可能成为瓶颈，推荐使用连接池。

---

6. 对比其他存储类

特性	PostgresStore	InMemoryStore	RedisStore
存储位置	PostgreSQL 数据库	内存	Redis 数据库
适用场景	生产环境、长时记忆、向量搜索	调试、测试、短期实验	高并发、快速访问
持久化	是	否（重启后丢失）	是
安装要求	需 psycopg、pgvector	无需额外安装	需 redis、redisvl
向量搜索	是（需 pgvector）	否	是（需 RedisJSON）
异步支持	是（AsyncPostgresStore）	是	是（AsyncRedisStore）

选择建议：

• 开发阶段：使用 InMemoryStore，快速迭代。
• 生产环境：根据需求选择 PostgresStore（向量搜索、事务支持）或 RedisStore（高并发、快速访问）。PostgresStore 更适合需要复杂查询和长期存储的场景。

---

7. 注意事项

1. 数据库配置：
   • 确保 PostgreSQL 运行，推荐版本 14+。
   • 启用 pgvector 扩展：

     CREATE EXTENSION IF NOT EXISTS vector;
     

   • 使用连接池（如 psycopg.Pool）优化性能：

     pool = psycopg.Pool("postgresql://user:password@localhost:5432/dbname", max_size=20)
     

2. 初始化：
   • 调用 setup() 创建表，确保用户有创建权限。
   • 检查表结构与当前版本兼容。
3. 序列化安全：
   • 默认 JsonPlusSerializer 安全可靠。
   • 自定义序列化器（如 PickleCheckpointSerializer）需确保数据可信。
4. 性能优化：
   • 配置向量索引（如 HNSW）以加速搜索：

     index_config = {"index_type": "hnsw", "m": 16, "ef_construction": 64}
     

   • 优化连接池大小（max_size），避免连接耗尽。
   • 定期清理过期数据，合理设置 TTL。
5. 调试技巧：
   • 启用 debug=True 查看存储日志。
   • 使用 SQL 工具（如 pgAdmin）检查 store 和 store_vectors 表。
   • 调用 get 或 search 验证数据。
6. 版本兼容性：
   • 确保 LangGraph 版本支持（0.2+），参考 LangGraph 存储参考。
   • PostgreSQL 版本需与 pgvector 兼容（建议 14+）。
   • 检查 psycopg 和 pgvector 版本是否匹配。

---

8. 学习建议

• 基础知识：
  • 掌握 LangGraph 的状态图、存储和 PostgreSQL 基础。
  • 了解向量搜索原理和 pgvector 扩展。
• 文档：
  • 阅读 LangGraph 存储参考。
  • 查看 pgvector 文档 和 Using PostgreSQL with LangGraph。
• 实践：
  • 搭建本地 PostgreSQL 数据库（可用 Docker：docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=password postgres:14）。
  • 测试键值存储和向量搜索，验证持久化效果。
  • 实现多轮对话，结合存储实现个性化响应。
• 社区：
  • 加入 LangChain Discord，查看 GitHub 示例。
  • 参考 Stack Overflow 和 GitHub Discussion。
• 调试：
  • 使用 SQL 工具（如 pgAdmin）检查表内容。
  • 启用日志和可视化工具（如 graph.get_graph().to_dot()）分析存储行为。

---

9. 总结

langgraph.store.postgres.PostgresStore 是 LangGraph 提供的持久化键值存储类，基于 PostgreSQL 数据库，支持层次命名空间和向量搜索（通过 pgvector）。它继承自 BaseStore，提供 put、get、delete 等方法，通过 setup() 初始化表结构。核心功能包括持久化存储、语义搜索和 TTL 管理，适合生产环境中需要长时记忆和内容检索的 AI 应用，如聊天机器人和复杂工作流。相比 InMemoryStore，它提供持久化优势；相比 RedisStore，更适合事务支持和复杂查询场景。通过示例和实践，开发者可以快速掌握其用法，构建高效、可靠的 AI 系统。

---

关键引用：

• LangGraph 存储参考
• Using PostgreSQL with LangGraph for State Management and Vector Storage
• LangGraph GitHub 仓库
• Stack Overflow: Using LangGraph Store with GCP Postgres
• GitHub Discussion: Update PostgresStore to support a connection pool
• pgvector 官方文档