Tutorial: Parte 1: Configuración del entorno de proyecto y desarrollo para crear una aplicación de recuperación de conocimiento personalizada (RAG) con el SDK de Microsoft Foundry

En este tutorial, configurará los recursos necesarios para crear una aplicación de chat de recuperación de conocimiento personalizada (RAG) con el SDK de Microsoft Foundry. Esta es la primera parte de una serie de tutoriales de tres partes. Aquí creará los recursos, construirá la aplicación en la segunda parte y la evaluará en la tercera parte. En esta parte, hará lo siguiente:

Si completó otros tutoriales o inicios rápidos, es posible que ya haya creado algunos de los recursos necesarios para este tutorial. Si lo hizo, no dude en omitir esos pasos.

Prerrequisitos

• Una cuenta de Azure con una suscripción activa y el rol Propietario o Colaborador asignados. Si no tiene ninguna cuenta, cree una gratuita.
• Microsoft Foundry: rol propietario o colaborador para crear un proyecto.

Creación de un proyecto basado en concentrador

Para crear un proyecto basado en concentrador en Microsoft Foundry, siga estos pasos:

1. Inicie sesión en Microsoft Foundry. Asegúrese de que el conmutador New Foundry está desactivado. Estos pasos hacen referencia a Foundry (clásico).

   

2. Lo que haces a continuación depende de dónde estés:

   • Si no tiene ningún proyecto existente: siga los pasos descritos en Inicio rápido: Introducción a Microsoft Foundry para crear el primer proyecto.

   • Si está en un proyecto: seleccione la ruta de navegación del proyecto y, a continuación, seleccione Crear nuevo recurso.

     

   • Si no está en un proyecto: seleccione Crear nuevo en la parte superior derecha para crear un nuevo proyecto Foundry

     

3. Seleccione el recurso del centro de IA y luego seleccione Siguiente.

4. Escriba un nombre para el proyecto.

5. Si tienes un hub, verás seleccionado el que has usado más recientemente.

   • Si tiene acceso a más de un centro, puede seleccionar otro centro en la lista desplegable.

   • Si desea crear uno nuevo, seleccione Crear un nuevo centro en la lista desplegable.

     

6. Si no tiene un centro, se crea uno predeterminado automáticamente para usted.

7. Selecciona Crear.

Implementación de modelos

Necesita dos modelos para crear una aplicación de chat basada en RAG: un modelo de chat de Azure OpenAI (gpt-4o-mini) y un modelo de inserción de Azure OpenAI (text-embedding-ada-002). Implemente estos modelos en el proyecto foundry mediante este conjunto de pasos para cada modelo.

Estos pasos implementan un modelo en un punto de conexión en tiempo real desde el catálogo de modelos del portal de Foundry:

1. En el panel izquierdo, seleccione Catálogo de modelos.

2. Seleccione el modelo gpt-4o-mini en la lista de modelos. Puede usar la barra de búsqueda para encontrarlo.

   

3. En la página de detalles del modelo, seleccione Usar este modelo.

4. Deje el nombre de implementación predeterminado y seleccione Implementar. O bien, si el modelo no está disponible en su región, se selecciona una región diferente para usted y se conecta al proyecto. En este caso, seleccione Conectar e implementar.

Después de implementar el modelo gpt-4o-mini, repita los pasos para implementar el modelo text-embedding-ada-002.

Creación de un servicio de Búsqueda de Azure AI

El objetivo de esta aplicación es basar las respuestas del modelo en tus datos personalizados. El índice de búsqueda recupera documentos relevantes en función de la pregunta del usuario.

Necesita un servicio de Azure AI Search y una conexión para crear un índice de búsqueda.

Si ya tiene un servicio Azure AI Search, vaya a la sección siguiente.

De lo contrario, cree un servicio Azure AI Search mediante Azure Portal.

1. Creación de un servicio de Búsqueda de Azure AI en Azure Portal.
2. Seleccione los detalles del grupo de recursos y de la instancia. Consulte los precios y niveles de precios en esta página. Para este tutorial, use un plan de tarifa básico o superior.
3. Continúe con el asistente y seleccione Revisar y asignar para crear el recurso.
4. Confirme los detalles del servicio Azure AI Search, incluido el costo estimado.
5. Seleccione Crear para crear el servicio de Búsqueda de Azure AI.

Conexión de Azure AI Search al proyecto

Si el proyecto ya tiene una conexión de Azure AI Search, vaya a Instalación de la CLI de Azure e inicie sesión.

En el portal de Foundry, compruebe si hay un recurso conectado de Azure AI Search.

1. En Foundry, vaya al proyecto y seleccione Centro de administración en el panel izquierdo.

2. En la sección Recursos conectados, busque si tiene una conexión de tipo Búsqueda de Azure AI.

3. Si tiene una conexión de Azure AI Search, puede omitir los pasos siguientes.

4. De lo contrario, seleccione Nueva conexión y, a continuación, Búsqueda de Azure AI.

5. Busque el servicio de Búsqueda de Azure AI en las opciones y seleccione Agregar conexión.

6. Utilice la clave de API para la autenticación.

   Importante

   No se recomienda la opción de clave de API para producción. El enfoque recomendado es la autenticación de Id. de Entra de Microsoft , que requiere los roles Colaborador de datos del índice de búsqueda y Colaborador del servicio de búsqueda (configurados en Requisitos previos). Para más información, consulte Conexión a la Búsqueda de Azure AI usando los roles. En este tutorial, la clave de API es aceptable si desea continuar rápidamente. Cambie a Entra ID antes de implementar en producción.

7. Seleccione Agregar conexión.

Creación de un entorno de Python

En el IDE que prefiera, cree una carpeta para el proyecto. Abra una ventana de terminal en esa carpeta.

En primer lugar, cree un nuevo entorno de Python. No instale paquetes en la instalación global de Python. Use siempre un entorno virtual o conda al instalar paquetes de Python. De lo contrario, puede interrumpir la instalación global de Python.

Si es necesario, instale Python.

Use Python 3.10 o posterior, pero se requiere al menos Python 3.9. Si no tiene instalada una versión adecuada de Python, siga las instrucciones del Tutorial de Python de VS Code para obtener la manera más fácil de instalar Python en el sistema operativo.

Creación de un entorno virtual

Si ya tiene Instalado Python 3.10 o superior, cree un entorno virtual mediante los siguientes comandos:

py -3 -m venv .venv
.venv\scripts\activate

python3 -m venv .venv
source .venv/bin/activate

python3 -m venv .venv
source .venv/bin/activate

Al activar el entorno de Python, ejecutar python o pip desde la línea de comandos usa el intérprete de Python en la carpeta .venv de tu aplicación.

Instalación de paquetes

Instale los paquetes requeridos.

1. Cree un archivo denominado requirements.txt en la carpeta del proyecto. Agregue los siguientes paquetes al archivo:

   azure-ai-projects==1.0.0b10
   azure-ai-inference[prompts]
   azure-identity
   azure-search-documents
   pandas
   python-dotenv
   opentelemetry-api
   

   Referencias: biblioteca cliente de proyectos de Azure AI, azure-ai-inference, python-dotenv.

2. Instale los paquetes necesarios:

   pip install -r requirements.txt
   

Comprobación de la configuración

Compruebe que el entorno está configurado correctamente mediante la ejecución de una prueba rápida:

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

# This will fail if credentials aren't set up, confirming auth is working
client = AIProjectClient.from_config(credential=DefaultAzureCredential())
print("Setup successful! You're ready to build your RAG app.")

Si ve "Setup successful!", las credenciales y el SDK de Azure se configuran correctamente.

Referencias: biblioteca cliente de Proyectos de Azure AI, DefaultAzureCredential.

Creación de script auxiliar

Cree una carpeta para el trabajo. Cree un archivo denominado config.py en esta carpeta. Usará este script auxiliar en las dos partes siguientes de la serie de tutoriales. El script carga las variables de entorno e inicializa el cliente de proyectos de Azure AI. Agregue el código siguiente:

# ruff: noqa: ANN201, ANN001

import os
import sys
import pathlib
import logging
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.inference.tracing import AIInferenceInstrumentor

# load environment variables from the .env file
from dotenv import load_dotenv

load_dotenv()

# Set "./assets" as the path where assets are stored, resolving the absolute path:
ASSET_PATH = pathlib.Path(__file__).parent.resolve() / "assets"

# Configure an root app logger that prints info level logs to stdout
logger = logging.getLogger("app")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(stream=sys.stdout))


# Returns a module-specific logger, inheriting from the root app logger
def get_logger(module_name):
    return logging.getLogger(f"app.{module_name}")


# Enable instrumentation and logging of telemetry to the project
def enable_telemetry(log_to_project: bool = False):
    AIInferenceInstrumentor().instrument()

    # enable logging message contents
    os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true"

    if log_to_project:
        from azure.monitor.opentelemetry import configure_azure_monitor

        project = AIProjectClient.from_connection_string(
            conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
        )
        tracing_link = f"https://ai.azure.com/tracing?wsid=/subscriptions/{project.scope['subscription_id']}/resourceGroups/{project.scope['resource_group_name']}/providers/Microsoft.MachineLearningServices/workspaces/{project.scope['project_name']}"
        application_insights_connection_string = project.telemetry.get_connection_string()
        if not application_insights_connection_string:
            logger.warning(
                "No application insights configured, telemetry will not be logged to project. Add application insights at:"
            )
            logger.warning(tracing_link)

            return

        configure_azure_monitor(connection_string=application_insights_connection_string)
        logger.info("Enabled telemetry logging to project, view traces at:")
        logger.info(tracing_link)

Referencias: AIProjectClient, DefaultAzureCredential, load_dotenv.

Configuración de las variables de entorno

La cadena de conexión de su proyecto es necesaria para invocar a Azure OpenAI en los modelos de Microsoft Foundry desde su código. En este inicio rápido, guardará este valor en un archivo .env, que es un archivo que contiene variables de entorno que la aplicación puede leer.

Cree un archivo .env y pegue el siguiente código:

AIPROJECT_CONNECTION_STRING=<your-connection-string>
AISEARCH_INDEX_NAME="example-index"
EMBEDDINGS_MODEL="text-embedding-ada-002"
INTENT_MAPPING_MODEL="gpt-4o-mini"
CHAT_MODEL="gpt-4o-mini"
EVALUATION_MODEL="gpt-4o-mini"

• Busque la cadena de conexión en el proyecto Foundry que ha creado en el Inicio rápido del área de juegos de Foundry. Abra el proyecto y busque la cadena de conexión en la página Información general. Copie la cadena de conexión y péguela en el archivo .env.

  

• Si aún no tiene un índice de búsqueda, mantenga el valor "example-index" para AISEARCH_INDEX_NAME. En la parte 2 de este tutorial, creará el índice con este nombre. Si ha creado previamente un índice de búsqueda que desea usar en su lugar, actualice el valor para que coincida con el nombre de ese índice de búsqueda.

• Si cambió los nombres de los modelos al implementarlos, actualice los valores del archivo .env para que coincidan con los nombres que usó.

Instale la CLI de Azure e inicie sesión.

Instale la CLI de Azure e inicie sesión desde el entorno de desarrollo local para que pueda usar las credenciales de usuario para llamar a Azure OpenAI en Microsoft Foundry Models.

En la mayoría de los casos, puede instalar la CLI de Azure desde el terminal mediante el siguiente comando:

winget install -e --id Microsoft.AzureCLI

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

brew update && brew install azure-cli

Puede seguir las instrucciones Cómo instalar la CLI de Azure si estos comandos no funcionan para su sistema operativo o configuración concretos.

Después de instalar la CLI de Azure, inicie sesión con el comando az login e inicie sesión con el explorador:

az login

Como alternativa, puede iniciar sesión manualmente a través del explorador con un código de dispositivo.

az login --use-device-code

Mantenga abierta esta ventana de terminal para ejecutar los scripts de Python desde aquí, ahora que ha iniciado sesión.

Limpieza de recursos

Para evitar incurrir en costos innecesarios de Azure, elimine los recursos que creó en este tutorial si ya no son necesarios. Para administrar recursos, puede usar Azure Portal.

Pero aún no los elimine si desea compilar una aplicación de chat en la siguiente parte de esta serie de tutoriales.

Paso siguiente

En este tutorial, configurará todo lo que necesita para crear una aplicación de chat personalizada con el SDK de Azure AI. En la siguiente parte de esta serie de tutoriales, creará la aplicación personalizada.