服务提供方密钥

创建服务提供方密钥，保存 AISIX 在解析模型别名后使用的上游凭证和端点设置。模型通过 ID 引用服务提供方密钥，因此上游凭证不会进入应用代码，并且可以被多个别名复用。

准备工作

请先准备以下内容：

一个 Admin 监听器可用的自托管网关。
网关 config.yaml 中的 Admin Key。
一个上游服务提供方凭证。

创建服务提供方密钥

首先创建服务提供方密钥，并保存返回的 ID 供模型配置使用。

下面的示例使用 OpenAI 作为上游服务提供方：

# 请替换为实际值
export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

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" \
  --data-binary @- <<EOF
  {
    "display_name": "openai-prod",
    "provider": "openai",
    "adapter": "openai",
    "secret": "${OPENAI_API_KEY}",
    "api_base": "https://api.openai.com/v1"
  }
EOF

你应该会看到类似下面的响应：

{
  "id": "db8613ea-2ecd-40e4-91aa-08197119f766",
  "value": {
    "display_name": "openai-prod",
    "secret": "***",
    "api_base": "https://api.openai.com/v1",
    "provider": "openai",
    "adapter": "openai",
    "telemetry_tags": {
      "featured": false
    },
    "strip_headers": [
      "authorization",
      "cookie",
      "set-cookie",
      "x-api-key"
    ]
  },
  "revision": 1
}

复制高亮的 id。创建模型时会将它作为 provider_key_id 使用。

这一步只会创建上游凭证资源。要通过 AISIX 发送流量，还需要把服务提供方密钥挂到模型上，在调用方 API Key 中允许访问该模型，并使用调用方 API Key 发送代理请求。

设置服务提供方与适配器

服务提供方密钥会将上游身份与上游 API 格式解耦。

provider 用于标识上游服务提供方或端点。它是开放字符串，例如 openai、deepseek、openrouter，也可以是私有端点名称。

adapter 用于标识 AISIX 应使用的上游 API 格式。它是封闭取值，因为 AISIX 只能编码已实现的协议族，例如 openai、anthropic、bedrock、vertex 和 azure-openai。

两个字段需要配合使用。上面的 OpenAI 示例使用 provider: "openai" 和 adapter: "openai"，因为上游服务提供方和 API 格式都是 OpenAI。

对于暴露 OpenAI 兼容 API 的非 OpenAI 服务提供方，请在 provider 中保留服务提供方名称，并使用 OpenAI 适配器：

{
  "provider": "deepseek",
  "adapter": "openai",
  "api_base": "https://api.deepseek.com"
}

关于适配器选择详情，参见适配器协议族。

配置 base URL

api_base 控制 AISIX 将上游请求发送到哪里。请按照所选适配器期望的格式配置它，不要依赖 AISIX 推断默认服务提供方 URL。

常见示例如下：

上游	适配器	base URL
OpenAI	`openai`	`https://api.openai.com/v1`
DeepSeek	`openai`	`https://api.deepseek.com`
Gemini OpenAI-compatible API	`openai`	`https://generativelanguage.googleapis.com/v1beta/openai`
Anthropic	`anthropic`	`https://api.anthropic.com`
Azure OpenAI	`azure-openai`	`https://<resource>.openai.azure.com`
AWS Bedrock	`bedrock`	标准 AWS 场景可留空；只有私有 Bedrock 端点才需要设置
Google Vertex AI	`vertex`	`https://<region>-aiplatform.googleapis.com`

AISIX 会规范化常见复制粘贴错误，例如尾随斜杠和完整端点路径。但它不会猜测任意服务提供方 URL 结构。对于私有网关、企业代理或自带端点，请显式配置 api_base。

凭证处理

服务提供方密钥会保存敏感的上游凭证。在多个模型复用同一个服务提供方密钥前，请先明确上游凭证的归属。

在自托管部署中，网关会把 secret 以明文形式保存在配置的 etcd 前缀下。任何拥有该 etcd keyspace 读取权限的人都可以读取凭证，因此应限制 etcd 网络访问，在可用时启用静态加密，并将网关到 etcd 的链路放在可信基础设施内。

服务提供方密钥是共享依赖。轮换一个服务提供方密钥会影响所有引用它的模型。

配置服务提供方兼容性覆盖

服务提供方密钥覆盖可以适配与所选适配器略有差异的上游 API。引用该服务提供方密钥的每个模型都会继承这些覆盖，因此只在需要时配置。

以下示例为自定义兼容 OpenAI 上游配置请求和响应兼容性：

export COMPAT_API_KEY="YOUR_UPSTREAM_API_KEY"

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" \
  --data-binary @- <<EOF
  {
    "display_name": "custom-openai-prod",
    "provider": "custom-openai",
    "adapter": "openai",
    "secret": "${COMPAT_API_KEY}",
    "api_base": "https://api.example.com/v1",
    "request": {
      "param_renames": {
        "max_completion_tokens": "max_tokens"
      }
    },
    "response": {
      "reasoning_field": "delta.thinking"
    }
  }
EOF

❶ request.param_renames 会在上游需要不同参数名时重命名顶层参数。如果请求同时包含两个名称，AISIX 使用原始调用方名称中的值。

❷ response.reasoning_field 会将非标准流式 delta 路径中的推理内容映射到 delta.reasoning_content。此覆盖适用于 openai 和 azure-openai 适配器。

不同适配器和请求路径支持的字段可能不同。有关所有请求和响应字段及其可接受值，请参阅 Admin API Reference 中的 Provider Keys。

验证服务提供方密钥

通过使用该服务提供方密钥的模型发送代表性请求，并确认上游接受请求。如果配置了自定义 reasoning_field，请发送流式 Chat Completions 请求，并确认推理内容显示在 delta.reasoning_content 中。

请先使用非生产别名测试服务提供方密钥覆盖，再在多个模型中复用该密钥。错误的覆盖会影响所有引用该服务提供方密钥的模型。

下一步

继续阅读模型别名，将服务提供方密钥挂到面向调用方的别名上。

准备工作​

创建服务提供方密钥​

设置服务提供方与适配器​

配置 base URL​

凭证处理​

配置服务提供方兼容性覆盖​

验证服务提供方密钥​

下一步​