← 返回文章短期记忆
介绍Langchain/Langgraph中如何使用内存/redis 搭建短期记忆
"""
# LangChain / LangGraph 短期记忆(Short-Term Memory)
一、核心概念
LangChain 1.x 的 create_agent 基于 LangGraph 构建。
Agent 的短期记忆主要通过 State + Checkpointer + thread_id 实现。
1. State(状态)
- 保存 Agent 当前执行过程中的状态数据。
- 默认 AgentState 包含 messages 字段,用来保存对话消息。
- 除了 messages,还可以通过自定义 State 保存其他业务状态。
- State 是运行时的逻辑状态,不等于数据库,也不负责持久化。
2. Checkpointer(检查点持久化器)
- 负责保存和读取 State 的检查点。
- LangGraph 通常在每个 super-step(超级步骤)边界生成检查点。
- 保存的不只是对话消息,还可能包括其他 State 字段及执行元数据。
- 可以用于多轮对话、断点恢复、人工审核和历史状态查看。
- 它是一套持久化接口,底层可以使用内存、Redis、PostgreSQL 等。
3. thread_id(会话标识)
- 用于标识一条独立的会话线程。
- 同一个 thread_id:读取该会话此前保存的状态,继续进行新的对话。
- 不同的 thread_id:使用不同的会话状态。
- thread_id 不是用户 ID,而是会话 ID;一个用户可以有多条会话。
整个执行过程:
用户输入
↓
config 中传入 thread_id
↓
Agent 通过 Checkpointer 查询当前会话的历史 State
↓
加载已有 State,并合并本次输入的 messages
↓
LLM 基于当前 State 执行推理
↓
Agent / Tool 等节点更新 State
↓
Checkpointer 保存新的检查点
↓
返回 Agent 执行结果
注意:
- 一般不需要手动查询 Redis 并拼接历史消息。
- Checkpointer 会在 LangGraph 执行过程中自动读取和保存状态。
- 再次调用时,只需要传入相同的 thread_id 和本轮新增消息。
- Checkpointer 保存历史状态,不代表会自动压缩模型上下文。
- 短期记忆主要作用于同一个 thread;跨会话的长期记忆通常使用 Store。
"""
# ============================================================
# 二、方式一:使用内存保存短期记忆
# ============================================================
"""
InMemorySaver:
- LangGraph 提供的内存型 Checkpointer。
- 数据保存于当前 Python 进程的内存中。
- 不需要数据库,适合本地开发、测试和简单 Demo。
- Python 进程退出后,保存的状态就会丢失。
- 多个独立进程之间不能共享其状态。
- 不建议用于需要可靠持久化的生产环境。
"""
from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver
# llm 为提前实例化好的 LangChain ChatModel
checkpointer = InMemorySaver()
agent = create_agent(
model=llm,
tools=[],
checkpointer=checkpointer,
)
# 定义会话 ID
config = {
"configurable": {
"thread_id": "user_001:session_001"
}
}
# 第一轮对话
result1 = await agent.ainvoke(
{"messages": [{"role": "user", "content": "我叫小王"}]},
config=config,
)
# 第二轮对话
# 不需要手动重新传入第一轮历史消息
# 因为 Checkpointer 会自动加载相同 thread_id 的 State
result2 = await agent.ainvoke(
{"messages": [{"role": "user", "content": "我叫什么名字?"}]},
config=config,
)
print(result2["messages"][-1].content)
# ============================================================
# 三、方式二:Redis 持久化短期记忆(推荐用于生产项目)
# ============================================================
"""
为什么使用 Redis?
1. InMemorySaver 的数据仅存在当前 Python 进程中。
2. Redis 是独立运行的内存数据库,支持多个服务进程共享数据。
3. Agent 服务重启后,只要 Redis 数据仍存在,就可以恢复会话状态。
4. 支持设置 TTL,控制检查点的保存时间。
5. 可以结合 Redis 的 RDB / AOF 等机制实现数据持久化。
注意:
- Redis 本身也是以内存为主要存储介质,并不是无限容量。
- Redis 不会自动解决所有内存问题,需要合理配置 TTL 和容量。
- Redis 并非唯一的生产方案,PostgreSQL 也是常见选择。
- 生产环境需要考虑 Redis 数据持久化、备份、故障恢复等问题。
"""
# ------------------------------------------------------------
# 1. 安装依赖与准备 Redis 服务
# ------------------------------------------------------------
"""
安装 Python 依赖:
uv add langchain langgraph langgraph-checkpoint-redis redis
如果使用 FastAPI:
uv add fastapi uvicorn
如果使用 OpenAI 模型:
uv add langchain-openai
Redis 服务要求:
langgraph-checkpoint-redis 需要:
- RedisJSON:保存 JSON 格式的检查点文档。
- RediSearch:建立索引并检索检查点。
推荐 Redis 8.0+,相关功能已内置。
本地 Docker 启动:
docker run -d \
--name langgraph-redis \
-p 127.0.0.1:6379:6379 \
redis:8
对于 Redis 8.0 以下版本:
需要使用具备 RedisJSON 和 RediSearch 功能的 Redis Stack,
或使用其他已安装对应模块的 Redis 服务。
注意:
普通的旧版 Redis 不一定可以直接使用 AsyncRedisSaver。
"""
# ------------------------------------------------------------
# 2. 创建 Redis 异步连接池
# ------------------------------------------------------------
import redis.asyncio as redis
"""
为什么使用连接池?
如果每次请求都独立创建和关闭 Redis TCP 连接:
- 增加连接建立和释放的开销。
- 高并发下产生大量短生命周期连接。
- 增加 Redis 服务端和应用程序的资源消耗。
ConnectionPool:
- 负责管理和复用 Redis TCP 连接。
- 多个并发任务可以通过同一个 Redis 客户端使用连接池。
- 可以配置最大连接数量。
- 不负责保存会话状态。
- 不负责区分不同用户的对话。
需要区分:
ConnectionPool:负责连接管理。
Redis Client:负责向 Redis 发送命令。
AsyncRedisSaver:负责 LangGraph Checkpoint 的读写。
thread_id:负责区分不同会话。
"""
pool = redis.ConnectionPool(
host="localhost",
port=6379,
db=0,
password=None,
# Redis Checkpointer 推荐使用 bytes 响应。
# 避免启用 Redis 客户端的自动字符串解码。
decode_responses=False,
# 最大连接数,不等于最大并发请求数。
max_connections=50,
# TCP 建立连接的超时时间(秒)
socket_connect_timeout=5,
# Redis Socket 操作的超时时间(秒)
socket_timeout=15,
# 定期检查连接健康状态(秒)
health_check_interval=30,
)
# ------------------------------------------------------------
# 3. 使用连接池创建 Redis 客户端
# ------------------------------------------------------------
redis_client = redis.Redis(
connection_pool=pool
)
"""
redis_client:
- 是异步 Redis 客户端。
- 它会自动从 pool 获取连接执行 Redis 命令。
- 支持多个异步任务复用。
- Redis(...) 本身通常不会立即建立网络连接。
- 第一次执行 Redis 命令时才实际获取连接。
通过已有 ConnectionPool 创建的客户端,
通常由应用程序自行管理连接池生命周期。
"""
# 可选:测试连接是否可用
await redis_client.ping()
# ------------------------------------------------------------
# 4. 创建 AsyncRedisSaver
# ------------------------------------------------------------
from langgraph.checkpoint.redis.aio import AsyncRedisSaver
"""
AsyncRedisSaver:
- 是 LangGraph Checkpointer 的 Redis 异步实现。
- 接收 redis.asyncio.Redis 客户端。
- 负责序列化与反序列化检查点中的 State 数据。
- 通过 RedisJSON 保存检查点及中间写入数据。
- 通过 RediSearch 索引查询对应的检查点。
- 在 Agent 执行过程中自动完成相关读写。
需要修正的理解:
AsyncRedisSaver 不是简单的 Redis JSON 读写器。
更准确地说:
它是 LangGraph Checkpointer 接口的一种 Redis 存储实现,
负责按照 LangGraph 的检查点协议管理状态及其历史记录。
也不需要开发者自己将 State 转成 JSON 再调用 Redis.set()。
"""
checkpointer = AsyncRedisSaver(
redis_client=redis_client,
# 可选:设置检查点 TTL
ttl={
# 单位是分钟
# 这里设置为 7 天
"default_ttl": 60 * 24 * 7,
# 读取已有检查点时刷新其 TTL
"refresh_on_read": True,
}
)
# 重要:初始化 Redis Checkpointer 所需的索引
# 必须在首次使用 Checkpointer 之前完成。
await checkpointer.asetup()
"""
补充:
1. 当前 AsyncRedisSaver 还提供异步 setup() 兼容接口:
await checkpointer.setup()
2. 官方文档中也广泛使用:
await checkpointer.asetup()
3. 如果采用:
async with AsyncRedisSaver.from_conn_string(...) as checkpointer:
其异步上下文管理器会自动执行初始化。
因此一般不需要再次调用 asetup()。
4. 上面的示例采用外部 Redis 客户端,
因此由应用程序统一负责关闭 Redis Client 和 ConnectionPool。
"""
# ------------------------------------------------------------
# 5. 将 Checkpointer 传给 Agent
# ------------------------------------------------------------
from langchain.agents import create_agent
agent = create_agent(
model=llm,
tools=[],
# 指定持久化实现
# Agent 内部会通过它保存和恢复运行状态
checkpointer=checkpointer,
)
"""
Agent 与 Checkpointer 的关系:
Agent:
负责模型推理、工具调用、State 更新和执行流程。
Checkpointer:
负责持久化 State 的检查点。
Redis:
负责实际存储数据。
这里不需要给每个用户分别实例化一个 Agent。
通常一个应用进程可以复用一个 Agent 实例,
使用不同的 thread_id 来管理不同会话。
"""
# ------------------------------------------------------------
# 6. 配置 thread_id,区分不同用户和会话
# ------------------------------------------------------------
user_id = "user_001"
session_id = "session_001"
config = {
"configurable": {
"thread_id": f"{user_id}:{session_id}"
}
}
"""
config 必须注意:
正确:
"configurable"
错误:
"configuable"
thread_id 的设计:
user_001:session_001
user_001:session_002
user_002:session_001
效果:
- 同一用户的不同会话具有不同的 State。
- 不同用户的会话也相互隔离。
注意:
thread_id 只是存储层面的会话标识,不是权限校验机制。
生产环境应从已认证的用户身份生成或校验 thread_id,
不能直接信任前端传入的任意 user_id。
"""
# ------------------------------------------------------------
# 7. 调用 Agent,自动读取和保存短期记忆
# ------------------------------------------------------------
message = "你好,我叫小王"
result = await agent.ainvoke(
{
"messages": [
{
"role": "user",
"content": message
}
]
},
config=config,
)
# 获取最后一条消息
answer = result["messages"][-1].content
print(answer)
"""
这里的执行过程:
1. LangGraph 根据 config 中的 thread_id 查找已有检查点。
2. 如果当前会话已有 State,则加载最近的状态。
3. 将本轮用户消息加入 State.messages。
4. Agent 根据当前 State 进行推理。
5. LangGraph 在执行过程中自动保存 Checkpoint。
6. 最后返回包含最新状态的 result。
再次调用相同的 thread_id:
不需要手动添加历史对话。
不需要自己查询 Redis。
只需要传入当前新增的用户消息。
补充:
result["messages"][-1].content 通常是文本字符串,
但多模态模型或结构化内容场景也可能返回内容块列表。
因此生产接口应按实际模型输出类型进行处理。
"""
# ------------------------------------------------------------
# 8. 查看某个会话当前保存的 State
# ------------------------------------------------------------
snapshot = await agent.aget_state(config)
# 获取当前会话的 State
state = snapshot.values
# 获取历史消息
messages = state.get("messages", [])
for msg in messages:
print(msg.type, msg.content)
"""
aget_state(config):
- 获取指定 thread_id 的最新状态快照。
- snapshot.values 是该检查点中的 State 字段。
- snapshot.metadata 是相关执行元数据。
- snapshot.config 包含检查点配置信息。
注意:
aget_state() 是查看状态的接口。
普通聊天请求无需提前调用它;
agent.ainvoke() 本身就会通过 Checkpointer 恢复状态。
"""
# ------------------------------------------------------------
# 9. 程序退出时释放 Redis 资源
# ------------------------------------------------------------
await redis_client.aclose()
await pool.aclose()
"""
为什么需要显式关闭?
redis.asyncio 使用异步网络连接。
程序退出时,应主动释放客户端及连接池资源。
redis_client.aclose()
关闭 Redis 客户端所持有的资源。
pool.aclose()
关闭连接池中维护的连接。
如果 pool 在多个客户端之间共享,
应在所有使用它的任务和客户端结束后,再关闭整个连接池。
生产环境不要每次请求结束都关闭共享连接池。
应将其生命周期交给应用程序统一管理。
"""
# ============================================================
# 四、生产环境推荐:结合 FastAPI Lifespan
# ============================================================
"""
上面的代码主要用于理解各组件之间的关系。
实际 FastAPI 项目中,更推荐:
服务启动:
创建 Redis 连接池
↓
创建 Redis Client
↓
创建 AsyncRedisSaver
↓
初始化 Checkpointer
↓
创建 Agent
↓
将 Agent 注册到 app.state
服务运行:
不同请求复用 Agent 和 Redis Client,
使用各自的 thread_id 区分会话。
服务关闭:
停止提供服务
↓
释放 Redis Client
↓
关闭 Redis 连接池
下面是一份独立的 FastAPI 示例。
"""
# ===== main.py =====
import os
from contextlib import asynccontextmanager
import redis.asyncio as redis
from fastapi import FastAPI
from pydantic import BaseModel
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langgraph.checkpoint.redis.aio import AsyncRedisSaver
@asynccontextmanager
async def lifespan(app: FastAPI):
# 1. 服务启动:创建共享 Redis 连接池
pool = redis.ConnectionPool(
host=os.getenv("REDIS_HOST", "localhost"),
port=int(os.getenv("REDIS_PORT", "6379")),
db=int(os.getenv("REDIS_DB", "0")),
password=os.getenv("REDIS_PASSWORD") or None,
decode_responses=False,
max_connections=50,
socket_connect_timeout=5,
socket_timeout=15,
health_check_interval=30,
)
# 2. 创建共享 Redis Client
redis_client = redis.Redis(connection_pool=pool)
try:
# 3. 检查连接
await redis_client.ping()
# 4. 创建 Checkpointer
checkpointer = AsyncRedisSaver(
redis_client=redis_client,
ttl={
"default_ttl": 60 * 24 * 7,
"refresh_on_read": True,
},
)
# 5. 初始化检查点索引
await checkpointer.asetup()
# 6. 初始化 LLM
# MODEL_ID 例如:openai:gpt-5.5
# 对应模型的 API Key 等配置需提前设置。
llm = init_chat_model(os.environ["MODEL_ID"])
# 7. 创建 Agent
agent = create_agent(
model=llm,
tools=[],
checkpointer=checkpointer,
)
# 8. 保存为应用级共享对象
app.state.agent = agent
# yield 之后,FastAPI 开始正常处理请求
yield
finally:
# 9. 服务关闭:释放共享资源
app.state.agent = None
# 先关闭客户端,再关闭共享连接池
await redis_client.aclose()
await pool.aclose()
app = FastAPI(lifespan=lifespan)
# 定义请求体
class ChatRequest(BaseModel):
user_id: str
session_id: str
message: str
@app.post("/chat")
async def chat(request: ChatRequest):
"""
接口执行逻辑:
1. 从请求中获取用户信息和会话信息。
2. 生成对应的 thread_id。
3. 调用 Agent。
4. Agent 自动加载和保存当前会话的 State。
5. 返回本次回答。
注意:
此处接收 user_id 仅用于演示。
生产项目应从登录认证信息中获取 user_id,
并检查用户对 session_id 的访问权限。
"""
thread_id = f"{request.user_id}:{request.session_id}"
config = {
"configurable": {
"thread_id": thread_id
}
}
result = await app.state.agent.ainvoke(
{
"messages": [
{
"role": "user",
"content": request.message
}
]
},
config=config,
)
return {
"session_id": request.session_id,
"answer": result["messages"][-1].content,
}
# 启动命令:
# uv run uvicorn main:app --host 0.0.0.0 --port 8000
# ============================================================
# 五、需要掌握的其他注意事项
# ============================================================
"""
1. State 和 Checkpointer 不要混淆
State:
定义和承载 Agent 的运行状态。
Checkpointer:
负责保存、读取和恢复 State 的检查点。
Redis:
是 Checkpointer 的具体存储后端之一。
2. Checkpointer 和 Redis ConnectionPool 不要混淆
ConnectionPool:
复用 Redis 网络连接,提高连接管理效率。
AsyncRedisSaver:
实现 LangGraph 的检查点存储协议。
二者关注的层次不同。
3. Redis 持久化不等于模型上下文无限增长
Checkpointer 可以保存很多轮历史对话,
但是 LLM 的上下文窗口是有限的。
随着 messages 不断增加:
- Token 消耗增加。
- 推理成本增加。
- 响应速度可能下降。
- 可能超过模型上下文长度限制。
因此实际项目可能还需要:
- 保留最近 N 轮对话。
- 历史消息裁剪(Trimming)。
- 历史对话摘要(Summarization)。
- 将长期知识提取到 Store 或其他存储系统。
注意:
上述消息管理需要额外实现或配置相应 Middleware。
仅使用 Checkpointer 不会自动执行这些策略。
4. Redis 的 TTL 不等于模型消息裁剪
TTL:
控制 Redis 中检查点数据的生存时间。
消息裁剪:
控制进入 LLM 上下文的历史消息数量。
这两个机制解决的是不同的问题。
5. Agent 实例通常不需要按请求创建
推荐:
每个应用进程初始化一次 Agent。
多个请求复用该 Agent。
不同会话使用不同的 thread_id。
避免:
每次请求重新初始化模型、连接池和 Checkpointer。
注意:
多个 Worker 进程可能分别创建自己的 Agent 实例和连接池,
但可以连接同一个 Redis,访问共享的会话状态。
6. 并发请求与同一 thread_id
不同 thread_id:
一般可以并发调用 Agent。
相同 thread_id:
应避免多个请求同时修改同一个会话状态。
否则可能出现检查点分支、状态竞争或消息顺序问题。
生产项目可使用:
- 会话级队列。
- 分布式锁。
- 同一会话请求串行化。
注意:
asyncio.Lock 只在当前进程内生效,
多 Worker / 多实例部署时需要跨进程的并发控制。
7. 短期记忆和长期记忆的区别
短期记忆:
以 thread_id 为核心。
保存某个会话中的消息和执行状态。
通常通过 Checkpointer 实现。
长期记忆:
可以跨多个 thread_id 使用。
保存用户偏好、用户画像或提取出的知识。
可以通过 LangGraph Store 等机制实现。
同一个用户创建一个新会话时:
不会仅因为 user_id 相同,就自动继承之前会话的消息历史。
8. 整套机制的最终总结
Agent + State + Checkpointer + thread_id
Agent:
执行 LLM 推理及工具调用。
State:
保存执行状态和消息数据。
Checkpointer:
负责状态检查点的持久化和恢复。
thread_id:
区分独立会话,定位对应的状态历史。
Redis Client:
提供 Redis 操作能力。
ConnectionPool:
管理并复用 Redis 连接。
AsyncRedisSaver:
将 LangGraph Checkpointer 协议适配到 Redis。
FastAPI Lifespan:
统一管理这些共享资源的生命周期。
最终可以理解为:
用户请求
↓
FastAPI
↓
获取共享 Agent
↓
传入 thread_id + 本轮消息
↓
Checkpointer 从 Redis 恢复 State
↓
Agent 执行推理 / 工具调用
↓
State 更新
↓
Checkpointer 将检查点保存到 Redis
↓
返回回答
这是使用 LangChain / LangGraph 构建多用户、多会话 Agent
短期记忆系统的一种常见工程实现。
"""