Creare e gestire un'API modello unificato

SI APPLICA A: Sviluppatore | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

È possibile creare un'API modello unificata in Gestione API di Azure per esporre più back-end LLM tramite un singolo endpoint client. Le applicazioni client usano un formato API noto, l'OpenAI Chat Completions API, mentre API Management traduce automaticamente le richieste per i modelli di back-end usando l'OpenAI Chat Completions API o l'Anthropic Messages API.

Centralizzando l'accesso al modello dietro un singolo livello API, è possibile:

• Standardizzare in un singolo formato API per i client in modo indipendente dai formati usati dai modelli back-end.
• Unifica osservabilità, sicurezza e governance con criteri nei vari provider di modelli.
• Configurare il failover dei modelli tra diversi provider di modelli.
• Disaccoppiare i nomi dei modelli esposti al client dai nomi dei modelli backend tramite alias.

Per saperne di più sulla gestione delle API di intelligenza artificiale in Gestione API, vedere Funzionalità del gateway AI in Gestione API di Azure.

Back-end supportati

L'API del modello unificato supporta i formati di API back-end seguenti:

• API OpenAI per il completamento delle chat
• API Messaggi Anthropic

Prerequisiti

• Un'istanza di API Management esistente. Crearne una se non è già stato fatto.
• Una o più distribuzioni di modelli in un back-end supportato.
• Per tenere traccia dell'utilizzo dei token dall'API, vedere Creare metriche personalizzate per i prerequisiti.
• Per applicare controlli di sicurezza dei contenuti nell'API, vedere Applicare controlli di sicurezza del contenuto alle richieste LLM per i prerequisiti.

Creare un'API modello unificata - portale di Azure

Usare la procedura seguente per creare un'API modello unificata in Gestione API.

Quando si crea l'API, Gestione API configura automaticamente:

• Endpoint /models per l'individuazione dei modelli che elenca tutti i modelli configurati.
• Un singolo endpoint di routing come /llm/v1/chat/completions, che accetta richieste nel formato OpenAI Chat Completions.
• Formattare la logica di conversione per ogni modello back-end aggiunto.
• Risorse back-end che indirizzano le richieste all'endpoint del provider corretto.

Per creare un'API modello unificata:

1. Nel portale di Azure passare all'istanza di Gestione API.

2. Nel menu della barra laterale, in API, selezionare Modelli>+ Aggiungi>API modello unificato.

   

3. Nella scheda Configura API modello unificato :

   1. Immetti un Nome visualizzato per l'API. Gestione API genera automaticamente un nome API basato sul nome visualizzato, ma è possibile modificarlo se necessario.
   2. In Percorso API immettere il percorso usato dai client per chiamare l'API. Il valore predefinito è /llm/v1, che genera un endpoint di completamento della chat in /llm/v1/chat/completions.
   3. Facoltativamente, selezionare uno o più prodotti da associare all'API.
   4. Seleziona Avanti.

4. Nella scheda Configura modelli selezionare + Aggiungi per aprire il riquadro Aggiungi modello e quindi configurare le impostazioni seguenti per ogni distribuzione del modello:

   1. In Configurazione backend:

      • In Modello immettere il nome del modello back-end, ad esempio gpt-4o o claude-sonnet-4.6.
      • Nel formato API selezionare il formato previsto dal modello back-end, ad esempio ApenAI Chat Completions API o Anthropic Messages API.
      • In URL immettere l'URL dell'endpoint back-end, ad esempio una distribuzione del modello in Foundry o, per altri provider, l'URL dell'endpoint API del provider.

   2. In Credenziali di autorizzazione selezionare la modalità di autenticazione di Gestione API nel back-end:

      • Intestazioni: immettere un nome di intestazione (ad esempio, api-key o Authorization) e il valore di intestazione corrispondente (chiave API o segreto).
      • Identità gestita: Per le distribuzioni di modelli in Azure, è possibile usare l'identità gestita assegnata dal sistema dell'istanza o un'identità gestita assegnata dall'utente per autenticarsi al back-end.

      Per una spiegazione delle impostazioni per l'identità gestita, vedere il riferimento per il criterio authentication-managed-identity.

   

5. Nella scheda Gestisci consumo di token configurare facoltativamente i criteri seguenti per monitorare e gestire l'utilizzo dei token:

   • Gestire l'utilizzo dei token
   • Tenere traccia dell'utilizzo dei token

6. Nella scheda Impostare la sicurezza dei contenuti di intelligenza artificiale configurare facoltativamente il servizio Sicurezza dei contenuti di Azure AI per bloccare le richieste con contenuto non sicuro:

   • Applicare controlli di sicurezza del contenuto alle richieste LLM

7. Selezionare Rivedi e crea e quindi Crea.

Gestire gli alias del modello

Gli alias del modello forniscono ai client un nome stabile e indipendente dal provider da usare quando si chiama un modello. Assegnando un alias come gpt o claude-sonnet, si separa il nome del modello per il client dalla distribuzione back-end effettiva. Quando si aggiorna un modello o si vuole eseguire un test A/B, è possibile aggiornare la destinazione alias senza apportare modifiche al codice client.

Aggiornare o aggiungere un alias del modello

Per aggiornare un alias del modello dopo la creazione dell'API del modello unificato:

1. Nel portale di Azure passare all'istanza di Gestione API e quindi selezionare APIs.
2. Selezionare l'API del modello unificato.
3. Selezionare la scheda Modelli per aggiornare o aggiungere un alias del modello.
   • Per aggiornare un alias per il client, selezionare l'alias da aggiornare, quindi aggiornare la configurazione back-end per specificare il modello back-end. Aggiungere le credenziali di autorizzazione per il nuovo back-end.
   • Per aggiungere un nuovo modello, selezionare + Aggiungi e configurare le impostazioni back-end, autorizzazione e client come descritto nella sezione precedente.
4. Seleziona Salva.

Individuare gli alias del modello

Gli sviluppatori possono individuare i modelli disponibili e i relativi alias chiamando l'endpoint dell'API /models del modello unificato. API Management restituisce un elenco di modelli con i relativi alias visibili ai client.

Chiamare l'API da un'applicazione client

Le applicazioni client possono chiamare l'API del modello unificato usando qualsiasi SDK compatibile con OpenAI. Imposta l'URL di base dell'SDK sull'endpoint di API Management e usa una chiave di sottoscrizione di API Management o un altro metodo di autenticazione supportato per autenticarti.

L'esempio seguente usa l'SDK Python OpenAI e passa una chiave di sottoscrizione di Gestione API nell'intestazione per l'autenticazione. Il corpo della richiesta specifica un alias del modello per il client configurato in Gestione API, gpt ad esempio o claude-sonnet.

from openai import OpenAI

client = OpenAI(
    base_url="https://<apim-instance>.azure-api.net/llm/v1",
    api_key="<api-management-subscription-key>",
)

# Specify the client-facing model alias
response = client.chat.completions.create(
    model="gpt",  # or "claude-sonnet", "gemini", or any other configured alias
    messages=[{"role": "user", "content": "What can you do?"}],
)
print(response.choices[0].message.content)

Per passare a un modello back-end diverso, modificare solo il model valore . Non sono necessarie altre modifiche al codice.

Contenuti correlati

• Funzionalità del gateway di intelligenza artificiale in Gestione API di Azure
• Importare un'API Microsoft Foundry
• Gestire l'utilizzo dei token LLM
• Tenere traccia dell'utilizzo dei token
• Applicare controlli di sicurezza del contenuto alle richieste LLM
• Abilitare la memorizzazione nella cache semantica delle risposte
• Back-end in Gestione API di Azure