跳到主要内容

Azure OpenAI

Azure OpenAI Service 通过资源专用端点提供由 Azure 托管的 OpenAI 模型部署。AISIX 允许应用通过统一的 OpenAI 兼容网关端点访问这些部署。

此配置适用于需要使用 AISIX 身份验证、模型允许列表、限流和用量核算的 Azure OpenAI 部署。AISIX 可以使用资源 API Key 或 Entra ID 客户端凭证向上游进行身份验证。

准备工作​

开始前，请准备以下内容：

  • 一套 AISIX 环境：
    • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
    • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
  • 包含一个部署的 Azure OpenAI 资源。
  • 资源 API Key，或已获得该资源访问权限且包含 tenant_id、client_id 和 client_secret 的 Entra ID 应用注册。
  • Azure OpenAI 资源主机和部署名称。
  • curl 和 jq。

使用 AISIX Cloud 配置​

导出 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"

使用 Azure 目录服务提供方创建服务提供方密钥。控制平面会派生 azure-openai 适配器，因此不要发送 adapter：

# 请替换为实际值
export AZURE_OPENAI_API_KEY="YOUR_AZURE_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "azure-prod",
    "provider": "azure",
    "api_key": "'"$AZURE_OPENAI_API_KEY"'",
    "api_base": "https://acme-west.openai.azure.com",
    "allowed_environments": ["'"$ENV_ID"'"]
  }' | jq -r '.provider_key.id')

Dashboard 的 Azure 服务提供方表单接受资源 API Key。AISIX Cloud Admin API 也接受将上述 Entra ID 凭证 JSON 作为 api_key 值，但不接受将该凭证放在 config 中。

创建模型，并将 Azure 部署名称设为 model_name：

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gpt-4o-azure",
    "model_name": "gpt4o-prod",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

创建可访问该模型的调用方 API Key：

AZURE_CALLER_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "azure-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

使用开源 AISIX 网关配置​

在 resources.yaml 中声明 Azure 服务提供方密钥、模型别名和调用方 API Key。两种 Azure 身份验证方案使用相同的模型和调用方 API Key 资源，只有服务提供方密钥的凭证不同。

创建 Azure 服务提供方密钥​

请选择与 Azure OpenAI 资源管理方式相匹配的身份验证方案。

使用资源 API Key 身份验证​

当 Azure OpenAI 资源使用资源 API Key 管理时，请使用此选项。导出密钥以供加载器插值，然后声明服务提供方密钥：

# 请替换为实际值
export AZURE_OPENAI_API_KEY="YOUR_AZURE_API_KEY"

在服务提供方资源中使用已导出的密钥：

_format_version: "1"
provider_keys:
  - display_name: azure-prod
    provider: azure
    adapter: azure-openai
    api_key: ${AZURE_OPENAI_API_KEY}
    api_base: https://acme-west.openai.azure.com
  • provider 用于标记上游。
  • adapter 选择 Azure OpenAI。
  • api_key 从环境中插入 Azure OpenAI 资源 API Key；切勿在文件中写入明文 Secret。
  • api_base 指向 Azure OpenAI 资源主机。AISIX 也接受不带域名的资源名称，例如 acme-west。

使用 Entra ID 身份验证​

当 Azure OpenAI 资源需要通过 Entra ID 应用注册访问时，请使用此选项。将客户端凭证导出为 JSON 值，然后声明服务提供方密钥：

# 请替换为实际值
export AZURE_ENTRA_CREDENTIAL='{"tenant_id":"YOUR_TENANT_ID","client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'

在服务提供方资源中使用已导出的客户端凭证：

_format_version: "1"
provider_keys:
  - display_name: azure-aad-prod
    provider: azure
    adapter: azure-openai
    api_key: ${AZURE_ENTRA_CREDENTIAL}
    api_base: https://acme-west.openai.azure.com
  • provider 用于标记上游。
  • adapter 选择 Azure OpenAI。
  • api_key 必须包含 tenant_id、client_id 和 client_secret。client_secret 应填写 Secret 值，而不是 Secret ID。
  • api_base 指向 Azure OpenAI 资源主机。AISIX 也接受不带域名的资源名称，例如 acme-west。

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

对于国家云或主权云，请在 JSON 凭证中添加 authority_host；公共 Azure 则应省略。该值必须是纯 HTTP(S) Origin，例如 https://login.microsoftonline.us。

创建模型​

添加 models 条目，将面向调用方的别名映射到 Azure 部署名称：

models:
  - display_name: gpt-4o-azure
    provider: azure
    model_name: gpt4o-prod
    provider_key: azure-prod
  • provider 使用与服务提供方密钥相同的标签。
  • model_name 是 Azure 部署名称，而不是底层模型 ID。
  • provider_key 通过服务提供方密钥的 display_name 将模型关联到 Azure 凭证。

如果使用 Entra ID 方案，请将 provider_key 设置为服务提供方密钥的 display_name，即 azure-aad-prod。

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 值并将其导出，然后声明可访问 Azure 支持的模型别名的 API Key 资源：

# 请替换为实际值
export AZURE_CALLER_KEY="YOUR_CALLER_API_KEY"

在调用方 API Key 资源中使用已导出的密钥：

api_keys:
  - display_name: azure-caller
    key_env: AZURE_CALLER_KEY
    allowed_models: ["gpt-4o-azure"]

allowed_models 值必须与已创建的模型别名匹配。加载时会从 key_env 指定的环境变量中读取明文密钥，并对其进行哈希处理。

验证并加载资源​

如果 AISIX 安装在本地，请在加载前验证完整文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。

验证服务提供方连接​

导出 AISIX 网关 Origin：

# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

通过 AISIX 代理发送 Chat Completions 请求。无论服务提供方密钥使用哪种上游身份验证方案，请求都完全相同。

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AZURE_CALLER_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 部署路径，并拒绝查询字符串、片段和嵌入的用户信息。

后续步骤​

你已将 AISIX 连接到 Azure OpenAI，并验证了模型别名。接下来可阅读以下指南：

  • OpenAI：改为通过 OpenAI API 配置模型，而不是使用 Azure 部署。
  • 模型别名：为别名配置路由、重试行为或成本元数据。
  • 服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。