在开发 AI 应用时，我们经常需要对接不同的大模型 API。其中 OpenAI 的 Chat Completions API 和 Anthropic 的 Messages API 是目前最流行的两种。虽然它们功能相似，但 请求/响应格式、消息角色、工具调用流程 存在显著差异。本文将从实际开发角度，为你详细对比两者，并提供可直接使用的代码示例。

一、响应体格式区别

OpenAI 响应结构

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "回复内容"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { ... }
}

Anthropic 响应结构

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "回复内容" }
  ],
  "model": "claude-3-sonnet-...",
  "stop_reason": "end_turn",
  "usage": { ... }
}

二、请求体格式区别

OpenAI 请求示例

{
  "model": "gpt-4",
  "messages": [
    { "role": "system", "content": "你是一个助手" },
    { "role": "user", "content": "你好" }
  ],
  "temperature": 0.7,
  "max_tokens": 1000
}

Anthropic 请求示例

{
  "model": "claude-3-sonnet-20240229",
  "system": "你是一个助手",
  "messages": [
    { "role": "user", "content": "你好" }
  ],
  "temperature": 0.7,
  "max_tokens": 1000   // 必填！
}

三、消息角色与格式注意事项

✅ OpenAI 支持的角色

• system：设定助手行为（可出现在任意位置，但通常放在开头）
• user：用户输入
• assistant：模型回复
• tool：工具调用结果

常见错误写法：

• ❌ 使用非规范角色名（如 function_call）
• ❌ 缺少 role 或 content 字段
• ❌ 连续两个 user 或两个 assistant（虽不强制，但影响逻辑）

✅ Anthropic 支持的角色

• user 和 assistant 仅限这两种。系统指令放在顶层的 system 字段。

严格约束：

• ❌ 消息不是以 user 开头 → 报错
• ❌ 没有严格交替 → 报错
• ❌ content 是字符串而非数组（某些模型会失败）
• ❌ 最后一条 assistant 消息的内容以空白字符结尾 → 特殊失败场景
• ❌ 使用旧版 \n\nHuman: 格式 → 不兼容 Messages API

四、工具调用（函数调用）完整示例

4.1 OpenAI 格式

第一次请求：定义工具，模型返回 tool_calls

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "北京天气怎么样？" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string", "description": "城市名称" }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

模型返回（简化）：

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\":\"北京\"}"
        }
      }]
    }
  }]
}

第二次请求：回传工具执行结果

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "北京天气怎么样？" },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{ "id": "call_abc123", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\":\"北京\"}" } }]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temperature\": \"22°C\", \"condition\": \"晴\"}"
    }
  ],
  "tools": [ /* 同第一次定义 */ ]
}

关键点：工具结果使用 role: "tool"，通过 tool_call_id 关联。

4.2 Anthropic 格式

第一次请求：定义工具，模型返回 tool_use 块

{
  "model": "claude-3-sonnet-20240229",
  "system": "You are a helpful assistant.",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "北京天气怎么样？" }
      ]
    }
  ],
  "tools": [
    {
      "name": "get_weather",
      "description": "获取指定城市的天气",
      "input_schema": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "城市名称" }
        },
        "required": ["city"]
      }
    }
  ],
  "tool_choice": { "type": "auto" },
  "max_tokens": 1024
}

模型返回：

{
  "id": "msg_xyz789",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "好的，我来查询北京的天气。" },
    {
      "type": "tool_use",
      "id": "toolu_01AbC",
      "name": "get_weather",
      "input": { "city": "北京" }
    }
  ],
  "stop_reason": "tool_use"
}

第二次请求：回传工具执行结果

{
  "model": "claude-3-sonnet-20240229",
  "system": "You are a helpful assistant.",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "北京天气怎么样？" }
      ]
    },
    {
      "role": "assistant",
      "content": [
        { "type": "text", "text": "好的，我来查询北京的天气。" },
        {
          "type": "tool_use",
          "id": "toolu_01AbC",
          "name": "get_weather",
          "input": { "city": "北京" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01AbC",
          "content": "{\"temperature\": \"22°C\", \"condition\": \"晴\"}"
        }
      ]
    }
  ],
  "tools": [ /* 同第一次定义 */ ],
  "max_tokens": 1024
}

关键点：

• 工具结果放在 user 消息中，类型为 tool_result。
• 必须保留之前的 assistant 完整 content。
• 消息仍然严格交替 user/assistant（工具结果本质上是一条新的 user 消息）。

五、总结与建议