Zelfstudie: Een chatbot bouwen met Azure App Service en Azure OpenAI (Spring Boot)

In deze zelfstudie bouwt u een intelligente AI-toepassing door Azure OpenAI te integreren met een Java Spring Boot-toepassing en deze te implementeren in Azure App Service. U maakt een Spring Boot-controller die een query naar Azure OpenAI verzendt en het antwoord naar de browser verzendt.

In deze handleiding leer je hoe je:

Vereiste voorwaarden

• Een Azure-account met een actief abonnement
• Een GitHub-account voor het gebruik van GitHub Codespaces

1. Een Azure OpenAI-resource maken

In deze sectie gebruikt u GitHub Codespaces om een Azure OpenAI-resource te maken met de Azure CLI.

1. Ga naar GitHub Codespaces en meld u aan met uw GitHub-account.

2. Zoek de lege sjabloon op GitHub en selecteer Deze sjabloon gebruiken om een nieuwe lege Codespace te maken.

3. Installeer de Azure CLI in de Codespace-terminal:

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

4. Meld u aan bij uw Azure-account:

   az login
   

   Volg de instructies in de terminal om te verifiëren.

5. Stel omgevingsvariabelen in voor de naam van uw resourcegroep, azure OpenAI-servicenaam en -locatie:

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

   Belangrijk

   De regio is essentieel omdat deze is gekoppeld aan de regionale beschikbaarheid van het gekozen model. Beschikbaarheid van modellen en beschikbaarheid van implementatietypen variëren per regio. In deze zelfstudie wordt gebruikgemaakt van gpt-4o-mini, dat beschikbaar is in eastus2 onder het standaardimplementatietype. Als u in een andere regio implementeert, is dit model mogelijk niet beschikbaar of is er mogelijk een andere laag vereist. Voordat u regio's wijzigt, raadpleegt u de overzichtstabel model en de beschikbaarheid van regio's om de modelondersteuning in uw voorkeursregio te controleren.

6. Maak een resourcegroep en een Azure OpenAI-resource met een aangepast domein en voeg vervolgens een gpt-4o-minimodel toe:

   # 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
   

Nu u een Azure OpenAI-resource hebt, maakt u een webtoepassing om ermee te communiceren.

2. Een Spring Boot-web-app maken en instellen

1. Kloon in uw Codespace-terminal het Spring Boot REST-voorbeeld naar de werkruimte en probeer het de eerste keer uit te voeren.

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

   U ziet een melding in GitHub Codespaces die aangeeft dat de app beschikbaar is op een specifieke poort. Selecteer Openen in de browser om de app te starten op een nieuw browsertabblad. Wanneer u de foutpagina met witte labels ziet, werkt de Spring Boot-app.

2. Stop de app in de Codespace-terminal met Ctrl+C.

3. Open pom.xml en voeg de volgende afhankelijkheden toe:

   <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. Voeg in dezelfde map als Application.java (src/main/java/com/example/restservice) een Java-bestand met de naam ChatController.java toe en kopieer de volgende inhoud erin:

   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";
       }
   }
   

   Aanbeveling

   Als u de bestanden in deze zelfstudie wilt minimaliseren, combineert de code de Spring @Configuration - en @Controller klassen in één bestand. In productie zou u normaal gesproken configuratie- en bedrijfslogica scheiden voor onderhoudbaarheid.

5. Maak onder src/main/resources een map met sjablonen en voeg een chat.html toe met de volgende inhoud voor de chatinterface:

   <!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. Haal in de terminal het OpenAI-eindpunt op:

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

7. Voer de app opnieuw uit door AZURE_OPENAI_ENDPOINT toe te voegen met de waarde ervan uit de CLI-uitvoer:

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

8. Selecteer Openen in de browser om de app te starten op een nieuw browsertabblad.

9. Typ een bericht in het tekstvak en selecteer Verzenden en geef de app een paar seconden om het bericht van Azure OpenAI te beantwoorden.

De toepassing maakt gebruik van DefaultAzureCredential, die automatisch gebruikmaakt van uw azure CLI-aangemelde gebruiker voor tokenverificatie. Verderop in deze zelfstudie implementeert u uw web-app in Azure App Service en configureert u deze om veilig verbinding te maken met uw Azure OpenAI-resource met behulp van een beheerde identiteit. Hetzelfde DefaultAzureCredential in uw code kan de beheerde identiteit detecteren en gebruiken voor verificatie. Er is geen extra code nodig.

3. Implementeren in Azure App Service en OpenAI-verbinding configureren

Nu uw app lokaal werkt, gaan we deze implementeren in Azure App Service en een serviceverbinding met Azure OpenAI instellen met behulp van beheerde identiteit.

1. Maak een implementatiepakket met Maven.

   mvn clean package
   

2. Implementeer eerst uw app in Azure App Service met behulp van de Azure CLI-opdracht az webapp up. Met deze opdracht maakt u een nieuwe web-app en implementeert u hier uw code in:

   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
   

   Het kan enkele minuten duren voordat deze opdracht is voltooid. Er wordt een nieuwe web-app gemaakt in dezelfde resourcegroep als uw OpenAI-resource.

3. Nadat de app is geïmplementeerd, maakt u een serviceverbinding tussen uw web-app en de Azure OpenAI-resource met behulp van een beheerde identiteit:

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

   Met deze opdracht maakt u een verbinding tussen uw web-app en de Azure OpenAI-resource door:

   • Door het systeem toegewezen beheerde identiteit voor de web-app genereren.
   • De rol Cognitive Services OpenAI-inzender toevoegen aan de beheerde identiteit voor de Azure OpenAI-resource.
   • AZURE_OPENAI_ENDPOINT De app-instelling toevoegen aan uw web-app.

4. Open de geïmplementeerde web-app in de browser.

   az webapp browse
   

5. Typ een bericht in het tekstvak en selecteer Verzenden en geef de app een paar seconden om het bericht van Azure OpenAI te beantwoorden.

   

Uw app is nu geïmplementeerd en verbonden met Azure OpenAI met beheerde identiteit. Houd er rekening mee dat het toegang heeft tot de AZURE_OPENAI_ENDPOINT app-instelling via de @Configuration injectie.

Veelgestelde vragen

• Waarom gebruikt het voorbeeld @Configuration Spring-beans voor de OpenAI-client?
• Wat moet ik doen als ik verbinding wil maken met OpenAI in plaats van Azure OpenAI?
• Kan ik in plaats daarvan verbinding maken met Azure OpenAI met een API-sleutel?
• Hoe werkt DefaultAzureCredential in deze zelfstudie?

Waarom gebruikt het voorbeeld @Configuration en Spring beans voor de OpenAI-client?

Het gebruik van een Spring bean voor OpenAIAsyncClient zorgt ervoor dat:

• Alle configuratie-eigenschappen (zoals het eindpunt) worden geladen en geïnjecteerd door Spring.
• De referentiegegevens en cliënt worden gemaakt nadat de toepassingscontext volledig is geïnitialiseerd.
• Afhankelijkheidsinjectie wordt gebruikt. Dit is het standaard en meest robuuste patroon in Spring-toepassingen.

De asynchrone client is robuuster, met name bij gebruik DefaultAzureCredential met Azure CLI-verificatie. De synchrone OpenAIClient kan problemen ondervinden bij het verkrijgen van tokens in sommige lokale ontwikkelscenario's. Het gebruik van de asynchrone client voorkomt deze problemen en is de aanbevolen aanpak.

Wat moet ik doen als ik verbinding wil maken met OpenAI in plaats van Azure OpenAI?

Gebruik in plaats daarvan de volgende code om verbinding te maken met OpenAI:

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

Zie OpenAI API-verificatie voor meer informatie.

Wanneer u werkt met verbindingsgeheimen in App Service, moet u Key Vault-verwijzingen gebruiken in plaats van geheimen rechtstreeks op te slaan in uw codebasis. Dit zorgt ervoor dat gevoelige informatie veilig blijft en centraal wordt beheerd.

Kan ik in plaats daarvan verbinding maken met Azure OpenAI met een API-sleutel?

Ja, u kunt verbinding maken met Azure OpenAI met behulp van een API-sleutel in plaats van een beheerde identiteit. Deze benadering wordt ondersteund door de Azure OpenAI SDK's en Semantische kernel.

• Voor meer informatie over het gebruik van API-sleutels met Semantic Kernel: Semantic Kernel C# Quickstart.
• Voor meer informatie over het gebruik van API-sleutels met de Azure OpenAI-clientbibliotheek: Quickstart: Aan de slag met chatvoltooiingen met De Azure OpenAI-service.

Wanneer u werkt met verbindingsgeheimen in App Service, moet u Key Vault-verwijzingen gebruiken in plaats van geheimen rechtstreeks op te slaan in uw codebasis. Dit zorgt ervoor dat gevoelige informatie veilig blijft en centraal wordt beheerd.

Hoe werkt DefaultAzureCredential in deze zelfstudie?

De DefaultAzureCredential verificatie vereenvoudigt door automatisch de best beschikbare verificatiemethode te selecteren:

• Tijdens de lokale ontwikkeling: Nadat u deze hebt uitgevoerd az login, worden uw lokale Azure CLI-referenties gebruikt.
• Wanneer deze wordt geïmplementeerd in Azure App Service: de beheerde identiteit van de app wordt gebruikt voor veilige, wachtwoordloze verificatie.

Met deze aanpak kan uw code veilig en naadloos worden uitgevoerd in zowel lokale als cloudomgevingen zonder aanpassingen.

Volgende stappen

• Handleiding: Bouw een Retrieval Augmented Generation met Azure OpenAI en Azure AI Search (Spring Boot)
• Handleiding: Chatbot uitvoeren in App Service met een Phi-4 sidecar-extensie (Spring Boot)
• Een Azure OpenAI-serviceresource maken en implementeren
• Azure App Service configureren
• Beheerde identiteit inschakelen voor uw app
• Java configureren in Azure App Service