从 OpenAI 迁到 Anthropic 协议：字段对照与踩坑点

把应用从 OpenAI 协议换到 Anthropic 协议，不是改一个 base URL 就完事。两套协议在消息结构、系统提示、参数命名、工具调用和错误形状上都不一样。中转站通常同时支持两种协议，但支持不等于无损转换。

一、请求结构对照

最容易漏的是 max_tokens 必填和 anthropic-version 头。少任何一个都返回 400。

二、同一个请求的两种写法

OpenAI：

{
  "model": "gpt-4o-mini",
  "messages": [
    {"role": "system", "content": "你是简洁的助手。"},
    {"role": "user", "content": "用一句话解释 TCP 三次握手。"}
  ],
  "max_tokens": 200
}

Anthropic：

{
  "model": "claude-sonnet-4-5",
  "system": "你是简洁的助手。",
  "messages": [
    {"role": "user", "content": "用一句话解释 TCP 三次握手。"}
  ],
  "max_tokens": 200
}

三、五处最容易出错的地方

1. 多轮对话里的 assistant 前缀

Anthropic 要求 messages 以 user 开头、user 结尾（可以有一轮 assistant 前缀用于预填充）。如果你的历史记录从 assistant 开始，或者中间有连续的 user，会返回 400。

迁移时要清洗历史：合并连续同角色消息，丢弃开头的 assistant。

2. 图片的传法

OpenAI 用 image_url，可以是 URL 也可以是 base64 data URI。Anthropic 用 source 对象，类型是 base64 或 url，结构完全不同。如果代码里直接拼 JSON，这里必须改。

3. 工具调用的返回

OpenAI 的 tool_calls 是 assistant 消息上的数组，每个有 id、function.name、function.arguments（JSON 字符串）。Anthropic 的 tool_use 是 content block，input 是对象不是字符串。

如果你的代码对 arguments 做了 JSON.parse，换成 Anthropic 后会拿到对象，JSON.parse 会抛错。

4. 停止原因

直接字符串比较 === "stop" 的代码，换协议后会静默失效——不报错，但逻辑走错分支。

5. 流式事件

OpenAI 的流是一串 choices[0].delta。Anthropic 的流是事件类型流：message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop。

需要一个适配层把 Anthropic 事件转成统一的增量文本。中转站如果声称"兼容 OpenAI"，通常是它自己做了这层转换，但转换质量参差不齐——这正是需要测的地方。

四、怎么验证迁移是否无损

用同一个提示词分别打两套协议，对比：

1. 输出长度是否接近（差太多说明参数没生效）
2. token 计数量级是否合理（Anthropic 的 tokenizer 与 OpenAI 不同，比例约 1:1.1–1.3）
3. 工具调用能否正确解析
4. 流式是否逐块到达

本站检测台支持四种协议（OpenAI Chat、OpenAI Responses、Anthropic Messages、Gemini），可以分别跑七项检查，直接看哪套协议下有问题。

五、什么时候该用中转站的"兼容层"

如果站点同时提供 /v1/chat/completions 和 /v1/messages，优先用原生协议。兼容层是站点自己写的转换，多一层就多一处可能出错的地方。只有当你的客户端只支持 OpenAI 协议时，才用兼容层，并且要额外验证工具调用和流式。

六、一个迁移检查表

• [ ] max_tokens 已设为必填并有默认值
• [ ] anthropic-version 头已加
• [ ] 历史消息已清洗（user 开头、无连续同角色）
• [ ] 图片改为 source 结构
• [ ] 工具调用按对象解析，不再 JSON.parse
• [ ] stop_reason 映射表已更新
• [ ] 流式适配层能处理 Anthropic 事件类型
• [ ] 错误体解析兼容两种格式

八项都过，再切生产流量。