LangChain
14 · 记忆系统
checkpointer 与 middleware
- LangChain
- Python
本节速览
这一节的每一块内容,分别是干什么的:
| 内容 | 是干什么的 |
|---|---|
| InMemorySaver(checkpointer) | agent 的短期记忆,按 thread_id 持久化会话 |
| SummarizationMiddleware | 历史超长自动摘要成一段,腾出上下文 |
| 自定义 middleware | 裁剪、删除消息,精确控制模型看到多少 |
| 自管理消息历史 | 不用 agent 时自己存取历史、注入 prompt |
LLM 本身无状态,多轮对话靠应用侧存储聊天记录并注入上下文。0.1.x 的 Memory 类家族(ConversationBufferMemory 等)0.2 起废弃,1.x 已移除。现行方案构建在 LangGraph 架构上:存储交给 checkpointer,加工交给 middleware(LangGraph 本身的拆解见 LangGraph 基础)。
两层抽象
| 层 | 职责 | 1.x 实现 |
|---|---|---|
| 存储层(chat history) | 忠实记录、完整存取消息序列,按会话隔离 | checkpointer:InMemorySaver / PostgresSaver,会话标识是 thread_id |
| 加工层(memory) | 决定每次注入多少上下文:裁剪、摘要 | middleware:SummarizationMiddleware、自写钩子 |
存储层永远保存全量,任意时刻可回放整条会话;加工层只影响「模型看到多少」,可随时替换。thread_id 对应旧版的 session_id。
InMemorySaver:agent 的短期记忆
没有它会怎样——不加 checkpointer,同一用户的第二句话进来,模型眼里是全新会话:上一句「我叫小明」,这句问「我叫什么」,它一脸茫然,每个 thread 都失忆。
有了它——invoke 时带 thread_id,状态自动持久化,同 thread 下次调用自动带全套历史。
agent 的每次 invoke 都会更新内部 messages 状态。配上 checkpointer 后,状态按 thread 持久化,同一 thread 的下次调用自动带上全部历史:
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain.agents import create_agent # 创建 agent
from langgraph.checkpoint.memory import InMemorySaver # 内存版记忆持久化
load_dotenv()
llm = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
agent = create_agent(
llm,
system_prompt="你是一个乐于助人的助手",
checkpointer=InMemorySaver(),
)
config = {"configurable": {"thread_id": "1"}}
res1 = agent.invoke({"messages": [{"role": "user", "content": "hi, 我叫小明"}]}, config)
print(res1["messages"][-1].content) # 你好,小明!
res2 = agent.invoke({"messages": [{"role": "user", "content": "我的名字叫什么?"}]}, config)
print(res2["messages"][-1].content) # 你叫小明。
要点:
- 输入的 messages 是本轮增量,框架负责追加到线程状态,不要手动拼历史。也接受纯字符串。
- 输出的
result["messages"]是该线程完整消息序列,[-1]即本轮回复。 thread_id隔离会话:换成"2"再问名字,模型一无所知。带 checkpointer 的调用必须传 thread_id,缺失直接报错。InMemorySaver重启即丢,适合开发调试。生产换PostgresSaver,前提是有一个能连上的 Postgres 实例,DATABASE_URL是它的连接串,形如postgresql://用户名:密码@localhost:5432/记忆库名:
import os # 读取环境变量
from langgraph.checkpoint.postgres import PostgresSaver # Postgres 版记忆持久化
checkpointer = PostgresSaver.from_conn_string(os.environ["DATABASE_URL"])
# create_agent(..., checkpointer=checkpointer),其余代码不变
SummarizationMiddleware:摘要记忆
没有它会怎样——历史全量注入,聊到二三十轮,上下文被老黄历占满:费用线性上涨,最新指令反而可能被挤出窗口,模型开始「忘事」。
有了它——超过阈值自动把早期历史压成一段摘要,上下文体积恒定,梗概记得住、新话装得下。
全量注入有两个问题:token 随轮数线性增长;无关历史分散注意力。摘要中间件在消息量达到阈值时,把旧消息压成一条摘要,同时保留最近若干条原文:
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain.agents import create_agent # 创建 agent
from langchain.agents.middleware import SummarizationMiddleware # 历史摘要中间件
from langgraph.checkpoint.memory import InMemorySaver # 内存版记忆持久化
load_dotenv()
llm = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
agent = create_agent(
llm,
checkpointer=InMemorySaver(),
middleware=[
SummarizationMiddleware(
llm, # 摘要交给便宜模型
trigger=("tokens", 4000), # 线程超过 4000 token 触发
keep=("messages", 20), # 压缩后保留最近 20 条原文
),
],
)
短对话零额外开销,长对话才压缩。压缩后的状态是一条摘要加最近 20 条原文,近期细节与远期记忆并存。工具调用轮次多的 agent 历史膨胀更快,这条中间件是标配。摘要指令可用 summary_prompt 参数自定义。
裁剪与删除:自定义 middleware
没有它会怎样——想要「保留第一句人设 + 最近 20 条」这种精确控制,内置开关没有,只能整段硬塞或粗暴砍半。
有了它——middleware 在每次调用前加工 messages,裁剪、删除、改写想怎么来怎么来。
更硬的控制是直接裁剪与删除。三个 API:
| API | 来源 | 职责 |
|---|---|---|
trim_messages | langchain_core.messages | 按预算返回最近的消息子集 |
RemoveMessage(id=...) | langchain_core.messages | 从线程状态删除指定消息 |
REMOVE_ALL_MESSAGES | langgraph.graph.message | 哨兵 id,配合 RemoveMessage 一次清空 |
自定义中间件继承 AgentMiddleware,覆写 before_model(模型调用前)或 after_model(调用后)钩子:
from typing import Any # 任意类型注解
from langchain.agents.middleware import AgentMiddleware # 自定义中间件基类
from langchain_core.messages import RemoveMessage, trim_messages # 删除消息、按预算裁剪
from langgraph.graph.message import REMOVE_ALL_MESSAGES # 清空全部消息的哨兵
class TrimHistoryMiddleware(AgentMiddleware):
"""模型调用前按预算裁剪历史"""
def before_model(self, state) -> dict[str, Any]:
trimmed = trim_messages(
state["messages"],
max_tokens=384,
strategy="last", # 从最新向前保留
start_on="human", # 结果必须以 human 消息开头
end_on=("human", "tool"), # 不得以悬空的 tool 消息结尾
token_counter=len, # 演示用条数近似;工程按主模型 tokenizer
)
return {
"messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES), *trimmed],
}
删除指定消息(不做整体替换)时,按 id 逐条删。比如每轮调用后删掉最早的两条:
from typing import Any # 任意类型注解
from langchain.agents.middleware import AgentMiddleware # 自定义中间件基类
from langchain_core.messages import RemoveMessage # 删除指定消息
class DeleteOldMiddleware(AgentMiddleware):
"""模型调用后删除最早的两条消息"""
def after_model(self, state) -> dict[str, Any]:
return {
"messages": [RemoveMessage(id=m.id) for m in state["messages"][:2]],
}
两个例子对应两个钩子:裁剪在 before_model(模型看到之前处理),删除在 after_model(模型回复之后清理)。
坑:
- AI 消息的 tool_calls 与对应 tool 结果必须成对出现,裁剪切掉一头会直接报错。
start_on/end_on就是守住这类边界的。 - 这类 middleware 修改的是持久化的线程状态,裁掉的消息不可恢复,与摘要方案是不同的取舍。
自管理消息历史:不依赖 agent 的持久化
没有它会怎样——用的是普通 chain 不是 agent,checkpointer 那套够不着,多轮对话每轮都失忆。
有了它——历史自己存(内存 / Redis),每轮用 MessagesPlaceholder 注入,chain 也有多轮能力。
纯 LCEL chain 也常需要跨进程历史。做法是绕开框架抽象,直接用标准库读写消息 JSON,注入靠 MessagesPlaceholder:
# file_history.py
import json # 处理 JSON 字符串
from pathlib import Path # 文件路径操作
from langchain_core.messages import AIMessage, HumanMessage # 模型与用户消息
ROLE_TO_CLASS = {"human": HumanMessage, "ai": AIMessage}
def load_history(session_id):
file = Path("chat_data") / f"{session_id}.json"
if file.exists():
records = json.loads(file.read_text(encoding="utf-8"))
return [ROLE_TO_CLASS[r["role"]](r["content"]) for r in records]
return []
def save_history(session_id, messages):
file = Path("chat_data") / f"{session_id}.json"
file.parent.mkdir(parents=True, exist_ok=True)
file.write_text(
json.dumps(
[{"role": m.type, "content": m.content} for m in messages],
ensure_ascii=False, indent=2,
),
encoding="utf-8",
)
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder # 消息模板与历史插槽
from langchain_core.messages import AIMessage, HumanMessage # 消息对象
from langchain_core.output_parsers import StrOutputParser # 提取纯文本
from pathlib import Path # 文件路径
import json # 读写历史
load_dotenv()
llm = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
prompt = ChatPromptTemplate.from_messages([
{"role": "system", "content": "你是一个乐于助人的助手"},
MessagesPlaceholder("history"),
{"role": "human", "content": "{input}"},
])
chain = prompt.pipe(llm).pipe(StrOutputParser())
ROLE_TO_CLASS = {"human": HumanMessage, "ai": AIMessage}
def load_history(session_id):
file = Path("chat_data") / f"{session_id}.json"
if file.exists():
records = json.loads(file.read_text(encoding="utf-8"))
return [ROLE_TO_CLASS[r["role"]](r["content"]) for r in records]
return []
def save_history(session_id, messages):
file = Path("chat_data") / f"{session_id}.json"
file.parent.mkdir(parents=True, exist_ok=True)
file.write_text(
json.dumps(
[{"role": m.type, "content": m.content} for m in messages],
ensure_ascii=False, indent=2,
),
encoding="utf-8",
)
def chat(session_id, user_input):
history = load_history(session_id)
output = chain.invoke({"history": history, "input": user_input})
save_history(session_id, [*history, HumanMessage(user_input), AIMessage(output)])
return output
要点:
- 读写时机在 chain 之外,持久化与 chain 解耦。磁盘存
{role, content},格式稳定、可读。 - 实现是「读全量、追加、写全量」,并发写会互相覆盖。接数据库时改成原子追加,只动 load/save 两个函数。
- 分工:agent 一律用 checkpointer;自管理方案留给「chain + 手动历史」的轻量场景。
上一节:完整 RAG 链 · 下一节:Function Calling