Inizia con l'estensione interfaccia della riga di comando di Azure

SI APPLICA A: AI Gateway (anteprima)

Importante

AI Gateway è attualmente in anteprima pubblica. Durante l'anteprima pubblica, AI Gateway è disponibile nelle seguenti regioni:

  • Stati Uniti - Stati Uniti orientali 2
  • Europa - Svezia Centrale

Usare l'estensione aigateway dell'interfaccia della riga di comando di Azure per dare alle applicazioni accesso alle distribuzioni esistenti del modello Microsoft Foundry tramite un gateway condiviso.

Questo quickstart introduce i az aigateway comandi e ti guida attraverso la tua prima richiesta di modello da un terminale Bash o PowerShell.

Prerequisites

  • interfaccia della riga di comando di Azure versione 2.75.0 o successiva.
  • Un abbonamento Azure e un gruppo di risorse esistente.
  • Il provider di risorse Microsoft.ApiManagement registrato nella sottoscrizione. Vedere Registrare un provider di risorse.
  • Ruolo Collaboratore nel gruppo di risorse.
    • Per usare un gateway esistente, serve Contributor su quel gateway, o permessi equivalenti.
    • Assicurati che la tua risorsa AI Gateway sia di tipo Microsoft.ApiManagement/gateways o che tu abbia eseguito la migrazione a essa.
  • Un account di Microsoft Foundry nello stesso abbonamento con almeno un modello distribuito che supporta Chat Completions e un endpoint backend accessibile pubblicamente.
  • I ruoli Reader e User Access Administrator sull'account Foundry, o l'accesso ereditato equivalente, sono necessari per individuare le distribuzioni e concedere all'identità del gateway l'accesso.
  • Un terminale Bash con curl, oppure un terminale PowerShell. Anche l'installatore di Bash richiede shasum o sha256sum.

Questo esempio utilizza un account Foundry denominato ai-foundry-demo-learn con una distribuzione gpt-6.1-sol. Le richieste di modello possono comportare costi di inferenza.

Installare l'estensione

Usa l'installer dal repository CLI di AI Gateway. Scegli il comando per la tua shell:

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

Gli installatori scaricano la versione pubblicata, verificano il checksum SHA-256 e installano o aggiornano l'estensione aigateway . L'installazione richiede accesso HTTPS e permesso per scrivere nella directory di estensioni di interfaccia della riga di comando di Azure, ma non richiede l'accesso ad Azure. Per rivedere gli script prima di eseguirli, vedi install.sh o install.ps1.

Controlla l'installazione e i comandi disponibili:

az aigateway version
az aigateway --help

Raccomandiamo di migrare gateway sul tipo di risorsa precedente Microsoft.ApiManagement/service con lo SKU AIGateway verso Microsoft.ApiManagement/aigateways. Migrazione completa prima del 15 gennaio 2027. Seguire Migrazione al tipo di risorsa Gateway IA per ricreare la configurazione e aggiornare i client. Installare o aggiornare l'estensione non migra un gateway.

Crea o seleziona il tuo gateway

Crea un gateway di test o seleziona una risorsa esistente Microsoft.ApiManagement/aigateways con accesso pubblico in runtime:

  1. Accedi e seleziona l'abbonamento che contiene il tuo gateway e il tuo account Foundry:

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

  2. Imposta il gruppo di risorse predefinito a quello che contiene, o conterrà, il tuo gateway:

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

    I comandi gateway usano questo valore predefinito durante tutto il quickstart. I comandi Foundry specificano il proprio gruppo di risorse. Il predefinito persiste finché non lo cambi o lo cancelli.

  3. Imposta il nome del gateway e gli altri nomi delle risorse. Usa il nome di un gateway esistente o scegli un nome per un nuovo gateway. Sostituisci i valori di Foundry con i tuoi e scegli i nomi di fornitori e chiavi non utilizzati:

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

  4. Se ti serve un nuovo gateway, crealo in una regione supportata. Se hai selezionato un gateway esistente, continua con il controllo gateway:

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

  5. Controlla il gateway che hai creato o selezionato:

    az aigateway show --name "$GATEWAY"

  6. Verificare che type sia Microsoft.ApiManagement/aigateways e properties.provisioningState sia 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"
}

Modelli di Import Foundry

Collega modelli di Microsoft Foundry per usarli nel tuo gateway. Il comando import abilita l'identità gestita assegnata dal sistema al gateway, gli conferisce Foundry User sull'account e registra le distribuzioni attuali dell'account sotto un unico provider.

Per importare le distribuzioni Foundry:

  1. Cerca l'ID risorsa dell'account Foundry. Usa il nome dell'account, non un nome di progetto o di deployment:

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

  2. Importare le distribuzioni:

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

  3. Consulta il riepilogo delle importazioni per registrazioni fallite prima di proseguire. Conservare l’elemento restituito roleAssignmentId per la revisione della pulizia. Lascia trascorrere del tempo prima che una nuova assegnazione di ruolo abbia effetto prima di testare l'inferenza.

  4. Elenca i modelli importati:

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

  5. L'output sarà simile al seguente:

    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. Impostare MODEL sul nome di registrazione di una distribuzione che supporta il completamento di chat. Per l'esempio di implementazione:

    MODEL="gpt-6-1-sol"

Il fornitore raggruppa le registrazioni modello per il tuo account.

Crea una chiave API di runtime

Il tuo terminale utilizza una chiave API di runtime gateway per autenticarsi al gateway. Crea una chiave separata per il test così puoi revocarla senza cambiare le credenziali di un'altra applicazione.

Warning

Una chiave API a runtime concede accesso a tutto il gateway, non solo al modello importato. Non stamparlo, non abilitare il tracciamento della shell, non registrarlo nelle trascrizioni né eseguirne il commit nel controllo del codice sorgente. Elimina la chiave quando hai finito.

Per creare e recuperare la tua chiave di test:

  1. Crea la chiave:

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

  2. Verifica l'output:

    {
   "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. Recuperare il valore principale in una variabile shell:

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

La creazione di una chiave restituisce i metadati. Il comando separato list-secrets recupera la credenziale utilizzata per le richieste di runtime.

Chiama il modello

Invia un prompt attraverso il gateway per verificare insieme la registrazione del modello, la chiave del gateway e la connessione Foundry.

Per inviare la tua prima richiesta di modello:

  1. Recupera il nome host assegnato e l'identificatore del modello runtime, poi costruisci l'URL di 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 il nome host restituito invece di costruirlo dal nome del gateway. L'URL completo delle Chat Completions ha la forma https://<assigned-gateway-hostname>.ai.gateway.azure.com/default/models/openai/v1/chat/completions.

  3. Invia una richiesta di completamento della chat:

    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 risposta include la risposta del modello in choices[0].message.content. Una risposta positiva conferma che la registrazione del modello, la chiave gateway e la connessione Foundry funzionano insieme.

Pulire le risorse

Rimuovi solo le risorse che hai creato per questo avvio rapido. Mantenere qualsiasi gateway preesistente, tutti i gruppi di risorse, l'account Foundry e le distribuzioni.

Per rimuovere la configurazione del test:

  1. Elimina la chiave API di runtime e cancella il suo valore dalla sessione terminale:

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

  2. Elimina il fornitore del test:

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

  3. Rivedi l'assegnazione del ruolo Foundry User sull'account Foundry. Se l'hai creato per questo quickstart, rimuovilo da controllo accesso (IAM) solo se nessun'altra connessione gateway ne ha bisogno. Mantieni l'identità gestita del gateway se altre connessioni la usano.

  4. Se hai creato un gateway per questo quickstart e non ne hai più bisogno, eliminalo. Non eseguire questo comando per un gateway preesistente:

    az aigateway delete --name "$GATEWAY"

  5. Controlla il prompt di conferma prima di eliminare il gateway.

  6. Cancella il predefinito del gruppo di risorse:

    az configure --defaults group=""

Contenuti correlati

  • Ultimo aggiornamento: