LangChain核心组件之Messages

在 LangChain 中，消息（Messages） 是模型上下文的基本单元。它们代表了模型的输入与输出，既包含实际内容，也携带元数据，用于在与大语言模型（LLM）交互时完整表达对话状态。

消息对象包含以下三个核心部分：

• 角色（Role） ------ 标识消息类型（例如 system、user）
• 内容（Content） ------ 表示消息的实际载荷（如文本、图像、音频、文档等）
• 元数据（Metadata） ------ 可选字段，例如响应信息、消息 ID、Token 使用量等

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

基础用法

使用消息最简单的方式是创建消息对象，并在 调用（invoke） 模型时传入。

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("你是一个乐于助人的助手。")
human_msg = HumanMessage("你好，最近怎么样？")

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

纯文本提示（Text Prompts）

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

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

适合使用纯文本提示的场景：

• 请求是单次且独立的
• 不需要维护对话历史
• 希望代码尽可能简洁

消息提示（Message Prompts）

你也可以通过传入一个消息对象列表来与模型交互。

from langchain.messages import SystemMessage, HumanMessage, AIMessage

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

适合使用消息提示的场景：

• 管理多轮对话
• 处理多模态内容（图像、音频、文件等）
• 需要系统指令（system instructions）

字典格式（Dictionary Format）

你还可以直接使用 OpenAI 聊天补全（chat completions）的字典格式来定义消息。

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

消息类型（Message Types）

• 系统消息（System Message） ------ 告诉模型应如何行为，并为交互提供上下文
• 人类消息（Human Message） ------ 表示用户输入和与模型的交互
• AI 消息（AI Message） ------ 模型生成的响应，包括文本、工具调用和元数据
• 工具消息（Tool Message） ------ 表示 工具调用（tool calls） 的执行结果

系统消息（System Message）

SystemMessage 用于提供初始指令，引导模型的行为。你可以用它设定语气、定义角色、制定回答规范。

• 基础指令

# 基础指令
system_msg = SystemMessage("你是一个乐于助人的编程助手。")
messages = [system_msg, HumanMessage("如何创建一个 REST API？")]
response = model.invoke(messages)

• 详细人设

# 详细人设
from langchain.messages import SystemMessage, HumanMessage

system_msg = SystemMessage("""
你是一位资深 Python 开发者，精通 Web 框架。
请始终提供代码示例并解释你的思路。
回答要简洁但全面。
""")

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

人类消息（Human Message）

HumanMessage 表示用户的输入，可包含文本、图像、音频、文件等任意形式的多模态 内容（content）。

1. 文本内容

• 使用消息对象

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

• 使用字符串

# 字符串是 HumanMessage 的快捷写法
response = model.invoke("什么是机器学习？")

2. 消息元数据

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

name 字段的行为因提供商而异------有些用于用户识别，有些则忽略。具体行为请参考对应模型提供商的 集成文档。

AI 消息（AI Message）

AIMessage 表示模型调用的输出结果，可能包含多模态数据、工具调用和提供商特定的元数据。

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

模型调用后返回的 AIMessage 对象包含了响应中的全部关联元数据。

由于不同提供商对消息类型的处理方式不同，有时你需要手动创建一个 AIMessage，并将其插入到对话历史中，模拟模型的回复。

from langchain.messages import AIMessage, SystemMessage, HumanMessage

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

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

response = model.invoke(messages)

AIMessage属性：

• text string
  消息的文本内容。
• content string | dict[]
  消息的原始内容。
• content_blocks ContentBlock[]
  消息的标准化 [内容块（content blocks）](#内容块（content blocks）)。
• tool_calls dict[] | None
  模型发起的工具调用。若未调用工具，则为空。
• id string
  消息的唯一标识符（由 LangChain 自动生成或由提供商返回）。
• usage_metadata dict | None
  消息的使用元数据，包含 Token 统计信息（如有）。
• response_metadata ResponseMetadata | None
  消息的响应元数据。

工具调用（Tool Calls）

当模型执行 工具调用（tool calling） 时，相关信息会包含在 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("巴黎的天气怎么样？")

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

其他结构化数据（如推理过程、引用来源等）也可能出现在消息的 内容（content） 中。

Token 使用量

AIMessage 可在其 usage_metadata 字段中记录 Token 使用情况：

from langchain.chat_models import init_chat_model

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

response = model.invoke("你好！")
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。

流式传输与分块（Streaming and Chunks）

在流式传输过程中，你会收到 AIMessageChunk 对象，可将其合并为完整消息：

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

了解更多：

• 从聊天模型流式输出 Token
• 从智能体流式输出 Token 和/或步骤

工具消息（Tool Message）

对于支持 工具调用（tool calling） 的模型，AI 消息可包含工具调用请求。工具消息（ToolMessage） 则用于将单个工具执行的结果传回给模型。

工具（Tools） 可直接生成 ToolMessage 对象。下面是一个简化示例（完整用法请参阅 工具指南）：

from langchain.messages import AIMessage, ToolMessage

# 模型发起工具调用（此处为手动构造示例）
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)  # 模型处理结果

参数：

• content stringr equired
  工具调用结果的字符串化输出。
• tool_call_id string required
  此消息所对应的工具调用 ID，必须与 AIMessage 中的 ID 一致。
• name string required
  被调用的工具名称。
• artifact dict
  额外数据，不会发送给模型，但可被程序访问。

artifact 字段用于存储不发送给模型 但可供程序使用的补充数据，例如原始结果、调试信息或下游处理所需的数据，避免污染模型上下文。 例如，一个 检索（retrieval） 工具可能从文档中提取一段文字供模型参考。此时，content 包含模型可见的文本，而 artifact 可包含文档 ID 或页码等元数据，供应用程序使用（如渲染页面）：

from langchain.messages import ToolMessage

# 发送给模型的内容
message_content = "这是最好的时代，也是最坏的时代。"

# 下游可用的元数据
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 构建带检索功能的 智能体（agents）。

消息内容（Message Content）

你可以将消息的 内容（content） 视为发送给模型的数据载荷。消息对象有一个 content 属性，其类型较为宽松，支持字符串或未类型化的对象列表（如字典），从而允许直接在 LangChain 聊天模型中使用提供商原生的结构，例如 多模态（multimodal） 内容。

此外，LangChain 还提供了专用的内容类型，用于表示文本、推理、引用、多模态数据、服务端工具调用等。详见下方的 标准内容块（standard content blocks）。

LangChain 聊天模型通过 content 属性接收消息内容，该属性可包含以下任一形式：

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

以下是一个使用 多模态 输入的示例：

from langchain.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 属性，但提供了类型安全的接口。

标准内容块（Standard Content Blocks）

LangChain 提供了一套跨提供商的标准内容表示方式。

消息对象实现了 content_blocks 属性，可将 content 懒加载解析为标准、类型安全的表示。例如，来自 ChatAnthropic 或 ChatOpenAI 的消息可能分别包含 thinking 或 reasoning 块，但均可被统一解析为 ReasoningContentBlock：

• Anthropic

from langchain.messages import AIMessage

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

• 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': '...'}]

更多用法请参阅 集成指南。

序列化标准内容

如果 LangChain 外部的应用需要访问标准内容块表示，你可以选择将内容块存储在消息的 content 中。

方法一：设置环境变量 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")

多模态（Multimodal）

多模态（Multimodality） 指处理多种数据形式的能力，如文本、音频、图像、视频等。LangChain 为这些数据提供了标准类型，可在不同提供商间通用。

聊天模型 可接收多模态数据作为输入，并生成多模态输出。以下是几种多模态输入的简短示例：

额外字段可直接放在内容块顶层，或嵌套在 "extras": {"key": value} 中。

例如，OpenAI 和 AWS Bedrock Converse 要求 PDF 文件提供文件名。具体要求请查阅所选模型的 提供商页面。

• 图像输入

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

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

# From provider-managed File ID
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this image."},
        {"type": "image", "file_id": "file-abc123"},
    ]
}

• PDF 文档输入

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

# From base64 data
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "描述这份文档的内容。"},
        {
            "type": "file",
            "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
            "mime_type": "application/pdf",
        },
    ]
}

# From provider-managed File ID
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "描述这份文档的内容。"},
        {"type": "file", "file_id": "file-abc123"},
    ]
}

• 音频输入

# From base64 data
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "描述这段音频的内容。"},
        {
            "type": "video",
            "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
            "mime_type": "video/mp4",
        },
    ]
}

# From provider-managed File ID
message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "描述这段视频的内容。"},
        {"type": "video", "file_id": "file-abc123"},
    ]
}

并非所有模型都支持全部文件类型。请查阅模型提供商的 集成文档 以确认支持的格式和大小限制。

内容块参考（Content Block Reference）

内容块在创建消息或访问 content_blocks 属性时，表示为一个类型化字典列表。每个元素必须符合以下某种块类型：

（此处省略详细块类型说明，保留结构清晰性；实际开发中可查阅官方 API 文档）

完整类型定义请参阅 API 参考文档。 内容块（Content Blocks）是在 LangChain v1 中作为消息的新属性引入的，旨在跨提供商标准化内容格式，同时保持与现有代码的向后兼容性。

内容块 不是 对 content 属性的替代，而是一个新属性，用于以标准化格式访问消息内容。

与聊天模型配合使用

聊天模型 接收一系列消息对象作为输入，并返回一个 AIMessage 作为输出。交互通常是无状态的，因此简单的对话循环只需不断将增长的消息列表传给模型即可。