Importare un'API OpenAI di Azure

2025-05-20

SI APPLICA A: tutti i livelli di Gestione API

È possibile importare gli endpoint del modello di intelligenza artificiale distribuiti nel servizio OpenAI di Azure nell'istanza di Gestione API come API REST. Usare i criteri del gateway di intelligenza artificiale e altre funzionalità in Gestione API per semplificare l'integrazione, migliorare l'osservabilità e migliorare il controllo sugli endpoint del modello.

Questo articolo illustra due opzioni per importare un'API OpenAI di Azure in un'istanza di Gestione API di Azure come API REST:

Importare un'API OpenAI di Azure direttamente dal servizio OpenAI di Azure (scelta consigliata)
Scaricare e aggiungere la specifica OpenAPI per OpenAI di Azure e inserirla in Gestione API come API OpenAPI.

Altre informazioni sulla gestione delle API di intelligenza artificiale in Gestione API:

Funzionalità del gateway di intelligenza artificiale in Gestione API di Azure

Prerequisiti

Un'istanza di API Management esistente. Crearne una se non è già stato fatto.
Una risorsa OpenAI di Azure con un modello distribuito. Per altre informazioni sulla distribuzione di modelli nel servizio Azure OpenAI, vedere la guida alla distribuzione delle risorse.

Prendere nota dell'ID (nome) della distribuzione. Sarà necessario quando si testa l'API importata in Gestione API.

Nota

I criteri di Gestione API, ad esempio azure-openai-token-limit e azure-openai-emit-token-metric , sono supportati per determinati endpoint API esposti tramite modelli specifici del servizio Azure OpenAI. Per altre informazioni, vedere Modelli di servizio OpenAI di Azure supportati.
Autorizzazioni per concedere l'accesso alla risorsa OpenAI di Azure dall'istanza di Gestione API.

Opzione 1. Importare l'API dal Servizio OpenAI di Azure

È possibile importare un'API Azure OpenAI direttamente dal Servizio OpenAI di Azure in Gestione API.

Nota

Attualmente, questa funzionalità non è disponibile nelle aree di lavoro.

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

Operazioni per ogni endpoint dell'API REST OpenAI di Azure
Un’identità assegnata dal sistema con le autorizzazioni necessarie per accedere alla risorsa OpenAI di Azure.
Una risorsa back-end e un criterio set-back-end-service che indirizzano le richieste API all'endpoint del servizio OpenAI di Azure.
Autenticazione al back-end OpenAI di Azure usando l'identità gestita assegnata dal sistema dell'istanza.
(facoltativamente) Criteri che consentono di monitorare e gestire l'API OpenAI di Azure.

Per importare un'API OpenAI di Azure in Gestione API:

Nel portale di Azure accedere all'istanza di Gestione API.
Nel menu a sinistra, in API, selezionare >.
In Crea da risorsa di Azure, selezionare Servizio OpenAI di Azure.
Passare alla scheda Nozioni di base:
1. Selezionare la risorsa OpenAI di Azure da importare.
2. Facoltativamente, selezionare una versione dell'API OpenAI di Azure. Se non se ne seleziona una, per impostazione predefinita viene usata la versione più recente dell'API REST pronta per la produzione. Prendere nota della versione selezionata. Sarà necessario per testare l'API.
3. Immettere un Nome visualizzato e una Descrizione facoltativa per l'API.
4. In URL di base, aggiungere un percorso usato dall'istanza di Gestione API per accedere agli endpoint dell'API OpenAI di Azure. Se si abilita l'opzione Verifica compatibilità con OpenAI SDK (scelta consigliata), /openai viene aggiunto automaticamente all'URL di base.
  
  Ad esempio, se l'endpoint del gateway di Gestione API è https://contoso.azure-api.net, impostare un URL di base simile a https://contoso.azure-api.net/my-openai-api/openai.
5. Facoltativamente, selezionare uno o più prodotti da associare all'API. Selezionare Avanti.
Nella scheda Criteri abilitare facoltativamente i criteri per monitorare e gestire l'API. È anche possibile impostare o modificare i criteri in un secondo momento.

Se selezionata, immettere le impostazioni o accettare le impostazioni predefinite che definiscono i criteri seguenti (vedere gli articoli collegati per i prerequisiti e i dettagli di configurazione):
Selezionare Rivedi e crea.
Dopo aver convalidato le impostazioni, selezionare Crea.

Opzione 2. Aggiungere una specifica OpenAPI a Gestione API

In alternativa, scaricare manualmente la specifica OpenAPI per l'API REST OpenAI di Azure e aggiungerla a Gestione API come API OpenAPI.

Scaricare la specifica OpenAPI

Scaricare la specifica OpenAPI per l'API REST OpenAI di Azure, ad esempio la versione ga 2024-10-21.

In un editor di testo aprire il file di specifica scaricato.
Nell'elemento servers della specifica, immettere il nome dell'endpoint del Servizio OpenAI di Azure al posto dei valori segnaposto url e l'endpoint default nella specifica. Ad esempio, se l'endpoint del Servizio OpenAI di Azure è contoso.openai.azure.com, aggiornare l'elemento servers con i valori seguenti:
- URL: https://contoso.openai.azure.com/openai
- Endpoint predefinito: contoso.openai.azure.com
```
[...]
"servers": [
    {
      "url": "https://contoso.openai.azure.com/openai",
      "variables": {
        "endpoint": {
          "default": "contoso.openai.azure.com"
        }
      }
    }
  ],
[...]
```
Prendere nota del valore dell'API version nella specifica. Sarà necessario per testare l'API. Esempio: 2024-10-21.

Aggiungere la specifica OpenAPI alla gestione delle API.

Nel portale di Azure accedere all'istanza di Gestione API.
Nel menu a sinistra selezionare API >+ Aggiungi API.
In Definisci una nuova API selezionare OpenAPI. Immettere un Nome visualizzato e un Nome per l’API.
Immettere un suffisso dell'URL API che termina con /openai per accedere agli endpoint dell'API OpenAI di Azure nell'istanza di Gestione API. Esempio: my-openai-api/openai.
Seleziona Crea.

L'API viene importata e visualizza le operazioni della specifica OpenAPI.

Configurare l'autenticazione dell'API OpenAI di Azure

Per eseguire l'autenticazione dell'API OpenAI di Azure, si fornisce una chiave API o un'identità gestita. Se si è importata l'API OpenAI di Azure direttamente nell'istanza di Gestione API, l'autenticazione tramite l'identità gestita dell'istanza di Gestione API viene configurata automaticamente.

Se si è aggiunta l'API OpenAI di Azure dalla specifica OpenAPI, è necessario configurare l'autenticazione. Per altre informazioni sulla configurazione dell'autenticazione tramite i criteri di Gestione API, vedere Autenticare e autorizzare l'API OpenAI di Azure.

Testare l'API OpenAI di Azure

Per assicurarsi che l'API OpenAI di Azure funzioni come previsto, testarla nella console di test di Gestione API. È necessario specificare un ID distribuzione del modello (nome) configurato nella risorsa OpenAI di Azure e nella versione dell'API per testare l'API.

Selezionare l'API creata nel passaggio precedente.
Selezionare la scheda Test.
Selezionare un'operazione compatibile con il modello distribuito nella risorsa OpenAI di Azure. Nella pagina vengono visualizzati i campi per i parametri e le intestazioni.
In Parametri modello, immettere i valori seguenti:
- deployment-id - ID di una distribuzione nel servizio OpenAI di Azure
- api-version - una versione valida dell'API OpenAI di Azure, ad esempio la versione dell'API selezionata durante l'importazione dell'API.
Immettere altri parametri e intestazioni in base alle esigenze. A seconda dell'operazione, potrebbe essere necessario configurare o aggiornare un corpo della richiesta.

Nota

Nella console di test, Gestione API popola automaticamente un'intestazione Ocp-Apim-Subscription-Key e configura la chiave di sottoscrizione della sottoscrizione con accesso completo integrata. Questa chiave consente l'accesso a ogni API nell'istanza di Gestione API. Facoltativamente, visualizzare l'intestazione Ocp-Apim-Subscription-Key selezionando l'icona "occhio" accanto alla richiesta HTTP.
Selezionare Invia.

Quando il test ha esito positivo, il back-end risponde con un codice di risposta HTTP corretto e alcuni dati. I dati sull'utilizzo dei token vengono aggiunti alla risposta per consentire il monitoraggio e la gestione dell'utilizzo di token dell'API Azure OpenAI.

Condividi tramite