20250911-01: 概念：基础认知--消息

无难事者若执

676人浏览 · 2025-09-11 23:47:36

无难事者若执 · 2025-09-11 23:47:36 发布

20250909-01: 概念：基础认知–消息

@🎯 关键结果（Key Results, KRs）

@KR

@任务：

@理论知识整理

@1. 消息包含什么？

@角色

@内容

@其他消息数据

@对话结构

@LangChain 消息

@五种主要消息类型是

@SystemMessage

@HumanMessage

@文本内容

@多模态内容

@AIMessage

@内容

@AIMessageChunk

@聚合

@ToolMessage

@RemoveMessage

@（旧版）FunctionMessage

@OpenAI 格式

@输入

@输出

@实践练习

@习题

@📚 任务 2.2：掌握内容格式与多模态支持

@✅ 一、内容格式对比表（文本 vs 多模态块）

@✅ 二、“何时用字典列表”的判断标准

@🚦 必须使用字典列表的情况：

@术语

@五类消息一句话定义模板

@进度跟踪卡

@🚀 导师结语

✅ LangChain 第二周成长计划：基础认知 —— 聊天模型

🎯 核心目标（Objective）

在 2 小时内系统掌握 LangChain 消息系统的角色语义、内容结构与工程实践，能独立设计符合规范的多轮对话消息序列，理解不同角色在工具调用、流式响应、多模态场景中的作用，为构建复杂对话系统打下原子级认知基础。

🎯 关键结果（Key Results, KRs）

KR

在 2小时内，用官方教程消息和AI辅助阅读完成 掌握 LangChain 消息系统的角色语义、内容结构与工程实践，交付 独立设计符合规范的多轮对话消息序列，理解不同角色在工具调用、流式响应、多模态场景中的作用 ；若因知识找不到失败，最多重试 查找其他资料，最终必须 输出文章并整理知识点题目

KR 编号	关键结果描述	验收标准（可量化/可验证）
KR2.1	能手绘五类核心消息（System/Human/AI/Tool/Chunk）的结构图，标注角色、内容、关键属性（如 tool_calls, tool_call_id）	图纸含完整标注，导师评分 ≥ 4.5/5
KR2.2	能编写并运行一个包含 System → Human → AI → Tool → AI 的完整对话流程代码，输出符合预期	代码可运行，打印每步消息类型与内容，含注释说明角色作用
KR2.3	能解释“SystemMessage 在不同提供商中的三种处理方式”，并说明 LangChain 如何自动适配	完成填空题 + 60秒录音，包含“API参数/合并/异常”关键词
KR2.4	能对比 AIMessage 与 AIMessageChunk 的结构差异，并演示流式聚合（chunk1 + chunk2）	提交对比表 + 可运行流式代码，输出聚合后完整消息
KR2.5	能将一段 OpenAI 格式对话转换为 LangChain 消息对象，并反向转换验证一致性	提交转换前后对比代码 + 断言验证，无类型/内容丢失

任务：

具体内容：

理解五类核心消息语义
- 学习 SystemMessage, HumanMessage, AIMessage, ToolMessage, AIMessageChunk 的角色定义与使用场景
- 重点标注：
  - SystemMessage 的三种适配方式（系统角色/API参数/合并）
  - AIMessage 的 tool_calls 与 usage_metadata
  - ToolMessage 的 tool_call_id 与 artifact
  - Chunk 的聚合机制（+ 运算符）
所需时间：45分钟
预期成果：
- 完成“五类消息一句话定义”初稿
- 整理“SystemMessage 适配方式”笔记
难度控制：i+1 —— 从“知道有消息” → “理解每类消息的工程语义”
资源准备：
- 📖 官方文档 - 消息
- 🧩 消息定义模板

按“知识学习 → 基础练习 → 综合应用”递进

‍

理论知识整理

1. 消息包含什么？

消息通常包含以下信息

角色 role ：消息的角色（例如，“用户”、“助手”）。
内容：消息的内容（例如，文本、多模态数据）
额外元数据：id,名称，token使用量和其他模型特定元数据

角色

角色用于区分对话中不同类型的消息，并帮助聊天模型理解如何对给定的消息序列做出响应。

角色	描述
系统 system	用于告诉聊天模型如何表现并提供额外上下文。并非所有聊天模型提供商都支持。
用户 user	表示与模型交互的用户的输入，通常以文本或其他交互式输入的形式。
助手 assistant	表示来自模型的响应，可以包括文本或调用工具的请求。
工具 tool	一种消息，用于在检索外部数据或处理后将工具调用的结果传递回模型。与支持工具调用的聊天模型一起使用。
函数 function（旧版）	这是一个旧版角色，对应于 OpenAI 的旧版函数调用 API。应使用工具角色代替。

内容

消息内容可以是文本或表示多模态数据（例如，图像、音频、视频）的字典列表。内容的具体格式可能因不同的聊天模型提供商而异。

其他消息数据

根据聊天模型提供商，消息可能包含其他数据，例如

ID：消息的可选唯一标识符。
name：一个可选的 `name` 属性，允许区分具有相同角色的不同实体/发言者。并非所有模型都支持此功能！
metadata：关于消息的额外信息，例如时间戳、token 使用量等。
tool calls：模型发出的调用一个或多个工具的请求。有关更多信息，请参阅工具调用。

‍

对话结构

输入到聊天模型中的消息序列应遵循特定结构，以确保聊天模型可以生成有效响应

例如，典型的对话结构可能如下所示

用户消息：“你好，你怎么样？”
助手消息：“我很好，谢谢你的询问。”
用户消息：“你能给我讲个笑话吗？”
助手消息：“当然！稻草人为什么获奖？因为它在自己的领域表现出色！”

请阅读聊天历史指南，了解有关管理聊天历史和确保对话结构正确的更多信息。

‍

LangChain 消息

LangChain 提供了一种统一的消息格式，可用于所有聊天模型，允许用户使用不同的聊天模型，而无需担心每个模型提供商使用的消息格式的具体细节。

LangChain 消息是继承自==BaseMessage== 的 Python 对象。

‍

五种主要消息类型是

SystemMessage：对应**系统**角色
HumanMessage：对应**用户**角色
AIMessage：对应**助手**角色
AIMessageChunk：对应**助手**角色，用于流式响应
ToolMessage：对应**工具**角色

其他重要消息包括

RemoveMessage – 不对应任何角色。这是一种抽象，主要用于 LangGraph 中管理聊天历史。
**旧版** FunctionMessage：对应 OpenAI **旧版**函数调用 API 中的**函数**角色。

‍

SystemMessage

一个SystemMessage用于引导 AI 模型的行为并提供额外上下文，例如指示模型采用特定角色或设定对话的语气（例如，“这是一场关于烹饪的对话”）。

不同的聊天提供商可能通过以下方式之一支持系统消息

通过“系统”消息角色：在这种情况下，系统消息作为消息序列的一部分包含在内，其角色明确设置为“系统”。
通过单独的 API 参数用于系统指令：系统指令不是作为消息包含在内，而是通过专用的 API 参数传递。
不支持系统消息：有些模型根本不支持系统消息。LangChain 会尝试将系统消息的内容合并到 HumanMessage ====

大多数主要的聊天模型提供商通过聊天消息或单独的 API 参数支持系统指令。LangChain 将根据提供商的功能自动适应。如果提供商支持用于系统指令的单独 API 参数，LangChain 将提取系统消息的内容并通过该参数传递。

如果提供商不支持系统消息，在大多数情况下 ，LangChain 会尝试将系统消息的内容合并到 HumanMessage 中，或者如果无法做到，则抛出异常。

然而，此行为尚未在所有实现中一致执行，如果使用聊天模型的一个不太流行的实现（例如，来自 langchain-community 包的实现），建议查看该模型的具体文档。

‍

HumanMessage

一个 HumanMessage对应用户角色。人类消息表示与模型交互的用户的输入。

文本内容

大多数聊天模型期望用户输入以文本形式存在。

多模态内容

一些聊天模型接受多模态输入，例如图像、音频、视频或 PDF 等文件。

AIMessage

AIMessage 用于表示角色为助手的消息。这是模型的响应，可以包括文本或调用工具的请求。它还可以包括图像、音频或视频等其他媒体类型——尽管目前这仍然不常见。

一个 AIMessage 具有以下属性。标准化的属性是 LangChain 尝试在不同聊天模型提供商之间进行标准化的属性。

原始字段特定于模型提供商，并且可能有所不同。

属性	标准化/原始	描述
`content`	原始	通常是字符串，但可以是内容块列表。有关详细信息，请参阅内容。
`tool_calls`	标准化	与消息关联的工具调用。有关详细信息，请参阅工具调用。
`invalid_tool_calls`	标准化	与消息关联的带解析错误的工具调用。有关详细信息，请参阅工具调用。
`usage_metadata`	标准化	消息的使用元数据，例如token 计数。请参阅Usage Metadata API 参考。
`id`	标准化	消息的可选唯一标识符，理想情况下由创建消息的提供商/模型提供。
`response_metadata`	原始	响应元数据，例如响应头、logprobs、token 计数。

内容

AIMessage 的内容属性表示聊天模型生成的响应。

内容可以是

文本 – 几乎所有聊天模型的规范。
一个字典列表 - 每个字典代表一个内容块，并与一个 `type` 关联。
- 由 Anthropic 用于在进行工具调用时揭示代理思考过程。
- 由 OpenAI 用于音频输出。请参阅多模态内容以获取更多信息。

内容属性在不同聊天模型提供商之间未标准化，主要原因是从中概括的示例仍然很少。

AIMessageChunk

通常会将聊天模型的响应在生成时流式传输，这样用户可以实时看到响应，而不是等待整个响应生成后再显示。

它由聊天模型的 `stream`、`astream` 和 `astream_events` 方法返回。

AIMessageChunk 遵循与 AIMessage 几乎相同的结构，但使用不同的 ToolCallChunk 来以标准化方式流式传输工具调用。

聚合

`AIMessageChunks` 支持 `+` 运算符以将它们合并为一个 `AIMessage`。当您想要向用户显示最终响应时，这很有用。

‍

ToolMessage

这表示一个角色为“工具”的消息，其中包含调用工具的结果。除了 `role` 和 `content` 之外，此消息还具有

一个 `tool_call_id` 字段，它传达调用该工具以生成此结果的调用 ID。
一个 `artifact` 字段，可用于传递工具执行的任意工件，这些工件有助于跟踪但不应发送到模型。

RemoveMessage

这是一种不对应任何角色的特殊消息类型。它用于在LangGraph中管理聊天历史。

有关如何使用 `RemoveMessage` 的更多信息，请参阅以下内容

‍

（旧版）FunctionMessage

这是一个旧版消息类型，对应 OpenAI 的旧版函数调用 API。应使用 `ToolMessage` 以对应更新的工具调用 API。

‍

OpenAI 格式

输入

聊天模型也接受 OpenAI 格式作为聊天模型的输入

chat_model.invoke([
    {
        "role": "user",
        "content": "Hello, how are you?",
    },
    {
        "role": "assistant",
        "content": "I'm doing well, thank you for asking.",
    },
    {
        "role": "user",
        "content": "Can you tell me a joke?",
    }
])

输出

目前，模型的输出将是 LangChain 消息，因此如果您也需要 OpenAI 格式的输出，则需要将输出转换为 OpenAI 格式。

convert\_to\_openai\_messages 实用函数可用于将 LangChain 消息转换为 OpenAI 格式。

‍

实践练习

https://gitcode.com/k316378085/langchain_study_by_xkong/blob/main/src/langchain_base/01_first_demo_app/0104_messages.ipynb

习题

‍

📚 任务 2.2：掌握内容格式与多模态支持

✅ 一、内容格式对比表（文本 vs 多模态块）

对比维度	纯文本格式（Text-only）	多模态块格式（Dict List / Content Blocks）
数据结构	`str` 字符串	`List[Dict]` 字典列表，每个元素是一个“内容块”
示例	`"你好，今天过得怎么样？"`	`[{"type": "text", "text": "看这张图"}, {"type": "image_url", "image_url": {"url": "https://..."}}]`
适用模型	所有基础语言模型	支持多模态的模型（如 GPT-4V, Claude 3, Gemini等）
HumanMessage便捷写法	✅ `HumanMessage("文本")` 自动转换为字符串内容	❌ 必须显式传入 `content=[...]`
可包含元素	仅文本	文本、图片URL、图片Base64、音频、视频（依模型支持）
Anthropic 特点	不推荐直接用字符串，建议用 `[{"type":"text", ...}]`	✅ 官方推荐格式，支持 `text` + `image`
OpenAI 特点	✅ 支持字符串（自动转块）	✅ 支持块列表，图像需 `image_url` 类型
调试友好度	⭐⭐⭐⭐⭐ 简单直观	⭐⭐⭐ 需注意结构嵌套和字段名
扩展性	❌ 无法扩展	✅ 可添加新类型（如 `audio`, `video`, `document`）

✅ 二、“何时用字典列表”的判断标准

请在以下情况使用 List[Dict] 格式的内容块：

🚦 必须使用字典列表的情况：

需要传入非文本内容
→ 如图像、音频、视频等多模态输入。

HumanMessage(content=[
    {"type": "text", "text": "描述这张图"},
    {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
])

‍

术语

五类消息一句话定义模板

🔹 SystemMessage：用于 设定AI行为 或 对话上下文 的 系统指令消息 ，LangChain会根据提供商能力自动适配传递方式。

🔹 HumanMessage：代表 用户输入的消息 ，支持文本或自动转换字符串，是对话的触发起点。

🔹 AIMessage： 模型生成的响应消息 ，可包含文本、tool_calls或多媒体内容，是对话的 核心输出 。

🔹 ToolMessage： 携带工具执行结果的消息 ，必须包含tool_call_id以关联原始调用，是工具调用闭环的关键。

🔹 AIMessageChunk： 流式响应中的消息片段 ，支持 + 运算符聚合为完整 AIMessage，用于 实时输出 场景。

‍

进度跟踪卡

字段	说明	示例
里程碑完成度	关键节点的达成情况（与计划对比）	1. 完成5大消息的作用和结构字段 2. 转换openai格式与langchain格式
能力变化曲线	核心指标的趋势跟踪（如正确率、耗时、难度等级）	耗时： 2h 难度：简单
瓶颈突破记录	遇到的停滞期及解决方案（如平台期、动机下降、技术难点）
心理表征发展	对领域规律的认知深化（如模式识别、问题拆解能力的提升）	消息是对话的原子，是智能的载体。掌握 SystemMessage，你控制AI的“人格”；掌握 ToolMessage，你打通AI的“手脚”；掌握 Chunk，你实现AI的“实时呼吸”。
总结与展望	阶段性成果、不足及下一阶段计划调整	成果：不足：调整：