1. 两套协议到底差在哪从一次真实迁移说起去年底我把一个内部知识库问答工具从 OpenAI 的接口切到 Anthropic原本以为只是改个 URL 和 key 的事结果整整折腾了一个下午。请求发出去要么 400要么返回的内容结构对不上最坑的是流式输出那块事件格式完全不是一回事。那次之后我把两套协议的差异从头到尾梳理了一遍今天就把这些踩过的坑和对照关系一次讲清楚。这篇文章面向的是已经在用大模型 API 做开发的工程师或者正准备从一套协议迁移到另一套的团队。我会把两套协议在请求结构、消息角色、系统提示、工具调用、流式响应、错误处理这几个维度的差异全部拆开讲每个差异都配上可直接复制的请求对照最后附上我实际踩过的坑和排查方法。读完你应该能做到拿到一份 OpenAI 风格的请求心里清楚要改哪几个字段才能跑在 Anthropic 上反过来也一样。先说结论层面的东西方便你建立整体印象。OpenAI 的接口设计偏向对话补全这个原始定位核心是messages数组加上role区分身份Anthropic 从设计之初就是给模型喂上下文的思路所以它把系统提示单独拎出来做顶层参数消息角色只有 user 和 assistant 两种。这个根本差异会像涟漪一样扩散到后面所有的细节里。理解了这一点后面那些字段名对不上的问题就都好解释了。我下面所有的对照都基于两家当前主流的对话接口OpenAI 这边是 chat completions 风格Anthropic 这边是 messages 接口。参数名和结构我会尽量给准确但两家迭代都很快具体字段以你接入时的官方文档为准我这里讲的是稳定了很长时间、短期内不会变的核心结构。2. 请求体结构逐字段对照2.1 顶层参数的一一映射先看最外层。OpenAI 的请求体里模型、消息、温度这些都在同一层Anthropic 也类似但多了几个 OpenAI 没有的顶层字段同时少了几个。我把最常用的字段列成表你迁移的时候直接照着改。含义OpenAI 字段Anthropic 字段备注模型名modelmodel命名规则完全不同不能混用对话消息messagesmessages结构有差异见下节系统提示messages里 role 为 system顶层system这是最大的结构差异最大输出长度max_tokens可选max_tokens必填Anthropic 不填直接报错采样温度temperaturetemperature取值范围都是 0 到 1核采样top_ptop_p语义一致流式开关streamstream语义一致但事件格式不同停止词stopstop_sequences字段名不同工具定义toolstools结构差异较大工具选择策略tool_choicetool_choice取值枚举不同这张表里最容易被忽略的是max_tokens。OpenAI 这边你不传它会用模型默认值请求照样成功Anthropic 这边max_tokens是必填项漏了直接返回 400报错信息大意是缺少必填参数。我第一次迁移就是栽在这因为原来的代码里根本没写这个字段。另一个高频坑是stop和stop_sequences。字段名不一样就算了值的类型也有讲究OpenAI 接受字符串或字符串数组Anthropic 只接受字符串数组。如果你原来传的是单个字符串迁移时记得包成数组。2.2 消息数组的结构差异消息数组是两套协议差异最集中的地方。OpenAI 的messages里每条消息有role和contentrole可以是system、user、assistant、tool四种。Anthropic 的messages里role只有user和assistant两种系统提示被提到了顶层。先看 OpenAI 的典型结构{ model: gpt-4o, messages: [ {role: system, content: 你是一个严谨的技术助手}, {role: user, content: 解释一下什么是幂等性} ], temperature: 0.7 }同样的语义Anthropic 要写成这样{ model: claude-sonnet-4-20250514, system: 你是一个严谨的技术助手, messages: [ {role: user, content: 解释一下什么是幂等性} ], max_tokens: 1024, temperature: 0.7 }注意system从数组里的一条消息变成了顶层的独立字符串。这个改动看起来小但它影响的是你整个消息拼装逻辑。如果你原来的代码是动态往messages里插 system 消息迁移时得把这段逻辑单独抽出来。还有一个细节Anthropic 要求messages里的角色必须交替出现也就是 user 和 assistant 轮流来不能连续两条都是 user。OpenAI 没这个限制你连着塞两条 user 消息它也能处理。这个约束在拼接多轮对话历史的时候特别容易触发比如你把用户连续两次追问合并处理就可能出现两条相邻的 user 消息Anthropic 会直接报错。2.3 content 字段的两种形态content这个字段两套协议都支持字符串和数组两种形态但数组里元素的写法不一样。字符串形态就是纯文本这个两边通用。数组形态用于多模态场景比如图文混合输入。OpenAI 的数组元素长这样{ role: user, content: [ {type: text, text: 这张图里有什么}, {type: image_url, image_url: {url: https://example.com/a.png}} ] }Anthropic 的数组元素长这样{ role: user, content: [ {type: text, text: 这张图里有什么}, {type: image, source: {type: base64, media_type: image/png, data: ...}} ] }差异点有两个。第一图片的类型标识OpenAI 用image_urlAnthropic 用image。第二图片来源的传法OpenAI 支持直接给 URLAnthropic 这边主流做法是传 base64 数据需要你自己把图片编码后塞进data字段。如果你原来依赖 OpenAI 的 URL 传图迁移到 Anthropic 时得先下载图片再编码这一步经常被漏掉。提示Anthropic 的图片 base64 数据不要带data:image/png;base64,这个前缀只放纯 base64 字符串前缀信息通过media_type字段单独表达。带前缀会报解析错误。3. 工具调用与函数调用的协议分歧3.1 工具定义的结构对比工具调用这块两套协议的差异比消息结构还大。OpenAI 的工具定义是type加function两层嵌套Anthropic 是扁平的name、description、input_schema三个字段。OpenAI 的写法{ tools: [ { type: function, function: { name: get_weather, description: 查询指定城市的天气, parameters: { type: object, properties: { city: {type: string, description: 城市名} }, required: [city] } } } ] }Anthropic 的写法{ tools: [ { name: get_weather, description: 查询指定城市的天气, input_schema: { type: object, properties: { city: {type: string, description: 城市名} }, required: [city] } } ] }关键差异是parameters变成了input_schema而且去掉了type: function和function这层包裹。如果你有工具定义的 JSON Schema 存在数据库里迁移时要做一次结构转换把外层剥掉、字段改名。3.2 模型返回工具调用的格式模型决定调用工具时两边的返回结构也不一样。OpenAI 在choices[0].message里放一个tool_calls数组每个元素有id、type、function三部分其中function.arguments是一个 JSON 字符串。Anthropic 的返回里content是一个数组工具调用是其中一个type为tool_use的元素带id、name、input三个字段注意input已经是解析好的对象不是字符串。这个差异直接影响你的解析代码。OpenAI 那边你需要对arguments做一次JSON.parseAnthropic 这边直接就是对象不用再解析。反过来如果你写了一套通用解析逻辑得判断当前是哪套协议走不同的分支。3.3 工具结果的回传方式工具执行完结果要回传给模型继续对话这一步两边的消息结构差异也很大。OpenAI 是新增一条role为tool的消息带上tool_call_id{ role: tool, tool_call_id: call_abc123, content: 北京今天晴25度 }Anthropic 是把工具结果作为一条role为user的消息content数组里放type为tool_result的元素{ role: user, content: [ { type: tool_result, tool_use_id: toolu_abc123, content: 北京今天晴25度 } ] }这里有个容易搞混的点Anthropic 用user角色来承载工具结果而不是单独搞一个tool角色。原因是它的设计哲学里工具结果本质上是用户侧提供给模型的信息所以归到 user 这边。理解了这个逻辑你就不会觉得别扭了。注意Anthropic 回传工具结果时tool_use_id必须和模型返回的tool_use里的id严格对应写错了模型会认为工具没被调用可能重复发起调用。这个 id 是模型生成的你原样带回去就行不要自己造。4. 流式响应的解析差异4.1 事件格式的根本不同流式输出是迁移时最费劲的部分因为两套协议的 SSE 事件格式完全不一样。OpenAI 的流式响应里每个 chunk 是一个 JSON结构类似非流式的choices只是delta字段里放增量内容。OpenAI 的 chunk 长这样data: {choices:[{delta:{content:你},index:0}]} data: {choices:[{delta:{content:好},index:0}]} data: [DONE]Anthropic 的流式响应是带事件类型的每个 SSE 消息有event和data两部分事件类型包括message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop等。Anthropic 的流大概长这样event: content_block_delta data: {type:content_block_delta,index:0,delta:{type:text_delta,text:你}} event: content_block_delta data: {type:content_block_delta,index:0,delta:{type:text_delta,text:好}} event: message_stop data: {type:message_stop}差异一目了然。OpenAI 你只需要取delta.content拼接就行Anthropic 你得先判断事件类型只在content_block_delta且delta.type为text_delta的时候取delta.text。如果你直接把 Anthropic 的流按 OpenAI 的方式解析会拿到一堆空内容因为文本藏在更深的一层。4.2 流式解析的代码对照我把两边的解析逻辑写成伪代码你对照着看就清楚了。OpenAI 的解析for line in response.iter_lines(): if not line.startswith(bdata: ): continue payload line[6:] if payload b[DONE]: break chunk json.loads(payload) delta chunk[choices][0][delta] if content in delta: yield delta[content]Anthropic 的解析for line in response.iter_lines(): if not line.startswith(bdata: ): continue chunk json.loads(line[6:]) if chunk[type] content_block_delta: delta chunk[delta] if delta[type] text_delta: yield delta[text]注意 Anthropic 这边没有[DONE]这个结束标记你得靠message_stop事件或者直接等连接关闭来判断结束。这个差异在写循环终止条件的时候特别容易出错我见过有人一直等[DONE]结果死循环的。4.3 工具调用的流式处理流式场景下工具调用的处理更麻烦。OpenAI 的tool_calls在流里是分片到达的function.arguments会一段一段拼起来你得自己维护一个缓冲区等finish_reason变成tool_calls再整体解析。Anthropic 这边工具调用的流式事件是content_block_start里带tool_use的初始信息然后input_json_delta事件里分片传partial_json最后content_block_stop表示这个块结束。你需要按index把分片归到对应的工具调用上。这块两边的复杂度都不低我的建议是如果你的场景对首字延迟不敏感工具调用干脆别用流式等完整响应回来再处理能省掉一大堆拼接逻辑。等业务真的需要了再优化。5. 错误处理与状态码的坑5.1 错误响应的结构差异请求出错时两套协议返回的错误结构也不一样。OpenAI 的错误在顶层error对象里有message、type、code、param几个字段。Anthropic 的错误也是顶层error但字段是type和message类型枚举值不同。OpenAI 的错误示例{ error: { message: Invalid API key, type: invalid_request_error, code: invalid_api_key } }Anthropic 的错误示例{ type: error, error: { type: authentication_error, message: invalid x-api-key } }注意 Anthropic 的错误类型是authentication_error这种更粗粒度的分类OpenAI 会细分到invalid_api_key这种具体 code。如果你原来依赖 OpenAI 的code字段做精细化错误处理迁移到 Anthropic 后得改成按type判断粒度会变粗。5.2 认证方式的差异认证这块两套协议用的是不同的请求头。OpenAI 用Authorization: Bearer keyAnthropic 用x-api-key: key而且 Anthropic 还要求带一个anthropic-version头来指定 API 版本。# OpenAI curl https://api.openai.com/v1/chat/completions \ -H Authorization: Bearer $OPENAI_KEY \ -H Content-Type: application/json \ -d {...} # Anthropic curl https://api.anthropic.com/v1/messages \ -H x-api-key: $ANTHROPIC_KEY \ -H anthropic-version: 2023-06-01 \ -H Content-Type: application/json \ -d {...}anthropic-version这个头是必填的漏了会报错。它的作用是让 Anthropic 能在不破坏老用户的前提下演进 API你指定了版本行为就锁定在那个版本。这个设计挺聪明的但第一次接入的人经常忘。5.3 常见错误速查表我把迁移过程中最常撞上的错误整理成表方便你对照排查。现象可能原因解决方向400 缺少 max_tokensAnthropic 必填项没传补上max_tokens400 角色不交替messages 里连续同角色合并或插入占位消息401 认证失败请求头用错换成x-api-key并加版本头400 模型不存在模型名混用用对应平台的模型名流式无内容事件解析逻辑不对按事件类型分支处理工具调用重复tool_use_id 对不上原样回传模型给的 id图片解析失败base64 带了前缀去掉data:前缀这张表里的每一条我基本都亲自撞过尤其是流式无内容和工具调用重复这两个排查起来最费时间因为报错信息不会直接告诉你原因得靠日志一点点看。6. 迁移实操一份请求的双向改写6.1 从 OpenAI 改到 Anthropic 的完整步骤假设你手上有一份能跑的 OpenAI 请求要改成 Anthropic 版本按这个顺序改最不容易漏。第一步换 URL 和认证头。URL 从/v1/chat/completions换成/v1/messages认证头从Authorization: Bearer换成x-api-key加上anthropic-version。第二步把messages里的 system 消息抽出来放到顶层system字段。如果有多条 system 消息用换行拼成一个字符串。第三步补上max_tokens。这个值根据你的业务定一般对话场景 1024 到 4096 够用长文本生成再往上加。第四步改stop为stop_sequences值包成数组。第五步改工具定义parameters换成input_schema去掉function外层。第六步改流式解析逻辑按事件类型分支。第七步改工具结果的回传结构从role: tool改成role: user加tool_result块。这七步走完基本就能跑通了。我建议每改一步就发一次请求验证别攒着一起改不然出错都不知道是哪步引入的。6.2 反向迁移的注意点从 Anthropic 改回 OpenAI 相对简单一些因为 OpenAI 的约束更少。主要改这几处system 从顶层塞回 messages 数组max_tokens可以留着也可以删stop_sequences改回stop工具定义加回function外层工具结果改成role: tool。反向迁移有个坑要注意Anthropic 的input是解析好的对象OpenAI 的arguments是字符串。你从 Anthropic 迁到 OpenAI 时得把工具调用的参数对象序列化成字符串再塞进arguments忘了这步模型会收到格式错误。6.3 用适配层屏蔽差异如果你的项目要同时支持两套协议别在每个业务代码里写 if-else抽一个适配层出来。我的做法是定义一套内部统一的消息格式然后写两个转换器一个转 OpenAI一个转 Anthropic业务代码只跟内部格式打交道。适配层要处理的核心转换点就三个system 提示的位置、工具定义的结构、流式事件的解析。把这三个封装好上层业务基本无感。这个投入在需要多平台兜底的场景下非常值我现在的项目就是一套内部格式切换平台只改一个配置项。7. 我踩过的坑和排查心得7.1 那些文档不会告诉你的细节第一个坑是 Anthropic 的max_tokens上限。不同模型的上限不一样你设太大也会报错报错信息不会告诉你上限是多少得去查文档。我的做法是设一个保守值比如 4096需要更长输出再针对性调。第二个坑是流式响应里的ping事件。Anthropic 会定期发event: ping的心跳你的解析逻辑如果没忽略它可能会把它当成内容处理。我一开始就中招了输出里混进了一堆空字符串。第三个坑是消息历史的长度控制。两套协议对上下文长度的计算方式不一样OpenAI 按 token 算Anthropic 也是按 token 但分词方式不同同样的文本两边算出来的 token 数会有差异。你做历史截断的时候别用一套 token 估算逻辑套两边容易一边超限一边浪费。第四个坑是并发限流的表现形式。OpenAI 触发限流返回 429 带Retry-After头Anthropic 也是 429 但重试建议的字段名不一样。写重试逻辑的时候要分别处理。7.2 排查问题的通用思路遇到请求失败我的排查顺序是这样的先看 HTTP 状态码4xx 基本是请求本身的问题5xx 是服务端问题可以重试然后看错误响应体里的type和message这两个字段通常能定位到具体原因最后如果错误信息模糊就把请求体完整打出来逐字段对照文档检查。流式问题排查稍微特殊一点因为错误可能藏在流中间。我的做法是在解析循环里加详细日志把每个事件的原始内容打出来这样能清楚看到流是在哪一步断的、哪个事件格式不对。提示调试阶段把请求体和响应体完整落盘出问题时能直接复现。生产环境注意脱敏别把 key 和用户数据写进日志。7.3 性能与成本的取舍两套协议在计费维度上也有差异。OpenAI 按输入输出 token 分别计价Anthropic 也是但它的缓存机制设计得比较特别支持显式标记可缓存的内容块命中缓存的部分价格低很多。如果你的场景有大量重复的系统提示或知识库内容用 Anthropic 的缓存能省不少钱。延迟方面两家的流式首字延迟都在几百毫秒级别具体取决于模型和负载。我的实测是同一量级的模型首字延迟差异不大但完整响应时间跟输出长度强相关这个两边都一样。选哪套协议我的建议是别只看协议本身要看你整个技术栈。如果你的工具链、监控、日志都是围绕 OpenAI 生态建的迁移成本要考虑进去。如果是从零开始两套都试试看哪套的模型输出更符合你的业务需求协议差异其实是可以靠适配层抹平的。最后分享一个我常用的验证方法写一个最小的测试脚本把同一个问题分别发给两套接口把请求体和响应体都打出来对比。这个脚本我留在项目里当回归测试用每次升级 SDK 或者改适配层就跑一遍能快速发现协议层面的破坏性变更。这个方法帮我提前发现过好几次字段改名的问题比等线上报错再排查省事多了。