跳到主要内容
版本：3.9.x

将 Anthropic Messages 转换为 OpenAI Chat Completions

本指南介绍 API7 AI 网关如何把 Anthropic Messages API 请求转换为 OpenAI Chat Completions API 格式。团队无需修改应用代码，即可继续使用 Anthropic SDK，同时把流量路由到一个 OpenAI 兼容后端服务提供方。

概览​

团队经常为不同服务采用不同的大语言模型 SDK，而切换服务提供方通常需要重写 API 集成代码。API7 AI 网关在网关层完成协议转换，解决这一问题：

  • Anthropic SDK 到 OpenAI 后端：发送 Anthropic 格式的请求；网关将其转换后转发到一个 OpenAI 兼容服务提供方。
  • 透明响应转换：OpenAI 后端返回的响应会自动转换回 Anthropic 格式。

当请求 URI 以 /v1/messages 结尾时，网关会将其识别为 Anthropic Messages 请求，并自动处理协议转换。

备注

请求 URI 可以带有自定义前缀，但必须保留 /v1/messages 后缀。如果服务提供方支持 Anthropic Messages，网关会以原始格式发送请求；如果所选服务提供方支持的是 OpenAI Chat Completions，则会执行转换。

前置条件​

  • 安装 Docker。

  • 安装 cURL，用于发送请求并验证服务。

  • 拥有一个正在运行的 API7 网关实例。

  • 从控制台获取令牌，并将其保存到环境变量：

    export API_KEY=your-dashboard-token   # 请替换为你的控制台令牌

  • 将 {gateway_group_id} 替换为网关组 ID。如果正在按照快速入门操作，请使用 default。

  • 如果使用 Admin API 示例，请创建或复用一个服务。如果尚无服务，请按照创建或复用服务操作，然后将其 ID 保存到环境变量：

    export SERVICE_ID=your-service-id         # 请替换为你的服务 ID

协议转换的工作原理​

转换流程如下：

  1. 自动检测：请求 URI 以 /v1/messages 结尾时，网关将其识别为 Anthropic Messages。
  2. 请求转换：将 Anthropic 字段映射为对应的 OpenAI 字段，包括系统提示词、消息、工具定义和参数。
  3. 响应转换：将 OpenAI 响应字段映射回 Anthropic 格式，包括内容块、停止原因和用量。
  4. 流式传输支持：将 OpenAI SSE 流数据块转换为 Anthropic SSE 事件（message_start、content_block_delta、message_delta、message_stop）。

转换兼容性​

转换支持 Anthropic Messages API 的一部分功能。部分字段会被转换或近似处理，不支持的字段可能会被静默丢弃。有关完整字段映射、版本边界和已知限制，请参阅协议参考。

配置协议转换​

把 Anthropic 格式请求路由到 OpenAI 后端。无需显式配置协议，因为 /v1/messages URI 后缀会将请求标识为 Anthropic Messages。

curl -k "https://localhost:7443/apisix/admin/routes?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  --data-binary @- <<EOF
  {
    "id": "protocol-conversion",
    "service_id": "$SERVICE_ID",
    "paths": ["/v1/messages"],
    "plugins": {
      "ai-proxy": {
        "provider": "openai",
        "auth": {
          "header": {
            "Authorization": "Bearer $OPENAI_API_KEY"
          }
        },
        "options": {
          "model": "gpt-4o"
        }
      }
    }
  }
EOF

❶ 将 URI 设置为 Anthropic Messages API 端点 /v1/messages，网关会自动将其识别为 Anthropic 协议。

❷ 将后端服务提供方设置为 openai。转发前，网关会把 Anthropic 请求转换为 OpenAI 格式。

❸ 设置后端模型。客户端发送 Anthropic 格式请求，但实际推理由此 OpenAI 模型执行。

示例：通过 Anthropic SDK 使用 OpenAI 后端​

向路由发送 Anthropic 格式请求：

curl "http://127.0.0.1:9080/v1/messages" -X POST \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "gpt-4o",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      { "role": "user", "content": "What is an API gateway?" }
    ]
  }'

你应收到 Anthropic 格式的响应：

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "An API gateway is a server that acts as a single entry point for API requests, handling routing, authentication, rate limiting, and other cross-cutting concerns for backend services."
    }
  ],
  "model": "gpt-4o",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 35
  }
}

虽然实际推理由 OpenAI GPT-4o 执行，响应仍遵循 Anthropic 格式，包括 type: "message"、content 块、stop_reason 和 input_tokens/output_tokens。

示例：跨协议工具调用​

发送包含工具定义的 Anthropic 格式请求：

curl "http://127.0.0.1:9080/v1/messages" -X POST \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "gpt-4o",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "Get weather for a location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": { "type": "string" }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      { "role": "user", "content": "What is the weather in San Francisco?" }
    ]
  }'

网关会将 Anthropic 工具定义转换为 OpenAI 函数格式，转发到 OpenAI，再把响应转换回 Anthropic tool_use 块。

后续步骤​