Messages | 产品经理学Langchian

目标：将 LangChain “消息” 模块转译为产品经理可执行的知识结构，支撑多轮对话、工具调用与多模态体验的需求设计。原文参考：https://docs.langchain.com/oss/python/langchain/messages

Messages 核心职责

• 承载上下文：role + content + metadata
• 消息类型：System / Human / AI / Tool（含 server tool 变体）
• 内容形态：文本、图片、音频、视频、文件、工具块
• 输入格式：文本字符串、message objects、OpenAI 字典
• Tool Calling：AIMessage.tool_calls → ToolMessage 回写
• 监控：usage metadata、response metadata、LangSmith tracing
• 关联模块：Models（调用）、Memory（裁剪）、Agents（工具调度）

概述

Messages 是与模型交互的最小上下文单元，是LangChain中模型上下文的基本单位。它们代表模型的输入和输出，承载着与大型语言模型交互时表示对话状态所需的内容和元数据。其封装角色（system/human/AI/tool）、内容（文本+多模态）和 metadata（ID、token、渠道）。

消息通常包含以下三类信息：

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

消息的用法

使用消息的最简单方式是创建消息对象，并在调用时将其传递给模型。根据场景的细分，消息也分为三类场景：

1. Text prompts ，适合不需要保留对话历史的简单生成任务。适用于单一的请求、对会话上下文无要求的情况，常用于AIGC产品。

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

2. Message prompts ，传入消息历史，适用于需要管理多轮对话、处理多模态或处理系统指令的情况；一般在代码里面带有不同角色的历史信息，如

   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)

3. Dictionary format：可以理解成 Message prompts不同的形式，如

   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)

消息的类型

上面提到了消息的用法，里面也已经有消息的类型区分。消息一共分为四个类型的消息：

• System message 系统消息 - 告知模型应如何表现并为交互提供上下文；代表着一组初始指令，用于设定模型的行为。你可以使用系统消息来设定语气、定义模型的角色，并制定响应准则。

• Human message 人类消息 - 代表用户输入以及与模型的交互；可以包含文本、图像、音频、文件以及其他任何形式的多模态内容。在人类消息中，为了区分人类的身份，也会携带多种信息。

  • Text content 文本内容，如常见的提问等 ，如

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

  • Message metadata 消息元数据，会携带更多的业务信息，如用户是谁、聊天ID是什么等等

  human_msg = HumanMessage(
      content="Hello!",
      name="pmsolo",  # Optional: identify different users
      id="888",  # Optional: unique identifier for tracing
  )

• AI message 人工智能消息 - 模型生成的响应，包括文本内容、工具调用和元数据；包含多模态数据、工具调用以及特定于提供者的元数据，这些内容在之后可以访问。AI message除了常见的大模型LLM产出之外，还包括以下几种类型：

  • Tool calls 工具调用：模型进行工具调用时候，也是以AI message输出的；有的推理也包含在内。
  • Token usage 令牌使用量：<code>sage_metadata</code>字段中包含令牌计数和其他使用元数据，如输入、输出、总结用量等
  • Streaming and chunks 流式传输和分块：在第二部分Models中提到流式输出，输出的是chunk块，故<code>AIMessageChunk</code>可以组合成一个完整的消息对象

• Tool message 工具消息 - 表示工具调用的输出。对于支持工具调用的模型，AI消息可以包含工具调用。工具消息用于将单次工具执行的结果传递回模型。

消息的content

消息具有一个<code>content</code>属性，该属性为松散类型，可以是字符串或非类型化对象列表（例如字典）。LangChain 为文本、推理、引用、多模态数据、服务器端工具调用和其他消息内容提供了专用的内容类型。

LangChain 提供了一种适用于所有提供商的消息内容标准表示形式。通过一个<code>content_blocks</code>属性，该属性会将<code>content</code>属性延迟解析为标准的、类型安全的表示形式。

LangChain 同时也支持多模态信息的标准化封装，以下是几个例子，方便了解多模态情况下的请求结构：

• 图片：支持URL或Base64 方式传入

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

• PD文件：支持URL或Base64 方式传入

  # From URL
  message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this document."},
        {"type": "file", "url": "https://example.com/path/to/document.pdf"},
    ]
  }
  
  # From base64 data
  message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this document."},
        {
            "type": "file",
            "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
            "mime_type": "application/pdf",
        },
    ]
  }
  
  # From provider-managed File ID
  message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this document."},
        {"type": "file", "file_id": "file-abc123"},
    ]
  }

• 音视频：Base64 或 文件ID

  # From base64 data
  message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this audio."},
        {
            "type": "audio",
            "base64": "AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...",
            "mime_type": "audio/wav",
        },
    ]
  }
  
  # From provider-managed File ID
  message = {
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe the content of this audio."},
        {"type": "audio", "file_id": "file-abc123"},
    ]
  }

延展知识

消息的处理纪要考虑历史会话中上下文的需要，同时也要考虑Token最大长度的限制，所以消息还与以下两个模块有密切关系：

Memory:用于持久化和管理对话历史的内置功能

Context:管理上下文窗口的策略，包括消息的裁剪和总结

这两部分也将随着后面的需求逐步解读。

需求关注点

适用场景（问题 → 方案 → 价值）

1. 客服多轮对话编排
   • 问题：需在多渠道对话中保持身份、历史上下文，并记录工具调用结果。
   • 方案：使用 <code>SystemMessage</code> 固定人设，<code>HumanMessage</code> 注入用户输入、渠道 metadata；工具结果通过 <code>ToolMessage</code> 回写并带 <code>tool_call_id</code>；结合 LangSmith 追踪每轮。
   • 价值：上下文可回放，定位问题更快，工具失败可复现。
2. 多模态业务质检
   • 问题：审核员需上传截图/音频并要求模型给出判定与证据。
   • 方案：<code>HumanMessage</code> 通过 content blocks 同时传文本+图像；模型输出 <code>AIMessage</code> 含文本结论与引用；metadata 标记场景 ID。
   • 价值：同一消息链保存多模态证据，利于复审与合规存档。

常见问题（FAQ）

1. 何时用文本 vs 消息列表？→ 单轮可文本，多轮/多模态/需 system 指令时必须列表。
2. 系统消息可动态改吗？→ 可以，根据角色/场景插入多条 system message，但需在 PRD 中定义触发条件。
3. 如何在历史中插入模型回复？→ 可手动创建 <code>AIMessage</code> 并插入消息列表。
4. ToolMessage 是必须的吗？→ 只要模型触发工具调用，就需要 ToolMessage 把结果写回（含 <code>tool_call_id</code>），否则模型无法读取输出。
5. metadata 字段是否跨供应商一致？→ LangChain 做了封装，但各模型暴露字段不同；PRD 需兼容差异。
6. content blocks 与旧 <code>content</code> 冲突吗？→ 不冲突；content blocks 是结构化访问方式，建议新项目统一使用。
7. 如何处理超长对话？→ 结合短期记忆策略：裁剪早期消息、生成摘要或使用记忆组件。
8. 多模态大小有限制？→ 受供应商约束，需在需求中写明文件大小、格式和压缩策略。
9. 如何记录 token？→ 使用 <code>usage_metadata</code> 或 LangSmith callback 统计，并在日志中带上消息 ID。
10. 工具调用失败如何暴露？→ ToolMessage 中写明 <code>status</code>/<code>error</code>，Agent 或 UI 决定重试或提示用户。

六、扩展信息

• LangChain Messages 文档：https://docs.langchain.com/oss/python/langchain/messages
• 短期记忆策略：https://docs.langchain.com/oss/python/langchain/short-term-memory
• LangChain Agents（工具调度关系）：https://docs.langchain.com/oss/python/langchain/agents