Empieza con la extensión CLI de Azure

APLICA A: AI Gateway (vista previa)

Importante

AI Gateway está actualmente en vista previa pública. Durante la vista previa pública, AI Gateway está disponible en las siguientes regiones:

  • Estados Unidos - Este de EE. UU. 2
  • Europa - Suecia Central

Utiliza la extensión aigateway CLI de Azure para dar a las aplicaciones acceso a las implementaciones existentes de modelos de Microsoft Foundry a través de una pasarela compartida.

Este inicio rápido introduce los az aigateway comandos y te guía a través de tu primera solicitud de modelo desde un terminal Bash o PowerShell.

Prerequisites

  • CLI de Azure versión 2.75.0 o posterior.
  • Una suscripción a Azure y un grupo de recursos existente.
  • El proveedor de recursos Microsoft.ApiManagement se ha registrado en su suscripción. Consulte Registro de un proveedor de recursos.
  • Rol Colaborador en el grupo de recursos.
    • Para usar una pasarela existente, necesitas Contributor en esa pasarela, o permisos equivalentes.
    • Asegúrate de que tu recurso de IA Gateway sea del tipo Microsoft.ApiManagement/gateways o que hayas migrado a él.
  • Una cuenta de Microsoft Foundry en la misma suscripción con al menos un modelo desplegado que soporta Chat Completions y un endpoint backend de acceso público.
  • Los roles Lector y Administrador de acceso de usuarios en la cuenta de Foundry, o un acceso heredado equivalente, para detectar implementaciones y conceder acceso a la identidad de la puerta de enlace.
  • Un terminal Bash con curl, o un terminal PowerShell. El instalador de Bash también requiere shasum o sha256sum.

Este ejemplo utiliza una cuenta de Foundry denominada ai-foundry-demo-learn con una gpt-6.1-sol implementación. Las solicitudes de modelo pueden generar cargos por inferencia.

Instalación de la extensión

Usa el instalador del repositorio de la CLI de AI Gateway. Elige el comando para tu shell:

curl -fsSL https://aka.ms/aigateway-cli-install | sh

Los instaladores descargan la versión publicada, verifican su suma de comprobación SHA-256 e instalan o actualizan la aigateway extensión. La instalación requiere acceso HTTPS y permiso para escribir en el directorio de extensiones de la CLI de Azure, pero no requiere iniciar sesión en Azure. Para revisar los scripts antes de ejecutarlos, consulta install.sh o install.ps1.

Revisa la instalación y los comandos disponibles:

az aigateway version
az aigateway --help

Recomendamos migrar las puertas de enlace del tipo de recurso anterior Microsoft.ApiManagement/service con la SKU AIGateway a Microsoft.ApiManagement/aigateways. Complete la migración antes del 15 de enero de 2027. Siga las instrucciones de Migrar al tipo de recurso AI Gateway para volver a crear la configuración y actualizar los clientes. La instalación o actualización de la extensión no migra una puerta de enlace.

Crea o selecciona tu gateway

Crea una pasarela de prueba o selecciona un recurso existente Microsoft.ApiManagement/aigateways con acceso público en tiempo de ejecución:

  1. Inicia sesión y selecciona la suscripción que contiene tu gateway y tu cuenta de Foundry:

    az login
az account set --subscription "<subscription-id>"

  2. Establece el grupo de recursos por defecto al grupo que contiene, o contendrá, tu gateway:

    az configure --defaults group="<gateway-resource-group>"

    Los comandos de la puerta de enlace usan este valor predeterminado durante todo el inicio rápido. Los comandos de Foundry especifican su propio grupo de recursos. El predeterminado persiste hasta que lo cambies o lo elimines.

  3. Establece el nombre del gateway y los otros nombres de recursos. Usa el nombre de una pasarela existente o elige un nombre para una nueva pasarela. Sustituye los valores de Foundry por los tuyos propios y elige los nombres de proveedor y clave no utilizados:

    GATEWAY="aigw-demo-learn"
FOUNDRY_RG="aigw-microsoft-learn-docs"
FOUNDRY_ACCOUNT="ai-foundry-demo-learn"
KEY_NAME="cli-quickstart-app"

  4. Si necesitas un nuevo gateway, créalo en una región soportada. Si seleccionaste un gateway existente, continúa con la comprobación del gateway:

    az aigateway create \
  --name "$GATEWAY" \
  --location eastus2 \
  --system-assigned true

  5. Comprueba la pasarela que creaste o seleccionaste:

    az aigateway show --name "$GATEWAY"

  6. Confirme que type es Microsoft.ApiManagement/aigateways y properties.provisioningState es Succeeded.

    {
   "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/my-resource-group/aigw-microsoft-learn-docs/providers/Microsoft.ApiManagement/aigateways/aigw-demo-learn",
   "identity": {
     "principalId": "00000000-1111-1111-1111-000000000000",
     "tenantId": "00000000-1111-1111-1111-000000000000",
     "type": "SystemAssigned"
   },
   "location": "eastus2",
   "name": "aigw-demo-learn",
   "properties": {
     "frontend": {
       "defaultHostname": "aigw-demo-learn.eastus2-01.ai.gateway.azure.com"
     },
     "provisioningState": "Succeeded"
   },
   "resourceGroup": "aigw-microsoft-learn-docs",
   "sku": {
     "name": "Premium"
   },
   "tags": {},
   "type": "Microsoft.ApiManagement/aigateways"
}

Modelos de Import Foundry

Conecta modelos de Microsoft Foundry para usarlos en tu gateway. El comando de importación activa la identidad gestionada asignada por el sistema de la pasarela, le otorga Foundry User en la cuenta y registra los despliegues actuales de la cuenta bajo un solo proveedor.

Para importar tus despliegues de Foundry:

  1. Consulta el ID de recurso de la cuenta de Foundry. Usa el nombre de cuenta, no el nombre de proyecto o despliegue:

    FOUNDRY_RESOURCE_ID="$(az cognitiveservices account show \
  --resource-group "$FOUNDRY_RG" --name "$FOUNDRY_ACCOUNT" \
  --query id --output tsv)"

  2. Importa las implementaciones:

    az aigateway model-provider create \
  --gateway-name "$GATEWAY" \
  --name "$FOUNDRY_ACCOUNT" \
  --foundry-resource-id "$FOUNDRY_RESOURCE_ID"

  3. Revisa el resumen de importación de las inscripciones fallidas antes de continuar. Guarda el elemento devuelto roleAssignmentId para la revisión de la limpieza. Deja tiempo para que una nueva asignación de rol entre en vigor antes de probar la inferencia.

  4. Enumera los modelos importados:

    az aigateway model list \
  --gateway-name "$GATEWAY" \
  --model-provider "$FOUNDRY_ACCOUNT" --output table

  5. La salida tiene el siguiente aspecto:

    Name                    Provider               Kind     Model                   Version
----------------------  ---------------------  -------  ----------------------  ----------
deepseek-v4-flash       ai-foundry-demo-learn  Foundry  DeepSeek-V4-Flash       2026-04-23
fw-deepseek-v4-1-flash  ai-foundry-demo-learn  Foundry  FW-DeepSeek-V4.1-Flash  1
fw-kimi-k3              ai-foundry-demo-learn  Foundry  FW-Kimi-K3              1
gpt-6-1-sol             ai-foundry-demo-learn  Foundry  gpt-6.1-sol             2026-09-29
gpt-6-astra             ai-foundry-demo-learn  Foundry  gpt-6-astra             2026-09-03
gpt-6-luna              ai-foundry-demo-learn  Foundry  gpt-6-luna              2026-09-22
grok-4-7                ai-foundry-demo-learn  Foundry  grok-4.7                1

  6. Configura MODEL con el nombre de registro de un despliegue que admite Chat Completions. Para el ejemplo de despliegue:

    MODEL="gpt-6-1-sol"

El proveedor agrupa los registros de modelos para tu cuenta.

Crear una clave API en tiempo de ejecución

Tu terminal utiliza una clave de API de tiempo de ejecución de la puerta de enlace para autenticarse en la misma. Crea una clave separada para tu prueba para poder revocarla sin cambiar las credenciales de otra aplicación.

Warning

Una clave API en tiempo de ejecución otorga acceso a toda la pasarela, no solo acceso al modelo importado. No la imprimas, no habilites el seguimiento del shell, no la registres en transcripciones ni la incorpores al control de código fuente. Elimina la clave cuando hayas terminado.

Para crear y recuperar tu clave de prueba:

  1. Crea la clave:

    az aigateway api-key create \
  --gateway-name "$GATEWAY" \
  --name "$KEY_NAME" --display-name "CLI quickstart application"

  2. Verifica la salida:

    {
   "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/aigw-microsoft-learn-docs/providers/Microsoft.ApiManagement/aigateways/aigw-demo-learn/apiKeys/cli-quickstart-app",
   "name": "cli-quickstart-app",
   "properties": {
     "createdDate": "2026-10-25T15:24:59.3183401Z",
     "displayName": "All APIs subscription",
     "expirationDate": null,
     "state": "active"
   },
   "resourceGroup": "aigw-microsoft-learn-docs",
   "type": "Microsoft.ApiManagement/aigateways/apiKeys"
}

  3. Recupera su valor primario en una variable de shell:

    AI_GATEWAY_API_KEY="$(az aigateway api-key list-secrets \
  --gateway-name "$GATEWAY" \
  --name "$KEY_NAME" --query primaryKey --output tsv)"

Crear una clave devuelve los metadatos. El comando independiente list-secrets recupera la credencial utilizada para las solicitudes en tiempo de ejecución.

Llama al modelo

Envía un prompt a través de la puerta de enlace para verificar juntos el registro del modelo, la clave de la puerta de enlace y la conexión de Foundry.

Para enviar tu primera solicitud de modelo:

  1. Recupera el nombre de host asignado y el identificador del modelo en tiempo de ejecución, y luego construye la URL de Chat Completions:

    AI_GATEWAY_HOSTNAME="$(az aigateway show \
  --name "$GATEWAY" \
  --query properties.frontend.defaultHostname --output tsv)"

AI_GATEWAY_CHAT_URL="https://${AI_GATEWAY_HOSTNAME}/default/models/openai/v1/chat/completions"

  2. Usa el nombre de host devuelto en lugar de construirlo a partir del nombre de la pasarela. La URL completa de Chat Completions tiene la forma https://<assigned-gateway-hostname>.ai.gateway.azure.com/default/models/openai/v1/chat/completions.

  3. Enviar una solicitud de Chat Completions:

    curl "$AI_GATEWAY_CHAT_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  --data @- <<EOF
{
  "model": "$MODEL",
  "messages": [
    {"role": "user", "content": "Give me three uses for an AI gateway."}
  ]
}
EOF

La respuesta incluye la respuesta del modelo en choices[0].message.content. Una respuesta exitosa confirma que el registro del modelo, la clave de pasarela y la conexión de Foundry funcionan juntos.

Limpieza de recursos

Elimina solo los recursos que creaste para este inicio rápido. Conserva cualquier gateway preexistente, todos los grupos de recursos y la cuenta y despliegues de Foundry.

Para eliminar tu configuración de prueba:

  1. Elimina la clave API de ejecución y borra su valor de la sesión terminal:

    az aigateway api-key delete \
  --gateway-name "$GATEWAY" --name "$KEY_NAME"
unset AI_GATEWAY_API_KEY

  2. Elimina el proveedor de prueba:

    az aigateway model-provider delete \
  --gateway-name "$GATEWAY" --name "$FOUNDRY_ACCOUNT"

  3. Revisa la asignación de rol de usuario de Foundry en la cuenta de Foundry. Si lo creaste para este inicio rápido, elimínalo del control de acceso (IAM) solo si ninguna otra conexión de gateway lo necesita. Conserva la identidad gestionada del gateway si otras conexiones la usan.

  4. Si ha creado una puerta de enlace para esta guía de inicio rápido y ya no la necesita, elimínela. No ejecutes este comando para un gateway preexistente:

    az aigateway delete --name "$GATEWAY"

  5. Revisa el aviso de confirmación antes de borrar la pasarela.

  6. Borrar el valor predeterminado del grupo de recursos:

    az configure --defaults group=""

Contenido relacionado

  • Se actualizó por última vez el