Skip to main content
API7.ai Logo

Azure OpenAI

Azure OpenAI Service provides Azure-hosted deployments of OpenAI models behind resource-specific endpoints. AISIX lets applications reach those deployments through a single OpenAI-compatible gateway endpoint.

This configuration is for Azure OpenAI deployments that should use AISIX authentication, model allowlists, rate limits, and usage accounting. AISIX can authenticate upstream with a resource API key or an Entra ID client credential.

Prerequisites​

Before starting, prepare the following:

  • One AISIX setup:
    • For AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
    • For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the Open-Source AISIX Gateway Quickstart. Configure the gateway to load a declarative resources file.
  • An Azure OpenAI resource with a deployment.
  • Either a resource API key or an Entra ID app registration with tenant_id, client_id, and client_secret granted access to the resource.
  • The Azure OpenAI resource host and deployment name.
  • curl and jq.

Configure with AISIX Cloud​

Export the AISIX Cloud connection details:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash
# The local On-Premises quickstart uses 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"

Create the provider key with the Azure catalog provider. The control plane derives the azure-openai adapter, so do not send adapter:

# Replace with your values
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')

The dashboard's Azure provider form accepts a resource API key. The AISIX Cloud Admin API also accepts the Entra ID credential JSON described above as the api_key value. The API does not accept that credential under config.

Create the model with the Azure deployment name as 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')

Create a caller API key that can access the model:

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')

Configure with the Open-Source AISIX Gateway​

Declare an Azure provider key, model alias, and caller API key in resources.yaml. Both Azure authentication schemes use the same model and caller API-key resources; only the provider-key credential differs.

Create an Azure Provider Key​

Choose the authentication scheme that matches how your Azure OpenAI resource is managed.

Use Resource API Key Authentication​

Use this option when your Azure OpenAI resource is managed with a resource API key. Export the key so the loader can interpolate it, then declare the provider key:

# Replace with your value
export AZURE_OPENAI_API_KEY="YOUR_AZURE_API_KEY"

Use the exported key in the provider resource:

_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 labels the upstream.
  • adapter selects Azure OpenAI.
  • api_key interpolates the Azure OpenAI resource API key from the environment; never place a literal secret in the file.
  • api_base points to the Azure OpenAI resource host. AISIX also accepts the bare resource name, such as acme-west.

Use Entra ID Authentication​

Use this option when your Azure OpenAI resource should be accessed through an Entra ID app registration. Export the client credential as a JSON value, then declare the provider key:

# Replace with your values
export AZURE_ENTRA_CREDENTIAL='{"tenant_id":"YOUR_TENANT_ID","client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'

Use the exported client credential in the provider resource:

_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 labels the upstream.
  • adapter selects Azure OpenAI.
  • api_key must include tenant_id, client_id, and client_secret. The client_secret value is the secret value, not the secret ID.
  • api_base points to the Azure OpenAI resource host. AISIX also accepts the bare resource name, such as acme-west.

Provider key secrets follow the credential-handling behavior described in Provider Keys.

For national or sovereign clouds, add authority_host to the JSON credential. Omit it for public Azure. The value must be a bare HTTP(S) origin, such as https://login.microsoftonline.us.

Create a Model​

Map a caller-facing alias to the Azure deployment name by adding a models entry:

models:
  - display_name: gpt-4o-azure
    provider: azure
    model_name: gpt4o-prod
    provider_key: azure-prod
  • provider uses the same label as the provider key.
  • model_name is the Azure deployment name, not the underlying model ID.
  • provider_key attaches the model to the Azure credential by its display_name.

If you used the Entra ID scheme, set provider_key to azure-aad-prod — the provider key's display_name.

AISIX builds the outbound chat-completions URL from the provider key's api_base and the model's model_name:

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

Create a Caller API Key​

Choose the caller API key value that the application will send to AISIX and export it, then declare the API key resource with access to the Azure-backed model alias:

# Replace with your value
export AZURE_CALLER_KEY="YOUR_CALLER_API_KEY"

Use the exported key in the caller API key resource:

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

The allowed_models value must match the model alias you created. The plaintext key is read from the environment variable named in key_env and hashed at load time.

Validate and Load the Resources​

If AISIX is installed locally, validate the complete file before loading it:

aisix validate --resources resources.yaml

After validation, start the gateway with the referenced environment variables in its process environment. Reload an existing gateway only if those variables are already available to the process; otherwise, restart it with the updated environment.

If you use Docker, adapt the validation and startup commands in the Open-Source AISIX Gateway Quickstart. Mount this resources.yaml file and pass every environment variable it references with -e in both commands.

Verify the Provider Connection​

Export the AISIX gateway origin:

# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

Send a chat-completions request through the AISIX proxy. The request is identical regardless of which upstream authentication scheme the provider key uses.

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."
      }
    ]
  }'

The gateway returns an OpenAI-compatible response with the caller-facing alias:

{
  "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
  }
}

For a resource API-key provider key, AISIX sends the Azure api-key header. For an Entra ID provider key, AISIX sends Authorization: Bearer <token>.

Check Azure OpenAI metrics, logs, or quota usage for the test request. If AISIX returns an upstream authentication error, check the resource API key or Entra ID credential. If it returns an upstream route error, check api_base, the deployment name in model_name, and the Azure API version supported by your deployment.

Prepare for Production​

AISIX currently sends Azure OpenAI requests with api-version=2024-10-21. Confirm that this API version is supported by your Azure OpenAI deployment and track Azure's API version deprecation schedule.

Azure may attach prompt_filter_results and content_filter_results to successful responses. AISIX accepts these Azure extension fields and returns the standard OpenAI-compatible response to the caller.

For a corporate proxy, private endpoint, or test endpoint, set api_base to the exact host AISIX should call. AISIX appends the Azure deployment path and rejects query strings, fragments, and embedded user information.

Next Steps​

You have now connected AISIX to Azure OpenAI and verified the model alias. Continue with these guides:

  • OpenAI: configure a model through the OpenAI API instead of an Azure deployment.
  • Model Aliases: configure routing, retry behavior, or cost metadata for the alias.
  • Provider Compatibility: review supported proxy endpoints and provider-specific boundaries.