Inizia con l'elemento costitutivo di sicurezza di Azure OpenAI

• Un'app Python Quart che usa il pacchetto openai e l'API Responses per generare risposte ai messaggi utente.
• Front-end HTML/JavaScript di base che trasmette le risposte dal back-end usando righe JSON su un flusso leggibile.

• Un'app Web Blazor che utilizza il pacchetto NuGet Azure.AI.OpenAI per generare risposte ai messaggi degli utenti.

• Un'app Web TypeScript che usa il pacchetto npm OpenAI per generare risposte ai messaggi utente.

Altre informazioni sul costo nell'esempio di repository.

Altre informazioni sul costo nell'esempio di repository.

Altre informazioni sul costo nell'esempio di repository.

Esplorazione del codice di esempio

Mentre OpenAI e Servizio Azure OpenAI si basano su una libreria client Python comune, quando si usano gli endpoint di Azure OpenAI sono necessarie piccole modifiche al codice. Vediamo come questo esempio configura l'autenticazione senza chiave con Microsoft Entra ID e comunica con Azure OpenAI.

Configurare l'autenticazione con l'identità gestita

In questo esempio il src/quartapp/chat.py file inizia con la configurazione dell'autenticazione senza chiave.

Il frammento di codice seguente usa il modulo azure.identity.aio per creare un flusso di autenticazione asincrono Microsoft Entra.

Il frammento di codice seguente usa la AZURE_CLIENT_IDazd variabile di ambiente per creare un'istanza managedIdentityCredential in grado di eseguire l'autenticazione tramite l'identità gestita assegnata dall'utente.

user_assigned_managed_identity_credential = ManagedIdentityCredential(client_id=os.getenv("AZURE_CLIENT_ID")) 

Il frammento di codice seguente usa AZURE_TENANT_IDazd variabile di ambiente delle risorse per creare un'istanza di AzureDeveloperCliCredential in grado di eseguire l'autenticazione con il tenant Microsoft Entra corrente.

azure_dev_cli_credential = AzureDeveloperCliCredential(tenant_id=os.getenv("AZURE_TENANT_ID"), process_timeout=60)  

La libreria client Azure Identity fornisce credenziali: classi pubbliche che implementano il protocollo TokenCredential della libreria Azure Core. Una credenziale rappresenta un flusso di autenticazione distinto per l'acquisizione di un token di accesso da Microsoft Entra ID. Queste credenziali si possono concatenare per formare una sequenza ordinata di meccanismi di autenticazione da tentare.

Il frammento di codice seguente crea un ChainedTokenCredential utilizzando un ManagedIdentityCredential e un AzureDeveloperCliCredential:

• Il ManagedIdentityCredential viene usato per Funzioni di Azure, Servizio app di Azure e App contenitore di Azure. Un'identità gestita assegnata dall'utente è supportata passando client_id a ManagedIdentityCredential.
• AzureDeveloperCliCredential viene utilizzato per lo sviluppo locale. È stato impostato in precedenza in base al tenant di Microsoft Entra da utilizzare.

azure_credential = ChainedTokenCredential(
    user_assigned_managed_identity_credential,
    azure_dev_cli_credential
)

Il frammento di codice seguente ottiene il provider di token OpenAI di Azure in base alla credenziale Azure selezionata. Questo valore viene ottenuto chiamando il azure.identity.aio.get_bearer_token_provider con due argomenti:

• azure_credential ChainedTokenCredential: istanza creata in precedenza per autenticare la richiesta.

• https://cognitiveservices.azure.com/.default: obbligatorio uno o più ambiti del token portatore. In questo caso, l'endpoint Azure Cognitive Services.

token_provider = get_bearer_token_provider(
    azure_credential, "https://cognitiveservices.azure.com/.default"
)

Le righe seguenti controllano la presenza delle variabili di ambiente necessarie AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_CHAT_DEPLOYMENT, le quali sono impostate durante il provisioning di azdazd. Se un valore non è presente, viene generato un errore.

openai_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
if not openai_endpoint:
    raise ValueError("AZURE_OPENAI_ENDPOINT is required for Azure OpenAI")
if not os.getenv("AZURE_OPENAI_CHAT_DEPLOYMENT"):
    raise ValueError("AZURE_OPENAI_CHAT_DEPLOYMENT is required for Azure OpenAI")

Questo frammento di codice inizializza il client OpenAI rispetto all'endpoint /openai/v1/ di Azure, passando il provider di token come api_key. Non api_version è necessario con l'endpoint v1:

bp.openai_client = AsyncOpenAI(
    base_url=f"{openai_endpoint.rstrip('/')}/openai/v1/",
    api_key=token_provider,
)

La riga seguente imposta il nome di distribuzione del modello OpenAI Azure da usare nelle chiamate API:

bp.openai_model = os.getenv("AZURE_OPENAI_CHAT_DEPLOYMENT")

Al termine di questa funzione, il client è configurato correttamente e pronto per interagire con Azure servizi OpenAI.

Trasmettere risposte usando l'API Risposte OpenAI

response_stream gestisce nella route la chiamata di streaming dell'API Responses. Il frontend invia direttamente gli elementi a forma di risposte input e il backend li inoltra a responses.stream():

async def response_stream():
    try:
        async with bp.openai_client.responses.stream(
            model=bp.openai_model,
            input=request_input,
            store=False,
        ) as openai_stream:
            async for event in openai_stream:
                yield json.dumps(event.model_dump(), ensure_ascii=False) + "\n"
    except Exception as e:
        current_app.logger.exception("Responses stream failed")
        yield json.dumps({"error": str(e)}, ensure_ascii=False) + "\n"

Esplorare il codice di esempio

Le applicazioni .NET fanno affidamento sulla libreria client Azure.AI.OpenAI per comunicare con i servizi Azure OpenAI, che dipende dalla libreria OpenAI. L'app di esempio configura l'autenticazione senza chiave usando Microsoft Entra ID per comunicare con Azure OpenAI.

Configurare l'autenticazione e la registrazione del servizio

In questo esempio l'autenticazione senza chiave viene configurata nel program.cs file . Il frammento di codice seguente usa la AZURE_CLIENT_ID variabile di ambiente impostata da azd per creare un'istanza managedIdentityCredential in grado di eseguire l'autenticazione tramite l'identità gestita assegnata dall'utente.

var userAssignedIdentityCredential = 
    new ManagedIdentityCredential(builder.Configuration.GetValue<string>("AZURE_CLIENT_ID"));

Il frammento di codice seguente usa la AZURE_TENANT_ID variabile di ambiente impostata da azd per creare un'istanza di AzureDeveloperCliCredential in grado di autenticarsi localmente usando l'account connesso a azd.

var azureDevCliCredential = new AzureDeveloperCliCredential(
    new AzureDeveloperCliCredentialOptions()
    { 
        TenantId = builder.Configuration.GetValue<string>("AZURE_TENANT_ID") 
    });

La libreria client Azure Identity fornisce classi di credenziali che implementano il protocollo TokenCredential della libreria Azure Core. Una credenziale rappresenta un flusso di autenticazione distinto per l'acquisizione di un token di accesso da Microsoft Entra ID. Queste credenziali possono essere concatenate usando ChainedTokenCredential per formare una sequenza ordinata di meccanismi di autenticazione da tentare.

Il frammento di codice seguente registra AzureOpenAIClient per l'iniezione delle dipendenze e crea un nuovo ChainedTokenCredential usando un ManagedIdentityCredential e un AzureDeveloperCliCredential:

• Il ManagedIdentityCredential viene usato per Funzioni di Azure, Servizio app di Azure e App contenitore di Azure. Un'identità gestita assegnata dall'utente è supportata utilizzando il AZURE_CLIENT_ID fornito a ManagedIdentityCredential.
• AzureDeveloperCliCredential viene utilizzato per lo sviluppo locale. È stato configurato in precedenza per il tenant di Microsoft Entra da utilizzare.

builder.Services.AddAzureClients(
    clientBuilder => {
        clientBuilder.AddClient<AzureOpenAIClient, AzureOpenAIClientOptions>((options, _, _)
            => new AzureOpenAIClient(
                new Uri(endpoint),
                new ChainedTokenCredential(
                    userAssignedIdentityCredential, azureDevCliCredential), options));
    });

Ottenere i completamenti della chat usando il client OpenAI Azure

L'app Web Blazor inserisce l'oggetto registrato AzureOpenAIClient nella parte superiore del componente Home.Razor.

@inject AzureOpenAIClient azureOpenAIClient

Quando l'utente invia il modulo, invia AzureOpenAIClient la richiesta al modello OpenAI di generare un completamento:

ChatClient chatClient = azureOpenAIClient.GetChatClient("gpt-4o-mini");

messages.Add(new UserChatMessage(model.UserMessage));

ChatCompletion completion = await chatClient.CompleteChatAsync(messages);
    messages.Add(new SystemChatMessage(completion.Content[0].Text));

Esplorare il codice di esempio

Mentre OpenAI e Servizio Azure OpenAI si basano su un openai (libreria client JavaScript comune), quando si usano gli endpoint OpenAI Azure sono necessarie piccole modifiche al codice. Vediamo come questo esempio configura l'autenticazione senza chiave con Microsoft Entra ID e comunica con Azure OpenAI.

Autenticazione senza chiave per ogni ambiente

La libreria client Azure Identity fornisce classi di credenziali che implementano il protocollo TokenCredential della libreria Azure Core. Una credenziale rappresenta un flusso di autenticazione distinto per l'acquisizione di un token di accesso da Microsoft Entra ID. Queste credenziali possono essere concatenate usando chainedTokenCredential per formare una sequenza ordinata di meccanismi di autenticazione da tentare. In questo modo è possibile distribuire lo stesso codice sia in ambienti di produzione che in ambienti di sviluppo locali.

Configurare l'autenticazione con l'identità gestita

In questo esempio, il ./src/azure-authentication.ts fornisce diverse funzioni per fornire l'autenticazione senza chiave per Azure OpenAI.

La prima funzione, getChainedCredential(), restituisce la prima credenziale valida Azure trovata nella catena.

function getChainedCredential() {

    return new ChainedTokenCredential(
        new ManagedIdentityCredential(process.env.AZURE_CLIENT_ID!), 
        new AzureDeveloperCliCredential({
            tenantId: process.env.AZURE_TENANT_ID! ? process.env.AZURE_TENANT_ID! : undefined
          })
    );
}

• ManagedIdentityCredential viene tentato per primo. Viene configurato con la variabile di ambiente AZURE_CLIENT_ID nel runtime di produzione ed è in grado di eseguire l'autenticazione tramite l'identità gestita assegnata dall'utente.
• Il tentativo di AzureDeveloperCliCredential è il secondo. Viene configurato quando uno sviluppatore accede con l'interfaccia della riga di comando di Azure Developer usando azd auth login.

Ottenere il token Bearer per OpenAI

La seconda funzione in ./src/azure-authentication.ts è getTokenProvider(), che restituisce un callback che fornisce un token di connessione per l'endpoint Azure Cognitive Services.

function getTokenProvider(): () => Promise<string> {
    const credential  = getChainedCredential();
    const scope = "https://cognitiveservices.azure.com/.default";
    return getBearerTokenProvider(credential, scope);
}

Il frammento di codice precedente utilizza getBearerTokenProvider per ottenere le credenziali e l'ambito, quindi restituisce un callback che fornisce un bearer token.

Creare un client OpenAI di Azure autenticato

La terza funzione in ./src/azure-authentication.ts è getOpenAiClient(), che restituisce il client OpenAI Azure.

export function getOpenAiClient(): AzureOpenAI | undefined{
    try {

        if (!process.env.AZURE_OPENAI_ENDPOINT) {
            throw new Error("AZURE_OPENAI_ENDPOINT is required for Azure OpenAI");
        }
        if (!process.env.AZURE_OPENAI_CHAT_DEPLOYMENT) {
            throw new Error("AZURE_OPENAI_CHAT_DEPLOYMENT is required for Azure OpenAI");
        }

        const options = { 
            azureADTokenProvider: getTokenProvider(), 
            deployment: process.env.AZURE_OPENAI_CHAT_DEPLOYMENT!, 
            apiVersion: process.env.AZURE_OPENAI_API_VERSION! || "2024-02-15-preview",
            endpoint: process.env.AZURE_OPENAI_ENDPOINT!
        }

        // Create the Asynchronous Azure OpenAI client
        return new AzureOpenAI (options);

    } catch (error) {
        console.error('Error getting Azure OpenAI client: ', error);
    }
}

Questo codice accetta le opzioni, incluso il token con ambito corretto, e crea il AzureOpenAI client

Rispondere alla chat in streaming con Azure OpenAI

Usare il gestore di route Fastify seguente in ./src/openai-chat-api.ts per inviare un messaggio a Azure OpenAI e trasmettere la risposta.

import { FastifyReply, FastifyRequest } from 'fastify';
import { AzureOpenAI } from "openai";
import { getOpenAiClient } from './azure-authentication.js';
import { ChatCompletionChunk, ChatCompletionMessageParam } from 'openai/resources/chat/completions';

interface ChatRequestBody {
    messages: ChatCompletionMessageParam [];
  }

export async function chatRoute (request: FastifyRequest<{ Body: ChatRequestBody }>, reply: FastifyReply) {

    const requestMessages: ChatCompletionMessageParam[] = request?.body?.messages;
    const openaiClient: AzureOpenAI | undefined = getOpenAiClient();

    if (!openaiClient) {
      throw new Error("Azure OpenAI client is not configured");
    }

    const allMessages = [
      { role: "system", content: "You are a helpful assistant."},
      ...requestMessages
    ] as ChatCompletionMessageParam [];

    const chatCompletionChunks = await openaiClient.chat.completions.create({
      // Azure Open AI takes the deployment name as the model name
      model: process.env.AZURE_OPENAI_CHAT_DEPLOYMENT_MODEL || "gpt-4o-mini",
      messages: allMessages,
      stream: true

    })
    reply.raw.setHeader('Content-Type', 'text/html; charset=utf-8');
    reply.raw.setHeader('Cache-Control', 'no-cache');
    reply.raw.setHeader('Connection', 'keep-alive');
    reply.raw.flushHeaders();

    for await (const chunk of chatCompletionChunks as AsyncIterable<ChatCompletionChunk>) {
      for (const choice of chunk.choices) {
        reply.raw.write(JSON.stringify(choice) + "\n")
      }
    }

    reply.raw.end()

}

La funzione ottiene la conversazione di chat, inclusi i messaggi precedenti e li invia a Azure OpenAI. Man mano che i blocchi di flusso vengono restituiti da Azure OpenAI, vengono inviati al client.

Se il problema non viene risolto, registrare il problema nel Issues del repository.

Passaggi successivi

Se il problema non viene risolto, registrare il problema nel Issues del repository.

Se il problema non viene risolto, registrare il problema nel Issues del repository.