Freigeben über

Lernprogramm: Erstellen eines Chatbots mit Azure App Service und Azure OpenAI (Spring Boot)

In diesem Lernprogramm erstellen Sie eine intelligente KI-Anwendung, indem Sie Azure OpenAI in eine Java Spring Boot-Anwendung integrieren und in Azure App Service bereitstellen. Sie erstellen einen Spring Boot Controller, der eine Abfrage an Azure OpenAI sendet und die Antwort an den Browser sendet.

Tipp

Während dieses Lernprogramms Spring Boot verwendet, gelten die Kernkonzepte des Erstellens einer Chatanwendung mit Azure OpenAI für jede Java-Webanwendung. Wenn Sie eine andere Hostingoption für App Service verwenden, z. B. Tomcat oder JBoss EAP, können Sie die hier gezeigten Authentifizierungsmuster und die Azure SDK-Verwendung an Ihr bevorzugtes Framework anpassen.

Screenshot eines Chatbots, der in Azure App Service ausgeführt wird.

In diesem Tutorial lernen Sie Folgendes:

  • Erstellen Sie eine Azure OpenAI-Ressource, und stellen Sie ein Sprachmodell bereit.
  • Erstellen Sie eine Spring Boot-Anwendung, die eine Verbindung mit Azure OpenAI herstellt.
  • Verwenden Sie die Abhängigkeitseinfügung, um den Azure OpenAI-Client zu konfigurieren.
  • Stellen Sie die Anwendung in Azure App Service bereit.
  • Implementieren Sie die kennwortlose sichere Authentifizierung sowohl in der Entwicklungsumgebung als auch in Azure.

Voraussetzungen

1. Erstellen einer Azure OpenAI-Ressource

In diesem Abschnitt verwenden Sie GitHub Codespaces, um eine Azure OpenAI-Ressource mit der Azure CLI zu erstellen.

  1. Wechseln Sie zu GitHub Codespaces , und melden Sie sich mit Ihrem GitHub-Konto an.

  2. Suchen Sie die leere Vorlage von GitHub, und wählen Sie "Diese Vorlage verwenden " aus, um einen neuen leeren Codespace zu erstellen.

  3. Installieren Sie im Codespace-Terminal die Azure CLI:

    curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

  4. Melden Sie sich bei Ihrem Azure-Konto an:

    az login

    Folgen Sie den Anweisungen im Terminal, um sich zu authentifizieren.

  5. Legen Sie Umgebungsvariablen für den Namen der Ressourcengruppe, den Namen des Azure OpenAI-Dienstes und den Speicherort fest.

    export RESOURCE_GROUP="<group-name>"
export OPENAI_SERVICE_NAME="<azure-openai-name>"
export APPSERVICE_NAME="<app-name>"
export LOCATION="eastus2"

    Von Bedeutung

    Die Region ist kritisch, da sie an die regionale Verfügbarkeit des ausgewählten Modells gebunden ist. Die Modellverfügbarkeit und die Verfügbarkeit des Bereitstellungstyps variieren von Region zu Region. Dieses Tutorial verwendet gpt-4o-mini, das im Standardbereitstellungstyp unter eastus2 verfügbar ist. Wenn Sie eine Bereitstellung in einer anderen Region ausführen, ist dieses Modell möglicherweise nicht verfügbar oder erfordert eine andere Ebene. Überprüfen Sie, bevor Sie Regionen ändern, die Modellzusammenfassungstabelle und die Regionsverfügbarkeit, um die Unterstützung des Modells in Ihrer bevorzugten Region zu überprüfen.

  6. Erstellen Sie eine Ressourcengruppe und eine Azure OpenAI-Ressource mit einer benutzerdefinierten Domäne, und fügen Sie dann ein gpt-4o-mini-Modell hinzu:

    # 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

Nachdem Sie nun über eine Azure OpenAI-Ressource verfügen, erstellen Sie eine Webanwendung für die Interaktion damit.

2. Erstellen und Einrichten einer Spring Boot Web App

  1. Klonen Sie im Codespace-Terminal das Spring Boot REST-Beispiel in den Arbeitsbereich, und versuchen Sie, es zum ersten Mal auszuführen.

    git clone https://github.com/rd-1-2022/rest-service .
mvn spring-boot:run

    In GitHub Codespaces sollte eine Benachrichtigung angezeigt werden, die angibt, dass die App an einem bestimmten Port verfügbar ist. Wählen Sie "Im Browser öffnen" aus, um die App in einem neuen Browser-Tab zu starten. Wenn die White-Label-Fehlerseite angezeigt wird, funktioniert die Spring Boot-Anwendung.

  2. Beenden Sie die App wieder im Codespace-Terminal mit STRG+C.

  3. Öffnen Sie pom.xml , und fügen Sie die folgenden Abhängigkeiten hinzu:

    <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-openai</artifactId>
    <version>1.0.0-beta.16</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-core</artifactId>
    <version>1.55.3</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.16.0</version>
    <scope>compile</scope>
</dependency>

  4. Fügen Sie im selben Verzeichnis wie Application.java (src/main/java/com/example/restservice) eine Java-Datei namens ChatController.java hinzu, und kopieren Sie den folgenden Inhalt darin:

    package com.example.restservice;

import java.util.ArrayList;
import java.util.List;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;

import com.azure.ai.openai.OpenAIAsyncClient;
import com.azure.ai.openai.models.ChatChoice;
import com.azure.ai.openai.models.ChatCompletionsOptions;
import com.azure.ai.openai.models.ChatRequestMessage;
import com.azure.ai.openai.models.ChatRequestUserMessage;
import com.azure.ai.openai.models.ChatResponseMessage;
import com.azure.core.credential.TokenCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

@Configuration
class AzureConfig {
    // Reads the endpoint from environment variable AZURE_OPENAI_ENDPOINT
    @Value("${azure.openai.endpoint}")
    private String openAiEndpoint;

    // Provides a credential for local dev and production
    @Bean
    public TokenCredential tokenCredential() {
        return new DefaultAzureCredentialBuilder().build();
    }

    // Configures the OpenAIAsyncClient bean
    @Bean
    public OpenAIAsyncClient openAIClient(TokenCredential tokenCredential) {
        return new com.azure.ai.openai.OpenAIClientBuilder()
                .endpoint(openAiEndpoint)
                .credential(tokenCredential)
                .buildAsyncClient();
    }
}

@Controller
public class ChatController {
    private final OpenAIAsyncClient openAIClient;

    // Inject the OpenAIAsyncClient bean
    public ChatController(OpenAIAsyncClient openAIClient) {
        this.openAIClient = openAIClient;
    }

    @RequestMapping(value = "/", method = RequestMethod.GET)
    public String chatFormOrWithMessage(Model model, @RequestParam(value = "userMessage", required = false) String userMessage) {
        String aiResponse = null;
        if (userMessage != null && !userMessage.isBlank()) {

            // Create a list of chat messages
            List<ChatRequestMessage> chatMessages = new ArrayList<>();
            chatMessages.add(new ChatRequestUserMessage(userMessage));

            // Send the chat completion request
            String deploymentName = "gpt-4o-mini";
            StringBuilder serverResponse = new StringBuilder();
            var chatCompletions = openAIClient.getChatCompletions(
                deploymentName, 
                new ChatCompletionsOptions(chatMessages)
            ).block();
            if (chatCompletions != null) {
                for (ChatChoice choice : chatCompletions.getChoices()) {
                    ChatResponseMessage message = choice.getMessage();
                    serverResponse.append(message.getContent());
                }
            }
            aiResponse = serverResponse.toString();
        }
        model.addAttribute("aiResponse", aiResponse);
        return "chat";
    }
}

    Tipp

    Um die Dateien in diesem Lernprogramm zu minimieren, kombiniert der Code die Spring @Configuration - und @Controller Klassen in einer Datei. In der Produktion würden Sie normalerweise Konfiguration und Geschäftslogik für die Wartung trennen.

  5. Erstellen Sie unter "src/main/resources" ein Vorlagenverzeichnis , und fügen Sie eine chat.html mit dem folgenden Inhalt für die Chatschnittstelle hinzu:

    <!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>Azure OpenAI Chat</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body>
<div class="container py-4">
    <h2 class="mb-4">Azure OpenAI Chat</h2>
    <form action="/" method="get" class="d-flex mb-3">
        <input name="userMessage" class="form-control me-2" type="text" placeholder="Type your message..." autocomplete="off" required />
        <button class="btn btn-primary" type="submit">Send</button>
    </form>
    <div class="mb-3">
        <div th:if="${aiResponse}" class="alert alert-info">AI: <span th:text="${aiResponse}"></span></div>
    </div>
</div>
</body>
</html>

  6. Rufen Sie im Terminal Ihren OpenAI-Endpunkt ab:

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

  7. Führen Sie die App erneut aus, indem Sie AZURE_OPENAI_ENDPOINT mit seinem Wert aus der CLI-Ausgabe hinzufügen.

    AZURE_OPENAI_ENDPOINT=<output-from-previous-cli-command> mvn spring-boot:run

  8. Wählen Sie "Im Browser öffnen " aus, um die App auf einer neuen Browserregisterkarte zu starten.

  9. Geben Sie eine Nachricht in das Textfeld ein, und wählen Sie "Senden" aus, und geben Sie der App ein paar Sekunden, um mit der Nachricht von Azure OpenAI zu antworten.

Die Anwendung verwendet DefaultAzureCredential, die automatisch Ihren azure CLI-Angemeldeten Benutzer für die Tokenauthentifizierung verwendet. Später in diesem Lernprogramm stellen Sie Ihre Web-App in Azure App Service bereit und konfigurieren sie so, dass eine sichere Verbindung mit Ihrer Azure OpenAI-Ressource mithilfe der verwalteten Identität hergestellt wird. Dasselbe DefaultAzureCredential in Ihrem Code kann die verwaltete Identität erkennen und für die Authentifizierung verwenden. Es ist kein zusätzlicher Code erforderlich.

3. Bereitstellen für Azure App Service und Konfigurieren der OpenAI-Verbindung

Nachdem Ihre App lokal funktioniert, stellen wir sie in Azure App Service bereit und richten eine Dienstverbindung mit Azure OpenAI mithilfe der verwalteten Identität ein.

  1. Erstellen Sie ein Bereitstellungspaket mit Maven.

    mvn clean package

  2. Stellen Sie zunächst Ihre App mit dem Azure CLI-Befehl in Azure App Service bereit az webapp up. Mit diesem Befehl wird eine neue Web-App erstellt und Ihr Code darauf bereitgestellt:

    az webapp up \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION \
  --name $APPSERVICE_NAME \
  --plan $APPSERVICE_NAME \
  --sku B1 \
  --runtime "JAVA:21" \
  --os-type Linux \
  --track-status false

    Die Ausführung dieses Befehls kann einige Minuten dauern. Sie erstellt eine neue Web-App in derselben Ressourcengruppe wie Ihre OpenAI-Ressource.

  3. Erstellen Sie nach der Bereitstellung der App eine Dienstverbindung zwischen Ihrer Web-App und der Azure OpenAI-Ressource mit verwalteter Identität:

    az webapp connection create cognitiveservices \
  --resource-group $RESOURCE_GROUP \
  --name $APPSERVICE_NAME \
  --target-resource-group $RESOURCE_GROUP \
  --account $OPENAI_SERVICE_NAME \
  --system-identity

    Dieser Befehl erstellt eine Verbindung zwischen Ihrer Web-App und der Azure OpenAI-Ressource durch:

    • Generieren der vom System zugewiesenen verwalteten Identität für die Web-App.
    • Hinzufügen der Rolle "Cognitive Services OpenAI-Mitwirkender" zur verwalteten Identität für die Azure OpenAI-Ressource.
    • Hinzufügen der AZURE_OPENAI_ENDPOINT App-Einstellung zu Ihrer Web-App.

  4. Öffnen Sie die bereitgestellte Web-App im Browser.

    az webapp browse

  5. Geben Sie eine Nachricht in das Textfeld ein, und wählen Sie "Senden" aus, und geben Sie der App ein paar Sekunden, um mit der Nachricht von Azure OpenAI zu antworten.

    Screenshot eines Chatbots, der in Azure App Service ausgeführt wird.

Ihre App wird jetzt bereitgestellt und mit Azure OpenAI mit verwalteter Identität verbunden. Beachten Sie, dass sie über die AZURE_OPENAI_ENDPOINT Injection auf die App-Einstellung zugreift.

Häufig gestellte Fragen

Warum verwendet das Beispiel @Configuration und Spring Beans für den OpenAI-Client?

Die Verwendung eines Spring-Beans für das OpenAIAsyncClient sorgt dafür, dass:

  • Alle Konfigurationseigenschaften (z. B. der Endpunkt) werden von Spring geladen und eingefügt.
  • Die Anmeldeinformationen und der Client werden erstellt, nachdem der Anwendungskontext vollständig initialisiert wurde.
  • Es wird Abhängigkeitsinjektion verwendet. Dies ist das standardmäßige und robusteste Muster in Spring-Anwendungen.

Der asynchrone Client ist robuster, insbesondere bei Verwendung der DefaultAzureCredential Azure CLI-Authentifizierung. Die synchrone OpenAIClient kann in einigen lokalen Entwicklungsszenarien Probleme beim Tokenerwerb haben. Die Verwendung des asynchronen Clients vermeidet diese Probleme und ist der empfohlene Ansatz.

Was geschieht, wenn ich anstelle von Azure OpenAI eine Verbindung mit OpenAI herstellen möchte?

Um stattdessen eine Verbindung mit OpenAI herzustellen, verwenden Sie den folgenden Code:

OpenAIClient client = new OpenAIClientBuilder()
    .credential(new KeyCredential(<openai-api-key>))
    .buildClient();

Weitere Informationen finden Sie unter OpenAI-API-Authentifizierung.

Wenn Sie mit Verbindungsschlüsseln in App Service arbeiten, sollten Sie Key Vault-Verweise verwenden, anstatt geheime Schlüssel direkt in Ihrer Codebasis zu speichern. Dadurch wird sichergestellt, dass vertrauliche Informationen sicher bleiben und zentral verwaltet werden.

Kann ich stattdessen eine Verbindung mit Azure OpenAI mit einem API-Schlüssel herstellen?

Ja, Sie können eine Verbindung mit Azure OpenAI mithilfe eines API-Schlüssels anstelle der verwalteten Identität herstellen. Dieser Ansatz wird von den Azure OpenAI-SDKs und dem semantischen Kernel unterstützt.

Wenn Sie mit Verbindungsschlüsseln in App Service arbeiten, sollten Sie Key Vault-Verweise verwenden, anstatt geheime Schlüssel direkt in Ihrer Codebasis zu speichern. Dadurch wird sichergestellt, dass vertrauliche Informationen sicher bleiben und zentral verwaltet werden.

Wie funktioniert DefaultAzureCredential in diesem Lernprogramm?

Die DefaultAzureCredential Authentifizierung wird vereinfacht, indem automatisch die beste verfügbare Authentifizierungsmethode ausgewählt wird:

  • Während der lokalen Entwicklung: Nach der Ausführung az loginwerden Ihre lokalen Azure CLI-Anmeldeinformationen verwendet.
  • Wenn sie in Azure App Service bereitgestellt wird: Sie verwendet die verwaltete Identität der App für sichere, kennwortlose Authentifizierung.

Mit diesem Ansatz kann Ihr Code ohne Änderungen sicher und nahtlos in lokalen und Cloudumgebungen ausgeführt werden.

Nächste Schritte