LangChain Messages模块-平芜编程栈

1. 消息核心概念

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

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

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

2. 消息类型详解

2.1 系统消息（SystemMessage）

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

fromlangchain.messagesimportSystemMessage# 基础指令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）

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

fromlangchain.messagesimportHumanMessage# 文本内容human_msg=HumanMessage("What is machine learning?")# 带元数据的人类消息human_msg_with_metadata=HumanMessage(content="Hello!",name="alice",# 可选：标识不同用户id="msg_123",# 可选：用于追踪的唯一标识符)

2.3 AI消息（AIMessage）

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

fromlangchain.messagesimportAIMessage# 从模型获取的响应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）

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

fromlangchain.messagesimportToolMessage# 创建工具消息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")

消息对象列表（适用于多轮对话）：

fromlangchain.messagesimportSystemMessage,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 完整工作流程示例

fromlangchain.chat_modelsimportinit_chat_modelfromlangchain.messagesimportHumanMessage,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消息中会包含工具调用信息：

fromlangchain.chat_modelsimportinit_chat_model model=init_chat_model("gpt-5-nano")# 定义工具函数defget_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?")# 处理工具调用fortool_callinresponse.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=Noneforchunkinmodel.stream("Hi"):chunks.append(chunk)print(chunk.text)full_message=chunkiffull_messageisNoneelsefull_message+chunk

5. 内容格式详解

5.1 内容表示方式

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

fromlangchain.messagesimportHumanMessage# 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",},]}# 使用提供者管理的文件IDmessage={"role":"user","content":[{"type":"text","text":"Describe the content of this image."},{"type":"image","file_id":"file-abc123"},]}

6. 最佳实践指南

6.1 消息组织原则

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

6.2 性能优化建议

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

6.3 错误处理策略

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

总结

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

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

LangChain Messages模块