1. 消息核心概念

消息（Messages） 是LangChain中模型交互的基本上下文单元，代表着模型输入和输出的结构化数据载体。每个消息对象包含三个核心组成部分：

• 角色（Role）：标识消息类型（如system、user、assistant）
• 内容（Content）：消息的实际内容，支持文本、图像、音频、文档等
• 元数据（Metadata）：可选字段，如响应信息、消息ID和令牌使用情况

在LangChain架构中，消息既是对话状态的表现形式，也是模型调用的标准接口，为LLM交互提供了统一的抽象层。

2. 消息类型详解

2.1 系统消息（SystemMessage）

系统消息用于引导模型行为和设置交互上下文，是对话的初始化指令：

from langchain.messages import SystemMessage

# 基础指令
system_msg = SystemMessage("You are a helpful coding assistant.")

# 详细角色定义
detailed_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.
""")

2.2 人类消息（HumanMessage）

人类消息代表用户输入，支持多模态内容：

from langchain.messages import HumanMessage

# 文本内容
human_msg = HumanMessage("What is machine learning?")

# 带元数据的人类消息
human_msg_with_metadata = HumanMessage(
    content="Hello!",
    name="alice",  # 可选：标识不同用户
    id="msg_123",  # 可选：用于追踪的唯一标识符
)

2.3 AI消息（AIMessage）

AI消息表示模型输出，包含响应内容、工具调用和元数据：

from langchain.messages import AIMessage

# 从模型获取的响应
response = model.invoke("Explain AI")
print(type(response))  # <class 'langchain.messages.AIMessage'>

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

2.4 工具消息（ToolMessage）

工具消息用于传递工具执行结果给模型：

from langchain.messages import ToolMessage

# 创建工具消息
tool_message = ToolMessage(
    content="Sunny, 72°F",  # 工具执行结果
    tool_call_id="call_123",  # 必须与AI消息中的工具调用ID匹配
    name="get_weather",  # 被调用工具的名称
    artifact={"document_id": "doc_123", "page": 0}  # 不发送给模型的附加数据
)

3. 基本使用方式

3.1 三种调用格式

文本提示（适用于单次独立请求）：

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)

3.2 完整工作流程示例

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

4. 高级功能特性

4.1 工具调用

当模型绑定工具时，AI消息中会包含工具调用信息：

from langchain.chat_models import init_chat_model

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

# 定义工具函数
def get_weather(location: str) -> str:
    """Get the weather at a location."""
    ...

# 绑定工具并调用
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']}")

4.2 令牌使用统计

AI消息包含详细的令牌使用元数据：

response = model.invoke("Hello!")
print(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}
# }

4.3 流式响应处理

处理流式响应时，接收的是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

5. 内容格式详解

5.1 内容表示方式

消息内容支持三种表示形式：

from langchain.messages import HumanMessage

# 1. 字符串形式
human_message = HumanMessage("Hello, how are you?")

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

# 3. 标准内容块（类型安全接口）
human_message = HumanMessage(content_blocks=[
    {"type": "text", "text": "Hello, how are you?"},
    {"type": "image", "url": "https://example.com/image.jpg"},
])

5.2 多模态内容支持

LangChain支持多种多模态输入格式：

# 从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"},
    ]
}

6. 最佳实践指南

6.1 消息组织原则

1. 明确角色分配：正确使用系统、用户和助手角色
2. 合理使用元数据：为消息添加ID和名称以支持追踪和调试
3. 保持对话状态：将完整对话历史作为消息序列传递

6.2 性能优化建议

1. 使用内容块标准表示：跨提供者的一致接口
2. 合理设置环境变量：使用LC_OUTPUT_VERSION="v1"以获得标准内容块表示
3. 监控令牌使用：通过usage_metadata分析成本和使用模式

6.3 错误处理策略

1. 验证工具调用ID匹配：确保ToolMessage的tool_call_id与AI消息中的调用ID一致
2. 检查模型支持能力：确认目标模型支持所需的多模态格式和文件类型
3. 处理提供者差异：注意不同提供者对消息字段（如name）的支持差异

总结

LangChain的Messages模块提供了强大而灵活的消息抽象层，支持从简单的文本对话到复杂的多模态交互和工具调用。通过掌握消息的核心概念、类型系统和使用模式，开发者可以构建出高效、可靠且可维护的LLM应用。

消息作为LangChain中模型交互的统一接口，其设计平衡了灵活性与类型安全，同时保持了与主流提供者API的兼容性。在实际应用中，建议根据具体需求选择适当的消息格式和调用方式，并结合最佳实践进行优化。