Scegliere un endpoint e un SDK

7 minuti

Microsoft Foundry offre flessibilità per lo sviluppo di applicazioni di chat di intelligenza artificiale generative. Prima di iniziare lo sviluppo, è importante comprendere le opzioni disponibili e come decidere quale di esse usare. Alcune considerazioni per lo sviluppo di un'applicazione includono:

Endpoint: i progetti Microsoft Foundry forniscono due endpoint che è possibile usare per connettersi e utilizzare asset di progetto, ad esempio distribuzioni di modelli, dalle applicazioni client. Ogni progetto ha sia un endpoint del progetto che un endpoint di Azure OpenAI.
Client SDK: a seconda dell'endpoint selezionato, è possibile scegliere di usare Microsoft Foundry SDK o OpenAI SDK per sviluppare un'applicazione di chat di intelligenza artificiale generativa. Entrambi gli SDK supportano un oggetto client compatibile con l'API OpenAI che può inviare richieste ai modelli, ma esistono alcune differenze nelle funzionalità specifiche disponibili in ogni SDK.
Autenticazione: a seconda dell'endpoint e dell'SDK che si sceglie di usare, esistono diversi modi in cui un'applicazione client può essere autenticata da Foundry per poter accedere agli asset. In generale, le applicazioni di produzione devono usare l'autenticazione con ID Entra Di Microsoft , che richiede che l'applicazione sia in esecuzione nel contesto di un'identità specifica; ma in alcuni scenari è anche possibile usare l'autenticazione basata su chiave o basata su token .
API Chat: l'API client OpenAI supporta due API di chat: ChatCompletions e Risposte. Anche se l'API Risposte è consigliata per la maggior parte dei nuovi progetti di sviluppo, l'API ChatCompletions è ben consolidata e compatibile in molti modelli e piattaforme di intelligenza artificiale generativi.

Si esamineranno ora gli endpoint, gli SDK client e i metodi di autenticazione disponibili. Le API Risposte e ChatCompletions verranno esaminate in un secondo momento.

Uso di Foundry SDK con l'endpoint del progetto

Microsoft Foundry SDK fornisce l'accesso a livello di codice alle risorse nei progetti tramite un'API REST e librerie client specifiche del linguaggio; Compreso:

Annotazioni

Questo modulo usa esempi di codice Python per le attività comuni. È possibile fare riferimento alla documentazione dell'SDK specifica del linguaggio per il codice equivalente nel linguaggio preferito. Ogni SDK viene sviluppato e gestito in modo indipendente, quindi alcune funzionalità possono trovarsi in fasi diverse dell'implementazione.

Installazione dell'SDK

Per usare la libreria Azure ai Projects in Python, installare il pacchetto azure-ai-projects da PyPI insieme ai pacchetti di supporto:

pip install azure-ai-projects azure-identity openai

Annotazioni

Quando si usa Foundry SDK per sviluppare un'applicazione chat, è anche necessario importare il pacchetto OpenAI SDK. La funzionalità client di chat in Foundry SDK è derivata da OpenAI SDK.

Connessione all'endpoint del progetto

Ogni progetto Foundry ha un endpoint univoco disponibile nella pagina Overview del progetto nel portale Foundry in https://ai.azure.com.

L'endpoint del progetto ha il seguente formato:

https://{resource-name}.services.ai.azure.com/api/projects/<project-name>

Usare questo endpoint per creare un oggetto AIProjectClient :

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

project_endpoint = "https://{resource-name}.services.ai.azure.com/api/projects/<project-name>"
project_client = AIProjectClient(
    credential=DefaultAzureCredential(),
    endpoint=project_endpoint
)

Annotazioni

Il codice usa le credenziali predefinite Azure per l'autenticazione. Per abilitare questa autenticazione, è necessario installare il pacchetto azure-identity (illustrato in precedenza nel comando di installazione).

Suggerimento

Per accedere al progetto correttamente, il codice deve essere eseguito in una sessione di Azure autenticata. Ad esempio, è possibile usare il comando Azure CLI az login per accedere prima di eseguire il codice.

Il client di progetto (AIProjectClient) fornisce l'accesso alle operazioni native di Foundry che non hanno equivalenti OpenAI. Usare il client project per:

Recuperare le connessioni alle risorse
Accedere alla configurazione del progetto
Abilitare il tracciamento
Gestire set di dati e indici

Creazione di un client di chat

Per chattare con un modello nel progetto Foundry, è necessario un oggetto client compatibile con OpenAI. È possibile usare il metodo get_openai_client() del client del progetto per ottenerlo, come illustrato di seguito:

openai_client = project_client.get_openai_client(api_version="2024-10-21")

È quindi possibile usare questo oggetto client di chat per inviare richieste ai modelli e restituire risposte.

Uso di OpenAI SDK con l'endpoint OpenAI di Azure

OpenAI SDK è la libreria client ufficiale per chiamare l'API OpenAI. Gestisce le richieste HTTP, l'autenticazione, i tentativi e l'analisi delle risposte. L'SDK funziona con modelli ospitati in OpenAI, distribuzioni OpenAI di Azure e modelli Foundry usando gli stessi modelli.

Installazione dell'SDK

Per usare la libreria OpenAI in Python, installare il pacchetto openai da PyPI insieme ai pacchetti di supporto:

pip install openai azure-identity

Annotazioni

Il pacchetto azure-identity è necessario se si intende usare l'autenticazione basata su token per connettersi all'endpoint usando le credenziali microsoft Entra ID.

Connessione all'endpoint OpenAI di Azure

Ogni progetto Foundry include un endpoint OpenAI di Azure che è possibile trovare nella pagina Panoramica del progetto nel portale foundry all'indirizzo https://ai.azure.com.

L'endpoint OpenAI di Azure segue questo formato:

https://{resource-name}.openai.azure.com/openai/v1

Creare un client OpenAI con l'endpoint e le credenziali di Azure:

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

openai_client = OpenAI(  
  base_url = "https://{resource-name}.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

Oltre a Microsoft Entra ID (scelta consigliata), è possibile eseguire l'autenticazione usando una chiave API o variabili di ambiente.

Autenticazione con chiave API:

import os
from openai import OpenAI

openai_client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://{resource-name}.openai.azure.com/openai/v1/"
)

Importante

Utilizzare le chiavi API con cautela. Archiviarli in modo sicuro in Azure Key Vault e non includerli mai direttamente nel codice.

Variabili di ambiente:

Se si impostano OPENAI_BASE_URL e OPENAI_API_KEY le variabili di ambiente, il client li usa automaticamente:

from openai import OpenAI

openai_client = OpenAI()  # Uses environment variables

Indipendentemente dal modo in cui si sceglie di eseguire l'autenticazione, il client OpenAI gestisce le operazioni di inferenza del modello. Usarlo per:

Generazione di risposte con l'API Risposte
Completamento della chat e generazione di immagini
Accesso ai modelli diretti Foundry (modelli OpenAI non di Azure)

Uso di un oggetto client AzureOpenAI

È in genere consigliabile usare l'oggetto client OpenAI per chattare con i modelli tramite l'endpoint OpenAI v1 di Azure. Tuttavia, è anche possibile creare un oggetto client AzureOpenAI se è necessario usare le funzionalità di una versione specifica dell'API OpenAI di Azure. Per creare un oggetto client AzureOpenAI , è necessario specificare la versione dell'API e l'endpoint di Azure, come illustrato di seguito:

import os
from openai import AzureOpenAI
    
openai_client = AzureOpenAI(
    azure_endpoint = "https://{resource-name}.openai.azure.com"
    api_key=os.getenv("AZURE_OPENAI_KEY"),  
    api_version="2024-10-21",
)

Scelta tra Foundry SDK e OpenAI SDK

Microsoft Foundry supporta due approcci per la creazione di applicazioni di intelligenza artificiale. Ognuno ha scopi diversi e comprende quando usarlo consente di creare la soluzione corretta.

Quando usare Foundry SDK

Usare Foundry SDK quando l'applicazione necessita di funzionalità specifiche di Foundry:

Servizio Agente Fonderia per la creazione e la gestione di agenti IA
Flussi di lavoro di chiamata e approvazione dello strumento
Valutazioni cloud per il test e la convalida delle risposte di intelligenza artificiale
Traccia e osservabilità per il monitoraggio del comportamento dell'applicazione
Modelli diretti Foundry (modelli OpenAI non Azure disponibili tramite il catalogo modelli)
Funzionalità di governance, connessioni e metadati del progetto

Microsoft consiglia Foundry SDK per la creazione di app con agenti, valutazioni o funzionalità specifiche di Foundry.

Quando usare OpenAI SDK

Usare OpenAI SDK quando è necessaria la massima compatibilità con l'API OpenAI:

Compatibilità completa dell'API OpenAI per il codice e gli strumenti esistenti
Portabilità tra le distribuzioni OpenAI e Azure OpenAI
Completamento della chat, risposte e immagini Api
Dipendenza minima dai concetti specifici di Foundry

OpenAI SDK è ideale per i carichi di lavoro di inferenza del modello in cui si vuole che il codice OpenAI esistente funzioni con modifiche minime. Tuttavia, questo approccio non fornisce funzionalità specifiche di Foundry, ad esempio agenti o valutazioni.

Microsoft Foundry offre flessibilità nella creazione di applicazioni di intelligenza artificiale. Usare Foundry SDK con AIProjectClient quando sono necessarie funzionalità a livello di progetto, ad esempio agenti, valutazioni, traccia e connessioni. Usare OpenAI SDK quando è necessaria un'inferenza semplice del modello con la massima compatibilità OpenAI. Entrambi gli SDK funzionano con l'endpoint del progetto Foundry, quindi è possibile combinarli in base alle esigenze nelle applicazioni. È anche possibile usare entrambi gli SDK nella stessa applicazione, ovvero Foundry SDK per le funzionalità del progetto e OpenAI SDK per l'inferenza del modello.

Commenti e suggerimenti

Questa pagina è stata utile?