消息 - Docs by LangChain中文

消息是 LangChain 中模型上下文的基本单位。它们代表了模型的输入和输出，既承载内容，也携带在与 LLM 交互时表达对话状态所需的元数据。消息是包含以下内容的对象：

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

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

基本用法

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

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

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

system_msg = SystemMessage("You are a helpful assistant.")
human_msg = HumanMessage("Hello, how are you?")

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

多轮智能体会积累很长的消息历史记录。LangSmith 会记录每一轮、工具结果和模型响应，以便你检查完整对话。请遵循追踪快速入门来启用追踪。我们建议你同时设置 LangSmith Engine，它可以监控你的追踪、检测问题并提出修复建议。

文本提示

文本提示是字符串 - 非常适合不需要保留对话历史的简单生成任务。

response = model.invoke("Write a haiku about spring")

在以下情况下使用文本提示：

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

消息提示

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

from langchain.messages import SystemMessage, HumanMessage, AIMessage

messages = [
    SystemMessage("You are a poetry expert"),
    HumanMessage("Write a haiku about spring"),
    AIMessage("Cherry blossoms bloom...")
]
response = model.invoke(messages)

在以下情况下使用消息提示：

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

字典格式

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

messages = [
    {"role": "system", "content": "You are a poetry expert"},
    {"role": "user", "content": "Write a haiku about spring"},
    {"role": "assistant", "content": "Cherry blossoms bloom..."}
]
response = model.invoke(messages)

消息类型

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

系统消息

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

基本指令

system_msg = SystemMessage("You are a helpful coding assistant.")

messages = [
    system_msg,
    HumanMessage("How do I create a REST API?")
]
response = model.invoke(messages)

详细角色设定

from langchain.messages import SystemMessage, HumanMessage

system_msg = SystemMessage("""
You are a senior Python developer with expertise in web frameworks.
Always provide code examples and explain your reasoning.
Be concise but thorough in your explanations.
""")

messages = [
    system_msg,
    HumanMessage("How do I create a REST API?")
]
response = model.invoke(messages)

用户消息

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

文本内容

response = model.invoke([
  HumanMessage("What is machine learning?")
])

# 使用字符串是创建单个 HumanMessage 的快捷方式
response = model.invoke("What is machine learning?")

消息元数据

添加元数据

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

name 字段的行为因提供商而异——有些用于用户识别，有些则忽略。要检查，请参阅模型提供商的参考文档。

AI 消息

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

response = model.invoke("Explain AI")
print(type(response))  # <class 'langchain.messages.AIMessage'>

AIMessage 对象在模型调用时被返回，其中包含响应中的所有关联元数据。提供商对不同类型的消息有不同的加权/上下文化方式，这意味着有时手动创建一个新的 AIMessage 对象并将其插入到消息历史记录中，就好像它来自模型一样，会很有帮助。

from langchain.messages import AIMessage, SystemMessage, HumanMessage

# 手动创建 AI 消息（例如，用于对话历史）
ai_msg = AIMessage("I'd be happy to help you with that question!")

# 添加到对话历史
messages = [
    SystemMessage("You are a helpful assistant"),
    HumanMessage("Can you help me?"),
    ai_msg,  # 像是来自模型一样插入
    HumanMessage("Great! What's 2+2?")
]

response = model.invoke(messages)

属性

string

消息的文本内容。

string | dict[]

消息的原始内容。

ContentBlock[]

消息的标准化内容块。

dict[] | None

模型发起的工具调用。如果没有调用工具，则为空。

string

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

dict | None

消息的使用情况元数据，可用时包含令牌计数。

ResponseMetadata | None

消息的响应元数据。

工具调用

当模型发起工具调用时，它们会包含在 AIMessage 中：

from langchain.chat_models import init_chat_model

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

def get_weather(location: str) -> str:
    """获取某地天气。"""
    ...

model_with_tools = model.bind_tools([get_weather])
response = model_with_tools.invoke("What's the weather in Paris?")

for tool_call in response.tool_calls:
    print(f"Tool: {tool_call['name']}")
    print(f"Args: {tool_call['args']}")
    print(f"ID: {tool_call['id']}")

其他结构化数据，如推理或引用，也可能出现在消息内容中。

令牌使用情况

AIMessage 可以在其 usage_metadata 字段中保存令牌计数和其他使用情况元数据：

from langchain.chat_models import init_chat_model

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

response = model.invoke("Hello!")
response.usage_metadata

{'input_tokens': 8,
 'output_tokens': 304,
 'total_tokens': 312,
 'input_token_details': {'audio': 0, 'cache_read': 0},
 'output_token_details': {'audio': 0, 'reasoning': 256}}

详情请参见 UsageMetadata。

流式传输与块

在流式传输过程中，你会收到 AIMessageChunk 对象，可以将它们组合成一个完整的消息对象：

chunks = []
full_message = None
for chunk in model.stream("Hi"):
    chunks.append(chunk)
    print(chunk.text)
    full_message = chunk if full_message is None else full_message + chunk

了解更多：

工具消息

对于支持工具调用的模型，AI 消息可以包含工具调用。工具消息用于将单个工具执行的结果传回给模型。工具可以直接生成 ToolMessage 对象。下面展示一个简单示例。更多内容请阅读工具指南。

from langchain.messages import AIMessage
from langchain.messages import ToolMessage

# 在模型发起工具调用后
# （这里为了简洁，我们手动创建消息演示）
ai_message = AIMessage(
    content=[],
    tool_calls=[{
        "name": "get_weather",
        "args": {"location": "San Francisco"},
        "id": "call_123"
    }]
)

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

# 继续对话
messages = [
    HumanMessage("What's the weather in San Francisco?"),
    ai_message,  # 模型的工具调用
    tool_message,  # 工具执行结果
]
response = model.invoke(messages)  # 模型处理结果

属性

string

required

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

string

required

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

string

required

被调用工具的名称。

dict

不会发送给模型但可通过编程方式访问的附加数据。

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

示例：使用 artifact 存储检索元数据

例如，一个检索工具可以从文档中检索一段内容供模型参考。其中，消息的 content 包含模型将引用的文本，而 artifact 可以包含应用程序可以使用的文档标识符或其他元数据（例如，用于渲染页面）。请参见下面的示例：

from langchain.messages import ToolMessage

# 发送给模型
message_content = "It was the best of times, it was the worst of times."

# 下游可用的 artifact
artifact = {"document_id": "doc_123", "page": 0}

tool_message = ToolMessage(
    content=message_content,
    tool_call_id="call_123",
    name="search_books",
    artifact=artifact,
)

请参阅 RAG 教程，了解使用 LangChain 构建检索智能体的端到端示例。

消息内容

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

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

请参阅下面使用多模态输入的示例：

from langchain.messages import HumanMessage

# 字符串内容
human_message = HumanMessage("Hello, how are you?")

# 提供商原生格式（例如，OpenAI）
human_message = HumanMessage(content=[
    {"type": "text", "text": "Hello, how are you?"},
    {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
])

# 标准内容块列表
human_message = HumanMessage(content_blocks=[
    {"type": "text", "text": "Hello, how are you?"},
    {"type": "image", "url": "https://example.com/image.jpg"},
])

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

标准内容块

LangChain 提供了一种跨提供商通用的消息内容标准表示。消息对象实现了一个 content_blocks 属性，它会延迟地将 content 属性解析为标准、类型安全的表示形式。例如，从 ChatAnthropic 或 ChatOpenAI 生成的消息将以各自提供商的格式包含 thinking 或 reasoning 块，但可以延迟解析为一致的 ReasoningContentBlock 表示：

Anthropic
OpenAI

from langchain.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.messages import AIMessage

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

[{'type': 'reasoning', 'id': 'rs_abc123', 'reasoning': 'summary 1'},
 {'type': 'reasoning', 'id': 'rs_abc123', 'reasoning': 'summary 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("gpt-5-nano", output_version="v1")

多模态

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

可以在内容块的顶层包含额外键，或者嵌套在 "extras": {"key": value} 中。例如，OpenAI 要求 PDF 文件有文件名。请参阅你选择模型的提供商页面以获取具体信息。

# 来自 URL
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this image."},
        {"type": "image", "url": "https://example.com/path/to/image.jpg"},
    ]
}

# 来自 base64 数据
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this image."},
        {
            "type": "image",
            "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
            "mime_type": "image/jpeg",
        },
    ]
}

# 来自提供商托管的文件 ID
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this image."},
        {"type": "image", "file_id": "file-abc123"},
    ]
}

# 来自 URL
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this document."},
        {"type": "file", "url": "https://example.com/path/to/document.pdf"},
    ]
}

# 来自 base64 数据
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this document."},
        {
            "type": "file",
            "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
            "mime_type": "application/pdf",
        },
    ]
}

# 来自提供商托管的文件 ID
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this document."},
        {"type": "file", "file_id": "file-abc123"},
    ]
}

# 来自 base64 数据
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this audio."},
        {
            "type": "audio",
            "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
            "mime_type": "audio/wav",
        },
    ]
}

# 来自提供商托管的文件 ID
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this audio."},
        {"type": "audio", "file_id": "file-abc123"},
    ]
}

# 来自 base64 数据
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this video."},
        {
            "type": "video",
            "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
            "mime_type": "video/mp4",
        },
    ]
}

# 来自提供商托管的文件 ID
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this video."},
        {"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": "The user is asking about...",
    "extras": {"signature": "abc123"},
}

多模态

ImageContentBlock

用途： 图像数据

string

required

始终为 "image"

string

指向图像位置的 URL。

string

Base64 编码的图像数据。

string

此内容块的唯一标识符（由提供商或 LangChain 生成）。

string

图像 MIME 类型（例如，image/jpeg，image/png）。base64 数据时必需。

AudioContentBlock

用途： 音频数据

string

required

始终为 "audio"

string

指向音频位置的 URL。

string

Base64 编码的音频数据。

string

此内容块的唯一标识符（由提供商或 LangChain 生成）。

string

音频 MIME 类型（例如，audio/mpeg，audio/wav）。base64 数据时必需。

VideoContentBlock

用途： 视频数据

string

required

始终为 "video"

string

指向视频位置的 URL。

string

Base64 编码的视频数据。

string

此内容块的唯一标识符（由提供商或 LangChain 生成）。

string

视频 MIME 类型（例如，video/mp4，video/webm）。base64 数据时必需。

FileContentBlock

用途： 通用文件（PDF 等）

string

required

始终为 "file"

string

指向文件位置的 URL。

string

Base64 编码的文件数据。

string

此内容块的唯一标识符（由提供商或 LangChain 生成）。

string

文件 MIME 类型（例如，application/pdf）。base64 数据时必需。

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 | string

此块在流中的位置

InvalidToolCall

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

string

required

始终为 "invalid_tool_call"

string

调用失败的工具名称

object

传递给工具的参数

string

错误描述

服务器端工具执行

ServerToolCall

用途： 在服务器端执行的工具调用。

string

required

始终为 "server_tool_call"

string

required

与工具调用关联的标识符。

string

required

要调用的工具名称。

string

required

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

ServerToolCallChunk

用途： 流式传输的服务器端工具调用片段

string

required

始终为 "server_tool_call_chunk"

string

与工具调用关联的标识符。

string

正在调用的工具名称

string

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

number | string

此块在流中的位置

ServerToolResult

用途： 搜索结果

string

required

始终为 "server_tool_result"

string

required

对应的服务器工具调用的标识符。

string

与服务器工具结果关联的标识符。

string

required

服务器端工具的执行状态。"success" 或 "error"。

执行工具的输出。

提供商特定块

NonStandardContentBlock

用途： 提供商特定的应急措施

string

required

始终为 "non_standard"

object

required

提供商特定的数据结构

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

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

请在 API 参考中查看规范的类型定义。

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

与聊天模型一起使用

聊天模型接受一系列消息对象作为输入，并返回一个 AIMessage 作为输出。交互通常是无状态的，因此一个简单的对话循环涉及使用不断增长的消息列表来调用模型。请参阅以下指南了解更多信息：

用于持久化和管理对话历史记录的内置功能
管理上下文窗口的策略，包括裁剪和总结消息

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Production

消息

基本用法

文本提示

消息提示

字典格式

消息类型

系统消息

用户消息

文本内容

消息元数据

AI 消息

工具调用

令牌使用情况

流式传输与块

工具消息

消息内容

标准内容块

多模态

内容块参考

与聊天模型一起使用

​基本用法

​文本提示

​消息提示

​字典格式

​消息类型

​系统消息

​用户消息

​文本内容

​消息元数据

​AI 消息

​工具调用

​令牌使用情况

​流式传输与块

​工具消息

​消息内容

​标准内容块

​多模态

​内容块参考

​与聊天模型一起使用

基本用法

文本提示

消息提示

字典格式

消息类型

系统消息

用户消息

文本内容

消息元数据

AI 消息

工具调用

令牌使用情况

流式传输与块

工具消息

消息内容

标准内容块

多模态

内容块参考

与聊天模型一起使用