服务提供方密钥

创建服务提供方密钥，用于保存 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": "YYYY-MM-DDTHH:MM:SSZ",
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ"
  }
}

创建响应不包含 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"

将以下条目添加到完整资源文件的 provider_keys 中：

resources.yaml（模型服务提供方 Key）

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，请按照重新加载资源文件操作。如果刚刚新增该变量，请调整开源 AISIX 网关快速入门中的启动命令，使用 -e 传入该变量，再重新创建网关，使进程能够解析它。

设置服务提供方和适配器

服务提供方密钥将上游身份与上游 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 默认发送上游请求的位置。请按所选适配器预期的格式配置。如果上游在另一条路径上还提供了第二种协议，可以单独声明该路径，见声明 API 协议面。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，两种配置方式下 api_base 都是可选的。未设置时，AISIX Cloud Admin API 会保存凭证 region 对应的区域运行时端点，开源 AISIX 网关则让 AWS SDK 推导出同样的端点。参见 AWS Bedrock。

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

大多数模型服务提供方端点共用一份 DNS 缓存。无论 DNS 记录的 TTL 是多少，成功的解析结果都会复用 30 秒，因此 DNS 变更最长可能需要 30 秒才会影响新的上游连接；解析失败则会在 1 秒后重试。Amazon Bedrock 和 Realtime 使用各自独立的客户端栈；网关使用正向代理时，由代理解析主机名。

通过没有 DNS 记录的专线访问的端点，同样在 api_base 中保留服务提供方的主机名；用 resolve_addresses 固定该主机名连到哪里。

固定端点地址

通过专线访问的上游往往没有自己的 DNS 记录，而服务提供方仍然只认自己的主机名：Host 换成别的值，它就返回 404。任何 AISIX 配置都无法设置 Host（见受保护的请求头名称），因此访问这类端点的办法是：api_base 里仍然填服务提供方的主机名，另外固定该主机名连到哪里。

resolve_addresses 列出网关连接 api_base 主机时直接使用的 IP 地址，不再通过 DNS 解析该主机。每个条目都是 IPv4 或 IPv6 地址字面量，不带端口，也不带方括号。改变的只有连接目标：Host 请求头、HTTP/2 的 :authority、TLS 服务器名和证书校验都仍然使用 api_base 中的主机名，协议和端口同样仍然来自 api_base。

配置多个地址时按列出的顺序依次尝试，就像 DNS 应答里的多个地址一样：当某个地址无法建立连接时才会尝试下一个。专线在每个可用区各终结于一个地址时，正是靠这一点在其中之一不可用时保持可达。

如果你能发布一个私有 DNS 区域，把服务提供方的主机名解析到专线，那么优先这么做——它完全不需要在网关侧做任何配置。resolve_addresses 针对的是做不到这一点的场景。

在 AISIX Cloud 中固定地址

在服务提供方密钥的创建和编辑表单中填写端点地址（API base 正下方的字段）。每行填一个地址，列出的顺序就是故障转移的顺序。清空该字段即移除该覆盖，主机名重新通过 DNS 解析。

AISIX Cloud Admin API 接受同样的列表：

curl -sS -X PATCH "$AISIX_CP/provider_keys/$PROVIDER_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_base": "https://api.example-llm.com/v1",
    "resolve_addresses": ["10.20.0.11", "10.20.1.11"]
  }'

传 null 可移除该覆盖。空列表会被拒绝，因为它等于配置了一项什么都没固定的设置。

在开源网关中固定地址

在资源文件的服务提供方密钥条目中加上同一个字段：

provider_keys:
  - display_name: private-llm
    provider: byo
    adapter: openai
    api_key: ${PRIVATE_LLM_API_KEY}
    api_base: https://api.example-llm.com/v1
    resolve_addresses: ["10.20.0.11", "10.20.1.11"]

完整字段目录见资源文件参考。

了解适用范围

resolve_addresses 只作用于 api_base 的主机，不影响其他任何主机：

• 如果某个 apis 条目在同一主机上提供第二种协议，它走的是同一条专线，因为主机相同；如果它指向另一个主机，则按正常方式解析。
• api_base 必须填域名。如果密钥的端点本身已经是地址字面量，就没有可覆盖的主机，AISIX Cloud 会直接拒绝这种组合，而不是存下一项永远不会生效的配置。
• 专线使用非标准端口时，端口写在 api_base 里，而不是写在这里。这里的条目不带端口，而 api_base 中的端口也会出现在 Host 中——服务提供方本来就是这么预期的。
• Amazon Bedrock 的服务提供方密钥不接受该字段，/v1/realtime 也不会生效。两者都走各自独立的传输通道，按密钥配置的 tls 同样无法覆盖这两处。
• 当网关通过正向代理访问上游时不会读取该字段，因为主机名是交给代理去解析的。见 IDE AI 流量的正向代理。

早于该字段的网关版本会忽略它，改为通过 DNS 解析主机，这会把该密钥的凭证发到专线本来要避开的公网上。因此，只要目标环境中注册的任意一个网关还在运行这类版本，AISIX Cloud 就会拒绝保存非空列表，返回 422 并给出 DP_INCOMPATIBLE。请先把这些网关升级到带有该字段的版本。

声明 API 协议面

api_base 只能指向一个端点，适配器也只表示一种协议。有两类常见上游不符合这个形状：

• 一份凭证、两种协议。 部分服务提供方（包括 DeepSeek）会在同一个主机上以同一份凭证提供 OpenAI 兼容路径和 Anthropic 兼容路径。只能到达 api_base 指向的那条路径，就意味着另一种协议的请求全部要经过转换，而转换会丢掉该协议独有、聊天格式没有的东西，Anthropic 的提示词缓存断点就在其中。思考内容经过转换后只能以不带签名的推理内容保留。
• 没有 Responses API 的 OpenAI 兼容端点。 很多自建端点和中转端点只实现了 /v1/chat/completions。Responses API 是 chat completions 的超集而不是改名，因此适配器无法说明该路由是否存在。把 Codex 的请求转发到端点没有实现的路由，只会得到上游返回的 404。

用 apis 声明该端点原生提供哪些协议面、分别在哪个地址。每一项都可以带自己的 base，格式要求与 api_base 相同；该协议面就在 api_base 上时省略 base 即可。

{
  "provider": "deepseek",
  "api_base": "https://api.deepseek.com",
  "apis": {
    "responses": {},
    "messages": { "base": "https://api.deepseek.com/anthropic" }
  }
}

这里列出 responses 是因为该端点就在 api_base 上提供它。不写它并不表示「保持原样」——那是在声明该端点没有这个接口，Responses 请求会改为被转换。

配置成这样之后，走 /v1/chat/completions 的调用方到达 https://api.deepseek.com/chat/completions，走 /v1/messages 的调用方原样到达 https://api.deepseek.com/anthropic/v1/messages，走 /v1/responses 的调用方到达 https://api.deepseek.com/v1/responses，三者用的是同一个模型名。

可以声明两个协议面：

协议面	路由	解析规则
responses	/v1/responses	只认声明。一旦存在 apis，只有列出该协议面时 AISIX 才会原生转发 Responses 请求。不列出它，就是在告诉 AISIX 该端点没有这个路由，请求会改为转换成 chat completions。
messages	/v1/messages、/v1/messages/count_tokens	增量声明。适配器为 anthropic 的密钥无论 apis 是否列出都提供该协议面；列出它是为了给适配器是别的协议的密钥补上这两条路由。AISIX 会在两条路由上使用 x-api-key 发送服务提供方凭证，并添加 anthropic-version。

由于 responses 由声明决定，一个已有的 OpenAI 密钥如果因为别的原因新增了 apis，必须同时列出 responses，才能继续原生转发 Responses 请求。AISIX Cloud 控制台在你开启该分节时会按该密钥当前提供的协议面预填，因此默认是在现状基础上编辑。

只有当上游接受 Anthropic 身份认证请求头，并在同一个 API Base 上实现这两条路由时，才声明 messages。如果其原生 Messages API 需要 Bearer 身份认证，或不提供 /v1/messages/count_tokens，请改用经过身份认证的透传路由访问该 API。

部分目录服务提供方自带一份经过厂商线上端点验证的声明——DeepSeek 就是其中之一——指向该服务提供方自有 base 的密钥无需任何配置即可获得。该声明和其他字段一样存在密钥上：控制台打开该区块时已经填好，服务提供方密钥的详情响应会同时返回 apis 和 apis_source: catalog，因此 AISIX 替你声明了什么是可见的，而不是隐含的。自行设置 apis 会覆盖它，并报告 apis_source: operator——正是这一点让 AISIX 后续修正内置条目时不会动你自己选择的声明。用 null 清除该字段会回到内置声明，而不是变成没有任何声明。把 api_base 改指到你自己的端点则会使声明失效，因为它描述的是厂商的路径而不是你的。

对于不自带声明的服务提供方，完全不写 apis，所有协议面就继续按服务提供方和适配器解析，这也是所有没有该字段的密钥的行为。该字段不控制 Chat Completions、嵌入、音频、图片、视频、文件、批处理、微调或重排序；这些协议面一律使用 api_base。

bedrock、vertex 和 azure-openai 适配器不接受 apis。这些平台提供的是自己的路由而不是上述路由，因此请求要经过转换才能到达；例外是发往 Bedrock 或 Vertex AI 上 Claude 模型的 /v1/messages 和 /v1/messages/count_tokens，AISIX 会把它们发往平台自己的 Anthropic Messages API。

凭证处理

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

在 AISIX Cloud 中，api_key 只写。明文值在存储前加密，读取端点绝不会返回它。Bedrock 和 Vertex AI 的凭证包含多个字段，因此使用结构化 config 对象。通过 config 提供凭证并省略 api_key；更新请求会拒绝空的 api_key。Bedrock 的 config 还可以选择使用 Bedrock API Key 或网关自身的 AWS 凭证，参见选择凭证模式。

对于开源 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 使用原始调用方字段中的值。在 openai 和 azure-openai 适配器上，推理模型 Token 上限规则会先把 max_tokens 重命名为 max_completion_tokens，因此这里配置的重命名在其之后执行，具有最终决定权。

❷ 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 中。

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

后续步骤

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