消息

先决条件

聊天模型

概述

消息是聊天模型中的通信单元。它们用于表示聊天模型的输入和输出，以及可能与对话关联的任何附加上下文或元数据。

每条消息都有一个角色（例如，“user”、“assistant”）和内容（例如，文本、多模态数据），以及因聊天模型提供商而异的其他元数据。

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

消息中包含什么？

消息通常包含以下信息：

角色：消息的角色（例如，“user”、“assistant”）。
内容：消息的内容（例如，文本、多模态数据）。
其他元数据：ID、名称、令牌使用情况以及其他模型特定的元数据。

角色

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

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

内容

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

目前，大多数聊天模型支持文本作为主要内容类型，一些模型也支持多模态数据。但是，多模态数据在大多数聊天模型提供商中的支持仍然有限。

有关更多信息，请参阅：

SystemMessage — 用于传递给指导对话的内容
HumanMessage — 用于用户输入的内容。
AIMessage — 用于模型响应的内容。
多模态 — 有关多模态内容的信息。

其他消息数据

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

ID：消息的可选唯一标识符。
名称：一个可选的 name 属性，用于区分同一角色的不同实体/说话者。并非所有模型都支持此功能！
元数据：消息的其他信息，例如时间戳、令牌使用情况等。
工具调用：模型调用一个或多个工具的请求。请参阅工具调用了解更多信息。

对话结构

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

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

用户消息：“你好，你好吗？”
助手消息：“我很好，谢谢你的询问。”
用户消息：“你能给我讲个笑话吗？”
助手消息：“当然！为什么稻草人获奖了？因为它出类拔萃！”

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

LangChain 消息

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

五个主要消息类型是：

SystemMessage：对应于 system 角色
HumanMessage：对应于 user 角色
AIMessage：对应于 assistant 角色
AIMessageChunk：对应于 assistant 角色，用于流式传输响应
ToolMessage：对应于 tool 角色

其他重要消息包括：

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

您可以在API 参考中找到有关消息的更多信息。

SystemMessage

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

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

通过“system”消息角色：在这种情况下，系统消息作为消息序列的一部分包含，角色显式设置为“system”。
通过系统指令的单独 API 参数：系统指令不是作为消息包含，而是通过专用 API 参数传递。
不支持系统消息：一些模型根本不支持系统消息。

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

如果提供商不支持系统消息，在大多数情况下，LangChain 会尝试将系统消息的内容合并到 HumanMessage 中，或者在无法做到时引发异常。但是，此行为尚未在所有实现中得到一致执行，如果使用聊天模型不太受欢迎的实现（例如，来自 langchain-community 软件包的实现），建议查看该模型的特定文档。

HumanMessage

HumanMessage 对应于 “user” 角色。HumanMessage 表示用户与模型交互的输入。

文本内容

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

from langchain_core.messages import HumanMessage

model.invoke([HumanMessage(content="Hello, how are you?")])

API Reference:HumanMessage

tip

当使用字符串作为输入调用聊天模型时，LangChain 会自动将字符串转换为 HumanMessage 对象。这对于快速测试很有用。

model.invoke("Hello, how are you?")

多模态内容

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

有关更多信息，请参阅多模态指南。

AIMessage

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

from langchain_core.messages import HumanMessage
ai_message = model.invoke([HumanMessage("Tell me a joke")])
ai_message # <-- AIMessage

API Reference:HumanMessage

AIMessage 具有以下属性。标准化的属性是 LangChain 尝试在不同聊天模型提供商之间进行标准化的属性。原始字段特定于模型提供商，可能会有所不同。

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

content

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

content 是以下之一：

文本——几乎所有聊天模型都如此。
字典列表——每个字典代表一个内容块，并关联一个 type。
- Anthropic 用于在执行工具调用时呈现代理思考过程。
- OpenAI 用于音频输出。请参阅多模态内容了解更多信息。

important

content 属性并未在不同的聊天模型提供商之间进行标准化，主要是因为到目前为止，可以进行泛化的示例仍然很少。

AIMessageChunk

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

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

例如，

for chunk in model.stream([HumanMessage("what color is the sky?")]):
    print(chunk)

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

聚合

AIMessageChunks 支持 + 运算符将其合并为单个 AIMessage。当您想向用户显示最终响应时，这很有用。

ai_message = chunk1 + chunk2 + chunk3 + ...

ToolMessage

这表示一个具有“tool”角色的消息，其中包含调用工具的结果。除了 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 格式。

概述​

消息中包含什么？​

角色​

内容​

其他消息数据​

对话结构​

LangChain 消息​

SystemMessage​

HumanMessage​

文本内容​

多模态内容​

AIMessage​

content​

AIMessageChunk​

聚合​

ToolMessage​

RemoveMessage​

(旧版) FunctionMessage​

OpenAI 格式​

输入​

输出​

概述