Avvio rapido: creare un'istanza livello gateway di iA (anteprima)

SI APPLICA A: livello gateway di IA (anteprima)

Importante

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

Stati Uniti - Stati Uniti orientali 2
Europa - Svezia Centrale

In questa guida introduttiva rapida, crei un'istanza del livello AI Gateway (anteprima), aggiungi un modello di chat, chiami il gateway, crei una chiave di accesso in fase di esecuzione e visualizzi la telemetria.

Il livello AI Gateway di Gestione API di Azure è un livello dedicato ai carichi di lavoro AI. Supporta la gestione del traffico verso modelli — da Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex, OpenAI, Anthropic o altri fornitori — e strumenti creati a partire da server MCP esistenti, definizioni OpenAPI o connettori. Il livello gateway di IA viene attivato rapidamente, di solito entro un minuto.

Tempo per completarlo: circa 20-30 minuti. Crei: un gateway, un modello di chat, una chiave di accesso runtime e una richiesta di completamento della chat con successo.

Note

Il livello AI Gateway è in anteprima pubblica. Le funzionalità di anteprima sono fornite senza un accordo di livello di servizio e non dovrebbero essere utilizzate per carichi di lavoro di produzione a meno che la tua organizzazione non accetti i termini di anteprima.

Prerequisiti

Un account Azure con Microsoft Entra ID. L'accesso all'anteprima AI Gateway è attualmente limitato agli utenti Azure che accedono con Microsoft Entra ID.
Un abbonamento Azure e il permesso di creare risorse in un gruppo di risorse (ad esempio, il ruolo Contributor).
Accesso ad almeno un fornitore di modelli supportato, come un modello distribuito in Microsoft Foundry o Azure OpenAI.
Se il tuo provider richiede una chiave API, tieni la chiave a disposizione.
Per chiamare il gateway, usa curl (senza installazione) o un SDK OpenAI — Python 3.9 o versioni successive oppure Node.js 18 o versioni successive — con il pacchetto openai.

Il portale AI Gateway è un'esperienza web autonoma - non si usa il portale Azure.

Vai al portale del livello AI Gateway all'indirizzo ai.gateway.azure.com.
Seleziona Accedi e autentica con Microsoft Entra ID.

Usa il portale per gestire modelli, server MCP, chiavi di accesso runtime, policy e monitoraggio, in base ai permessi dell'Entra ID. I chiamanti di runtime non accedono al portale: chiamano il gateway con chiavi di accesso runtime da creare in seguito.

2. Creare un gateway

Nel portale, seleziona Crea gateway. Per usare invece un gateway esistente, selezionalo e passa al passo successivo.
Immettere un nome. Il nome diventa parte dell'endpoint runtime:

https://<gateway>.azure-api.net
Seleziona il tuo Abbonamento e una regione di anteprima supportata (Est US 2 o Svezia Centrale).
Opzionalmente imposta il gruppo Risorse sotto Avanzato. Di default, il portale ne crea uno per te.
Fare clic su Crea. L'attivazione di solito richiede meno di un minuto.

Il gateway è una risorsa dedicata nel tuo abbonamento Azure. Non scegli la capacità o aggiungi unità in scala prima di aggiungere i modelli. Per l'automazione, la versione dell'API di gestione dell'anteprima è 2026-05-01-preview; le richieste di esecuzione utilizzano il nome host gateway, non Azure Resource Manager.

3. Aggiungere un modello

Il modo più veloce per creare un modello è importarlo dagli account Microsoft Foundry.

Sotto Home, Configura il gateway, seleziona l'opzione Inizia o apri la pagina di configurazione direttamente sul /settings/start percorso.
Seleziona uno o più abbonamenti per scansionare. Opzionalmente, applica un filtro per gruppi risorse per restringere i risultati.
Esaminare gli account scoperti. Le implementazioni sono raggruppate per account Foundry madre (la risorsa Azure). La selezione avviene per account: quando selezioni un account, il wizard importa tutte le sue implementazioni di modello.
Scegli un metodo di autenticazione backend per questa importazione:
- Basato su tasti (predefinito). Il gateway memorizza la chiave API dell'account e la invia nell'intestazione api-key. Il wizard recupera la chiave al momento dell'importazione.
- Identità gestita (Microsoft Entra ID). Il gateway si autentica con la sua identità gestita. Se il gateway non ha un'identità gestita, il wizard abilita un'identità assegnata al sistema. Se esiste già uno, scegli tu quale identità usare. La procedura guidata assegna all'identità il ruolo Utente di Foundry su ogni account selezionato.
Seleziona Importa
Quando selezioni Importa, il wizard esegue un controllo di verifica dei requisiti per ogni account selezionato prima di creare qualsiasi cosa. Questo controllo conferma che l'autenticazione è configurata correttamente e che i nomi dei modelli non entrano in conflitto con quelli già presenti nel gateway. Gli account che superano il controllo vengono importati; gli account che non lo superano vengono ignorati con un avviso in linea e il resto dell’esecuzione prosegue.

Per connettere un fornitore non Foundry (AWS Bedrock, Google Vertex, OpenAI o Anthropic), seleziona invece Aggiungi un modello personalizzato. Vedi Gestire modelli e strumenti.

I chiamanti passano il nome del modello nel model campo delle richieste compatibili con OpenAI. Questo quickstart utilizza gpt-5.6-sol; sostituiscilo con il modello che hai registrato.

Suggerimento

Per provare subito il modello, apri la pagina Discover e seleziona il modello per invocarlo nel playground integrato. Il playground utilizza la chiave integrata del gateway, così puoi esplorare e testare modelli o strumenti aggiunti prima di creare una chiave di accesso runtime.

4. Chiama il gateway

Il gateway espone l'API supportata dal modello backend. I modelli di fornitori compatibili con OpenAI — come Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex e OpenAI — vengono serviti su un endpoint compatibile con OpenAI. Puntare qualsiasi client OpenAI all'URL base del gateway, inviare un'intestazione api-key e passare il nome del modello nel campo model. I modelli Anthropic utilizzano invece l'API Anthropic Messages; vedi Gestire modelli e strumenti.

Per un test rapido, usa la chiave integrata del gateway — la stessa chiave utilizzata dal playground Discover. Copialo dalla pagina Chiavi , che elenca la chiave integrata insieme alle chiavi API che concedono l'accesso in runtime a ogni asset del gateway. Per le tue applicazioni, crea invece una chiave di accesso in runtime (vedi la sezione successiva).

Imposta questi valori una volta:

export AI_GATEWAY_BASE_URL="https://<gateway>.azure-api.net/default/models/openai/v1"
export AI_GATEWAY_API_KEY="<gateway-key>"

Suggerimento

Copia l'URL base esatto dalla pagina panoramica del tuo gateway invece di costruirlo a mano.

Fai la tua prima chiamata con il cliente che preferisci:

curl "$AI_GATEWAY_BASE_URL/chat/completions" \
  -H "Content-Type: application/json" \
  -H "api-key: $AI_GATEWAY_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Give me three benefits of using an AI gateway." }
    ]
  }'

Per trasmettere i token come eventi inviati dal server, aggiungi "stream": true al corpo della richiesta.

Installa il client con pip install openai.

import os
from openai import OpenAI

# The gateway reads the api-key header, not the api_key argument.
client = OpenAI(
    base_url=os.environ["AI_GATEWAY_BASE_URL"],
    api_key="unused",
    default_headers={"api-key": os.environ["AI_GATEWAY_API_KEY"]},
)

response = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Give me three benefits of using an AI gateway."},
    ],
)
print(response.choices[0].message.content)

Per trasmettere i token man mano che vengono generati, aggiungi stream=True e itera la risposta:

stream = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "Stream a short greeting."}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Installa il pacchetto con npm install openai.

import OpenAI from "openai";

// The gateway reads the api-key header, not the apiKey argument.
const client = new OpenAI({
  baseURL: process.env.AI_GATEWAY_BASE_URL,
  apiKey: "unused",
  defaultHeaders: { "api-key": process.env.AI_GATEWAY_API_KEY },
});

const response = await client.chat.completions.create({
  model: "gpt-5.6-sol",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Give me three benefits of using an AI gateway." },
  ],
});
console.log(response.choices[0].message.content);

Per eseguire lo streaming, aggiungi stream: true e itera sulla risposta asincrona.

Ogni risposta dall'endpoint /chat/completions utilizza il formato OpenAI Chat Completions, indipendentemente dal provider compatibile OpenAI che supporta il modello.

Una chiamata senza streaming restituisce un completamento della chat:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "gpt-5.6-sol",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "1. Centralized governance ...\n2. ...\n3. ..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 24, "completion_tokens": 61, "total_tokens": 85 }
}

Con lo streaming abilitato, il gateway restituisce chat.completion.chunk eventi:

{
  "id": "chatcmpl-...",
  "object": "chat.completion.chunk",
  "model": "gpt-5.6-sol",
  "choices": [
    { "index": 0, "delta": { "content": "Hello" }, "finish_reason": null }
  ]
}

Lo stesso URL base serve anche l'API OpenAI Responses in /responses.

Se una richiesta fallisce, il gateway restituisce un codice di stato HTTP standard:

Condizione	Meaning	Controlli da eseguire
400	Richiesta non valida	Controlla il corpo della richiesta.
400	Bloccati dalla sicurezza dei contenuti o da un filtro IP, o negati dal backend	Una politica di sicurezza dei contenuti può bloccare un prompt o una risposta; Controlla anche eventuali policy di filtro IP. Per l’identità gestita, assegnare il ruolo Utente di Foundry all’identità del gateway nella risorsa di back-end. Vedere Usare l'identità gestita per l'autenticazione back-end.
401	Chiave di accesso runtime mancante o non valida	Invia la chiave nell'intestazione `api-key` e conferma che la chiave è attiva.
404	Modello sconosciuto	Conferma che il `model` valore corrisponda al nome di un modello nella pagina Modelli .
429	Limitato da un criterio di limite di frequenza o dal back-end	Esaminare i criteri di limitazione della frequenza dei token e delle richieste e rispettare l'intestazione di risposta `Retry-After`.
5xx	Errore del backend	Conferma che il fornitore backend sia in buona salute e che la credenzialità del fornitore sia valida.

Gli SDK OpenAI generano eccezioni tipate per questi codici di stato, quindi la gestione degli errori esistente funziona:

from openai import AuthenticationError, RateLimitError, APIStatusError

try:
    response = client.chat.completions.create(
        model="gpt-5.6-sol",
        messages=[{"role": "user", "content": "Hello"}],
    )
except AuthenticationError:
    ...  # 401 — check the api-key header and that the key is active
except RateLimitError:
    ...  # 429 — back off and honor the Retry-After header
except APIStatusError as e:
    ...  # inspect e.status_code for 400, 403, 404, or 5xx

5. Creare una chiave di accesso in fase di esecuzione

Le applicazioni si autenticano al gateway con una chiave di accesso runtime invece della chiave integrata. Crea una chiave separata per ogni applicazione e ambiente.

Selezionare Chiavi.
Selezionare Crea chiave API.
Immettere un nome, ad esempio quickstart-client.
Fare clic su Crea.
Copia il valore chiave e conservalo in modo sicuro. Puoi anche rivederlo più avanti nella pagina Chiavi .

Crea chiavi di accesso runtime a livello di gateway. Queste chiavi concedono l'accesso a ogni modello e strumento nel gateway. Trattali come segreti. Memorizza le chiavi in uno store segreto per le applicazioni, ruotale regolarmente e revoca le chiavi non più necessarie. Per chiamare il gateway con una chiave di accesso in fase di esecuzione, imposta AI_GATEWAY_API_KEY sul relativo valore nelle chiamate mostrate in precedenza.

6. Vedi telemetria

Il livello AI Gateway emette metriche di utilizzo dei token OpenTelemetry. Per vederli, configura prima una destinazione di telemetria, e poi invia le richieste:

Configura una destinazione di telemetria per il gateway, come Application Insights. Vedi Governare, proteggere e operare.
Invia una o più richieste tramite il gateway, come mostrato in precedenza in Chiamare il gateway.
Apri la destinazione della telemetria per rivedere l'utilizzo dei token. Se usi Application Insights, il portale fornisce un cruscotto integrato per il consumo dei token.

Poiché la telemetria viene emessa solo dopo aver connesso una destinazione, configura il monitoraggio prima di affidarti ad essa. L'utilizzo dei token è attualmente l'unica metrica generata; log, tracce e altre metriche relativi a modelli e strumenti saranno disponibili presto. I chiamanti utilizzano chiavi di accesso a runtime a livello gateway, così puoi monitorare il traffico senza esporre le credenziali del provider alle applicazioni client. Per configurare una destinazione di telemetria, vedi Governare, proteggere e operare.

Pulire le risorse

Quando hai finito, elimina tutte le risorse di cui non hai più bisogno. Rimuovi l'istanza di livello AI Gateway, le implementazioni di test provider e le chiavi di accesso runtime che hai creato solo per la valutazione.

Passaggi successivi

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-08-04