消息

¥Messages

Prerequisites

• 聊天模型

  ¥Chat Models

概述

¥Overview

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

¥Messages are the unit of communication in chat models. They are used to represent the input and output of a chat model, as well as any additional context or metadata that may be associated with a conversation.

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

¥Each message has a role (e.g., "user", "assistant"), content (e.g., text, multimodal data), and additional metadata that can vary depending on the chat model provider.

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

¥LangChain provides a unified message format that can be used across chat models, allowing users to work with different chat models without worrying about the specific details of the message format used by each model provider.

消息中的内容是什么？

¥What inside a message?

一条消息通常包含以下信息：

¥A message typically consists of the following pieces of information:

• 角色：消息的角色（例如 "user"、"assistant"）。

  ¥Role: The role of the message (e.g., "user", "assistant").

• 内容：消息的内容（例如，文本、多模态数据）。

  ¥Content: The content of the message (e.g., text, multimodal data).

• 附加元数据：id、name、令牌使用 和其他特定于模型的元数据。

  ¥Additional metadata: id, name, token usage and other model-specific metadata.

角色

¥Role

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

¥Roles are used to distinguish between different types of messages in a conversation and help the chat model understand how to respond to a given sequence of messages.

Role	Description
system	Used to tell the chat model how to behave and provide additional context. Not supported by all chat model providers.
user	Represents input from a user interacting with the model, usually in the form of text or other interactive input.
assistant	Represents a response from the model, which can include text or a request to invoke tools.
tool	A message used to pass the results of a tool invocation back to the model after external data or processing has been retrieved. Used with chat models that support tool calling.
function (legacy)	This is a legacy role, corresponding to OpenAI's legacy function-calling API. tool role should be used instead.

内容

¥Content

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

¥The content of a message text or an array of objects representing multimodal data (e.g., images, audio, video). The exact format of the content can vary between different chat model providers.

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

¥Currently, most chat models support text as the primary content type, with some models also supporting multimodal data. However, support for multimodal data is still limited across most chat model providers.

更多信息请参见：

¥For more information see:

• HumanMessage — 用于用户输入的内容。

  ¥HumanMessage -- for content in the input from the user.

• AIMessage — 用于模型响应的内容。

  ¥AIMessage -- for content in the response from the model.

• 多模态 — 用于获取有关多模态内容的更多信息。

  ¥Multimodality -- for more information on multimodal content.

其他消息数据

¥Other Message Data

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

¥Depending on the chat model provider, messages can include other data such as:

• ID:可选的消息唯一标识符。

  ¥ID: An optional unique identifier for the message.

• 名称：可选的 name 属性，用于区分具有相同角色的不同实体/发言人。并非所有模型都支持此格式！

  ¥Name: An optional name property which allows differentiate between different entities/speakers with the same role. Not all models support this!

• 元数据：有关消息的其他信息，例如时间戳、令牌使用情况等。

  ¥Metadata: Additional information about the message, such as timestamps, token usage, etc.

• 工具调用：模型发出的调用一个或多个工具的请求 > 更多信息请参阅 工具调用。

  ¥Tool Calls: A request made by the model to call one or more tools> See tool calling for more information.

对话结构

¥Conversation Structure

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

¥The sequence of messages into a chat model should follow a specific structure to ensure that the chat model can generate a valid response.

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

¥For example, a typical conversation structure might look like this:

1. 用户消息："你好，你好吗？"

   ¥User Message: "Hello, how are you?"

2. 助手消息："我很好，谢谢你的关心。"

   ¥Assistant Message: "I'm doing well, thank you for asking."

3. 用户消息："你能给我讲个 Jest 吗？"

   ¥User Message: "Can you tell me a joke?"

4. 助手消息：“当然可以！”为什么稻草人会获奖？因为他在他的字段非常杰出！

   ¥Assistant Message: "Sure! Why did the scarecrow win an award? Because he was outstanding in his field!"

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

¥Please read the chat history guide for more information on managing chat history and ensuring that the conversation structure is correct.

LangChain 消息

¥LangChain Messages

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

¥LangChain provides a unified message format that can be used across all chat models, allowing users to work with different chat models without worrying about the specific details of the message format used by each model provider.

LangChain 消息是从 BaseMessage 继承而来的子类。

¥LangChain messages are classes that subclass from a BaseMessage.

五种主要消息类型为：

¥The five main message types are:

• SystemMessage：对应系统角色

  ¥SystemMessage: corresponds to system role

• HumanMessage：对应用户角色

  ¥HumanMessage: corresponds to user role

• AIMessage：对应助理角色

  ¥AIMessage: corresponds to assistant role

• AIMessageChunk：对应于助手角色，用于 streaming 回复

  ¥AIMessageChunk: corresponds to assistant role, used for streaming responses

• ToolMessage：对应工具角色

  ¥ToolMessage: corresponds to tool role

其他重要信息包括：

¥Other important messages include:

• RemoveMessage - 不对应任何角色。这是一种抽象概念，主要用于 LangGraph 中管理聊天历史记录。

  ¥RemoveMessage -- does not correspond to any role. This is an abstraction, mostly used in LangGraph to manage chat history.

• 旧版 FunctionMessage：对应于 OpenAI 旧式函数调用 API 中的函数角色。

  ¥Legacy FunctionMessage: corresponds to the function role in OpenAI's legacy function-calling API.

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

¥You can find more information about messages in the API Reference.

SystemMessage

SystemMessage 用于启动 AI 模型的行为并提供额外的上下文，例如指示模型采用特定角色或设定对话基调（例如 "这是一段关于烹饪的对话"）。

¥A SystemMessage is used to prime the behavior of the AI model and provide additional context, such as instructing the model to adopt a specific persona or setting the tone of the conversation (e.g., "This is a conversation about cooking").

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

¥Different chat providers may support system message in one of the following ways:

• 通过 "system" 消息角色：在本例中，系统消息作为消息序列的一部分包含在内，其角色明确设置为 "系统。"。

  ¥Through a "system" message role: In this case, a system message is included as part of the message sequence with the role explicitly set as "system."

• 通过单独的 API 参数进行系统指令：系统指令不是以消息形式包含，而是通过专用 API 参数传递。

  ¥Through a separate API parameter for system instructions: Instead of being included as a message, system instructions are passed via a dedicated API parameter.

• 不支持系统消息：某些模型根本不支持系统消息。

  ¥No support for system messages: Some models do not support system messages at all.

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

¥Most major chat model providers support system instructions via either a chat message or a separate API parameter. LangChain will automatically adapt based on the provider’s capabilities. If the provider supports a separate API parameter for system instructions, LangChain will extract the content of a system message and pass it through that parameter.

如果提供程序不支持任何系统消息，在大多数情况下，LangChain 会尝试将系统消息的内容合并到 HumanMessage 中，如果无法合并，则会引发异常。然而，此行为尚未在所有实现中一致执行，如果使用不太流行的聊天模型实现（例如，来自 @langchain/community 包的实现），建议查看该模型的具体文档。

¥If no system message is supported by the provider, in most cases LangChain will attempt to incorporate the system message's content into a HumanMessage or raise an exception if that is not possible. However, this behavior is not yet consistently enforced across all implementations, and if using a less popular implementation of a chat model (e.g., an implementation from the @langchain/community package) it is recommended to check the specific documentation for that model.

HumanMessage

HumanMessage 对应 "user" 角色。人工消息表示用户与模型交互的输入。

¥The HumanMessage corresponds to the "user" role. A human message represents input from a user interacting with the model.

文本内容

¥Text Content

大多数聊天模型都要求用户以文本形式输入。

¥Most chat models expect the user input to be in the form of text.

import { HumanMessage } from "@langchain/core/messages";

await model.invoke([new HumanMessage("Hello, how are you?")]);

tip

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

¥When invoking a chat model with a string as input, LangChain will automatically convert the string into a HumanMessage object. This is mostly useful for quick testing.

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

多模态内容

¥Multi-modal Content

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

¥Some chat models accept multimodal inputs, such as images, audio, video, or files like PDFs.

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

¥Please see the multimodality guide for more information.

AIMessage

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

¥AIMessage is used to represent a message with the role "assistant". This is the response from the model, which can include text or a request to invoke tools. It could also include other media types like images, audio, or video -- though this is still uncommon at the moment.

import { HumanMessage } from "@langchain/core/messages";

const aiMessage = await model.invoke([new HumanMessage("Tell me a joke")]);
console.log(aiMessage);

AIMessage({
  content: "Why did the chicken cross the road?\n\nTo get to the other side!",
  tool_calls: [],
  response_metadata: { ... },
  usage_metadata: { ... },
})

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

¥An AIMessage has the following attributes. The attributes which are standardized are the ones that LangChain attempts to standardize across different chat model providers. raw fields are specific to the model provider and may vary.

Attribute	Standardized/Raw	Description
content	Raw	Usually a string, but can be a list of content blocks. See content for details.
tool_calls	Standardized	Tool calls associated with the message. See tool calling for details.
invalid_tool_calls	Standardized	Tool calls with parsing errors associated with the message. See tool calling for details.
usage_metadata	Standardized	Usage metadata for a message, such as token counts. See Usage Metadata API Reference.
id	Standardized	An optional unique identifier for the message, ideally provided by the provider/model that created the message.
response_metadata	Raw	Response metadata, e.g., response headers, logprobs, token counts.

content

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

¥The content property of an AIMessage represents the response generated by the chat model.

内容如下：

¥The content is either:

• 文本 - 几乎所有聊天模型的标准。

  ¥text -- the norm for virtually all chat models.

• 对象数组 - 每个对象代表一个内容块，并与一个 type 关联。

  ¥A array of objects -- Each object represents a content block and is associated with a type.

  • Anthropic 使用它来在执行 工具调用 时展现代理的思维过程。

    ¥Used by Anthropic for surfacing agent thought process when doing tool calling.

  • OpenAI 使用它来输出音频。请参阅 多模态内容 获取更多信息。

    ¥Used by OpenAI for audio outputs. Please see multi-modal content for more information.

info

不同聊天模型提供商的 content 属性尚未标准化，主要是因为可供借鉴的示例仍然很少。

¥The content property is not standardized across different chat model providers, mostly because there are still few examples to generalize from.

AIMessageChunk

聊天模型的 stream 响应在生成时很常见，因此用户可以实时查看响应，而不必等待整个响应生成后再显示。

¥It is common to stream responses for the chat model as they are being generated, so the user can see the response in real-time instead of waiting for the entire response to be generated before displaying it.

它由聊天模型的 stream 和 streamEvents 方法返回。

¥It is returned from the stream, and streamEvents methods of the chat model.

例如，

¥For example,

for await (const chunk of model.stream([
  new HumanMessage("what color is the sky?"),
])) {
  console.log(chunk);
}

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

¥AIMessageChunk follows nearly the same structure as AIMessage, but uses a different ToolCallChunk to be able to stream tool calling in a standardized manner.

聚合

¥Aggregating

<Type>MessageChunks 有一个 concat 方法可供你使用，或者你可以导入它。当你想要向用户显示最终响应时，这很有用。

¥<Type>MessageChunks have a concat method you can use, or you can import it. This is useful when you want to display the final response to the user.

const aiMessage = chunk1.concat(chunk2).concat(chunk3).concat(...);

or

import { concat } from "@langchain/core/utils/stream";
const aiMessage = concat(chunk1, chunk2);

ToolMessage

这表示一条具有角色 "tool" 的消息，其中包含 调用工具 的结果。除了 role 和 content 之外，此消息还包含：

¥This represents a message with role "tool", which contains the result of calling a tool. In addition to role and content, this message has:

• tool_call_id 字段用于传递调用该工具的 ID，该工具被调用来生成此结果。

  ¥a tool_call_id field which conveys the id of the call to the tool that was called to produce this result.

• 一个 artifact 字段，可用于传递工具执行过程中的任意工件，这些工件可用于跟踪，但不应发送给模型。

  ¥an artifact field which can be used to pass along arbitrary artifacts of the tool execution which are useful to track but which should not be sent to the model.

请参阅 工具调用 获取更多信息。

¥Please see tool calling for more information.

RemoveMessage

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

¥This is a special message type that does not correspond to any roles. It is used for managing chat history in LangGraph.

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

¥Please see the following for more information on how to use the RemoveMessage:

• 内存概念指南

  ¥Memory conceptual guide

• 如何删除消息

  ¥How to delete messages

（旧版）FunctionMessage

¥(Legacy) FunctionMessage

这是一种旧版消息类型，与 OpenAI 的旧版函数调用 API 相对应。应使用 ToolMessage 来对应更新的工具调用 API。

¥This is a legacy message type, corresponding to OpenAI's legacy function-calling API. ToolMessage should be used instead to correspond to the updated tool-calling API.

OpenAI 格式

¥OpenAI Format

输入

¥Inputs

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

¥Chat models also accept OpenAI's format as inputs to chat models:

await chatModel.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?",
  },
]);

输出

¥Outputs

目前，模型的输出将以 LangChain 消息的形式呈现，因此如果你也需要 OpenAI 格式的输出，则需要将输出转换为 OpenAI 格式。

¥At the moment, the output of the model will be in terms of LangChain messages, so you will need to convert the output to the OpenAI format if you need OpenAI format for the output as well.