Tutorial: Creación de una aplicación de generación aumentada de recuperación en Azure App Service con Azure OpenAI y Azure AI Search (Express.js)

2025-05-20

En este tutorial, creará una aplicación de recuperación aumentada de generación (RAG) de Node.js mediante Express.js, Azure OpenAI y Búsqueda de Azure AI y la implementará 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 Azure AI para proporcionar respuestas precisas y contextuales con citas adecuadas. La solución usa identidades administradas para la autenticación sin contraseña entre servicios.

En este tutorial, aprenderá a:

Implemente una aplicación de Express.js que use el patrón RAG con los servicios de Azure AI.
Configure Azure OpenAI y Azure AI Search para la búsqueda híbrida.
Cargue e indexe documentos para su uso en la aplicación con tecnología de IA.
Use identidades administradas para la comunicación segura entre servicios.
Pruebe la implementación de RAG localmente con los servicios de producción.

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 para Azure AI Search:

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 a Azure AI Search. En su lugar, indica a Azure OpenAI que realice la consulta de conocimientos que especifica Azure AI Search como origen de datos. Esta arquitectura ofrece varias ventajas clave:

Vectorización integrada: las funcionalidades de vectorización integrada de Azure AI Search facilitan y rápida la ingesta de todos los documentos para realizar búsquedas, sin necesidad de más código para generar incrustaciones.
Acceso simplificado a la API: Al utilizar el patrón Azure OpenAI en tus datos con Azure AI Search como origen de datos para las finalizaciones de Azure OpenAI, no es necesario implementar una búsqueda de vectores compleja ni la generación de incrustaciones. Es solo una llamada API y Azure OpenAI controla todo, incluida la ingeniería rápida 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: cree una cuenta de forma gratuita.
Cuenta de GitHub para usar GitHub Codespaces: obtenga más información 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.

Vaya al repositorio de GitHub en https://github.com/Azure-Samples/app-service-rag-openai-ai-search-nodejs.
Seleccione el botón Código , seleccione la pestaña Codespaces y haga clic en Crear espacio de código en main.
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

En el terminal, inicie sesión en Azure mediante la CLI para desarrolladores de Azure:
```
azd auth login
```
Siga las instrucciones para completar el proceso de autenticación.
Aprovisione los recursos de Azure con la plantilla de AZD:
```
azd provision
```

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

Espere a que la implementación se complete. Este proceso hará lo siguiente:
- Cree todos los recursos de Azure necesarios.
- Implemente la aplicación Blazor 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 Uso de identidades administradas con App Service.
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:

En Azure Portal, vaya a la cuenta de almacenamiento que creó la implementación. El nombre comenzará con el nombre del entorno que proporcionó anteriormente.
Seleccione Contenedores en el menú de navegación izquierdo y abra el contenedor de documentos .
Para cargar documentos de ejemplo, haga clic en Cargar. Puede usar los documentos de ejemplo de la sample-docs carpeta del repositorio o sus propios archivos PDF, Word o texto.
Vaya al servicio de búsqueda de Azure AI en el portal de Azure.
Seleccione Importar y vectorizar datos para iniciar el proceso de creación de un índice de búsqueda.
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 .
- Asegúrese de que la opción Autenticar con identidad administrada está seleccionada.
- Seleccione Siguiente.
En el paso Vectorizar el texto :
- Seleccione el 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.
- Active la casilla confirmación para ver los costos adicionales.
- Seleccione Siguiente.
Sugerencia

Obtenga más información sobre la búsqueda vectorial en Azure AI Search e incrustaciones de texto en Azure OpenAI.
En el paso Vectorize and enrich your images (Vectorizar y enriquecer las imágenes ):
- Mantenga la configuración predeterminada.
- Seleccione Siguiente.
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.
En el paso Revisar y crear :
- Copie el valor de Prefijo nombre de objetos. Es el nombre del índice de búsqueda.
- Seleccione Crear para iniciar el proceso de indexación.
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.
Para probar la importación de datos, seleccione Iniciar búsqueda e intente una consulta de búsqueda como "Cuéntame sobre su empresa".
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 <your-search-index-name> 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:

En el terminal de Codespace, obtenga los valores de entorno de AZD:
```
azd env get-values
```
Abra .env. Con la salida del terminal, actualice los valores siguientes, en los marcadores de posición respectivos <input-manually-for-local-testing>:
- AZURE_OPENAI_ENDPOINT
- AZURE_SEARCH_SERVICE_URL
- AZURE_SEARCH_INDEX_NAME
Inicie sesión en Azure con la CLI de Azure:
```
az login
```
Esto permite que la biblioteca cliente de Identidad de Azure en el código de ejemplo reciba un token de autenticación para el usuario que ha iniciado sesión.
Ejecute la aplicación localmente:
```
npm run dev
```
Cuando vea La aplicación que se ejecuta en el puerto 8080 está disponible, seleccione Abrir en el explorador.
Pruebe a hacer algunas preguntas en la interfaz de chat. Si recibe una respuesta, la aplicación se conecta correctamente al recurso de Azure OpenAI.
Detenga el servidor de desarrollo con Ctrl+C.
Aplique la nueva SEARCH_INDEX_NAME configuración 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:

Abra la dirección URL de la aplicación proporcionada al final de la implementación.
Verá una interfaz de chat en la que puede escribir preguntas sobre el contenido de los documentos cargados.
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?
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.
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?
¿Puedo usar 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 finalizaciones de chat de Azure OpenAI?

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

const message = choice.message;
const content = message.content;
const citations = message.context?.citations || [];

En la respuesta del chat, el contenido usa la notación [doc#] 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:

¿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 Azure AI Search sin administrar secretos. Este enfoque sigue los principios de seguridad de 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 Azure AI Search. 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 Configuración de red y acceso para Azure OpenAI en tus datos.

En la aplicación de ejemplo Express.js, los SDK de Azure usan esta identidad administrada para la autenticación segura, por lo que no es necesario almacenar credenciales ni secretos en ningún lugar. Por ejemplo, AzureOpenAI se inicializa con DefaultAzureCredential, que usa automáticamente la identidad administrada cuando se ejecuta en Azure:

const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), scope);

// Initialize Azure OpenAI client with managed identity
this.openAIClient = new AzureOpenAI({
  azureADTokenProvider, 
  apiVersion: "2024-02-01", // Update this to a known working API version
  endpoint: this.config.openai.endpoint
});

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

const searchDataSource = {
  type: 'azure_search',
  parameters: {
    // ...
    authentication: {
      type: 'system_assigned_managed_identity'
    },
    // ...
  }
};

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

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

La aplicación de ejemplo configura la búsqueda híbrida con clasificación semántica mediante el SDK de Azure OpenAI. En el back-end, el origen de datos se configura de la siguiente manera:

const searchDataSource = {
  type: 'azure_search',
  parameters: {
    // ...
    query_type: 'vector_semantic_hybrid',
    semantic_configuration: `${this.config.search.index.name}-semantic-configuration`,
    embedding_dependency: {
      type: 'deployment_name',
      deployment_name: this.config.openai.embedding.deployment
    }
  }
};

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 usa 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 -semantic-configuration 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-embeding-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 del modelo: modelos del servicio Azure OpenAI
Fechas de retirada del modelo: las Retiradas y los desusos del modelo de Azure OpenAI Service.

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

Esta solución está diseñada para trabajar con el servicio Azure OpenAI. 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 Azure AI Search 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 Azure AI Search. 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 del origen de datostype: "azure_search.
Uso de modelos de Azure OpenAI más especializados para su dominio específico.

Compartir a través de