服务提供方密钥

创建服务提供方密钥，用于保存 AISIX 解析模型别名后访问上游所需的凭证和端点设置。在 AISIX Cloud 中，模型通过 ID 引用服务提供方密钥；在开源 AISIX 网关中，resources.yaml 里的模型通过 display_name 引用。两种方式都能避免在应用代码中保存上游凭证，并允许多个别名复用同一个凭证。

创建示例涵盖两种管理方式。字段和行为章节会说明 AISIX Cloud Admin API 与声明式资源文件之间的重要差异。

前置条件

开始前请准备：

上游服务提供方凭证。
对于 AISIX Cloud，需要环境访问权限和具有写入权限的 Admin Token。对于 On-Premises 部署，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
对于开源 AISIX 网关，需要一个加载声明式资源文件的网关。开源 AISIX 网关快速入门提供了可运行的配置和重新加载流程。

创建服务提供方密钥

根据部署使用的管理方式配置凭证。

AISIX Cloud

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

服务提供方密钥的作用域是组织。allowed_environments 列出创建模型时可以引用该密钥的环境，因此请包含模型所在环境。

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；请包含 /api，且不要以斜杠结尾。
# 本地 On-Premises 快速入门使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

以下示例创建一个 OpenAI 服务提供方密钥：

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

curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "openai-prod",
    "provider": "openai",
    "api_key": "'"${OPENAI_API_KEY}"'",
    "api_base": "https://api.openai.com/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }'

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

{
  "provider_key": {
    "id": "db8613ea-2ecd-40e4-91aa-08197119f766",
    "org_id": "3f1c2b6a-9d4e-4c1f-8a2b-5e6d7c8f9a0b",
    "provider": "openai",
    "display_name": "openai-prod",
    "allowed_environments": ["9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"],
    "strip_headers": null,
    "telemetry_label": "openai-prod",
    "created_at": "2026-06-24T12:18:39Z",
    "updated_at": "2026-06-24T12:18:39Z"
  }
}

创建响应不包含 api_base；使用 GET $AISIX_CP/provider_keys/{id} 获取该密钥，即可查看端点覆盖值。

复制高亮的 id 并将其导出。创建模型时会将其用作 provider_key_id：

export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

该操作只创建上游凭证资源。要通过 AISIX 发送流量，还需把服务提供方密钥关联到模型、在调用方 API Key 上允许该模型，并使用调用方 API Key 发送代理请求。

开源 AISIX 网关

在资源文件的 provider_keys 集合中添加服务提供方密钥。请通过环境变量提供凭证，不要把明文密钥写入 YAML：

export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

在服务提供方密钥条目中引用该变量：

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: openai-prod
    provider: openai
    adapter: openai
    api_key: ${OPENAI_API_KEY}
    api_base: https://api.openai.com/v1

模型通过该密钥的 display_name（即 openai-prod）进行引用。应用前请验证完整的资源文件。如果运行中的网关进程已经能够访问 OPENAI_API_KEY，发送 SIGHUP 即可重新加载文件；如果刚刚新增该变量，请使用该变量重启或重新创建网关，使进程能够解析它。可运行的 Docker 流程参见更新并重新加载配置。

设置服务提供方和适配器

服务提供方密钥将上游身份与上游 API 格式分开。

在 AISIX Cloud 中，服务提供方用于标识上游厂商或端点。它不是任意字符串：provider 必须是 AISIX 服务提供方目录 ID（例如 openai、anthropic 或 deepseek），或表示自定义端点的保留值 byo。该目录包含 AISIX 原生集成和来自 models.dev 的社区条目。对于开源 AISIX 网关，resources.yaml 中的 provider 是开放标签，adapter 用来选择已经实现的协议族。

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

对于 AISIX Cloud 目录中的服务提供方，控制面会根据目录条目推导适配器；发送 adapter 字段会返回 400 错误。上面的 OpenAI 示例只设置 provider: "openai"，控制面会推导 OpenAI 适配器。DeepSeek 等提供 OpenAI 兼容 API 的目录服务提供方也采用相同方式：设置 provider，并在需要时设置 api_base：

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

对于不在 AISIX Cloud 目录中的私有或 OpenAI 兼容端点，将 provider 设置为 byo，显式选择 adapter，并配置 BYO 密钥必需的 api_base：

{
  "provider": "byo",
  "adapter": "openai",
  "api_base": "https://api.example.com/v1"
}

AISIX Cloud Admin API 不允许修改现有 BYO 服务提供方密钥的适配器。请使用所需适配器创建新的服务提供方密钥，并更新依赖模型。对于开源 AISIX 网关，修改 resources.yaml 中服务提供方密钥条目的适配器并重新加载配置即可。

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

配置基础 URL

api_base 控制 AISIX 发送上游请求的位置。请按所选适配器预期的格式配置。AISIX Cloud 可在目录存在默认值时自动提供；开源网关只会为设置指南中明确说明的服务提供方推导端点。

常见示例如下：

上游 API	适配器	基础 URL
OpenAI	`openai`	`https://api.openai.com/v1`
DeepSeek	`openai`	`https://api.deepseek.com`
Gemini OpenAI 兼容 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`	`https://bedrock-runtime.<region>.amazonaws.com`
Google Vertex AI	`vertex`	`https://<region>-aiplatform.googleapis.com`

对于 Bedrock，AISIX Cloud Admin API 要求把区域运行时端点作为 api_base。开源 AISIX 网关在标准 AWS 环境中可以省略该值，让 AWS SDK 根据 region 推导端点。

AISIX 会规范化常见的复制错误，例如末尾斜杠和完整端点路径，但不会猜测任意服务提供方的 URL 布局。对于私有模型服务、企业代理或自定义端点，请显式配置 api_base。

凭证处理

服务提供方密钥保存敏感的上游凭证。在跨多个模型复用一个密钥前，请明确该上游凭证的负责人。

在 AISIX Cloud 中，api_key 只写。明文值在存储前加密，读取端点绝不会返回它。Bedrock 和 Vertex AI 的凭证包含多个字段，因此使用结构化 config 对象。创建这些服务提供方密钥时，将必需的 api_key 字段设置为空字符串，并通过 config 提供凭证。更新 config 时省略 api_key；更新请求会拒绝空的 api_key。

对于开源 AISIX 网关，请在 resources.yaml 中通过环境变量引用凭证，而不要保存明文密钥。结构化凭证需要序列化为 JSON 字符串，并通过服务提供方密钥的 api_key 字段提供。

服务提供方密钥是共享依赖。原地轮换会影响引用它的所有模型。无论使用哪种管理方式，都可以通过服务提供方密钥轮换在原地更新和渐进替换之间选择。

配置服务提供方专用覆盖

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

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

export COMPAT_API_KEY="YOUR_UPSTREAM_API_KEY"

curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "custom-openai-prod",
    "provider": "byo",
    "adapter": "openai",
    "api_key": "'"${COMPAT_API_KEY}"'",
    "api_base": "https://api.example.com/v1",
    "allowed_environments": ["'"${ENV_ID}"'"],
    "request": {
      "param_renames": {
        "max_completion_tokens": "max_tokens"
      }
    },
    "response": {
      "reasoning_field": "delta.thinking"
    }
  }'

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

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

对于开源 AISIX 网关，在资源文件的服务提供方密钥条目中添加相同的 request 和 response 配置块。

支持情况因适配器、请求路径和管理方式而异。AISIX Cloud Admin API 参考定义控制面接受的覆盖。资源文件参考定义完整的开源字段目录。

request 对象还可以控制 AISIX 发送到上游的请求头。两种管理方式都支持 request.default_headers 生成调用团队等值，也支持 request.forward_client_headers 转发指定的调用方请求头。参见上游请求头。

验证服务提供方密钥

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

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

后续步骤

继续阅读模型别名，将新的服务提供方密钥关联到面向调用方的别名。要替换现有模型使用的凭证，请按照服务提供方密钥轮换操作。

前置条件​

创建服务提供方密钥​

AISIX Cloud​

开源 AISIX 网关​

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

配置基础 URL​

凭证处理​

配置服务提供方专用覆盖​

验证服务提供方密钥​

后续步骤​