Governa e proteggi gli asset nel livello AI Gateway (anteprima)

SI APPLICA A: livello gateway di IA (anteprima)

Usa AI Gateway tier (anteprima) per mettere i controlli comuni davanti ai modelli AI, alle risorse di Microsoft Foundry, alle implementazioni Azure OpenAI e ai server MCP. I team della piattaforma possono applicare impostazioni di governance, sicurezza e monitoraggio in un unico luogo mentre i team applicativi continuano a utilizzare le risorse di cui hanno bisogno. Per collegare il gateway a backend e client privati, vedi Configura rete privata.

Il livello del gateway di IA è in anteprima. Usalo per piloti e validazioni in stile produzione. Caratteristiche, regioni, limiti, campi di telemetria e flussi di configurazione possono cambiare prima della disponibilità generale. L'anteprima supporta il provisioning rapido, ma l'affidabilità è garantita solo nei limiti del possibile. Monitorare gli errori e mantenere un percorso di rollback per le applicazioni critiche.

Prerequisiti

• Un'istanza di livello gateway di IA.
• Autorizzazione a gestire l'istanza di livello AI Gateway.
• Accesso al modello di provider o al backend che intendi gestire.
• Per l'autenticazione back-end con identità gestita, l'autorizzazione ad assegnare il ruolo richiesto alla risorsa back-end.
• Accesso a una destinazione di telemetria, come Application Insights o un altro endpoint compatibile con OpenTelemetry (OTLP).

Criteri di governance

Le politiche di governance proteggono il traffico IA prima che le richieste raggiungano modelli o strumenti backend. In anteprima, si configurano le policy come schede visive nel portale; nell'API del piano di controllo, ogni policy è un oggetto JSON strutturato. Selezioni un tipo di policy, scegli a quali modelli o strumenti si applica, compili i campi validati e selezioni Crea. Non è necessario scrivere XML, incollare frammenti di policy o usare espressioni di policy. Poiché le policy sono oggetti strutturati, puoi auditarle o applicarle su una flotta di gateway con Criteri di Azure.

Applichi ogni policy ai modelli o agli strumenti che scegli. Per impostare un controllo di base come la sicurezza dei contenuti, seleziona tutte le risorse applicabili. Applicare politiche più restrittive quando un modello o uno strumento ha diversi rischi, capacità o requisiti di rete.

Quando più policy si applicano a una richiesta, il gateway le valuta tutte prima di inoltrare la richiesta al backend. Se una policy blocca la richiesta, il gateway si ferma e restituisce un errore senza chiamare il backend:

Quando si applicano sia un limite di token che un limite di richiesta, una richiesta deve soddisfare entrambi.

Non tutte le polizze si applicano a ogni tipo di asset. La sicurezza dei contenuti, il filtro IP e i limiti di frequenza delle richieste si applicano sia ai modelli che agli strumenti MCP. I limiti di tasso dei token si applicano ai modelli.

Il diagramma seguente mostra dove si applicano le politiche di governance nel flusso delle richieste.

Per configurare un criterio:

1. Nel portale AI Gateway a livelli, seleziona Politiche>Aggiungi politica.
2. Su Type, scegli ogni policy (guardrail) che vuoi aggiungere, come Sicurezza dei contenuti, filtro IP, limite di velocità Token o limite di frequenza Richiesta.
3. Su Asset, seleziona i modelli o gli strumenti a cui si applica la policy. Per una base di base a livello gateway, seleziona tutti gli asset applicabili.
4. Su Configura, inserisci o scegli i valori dei campi validati, poi seleziona Crea.

Inizia con questi tipi di polizze:

• Sicurezza dei contenuti: Ispeziona i prompt in arrivo e gli input degli strumenti con Sicurezza dei contenuti di Azure AI prima che arrivino al backend. Stabilisci soglie di gravità per categoria (odio, sessuale, violenza, autolesionismo) e scegli 4 o 8 livelli di gravità per un controllo più preciso. Attiva gli Shield di Prompt per rilevare tentativi di jailbreak e di inserzione di prompt, e aggiungi liste di blocco per rifiutare parole chiave o frasi specifiche (ad esempio, nomi di concorrenti o termini bannati). Scegliere se bloccare, registrare o entrambi; una chiamata bloccata restituisce un errore al client. La sicurezza dei contenuti richiede una risorsa Sicurezza dei contenuti di Azure AI, che selezioni come backend della policy nel passaggio Configura. Per calibrare senza rifiutare il traffico legittimo, inizia in modalità di sola registrazione, regola le soglie in base al traffico reale e poi passa al blocco. Vale per modelli e strumenti MCP.
• Filtro IP: Limitare le chiamate in tempo reale agli intervalli di rete client approvati tramite IPv4 o IPv6 CIDR (liste di permesso o rifiuto). Applicalo globalmente per applicazioni private, o su un modello o strumento specifico che necessita di un confine più stretto. Combinalo con le chiavi di accesso runtime per la difesa in profondità: la chiave autentica il chiamante e l'intervallo IP impone un confine di rete. Vale per modelli e strumenti MCP.
• Limiti di velocità dei token: limitano il throughput dei token (prompt e completamento) per minuto, ora o giorno. Nel passaggio Configura, imposta la quota di token e scegli la dimensione contro cui il limite viene conteggiato — identità del chiamante o indirizzo IP del chiamante. Il gateway restituisce le intestazioni di risposta remaining-tokens e consumed-tokens (e remaining-quota-tokens per periodi di un'ora o più lunghi) in modo che le applicazioni client possano limitare autonomamente la frequenza delle richieste prima di essere bloccate. Usa i limiti di token per proteggere la capacità del modello e attenuare i picchi. Vale per i modelli.
• Limiti di frequenza di richiesta: Limitare il volume delle chiamate su una finestra configurabile (ad esempio, 30 secondi, 1 minuto, 2 minuti o 5 minuti), contati per identificazione del chiamante o indirizzo IP del chiamante. Usali per strumenti che chiamano API SaaS o sistemi interni con quote rigorose. Vale per modelli e strumenti MCP.

Criteri a livelli per una configurazione di base e sostituzioni mirate

Ottenete il massimo dalla governance combinando una base di riferimento ampia con eccezioni più specifiche:

• Imposta una configurazione di base per l'intero gateway. Applica la sicurezza dei contenuti e un filtro IP a tutti gli asset applicabili in modo che ogni modello e strumento erediti la stessa protezione.
• Aggiungi sovrascritture mirate. Applicare un limite di tasso di token a modelli ad alto costo o a capacità vincolata, e un limite di tasso di richiesta più rigido a uno strumento specifico che chiama un'API downstream a velocità limitata.
• Controlli dei costi dello stack. Applicare sia un limite di token che un limite di richiesta allo stesso modello quando è necessario proteggere la capacità del modello e i sistemi a valle; una richiesta deve soddisfare entrambi.
• Ambito per identità. Emetti una chiave di accesso separata per ogni applicazione, poi conterai i limiti di velocità per identità del chiamante così ogni applicazione ha il proprio budget e puoi attribuire l'utilizzo.

Le politiche di governance sono controlli operativi. I limiti dei token aiutano a ridurre i picchi e a fornire segnali di utilizzo. Per la rendicontazione finanziaria, usa la fatturazione del provider o Gestione costi di Azure.

Sicurezza e identità

Utilizza le capacità di sicurezza nel livello gateway AI per controllare l'accesso e proteggere le risorse.

Chiavi di accesso runtime

Le chiavi di accesso runtime permettono alle applicazioni client di chiamare asset esposti dal livello AI Gateway senza ricevere credenziali backend. Le applicazioni client si autenticano al gateway con le chiavi di accesso runtime. Un client invia una chiave di accesso runtime al gateway nell'header api-key . Il gateway valida la chiave, applica politiche di governance e si autentica al backend utilizzando la chiave API configurata, la configurazione OAuth per gli strumenti o l'identità gestita. Usa le chiavi di accesso runtime per applicazioni per agenti, framework di valutazione, strumenti per sviluppatori e automazioni che chiamano server MCP, strumenti MCP generati da OpenAPI, risorse del modello o altre risorse del gateway.

Il gateway genera una chiave di accesso in fase di esecuzione, la assegna a un titolare e ne effettua la rotazione o la revoca secondo necessità. In anteprima, ogni chiave è limitata al gateway: consente l'accesso a tutti i modelli e gli strumenti pubblicati nel gateway e la definizione dell'ambito per singola risorsa non è ancora disponibile. Crea chiavi separate per applicazione e ambiente così puoi ruotarle e auditarle in modo indipendente.

Per creare una chiave di accesso runtime:

1. Nel portale di livelli del Gateway IA, seleziona Chiavi.
2. Selezionare Crea chiave API.
3. Inserisci un nome di scuderia e identifica il proprietario.
4. Fare clic su Crea.
5. Copia il valore per l'uso nella tua applicazione. Puoi visualizzare di nuovo la chiave più avanti nella pagina Chiavi .

Le applicazioni client includono la chiave di accesso runtime nell'intestazione api-key (header). Non incollare le chiavi di accesso runtime nel codice sorgente, nei log di build, nei notebook o nelle chat condividete. Conservali nell'archivio dei segreti della tua piattaforma di distribuzione o in un altro gestore di segreti approvato. Usa una chiave per ogni applicazione e ambiente. Ruota le chiavi regolarmente e ogni volta che la proprietà cambia. Se una chiave può essere esposta, ruotarla o revocarla immediatamente e controllare i log del gateway.

Usa l'identità gestita per l'autenticazione backend

Configura l'identità gestita affinché il tier AI Gateway possa autenticarsi ai backend supportati per modelli e server MCP senza memorizzare chiavi API. L'uso dell'identità gestita per accedere a modelli e server MCP è disponibile in anteprima pubblica. Preferisci l'identità gestita dove supportato perché riduce la gestione delle chiavi nel backend. Elimina la rotazione delle chiavi dalla configurazione del gateway e ti permette di gestire l'accesso con Azure RBAC. Il livello AI Gateway supporta identità gestite assegnate al sistema e all'utente. Gestiscili nella pagina Identità gestite del portale del livello AI Gateway.

Scegli identità assegnate al sistema o all'utente in base alle tue esigenze. Un'identità assegnata al sistema è legata al ciclo di vita del gateway ed è semplice quando un singolo gateway necessita di accesso backend. Le identità assegnate dall'utente ti danno un controllo più stretto: puoi condividere un'identità tra i gateway, oppure associare identità separate per backend diversi invece di usare un'identità unica per ogni backend. Usa una chiave API quando un fornitore non supporta l'identità gestita.

Prima di configurare l'autenticazione backend, assicurati di avere questi elementi:

• Un'istanza di livello gateway di IA.
• Una risorsa Microsoft Foundry o Azure OpenAI che ospita la distribuzione del modello.
• Permesso di aggiornare le impostazioni dell'identità del gateway.
• Permesso di assegnare ruoli Azure RBAC alla risorsa backend.
• interfaccia della riga di comando di Azure 2.57.0 o successiva.

Per abilitare un'identità assegnata al sistema, apri la pagina Identità gestite nel portale AI Gateway a livelli. Su Configura identità, attiva l'identità assegnata al Sistema e poi copia il suo ID Oggetto (principale).

Per abilitare un’identità assegnata dall'utente, creare l'identità nello stesso tenant del gateway e della risorsa back-end. Nella pagina Identità gestite, seleziona Assegnata dall'utente>Aggiungi identità e sceglila. Copia l'ID client e l'ID oggetto (principale) dell'identità gestita. Il gateway utilizza l'ID client per richiedere un token. Azure RBAC utilizza l'ID principale.

Concedere all'identità del gateway l'accesso a ogni risorsa back-end con l'ambito più ristretto possibile. Nella maggior parte dei casi, usa la singola risorsa OpenAI di Foundry o Azure.

Usa il seguente estratto di interfaccia della riga di comando di Azure. Sostituire i segnaposto con i tuoi valori. Fai riferimento al ruolo con il suo ID invece che con il nome.

Raccogli questi valori:

• GATEWAY_PRINCIPAL_ID: l'ID oggetto (principale) dell'identità gestita del gateway.
• BACKEND_RESOURCE_ID: l'ID completo della risorsa Azure di Microsoft Foundry o della risorsa Azure OpenAI, nel formato /subscriptions/....

GATEWAY_PRINCIPAL_ID="<gateway-managed-identity-principal-id>"
BACKEND_RESOURCE_ID="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<foundry-or-aoai-resource-name>"

az role assignment create \
  --assignee-object-id "$GATEWAY_PRINCIPAL_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
  --scope "$BACKEND_RESOURCE_ID"

Le assegnazioni dei ruoli possono richiedere diversi minuti per essere propagate. Conferma l'incarico:

az role assignment list \
  --assignee-object-id "$GATEWAY_PRINCIPAL_ID" \
  --scope "$BACKEND_RESOURCE_ID" \
  --output table

Quando importi un modello, scegli l'identità gestita come metodo di autenticazione backend. Nella procedura guidata Aggiungi modelli, seleziona Importa da Foundry e scegli la sottoscrizione, la risorsa e la distribuzione del modello. Nei dettagli del Provider, seleziona Identità gestita, poi scegli l'identità assegnata dal sistema o un'identità assegnata dall'utente collegata al gateway. I client che chiamano il gateway non hanno bisogno delle chiavi backend.

Se le chiamate falliscono con errori 401, conferma che l'importazione utilizza l'identità gestita e che il backend accetta l'autenticazione Entra ID. Se le chiamate falliscono con errori 403, confermare che l'ID entità dell'identità abbia il ruolo Utente Foundry nell'ambito della risorsa back-end e attendere la propagazione dell'assegnazione dei ruoli.

Monitoring

Il livello AI Gateway emette una metrica di utilizzo del token OpenTelemetry per il traffico del modello. Scegli dove va: invia la metrica ad applicazione Azure Insights o a un'altra destinazione compatibile OpenTelemetry (OTLP), come Datadog, Splunk o Grafana Cloud. Quando si utilizza Application Insights, il portale fornisce una dashboard integrata per il consumo dei token.

Il monitoraggio del traffico degli strumenti MCP (volume di richieste, latenza ed errori) è disponibile nelle viste di monitoraggio del portale quando si collega Application Insights. L'esportazione di OpenTelemetry (OTLP) attualmente copre solo la metrica di utilizzo dei token del modello, non il traffico dello strumento MCP.

La metrica di utilizzo del token è una metrica personalizzata di OpenTelemetry che contiene un sottoinsieme degli attributi OpenTelemetry Generative AI e della convenzione semantica cloud — ad esempio, il nome del modello. Non tutti i backend riportano il conteggio dei token; alcuni fornitori non lo includono nelle risposte in streaming o di passthrough. Considera i dati dei token mancanti come non disponibili, non come zero.

La metrica di utilizzo del token include attributi quali:

Configura una destinazione di telemetria nelle impostazioni di monitoraggio del gateway. Per le Analisi delle Applicazioni, seleziona la risorsa nel tuo abbonamento. Per un endpoint OpenTelemetry (OTLP) generico, fornisci l'URL del collector e gli eventuali token di accesso o header richiesti. Usa Datadog, Splunk, Grafana Cloud o un collector generico OTLP quando queste piattaforme sono le tue piattaforme operative standard. Proteggi le credenziali di destinazione come dati sensibili e monitora gli errori di esportazione dei dati di telemetria.

Quando invii la metrica di utilizzo del token ad Application Insights, il portale fornisce una dashboard integrata per il consumo dei token. Interroghi la metrica dei token con PromQL, sia che venga inviata ad Application Insights sia a un'altra destinazione di metriche OTLP. Ad esempio, questa query PromQL somma l'utilizzo dei token per modello:

sum by (gen_ai_request_model) (gen_ai_client_token_usage)

Poiché la metrica porta gli attributi della convenzione semantica, puoi segmentare il consumo senza configurazioni aggiuntive. Ad esempio, raggruppa per gen_ai_operation_name per confrontare il traffico di chat e responses, oppure per gen_ai_token_type per separare i token di prompt e di completamento:

sum by (gen_ai_request_model, gen_ai_token_type) (gen_ai_client_token_usage)

Usa l'uso di modelli e token per le stime di consumo, poi riconcilia con la fatturazione dei fornitori o con le esportazioni di Gestione costi di Azure per la rendicontazione finanziaria.

Invia un'intestazione x-correlation-id per le indagini a livello applicativo. Non inserire dati personali, segreti, prompt o identificatori regolamentati nelle intestazioni di correlazione.

Inizia con avvisi su cui puoi agire, come picchi di utilizzo dei token, fallimenti nell'autenticazione backend e fallimenti nell'esportazione della telemetria. Instradare ogni avviso a un proprietario che possa indagare il gateway, il backend, la policy o la configurazione di destinazione.

Contenuti correlati

• Panoramica dei livelli dell'AI Gateway
• Avvio rapido: creare un'istanza di livello gateway di IA
• Gestire modelli e strumenti
• Configurare la rete privata