🎯 课程主题

掌握 LangGraph Store 基础 API 中 put()（写入）和 get()（读取）方法的使用，分别在 InMemoryStore 和 PostgresStore 两种环境下进行实战演示，理解数据的写入、覆盖与更新机制。

📝 核心知识点

1. put() 方法

  • 功能：向 Store 写入或覆盖数据。
  • 关键参数：
参数类型说明
namespacetuple[str, ...]命名空间（字符串元组）
keystrnamespace 下的唯一标识
valuedict[str, Any]存储的字典数据
indexLiteral[False] | list[str] | None语义检索索引配置（False=禁用，None=使用默认）
ttlfloat | NoneTime To Live，数据存活时间（秒）
  • 覆盖行为：当 namespace + key 相同时，后续 put() 会覆盖之前的数据。

2. get() 方法

  • 功能：基于 namespace + key 进行精确查询。
  • 关键参数：
参数类型说明
namespacetuple[str, ...]命名空间
keystr查找的键
refresh_ttlbool是否刷新存活时间（默认 False）
  • 返回值：完整的 Item 对象，包含 namespace、key、value、created_at、updated_at 等字段 — 而非仅返回 value。

3. Item 对象结构

Item(
    namespace=("users",),
    key="user-1",
    value={"username": "小明"},
    created_at="2025-xx-xx ...",
    updated_at="2025-xx-xx ..."
)

4. InMemoryStore vs PostgresStore 的行为差异

行为InMemoryStorePostgresStore
首次 putcreated_at == updated_atcreated_at == updated_at
覆盖 put（同 namespace+key）视为全新写入，created_at 和 updated_at 均更新为当前时间，两者一致视为数据库行更新，created_at 保持不变，仅 updated_at 更新

核心原因：InMemoryStore 每次 put() 都创建新的 Item 对象；PostgresStore 则是数据库层面的 UPDATE 操作，保留了原始创建时间。

🏗️ 架构与工作流

put(namespace, key, value) ──▶ Store ──▶ get(namespace, key) ──▶ Item
                                          │
                                    同 namespace+key 再次 put
                                          │
                              ┌───────────┴───────────┐
                              ▼                       ▼
                       InMemoryStore           PostgresStore
                      (全新 Item 对象)       (UPDATE 数据库行)
                      created_at 更新         created_at 不变
                      updated_at 更新         updated_at 更新

💻 代码实战

2.1 基于 InMemoryStore 的 put 和 get

from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

# 定义数据
namespace = ("users",)
user_id = "user-1"
user_name = {"username": "小明"}

# 写入数据
store.put(namespace=namespace, key=user_id, value=user_name)

# 读取数据 — 返回完整 Item 对象（非仅 value）
item = store.get(namespace=namespace, key=user_id)
print(item)
# 输出: Item(namespace=('users',), key='user-1', value={'username': '小明'}, ...)

# 覆盖写入（同 namespace + key，value 变更）
store.put(namespace=namespace, key=user_id, value={"username": "小红"})
item = store.get(namespace=namespace, key=user_id)
print(item.value)  # {'username': '小红'}
# InMemoryStore 下 created_at 和 updated_at 均刷新为当前时间

2.2 基于 PostgresStore 的 put 和 get

from langgraph.store.postgres import PostgresStore

DB_URL = "postgresql://user:password@localhost:5432/langchadb"

with PostgresStore.from_conn_string(DB_URL) as store:
    # 首次使用需初始化表结构（仅首次创建表）
    store.setup()

    # 写入数据
    store.put(
        namespace=("users",),
        key="user-1",
        value={"username": "小明"}
    )

    # 读取
    item = store.get(namespace=("users",), key="user-1")
    print(item)
    # 首次写入：created_at == updated_at

    # 覆盖更新 — PostgresStore 下 created_at 保持不变
    store.put(
        namespace=("users",),
        key="user-1",
        value={"username": "小红"}
    )
    item = store.get(namespace=("users",), key="user-1")
    print(item.value)  # {'username': '小红'}
    # created_at 保持原时间，updated_at 更新为当前时间

⚠️ 常见问题与避坑指南

  1. get() 返回的是 Item 对象不是字典：取值需通过 item.value 而非直接使用 item["value"]。
  2. PostgresStore 需要先 setup()：首次使用必须调用 store.setup() 创建数据库表，否则写入会报错。
  3. Postgres 服务必须开启：使用 PostgresStore 前确保 PostgreSQL 服务正常运行。
  4. namespace 元组末尾逗号：("users",) 表示单元素元组，不能写成 ("users")（那会被当作字符串）。
  5. value 必须是 dict 类型：不能直接传字符串，必须用 {"key": "val"} 结构。

💡 个人总结与延伸

  • put() 和 get() 构成 Store 最基础的读写操作，是后续 search() 和 Agent 集成的前提。
  • 理解 InMemoryStore 和 PostgresStore 在覆盖行为上的差异很重要：前者每次 put 都相当于删除重建，后者是真正的数据库 UPDATE。
  • ttl 参数可用于实现自动过期的"会话级"长期记忆，结合 refresh_ttl 可实现"访问即续期"模式。
  • 下一节将介绍 search() 方法，支持基于 namespace 前缀、filter 过滤和语义搜索的灵活检索。
最近更新:
Contributors: yangwenguang