Anthropic SDK 快速开始

本页通过 Anthropic SDK 示例说明如何把客户端请求发送到 AISIX，并通过网关路由到配置好的模型别名。

本指南会把 Anthropic 风格的 SDK 客户端指向 AISIX AI 网关。这种方式适合已经使用 Anthropic Messages 格式、并希望尽量少改客户端代码的应用。

本配置会向本地网关添加一个由 Anthropic 支持的模型别名，为该别名创建调用方 API Key，并通过 Anthropic Python SDK 调用 POST /v1/messages。

相比 OpenAI SDK 快速开始，本指南需要更多网关配置，因为主快速开始已经创建了 OpenAI 服务提供方密钥、模型别名和调用方 API Key。Anthropic 使用相同的网关资源模式，但客户端 API 形态不同，因此本快速开始会先创建 Anthropic 对应资源，再运行 SDK 示例。

准备工作

完成自托管快速开始。
准备一个 Anthropic API Key。
安装 Python 3.8 或更新版本。
安装 curl 和 jq，用于创建并验证示例别名。

请求流程

主快速开始会创建名为 gpt-4o-mini、由 OpenAI 支持的别名。本快速开始会新增 claude-demo，这是一个由 Anthropic 支持的别名，使 Anthropic SDK 客户端可以通过 /v1/messages 调用 AISIX。

保留 Anthropic SDK 客户端，但让请求经过网关，而不是直接调用 Anthropic：

应用会发送调用方 API Key sk-anthropic-caller、AISIX 模型别名 claude-demo，并使用网关 base URL http://127.0.0.1:3000。

AISIX 会将 claude-demo 解析到上游 Anthropic 模型，并在上游侧注入已保存的服务提供方凭证。

配置网关

创建 Anthropic 服务提供方密钥，添加 claude-demo 模型别名，并创建可使用该别名的调用方 API Key。

设置环境变量

导出 Admin 命令要使用的变量：

export AISIX_ADMIN_KEY="admin-local-only-change-me"
export AISIX_API_KEY="sk-anthropic-caller"
export ANTHROPIC_API_KEY="YOUR_ANTHROPIC_API_KEY"   # 替换为你的 Anthropic API Key
export ANTHROPIC_MODEL="claude-sonnet-4-6"          # AISIX 发送给 Anthropic 的上游模型 ID
export AISIX_ANTHROPIC_ALIAS="claude-demo"          # 应用发送给 AISIX 的面向客户端模型别名

创建 Anthropic 服务提供方密钥

创建一个保存上游 Anthropic 凭证的服务提供方密钥：

ANTHROPIC_PROVIDER_KEY_RESPONSE=$(curl -sS -X POST "http://127.0.0.1:3001/admin/v1/provider_keys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "anthropic-upstream",
    "provider": "anthropic",
    "adapter": "anthropic",
    "secret": "'"${ANTHROPIC_API_KEY}"'",
    "api_base": "https://api.anthropic.com"
  }')

printf '%s\n' "${ANTHROPIC_PROVIDER_KEY_RESPONSE}" | jq .
ANTHROPIC_PROVIDER_KEY_ID=$(jq -r '.id // empty' <<< "${ANTHROPIC_PROVIDER_KEY_RESPONSE}")

AISIX 会在 api_base 后追加 /v1/messages，因此这里使用不带路径的主机 https://api.anthropic.com。

创建由 Anthropic 支持的模型别名

创建面向客户端的模型别名：

ANTHROPIC_MODEL_RESPONSE=$(curl -sS -X POST "http://127.0.0.1:3001/admin/v1/models" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "'"${AISIX_ANTHROPIC_ALIAS}"'",
    "provider": "anthropic",
    "model_name": "'"${ANTHROPIC_MODEL}"'",
    "provider_key_id": "'"${ANTHROPIC_PROVIDER_KEY_ID}"'"
  }')

printf '%s\n' "${ANTHROPIC_MODEL_RESPONSE}" | jq .
ANTHROPIC_MODEL_ID=$(jq -r '.id // empty' <<< "${ANTHROPIC_MODEL_RESPONSE}")

客户端向 AISIX 发送 claude-demo。上游服务提供方会收到 claude-sonnet-4-6。

创建 AISIX API Key

创建可访问 claude-demo 的调用方 API Key：

AISIX_API_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')

ANTHROPIC_APIKEY_RESPONSE=$(curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": ["'"${AISIX_ANTHROPIC_ALIAS}"'"]
  }')

printf '%s\n' "${ANTHROPIC_APIKEY_RESPONSE}" | jq .
ANTHROPIC_APIKEY_ID=$(jq -r '.id // empty' <<< "${ANTHROPIC_APIKEY_RESPONSE}")

验证别名可见

列出该调用方 API Key 可见的模型：

curl -sS "http://127.0.0.1:3000/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  | jq -r '.data[].id'

输出中应该包含 claude-demo。

运行 SDK 示例

安装 Anthropic SDK，将其指向 AISIX，并通过网关发送一次 Anthropic 风格请求。

安装 Anthropic SDK

创建并激活一个小型 Python 环境：

python3 -m venv .venv
. .venv/bin/activate

在虚拟环境中安装 Anthropic SDK：

python -m pip install anthropic

创建客户端示例

使用兼容 Anthropic 的客户端，并传入网关 base URL 和调用方 API Key：

anthropic-sdk-example.py
import os

from anthropic import Anthropic

client = Anthropic(
  api_key=os.environ["AISIX_API_KEY"],
  base_url=os.environ["AISIX_BASE_URL"],
)

message = client.messages.create(
  model=os.environ.get("AISIX_MODEL", "claude-demo"),
  max_tokens=128,
  messages=[{"role": "user", "content": "Say hello from AISIX."}],
)

print(message.content[0].text)

设置面向网关的 SDK 参数：

export AISIX_API_KEY="sk-anthropic-caller"
export AISIX_MODEL="claude-demo"
export AISIX_BASE_URL="http://127.0.0.1:3000"

运行示例：

python anthropic-sdk-example.py

你应该会看到一段简短的助手回复。具体文本取决于上游模型。

验证 SDK 响应

当网关能够解析 claude-demo 且上游可访问时，客户端会从 AISIX 收到 Anthropic 风格的 message 响应。

在客户端侧，SDK 会把请求发送到 POST /v1/messages；model 是 AISIX 模型别名，messages 和 max_tokens 遵循 Anthropic Messages 格式。AISIX 会认证调用方 API Key，检查 allowed_models，解析别名，并注入上游 Anthropic 服务提供方密钥。

兼容性边界

POST /v1/messages 既可以解析由 Anthropic 支持的模型别名，也可以解析非 Anthropic 支持的模型别名。由 Anthropic 支持的别名最能直接保留 Anthropic 特有的请求和响应行为。

当你需要稳定的 Anthropic 风格客户端入口时，非 Anthropic 转换很有用，但它并不与原生 Anthropic 行为完全等价。如果应用依赖工具结果往返、thinking blocks、图片块或其它 Anthropic 特有内容块，建议优先使用由 Anthropic 支持的别名，并验证完整流程。

完整端点行为请参见 Anthropic 风格 Messages API。

如果 SDK 请求失败

首先确认 SDK 使用了本快速开始中的调用方 API Key、网关 base URL 和 AISIX 模型别名。

如果 AISIX 返回 404，说明请求的模型别名未配置。如果 AISIX 返回 403，说明调用方 API Key 已存在，但没有权限使用该别名。

可选清理

如果这些资源只用于本快速开始，请先删除调用方 API Key。如果你计划继续通过 AISIX 使用 Anthropic SDK，可以保留这些资源。

curl -sS -X DELETE "http://127.0.0.1:3001/admin/v1/apikeys/${ANTHROPIC_APIKEY_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}"

然后删除模型别名：

curl -sS -X DELETE "http://127.0.0.1:3001/admin/v1/models/${ANTHROPIC_MODEL_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}"

最后删除保存上游 Anthropic 凭证的服务提供方密钥：

curl -sS -X DELETE "http://127.0.0.1:3001/admin/v1/provider_keys/${ANTHROPIC_PROVIDER_KEY_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}"

如果要移除所有本地快速开始资源，请在快速开始工作目录中运行 docker compose down -v。

下一步

你已经通过 Anthropic SDK 客户端调用了 AISIX。接下来可查看 /v1/messages 行为，以及不同端点族的流式响应。关于服务提供方支持情况，参见服务提供方兼容性。

准备工作​

请求流程​

配置网关​

设置环境变量​

创建 Anthropic 服务提供方密钥​

创建由 Anthropic 支持的模型别名​

创建 AISIX API Key​

验证别名可见​

运行 SDK 示例​

安装 Anthropic SDK​

创建客户端示例​

验证 SDK 响应​

兼容性边界​

如果 SDK 请求失败​

可选清理​

下一步​