Esercitazione: Creare un chatbot con il servizio app di Azure e Azure OpenAI (.NET)

2025-05-20

In questa esercitazione si creerà un'applicazione di intelligenza artificiale intelligente integrando Azure OpenAI con un'applicazione Java Spring Boot e distribuendola nel servizio app di Azure. Si creerà una pagina Razor che invia richieste di completamento della chat a un modello in Azure OpneAI e trasmette la risposta alla pagina.

Screenshot che mostra il chatbot in esecuzione nel servizio app di Azure.

In questa esercitazione si apprenderà come:

Creare una risorsa OpenAI di Azure e distribuire un modello linguistico
Creare un'applicazione Blazor con Azure OpenAI
Distribuire l'applicazione nel servizio app di Azure
Implementare l'autenticazione senza password sia nell'ambiente di sviluppo che in Azure

Prerequisiti

Un account Azure con una sottoscrizione attiva
Un account GitHub per l'uso di GitHub Codespaces

1. Creare una risorsa OpenAI di Azure

In questa sezione si useranno GitHub Codespaces per creare una risorsa Azure OpenAI con Azure CLI.

Passare a GitHub Codespaces e accedere con l'account GitHub.
Trovare il modello Vuoto di GitHub e selezionare Usa questo modello per creare un nuovo spazio di codice vuoto.
Nel terminale Codespace installare l'interfaccia della riga di comando di Azure:
```
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
```
Accedere all'account Azure:
```
az login
```
Seguire le istruzioni nel terminale per l'autenticazione.
Impostare le variabili di ambiente per il nome del gruppo di risorse, il nome del servizio OpenAI di Azure e la posizione:
```
export RESOURCE_GROUP="<group-name>"
export OPENAI_SERVICE_NAME="<azure-openai-name>"
export APPSERVICE_NAME="<app-name>"
export LOCATION="eastus2"
```
Importante

L'area è fondamentale perché è associata alla disponibilità a livello di area del modello scelto. La disponibilità del modello e il tipo di distribuzione variano da un'area all'altra. Questa esercitazione usa gpt-4o-mini, disponibile nel tipo di distribuzione Standard eastus2. Se si esegue la distribuzione in un'area diversa, questo modello potrebbe non essere disponibile o potrebbe richiedere un livello diverso. Prima di modificare le aree, consultare la tabella di riepilogo del modello e la disponibilità dell'area per verificare il supporto del modello nell'area preferita.

Creare un gruppo di risorse e una risorsa OpenAI di Azure con un dominio personalizzato, quindi aggiungere un modello gpt-4o-mini:

# Resource group
az group create --name $RESOURCE_GROUP --location $LOCATION
# Azure OpenAI resource
az cognitiveservices account create \
  --name $OPENAI_SERVICE_NAME \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION \
  --custom-domain $OPENAI_SERVICE_NAME \
  --kind OpenAI \
  --sku s0
# gpt-4o-mini model
az cognitiveservices account deployment create \
  --name $OPENAI_SERVICE_NAME \
  --resource-group $RESOURCE_GROUP \
  --deployment-name gpt-4o-mini \
  --model-name gpt-4o-mini \
  --model-version 2024-07-18 \
  --model-format OpenAI \
  --sku-name Standard \
  --sku-capacity 1
# Cognitive Services OpenAI User role that lets the signed in Azure user to read models from Azure OpenAI
az role assignment create \
  --assignee $(az ad signed-in-user show --query id -o tsv) \
  --role "Cognitive Services OpenAI User" \
  --scope /subscriptions/$(az account show --query id -o tsv)/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$OPENAI_SERVICE_NAME

Dopo aver creato una risorsa OpenAI di Azure, si creerà un'applicazione Web per interagire con essa.

2. Creare e configurare un'app Web Blazor

In questa sezione si creerà una nuova applicazione Web Blazor usando l'interfaccia della riga di comando di .NET.

Nel terminale Codespace creare una nuova app Blazor e provare a eseguirla per la prima volta.
```
dotnet new blazor -o .
dotnet run
```
Verrà visualizzata una notifica in GitHub Codespaces che indica che l'app è disponibile in una porta specifica. Selezionare Apri nel browser per avviare l'app in una nuova scheda del browser.
Tornare al terminale Codespace, arrestare l'app con CTRL+C.

Installare i pacchetti NuGet necessari per l'uso di Azure OpenAI:

dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity

Aprire Components/Pages/Home.razor e sostituire il contenuto con il codice seguente per una semplice chiamata al flusso di completamento della chat con Azure OpenAI:

@page "/"
@rendermode InteractiveServer
@using Azure.AI.OpenAI
@using Azure.Identity
@using OpenAI.Chat
@inject Microsoft.Extensions.Configuration.IConfiguration _config

<h3>Azure OpenAI Chat</h3>
<div class="mb-3 d-flex align-items-center" style="margin:auto;">
    <input class="form-control me-2" @bind="userMessage" placeholder="Type your message..." />
    <button class="btn btn-primary" @onclick="SendMessage">Send</button>
</div>
<div class="card p-3" style="margin:auto;">
    @if (!string.IsNullOrEmpty(aiResponse))
    {
        <div class="alert alert-info mt-3 mb-0">@aiResponse</div>
    }
</div>

@code {
    private string? userMessage;
    private string? aiResponse;

    private async Task SendMessage()
    {
        if (string.IsNullOrWhiteSpace(userMessage)) return;

        // Initialize the Azure OpenAI client
        var endpoint = new Uri(_config["AZURE_OPENAI_ENDPOINT"]!);
        var client = new AzureOpenAIClient(endpoint, new DefaultAzureCredential());
        var chatClient = client.GetChatClient("gpt-4o-mini");

        aiResponse = string.Empty;
        StateHasChanged();

        // Create a chat completion streaming request
        var chatUpdates = chatClient.CompleteChatStreamingAsync(
            [
                new UserChatMessage(userMessage)
            ]);

            await foreach(var chatUpdate in chatUpdates)
            {
                // Update the UI with the streaming response
                foreach(var contentPart in chatUpdate.ContentUpdate)
            {
                aiResponse += contentPart.Text;
                StateHasChanged();
            }
        }
    }
}

Nel terminale recuperare l'endpoint OpenAI:

az cognitiveservices account show \
  --name $OPENAI_SERVICE_NAME \
  --resource-group $RESOURCE_GROUP \
  --query properties.endpoint \
  --output tsv

Esegui di nuovo l'app aggiungendo AZURE_OPENAI_ENDPOINT con il suo valore dall'output della CLI:
```
AZURE_OPENAI_ENDPOINT=<output-from-previous-cli-command> dotnet run
```
Selezionare Apri nel browser per avviare l'app in una nuova scheda del browser.
Digitare un messaggio nella casella di testo e selezionare "Invia e assegnare all'app alcuni secondi la risposta con il messaggio da Azure OpenAI.

L'applicazione usa DefaultAzureCredential, che usa automaticamente l'utente connesso all'interfaccia della riga di comando di Azure per l'autenticazione del token. Più avanti in questa esercitazione si distribuirà l'app Blazor nel servizio app di Azure e la si configurerà per connettersi in modo sicuro alla risorsa OpenAI di Azure usando l'identità gestita. Lo stesso DefaultAzureCredential nel codice può rilevare l'identità gestita e usarla per l'autenticazione. Non è necessario alcun codice aggiuntivo.

3. Distribuire nel servizio app di Azure e configurare la connessione OpenAI

Ora che l'app funziona in locale, è possibile distribuirla nel servizio app di Azure e configurare una connessione del servizio ad Azure OpenAI usando l'identità gestita.

Innanzitutto, distribuisci l'app su Azure App Service usando il comando Azure CLI az webapp up. Questo comando crea una nuova app Web e distribuisce il codice:
```
az webapp up \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION \
  --name $APPSERVICE_NAME \
  --plan $APPSERVICE_NAME \
  --sku B1 \
  --os-type Linux \
  --track-status false
```
Il completamento di questo comando potrebbe richiedere alcuni minuti. Crea una nuova app Web nello stesso gruppo di risorse della risorsa OpenAI.
Dopo aver distribuito l'app, creare una connessione al servizio tra l'app Web e la risorsa OpenAI di Azure usando l'identità gestita:
```
az webapp connection create cognitiveservices \
  --resource-group $RESOURCE_GROUP \
  --name $APPSERVICE_NAME \
  --target-resource-group $RESOURCE_GROUP \
  --account $OPENAI_SERVICE_NAME
  --connection azure-openai \
  --system-identity
```
Questo comando crea una connessione tra l'app Web e la risorsa OpenAI di Azure tramite:
- Generazione dell'identità gestita assegnata dal sistema per l'app Web.
- Aggiunta del ruolo Collaboratore di Servizi cognitivi OpenAI all'identità gestita per la risorsa Azure OpenAI.
- Aggiunta dell'impostazione dell'app AZURE_OPENAI_ENDPOINT per l'app Web.
L'app viene ora distribuita e connessa ad Azure OpenAI con identità gestita. Leggo l'impostazione dell'app AZURE_OPENAI_ENDPOINT attraverso l'iniezione di IConfiguration.
Aprire l'app Web distribuita nel browser. Trovare l'URL dell'app Web distribuita nell'output del terminale. Apri il browser web e naviga verso di esso.
```
az webapp browse
```
Digitare un messaggio nella casella di testo e selezionare "Invia e assegnare all'app alcuni secondi la risposta con il messaggio da Azure OpenAI.

Domande frequenti

Cosa accade se si vuole connettersi a OpenAI anziché ad Azure OpenAI?
È invece possibile connettersi ad Azure OpenAI con una chiave API?
Come funziona DefaultAzureCredential in questa esercitazione?

Cosa accade se si vuole connettersi a OpenAI anziché ad Azure OpenAI?

Per connettersi invece a OpenAI, usare il codice seguente:

@using OpenAI.Client

var client = new OpenAIClient("<openai-api-key>");

Per altre informazioni, vedere Autenticazione api OpenAI.

Quando si usano segreti di connessione nel servizio app, è consigliabile usare i riferimenti a Key Vault anziché archiviare i segreti direttamente nella codebase. Ciò garantisce che le informazioni riservate rimangano sicure e gestite centralmente.

È invece possibile connettersi ad Azure OpenAI con una chiave API?

Sì, è possibile connettersi ad Azure OpenAI usando una chiave API anziché un'identità gestita. Questo approccio è supportato dagli SDK OpenAI di Azure e dal kernel semantico.

Per informazioni dettagliate sull'uso delle chiavi API con il kernel semantico in C#, vedere guida introduttiva sul kernel semantico C#.
Per informazioni dettagliate sull'uso delle chiavi API con la libreria client OpenAI di Azure: Avvio rapido: Introduzione all'uso dei completamenti della chat con il servizio Azure OpenAI.

Come funziona DefaultAzureCredential in questa esercitazione?

Semplifica DefaultAzureCredential l'autenticazione selezionando automaticamente il metodo di autenticazione migliore disponibile:

Durante lo sviluppo locale: dopo aver eseguito az login, usa le credenziali della CLI di Azure locale.
Quando viene distribuito nel servizio app di Azure: usa l'identità gestita dell'app per l'autenticazione sicura e senza password.

Questo approccio consente di eseguire il codice in modo sicuro e senza problemi in ambienti locali e cloud senza modifiche.

Condividi tramite