Guida introduttiva rapida: Crea un AI Gateway

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

AI Gateway offre alle tue applicazioni un punto di ingresso centrale per i modelli di IA, così puoi gestire l'accesso senza dover configurare ogni applicazione per collegarsi direttamente a un fornitore di modelli.

Questo articolo ti guida nella creazione di un AI Gateway, nell'aggiunta del tuo primo modello da Microsoft Foundry e nell'invio di una richiesta attraverso il gateway.

Prerequisites

  • Un abbonamento Azure con il ruolo Contributor assegnato a te nell'ambito dell'abbonamento o nel gruppo di risorse dove crei il gateway. Creare un nuovo gruppo di risorse richiede l'accesso a livello di abbonamento.
  • Il provider di risorse Microsoft.ApiManagement registrato nella sottoscrizione. Se non è registrato, segui Registra un fornitore di risorse o chiedi a un amministratore della sottoscrizione di registrarlo.
  • Un account di Microsoft Foundry con almeno un modello distribuito che supporta Chat Completions e un endpoint backend accessibile pubblicamente.
  • Sono necessari i ruoli Lettore e Amministratore accessi utente nell'account Foundry, o un accesso ereditato equivalente, per scoprire le distribuzioni e concedere l'accesso all'identità del gateway.
  • Un terminale con curl per la richiesta dell'applicazione.

Questo esempio utilizza un account Foundry denominato ai-foundry-demo-learn con una distribuzione gpt-6.1-sol. Il gateway utilizza la sua identità gestita assegnata al sistema per connettersi a Foundry, e tu usi una chiave API runtime del gateway per inviare richieste.

Crea il gateway

Crea un gateway nel tuo abbonamento per fornire un punto di ingresso gestito per il traffico AI.

  1. Apri il portale AI Gateway e accedi.

  2. Su tutti i gateway, seleziona Crea gateway.

  3. Inserisci un nome e scegli il tuo Abbonamento.

  4. In Gruppo di risorse, scegliere Nuovo e immettere un nome per il gruppo di risorse oppure scegliere Esistente e selezionare un gruppo di risorse esistente.

  5. Scegli una Regione supportata visualizzata nel portale.

  6. Espandere Avanzato per esaminare la configurazione di identità gestita e rete. Per questo avvio rapido, lascia selezionato Abilita l'identità gestita assegnata al sistema, imposta l'accesso alla rete pubblica su Abilitato e Rete su Instradamento pubblico. Per altri scenari di rete, consulta la documentazione integrata nel prodotto.

    Screenshot della creazione di gateway con identità gestita assegnata al sistema abilitata, accesso pubblico alla rete abilitato e routing pubblico selezionato.

  7. Seleziona Crea gateway.

  8. Aspetta che la creazione e l'attivazione si completino, poi seleziona il gateway pronto.

Importante

Le impostazioni di rete sono di sola lettura dopo la creazione. Questo quickstart utilizza il routing backend pubblico; pianificare il networking prima di creare gateway per backend privati.

Importa un modello

Aggiungi il tuo primo modello così potrai inviare richieste attraverso il gateway. L'importazione registra le distribuzioni esistenti di Foundry senza dover distribuire nuovi modelli. Crea anche alias che le tue applicazioni usano per chiamare i modelli.

Per importare i modelli di Foundry di esempio:

  1. Seleziona Modelli, poi seleziona Aggiungi>Modelli da Microsoft Foundry.

  2. Sotto Informazioni di base, seleziona la voce Abbonamenti che contiene il tuo account Foundry.

  3. In Modelli, selezionare l'account Foundry, come ai-foundry-demo-learn. La selezione include le distribuzioni supportate dall'account, non una distribuzione individuale.

  4. Imposta il metodo di Autenticazione su Identità Gestita e seleziona Identità gestita assegnata al Sistema sotto Identità Gestita. Il portale concede l'identità gateway Foundry User sull'account selezionato.

  5. In Alias, lascia selezionato Crea un alias per ciascun modello.

    Screenshot dell'account Foundry selezionato e delle distribuzioni con identità gestita assegnata dal sistema e creazione automatica di alias abilitata.

  6. Seleziona Aggiungi modelli e rivedi i risultati dell'importazione.

Le distribuzioni importate appaiono in Modelli>Modelli di back-end, con alias richiamabili come ai-foundry-demo-learn/gpt-6-1-sol. Per le opzioni di autenticazione e la sincronizzazione, consulta la documentazione interna al prodotto.

Crea una chiave API di runtime

Creare la credenziale da usare sia per il playground sia per la richiesta del terminale. Questa chiave consente di autenticarsi al gateway. L'identità gestita autentica il gateway in Foundry.

Per creare una chiave API runtime:

  1. Selezionare Accesso>Chiavi.
  2. Selezionare Crea chiave API.
  3. Inserisci un nome descrittivo, come demo-app, in nome della chiave, poi seleziona Crea.
  4. Nel messaggio Chiave API creata con successo, seleziona Copia e chiudi per copiare la chiave API e chiudere la finestra di dialogo. Memorizza il valore in modo sicuro per la richiesta del terminale.

Warning

Una chiave API runtime concede accesso a tutto il gateway, non solo al modello in questo quickstart. Conservarla in modo sicuro, non sottoporla a commit nel controllo del codice sorgente ed eliminarla al termine.

Per il recupero, la rotazione e la revoca delle chiavi, consulta la documentazione in prodotto.

Testare il modello

Invia un prompt attraverso il gateway per controllare la prima risposta del modello.

Per testare il modello importato:

  1. Nei Modelli, seleziona Modelli Backend, apri il modello con capacità di chat, come gpt-6.1-sol, e seleziona Alias. Nota il nome della callable, come ai-foundry-demo-learn/gpt-6-1-sol.
  2. Apri il Catalogo e seleziona quell'alias.
  3. Seleziona l'endpoint Chat completions.
  4. In Autenticazione, seleziona la chiave che hai creato, come demo-app, sotto la chiave API.
  5. Inserisci un breve prompt, come Give me three uses for an AI gateway, e seleziona Invia.

Una risposta del modello conferma che la credenziale gateway, l'alias chiamabile e la connessione backend lavorano insieme per questo endpoint.

Per altre opzioni di playground, consulta la documentazione integrata nel prodotto.

Invoca il modello dal tuo terminale

In Modelli>Modelli di back-end, aprire il modello e selezionare Panoramica. Copia l'endpoint completo Chat completions. Ad esempio, l'URL potrebbe essere https://my-awesome-gateway.eastus2-01.ai.gateway.azure.com/default/models/openai/v1/chat/completions. Usa l'URL mostrato per il tuo gateway invece di costruirlo dal nome del gateway.

Screenshot della panoramica del modello importato con l'endpoint di completamento della Chat e il controllo copia evidenziati.

Imposta l'endpoint e la chiave API nella sessione del terminale. Sostituisci l'URL di esempio con il tuo endpoint copiato e il segnaposto chiave con il valore che hai memorizzato:

export AI_GATEWAY_CHAT_URL="https://my-awesome-gateway.eastus2-01.ai.gateway.azure.com/default/models/openai/v1/chat/completions"
export AI_GATEWAY_API_KEY="<gateway-runtime-api-key>"

Invia una richiesta con l'alias che hai testato. Sostituire ai-foundry-demo-learn/gpt-6-1-sol con il nome della chiamata del modello se è diverso:

curl --fail-with-body "$AI_GATEWAY_CHAT_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -d '{
    "model": "ai-foundry-demo-learn/gpt-6-1-sol",
    "messages": [
      {"role": "user", "content": "Give me three uses for an AI gateway."}
    ]
  }'

La risposta dovrebbe contenere la risposta del modello nella struttura di risposta Chat Completions. Ora è stato chiamato il modello Foundry tramite il gateway invece di collegare direttamente l'applicazione all'account Foundry.

Pulire le risorse

Per rimuovere le risorse che hai creato per questo quickstart quando non ne hai più bisogno:

  1. Elimina la chiave API di runtime in Accesso>Chiavi.
  2. Torna a Tutti i gateway, trova il gateway che hai creato e seleziona Elimina. Rivedi e conferma la cancellazione.
  3. Rivedi il gruppo di risorse che hai creato e rimuovilo se è vuoto e non serve più.

Mantenere l'account Foundry esistente e le distribuzioni. Tieni qualsiasi gruppo di risorse preesistente. Elimina solo un gruppo di risorse che hai creato per questo quickstart.

Passaggi successivi

Scopri di più sull'AI Gateway.