# 代理 Anthropic 请求

[Anthropic](https://www.anthropic.com/) 提供原生 Messages API 和 OpenAI 兼容 API，用于访问 Claude 模型。

本指南将介绍如何使用 [`ai-proxy`](https://docs.apiseven.com/hub/ai-proxy.md) 插件将 APISIX 与 Anthropic 集成。当 `provider` 设置为 `anthropic` 时，无需配置自定义端点。

## 前提条件[​](#前提条件 "前提条件的直接链接")

* 安装 [Docker](https://docs.docker.com/get-docker/)。
* 安装 [cURL](https://curl.se/) 以便向服务发送请求进行验证。
* 按照 [入门教程](https://docs.apiseven.com/apisix/getting-started.md) 在 Docker 或 Kubernetes 上启动一个新的 APISIX 实例。

## 获取 Anthropic API Key[​](#获取-anthropic-api-key "获取 Anthropic API Key的直接链接")

按照 [Anthropic API 文档](https://platform.claude.com/docs/en/api/overview) 创建账户并生成 API Key。将 API Key 和受支持的[模型 ID](https://platform.claude.com/docs/en/models/overview)保存为环境变量：

```
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # replace with your API key

export ANTHROPIC_MODEL=claude-sonnet-5-5
```

## 创建指向 Anthropic 的路由[​](#创建指向-anthropic-的路由 "创建指向 Anthropic 的路由的直接链接")

以下示例通过自定义路径接收 OpenAI Chat Completions 请求。APISIX 会根据 `messages` 字段识别请求格式，并将请求发送到 Anthropic 的 OpenAI 兼容端点。如果要接收 Anthropic 原生 Messages 格式，请配置一个以 `/v1/messages` 结尾的路由 URI；详见 [原生 Anthropic Messages API 透传](https://docs.apiseven.com/hub/ai-proxy.md#native-anthropic-messages-api-pass-through)。

按照如下方式创建一个启用 [`ai-proxy`](https://docs.apiseven.com/hub/ai-proxy.md) 插件的路由：

* Admin API
* ADC

```
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  --data-binary @- <<EOF

{

  "id": "anthropic-chat",

  "uri": "/anything",

  "plugins": {

    "ai-proxy": {

      "provider": "anthropic",

      "auth": {

        "header": {

          "x-api-key": "$ANTHROPIC_API_KEY"

        }

      },

      "options": {

        "model": "$ANTHROPIC_MODEL"

      }

    }

  }

}

EOF
```

❶ 将 `provider` 设置为 `anthropic`。

❷ 使用 `x-api-key` 请求头附加 Anthropic API Key。

❸ 设置保存在 `ANTHROPIC_MODEL` 中的 Anthropic 模型。

adc.yaml

```
services:

  - name: Anthropic Service

    routes:

      - uris:

          - /anything

        name: anthropic-chat

        plugins:

          ai-proxy:

            provider: anthropic

            auth:

              header:

                x-api-key: "${ANTHROPIC_API_KEY}"

            options:

              model: "${ANTHROPIC_MODEL}"
```

❶ 将 `provider` 设置为 `anthropic`。

❷ 使用 `x-api-key` 请求头附加 Anthropic API Key。

❸ 设置保存在 `ANTHROPIC_MODEL` 中的 Anthropic 模型。

预览服务变更。以下选项仅比较本示例的服务，因此其他网关资源不会受到影响：

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=anthropic-chat
```

检查 `diff.yaml`，确认其中仅包含预期的服务和路由变更。然后使用相同范围同步已审查的配置：

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=anthropic-chat
```

## 验证[​](#验证 "验证的直接链接")

向该路由发送如下请求。请求未指定 `model`，因为 `ai-proxy` 会添加插件配置中的模型：

```
curl "http://127.0.0.1:9080/anything" -X POST \

  -H "Content-Type: application/json" \

  -d '{"messages": [{"role": "user", "content": "Hello"}]}'
```

你应当会收到类似如下的 OpenAI Chat Completions 响应。生成的文本、标识符、时间戳和 Token 数量仅作示例，实际请求的结果会有所不同：

```
{

  "id": "msg_01HUQ8fAR1XvJ9PodefrZixW",

  "object": "chat.completion",

  "created": 1793350800,

  "model": "claude-sonnet-5-5",

  "choices": [

    {

      "index": 0,

      "finish_reason": "stop",

      "message": {

        "role": "assistant",

        "content": "Hello! How can I help you today?"

      }

    }

  ],

  "usage": {

    "prompt_tokens": 8,

    "completion_tokens": 12,

    "total_tokens": 20

  }

}
```

对于这一兼容 OpenAI 的响应，`prompt_tokens` 已包含缓存用量。计算提示词总用量时，不要再加上单独的缓存字段。

## 代理原生 Anthropic Messages 请求[​](#代理原生-anthropic-messages-请求 "代理原生 Anthropic Messages 请求的直接链接")

当客户端和 Anthropic 都使用 Messages API 时，请配置一条以 `/v1/messages` 结尾的路由。APISIX 会检测该路径，并在不转换协议的情况下转发原生请求，从而保留 Anthropic 特有的请求和响应字段。

创建原生 Messages 路由：

* Admin API
* ADC

```
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  --data-binary @- <<EOF

{

  "id": "anthropic-messages",

  "uri": "/v1/messages",

  "plugins": {

    "ai-proxy": {

      "provider": "anthropic",

      "auth": {

        "header": {

          "x-api-key": "$ANTHROPIC_API_KEY"

        }

      },

      "options": {

        "model": "$ANTHROPIC_MODEL"

      }

    }

  }

}

EOF
```

adc.yaml

```
services:

  - name: Anthropic Messages Service

    routes:

      - uris:

          - /v1/messages

        name: anthropic-messages

        plugins:

          ai-proxy:

            provider: anthropic

            auth:

              header:

                x-api-key: "${ANTHROPIC_API_KEY}"

            options:

              model: "${ANTHROPIC_MODEL}"
```

单独预览原生 Messages 服务，避免本示例替换上面配置的 Chat Completions 服务：

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=anthropic-messages
```

检查 `diff.yaml`，确认其中仅包含原生 Messages 服务和路由。然后使用相同范围同步已审查的配置：

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=anthropic-messages
```

发送原生 Messages 请求：

```
curl "http://127.0.0.1:9080/v1/messages" -X POST \

  -H "Content-Type: application/json" \

  -H "anthropic-version: 2023-06-01" \

  -d '{

    "max_tokens": 128,

    "messages": [

      {

        "role": "user",

        "content": "Hello"

      }

    ]

  }'
```

你应会收到类似以下内容的原生 Anthropic Messages 响应。生成的文本、标识符和 Token 数量仅作示例，实际请求的结果会有所不同：

```
{

  "id": "msg_01HUQ8fAR1XvJ9PodefrZixW",

  "type": "message",

  "role": "assistant",

  "model": "claude-sonnet-5-5",

  "content": [

    {

      "type": "text",

      "text": "Hello! How can I help you today?"

    }

  ],

  "stop_reason": "end_turn",

  "stop_sequence": null,

  "usage": {

    "input_tokens": 8,

    "output_tokens": 12

  }

}
```

APISIX 会保留 Anthropic 原生的 `usage` 对象。对于访问日志、Prometheus 指标和基于 Token 的限流，归一化后的提示词总量包含输入 Token、缓存读取 Token 和缓存创建 Token。单独的缓存字段仍可用于自定义用量统计。

要验证流式响应，请发送 `stream` 设为 `true` 的请求。`-N` 选项会禁用 curl 响应缓冲，使各事件到达时立即显示：

```
curl -N "http://127.0.0.1:9080/v1/messages" -X POST \

  -H "Content-Type: application/json" \

  -H "anthropic-version: 2023-06-01" \

  -d '{

    "max_tokens": 128,

    "stream": true,

    "messages": [

      {

        "role": "user",

        "content": "Hello"

      }

    ]

  }'
```

你应会收到以 `message_stop` 结束的 Anthropic SSE 事件，以下为缩略响应示例：

```
event: message_start

data: {"type":"message_start","message":{"type":"message","role":"assistant",...}}



event: content_block_delta

data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}



...



event: message_stop

data: {"type":"message_stop"}
```

## 下一步[​](#下一步 "下一步的直接链接")

现在你已经学会如何将 APISIX 与 Anthropic 集成。更多详细信息，请参阅 [Anthropic API 文档](https://platform.claude.com/docs/en/api/overview) 和 [模型](https://platform.claude.com/docs/en/models/overview) 页面。
