Tutorial: Creación de una aplicación de generación aumentada de recuperación en Azure App Service con Azure OpenAI y Búsqueda de Azure AI (Spring Boot)

En este tutorial, crearás una aplicación de Java Generación Aumentada por Recuperación (RAG) mediante Spring Boot, Azure OpenAI y Búsqueda de Azure AI e implementarla en Azure App Service. Esta aplicación muestra cómo implementar una interfaz de chat que recupera información de sus propios documentos y aprovecha los servicios de inteligencia artificial en Azure para proporcionar respuestas precisas y contextuales con citas adecuadas. La solución usa identidades administradas para la autenticación sin contraseña entre servicios.

Captura de pantalla que muestra la interfaz de chat de Spring Boot en la introducción.

En este tutorial, aprenderá a:

Introducción a la arquitectura

Antes de comenzar la implementación, resulta útil comprender la arquitectura de la aplicación que va a compilar. El siguiente diagrama procede del patrón RAG Personalizado de Búsqueda de Azure AI:

Diagrama de arquitectura que muestra una aplicación web que se conecta a Azure OpenAI y Búsqueda de Azure AI, con almacenamiento como origen de datos

En este tutorial, la aplicación Blazer en App Service se encarga tanto de la experiencia de usuario de la aplicación como del servidor de aplicaciones. Sin embargo, no realiza una consulta de conocimiento independiente para Búsqueda de Azure AI. En su lugar, indica a Azure OpenAI que realice la consulta de conocimientos que especifica Búsqueda de Azure AI como origen de datos. Esta arquitectura ofrece varias ventajas clave:

• Vectorización integrada: las funcionalidades de vectorización integrada de Búsqueda de Azure AI facilitan y rápido la ingesta de todos los documentos para buscar, sin necesidad de más código para generar incrustaciones.
• Simplified API Access: Al utilizar el patrón Azure OpenAI On Your Data con Búsqueda de Azure AI como fuente de datos para las completions de Azure OpenAI, no es necesario implementar una compleja búsqueda de vectores ni la generación de incrustaciones. Es solo una llamada API y Azure OpenAI controla todo, incluida la ingeniería de mensajes y la optimización de consultas.
• Funcionalidades avanzadas de búsqueda: la vectorización integrada proporciona todo lo necesario para la búsqueda híbrida avanzada con el reranking semántico, que combina los puntos fuertes de coincidencia de palabras clave, similitud de vectores y clasificación con tecnología de IA.
• Compatibilidad completa con citas: las respuestas incluyen automáticamente citas a documentos de origen, lo que hace que la información sea verificable y rastreable.

Prerrequisitos

• Una cuenta de Azure con una suscripción activa: Crear una cuenta gratuita.
• GitHub cuenta para usar GitHub Codespaces: Learn más sobre GitHub Codespaces.

1. Abra el ejemplo con Codespaces

La manera más fácil de empezar es usar GitHub Codespaces, que proporciona un entorno de desarrollo completo con todas las herramientas necesarias preinstaladas.

1. Vaya al repositorio de GitHub en https://github.com/Azure-Samples/app-service-rag-openai-ai-search-java.

2. Seleccione el botón Código , seleccione la pestaña Codespaces y haga clic en Crear espacio de código en main.

3. Espere unos instantes para que codespace se inicialice. Cuando esté listo, verá un entorno de VS Code totalmente configurado en el explorador.

2. Implementación de la arquitectura de ejemplo

1. En el terminal, inicie sesión en Azure mediante Azure CLI para desarrolladores:

   azd auth login
   

   Siga las instrucciones para completar el proceso de autenticación.

2. Aprovisione los recursos de Azure con la plantilla AZD:

   azd provision
   

3. Cuando se le solicite, proporcione las siguientes respuestas:

   Pregunta	Respuesta
   Escriba un nuevo nombre de entorno:	Escriba un nombre único.
   Seleccione una suscripción de Azure que se va a usar:	Seleccione la suscripción.
   Elija un grupo de recursos para usar:	Seleccione Crear un grupo de recursos nuevo.
   Seleccione una ubicación para crear el grupo de recursos en:	Seleccione cualquier región. Los recursos se crearán realmente en East US 2.
   Escriba un nombre para el nuevo grupo de recursos:	Escriba Entrar.

4. Espere a que la implementación se complete. Este proceso hará lo siguiente:

   • Cree todos los recursos Azure necesarios.
   • Implemente la aplicación en Azure App Service.
   • Configure la autenticación segura entre servicios mediante identidades administradas.
   • Configure las asignaciones de roles necesarias para el acceso seguro entre los servicios.

   Nota:

   Para más información sobre cómo funcionan las identidades administradas, consulte ¿Qué son las identidades administradas para los recursos de Azure? y Cómo usar identidades administradas con App Service.

5. Después de una implementación correcta, verá una dirección URL para la aplicación implementada. Anote esta dirección URL, pero aún no tenga acceso a ella porque todavía necesita configurar el índice de búsqueda.

3. Cargar documentos y crear un índice de búsqueda

Ahora que se implementa la infraestructura, debe cargar documentos y crear un índice de búsqueda que usará la aplicación:

1. En el portal de Azure, vaya a la cuenta de almacenamiento que creó la implementación. El nombre comenzará con el nombre del entorno que proporcionó anteriormente.

2. Seleccione Contenedores de almacenamiento de datos en el menú de navegación izquierdo y abra el contenedor de documentos.

3. Para cargar documentos de ejemplo, haga clic en Cargar. Puede usar los documentos de ejemplo de la carpeta sample-docs en el repositorio, o sus propios archivos PDF, Word o de texto.

   Captura de pantalla que muestra cómo cargar documentos en el contenedor de almacenamiento.

4. Vaya al servicio Búsqueda de Azure AI en el portal de Azure.

5. Seleccione Importar datos (nuevo) para iniciar el proceso de creación de un índice de búsqueda.

   

6. En el paso Conectar a los datos:

   • Seleccione Azure Blob Storage como origen de datos.
   • Seleccione RAG.
   • Elija la cuenta de almacenamiento y el contenedor de documentos .
   • Seleccione Autenticar con identidad administrada.
   • Seleccione Siguiente.

7. En el paso Vectorizar el texto :

   • Seleccione su servicio Azure OpenAI.
   • Elija text-embeding-ada-002 como modelo de inserción. La plantilla AZD ya ha desplegado este modelo para ti.
   • Seleccione Identidad asignada por el sistema para la autenticación.
   • Seleccione la casilla de confirmación de costos adicionales.
   • Seleccione Siguiente.

   Sugerencia

   Obtenga más información sobre la búsqueda Vector en Búsqueda de Azure AI y incrustaciones de texto en Azure OpenAI.

8. En el paso Vectorize and enrich your images (Vectorizar y enriquecer las imágenes ):

   • Mantenga la configuración predeterminada.
   • Seleccione Siguiente.

9. En el paso Configuración avanzada :

   • Asegúrese de que habilitar el clasificador semántico está seleccionado.
   • (Opcional) Seleccione una programación de indexación. Esto resulta útil si desea actualizar el índice periódicamente con los cambios de archivo más recientes.
   • Seleccione Siguiente.

10. En el paso Revisar y crear :

    • Copiar el valor de Prefijo nombre de objetos. Es el nombre del índice de búsqueda.
    • Seleccione Crear para iniciar el proceso de indexación.

11. Espere a que se complete el proceso de indexación. Esto puede tardar unos minutos en función del tamaño y el número de documentos.

12. Para probar la importación de datos, seleccione Iniciar búsqueda e intente una consulta de búsqueda como "Cuéntame sobre su empresa".

13. De nuevo en el terminal de Codespace, establezca el nombre del índice de búsqueda como una variable de entorno de AZD:

    azd env set SEARCH_INDEX_NAME <your-search-index-name>
    

    Reemplace por el nombre de índice que copió anteriormente. AZD usa esta variable en implementaciones posteriores para establecer la configuración de la aplicación de App Service.

4. Probar la aplicación e implementar

Si prefiere probar la aplicación localmente antes o después de la implementación, puede ejecutarla directamente desde Codespace:

1. En el terminal de Codespace, obtenga los valores de entorno de AZD:

   azd env get-values
   

2. Abra src/main/resources/application.properties. Con la salida del terminal, actualice los valores siguientes, en los marcadores de posición respectivos :

   • azure.openai.endpoint
   • azure.search.url
   • azure.search.index.name

3. Inicie sesión en Azure con el CLI de Azure:

   az login
   

   Esto permite que la biblioteca cliente de Azure Identity del código de ejemplo reciba un token de autenticación para el usuario que ha iniciado sesión.

4. Ejecute la aplicación localmente:

   mvn spring-boot:run
   

5. Cuando vea La aplicación que se ejecuta en el puerto 8080 está disponible, seleccione Abrir en el explorador.

6. Pruebe a hacer algunas preguntas en la interfaz de chat. Si recibe una respuesta, la aplicación se conecta correctamente al recurso Azure OpenAI.

7. Detenga el servidor de desarrollo con Ctrl+C.

8. Aplique la nueva configuración de SEARCH_INDEX_NAME en Azure e implemente el código de aplicación de ejemplo:

   azd up
   

5. Probar la aplicación RAG implementada

Con la aplicación totalmente implementada y configurada, ahora puede probar la funcionalidad rag:

1. Abra la dirección URL de la aplicación proporcionada al final de la implementación.

2. Verá una interfaz de chat en la que puede escribir preguntas sobre el contenido de los documentos cargados.

   Captura de pantalla que muestra la interfaz de chat de Blazor.

3. Intente formular preguntas específicas del contenido de los documentos. Por ejemplo, si cargó los documentos en la carpeta sample-docs , puede probar estas preguntas:

   • ¿Cómo usa Contoso mis datos personales?
   • ¿Cómo presentar una reclamación de garantía?

4. Observe cómo las respuestas incluyen citas que hacen referencia a los documentos de origen. Estas citas ayudan a los usuarios a comprobar la precisión de la información y a encontrar más detalles en el material de origen.

   Captura de pantalla que muestra una respuesta con citas a documentos de origen.

5. Pruebe las funcionalidades de búsqueda híbrida mediante la formulación de preguntas que podrían beneficiarse de diferentes enfoques de búsqueda:

   • Preguntas con terminología específica (buena para la búsqueda de palabras clave).
   • Preguntas sobre los conceptos que se pueden describir mediante términos diferentes (adecuado para la búsqueda de vectores).
   • Preguntas complejas que requieren comprender el contexto (adecuado para la clasificación semántica).

Limpieza de recursos

Cuando haya terminado con la aplicación, puede eliminar todos los recursos para evitar incurrir en costos adicionales:

azd down --purge

Este comando elimina todos los recursos asociados a la aplicación.

Preguntas más frecuentes

• ¿Cómo recupera el código de ejemplo las citas de las finalizaciones de chat de Azure OpenAI?
• ¿Cuál es la ventaja de usar identidades administradas en esta solución?
• ¿Cómo se usa la identidad administrada asignada por el sistema en esta arquitectura y aplicación de ejemplo?
• ¿Cómo se implementa la búsqueda híbrida con clasificador semántico en la aplicación de ejemplo?
• ¿Por qué se crean todos los recursos en este de EE. UU. 2?
• Can uso mis propios modelos de OpenAI en lugar de los proporcionados por Azure?
• ¿Cómo puedo mejorar la calidad de las respuestas?

¿Cómo recupera el código de ejemplo las citas de las completaciones de chat de Azure OpenAI?

En el ejemplo se recuperan las citas mediante como origen de datos para el cliente de chat. Cuando se solicita una finalización del chat, la respuesta incluye un objeto dentro del contexto del mensaje. El código extrae estas citas de la siguiente manera:

public static ChatResponse fromChatCompletions(ChatCompletions completions) {
    ChatResponse response = new ChatResponse();
    
    if (completions.getChoices() != null && !completions.getChoices().isEmpty()) {
        var message = completions.getChoices().get(0).getMessage();
        if (message != null) {
            response.setContent(message.getContent());

            if (message.getContext() != null && message.getContext().getCitations() != null) {
                var azureCitations = message.getContext().getCitations();
                for (int i = 0; i < azureCitations.size(); i++) {
                    var azureCitation = azureCitations.get(i);
                    
                    Citation citation = new Citation();
                    citation.setIndex(i + 1);
                    citation.setTitle(azureCitation.getTitle());
                    citation.setContent(azureCitation.getContent());
                    citation.setFilePath(azureCitation.getFilepath());
                    citation.setUrl(azureCitation.getUrl());
                    
                    response.getCitations().add(citation);
                }
            }
        }
    }
    
    return response;
}

En la respuesta del chat, el contenido usa la notación para referenciar la cita correspondiente en la lista, lo que permite a los usuarios rastrear la información hasta los documentos de origen originales. Para obtener más información, consulte:

• Referencia de la API de Datos de Azure OpenAI
• origen Data: Búsqueda de Azure AI

¿Cuál es la ventaja de usar identidades administradas en esta solución?

Las identidades administradas eliminan la necesidad de almacenar credenciales en el código o la configuración. Mediante el uso de identidades administradas, la aplicación puede acceder de forma segura a servicios de Azure como Azure OpenAI y Búsqueda de Azure AI sin administrar secretos. Este enfoque sigue los principios de seguridad Confianza cero y reduce el riesgo de exposición de credenciales.

¿Cómo se usa la identidad administrada asignada por el sistema en esta arquitectura y aplicación de ejemplo?

La implementación de AZD crea identidades administradas asignadas por el sistema para Azure App Service, Azure OpenAI y Búsqueda de Azure AI. También realiza asignaciones de roles respectivas para cada una de ellas (consulte el archivo main.bicep ). Para obtener información sobre las asignaciones de roles necesarias, consulte Red y la configuración de acceso para Azure OpenAI sobre sus datos.

En la aplicación de ejemplo de Java, los SDKs de Azure usan esta identidad administrada para la autenticación segura, por lo que no necesitas almacenar credenciales ni secretos en ningún lugar. Por ejemplo, el OpenAIAsyncClient se inicializa con DefaultAzureCredential, que usa automáticamente la identidad administrada cuando se ejecuta en Azure:

@Bean
public TokenCredential tokenCredential() {
   return new DefaultAzureCredentialBuilder().build();
}

@Bean
public OpenAIAsyncClient openAIClient(TokenCredential tokenCredential) {
   return new OpenAIClientBuilder()
         .endpoint(openAiEndpoint)
         .credential(tokenCredential)
         .buildAsyncClient();
}

Del mismo modo, al configurar el origen de datos para Búsqueda de Azure AI, se especifica la identidad administrada para la autenticación:

AzureSearchChatExtensionConfiguration searchConfiguration =
   new AzureSearchChatExtensionConfiguration(
      new AzureSearchChatExtensionParameters(appSettings.getSearch().getUrl(), appSettings.getSearch().getIndex().getName())
         .setAuthentication(new OnYourDataSystemAssignedManagedIdentityAuthenticationOptions())
         // ...
   );

Esta configuración permite la comunicación segura y sin contraseña entre la aplicación de Spring Boot y los servicios de Azure, siguiendo los procedimientos recomendados para Confianza cero seguridad. Obtenga más información sobre DefaultAzureCredential y la biblioteca cliente de Azure Identity para Java.

¿Cómo se implementa la búsqueda híbrida con clasificador semántico en la aplicación de ejemplo?

La aplicación de muestra configura la búsqueda híbrida con clasificación semántica usando los SDKs de Java de Azure OpenAI y Búsqueda de Azure AI. En el back-end, el origen de datos se configura de la siguiente manera:

AzureSearchChatExtensionParameters parameters = new AzureSearchChatExtensionParameters(
   appSettings.getSearch().getUrl(),
   appSettings.getSearch().getIndex().getName())
    // ...
    .setQueryType(AzureSearchQueryType.VECTOR_SEMANTIC_HYBRID)
    .setEmbeddingDependency(new OnYourDataDeploymentNameVectorizationSource(appSettings.getOpenai().getEmbedding().getDeployment()))
    .setSemanticConfiguration(appSettings.getSearch().getIndex().getName() + "-semantic-configuration");

Esta configuración permite a la aplicación combinar la búsqueda vectorial (similitud semántica), la coincidencia de palabras clave y la clasificación semántica en una sola consulta. El clasificador semántico reordena los resultados para devolver las respuestas más relevantes y contextualmente adecuadas, que después usan Azure OpenAI para generar respuestas.

El nombre de configuración semántica se define automáticamente mediante el proceso de vectorización integrado. Usa el nombre del índice de búsqueda como prefijo y anexa como sufijo. Esto garantiza que la configuración semántica esté asociada de forma única con el índice correspondiente y siga una convención de nomenclatura coherente.

¿Por qué se crean todos los recursos en este de EE. UU. 2?

En el ejemplo se usan los modelos gpt-4o-mini y text-embedding-ada-002, ambos disponibles con el tipo de implementación Estándar en Este de EE. UU. 2. Estos modelos también se eligen porque no están programados para su retiro pronto, lo que proporciona estabilidad para el despliegue de muestra. La disponibilidad del modelo y los tipos de implementación pueden variar según la región, por lo que Este de EE. UU. 2 está seleccionado para asegurarse de que el ejemplo funcione sin problemas. Si desea usar una región o modelos diferentes, asegúrese de seleccionar los modelos que están disponibles para el mismo tipo de implementación en la misma región. Al elegir sus propios modelos, compruebe sus fechas de disponibilidad y retirada para evitar interrupciones.

• Disponibilidad de modelos: modelos de Azure OpenAI Service
• Fechas de retirada de modelos: Azure OpenAI Service descontinuaciones y retiradas de modelos.

¿Puedo usar mis propios modelos de OpenAI en lugar de los proporcionados por Azure?

Esta solución está diseñada para trabajar con Azure OpenAI Service. Aunque podría modificar el código para usar otros modelos de OpenAI, perdería las características de seguridad integradas, la compatibilidad con identidad administrada y la integración sin problemas con Búsqueda de Azure AI que proporciona esta solución.

¿Cómo puedo mejorar la calidad de las respuestas?

Puede mejorar la calidad de la respuesta mediante:

• Cargando documentos de mayor calidad y más relevantes.
• Ajuste de las estrategias de fragmentación en la canalización de indexación de Búsqueda de Azure AI. Sin embargo, no puede personalizar la fragmentación con la vectorización integrada que se muestra en este tutorial.
• Experimentos con distintas plantillas de instrucciones en el código de la aplicación.
• Ajuste de la búsqueda con otras propiedades de la clase AzureSearchChatExtensionParameters.
• Utilización de modelos más especializados de Azure OpenAI para su dominio específico.

Más recursos

• Explore las funcionalidades de búsqueda híbrida en Búsqueda de Azure AI
• Utiliza Azure OpenAI en tus datos
• Biblioteca cliente de Azure OpenAI para Java
• Ejemplos de la biblioteca de cliente de Azure OpenAI para Java