跳转到主要内容

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_messageslangchain_core.messages按预算返回最近的消息子集
RemoveMessage(id=...)langchain_core.messages从线程状态删除指定消息
REMOVE_ALL_MESSAGESlanggraph.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