Azure OpenAI 上游

本指南将说明如何将 AISIX AI 网关路由到 Azure OpenAI Service。调用方可以通过网关的 OpenAI 兼容 API 访问 Azure 部署。

该配置适用于希望使用 AISIX 认证、模型允许列表、限流和用量核算的 Azure OpenAI 部署。AISIX 可以使用资源 API Key 或 Entra ID 客户端凭证向上游认证。

准备工作

请先准备以下内容：

一个 Admin API 位于 :3001、代理 API 位于 :3000 的网关。
网关 config.yaml 中的 Admin Key。
一个已创建部署的 Azure OpenAI 资源。
可访问该资源的资源 API Key，或包含 tenant_id、client_id 和 client_secret 的 Entra ID 应用注册。
Azure OpenAI 资源主机、部署名称和面向调用方的别名。

配置 Azure 上游

创建 Azure 服务提供方密钥、模型别名和调用方 API Key。两种 Azure 认证方案使用相同的模型和调用方 API Key 资源，只有服务提供方密钥的 secret 不同。

创建 Azure 服务提供方密钥

请选择与你的 Azure OpenAI 资源管理方式匹配的认证方案。

使用资源 API Key 认证

当 Azure OpenAI 资源使用资源 API Key 管理时，请使用该选项：

export AISIX_ADMIN_KEY="admin-local-only-change-me"

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": "azure-prod",
    "provider": "azure",
    "adapter": "azure-openai",
    "secret": "YOUR_AZURE_API_KEY",
    "api_base": "https://acme-west.openai.azure.com"
  }'

❶ provider 用于标记上游。

❷ adapter 选择 Azure OpenAI。

❸ secret 存储 Azure OpenAI 资源 API Key。

❹ api_base 指向 Azure OpenAI 资源主机。AISIX 也接受裸资源名称，例如 acme-west。

使用 Entra ID 认证

当 Azure OpenAI 资源需要通过 Entra ID 应用注册访问时，请使用该选项：

export AISIX_ADMIN_KEY="admin-local-only-change-me"

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": "azure-aad-prod",
    "provider": "azure",
    "adapter": "azure-openai",
    "secret": "{\"tenant_id\":\"YOUR_TENANT_ID\",\"client_id\":\"YOUR_CLIENT_ID\",\"client_secret\":\"YOUR_CLIENT_SECRET\"}",
    "api_base": "https://acme-west.openai.azure.com"
  }'

❶ provider 用于标记上游。

❷ adapter 选择 Azure OpenAI。

❸ secret 必须包含 tenant_id、client_id 和 client_secret。client_secret 应填写 Entra ID 应用注册中的 Client Secret Value，而不是 Secret ID。

❹ api_base 指向 Azure OpenAI 资源主机。AISIX 也接受裸资源名称，例如 acme-west。

服务提供方密钥 secret 的处理方式遵循服务提供方凭证中说明的凭证处理行为。

对于国家云或主权云，请在 JSON secret 中添加 authority_host。公共 Azure 可省略该字段。该值必须是不带路径的 HTTP(S) origin，例如 https://login.microsoftonline.us。

保存返回的服务提供方密钥 ID，后续创建模型资源时使用。

创建模型

将面向调用方的别名映射到 Azure 部署名称：

export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

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": "gpt-4o-azure",
    "provider": "azure",
    "model_name": "gpt4o-prod",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }'

❶ provider 使用与服务提供方密钥相同的标签。

❷ model_name 是 Azure 部署名称，而不是底层模型 ID。

❸ provider_key_id 将模型关联到 Azure 凭证。

AISIX 会根据服务提供方密钥的 api_base 和模型的 model_name 构造出站 chat completions URL：

https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=2024-10-21

创建调用方 API Key

选择应用发送给 AISIX 的明文调用方 API Key，然后为 Admin 资源计算哈希：

export AISIX_API_KEY="sk-azure-caller"

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

创建可访问 Azure 模型别名的 API Key 资源：

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": "'"${CALLER_KEY_HASH}"'",
    "allowed_models": ["gpt-4o-azure"]
  }'

❶ allowed_models 必须与已创建的模型别名匹配。

验证上游

通过 AISIX 代理发送 chat completions 请求。无论服务提供方密钥使用哪种上游认证方案，该请求都相同。

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-azure",
    "messages": [
      {"role": "user", "content": "Say hello from Azure OpenAI."}
    ]
  }'

网关会返回带有面向调用方别名的 OpenAI 兼容响应：

{
  "id": "cmpl_azure_example",
  "object": "chat.completion",
  "model": "gpt-4o-azure",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello from Azure OpenAI!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 7,
    "completion_tokens": 5,
    "total_tokens": 12
  }
}

对于使用资源 API Key 的服务提供方密钥，AISIX 会发送 Azure api-key 请求头。对于 Entra ID 服务提供方密钥，AISIX 会发送 Authorization: Bearer <token>。

请在 Azure OpenAI 指标、日志或配额用量中检查测试请求。如果 AISIX 返回上游认证错误，请检查资源 API Key 或 Entra ID 凭证。如果返回上游路由错误，请检查 api_base、model_name 中的部署名称，以及该部署支持的 Azure API 版本。

生产前检查

AISIX 目前使用 api-version=2024-10-21 发送 Azure OpenAI 请求。请确认你的 Azure OpenAI 部署支持该 API 版本，并关注 Azure 的 API 版本弃用计划。

Azure 可能会在成功响应中附加 prompt_filter_results 和 content_filter_results。AISIX 会接受这些 Azure 扩展字段，并向调用方返回标准 OpenAI 兼容响应。

对于企业代理、私有端点或测试端点，请将 api_base 设置为 AISIX 应调用的精确主机。AISIX 会追加 Azure 部署路径，并拒绝查询字符串、片段和嵌入式用户信息。

下一步

你已经将 Azure OpenAI 配置为上游服务提供方协议族。对于其它 Azure 部署，可以按相同模式替换资源主机、凭证、部署名称和面向调用方的别名。

准备工作​

配置 Azure 上游​

创建 Azure 服务提供方密钥​

使用资源 API Key 认证​

使用 Entra ID 认证​

创建模型​

创建调用方 API Key​

验证上游​

生产前检查​

下一步​