Självstudie: Skapa en chattrobot med Azure App Service och Azure OpenAI (Spring Boot)

I den här självstudien skapar du ett intelligent AI-program genom att integrera Azure OpenAI med ett Java Spring Boot-program och distribuera det till Azure App Service. Du skapar en Spring Boot-kontrollant som skickar en fråga till Azure OpenAI och skickar svaret till webbläsaren.

Tips/Råd

I den här självstudien används Spring Boot, men huvudbegreppen för att skapa ett chattprogram med Azure OpenAI gäller för alla Java-webbappar. Om du använder ett annat värdalternativ i App Service, till exempel Tomcat eller JBoss EAP, kan du anpassa autentiseringsmönstren och Azure SDK-användningen som visas här till önskat ramverk.

I den här tutorialen lär du dig följande:

• Skapa en Azure OpenAI-resurs och distribuera en språkmodell.
• Skapa ett Spring Boot-program som ansluter till Azure OpenAI.
• Använd beroendeinmatning för att konfigurera Azure OpenAI-klienten.
• Distribuera programmet till Azure App Service.
• Implementera lösenordslös säker autentisering både i utvecklingsmiljön och i Azure.

Förutsättningar

• Ett Azure-konto med en aktiv prenumeration
• Ett GitHub-konto för att använda GitHub Codespaces

1. Skapa en Azure OpenAI-resurs

I det här avsnittet använder du GitHub Codespaces för att skapa en Azure OpenAI-resurs med Azure CLI.

1. Gå till GitHub Codespaces och logga in med ditt GitHub-konto.

2. Leta upp den tomma mallen från GitHub och välj Använd den här mallen för att skapa ett nytt tomt kodområde.

3. Installera Azure CLI i Codespace-terminalen:

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

4. Logga in på ditt Azure-konto:

   az login
   

   Följ anvisningarna i terminalen för att autentisera.

5. Ange miljövariabler för resursgruppens namn, Azure OpenAI-tjänstnamn och plats:

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

   Viktigt!

   Regionen är kritisk eftersom den är kopplad till den valda modellens regionala tillgänglighet. Modelltillgänglighet och tillgänglighet för distributionstyp varierar från region till region. Handledningen använder gpt-4o-mini, som finns i eastus2 under standardmodellen. Om du distribuerar till en annan region kanske den här modellen inte är tillgänglig eller kräver en annan nivå. Innan du ändrar regioner läser du tabellen Modellsammanfattning och regiontillgänglighet för att verifiera modellstöd i önskad region.

6. Skapa en resursgrupp och en Azure OpenAI-resurs med en anpassad domän och lägg sedan till en gpt-4o-mini-modell:

   # 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 när du har en Azure OpenAI-resurs skapar du ett webbprogram för att interagera med den.

2. Skapa och konfigurera en Spring Boot-webbapp

1. I codespace-terminalen klonar du Spring Boot REST-exemplet till arbetsytan och försöker köra det första gången.

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

   Du bör se ett meddelande i GitHub Codespaces som anger att appen är tillgänglig på en specifik port. Välj Öppna i webbläsaren för att starta appen på en ny webbläsarflik. När du ser felsidan för vit etikett fungerar Spring Boot-appen.

2. Gå tillbaka till Codespace-terminalen och stoppa appen med Ctrl+C.

3. Öppna pom.xml och lägg till följande beroenden:

   <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. I samma katalog som Application.java (src/main/java/com/example/restservice) lägger du till en Java-fil med namnet ChatController.java och kopierar följande innehåll till den:

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

   Tips/Råd

   För att minimera filerna i den här självstudien kombinerar koden Spring @Configuration och @Controller klasser i en fil. I produktion skulle du normalt separera konfiguration och affärslogik för underhåll.

5. Under src/main/resources skapar du en mallkatalog och lägger till en chat.html med följande innehåll för chattgränssnittet:

   <!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. Hämta OpenAI-slutpunkten i terminalen:

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

7. Kör appen igen genom att lägga till AZURE_OPENAI_ENDPOINT med dess värde från CLI-utdata:

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

8. Välj Öppna i webbläsaren för att starta appen på en ny webbläsarflik.

9. Skriv ett meddelande i textrutan och välj Skicka och ge appen några sekunder att svara med meddelandet från Azure OpenAI.

Programmet använder DefaultAzureCredential, som automatiskt använder din Azure CLI-inloggade användare för tokenautentisering. Senare i den här självstudien distribuerar du webbappen till Azure App Service och konfigurerar den för att ansluta på ett säkert sätt till din Azure OpenAI-resurs med hjälp av hanterad identitet. Samma DefaultAzureCredential i din kod kan identifiera den hanterade identiteten och använda den för autentisering. Ingen extra kod behövs.

3. Distribuera till Azure App Service och konfigurera OpenAI-anslutning

Nu när din app fungerar lokalt ska vi distribuera den till Azure App Service och konfigurera en tjänstanslutning till Azure OpenAI med hjälp av hanterad identitet.

1. Skapa ett distributionspaket med Maven.

   mvn clean package
   

2. Distribuera först din app till Azure App Service med hjälp av Azure CLI-kommandot az webapp up. Det här kommandot skapar en ny webbapp och distribuerar koden till den:

   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
   

   Det kan ta några minuter att slutföra det här kommandot. Den skapar en ny webbapp i samma resursgrupp som din OpenAI-resurs.

3. När appen har distribuerats skapar du en tjänstanslutning mellan webbappen och Azure OpenAI-resursen med hjälp av hanterad identitet:

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

   Det här kommandot skapar en anslutning mellan webbappen och Azure OpenAI-resursen genom att:

   • Generera systemtilldelad hanterad identitet för webbappen.
   • Lägga till rollen som deltagare i Cognitive Services OpenAI till den hanterade identiteten för Azure OpenAI-resursen.
   • Lägga till appinställningen AZURE_OPENAI_ENDPOINT i webbappen.

4. Öppna den distribuerade webbappen i webbläsaren.

   az webapp browse
   

5. Skriv ett meddelande i textrutan och välj "Skicka och ge appen några sekunder att svara med meddelandet från Azure OpenAI.

   

Din app har nu distribuerats och anslutits till Azure OpenAI med hanterad identitet. Observera att appinställningen AZURE_OPENAI_ENDPOINT nås via @Configuration-injektionen.

Vanliga frågor

• Varför använder @Configuration exemplet och Spring beans för OpenAI-klienten?
• Vad händer om jag vill ansluta till OpenAI i stället för Azure OpenAI?
• Kan jag ansluta till Azure OpenAI med en API-nyckel i stället?
• Hur fungerar DefaultAzureCredential i den här självstudien?

Varför använder exemplet @Configuration och Spring beans för OpenAI-klienten?

Genom att använda en Spring-böna för OpenAIAsyncClient säkerställer att:

• Alla konfigurationsegenskaper (till exempel slutpunkten) läses in och matas in av Spring.
• Autentiseringsuppgifterna och klienten skapas när programkontexten har initierats helt.
• Beroendeinmatning används, vilket är det standardmässiga och mest robusta mönstret i Spring-program.

Den asynkrona klienten är mer robust, särskilt när du använder DefaultAzureCredential med Azure CLI-autentisering. Synkrona OpenAIClient kan stöta på problem med tokenförvärv i vissa lokala utvecklingsscenarier. Med hjälp av den asynkrona klienten undviker du dessa problem och är den rekommenderade metoden.

---

Vad händer om jag vill ansluta till OpenAI i stället för Azure OpenAI?

Om du vill ansluta till OpenAI i stället använder du följande kod:

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

Mer information finns i OpenAI API-autentisering.

När du arbetar med anslutningshemligheter i App Service bör du använda Key Vault-referenser i stället för att lagra hemligheter direkt i din kodbas. Detta säkerställer att känslig information förblir säker och hanteras centralt.

---

Kan jag ansluta till Azure OpenAI med en API-nyckel i stället?

Ja, du kan ansluta till Azure OpenAI med hjälp av en API-nyckel i stället för hanterad identitet. Den här metoden stöds av Azure OpenAI SDK:er och semantisk kernel.

• Mer information om hur du använder API-nycklar med semantisk kernel: Semantisk kernel-C#-snabbstart.
• Mer information om hur du använder API-nycklar med Azure OpenAI-klientbiblioteket: Snabbstart: Kom igång med chatten med Azure OpenAI Service.

När du arbetar med anslutningshemligheter i App Service bör du använda Key Vault-referenser i stället för att lagra hemligheter direkt i din kodbas. Detta säkerställer att känslig information förblir säker och hanteras centralt.

---

Hur fungerar DefaultAzureCredential i den här självstudien?

Det DefaultAzureCredential förenklar autentiseringen genom att automatiskt välja den bästa tillgängliga autentiseringsmetoden:

• Under lokal utveckling: När du har kört az loginanvänder den dina lokala Azure CLI-autentiseringsuppgifter.
• När den distribueras till Azure App Service: Den använder appens hanterade identitet för säker, lösenordslös autentisering.

Med den här metoden kan koden köras säkert och sömlöst i både lokala miljöer och molnmiljöer utan ändringar.

Nästa steg

• Självstudie: Bygg en Retrieval Augmented Generation med Azure OpenAI och Azure AI Search (Spring Boot)
• Självstudie: Köra chattrobot i App Service med ett Phi-4 sidecar-tillägg (Spring Boot)
• Skapa och distribuera en Azure OpenAI Service-resurs
• Konfigurera Azure App Service
• Aktivera hanterad identitet för din app
• Konfigurera Java på Azure App Service