代理 Anthropic 请求
Anthropic 提供原生 Messages API 和 OpenAI 兼容 API,用于访问 Claude 模型。
本指南将介绍如何使用 ai-proxy 插件将 APISIX 与 Anthropic 集成。当 provider 设置为 anthropic 时,无需配置自定义端点。
前提条件
获取 Anthropic API Key
按照 Anthropic API 文档 创建账户并生成 API Key。将 API Key 和受支持的模型 ID保存为环境变量:
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # replace with your API key
export ANTHROPIC_MODEL=claude-sonnet-5-5
创建指向 Anthropic 的路由
以下示例通过自定义路径接收 OpenAI Chat Completions 请求。APISIX 会根据 messages 字段识别请求格式,并将请求发送到 Anthropic 的 OpenAI 兼容端点。如果要接收 Anthropic 原生 Messages 格式,请配置一个以 /v1/messages 结尾的路由 URI;详见 原生 Anthropic Messages API 透传。
按照如下方式创建一个启用 ai-proxy 插件的路由:
- 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 模型。
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 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
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 文档 和 模型 页面。