理解 LangChain的Runnable RunnableWithMessageHistory

花半天时间搞明白了 RunnableWithMessageHistory、get_session_history、MessagesPlaceholder等概念的机制和用法后，才发现对于实现带消息历史的简单聊天机器人demo代码，langChain官方在V0.3版升级为用 LangGraph 实现。长远来说，langChain未来版本大概率会被弃用RunnableWithMessageHistory 。但还是把对RunnableWithMessageHistory学习的理解记录一下吧。

Runnable 不是 Python 语言中的保留字，Python 语言本身没有 Runnable 类型或规范。Python 编程中提到 Runnable，通常只是自然语言中 Runnable 作为名词或形容词的用法，泛指“可运行的对象”，通常与 callable 等价。

但在 LangChain 等特定框架或语境下，Runnable 有明确的定义和规范，例如必须实现 invoke()、batch()、stream() 等方法，以支持结构化的数据流处理。

LangChain中可以通过 RunnableLambda 把普通函数封装成 Runnable，从而拥有invoke()、 batch()、stream()方法

# https://python.langchain.com/v0.2/docs/tutorials/chatbot/

from langchain_core.chat_history import (
    BaseChatMessageHistory,
    InMemoryChatMessageHistory,
)
from langchain_core.runnables.history import RunnableWithMessageHistory

store = {}


def get_session_history(session_id: str) -> BaseChatMessageHistory:
    if session_id not in store:
        store[session_id] = InMemoryChatMessageHistory()
    return store[session_id]


with_message_history = RunnableWithMessageHistory(model, get_session_history)

这是LangChain V0.2 官方在文档《构建简单聊天机器人》的范例代码，里面使用RunnableWithMessageHistory的逻辑对于初学者来说有点绕。想实现标准化聊天历史管理，用原生代码自定义一个函数来实现逻辑也不复杂，反而很直观容易理解。那为什么要设计RunnableWithMessageHistory呢，重要原因是为了便于链式调用，因为Runnable才能拼接链式调用啊。还有就是让Runnable 组件与消息历史解耦。

RunnableWithMessageHistory 的意义：

1. 标准化聊天历史管理
2. 便于链式调用
3. 让Runnable 组件与消息历史解耦

我们尝试通过原生代码来实现这个功能，就可以理解RunnableWithMessageHistory的机制了。

1. 定义聊天历史存储

我们使用一个全局 store 变量作为 聊天历史存储：

from langchain_core.messages import AIMessage, HumanMessage,SystemMessage
from langchain_openai import ChatOpenAI
from dotenv import load_dotenv
load_dotenv()
model = ChatOpenAI(model='deepseek-r1')

# 用字典存储聊天历史
store = {}

def get_session_history(session_id):
    """ 获取某个 session_id 的聊天历史 """
    return store.get(session_id, [])

def save_session_history(session_id, new_messages):
    """ 更新 session_id 的聊天历史 """
    if session_id not in store:
        store[session_id] = []
    store[session_id].extend(new_messages)

最终会生成 ：store['my_topic_123456']=[(user的第1次input), (AI的第1次response), (user的第2次input), (AI的第2次response), (user的第3次input), (AI的第3次response),.....]

store['33874550'] = [
    HumanMessage(content="你好，今天天气怎么样？"),
    AIMessage(content="今天是晴天，温度25℃。"),
    HumanMessage(content="明天呢？"),
    AIMessage(content="明天狂风暴雨，气温骤降10度！")
]

注意，这里用的是.extend()而不是.append()，说明new_messages也是一个list，包含了input_message和output_message。

2.运行 链式调用 并手动管理历史

流程：  获取历史消息 -> 构造输入 -> 调用接口获取AI的回答 ->更新历史

def chat_with_history(session_id, user_input):
    """ 处理聊天，并手动管理聊天历史 """

    history = get_session_history(session_id)    # 获取当前会话的历史记录

    input_data =[SystemMessage(content="You are a helpful assistant. Answer all questions to the best of your ability")] + history + [HumanMessage(content=user_input)]
    print(input_data)

    response = model.invoke(input_data)

    # 更新历史（添加用户输入和 AI 回复）
    new_messages = [HumanMessage(content=user_input), AIMessage(content=response.content)]
    save_session_history(session_id, new_messages)

    return response.content


# 测试
session_id = "my_topic_123456"
print(chat_with_history(session_id,  "Hi! I'm Bob"))
print(chat_with_history(session_id,  "What's my name?"))

可见，每个回合的 (user_input 和 response.content) 都被追加到 store['my_topic_123456']=[(对话信息第1回合),(对话信息第2回合),(对话信息第3回合).....] 中去，并作为history参数值传入下一个回合的对话中。

当用户再新建一个会话的时候，讨论另一个领域的话题，就可以用一个新的session_id来标识新的一轮聊天历史记录了。

再对比看回官方文档中的完整代码(有删改)：

from langchain_core.messages import HumanMessage
from langchain_openai import ChatOpenAI
from dotenv import load_dotenv
load_dotenv()
model = ChatOpenAI(model='deepseek-r1')


from langchain_core.chat_history import InMemoryChatMessageHistory
from langchain_core.runnables.history import RunnableWithMessageHistory

store = {}


def get_session_history(session_id):
    if session_id not in store:
        store[session_id] = InMemoryChatMessageHistory() # 创建一个InMemoryChatMessageHistory对象，用于保存session_id=xxxx的聊天历史记录。
    return store[session_id]


with_message_history = RunnableWithMessageHistory(model, get_session_history)

config = {"configurable": {"session_id": "abc2"}}

response = with_message_history.invoke(
    [HumanMessage(content="Hi! I'm Bob")],
    config=config,
)

print(response.content)

response = with_message_history.invoke(
    [HumanMessage(content="What's my name?")],
    config=config,
)

print(response.content)

RunnableWithMessageHistory 通过 get_session_history(‘abc2’) 获得 ChatMessageHistory 对象(这里具体是InMemoryChatMessageHistory)，还会在收到AI回复后将回复信息追加到这个对象中。

with_message_history这个Runnable 通过 config = {"configurable": {"session_id": "abc2"}} 配置 get_session_history 的 session_id参数值。 （这跟常规的直接传递参数有点不一样）

最终实现【让Runnable 组件与消息历史解耦】 , 无需显式地处理 history。

-------------------

 MessagesPlaceholder 在 Prompt 模板中动态插入一组消息,  主要用于“历史对话消息”相关的场景，当然，其他场景也可以用，例如FAQ 系统中 用 MessagesPlaceholder 来填充知识库问答，然后让 AI 生成回答，还可以把附件/附加信息填充进去。

2. MessagesPlaceholder 的基本用法

from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

# 创建一个 Prompt 模板，其中 `history` 是历史消息的占位符
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个智能助手，可以帮助用户回答问题。"),
    MessagesPlaceholder(variable_name="history"),  # 插入历史消息
    ("human", "{input}")  # 插入用户当前输入
])

# 示例：填充 Prompt
messages = [
    ("human", "你好，你是谁？"),
    ("ai", "我是一个 AI 助手，可以帮助你回答问题。")
]

formatted_prompt = prompt.format(history=messages, input="你能做什么？")
print(formatted_prompt)

最终生成的 Prompt：

系统消息：你是一个智能助手，可以帮助用户回答问题。
用户：你好，你是谁？
AI：我是一个 AI 助手，可以帮助你回答问题。
用户：你能做什么？