1. 两套协议到底差在哪从一次迁移踩坑说起前阵子我把一个跑了半年的小工具从 OpenAI 的接口切到 Anthropic本来以为就是改个 URL 和 key 的事结果整整折腾了一个下午。报错一个接一个从401到400再到消息结构不匹配最后发现连系统提示词放哪这种最基础的问题两家的设计哲学都完全不一样。这件事让我意识到很多人嘴上说都是大模型 API能差多少真上手才发现差异比想象中大得多。这篇内容就是那次迁移的完整复盘。我会把 OpenAI 和 Anthropic 两套 API 协议的核心差异一次讲清楚包括请求结构、消息角色、系统提示词位置、参数命名、返回格式、流式响应、工具调用这几个最容易踩坑的地方并且给出可以直接对照的请求示例。不管你是刚接触大模型 API 的新手还是已经用过其中一家、准备接入另一家的开发者看完都能少走弯路。需要先说明一点这两套协议背后其实是两种不同的产品思路。OpenAI 更像通用聊天补全把一切都塞进messages数组里Anthropic 则强调对话与指令分离专门给系统提示词留了独立字段。理解了这个底层逻辑后面所有的差异就都能串起来了。下面我按实际迁移顺序一块一块拆。2. 请求结构对照从端点、鉴权到消息体2.1 端点与鉴权方式的差异先看最外层。OpenAI 的对话补全端点是/v1/chat/completionsAnthropic 是/v1/messages。名字不一样不是随便起的chat/completions暗示它是个聊天补全接口而messages更中性强调消息这个核心概念。鉴权上两家都用 Bearer Token但请求头的写法有细微区别。OpenAI 是标准的Authorization: Bearer sk-xxxxxxAnthropic 除了这个还必须额外带一个版本头x-api-key: sk-ant-xxxxxx anthropic-version: 2023-06-01注意这里有个坑Anthropic 官方推荐用x-api-key而不是Authorization虽然部分网关两种都认但直连官方时用错头会直接401。我第一次迁移就是习惯性写了Authorization结果卡在鉴权上半天。anthropic-version这个头是强制的它用来做 API 版本控制不带你就会收到明确的报错提示。提示Anthropic 的版本头是日期格式目前主流是2023-06-01。这个值不是越新越好而是官方指定的稳定版本号照抄即可别自己乱改。2.2 消息体结构的核心分歧这是差异最大的地方。OpenAI 的请求体长这样{ model: gpt-4o, messages: [ {role: system, content: 你是一个严谨的助手}, {role: user, content: 帮我解释一下什么是API} ], temperature: 0.7, max_tokens: 1024 }Anthropic 的对应请求{ model: claude-3-5-sonnet-20241022, system: 你是一个严谨的助手, messages: [ {role: user, content: 帮我解释一下什么是API} ], temperature: 0.7, max_tokens: 1024 }看出关键区别了吗OpenAI 把系统提示词当成messages里的一条system角色消息而 Anthropic 把它抽出来做成了顶层字段system。这个设计差异直接导致两个后果一是迁移时你必须把messages数组里那条system消息删掉改放到顶层二是 Anthropic 的messages数组里只允许user和assistant两种角色你塞个system进去会直接报错。我当时的报错就是messages: roles must alternate between user and assistant一开始还以为是消息顺序问题后来才明白是角色限制。Anthropic 对消息顺序要求很严基本要求 user 和 assistant 交替出现第一条通常是 user。2.3 参数命名的细节差异除了结构参数名也有几处容易忽略的不同。max_tokens两家都有但 Anthropic 里它是必填的不填会报错OpenAI 里它是可选的不填就用模型默认值。这个差异在迁移时特别容易漏因为 OpenAI 代码里经常不写max_tokens直接搬过去就挂了。temperature两家语义一致范围都是 0 到 1OpenAI 部分模型支持到 2。但 Anthropic 还有个top_p和top_k的组合玩法top_k是 OpenAI 没有的它限制每步只从概率最高的 K 个 token 里采样。如果你追求输出稳定Anthropic 这边调top_k往往比调temperature更直接。对比项OpenAIAnthropic端点/v1/chat/completions/v1/messages鉴权头Authorization: Bearerx-api-keyanthropic-version系统提示词messages里的system角色顶层system字段消息角色system/user/assistant/tool仅 user/assistantmax_tokens可选必填独有参数frequency_penalty、presence_penaltytop_k这张表建议直接存下来迁移时对着改能省掉一大半试错时间。3. 返回格式与流式响应解析逻辑要重写3.1 非流式返回的结构差异请求发出去只是第一步拿到响应后怎么解析又是另一套逻辑。OpenAI 的返回结构是{ id: chatcmpl-xxx, object: chat.completion, choices: [ { index: 0, message: {role: assistant, content: API是...}, finish_reason: stop } ], usage: {prompt_tokens: 20, completion_tokens: 50, total_tokens: 70} }Anthropic 的返回{ id: msg_xxx, type: message, role: assistant, content: [ {type: text, text: API是...} ], stop_reason: end_turn, usage: {input_tokens: 20, output_tokens: 50} }最直观的区别OpenAI 的正文在choices[0].message.contentAnthropic 的正文在content[0].text。而且 Anthropic 的content是个数组因为一条回复里可能同时包含文本块和工具调用块。这意味着你取文本时不能直接.content得先遍历数组找type text的那一项。我第一次解析 Anthropic 响应时直接按 OpenAI 的路径去取结果拿到undefined还以为是请求失败了。后来打印完整响应才发现结构完全不同。这个坑非常典型凡是做过迁移的人基本都踩过。3.2 结束原因与用量统计的映射finish_reason和stop_reason的取值也不一样。OpenAI 常见的是stop、length、tool_callsAnthropic 是end_turn、max_tokens、tool_use、stop_sequence。做业务判断时比如是否因为超长被截断OpenAI 判断lengthAnthropic 判断max_tokens写错了逻辑就会失效。用量统计字段名也不同。OpenAI 是prompt_tokens/completion_tokensAnthropic 是input_tokens/output_tokens。如果你有计费或监控模块这两个字段名必须做映射否则统计会全是 0。3.3 流式响应的分帧格式流式是另一个重灾区。两家都用 SSEServer-Sent Events但事件格式不同。OpenAI 每个 chunk 是data: {choices:[{delta:{content:你}}]} data: [DONE]Anthropic 的事件类型更丰富每个 chunk 带type字段event: content_block_delta data: {type:content_block_delta,delta:{type:text_delta,text:你}} event: message_stop data: {type:message_stop}关键差异在于OpenAI 用[DONE]标记结束Anthropic 用message_stop事件类型标记结束。如果你写了个通用解析器只认[DONE]那接 Anthropic 时会一直等不到结束信号流就挂住了。另外 Anthropic 的文本增量在delta.textOpenAI 在delta.content取值路径也得改。注意Anthropic 流式响应里还有message_start、content_block_start、content_block_stop、message_delta等事件做完整解析时建议按type分发处理别只盯着文本增量。4. 工具调用与多模态协议设计思路的分水岭4.1 工具调用的声明方式工具调用Function Calling / Tool Use是两家差异最能体现设计哲学的地方。OpenAI 的工具声明放在顶层tools字段{ tools: [ { type: function, function: { name: get_weather, description: 查询天气, parameters: {type: object, properties: {city: {type: string}}} } } ] }Anthropic 的声明更扁平{ tools: [ { name: get_weather, description: 查询天气, input_schema: {type: object, properties: {city: {type: string}}} } ] }区别在于 OpenAI 多包了一层function参数 schema 叫parametersAnthropic 直接平铺schema 叫input_schema。迁移时这层嵌套必须拆掉否则工具根本注册不上。4.2 模型返回工具调用的形式模型决定调用工具时OpenAI 返回的是message.tool_calls数组里面每项有id、function.name、function.arguments注意 arguments 是 JSON 字符串得手动 parse。Anthropic 则把工具调用作为content数组里的一个块type为tool_use字段是id、name、inputinput 已经是解析好的对象不用再 parse。这个差异很关键OpenAI 的 arguments 是字符串要二次解析Anthropic 的 input 直接就是对象。我见过有人迁移后忘了 parse结果把整个 JSON 字符串当参数传进函数报了一堆莫名其妙的错。回传工具结果时OpenAI 用role: tool加tool_call_idAnthropic 用role: usercontent 里放type: tool_result的块并带上tool_use_id。也就是说 Anthropic 没有独立的 tool 角色工具结果是以 user 身份回传的。这个设计初看别扭但理解成工具结果是用户侧提供的信息就顺了。4.3 多模态输入的差异图片输入两家都支持但格式不同。OpenAI 用 content 数组每项type: image_url里面套image_url.url可以是 URL 也可以是 base64。Anthropic 用type: image里面是source对象明确区分type: base64或type: urlbase64 还要单独写media_type。// Anthropic 图片格式 { type: image, source: { type: base64, media_type: image/png, data: iVBORw0KG... } }Anthropic 这种写法更啰嗦但胜在明确——它强制你声明媒体类型避免了 OpenAI 那种从 data URI 里猜类型的模糊地带。实际用下来Anthropic 对图片格式的校验更严格media_type 写错会直接报错。5. 迁移实操一份可复用的适配层写法5.1 用适配器模式统一两套协议既然差异这么多最省心的做法不是到处改业务代码而是写一层适配器把两套协议统一成内部标准格式。我的做法是定义一个内部消息结构然后写两个转换函数一个转 OpenAI 格式一个转 Anthropic 格式。def to_openai(system, messages, toolsNone): msgs [{role: system, content: system}] messages body {model: gpt-4o, messages: msgs} if tools: body[tools] [{type: function, function: t} for t in tools] return body def to_anthropic(system, messages, toolsNone): body { model: claude-3-5-sonnet-20241022, system: system, messages: messages, max_tokens: 1024 } if tools: body[tools] [ {name: t[name], description: t[description], input_schema: t[parameters]} for t in tools ] return body这样业务层只管传内部格式具体走哪家由适配器决定。切换模型时只改一个配置项不用动业务逻辑。这个模式我在两个项目里都用过迁移成本从改一天降到改十分钟。5.2 响应解析的统一封装响应侧同理写一个parse_response函数根据 provider 走不同分支但对外返回统一结构def parse_response(provider, raw): if provider openai: choice raw[choices][0] return { text: choice[message][content], finish: choice[finish_reason], usage: { in: raw[usage][prompt_tokens], out: raw[usage][completion_tokens] } } else: text .join(b[text] for b in raw[content] if b[type] text) return { text: text, finish: raw[stop_reason], usage: { in: raw[usage][input_tokens], out: raw[usage][output_tokens] } }注意 Anthropic 那边我用join拼接所有文本块因为一条回复可能有多个 text 块。这个细节不做遇到多块回复就会丢内容。5.3 流式解析的适配流式适配稍微麻烦点核心是统一增量文本和结束信号两个概念。我的做法是写一个生成器内部按 provider 解析 SSE对外只 yield 文本增量遇到结束就 return。def stream_text(provider, line): if provider openai: if line.startswith(data: [DONE]): return None data json.loads(line[6:]) return data[choices][0][delta].get(content, ) else: if message_stop in line: return None if line.startswith(data:): data json.loads(line[6:]) if data.get(type) content_block_delta: return data[delta].get(text, ) return 调用方只管拿文本不用关心底层是哪家。这套封装我实测下来很稳切换 provider 时业务代码零改动。6. 常见报错与排查速查表迁移过程中我攒了一堆报错这里整理成速查表遇到问题直接对号入座。报错信息原因解决方式401 Unauthorized鉴权头写错Anthropic 用x-api-key别用Authorizationmissing anthropic-version缺版本头补上anthropic-version: 2023-06-01roles must alternate消息角色不合法删掉 system 角色检查 user/assistant 交替max_tokens required没传 max_tokensAnthropic 必填补上content is undefined解析路径错Anthropic 取content[0].text不是choices流式一直不结束结束标记没识别Anthropic 认message_stop不是[DONE]工具参数是字符串忘了 parseOpenAI 的 arguments 要json.loads工具注册失败结构没拆层Anthropic 工具无function外层schema 叫input_schema除了这些还有几个不那么明显但很坑的点。比如 Anthropic 对空字符串的 content 会报错如果你某条消息 content 是空的得直接跳过OpenAI 相对宽容。再比如 Anthropic 的temperature和top_p不建议同时调官方建议二选一同时改容易出不可预期的结果。提示调试时建议先把max_tokens设小一点比如 256这样报错和响应都快确认协议通了再放大。我一开始设了 4096每次调试都等半天效率极低。还有一个经验两家的错误响应结构也不同。OpenAI 错误在error.messageAnthropic 错误在error.message但外层还包了type: error。写统一错误处理时建议先判断 HTTP 状态码再取 message别硬编码路径。7. 我踩过的几个真实坑与应对心得第一个坑是系统提示词迁移。我一开始偷懒直接把 OpenAI 的messages数组整个传给 Anthropic只改了端点。结果第一条 system 消息直接触发角色校验错误。后来才改成把 system 抽出来放顶层。这个改动看着小但如果你的系统提示词很长、还带变量拼接迁移时容易漏掉某处拼接逻辑建议全局搜一遍role.*system再动手。第二个坑是流式的结束判断。我写了个通用 SSE 解析器只认[DONE]。接 Anthropic 时流一直不结束前端转圈转到超时。排查了半天才发现 Anthropic 用message_stop事件。后来我在解析器里同时判断两种结束信号才算通用。这个教训是别假设所有 SSE 都用[DONE]结尾。第三个坑是工具调用的参数解析。OpenAI 的arguments是 JSON 字符串Anthropic 的input是对象。我迁移时忘了这点直接把input当字符串处理结果json.loads一个已经是 dict 的东西报TypeError。后来加了个类型判断才解决。这种差异在文档里往往一笔带过但实际写代码时特别容易中招。第四个坑是用量统计字段名。我有个监控面板统计 token 消耗迁移后数字全变 0。查了半天发现字段名从prompt_tokens变成了input_tokens。这种静默失败最烦人不报错但数据不对。建议迁移后专门跑一次统计校验确认数字对得上。说到底两套协议差异的本质是产品理念不同OpenAI 追求一个接口搞定所有所以把 system、tool 都塞进 messagesAnthropic 追求职责清晰所以把 system 独立、把 content 做成块数组。理解了这个迁移时就不会觉得这些差异是故意找麻烦而是各有各的合理性。我个人现在的做法是业务层用统一抽象底层按 provider 适配这样既能享受各家的模型优势又不用被协议绑死。如果你也在做多模型接入强烈建议早点把这层适配写出来后面换模型、加模型都会轻松很多。