1. 从混乱到秩序为什么我们需要标准消息格式如果你最近在折腾大模型不管是调用 OpenAI 的 GPT、DeepSeek 的 API还是自己部署一个 Llama、Qwen 之类的开源模型大概率都见过类似api error: 400 type must be in [enabled, disabled, auto]或者error: http post https://api.siliconflow.cn/v1/chat/completions failed这样的报错。这些错误背后很大一部分原因都指向同一个东西消息格式。这玩意儿听起来简单不就是把用户说的话发给模型再把模型的回复拿回来吗但当你真正开始对接不同厂商、不同模型甚至同一个模型的不同版本时就会发现这里面的水有多深。有的 API 要求消息是个数组里面每个对象要有role和content有的还要求name字段有的对system角色的消息位置有特殊要求更别提那些五花八门的temperature、max_tokens、stream参数了。一个字段拼错或者一个枚举值传得不合规范等待你的就是冰冷的400 Bad Request。所以今天我们不聊高深的模型原理也不讲复杂的微调技巧就扎扎实实地把“大模型 Chat 接口的标准消息格式”这件事掰开揉碎了讲清楚。我会结合 OpenAI、AnthropicClaude、DeepSeek 以及开源模型常用的 OpenAI 兼容 API 的实际例子告诉你这个标准格式是什么、为什么这么设计、以及在实际开发中你会遇到哪些坑又该如何优雅地跨平台处理。无论你是刚入门的新手还是在为产品对接多个模型而头疼的开发者这篇文章都能给你一套清晰的“操作手册”。2. 核心结构拆解一条标准消息里到底有什么几乎所有主流大模型的 Chat Completion API都遵循着一个相似的核心结构。我们可以把它想象成一场有剧本的对话而 API 的请求体就是这个剧本的“舞台指令”和“台词本”。2.1 消息列表对话的骨架最核心的部分是messages字段它是一个数组按顺序记录了整段对话。数组里的每个元素都是一个消息对象代表对话中的一个“回合”。这是对话能够保持上下文连贯性的关键。{ model: gpt-4o, messages: [ {role: system, content: 你是一个乐于助人的助手。}, {role: user, content: 你好今天天气怎么样}, {role: assistant, content: 你好我是一个AI无法获取实时天气信息。你可以通过天气预报应用或网站查询你所在地区的天气。}, {role: user, content: 那你能告诉我北京的历史天气规律吗} ] }这个数组的顺序至关重要。模型会严格按照这个顺序来理解对话的演进过程。通常对话以system角色如果有的话开始然后是user和assistant的交替。你不能把assistant的回复放在user的问题之前那会让模型感到困惑。2.2 角色定义谁在说话每个消息对象里role字段定义了发言者的身份。目前主流的角色有三种system系统指令。用于在对话开始前设定 AI 助手的身份、行为准则和回答风格。例如“你是一位资深软件架构师用简洁专业的语言回答问题。” 这个角色的消息通常只出现一次并且放在messages数组的开头。注意并非所有 API 都支持system角色。一些早期或精简的 API 可能要求你将系统指令作为第一个user消息发送。user用户。代表人类用户输入的问题或指令。这是驱动对话的主要角色。assistant助手。代表 AI 模型之前的回复。在发起新的请求时你必须将历史对话中模型的所有回复都以role: “assistant”的形式包含在messages数组中。这是实现多轮对话的关键。如果你只发送最新的user消息模型就失去了上下文相当于开始了一段全新的对话。一个常见的误解有人认为assistant消息是我们在请求时“预测”或“填充”的。不对。assistant消息是历史事实是模型之前已经生成过的内容。我们把它放进去是告诉模型“看这是我们之前聊到的这里现在请基于这个上下文继续。”有些高级或特定场景的 API 支持更多角色比如function已被tool逐步取代或tool用于函数调用developer用于更深层的系统控制。但对于绝大多数 Chat 场景掌握以上三种就足够了。2.3 内容承载不止是文本content字段是消息的正文。长期以来它都是一个简单的字符串。但随着多模态模型的发展content变得复杂起来。对于纯文本模型content就是字符串{role: user, content: 请用Python写一个快速排序函数。}对于支持多模态的模型如 GPT-4V, Claude 3content可以是一个数组里面可以混合文本和图像对象{ role: user, content: [ {type: text, text: 请描述这张图片的主要内容。}, { type: image_url, image_url: { url: data:image/jpeg;base64,... // 或一个可公开访问的 URL } } ] }这种格式的标准化使得一套代码可以同时处理纯文本和图文混合的问答大大简化了开发。2.4 可选字段让对话更精细除了role和content消息对象有时还可以包含一些可选字段用于更精细的控制。name为对话参与者命名。这在区分多个用户或助手的场景下有用。例如在一个客服系统中可以有{role: user, name: customer_A, content: ...}。但需要注意的是这个字段可能会影响模型对上下文的处理并非所有场景都适用。function_call/tool_calls在旧版的函数调用或新版工具调用中当模型决定调用一个函数/工具时它的回应会以特殊的assistant消息形式存在其中content可能为null而function_call或tool_calls字段包含了要调用的函数名和参数。随后开发者需要将函数执行的结果以role: “function”或role: “tool”的消息追加到对话历史中模型再基于此生成最终面向用户的回答。这是一个相对高级的流程。3. 主流API格式对比与实战解析虽然核心思想一致但不同厂商、不同模型的 API 在细节上仍有差异。了解这些差异是避免400错误的关键。3.1 OpenAI 格式事实上的行业标准OpenAI 的 Chat Completions API 是目前最广泛采用的标准也是许多开源模型服务如使用vLLM、TGI部署的模型提供“OpenAI 兼容”接口时所模仿的对象。一个完整的请求体示例{ model: gpt-4o, messages: [ {role: system, content: 你是一位翻译专家将用户输入翻译成英文。}, {role: user, content: 今天的夕阳真美。} ], temperature: 0.7, max_tokens: 1024, top_p: 1, stream: false }关键参数解析model指定使用的模型。这是必须的。temperature默认0.7控制输出的随机性。值越高接近1回答越多样、有创意值越低接近0回答越确定、保守。对于代码生成、事实问答通常设低一些如0.2对于创意写作可以设高一些。max_tokens限制模型本次回答的最大长度以 token 计。这是你成本控制和防止回答过长的主要手段。必须根据模型上下文长度合理设置。比如模型总上下文是 4096 tokens你的输入messages历史占了 500 tokens那么max_tokens最好设置为 3596 以内。top_p默认1另一种控制随机性的方式称为核采样。通常与temperature二选一调整即可不建议同时大幅调整两者。stream是否启用流式传输。设为true时服务器会以 Server-Sent Events (SSE) 形式逐步返回回答适合需要实时显示生成过程的场景如 ChatGPT 网页版。注意你遇到的api error: 400 this model‘s maximum context length is 1048576 tokens. however, your messages resulted in ...这类错误就是messages的总 token 数加上你请求的max_tokens超过了模型的能力上限。你需要精简历史消息或减少max_tokens。3.2 Anthropic (Claude) 格式略有不同的哲学Anthropic 的 Claude API 在格式上与 OpenAI 大同小异但有一些关键区别体现了其不同的设计理念。{ model: claude-3-opus-20240229, max_tokens: 1024, messages: [ {role: user, content: Hello, Claude}, {role: assistant, content: Hello! How can I assist you today?}, {role: user, content: 之前的对话中我说了Hello你回复了Hello! How...请重复我的第一句话。} ], system: 你是一个谨慎且乐于助人的助手。 }主要差异点system指令的位置OpenAI 将系统指令放在messages数组里作为一个角色。而 Claude 将其作为一个独立的顶级参数system。这意味着在 Claude 的messages数组中你通常只看到user和assistant的交替。必需参数Claude API 要求必须提供max_tokens参数不能省略。模型名称Claude 的模型命名包含版本日期如-20240229调用时需指定完整名称。这些差异虽然不大但在编写通用 SDK 或代理层时就需要进行相应的适配转换。3.3 开源模型与 OpenAI 兼容 API当你使用ollama部署本地模型或者使用vLLM、text-generation-inference等框架部署开源模型时它们通常会提供一个与 OpenAI API 格式高度兼容的端点。这极大地降低了开发者的适配成本。例如本地运行 Llama 3 的 Ollamacurl http://localhost:11434/api/chat -d { model: llama3, messages: [ { role: user, content: 为什么天空是蓝色的 } ], stream: false }格式几乎与 OpenAI 一模一样。这也是为什么社区生态普遍围绕 OpenAI 格式建立的原因。但是这里有巨坑兼容性并非 100%。例如角色支持一些较小的开源模型可能不完全理解system角色或者对其处理不佳。实践中更稳妥的做法是把系统指令作为第一个user消息发送。参数支持并非所有参数都被支持。frequency_penalty,presence_penalty等高级参数在一些简易部署中可能被忽略。错误信息错误码和消息格式可能不同增加了调试难度。3.4 常见错误格式与排查清单对接 API 时大部分错误都源于格式问题。下面是一个快速排查清单错误现象可能原因解决方案400 Bad Request1. JSON 格式语法错误。2. 缺少必需字段如model,messages。3. 字段值类型错误如messages不是数组。4. 枚举值错误如role不是system/user/assistant。1. 使用 JSON 校验工具检查请求体。2. 对照官方文档检查必填字段。3. 确保messages是数组且每个元素是对象。400 ‘type‘ must be in [“enabled“, “disabled“, “auto“]传递了 API 不认识的参数或参数值。可能是拼写错误或者将用于其他模型的参数用在了当前模型上。仔细检查请求体中每一个键值对确保参数名和值都在当前 API 版本的支持范围内。400 maximum context length exceeded输入消息历史当前的 token 总数超过了模型限制。1. 估算或调用 API 计算消息的 token 数。2. 精简历史消息删除最早的非关键对话、总结长消息。3. 减少max_tokens的请求值。404 Model not foundmodel参数指定的模型名称错误或你无权访问。核对模型名称列表注意大小写和完整名称如 Claude 的日期后缀。401/403 Authentication errorAPI Key 错误、过期或没有权限。检查 API Key 是否正确设置是否有足够的余额或调用额度。500 Internal Server Error/Connection reset服务端问题。可能是模型加载失败、过载或网络不稳定。重试请求检查服务提供商的状态页。如果是自建服务检查日志。一个实战技巧在编写代码时不要将请求体 JSON 硬编码为字符串拼接极易出错。务必使用你所用编程语言的 JSON 序列化库如 Python 的json.dumps()来构建对象并转换为字符串。这能有效避免引号、转义字符带来的语法错误。4. 高级话题与最佳实践掌握了基础格式和常见错误我们可以探讨一些更深入的话题让你的大模型集成更加稳健和高效。4.1 上下文管理与消息裁剪大模型的上下文窗口如 4K, 8K, 128K, 1M tokens是宝贵的资源也是成本的主要构成部分输入 token 通常也计费。如何高效管理messages数组是生产级应用的核心课题。策略一滑动窗口这是最简单的方法只保留最近 N 轮对话或最近 K 个 tokens。当新的对话加入导致总长度超限时就从最老的对话开始删除直到满足要求。这种方法会丢失早期的上下文可能导致模型“忘记”很久之前设定的指令或关键信息。策略二关键信息摘要当对话较长时可以调用模型自身或一个更小、更便宜的模型对超出窗口的早期对话进行总结生成一段简短的摘要。然后将这段摘要作为一条新的system或user消息放在当前messages的开头。例如[旧的 system 指令] [历史对话摘要“用户之前咨询了关于Python装饰器的问题我们讨论了它的概念和基本用法。”] [最近3轮具体对话] [当前用户问题]这样既保留了长期记忆的精华又节省了大量 tokens。策略三结构化历史存储对于复杂的多轮对话如客服、教学可以将对话历史结构化地存储在外部数据库如向量数据库中。当进行新一轮对话时先根据当前问题从历史中检索最相关的若干片段然后将这些片段作为上下文插入到messages中。这就是 RAG检索增强生成的基本思想它能突破模型固有上下文长度的限制。4.2 流式传输的实现与处理将stream参数设为true后API 的响应不再是完整的 JSON而是一个流HTTP chunked transfer encoding。每生成一个 token 或一小段文本服务器就会发送一个data: {...}格式的事件。服务器返回的数据格式示例data: {id:...,object:chat.completion.chunk,choices:[{delta:{content:今}}]} data: {id:...,object:chat.completion.chunk,choices:[{delta:{content:天}}]} data: {id:...,object:chat.completion.chunk,choices:[{delta:{content:天气}}]} data: {data: [DONE]}客户端处理逻辑建立连接并发送请求。持续读取 HTTP 响应流。按行解析找到以data:开头的行。去掉data:前缀后解析其中的 JSON最后一行[DONE]除外。从choices[0].delta.content中获取本次“流出的”文本片段并实时展示给用户。收到[DONE]后关闭连接。流式传输能极大提升用户体验但增加了客户端的处理复杂度需要处理好网络中断、连接超时、数据拼接等问题。4.3 函数调用与工具调用的消息格式演进这是消息格式中比较复杂的部分。以 OpenAI 从 Function Calling 到 Tool Calling 的演进为例旧版 Function Calling用户提问“北京今天天气怎么样”请求中定义好functions参数描述可用的函数。模型回复一条特殊的assistant消息其中content为null但包含function_call: {“name”: “get_weather”, “arguments”: “{\”city\“: \”Beijing\“}”}。开发者本地执行get_weather(“Beijing”)函数获得结果。将结果作为一条role: “function”name: “get_weather”content: “{...天气数据...}”的消息追加到对话历史中。再次请求模型这次模型会根据函数执行结果生成面向用户的自然语言回答。新版 Tool Calling 逻辑类似但更通用。tools参数替代了functions模型回复中的tool_calls是一个数组支持同时调用多个工具执行结果以role: “tool”的消息返回。关键点无论是函数还是工具调用其核心都是通过特殊的消息格式在messages对话历史中插入“模型决定调用工具”和“工具返回结果”这两个步骤从而将外部能力无缝融入对话流程。理解这个消息流的编排是实现复杂 AI 应用的基础。5. 构建健壮的客户端抽象与适配层设计如果你需要对接多个不同格式的 AI 提供商比如同时用 OpenAI、Claude 和本地部署的模型为每一个都写一套独特的请求构建代码是低效且难以维护的。一个好的实践是设计一个抽象层。第一步定义统一的消息结构体在你的应用内部定义一套与具体厂商无关的消息表示法。例如from typing import Literal, Union from pydantic import BaseModel class TextContent(BaseModel): type: Literal[text] text text: str class ImageContent(BaseModel): type: Literal[image_url] image_url image_url: str # 可以是 URL 或 base64 ContentItem Union[TextContent, ImageContent] class UnifiedMessage(BaseModel): role: Literal[system, user, assistant, tool] content: Union[str, list[ContentItem]] # 支持字符串或混合内容数组 name: str | None None第二步为每个提供商编写适配器每个适配器负责两件事1. 将内部的UnifiedMessage列表转换为该提供商 API 所需的格式2. 将该提供商的响应转换回内部的统一格式。class OpenAIAdapter: def to_request(self, messages: list[UnifiedMessage], model: str, **kwargs): openai_messages [] for msg in messages: # 处理 content 转换 if isinstance(msg.content, str): content msg.content else: content [item.dict() for item in msg.content] # 转换为混合内容数组 openai_messages.append({ role: msg.role, content: content, **({name: msg.name} if msg.name else {}) }) return { model: model, messages: openai_messages, **kwargs } class ClaudeAdapter: def to_request(self, messages: list[UnifiedMessage], model: str, **kwargs): claude_messages [] system_prompt None for msg in messages: if msg.role system: # Claude 需要把 system 提取出来 system_prompt msg.content if isinstance(msg.content, str) else .join([c.text for c in msg.content if c.type text]) else: # 处理 user/assistant 消息 ... request_body { model: model, max_tokens: kwargs.pop(max_tokens, 1024), messages: claude_messages, **kwargs } if system_prompt: request_body[system] system_prompt return request_body第三步在业务逻辑中使用统一接口你的主程序只需要操作UnifiedMessage然后根据配置选择对应的适配器即可。这样增加一个新的 AI 服务提供商只需要新增一个适配器类核心业务代码完全不用动。这种设计模式不仅让代码更清晰也使得 A/B 测试不同模型、故障转移当一个服务宕机时切换到另一个变得非常容易实现。6. 调试技巧与工具推荐最后分享几个我在实际工作中高频使用的调试技巧和工具能帮你快速定位消息格式相关的问题。1. 使用curl或httpie进行快速测试在编写正式代码前先用命令行工具手动构造请求验证 API 是否通畅、格式是否正确。这能排除掉代码中序列化、网络库等复杂因素的干扰。# 使用 httpie (更友好) http POST https://api.openai.com/v1/chat/completions \ Authorization:Bearer $OPENAI_API_KEY \ modelgpt-3.5-turbo \ messages:[{role: user, content: Hello}] # 使用 curl curl https://api.openai.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $OPENAI_API_KEY \ -d { model: gpt-3.5-turbo, messages: [{role: user, content: Hello}] }2. 善用 Token 计数器很多错误源于上下文超长。在发送请求前估算一下 token 数量非常必要。OpenAI提供了官方的tiktokenPython 库可以精确计算。通用估算对于英文可以粗略按1 token ≈ 4 字符估算对于中文1 token ≈ 1.5~2 个汉字。但这只是估算复杂文本差异很大。在线工具一些 playground 或第三方网站提供 token 计算功能。3. 从简单到复杂构建请求不要一开始就构建包含长历史、多模态、函数调用的复杂请求。从一个最简单的单轮对话请求开始确保能成功收到响应。然后逐步添加加上system指令加上历史对话加上流式传输最后再加上高级功能。每加一步都测试一下这样当错误出现时你就能立刻知道是哪一步引入的。4. 详细记录日志在你的客户端代码中务必在发出请求前和收到响应后或错误时打印出完整的请求体和响应体/错误信息。很多 SDK 有 debug 模式可以开启。这些日志是排查问题的第一手资料。记得在日志中脱敏你的 API Key。消息格式就像大模型对话的“协议”理解了它你就掌握了与这些“数字大脑”有效沟通的基本法则。从避免400错误开始到高效管理上下文再到设计兼容多后端的健壮架构每一步都建立在对这个格式的深刻理解之上。希望这篇近万字的梳理能成为你大模型应用开发路上的一块坚实垫脚石。下次再看到‘type‘ must be in [“enabled“, “disabled“, “auto“]这样的错误时你一定能会心一笑然后快速定位到那个拼写错误的参数。