消息（Messages）

Alpha 版本提示： 本文档涵盖的是 v1-alpha 版本。内容尚不完整，且可能随时变更。如需查阅最新稳定版本，请参阅 v0 版本的 LangChain Python 文档或 LangChain JavaScript 文档。

在 LangChain 中，消息是模型上下文的基本单元。它们代表模型的输入和输出，既包含内容，也包含与大语言模型（LLM）交互时用于表示对话状态所需的元数据。消息对象包含以下组成部分：

角色 — 标识消息类型（例如 system、user）
内容 — 表示消息的实际内容（如文本、图像、音频、文档等）
元数据 — 可选字段，例如响应信息、消息 ID 和令牌用量

LangChain 提供了一种标准消息类型，可在所有模型提供商之间通用，确保无论调用哪个模型，行为都保持一致。

基本用法

使用消息最简单的方法是创建消息对象，并在调用模型时将其传入。

from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage, AIMessage, SystemMessage

model = init_chat_model("openai:gpt-5-nano")

system_msg = SystemMessage("你是一个乐于助人的助手。")
human_msg = HumanMessage("你好，你怎么样？")

# 与聊天模型一起使用
messages = [system_msg, human_msg]
response = model.invoke(messages)  # 返回 AIMessage

文本提示

文本提示是字符串，适用于不需要保留对话历史的简单生成任务。

response = model.invoke("写一首关于春天的俳句")

何时使用文本提示：

你有一个独立的单次请求
你不需要对话历史
你希望代码复杂度最低

消息提示

或者，你可以通过提供消息对象列表，将消息列表传递给模型。

from langchain_core.messages import SystemMessage, HumanMessage, AIMessage

messages = [
    SystemMessage("你是一位诗歌专家"),
    HumanMessage("写一首关于春天的俳句"),
    AIMessage("樱花绽放...")
]
response = model.invoke(messages)

何时使用消息提示：

管理多轮对话
处理多模态内容（图像、音频、文件）
包含系统指令

字典格式

你也可以直接使用 OpenAI 聊天补全格式指定消息。

messages = [
    {"role": "system", "content": "你是一位诗歌专家"},
    {"role": "user", "content": "写一首关于春天的俳句"},
    {"role": "assistant", "content": "樱花绽放..."}
]
response = model.invoke(messages)

消息类型

系统消息 — 告诉模型如何行为，并为交互提供上下文
人类消息 — 表示用户输入和与模型的交互
AI 消息 — 模型生成的响应，包括文本内容、工具调用和元数据
工具消息 — 表示工具调用的输出

系统消息

SystemMessage 代表一组初始指令，用于引导模型的行为。你可以使用系统消息来设定语气、定义模型的角色，并为响应建立准则。

基本指令

system_msg = SystemMessage("你是一个乐于助人的编程助手。")

messages = [
    system_msg,
    HumanMessage("我如何创建一个 REST API？")
]
response = model.invoke(messages)

详细角色设定

from langchain_core.messages import SystemMessage, HumanMessage

system_msg = SystemMessage("""
你是一位精通 Web 框架的资深 Python 开发者。
始终提供代码示例并解释你的推理过程。
解释要简洁但详尽。
""")

messages = [
    system_msg,
    HumanMessage("我如何创建一个 REST API？")
]
response = model.invoke(messages)

人类消息

HumanMessage 表示用户输入和交互。它们可以包含文本、图像、音频、文件以及其他任意数量的多模态内容。

文本内容

human_msg = HumanMessage("什么是机器学习？")
response = model.invoke([human_msg])

# 使用字符串是单个人类消息的快捷方式
response = model.invoke("什么是机器学习？")

消息元数据

添加元数据

human_msg = HumanMessage(
    content="你好！",
    name="alice",  # 可选：标识不同用户
    id="msg_123",  # 可选：用于追踪的唯一标识符
)

name 字段的行为因提供商而异——有些将其用于用户标识，有些则忽略它。要确认，请参考模型提供商的@[reference][参考文档]。

AI 消息

AIMessage 表示模型调用的输出。它们可以包含多模态数据、工具调用和提供商特定的元数据，供你后续访问。

response = model.invoke("解释人工智能")
print(type(response))  # <class 'langchain_core.messages.AIMessage'>

当调用模型时，会返回 AIMessage 对象，其中包含响应中的所有关联元数据。但这并不意味着只能从该处创建或修改它们。不同的提供商对消息类型的权重/上下文处理方式不同，因此有时手动创建一个新的 AIMessage 对象并将其插入消息历史中（如同它来自模型一样）会很有帮助。

from langchain_core.messages import AIMessage, SystemMessage, HumanMessage

# 手动创建 AI 消息（例如用于对话历史）
ai_msg = AIMessage("我很乐意帮你解答这个问题！")

# 添加到对话历史
messages = [
    SystemMessage("你是一个乐于助人的助手"),
    HumanMessage("你能帮我吗？"),
    ai_msg,  # 插入，如同来自模型
    HumanMessage("太好了！2+2 等于多少？")
]

response = model.invoke(messages)

属性

string

消息的文本内容。

string | dict[]

消息的原始内容。

ContentBlock[]

消息的标准化内容块。

dict[] | None

模型调用的工具。若未调用工具则为空。

string

消息的唯一标识符（由 LangChain 自动生成或由提供商响应返回）

dict | None

消息的用量元数据，在可用时可包含令牌计数。

ResponseMetadata | None

消息的响应元数据。

工具调用响应

当模型调用工具时，这些调用会包含在 AI 消息中：

工具调用

model_with_tools = model.bind_tools([GetWeather])
response = model_with_tools.invoke("巴黎的天气如何？")

for tool_call in response.tool_calls:
    print(f"工具: {tool_call['name']}")
    print(f"参数: {tool_call['args']}")
    print(f"ID: {tool_call['id']}")

流式传输与分块

在流式传输过程中，你会收到 AIMessageChunk 对象，可以将它们合并：

chunks = []
for chunk in model.stream("写一首诗"):
    chunks.append(chunk)
    print(chunk.text)

from langchain_core.messages import AIMessage

# 将分块合并为最终消息
final_message = sum(chunks, AIMessage(""))
print(f"完整响应: {final_message.text}")

工具消息

对于支持工具调用的模型，AI 消息可以包含工具调用。工具消息用于将单个工具执行的结果传递回模型。

# 模型进行工具调用后
ai_message = AIMessage(
    content=[],
    tool_calls=[{
        "name": "get_weather",
        "args": {"location": "旧金山"},
        "id": "call_123"
    }]
)

# 执行工具并创建结果消息
weather_result = "晴天，72°F"
tool_message = ToolMessage(
    content=weather_result,
    tool_call_id="call_123"  # 必须与调用 ID 匹配
)

# 继续对话
messages = [
    HumanMessage("旧金山的天气如何？"),
    ai_message,  # 模型的工具调用
    tool_message,  # 工具执行结果
]
response = model.invoke(messages)  # 模型处理结果

属性

string

required

工具调用的字符串化输出。

string

required

此消息所响应的工具调用 ID。（必须与 AI 消息中的工具调用 ID 匹配）

string

required

被调用的工具名称。

dict

不发送给模型但可编程访问的附加数据。

artifact 字段存储不会发送给模型但可编程访问的补充数据。这对于存储原始结果、调试信息或用于下游处理的数据非常有用，而不会使模型上下文变得混乱。

示例：使用 artifact 存储原始数据

from langchain_core.messages import ToolMessage
import json

# 工具执行返回结构化数据
raw_data = {"temperature": 72, "condition": "晴天"}
tool_message = ToolMessage(
    content="天气晴朗，气温为 72°F。",
    tool_call_id="call_123",
    name="get_weather",
    artifact={"raw_data": raw_data}  # 存储结构化数据
)

# 稍后，以编程方式访问原始数据
weather_info = tool_message.artifact.get("raw_data")
print(f"原始天气数据: {json.dumps(weather_info)}")

内容

你可以将消息的内容视为发送给模型的数据载荷。消息具有一个 content 属性，其类型较为宽松，支持字符串和未类型化对象（例如字典）的列表。这使得 LangChain 聊天模型可以直接支持提供商原生结构，例如多模态内容和其他数据。此外，LangChain 为文本、推理、引用、多模态数据、服务器端工具调用及其他消息内容提供了专用的内容类型。请参见下面的标准内容块。 LangChain 聊天模型接受消息内容的 .content 属性，可以包含：

一个字符串
一个提供商原生格式的内容块列表
一个 LangChain 标准内容块列表

请参见以下使用多模态输入的示例：

from langchain_core.messages import HumanMessage

# 字符串内容
human_message = HumanMessage("你好，你怎么样？")

# 提供商原生格式（例如 OpenAI）
human_message = HumanMessage(content=[
    {"type": "text", "text": "你好，你怎么样？"},
    {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
])

# 标准内容块列表
human_message = HumanMessage(content_blocks=[
    {"type": "text", "text": "你好，你怎么样？"},
    {"type": "image", "url": "https://example.com/image.jpg"},
])

在初始化消息时指定 content_blocks 仍会填充消息的 content，但提供了类型安全的接口。

标准内容块

LangChain 维护了一组跨提供商的标准消息内容类型（请参见下面的参考部分）。消息还实现了一个 content_blocks 属性，它会将 content 属性惰性解析为这种标准的类型安全表示。例如，从 ChatAnthropic 或 ChatOpenAI 生成的消息将包含各自提供商格式的 thinking 或 reasoning 块，但这些块可以惰性解析为一致的 ReasoningContentBlock 表示：

Anthropic
OpenAI

from langchain_core.messages import AIMessage

message = AIMessage(
    content=[
        {"type": "thinking", "thinking": "...", "signature": "WaUjzkyp..."},
        {"type": "text", "text": "..."},
    ],
    response_metadata={"model_provider": "anthropic"}
)
message.content_blocks

[{'type': 'reasoning',
  'reasoning': '...',
  'extras': {'signature': 'WaUjzkyp...'}},
 {'type': 'text', 'text': '...'}]

from langchain_core.messages import AIMessage

message = AIMessage(
    content=[
        {
            "type": "reasoning",
            "id": "rs_abc123",
            "summary": [
                {"type": "summary_text", "text": "摘要 1"},
                {"type": "summary_text", "text": "摘要 2"},
            ],
        },
        {"type": "text", "text": "...", "id": "msg_abc123"},
    ],
    response_metadata={"model_provider": "openai"}
)
message.content_blocks

[{'type': 'reasoning', 'id': 'rs_abc123', 'reasoning': '摘要 1'},
 {'type': 'reasoning', 'id': 'rs_abc123', 'reasoning': '摘要 2'},
 {'type': 'text', 'text': '...', 'id': 'msg_abc123'}]

请参阅集成指南以开始使用你选择的推理提供商。

序列化标准内容如果 LangChain 之外的应用程序需要访问标准内容块表示，你可以选择将内容块存储在消息内容中。为此，你可以将 LC_OUTPUT_VERSION 环境变量设置为 v1。或者，在初始化任何聊天模型时设置 output_version="v1"：

from langchain.chat_models import init_chat_model

model = init_chat_model("openai:gpt-5-nano", output_version="v1")

多模态

多模态是指能够处理以不同形式出现的数据，例如文本、音频、图像和视频。LangChain 包含了跨提供商使用的这些数据的标准类型。聊天模型可以接受多模态数据作为输入并生成多模态数据作为输出。下面我们展示了一些包含多模态数据的输入消息的简短示例：

# 来自 URL
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "描述这张图像的内容。"},
        {"type": "image", "url": "https://example.com/path/to/image.jpg"},
    ]
}

# 来自 base64 数据
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "描述这张图像的内容。"},
        {
            "type": "image",
            "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
            "mime_type": "image/jpeg",
        },
    ]
}

# 来自提供商管理的文件 ID
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "描述这张图像的内容。"},
        {"type": "image", "file_id": "file-abc123"},
    ]
}

# 来自 URL
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "描述此文档的内容。"},
        {"type": "file", "url": "https://example.com/path/to/document.pdf"},
    ]
}

# 来自 base64 数据
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "描述此文档的内容。"},
        {
            "type": "file",
            "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
            "mime_type": "application/pdf",
        },
    ]
}

# 来自提供商管理的文件 ID
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "描述此文档的内容。"},
        {"type": "file", "file_id": "file-abc123"},
    ]
}

# 来自 base64 数据
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "描述此音频的内容。"},
        {
            "type": "audio",
            "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
            "mime_type": "audio/wav",
        },
    ]
}

# 来自提供商管理的文件 ID
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "描述此音频的内容。"},
        {"type": "audio", "file_id": "file-abc123"},
    ]
}

# 来自 base64 数据
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "描述此视频的内容。"},
        {
            "type": "video",
            "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
            "mime_type": "video/mp4",
        },
    ]
}

# 来自提供商管理的文件 ID
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "描述此视频的内容。"},
        {"type": "video", "file_id": "file-abc123"},
    ]
}

并非所有模型都支持所有文件类型。请查阅模型提供商的参考文档以了解支持的格式和大小限制。

内容块参考

内容块（无论是创建消息时还是访问 content_blocks 属性时）均表示为类型化字典列表。列表中的每一项必须符合以下块类型之一：

核心

TextContentBlock

用途： 标准文本输出

string

required

始终为 "text"

string

required

文本内容

object[]

文本的注释列表

object

额外的提供商特定数据

示例：

{
    "type": "text",
    "text": "Hello world",
    "annotations": []
}

ReasoningContentBlock

用途： 模型推理步骤

string

required

始终为 "reasoning"

string

推理内容

object

额外的提供商特定数据

示例：

{
    "type": "reasoning",
    "reasoning": "用户正在询问关于...",
    "extras": {"signature": "abc123"},
}

多模态

ImageContentBlock

用途： 图像数据

string

required

始终为 "image"

string

指向图像位置的 URL。

string

Base64 编码的图像数据。

string

对外部存储图像的引用 ID（例如，在提供商的文件系统或存储桶中）。

string

图像 MIME 类型（例如，image/jpeg、image/png）

AudioContentBlock

用途： 音频数据

string

required

始终为 "audio"

string

指向音频位置的 URL。

string

Base64 编码的音频数据。

string

对外部存储音频文件的引用 ID（例如，在提供商的文件系统或存储桶中）。

string

音频 MIME 类型（例如，audio/mpeg、audio/wav）

VideoContentBlock

用途： 视频数据

string

required

始终为 "video"

string

指向视频位置的 URL。

string

Base64 编码的视频数据。

string

对外部存储视频文件的引用 ID（例如，在提供商的文件系统或存储桶中）。

string

视频 MIME 类型（例如，video/mp4、video/webm）

FileContentBlock

用途： 通用文件（PDF 等）

string

required

始终为 "file"

string

指向文件位置的 URL。

string

Base64 编码的文件数据。

string

对外部存储文件的引用 ID（例如，在提供商的文件系统或存储桶中）。

string

文件 MIME 类型（例如，application/pdf）

PlainTextContentBlock

用途： 文档文本（.txt、.md）

string

required

始终为 "text-plain"

string

文本内容

string

文本的 MIME 类型（例如，text/plain、text/markdown）

工具调用

ToolCall

用途： 函数调用

string

required

始终为 "tool_call"

string

required

要调用的工具名称

object

required

传递给工具的参数

string

required

此工具调用的唯一标识符

示例：

{
    "type": "tool_call",
    "name": "search",
    "args": {"query": "weather"},
    "id": "call_123"
}

ToolCallChunk

用途： 流式工具片段

string

required

始终为 "tool_call_chunk"

string

正在调用的工具名称

string

部分工具参数（可能是不完整的 JSON）

string

工具调用标识符

number

此块在流中的位置

InvalidToolCall

用途： 格式错误的调用，旨在捕获 JSON 解析错误。

string

required

始终为 "invalid_tool_call"

string

调用失败的工具名称

string

未能解析的原始参数

string

错误描述

服务器端工具执行

WebSearchCall

用途： 内置网页搜索

string

required

始终为 "web_search_call"

string

要执行的搜索查询

WebSearchResult

用途： 搜索结果

string

required

始终为 "web_search_result"

string[]

搜索结果的 URL

返回： 附带 URL 的顶级搜索结果。

CodeInterpreterCall

用途： 代码执行

string

required

始终为 "code_interpreter_call"

string

要执行的编程语言（例如 python、javascript、sql）

string

要执行的代码

CodeInterpreterResult

用途： 执行结果

string

required

始终为 "code_interpreter_result"

CodeInterpreterOutput[]

代码执行的输出

提供商特定块

NonStandardContentBlock

用途： 提供商特定的转义机制

string

required

始终为 "non_standard"

object

required

提供商特定的数据结构

用法： 用于实验性或提供商独有的功能

其他提供商特定的内容类型可在每个模型提供商的参考文档中找到。

内容块是在 LangChain v1 中作为消息的新属性引入的，旨在跨提供商标准化内容格式，同时保持与现有代码的向后兼容性。内容块并非 content 属性的替代品，而是一个新属性，可用于以标准化格式访问消息内容。

示例

多轮对话

构建对话应用程序需要管理消息历史和上下文：

from langchain_core.messages import HumanMessage, AIMessage

# 初始化对话
messages = [
    SystemMessage("您是一位专门研究 Python 编程的助手")
]

# 模拟多轮对话
while True:
    user_input = input("您: ")
    if user_input.lower() == "quit":
        break

    # 添加用户消息
    messages.append(HumanMessage(user_input))

    # 获取模型响应
    response = model.invoke(messages)

    # 将助手响应添加到历史记录中
    messages.append(response)

    print(f"助手: {response.content}")

from langchain_core.messages import filter_messages

def manage_conversation_window(messages, max_messages=10):
    """仅保留系统消息和最后 N 条消息"""
    system_msgs = filter_messages(messages, include_types="system")
    recent_msgs = messages[-(max_messages-len(system_msgs)):]
    return system_msgs + recent_msgs

# 在对话循环中使用
while True:
    user_input = input("您: ")
    messages.append(HumanMessage(user_input))

    # 修剪对话以适应上下文窗口
    messages = manage_conversation_window(messages)

    response = model.invoke(messages)
    messages.append(response)

快速开始

核心组件

进阶使用

在生产环境使用

基本用法

文本提示

消息提示

字典格式

消息类型

系统消息

人类消息

文本内容

消息元数据

AI 消息

工具调用响应

流式传输与分块

工具消息

内容

标准内容块

多模态

内容块参考

示例

多轮对话

​基本用法

​文本提示

​消息提示

​字典格式

​消息类型

​系统消息

​人类消息

​文本内容

​消息元数据

​AI 消息

​工具调用响应

​流式传输与分块

​工具消息

​内容

​标准内容块

​多模态

​内容块参考

​示例

​多轮对话

基本用法

文本提示

消息提示

字典格式

消息类型

系统消息

人类消息

文本内容

消息元数据

AI 消息

工具调用响应

流式传输与分块

工具消息

内容

标准内容块

多模态

内容块参考

示例

多轮对话