2. API兼容性深度拆解：OpenAI API标准格式与各家差异

聊到API兼容性，我得先说说我的一个习惯。每次评估一个新模型，我第一件事不是看它的benchmark分数，而是直接拿OpenAI的Chat Completions接口去怼。为什么？因为说白了，这已经是事实上的行业标准了。你想想看，从2023年初到现在，几乎所有主流大模型厂商都在往这个格式上靠。

2.1 OpenAI API标准格式：Chat Completions

先看一个最标准的请求体长什么样。我项目中经常这么写：

curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "system", "content": "你是一个AI助手"},
      {"role": "user", "content": "你好"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'

这个结构其实就三个核心部分：model指定模型、messages放对话历史、参数控制生成行为。嗯，这里要注意，messages数组里的role只有三种：system、user、assistant。我见过有人把function call的结果乱塞进去，结果接口直接报错。

2.2 各家API的差异点

接下来我拆解一下各家在三个关键维度上的差异：Endpoint、参数命名、Stream模式。这些都是我在实际迁移项目中踩过的坑。

2.2.1 Endpoint差异

厂商	Endpoint	备注
OpenAI	/v1/chat/completions	标准格式
Anthropic	/v1/messages	路径不同，且请求体结构差异大
Google Gemini	/v1beta/models/{model}:generateContent	RESTful风格，参数在路径中
百度文心	/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions	路径较长，且需要access_token
阿里通义千问	/compatible-mode/v1/chat/completions	兼容模式，路径与OpenAI几乎一致

我个人习惯是，先看Endpoint的路径结构。如果路径里带compatible-mode或者chat/completions，那大概率是兼容OpenAI的。像Anthropic那种完全不同的路径，就得单独写适配层。

2.2.2 参数命名差异

这个坑我踩过好几次。不同厂商对同一个参数的命名可能完全不同。举个例子：

// OpenAI
{
  "max_tokens": 1024,
  "temperature": 0.7,
  "top_p": 0.9,
  "frequency_penalty": 0.5,
  "presence_penalty": 0.5
}

// Anthropic
{
  "max_tokens": 1024,
  "temperature": 0.7,
  "top_p": 0.9,
  // 没有frequency_penalty和presence_penalty
  // 但有top_k参数
}

// Google Gemini
{
  "generationConfig": {
    "maxOutputTokens": 1024,
    "temperature": 0.7,
    "topP": 0.9,
    "topK": 40
  }
  // 注意：参数名是驼峰命名，且放在generationConfig里
}

2.2.3 Stream模式差异

Stream模式是实时对话的关键。各家实现方式差异很大，我重点说三个：

• OpenAI：标准SSE格式，每个chunk包含完整的delta对象。格式是data: {"choices":[{"delta":{"content":"你好"}}]}，最后以data: [DONE]结束。
• Anthropic：也是SSE，但事件类型不同。有message_start、content_block_delta、message_stop等事件。解析起来稍微复杂一点。
• Google Gemini：使用gRPC流式传输，或者HTTP的Server-Sent Events。但返回格式是data: {"candidates":[{"content":{"parts":[{"text":"你好"}]}}]}，结构嵌套更深。

我建议你在做流式解析时，不要直接硬编码解析逻辑。写一个抽象层，把不同厂商的stream格式统一成标准的事件格式。这样切换模型时，只需要改底层适配器。

2.3 知识体系结构图

下面这张图是我自己整理的API兼容性分析框架，你可以对照着看：

2.4 实战建议

最后给几个实战建议，都是我在多个项目中验证过的：

1. 不要直接硬编码API调用。写一个抽象层，把不同厂商的差异封装起来。这样切换模型时，只需要改配置文件和适配器。
2. 注意错误处理。不同厂商的错误码和错误信息格式差异很大。我建议统一封装成标准错误类型，方便上层处理。
3. 测试要覆盖Stream模式。很多问题在非流式模式下看不出来，一开Stream就暴露了。比如超时设置、断线重连、数据解析等。
4. 关注版本更新。大模型API迭代很快，参数和Endpoint可能会变。建议定期检查文档，或者用自动化测试来监控兼容性。