02 · 消息类数据字典：模型输入输出的”统一信封”

本片目标：彻底搞懂 LangChain 的”消息”体系——为什么对话不是”字符串进字符串出”，而是”消息对象进、AIMessage 出”。这是全系列最重要的一篇数据字典。 新增规定性：2（对话的原子单位是消息对象，有角色之分、有 9 个字段） 数据字典：BaseMessage / SystemMessage / HumanMessage / AIMessage / ToolCall / UsageMetadata。 进程线程模型：无变化（仍是同步阻塞）。 网络模型：invoke(messages) 把消息对象序列化成各家协议的 JSON 结构。

1. 上集回顾

第 01 篇我们只用了 model.invoke("你好")——传字符串。但你有两个问题：

多轮对话怎么传？我需要同时告诉模型”你是助手”（system）+ 用户历史问题（user）+ 之前回答（assistant）。一个字符串表达不了这种结构。
模型返回的 AIMessage 到底有什么？第 01 篇看到它有 content、response_metadata、usage_metadata、tool_calls…… 为什么一个回答要带这么多字段？

答案都在”消息类”里。消息是 LangChain 里所有对话的原子单位——输入是消息列表，输出是 AIMessage。

2. 数据字典：消息类体系（关键类的数据）

2.1 类层次

BaseMessage（抽象基类，6 字段）
 ├── SystemMessage   ← 系统指令（你是谁、怎么回答）
 ├── HumanMessage    ← 用户输入
 ├── AIMessage       ← 模型输出（9 字段，特殊）
 ├── AIMessageChunk  ← 流式输出碎片（第 04 篇）
 └── ToolMessage     ← 工具返回结果（第 11 篇工具篇深入用）

2.2 BaseMessage 六字段（所有消息的公共部分）

字段	数据类型	说明
`content`	`str` / `list[dict]`	消息内容。字符串是常见情况；Anthropic 协议的思考/工具轮是块列表（第 06 篇细讲）
`additional_kwargs`	`dict`	协议私货。如 DeepSeek 的思考内容放 `reasoning_content`
`response_metadata`	`dict`	模型返回的元信息（id/model/stop_reason/usage/model_provider）
`type`	`str`	消息类型标识：`"system"` / `"human"` / `"ai"`
`name`	`str	None`	可选的发言者名字
`id`	`str	None`	消息唯一 ID（用于追踪/删除）

序列化后的形态（给模型的 JSON）——这是网络层真正发送的：

{ "content": "你是公司智能助手", "type": "system", "id": null }
{ "content": "我叫小林", "type": "human", "id": null }

2.3 AIMessage：9 字段（模型输出的完整信封）

字段	数据类型	说明
`content`	`str / list[dict]`	答案文本（或块列表）
`additional_kwargs`	`dict`	协议私货
`response_metadata`	`dict`	实测：`{"id","model","stop_reason","usage","model_name","model_provider",...}`
`type`	`str`	恒为 `"ai"`
`name`	`str	None`	—
`id`	`str	None`	形如 `"lc_run--xxx"`（LangChain 生成的 run id）
`tool_calls`	`list[ToolCall]`	模型请求调用的工具（结构见 2.5，第 11 篇深入）
`invalid_tool_calls`	`list[InvalidToolCall]`	解析失败的工具调用（args 不是合法 JSON）
`usage_metadata`	`UsageMetadata	None`	token 用量

实测 AIMessage.model_dump() 完整结构（智谱 glm-4.7，第 01 篇运行输出，脱敏）：

{
  "content": "你好！我是Z.ai训练的GLM大语言模型...",
  "additional_kwargs": {},
  "response_metadata": {
    "id": "msg_20260805...", "container": null, "model": "glm-4.7",
    "stop_details": null, "stop_reason": "end_turn", "stop_sequence": null,
    "usage": {
      "cache_creation": null, "cache_creation_input_tokens": null,
      "cache_read_input_tokens": 0, "inference_geo": null,
      "input_tokens": 6, "output_tokens": 45, "output_tokens_details": null,
      "server_tool_use": {"web_fetch_requests": null, "web_search_requests": 0},
      "service_tier": "standard"
    },
    "model_name": "glm-4.7", "model_provider": "anthropic"
  },
  "type": "ai",
  "name": null,
  "id": "lc_run--9d5c...",
  "tool_calls": [],
  "invalid_tool_calls": [],
  "usage_metadata": {
    "input_tokens": 6, "output_tokens": 45, "total_tokens": 51,
    "input_token_details": {"cache_read": 0}
  }
}

2.4 UsageMetadata（token 用量，三家协议统一成这三键）

键	类型	说明
`input_tokens`	`int`	输入 token 数
`output_tokens`	`int`	输出 token 数
`total_tokens`	`int`	合计

三家的原始 usage 结构完全不同（Anthropic 是 input_tokens/output_tokens，OpenAI 是 prompt_tokens/completion_tokens），LangChain 统一成一套——这就是”统一信封”在元数据层的体现。

2.5 ToolCall（工具调用结构，第 11 篇深入）

ToolCall(
    name="get_weather",        # str，工具名
    args={"city": "北京"},      # dict！永远解析成 dict（OpenAI 系 json.loads，Anthropic 系透传）
    id="call_1",               # str，调用 ID
    type="tool_call",
)

3. 关键方法（本片主角：怎么构造和检查消息）

方法/构造	签名	说明
`SystemMessage(content)`	`SystemMessage(content="...")`	系统指令
`HumanMessage(content)`	`HumanMessage(content="...")`	用户输入
`AIMessage(content=..., ...)`	全部字段可传	模型输出（一般由框架构造，你很少手动建）
`invoke(messages)`	`model.invoke(list[BaseMessage])`	传消息列表给模型
`.model_dump()`	`msg.model_dump()`	Pydantic 序列化 → dict（打印看结构用这个）
`.pretty_print()`	`msg.pretty_print()`	彩色打印消息（调试用）
`msg.content`	属性	取文本答案

4. 三协议差异（为什么需要”统一信封”的实证）

	Anthropic 协议（智谱/Claude）	OpenAI 协议（DeepSeek/通义/Kimi）
role 名	`system` / `user` / `assistant`	`system` / `user` / `assistant`
消息列表	`messages: [...]`	`messages: [...]`
base_url 规则	自动拼 `/v1/messages`（不带 /v1）	不自动拼（自己带 /v1）
content 响应结构	`content` 是列表：`[{"type":"text","text":...}]`	`choices[0].message.content` 是字符串
usage 键名	`input_tokens/output_tokens`	`prompt_tokens/completion_tokens`
思考内容	`content` 块列表里 `{"type":"thinking"}`	`additional_kwargs["reasoning_content"]`
model_provider	`"anthropic"`	`"openai"`

这就是第 01 篇说的”换厂商只改 import + 构造参数”的底层原因：LangChain 的消息对象把上表右边的全部差异吸收掉了。你写的消息列表，对三家是同一份 Python 代码。

5. 验证：跑起来

配套代码 code/02_messages.py：

构造 SystemMessage + HumanMessage，invoke 传给模型；
打印 AIMessage 的 model_dump() 全字段 JSON；
打印 usage_metadata 和 model_provider，验证协议统一。

cd enterprise-rag-course\code
python 02_messages.py

预期输出（节选）：

✅ 消息类型: system / human
✅ model_provider: anthropic   ← 智谱走 Anthropic 协议
✅ usage_metadata: {'input_tokens': ..., 'output_tokens': ..., 'total_tokens': ...}
📦 AIMessage 完整结构（9 字段）:
{
  "content": "...",
  "response_metadata": {...},
  "usage_metadata": {...},
  "type": "ai",
  ...
}

6. 边界

AIMessage 的 id 不是模型返回的 id——它是 LangChain 给 run 生成的 id（lc_run--xxx）。模型原始 id 在 response_metadata["id"]（msg_xxx）。
tool_calls 平时是空列表——只有你让模型”可以调工具”时它才有内容（第 11 篇工具篇用 bind_tools 激活它）。
不要把消息对象和普通 dict 混用——model.invoke() 里要么全是消息对象，要么是符合协议的 dict 列表（第 01 篇那种）。混用会报错。
content 可能是列表——Anthropic 协议在思考/工具场景下 content 是 [{"type":"text","text":...}, ...]。判断答案要遍历找 type=="text" 的块。

7. 未完待续

我们已经能手工构造消息列表并调用模型。但问题来了：每次都要手写 SystemMessage(...) + HumanMessage(...) 列表，还穿插历史消息，代码会变得很啰嗦、很容易写错（比如漏了 system、历史消息位置不对）。有没有一种方式，把”消息怎么拼”变成”模板”？ → 03 · ChatPromptTemplate：模板与历史槽位

RAG 教程

小林学 LangChain

02 · 消息类数据字典：模型输入输出的"统一信封"

02 · 消息类数据字典：模型输入输出的”统一信封”

1. 上集回顾

2. 数据字典：消息类体系（关键类的数据）

2.1 类层次

2.2 BaseMessage 六字段（所有消息的公共部分）

2.3 AIMessage：9 字段（模型输出的完整信封）

2.4 UsageMetadata（token 用量，三家协议统一成这三键）

2.5 ToolCall（工具调用结构，第 11 篇深入）

3. 关键方法（本片主角：怎么构造和检查消息）

4. 三协议差异（为什么需要”统一信封”的实证）

5. 验证：跑起来

6. 边界

推荐资料（延伸阅读）

7. 未完待续

​02 · 消息类数据字典：模型输入输出的”统一信封”

​1. 上集回顾

​2. 数据字典：消息类体系（关键类的数据）

​2.1 类层次

​2.2 BaseMessage 六字段（所有消息的公共部分）

​2.3 AIMessage：9 字段（模型输出的完整信封）

​2.4 UsageMetadata（token 用量，三家协议统一成这三键）

​2.5 ToolCall（工具调用结构，第 11 篇深入）

​3. 关键方法（本片主角：怎么构造和检查消息）

​4. 三协议差异（为什么需要”统一信封”的实证）

​5. 验证：跑起来

​6. 边界

​推荐资料（延伸阅读）

​7. 未完待续

02 · 消息类数据字典：模型输入输出的”统一信封”

1. 上集回顾

2. 数据字典：消息类体系（关键类的数据）

2.1 类层次

2.2 BaseMessage 六字段（所有消息的公共部分）

2.3 AIMessage：9 字段（模型输出的完整信封）

2.4 UsageMetadata（token 用量，三家协议统一成这三键）

2.5 ToolCall（工具调用结构，第 11 篇深入）

3. 关键方法（本片主角：怎么构造和检查消息）

4. 三协议差异（为什么需要”统一信封”的实证）

5. 验证：跑起来

6. 边界

推荐资料（延伸阅读）

7. 未完待续