Importare un'API OpenAI di Azure

  • Articolo

SI APPLICA A: tutti i livelli di Gestione API

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

Prerequisiti

  • Un'istanza di API Management esistente. Crearne una se non è già stato fatto.

  • Una risorsa OpenAI di Azure con un modello distribuito. Per ulteriori informazioni sulla distribuzione del modello, 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.

  • 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 di Azure OpenAI.
  • Un’identità assegnata dal sistema con le autorizzazioni necessarie per accedere alla risorsa OpenAI di Azure.
  • Una risorsa back-end e un criterio set-backend-service che indirizzano le richieste API all'endpoint del Servizio OpenAI di Azure.
  • Un criterio authentication-managed-identity che può eseguire l'autenticazione per la risorsa OpenAI di Azure usando l'identità assegnata dal sistema dell'istanza.
  • (facoltativamente) Criteri che consentono di monitorare e gestire l'utilizzo dei token tramite l'API OpenAI di Azure.

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

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

  2. Nel menu a sinistra, in API, selezionare API>+ Aggiungi API.

  3. In Crea da risorsa di Azure, selezionare Servizio OpenAI di Azure.

    Screenshot della creazione di un'API dal Servizio OpenAI di Azure nel portale.

  4. 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.

    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.

  5. Nella scheda Criteri, abilitare facoltativamente i criteri per monitorare e gestire l'utilizzo di token API OpenAI di Azure. Se questa opzione è selezionata, immettere le impostazioni o accettare quelle predefinite che definiscono i criteri azure-openai-token-limit e azure-openai-emit-token-metric per l'API. È anche possibile impostare o aggiornare la configurazione dei criteri in un secondo momento. Selezionare Rivedi e crea.

  6. 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 2024-02-01GA.

  1. In un editor di testo aprire il file di specifica scaricato.

  2. Nell'defaultelemento della specifica, sostituire il nome dell'endpoint del Servizio OpenAI di Azure con i valori segnaposto di servers e l’endpoint url 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"
        }
      }
    }
  ],
[...]

  3. Prendere nota del valore dell'API version nella specifica. Sarà necessario per testare l'API. Esempio: 2024-02-01.

Aggiungere la specifica OpenAPI a Gestione API

  1. Nel portale di Azure accedere all'istanza di Gestione API.
  2. Nel menu a sinistra selezionare API >+ Aggiungi API.
  3. In Definisci una nuova API selezionare OpenAPI. Immettere un Nome visualizzato e un Nome per l’API.
  4. 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.
  5. 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. Per testare l'API, è necessario specificare un ID di distribuzione modello (nome) configurato nella risorsa OpenAI di Azure.

  1. Selezionare l'API creata nel passaggio precedente.

  2. Selezionare la scheda Test.

  3. 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.

  4. 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. Screenshot del test di un'API del Servizio OpenAI di Azure nel portale.

  5. 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 all-access 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.

  6. 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 dell'API OpenAI di Azure. Screenshot dei dati sull'utilizzo dei token nella risposta API nel portale.

Criteri di memorizzazione nella cache per le API OpenAI di Azure

Oltre ai criteri azure-openai-token-limit e azure-openai-emit-token-metric che è possibile configurare durante l'importazione di un'API del Servizio OpenAI di Azure, Gestione API fornisce i criteri di memorizzazione nella cache seguenti per ottimizzare le prestazioni e ridurre la latenza per le API OpenAI di Azure:

  • azure-openai-semantic-cache-store
  • azure-openai-semantic-cache-lookup

Contenuto correlato