核心组件消息消息是 LangChain 中模型的基础上下文单元。它们代表模型的输入和输出承载着与 LLM 交互时表示对话状态所需的内容和元数据。消息是包含以下内容的对象角色Role- 标识消息类型例如系统、用户内容Content- 代表消息的实际内容如文本、图像、音频、文档等元数据Metadata- 可选字段如响应信息、消息 ID 和令牌使用情况LangChain 提供了一种适用于所有模型提供商的标准消息类型确保无论调用何种模型行为都保持一致。基本用法使用消息的最简单方法是创建消息对象并在调用时将它们传递给模型。fromlangchain.chat_modelsimportinit_chat_modelfromlangchain.messagesimportHumanMessage,AIMessage,SystemMessage modelinit_chat_model(gpt-5-nano)system_msgSystemMessage(你是一个有帮助的助手。)human_msgHumanMessage(你好你好吗)# 与聊天模型一起使用messages[system_msg,human_msg]responsemodel.invoke(messages)# 返回 AIMessage多轮智能体会积累较长的消息历史。LangSmith 会记录每一轮、工具结果和模型响应以便您可以检查完整的对话。请按照追踪快速入门指南启用追踪。我们建议您同时设置 LangSmith Engine它会监控您的追踪、检测问题并提出修复建议。文本提示文本提示是字符串 —— 适用于不需要保留对话历史的简单生成任务。responsemodel.invoke(写一首关于春天的俳句)在以下情况使用文本提示您有一个独立的单次请求您不需要对话历史您希望代码复杂度最低消息提示或者您可以通过提供消息对象列表来向模型传递消息列表。fromlangchain.messagesimportSystemMessage,HumanMessage,AIMessage messages[SystemMessage(你是一位诗歌专家),HumanMessage(写一首关于春天的俳句),AIMessage(樱花盛开...)]responsemodel.invoke(messages)在以下情况使用消息提示管理多轮对话处理多模态内容图像、音频、文件包含系统指令字典格式您也可以直接使用 OpenAI 聊天补全格式来指定消息。messages[{role:system,content:你是一位诗歌专家},{role:user,content:写一首关于春天的俳句},{role:assistant,content:樱花盛开...}]responsemodel.invoke(messages)消息类型系统消息System message- 告诉模型如何表现并为交互提供上下文人类消息Human message- 代表用户输入和与模型的交互AI 消息AI message- 模型生成的响应包括文本内容、工具调用和元数据工具消息Tool message- 代表工具调用的输出系统消息SystemMessage代表一组初始指令用于设定模型的行为。您可以使用系统消息来设定语气、定义模型的角色并建立回复的指导原则。基本指令system_msgSystemMessage(你是一位有帮助的编码助手。)messages[system_msg,HumanMessage(如何创建 REST API)]responsemodel.invoke(messages)详细的角色设定fromlangchain.messagesimportSystemMessage,HumanMessage system_msgSystemMessage( 你是一位资深 Python 开发者专精于 Web 框架。 始终提供代码示例并解释你的推理。 解释要简洁但全面。 )messages[system_msg,HumanMessage(如何创建 REST API)]responsemodel.invoke(messages)人类消息HumanMessage代表用户输入和交互。它们可以包含文本、图像、音频、文件以及任何其他形式的多模态内容。文本内容消息对象字符串快捷方式responsemodel.invoke([HumanMessage(什么是机器学习)])消息元数据添加元数据human_msgHumanMessage(content你好,namealice,# 可选识别不同用户idmsg_123,# 可选用于追踪的唯一标识符)name字段的行为因提供商而异 —— 有些将其用于用户识别有些则忽略。如需确认请参阅模型提供商的参考文档。AI 消息AIMessage代表模型调用的输出。它们可以包含多模态数据、工具调用以及提供商特定的元数据您可以在之后访问这些数据。responsemodel.invoke(解释人工智能)print(type(response))# class langchain.messages.AIMessage调用模型时会返回AIMessage对象其中包含响应中所有相关的元数据。提供商对消息类型的权重/上下文处理方式不同这意味着有时手动创建一个新的AIMessage对象并插入到消息历史中就像它来自模型一样会很有帮助。fromlangchain.messagesimportAIMessage,SystemMessage,HumanMessage# 手动创建一条 AI 消息例如用于对话历史ai_msgAIMessage(我很乐意帮助您回答那个问题)# 添加到对话历史中messages[SystemMessage(你是一个有帮助的助手),HumanMessage(你能帮我吗),ai_msg,# 像来自模型一样插入HumanMessage(太好了22 等于多少)]responsemodel.invoke(messages)属性工具调用当模型进行工具调用时它们会包含在AIMessage中fromlangchain.chat_modelsimportinit_chat_model modelinit_chat_model(gpt-5-nano)defget_weather(location:str)-str:获取某个位置的天气。...model_with_toolsmodel.bind_tools([get_weather])responsemodel_with_tools.invoke(巴黎的天气怎么样)fortool_callinresponse.tool_calls:print(f工具:{tool_call[name]})print(f参数:{tool_call[args]})print(fID:{tool_call[id]})其他结构化数据如推理或引用也可能出现在消息内容中。令牌使用情况AIMessage可以在其usage_metadata字段中保存令牌计数和其他使用情况元数据fromlangchain.chat_modelsimportinit_chat_model modelinit_chat_model(gpt-5-nano)responsemodel.invoke(你好)response.usage_metadata{input_tokens:8,output_tokens:304,total_tokens:312,input_token_details:{audio:0,cache_read:0},output_token_details:{audio:0,reasoning:256}}详情请参阅UsageMetadata。流式传输和数据块在流式传输过程中您会收到AIMessageChunk对象这些对象可以组合成一个完整的消息对象chunks[]full_messageNoneforchunkinmodel.stream(嗨):chunks.append(chunk)print(chunk.text)full_messagechunkiffull_messageisNoneelsefull_messagechunk了解更多从聊天模型流式传输令牌从智能体流式传输令牌和/或步骤工具消息对于支持工具调用的模型AI 消息可以包含工具调用。工具消息用于将单次工具执行的结果传回模型。工具可以直接生成ToolMessage对象。下面我们展示一个简单的例子。更多信息请参阅工具指南。fromlangchain.messagesimportAIMessagefromlangchain.messagesimportToolMessage# 在模型进行工具调用之后# 为简洁起见我们在此演示手动创建消息ai_messageAIMessage(content[],tool_calls[{name:get_weather,args:{location:旧金山},id:call_123}])# 执行工具并创建结果消息weather_result晴朗72°Ftool_messageToolMessage(contentweather_result,tool_call_idcall_123# 必须与调用 ID 匹配)# 继续对话messages[HumanMessage(旧金山的天气怎么样),ai_message,# 模型的工具调用tool_message,# 工具执行结果]responsemodel.invoke(messages)# 模型处理结果属性artifact字段存储不会发送给模型的补充数据但可以通过编程方式访问。这对于存储原始结果、调试信息或用于下游处理的数据非常有用而不会使模型的上下文变得混乱。示例将 artifact 用于检索元数据消息内容您可以将消息的内容视为发送给模型的数据负载。消息有一个content属性它是松散类型的支持字符串和未类型化对象例如字典的列表。这使得 LangChain 聊天模型可以直接支持提供商本地的结构例如多模态内容和其他数据。另外LangChain 为文本、推理、引用、多模态数据、服务器端工具调用和其他消息内容提供了专门的内容类型。请参见下面的内容块。LangChain 聊天模型接受content属性中的消息内容。这可能包含一个字符串提供商本地格式的内容块列表LangChain 标准内容块列表下面是一个使用多模态输入的示例fromlangchain.messagesimportHumanMessage# 字符串内容human_messageHumanMessage(你好你好吗)# 提供商本地格式例如 OpenAIhuman_messageHumanMessage(content[{type:text,text:你好你好吗},{type:image_url,image_url:{url:https://example.com/image.jpg}}])# 标准内容块列表human_messageHumanMessage(content_blocks[{type:text,text:你好你好吗},{type:image,url:https://example.com/image.jpg},])在初始化消息时指定content_blocks仍然会填充消息的content但提供了一种类型安全的接口来执行此操作。标准内容块LangChain 为消息内容提供了一种适用于所有提供商的标准表示。消息对象实现了content_blocks属性该属性会将content属性惰性解析为标准的、类型安全的表示。例如由ChatAnthropic或ChatOpenAI生成的消息将分别包含各自提供商的思考或推理块但可以惰性解析为一致的ReasoningContentBlock表示AnthropicOpenAIfromlangchain.messagesimportAIMessage messageAIMessage(content[{type:thinking,thinking:...,signature:WaUjzkyp...},{type:text,text:...},],response_metadata{model_provider:anthropic})message.content_blocks[{type:reasoning,reasoning:...,extras:{signature:WaUjzkyp...}},{type:text,text:...}]请参阅集成指南开始使用您选择的推理提供商。序列化标准内容如果 LangChain 外部的应用程序需要访问标准内容块表示您可以选择将内容块存储在消息内容中。为此您可以将LC_OUTPUT_VERSION环境变量设置为v1。或者使用output_versionv1初始化任何聊天模型fromlangchain.chat_modelsimportinit_chat_model modelinit_chat_model(gpt-5-nano,output_versionv1)多模态多模态是指处理不同形式数据的能力例如文本、音频、图像和视频。LangChain 包含这些数据的标准类型可以跨提供商使用。聊天模型可以接受多模态数据作为输入并生成多模态数据作为输出。下面我们展示了包含多模态数据的输入消息的简短示例。额外的键可以包含在内容块的顶层或嵌套在extras: {key: value}中。例如OpenAI 要求 PDF 文件提供文件名。有关具体细节请参阅您所选模型的提供商页面。图像输入PDF 文档输入音频输入视频输入# 从 URLmessage{role:user,content:[{type:text,text:描述这张图片的内容。},{type:image,url:https://example.com/path/to/image.jpg},]}# 从 base64 数据message{role:user,content:[{type:text,text:描述这张图片的内容。},{type:image,base64:AAAAIGZ0eXBtcDQyAAAAAGlzb21tcDQyAAACAGlzb2...,mime_type:image/jpeg,},]}# 从提供商管理的文件 IDmessage{role:user,content:[{type:text,text:描述这张图片的内容。},{type:image,file_id:file-abc123},]}并非所有模型都支持所有文件类型。请查看模型提供商的参考文档了解支持的格式和大小限制。内容块参考内容块在创建消息时或访问content_blocks属性时以类型化字典列表的形式表示。列表中的每个项目必须遵循以下块类型之一核心多模态工具调用服务器端工具执行提供商特定块请查看 API 参考中的规范类型定义。内容块是在 LangChain v1 中作为消息的新属性引入的目的是在保持与现有代码向后兼容的同时标准化不同提供商之间的内容格式。内容块并不是content属性的替代品而是可以用来以标准化格式访问消息内容的新属性。与聊天模型一起使用聊天模型接受一系列消息对象作为输入并返回一个AIMessage作为输出。交互通常是无状态的因此一个简单的对话循环涉及使用不断增长的消息列表来调用模型。请参阅以下指南以了解更多信息用于持久化和管理对话历史的内置功能管理上下文窗口的策略包括修剪和总结消息
)
