系列文章LangChain 1.0 入门一Runnable 统一接口全解析含完整代码逐行输出解读LangChain 1.0 入门二LangChain 全模型标准化接入最佳实践小白参数详解版LangChain 1.0 入门三稳定性双核心——重试机制速率限速器参数详解与实战LangChain 1.0 入门四 Messages 深度解析——大模型对话上下文核心单元LangChain 1.0 入门五提示词工程、partial变量、ChatPromptTemplate、Hub模板库前言当我们调用大模型对话接口时模型并不能自动记忆聊天历史。每一次调用 LLM 都是一次独立无状态请求。Messages 是 LangChain 1.0 中构建对话、Agent、RAG 应用的基石。很多开发者写多轮对话记不住上下文、多模态调用异常、工具调用报错根源大多是对消息对象理解不到位。本文结合 LangChain 官方文档从底层概念、消息类型、三种调用方式、多模态 Content‑Blocks、序列化持久化、实战案例以及踩坑点完整讲解 Messages。ChatGPT 类产品能够实现多轮对话本质是不断把完整对话消息数组提交给大模型。在 OpenAI 原生接口中它是messages数组在 LangChain 1.0被封装成一套标准消息对象Messages。Messages 的核心思想把对话做结构化拆分区分角色、内容、元数据实现 Prompt 模块化、可维护兼容各家大模型服务商。参考文档LangChain 官方文档https://docs.langchain.com/oss/python/langchain/messagesMessages 并非 LangChain 独创这套消息结构和 OpenAI、Anthropic Claude、Gemini、Ollama 的 Chat 接口格式对齐知识可以跨平台迁移。一、Messages 核心三要素每一条消息对象都由Role角色、Content内容、Metadata元数据三部分构成。要素说明Role 角色标识这条消息是谁发出的决定模型解析优先级system/human/ai/toolContent 内容消息载荷可以是普通字符串也可以是文本、图片、PDF、音频、视频的内容块Metadata 元数据可选字段不会发送给模型用于调试追踪消息id、用户名、Token消耗、原始响应信息角色优先级从高到低system developer human assistant tool。system系统指令拥有最高优先级用来定义模型身份、回答风格、业务约束。二、四大标准消息类型详解LangChain四大消息类型只封装跨模型通用角色OpenAI专属的developer没有独立消息类可通过ChatMessage或原生字典使用跨模型开发优先用SystemMessage。LangChain1.0 提供4种核心消息类一一对应对话中不同角色。1. SystemMessage 系统消息用于初始化模型行为设定人设、任务、输出约束优先级最高。fromlangchain.messagesimportSystemMessage,HumanMessage system_msgSystemMessage( 你是一名资深Python开发工程师。 回答必须附带简短可运行代码解释简洁。 )messages[system_msg,HumanMessage(如何读取CSV文件)]最佳实践一条合格的 System 提示词包含4点角色定义、任务目标、输出风格、约束条件。2. HumanMessage 用户消息代表用户输入支持普通文本同时也是多模态的载体可以携带图片、PDF、音频文件。还可以附加元数据name、id用于区分不同用户会话。human_msgHumanMessage(content帮我分析这张图表,nameuser_alice,idmsg_001)3. AIMessage AI消息模型调用完成返回的对象代表模型输出。重要属性content模型输出文本tool_calls当模型需要调用工具时存放函数调用参数usage_metadata统计输入输出 Tokencontent_blocksLangChain1.0标准化多模态/推理内容块id消息唯一标识respmodel.invoke(简单介绍LangChain)print(type(resp))# langchain.messages.AIMessageprint(resp.usage_metadata)重点可以手动构造 AIMessage 对象插入消息列表用来补全历史对话。4. ToolMessage 工具消息专门用于Agent工具调用场景把工具执行结果回传给大模型。⚠️硬性约束tool_call_id必须和 AIMessage 的 tool_calls.id 完全匹配否则模型无法关联调用与返回结果。特殊字段artifact存放调试、溯源元数据不会发送给模型仅程序内部读取适合RAG存储文档id、页码等信息。fromlangchain.messagesimportAIMessage,ToolMessage# 模拟模型发起工具调用ai_msgAIMessage(content[],tool_calls[{name:get_weather,args:{location:上海},id:call_001}])# 模拟工具返回结果tool_msgToolMessage(content上海多云26℃,tool_call_idcall_001,nameget_weather,artifact{city_code:sh001}# 不传给模型)msgs[HumanMessage(上海天气),ai_msg,tool_msg]model.invoke(msgs)三、三种消息传入方式对比LangChain支持三种消息输入方式可以互相混用框架内部自动做格式转换。方式示例代码适用场景Text Prompts 纯字符串model.invoke(写一首俳句)单次独立请求不需要对话历史追求代码极简Message Prompts 消息对象 ✅推荐传入SystemMessage、HumanMessage对象列表多轮对话、多模态输入、系统指令类型安全IDE提示友好Dictionary Format字典格式OpenAI原生role/content字典数组旧OpenAI项目迁移兼容原生接口格式# 方式1 纯字符串res1model.invoke(写一首关于春天的小诗)# 方式2 消息对象官方推荐msgs_obj[SystemMessage(你是诗歌专家),HumanMessage(写一首关于春天的小诗)]res2model.invoke(msgs_obj)# 方式3 OpenAI字典格式msgs_dict[{role:system,content:你是诗歌专家},{role:user,content:写一首关于春天的小诗}]res3model.invoke(msgs_dict)四、LangChain1.0 Content‑Blocks 标准内容块重要新特性LangChain1.0 引入content_blocks用来统一不同厂商的多模态格式解决OpenAI、Claude、Gemini多模态入参格式不一致的痛点。消息的 content 可以接收3种格式普通字符串模型服务商原生格式字典LangChain标准content_blocks推荐跨模型兼容。fromlangchain.messagesimportHumanMessage# 1.字符串msg1HumanMessage(描述图片)# 2.OpenAI原生格式msg2HumanMessage(content[{type:text,text:描述图片},{type:image_url,image_url:{url:https://xxx.jpg}}])# 3.标准content_blocks【推荐】msg3HumanMessage(content_blocks[{type:text,text:描述图片},{type:image,url:https://xxx.jpg}])支持的内容块类型text文本、reasoning模型推理思考过程、image图片、audio音频、video视频、filePDF文档、tool_call工具调用。开启完整content_blocks输出初始化模型设置output_versionv1或者设置环境变量LC_OUTPUT_VERSIONv1。五、消息序列化与会话持久化实际业务中我们需要把对话保存到文件、数据库实现会话恢复。LangChain提供dumpd/load完成序列化与反序列化。fromlangchain.messagesimportHumanMessagefromlangchain_core.loadimportdumpd,load msgHumanMessage(法国的首都是哪里)# 对象转字典序列化serializeddumpd(msg)# 字典恢复消息对象restore_msgload(serialized)⚠️安全警告load()会实例化Python对象绝对不要加载不受信任来源的序列化数据会存在安全副作用。六、流式输出 AIMessageChunk调用model.stream()不会直接返回完整AIMessage而是返回分片对象AIMessageChunk可以使用运算符把分片合并成完整消息。full_msgNoneforchunkinmodel.stream([SystemMessage(简短回答),HumanMessage(介绍Python)]):print(chunk.text,end)full_msgchunkiffull_msgisNoneelsefull_msgchunk七、实战完整可运行多轮对话助手核心原理大模型是无状态记忆全部依赖维护不断增长的messages列表。每一轮必须完成三步用户消息追加进列表调用模型传入完整消息列表把模型返回AIMessage追加到列表极易漏掉漏掉就丢失上下文完整依赖安装pipinstalllangchain langchain-openai python-dotenv.env配置文件# 通用固定参数全局生效 TEMPERATURE0.7 MAX_TOKENS2048 TIMEOUT120 # 1. OpenAI 官方 # BASE_URLhttps://api.openai.com/v1 # API_KEYsk-xxxxxxxxxxxxxxxx # MODEL_NAMEgpt-4o-mini # 2. DeepSeek 深度求索 # BASE_URLhttps://api.deepseek.com/v1 # API_KEYsk-xxxxxxxxxxxxxxxx # MODEL_NAMEdeepseek-chat # 3. 阿里通义千问 # BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 # API_KEYsk-xxxxxxxxxxxxxxxx # MODEL_NAMEqwen-turbo # 4. 智谱AI GLM # BASE_URLhttps://open.bigmodel.cn/api/paas/v4 # API_KEYxxxxxxxxxxxxxxxx # MODEL_NAMEglm-4 # 5. 本地 Ollama离线免费 BASE_URLhttp://127.0.0.1:11434/v1 API_KEYdummy MODEL_NAMEqwen2.5:7b # 6. 本地 vLLM 推理服务 # BASE_URLhttp://localhost:8000/v1 # API_KEYEMPTY # MODEL_NAME你部署的模型名业务代码importosimportjsonfromdotenvimportload_dotenvfromlangchain.chat_modelsimportinit_chat_modelfromlangchain.messagesimportSystemMessage,HumanMessagefromlangchain_core.loadimportdumpd load_dotenv()defget_model():returnmodelChatOpenAI(# 1. 接口地址不同厂商唯一区别必须带 /v1base_urlos.getenv(BASE_URL),# 2. 密钥云端模型填官网key本地模型随便填api_keyos.getenv(API_KEY),# 3. 模型名对应厂商的模型名称modelos.getenv(MODEL_NAME),# 4. 可选参数创造性、最大长度、超时时间temperaturefloat(os.getenv(TEMPERATURE,0.7)),max_tokensint(os.getenv(MAX_TOKENS,2048)),timeoutint(os.getenv(TIMEOUT,120)),)defchat_loop():modelget_model()messages[SystemMessage(你是技术答疑助手回答简洁结束询问用户是否还有其他问题。)]print(对话已启动输入 exit 退出)whileTrue:user_inputinput(user ).strip()ifuser_input.lower()in[exit,退出]:print(assistant 会话结束)breakifnotuser_input:continuemessages.append(HumanMessage(user_input))respmodel.invoke(messages)print(fassistant {resp.content})# 关键保存AI回复维持对话记忆messages.append(resp)# 保存会话withopen(chat_history.json,w,encodingutf‑8)asf:json.dump([dumpd(m)forminmessages],f,ensure_asciiFalse,indent2)if__name____main__:chat_loop()八、常见问题与生产最佳实践常见坑多轮对话模型记不住历史没有把模型返回的AIMessage追加进消息列表。LLM本身无状态记忆全部靠传入完整消息数组。ToolMessage工具调用异常tool_call_id没有和AIMessage内部tool_calls的id一一对应。反序列化安全漏洞不要调用load()解析来自外部、前端提交的json会话数据。多模态图片/PDF不生效不是所有模型支持全部多模态格式需要查阅对应模型服务商文档。上下文窗口溢出消息列表越来越长token超限。生产环境要引入消息修剪trimming或者摘要summarizing策略裁剪早期对话。最佳实践优先使用消息对象而不是原生字典拥有更好IDE类型提示System提示词要写完整角色、任务、风格、约束多模态场景优先使用content_blocks跨模型兼容读取usage_metadata监控token消耗控制成本敏感业务数据不要放入messages全部消息会提交给模型服务商生产环境会话持久化不要直接依赖dumpd/load做好数据校验。九、学习总结Messages是LangChain上下文基础单元由Role、Content、Metadata三要素组成四类核心消息对象SystemMessage、HumanMessage、AIMessage、ToolMessage三种调用方式推荐消息对象LangChain1.0新增content_blocks统一多模态格式LLM无状态多轮对话靠维护完整消息列表dumpd序列化保存会话load恢复会话注意安全风险流式输出得到AIMessageChunk分片支持分片相加合并完整消息。掌握Messages是学习PromptTemplate、Chain、Agent、RAG的前置基础。掌握之后就可以继续学习工具调用、消息窗口裁剪、LangSmith链路追踪等生产级能力。