Tutorial: Creación de un bot de chat con Azure App Service y Azure OpenAI (Spring Boot)

2025-05-20

En este tutorial, creará una aplicación de inteligencia artificial inteligente mediante la integración de Azure OpenAI con una aplicación de Java Spring Boot e implementarla en Azure App Service. Creará un controlador de Spring Boot que envíe una consulta a Azure OpenAI y enviará la respuesta al explorador.

Sugerencia

Aunque en este tutorial se usa Spring Boot, los conceptos básicos de la creación de una aplicación de chat con Azure OpenAI se aplican a cualquier aplicación web de Java. Si usa una opción de hospedaje diferente en App Service, como Tomcat o JBoss EAP, puede adaptar los patrones de autenticación y el uso del SDK de Azure que se muestran aquí a su marco preferido.

Captura de pantalla que muestra un bot de chat que se ejecuta en Azure App Service.

En este tutorial, aprenderá a:

Cree un recurso de Azure OpenAI e implemente un modelo de lenguaje.
Cree una aplicación de Spring Boot que se conecte a Azure OpenAI.
Use la inserción de dependencias para configurar el cliente de Azure OpenAI.
Implemente la aplicación en Azure App Service.
Implemente la autenticación segura sin contraseña tanto en el entorno de desarrollo como en Azure.

Prerrequisitos

Una cuenta de Azure con una suscripción activa
Una cuenta de GitHub para usar GitHub Codespaces

1. Creación de un recurso de Azure OpenAI

En esta sección, usará GitHub Codespaces para crear un recurso de Azure OpenAI con la CLI de Azure.

Vaya a GitHub Codespaces e inicie sesión con su cuenta de GitHub.
Busque la plantilla En blanco de GitHub y seleccione Usar esta plantilla para crear un nuevo espacio de código en blanco.

En el terminal de Codespace, instale la CLI de Azure:

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

Inicio de sesión en la cuenta de Azure
```
az login
```
Siga las instrucciones del terminal para autenticarse.
Establezca variables de entorno para el nombre del grupo de recursos, el nombre del servicio Azure OpenAI y la ubicación:
```
export RESOURCE_GROUP="<group-name>"
export OPENAI_SERVICE_NAME="<azure-openai-name>"
export APPSERVICE_NAME="<app-name>"
export LOCATION="eastus2"
```
Importante

La región es fundamental, ya que está vinculada a la disponibilidad regional del modelo elegido. La disponibilidad del modelo y el tipo de implementación varían de región a región. En este tutorial se utiliza gpt-4o-mini, que está disponible en eastus2 bajo el tipo de implementación estándar. Si implementa en otra región, es posible que este modelo no esté disponible o que requiera un nivel diferente. Antes de cambiar las regiones, consulte la tabla de resumen del modelo y la disponibilidad de regiones para comprobar la compatibilidad del modelo en su región preferida.

Cree un grupo de recursos y un recurso de Azure OpenAI con un dominio personalizado y agregue un modelo 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

Ahora que tiene un recurso de Azure OpenAI, creará una aplicación web para interactuar con él.

2. Creación y configuración de una aplicación web de Spring Boot

En el terminal de Codespaces, clone el ejemplo REST de Spring Boot en el área de trabajo y pruébelo por primera vez.
```
git clone https://github.com/rd-1-2022/rest-service .
mvn spring-boot:run
```
Debería ver una notificación en GitHub Codespaces que indica que la aplicación está disponible en un puerto específico. Seleccione Abrir en el explorador para iniciar la aplicación en una nueva pestaña del explorador. Cuando vea la página de error de la etiqueta blanca, la aplicación Spring Boot funciona.
De nuevo en el terminal codespace, detenga la aplicación con Ctrl+C.

Abra pom.xml y agregue las siguientes dependencias:

<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>

En el mismo directorio que Application.java (src/main/java/com/example/restservice) agregue un archivo Java denominado ChatController.java y copie el siguiente contenido en él:

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

Sugerencia

Para minimizar los archivos de este tutorial, el código combina las clases Spring @Configuration y @Controller en un archivo. En producción, normalmente se separan la configuración y la lógica empresarial para mantener la facilidad de mantenimiento.

En src/main/resources, cree un directorio templates y agregue un chat.html con el siguiente contenido para la interfaz de chat:

<!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>

En el terminal, recupere el punto de conexión de OpenAI:

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

Vuelva a ejecutar la aplicación agregando AZURE_OPENAI_ENDPOINT con su valor a partir de la salida de la CLI:
```
AZURE_OPENAI_ENDPOINT=<output-from-previous-cli-command> mvn spring-boot:run
```
Seleccione Abrir en el explorador para iniciar la aplicación en una nueva pestaña del explorador.
Escriba un mensaje en el cuadro de texto y seleccione "Enviar" y proporcione a la aplicación unos segundos para responder con el mensaje de Azure OpenAI.

La aplicación usa DefaultAzureCredential, que usa automáticamente la CLI de Azure que inició sesión en el usuario para la autenticación de tokens. Más adelante en este tutorial, implementará la aplicación web en Azure App Service y la configurará para conectarse de forma segura al recurso de Azure OpenAI mediante la identidad administrada. El mismo DefaultAzureCredential en su código puede detectar la identidad administrada y utilizarla para la autenticación. No se necesita código adicional.

3. Implementación en Azure App Service y configuración de la conexión de OpenAI

Ahora que la aplicación funciona localmente, vamos a implementarla en Azure App Service y configurar una conexión de servicio a Azure OpenAI mediante la identidad administrada.

Cree un paquete de implementación con Maven.
```
mvn clean package
```
En primer lugar, implemente la aplicación en Azure App Service mediante el comando az webapp upde la CLI de Azure. Este comando crea una nueva aplicación web e implementa el código en ella:
```
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
```
Este comando puede tardar unos minutos en completarse. Crea una nueva aplicación web en el mismo grupo de recursos que el recurso de OpenAI.
Una vez implementada la aplicación, cree una conexión de servicio entre la aplicación web y el recurso de Azure OpenAI mediante la identidad administrada:
```
az webapp connection create cognitiveservices \
  --resource-group $RESOURCE_GROUP \
  --name $APPSERVICE_NAME \
  --target-resource-group $RESOURCE_GROUP \
  --account $OPENAI_SERVICE_NAME \
  --system-identity
```
Este comando crea una conexión entre la aplicación web y el recurso de Azure OpenAI mediante:
- Generación de una identidad administrada asignada por el sistema para la aplicación web.
- Agregando el rol de Colaborador de OpenAI de Cognitive Services a la identidad administrada del recurso de Azure OpenAI.
- Añadiendo la configuración de la aplicación AZURE_OPENAI_ENDPOINT a tu aplicación web.
Abra la aplicación web implementada en el explorador.
```
az webapp browse
```
Escriba un mensaje en el cuadro de texto y seleccione "Enviar" y proporcione a la aplicación unos segundos para responder con el mensaje de Azure OpenAI.

La aplicación ahora está implementada y conectada a Azure OpenAI con identidad administrada. Tenga en cuenta que está accediendo a la configuración de la aplicación AZURE_OPENAI_ENDPOINT a través de la inyección @Configuration.

Preguntas más frecuentes

¿Por qué el ejemplo usa @Configuration y beans de Spring para el cliente de OpenAI?
¿Qué ocurre si quiero conectarse a OpenAI en lugar de Azure OpenAI?
¿Puedo conectarse a Azure OpenAI con una clave de API en su lugar?
¿Cómo funciona DefaultAzureCredential en este tutorial?

¿Por qué el ejemplo utiliza `@Configuration` y beans de Spring para el cliente de OpenAI?

El uso de un bean de Spring para OpenAIAsyncClient garantiza que:

Spring carga e inserta todas las propiedades de configuración (como el punto de conexión).
Las credenciales y el cliente se crean después de inicializar completamente el contexto de la aplicación.
La inyección de dependencias se utiliza, la cual constituye el patrón estándar y más sólido en las aplicaciones Spring.

El cliente asincrónico es más sólido, especialmente cuando se usa DefaultAzureCredential con la autenticación de la CLI de Azure. OpenAIClient de modo sincrónico puede encontrar problemas con la adquisición de tokens en algunos escenarios de desarrollo local. El uso del cliente asincrónico evita estos problemas y es el enfoque recomendado.

¿Qué ocurre si quiero conectarse a OpenAI en lugar de Azure OpenAI?

Para conectarse a OpenAI en su lugar, use el código siguiente:

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

Para más información, consulte Autenticación de API de OpenAI.

Al trabajar con secretos de conexión en App Service, debe usar referencias de Key Vault en lugar de almacenar secretos directamente en el código base. Esto garantiza que la información confidencial permanece segura y se administra de forma centralizada.

¿Puedo conectarse a Azure OpenAI con una clave de API en su lugar?

Sí, puede conectarse a Azure OpenAI mediante una clave de API en lugar de una identidad administrada. Este enfoque es compatible con los SDK de Azure OpenAI y el kernel semántico.

Para más información sobre el uso de claves de API con Semantic Kernel: Guía rápida de C# del Semantic Kernel.
Para más información sobre el uso de claves de API con la biblioteca cliente de Azure OpenAI: Guía rápida: Comience a utilizar las finalizaciones de chat con el servicio Azure OpenAI.

¿Cómo funciona DefaultAzureCredential en este tutorial?

Simplifica DefaultAzureCredential la autenticación seleccionando automáticamente el mejor método de autenticación disponible:

Durante el desarrollo local: después de ejecutar az login, usa las credenciales de la CLI de Azure local.
Cuando se implementa en Azure App Service: usa la identidad administrada de la aplicación para la autenticación segura sin contraseña.

Este enfoque permite que el código se ejecute de forma segura y sin problemas en entornos locales y en la nube sin modificaciones.

Compartir a través de