LangChain核心组件之Messages

最新推荐文章于 2026-01-06 17:47:27 发布

原创最新推荐文章于 2026-01-06 17:47:27 发布 · 684 阅读

21 ·

CC 4.0 BY-SA版权

文章标签：

#langchain #message #消息

LangChain入门实战专栏收录该内容

10 篇文章

订阅专栏

在 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）。

文本内容

使用消息对象

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

使用字符串

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

消息元数据

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）。
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

了解更多：

工具消息（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 属性接收消息内容，该属性可包含以下任一形式：

一个字符串
一个提供商原生格式的内容块列表
一个 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"},
    ]
}