Metodi di autenticazione senza chiave

Completato

La modalità di configurazione dell'autenticazione dell'identità gestita per lo sviluppo Python locale è diversa dalla modalità di configurazione dell'autenticazione dell'identità gestita per ambienti Python con ospitati in Azure.

Autenticazione senza chiave in Azure OpenAI per lo sviluppo Python locale

Per lo sviluppo locale in Python, l'autenticazione senza chiave nel servizio OpenAI di Azure usa le identità gestite di Azure e il controllo degli accessi in base al ruolo per autenticare e autorizzare gli sviluppatori in modo efficiente. Assicurarsi di aver configurato le assegnazioni di ruolo nell'unità precedente. Assicurarsi anche di aver configurato il proprio account Azure con accesso a livello locale per accedere alla risorsa Azure OpenAI di destinazione.

Dopo aver configurato le assegnazioni dei ruoli, gli sviluppatori Python possono usare la libreria di Identità di Azure per eseguire l'autenticazione con Azure OpenAI.

Autenticazione senza chiave con il pacchetto OpenAI

L'esempio seguente implementa l'autenticazione senza chiave per il pacchetto openai ufficiale:

import azure.identity
import openai
credential = azure.identity.DefaultAzureCredential()
token_provider = azure.identity.get_bearer_token_provider(credential, "https://cognitiveservices.azure.com/.default")

client = openai.AzureOpenAI(   
   azure_endpoint=f"https://YOUR-AZURE-OPENAI-ENDPOINT.openai.azure.com",
    azure_ad_token_provider=token_provider,
    api_version="2024-06-01",
)

response = client.chat.completions.create(
    model="YOUR-MODEL-DEPLOYMENT", 
    messages=[
        {"role": "user", "content": "Write a haiku about a hungry cat"},
    ],
)

Nel codice precedente:

• DefaultAzureCredential è una catena di credenziali che tenta l'autenticazione tramite una sequenza di credenziali specifiche, come AzureCliCredential e AzureDeveloperCliCredential. Questo comportamento può essere utile per lo sviluppo locale, perché offre la flessibilità dell'accesso con az login, azd auth login o con qualsiasi altro approccio di autenticazione supportato.

  È possibile sostituire questa classe con una classe di credenziali specifica, se necessario. È possibile passare molti parametri per personalizzare il funzionamento.

• azure.identity.get_bearer_token_provider()restituisce un token che fornisce una funzione per l'ambito OAuth2. L'ambito specificato qui è https://cognitiveservices.azure.com/.default; che corrisponde alle risorse di Azure OpenAI. Tale funzione di provider di token viene chiamata solo quando è eseguita una richiesta effettiva, in modo che la riga abbia esito positivo anche se le autorizzazioni della risorsa non sono configurate correttamente.

• Il client AzureOpenAI viene sottoposto a istanza con l'endpoint di Azure, il provider del token e la versione API desiderata. È anche possibile creare un'istanza di un client AsyncAzureOpenAI con gli stessi parametri. È consigliabile scegliere questa opzione per l'uso all'interno di framework asincroni come FastAPI o Quart.

• client.chat.completions.create invia una richiesta alla distribuzione Azure OpenAI. Quando si utilizza il pacchetto openai con Azure, il parametro del modello non deve essere il nome del modello, ma il nome del modello. Deve essere il nome della distribuzione. Per ragioni pratiche, alcuni sviluppatori scelgono di nominare sempre le distribuzioni come i modelli, ma non è sempre così.

  La funzione del provider di token viene richiamata in questo momento. Viene restituito un token per le credenziali e l'ambito specificati. Se la funzione restituisce un errore di autorizzazione, si è verificato un problema con le credenziali di autenticazione usate localmente o con le autorizzazioni di controllo degli accessi in base al ruolo per la risorsa.

Autenticazione senza chiave con altri pacchetti

Se si chiama Azure OpenAI tramite un altro pacchetto, ad esempio LangChain o LlamaIndex, consultare il riferimento per tale pacchetto per determinare come usare l'autenticazione senza chiave. Cercare parametri come "provider di token" (per trasmettere i risultati della chiamata get_bearer_token_provider) o "credenziali" (per trasmettere le credenziali stesse).

Alcuni pacchetti possono offrire solo l'opzione per trasmettere un token effettivo. In tal caso, è possibile generare un token usando Azure Identity SDK:

credential = azure.identity.DefaultAzureCredential()
token = credential.get_token("https://cognitiveservices.azure.com/.default")

Il token generato è di breve durata. Può scadere non appena un'ora dopo la generazione. Sarà quindi necessario generare un nuovo token o implementare la logica di aggiornamento del token per evitare errori di scadenza del token dall'API. Per evitare questi problemi, è consigliabile usare un SDK che genera nuovi token per ogni richiesta o implementa la logica di aggiornamento del token.

Codice di esempio

Il progetto azure-openai-keyless usa l'autenticazione senza chiave con il openai pacchetto. Include anche file di infrastruttura come codice (file Bicep) che configurano il ruolo controllo degli accessi in base al ruolo richiesto per lo sviluppatore locale. È possibile distribuire questo progetto usando solo alcuni comandi nell'interfaccia della riga di comando per sviluppatori di Azure.

Autenticazione senza chiave in Azure OpenAI per gli ambienti Python ospitati in Azure

Quando si distribuisce un'app Python in un ambiente ospitato in Azure, come App contenitore di Azure o Servizio app di Azure, l'app può utilizzare l'autenticazione senza chiave per eseguire l'autenticazione ad Azure OpenAI.

Per il corretto funzionamento dell'autenticazione senza chiave, è necessario configurare correttamente l'app:

• L'app deve avere un'identità di sistema abilitata o essere associata a un'identità assegnata dall'utente.
• L'identità dell'app deve disporre delle autorizzazioni corrette per accedere alla risorsa Azure OpenAI, come il ruolo Utente Servizi cognitivi OpenAI o il ruolo Sviluppatore Azure per intelligenza artificiale.

Il passaggio successivo consiste nell'usare Azure Identity SDK per autenticare l'applicazione distribuita. Sono disponibili diverse opzioni a seconda del tipo di identità in uso e del controllo desiderato sul flusso di autenticazione.

Autenticazione senza chiave con DefaultAzureCredential

La prima opzione consiste nell'usare lo stesso codice DefaultAzureCredential illustrato in precedenza:

import azure.identity
import openai
credential = azure.identity.DefaultAzureCredential()
token_provider = azure.identity.get_bearer_token_provider(credential, "https://cognitiveservices.azure.com/.default")

client = openai.AzureOpenAI(   
   azure_endpoint=f"https://YOUR-AZURE-OPENAI-ENDPOINT.openai.azure.com",
    azure_ad_token_provider=token_provider,
    api_version="2024-06-01",
)

Come descritto in precedenza, questo codice usa una catena di credenziali per autenticare l'app. Generalmente, offre buone prestazioni quando si utilizza un'identità di sistema, poiché Azure Identity SDK sa esattamente quale identità utilizzare al momento dell'autenticazione.

Tuttavia, se si configura un'identità assegnata dall'utente per l'app, l'SDK potrebbe non essere in grado di determinare quale identità usare per l'autenticazione. Il motivo è che un'app può essere associata a più identità assegnate dall'utente. Favorisce la configurazione di una variabile di ambiente AZURE_CLIENT_ID per l'ID client dell'identità assegnata dall'utente, ma questo approccio potrebbe non funzionare su tutte le piattaforme di Azure.

Autenticazione senza chiave con ManagedIdentityCredential

In un ambiente di produzione in un host di Azure, è consigliabile usare la classe ManagedIdentityCredential(/python/api/azure-identity/azure.identity.managedidentitycredential) per un'autenticazione più affidabile.

Tale classe può essere trasmessa all'ID client di un'identità assegnata dall'utente:

ManagedIdentityCredential(client_id=YOUR_APP_IDENTITY_CLIENT_ID)

Può anche essere creata senza parametri, per l'utilizzo con un'identità del sistema:

ManagedIdentityCredential()

È possibile usare le credenziali allo stesso modo di DefaultAzureCredential. È possibile usarlo per generare provider di token o token.

Autenticazione senza chiave tra ambienti

Spesso, lo stesso codice Python viene usato negli ambienti locali come nella produzione. Se DefaultAzureCredential funziona sia in ambienti locali che in produzione, è possibile usarlo ovunque.

Tuttavia, gli sviluppatori spesso scelgono di usare credenziali diverse in ogni ambiente. Controllano la scelta in base alle variabili di ambiente che segnalano l'host corrente.

Ad esempio, considerare questa istruzione if:

if os.getenv("RUNNING_ON_AZURE"):
   credential = azure.identity.ManagedIdentityCredential(os.getenv("AZURE_CLIENT_ID"))
else:
  credential = azure.identity.AzureDeveloperCliCredential()

Il codice verifica innanzitutto l'esistenza di una variabile di ambiente personalizzata esplicitamente impostata per segnalare un ambiente di produzione. Per la produzione, imposta la variabile delle credenziali su ManagedIdentityCredential e trasmette l'ID client dell'identità assegnata dall'utente con il ruolo corretto. In caso contrario, imposta la variabile delle credenziali su AzureDeveloperCliCredential. AzureDeveloperCliCredential presuppone che lo sviluppatore usi azd auth login per accedere all'account Azure in locale.

Un altro approccio consiste nel configurare credenziali concatenate personalizzate.

Esistono molte opzioni, a seconda degli ambienti e delle esigenze di autenticazione.

Codice di esempio

Il progetto openai-chat-app-quickstart usa l'autenticazione senza chiave per un'app contenitore di Azure con un'identità assegnata dall'utente. Il progetto include file Infrastructure as Code (file Bicep) che configura l'app contenitore, l'identità e i ruoli per l'identità dell'app e per lo sviluppatore locale. È possibile distribuire questo progetto usando solo alcuni comandi nell'interfaccia della riga di comando per sviluppatori di Azure.