版本：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 格式。

协议转换会自动触发：当网关检测到发往 /v1/messages 的请求时，会将其识别为 Anthropic 协议并透明地完成转换。

备注

自动检测基于请求 URI /v1/messages。网关会把 Anthropic 格式请求转换为 OpenAI 格式后再转发。相反方向，即把 OpenAI 格式请求发送到 Anthropic 后端，不会被自动检测。

前置条件

安装 Docker。
安装 cURL，用于发送请求并验证服务。
拥有一个正在运行的 API7 网关实例。

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

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

将 {gateway_group_id} 替换为网关组 ID。如果正在按照快速入门操作，请使用 default。
如果使用 Admin API 示例，请创建或复用一个服务。如果尚无服务，请按照创建或复用服务操作，然后将其 ID 保存到环境变量：
```
export SERVICE_ID=your-service-id         # 请替换为你的服务 ID
```

协议转换的工作原理

转换流程如下：

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

支持的转换

Anthropic	方向	OpenAI
`system`（顶层字段）	请求	`messages[0].role: "system"`
`max_tokens`	请求	`max_completion_tokens`
`stop_sequences`	请求	`stop`
`stop_reason: "end_turn"`	响应	`finish_reason: "stop"`
`stop_reason: "max_tokens"`	响应	`finish_reason: "length"`
`stop_reason: "tool_use"`	响应	`finish_reason: "tool_calls"`
`input_tokens` / `output_tokens`	响应	`prompt_tokens` / `completion_tokens`
`tool_use` / `tool_result` 块	请求	`function` / `tool` 调用

配置协议转换

把 Anthropic 格式请求路由到 OpenAI 后端。无需显式配置协议，网关会根据 URI 自动检测协议。

Admin API
ADC

curl -k "https://localhost:7443/apisix/admin/routes?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -d '{
    "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"
        }
      }
    }
  }'

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

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

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

adc.yaml
services:
  - name: Protocol Conversion
    routes:
      - uris:
          - /v1/messages
        name: protocol-conversion
        plugins:
          ai-proxy:
            provider: openai
            auth:
              header:
                Authorization: "Bearer ${OPENAI_API_KEY}"
            options:
              model: gpt-4o

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

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

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

将配置同步到 API7 网关：

adc sync -f adc.yaml

示例：通过 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 块。

限制

自动检测依赖精确的 URI /v1/messages，不会把其他 URI 模式识别为 Anthropic 协议。
协议转换目前仅支持 Anthropic 与 OpenAI，尚不支持其他协议组合。

后续步骤

接入 Anthropic Claude — 不经过协议转换，直接把流量路由到 Anthropic。
多模型路由和故障转移 — 将协议转换与多模型路由组合使用。
完整配置说明请参阅 ai-proxy。

概览​

前置条件​

协议转换的工作原理​

支持的转换​

配置协议转换​

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

示例：跨协议工具调用​

限制​

后续步骤​

概览