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 (clásico)

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 de Owner o Contributor asignado. Si no tienes ninguna cuenta, crea 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.

     La captura de pantalla muestra la creación de un nuevo proyecto a partir de unas migas de pan.

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

     Captura de pantalla que muestra cómo crear un nuevo proyecto en 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.

     Captura de pantalla de la página de detalles del proyecto en el cuadro de diálogo crear proyecto.

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 OpenAI Azure (gpt-4o-mini) y un modelo de inserción de OpenAI Azure (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.

   Captura de pantalla de la página de selección de modelos.

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 Búsqueda de Azure AI y una conexión para crear un índice de búsqueda.

Si ya tiene un servicio de Búsqueda de Azure AI, vaya a la sección next.

De lo contrario, cree un servicio de Búsqueda de Azure AI mediante el portal de Azure.

1. Crear un servicio Búsqueda de Azure AI en el portal de Azure.
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 Búsqueda de Azure AI, incluido el costo estimado.
5. Seleccione Crear para crear el servicio Búsqueda de Azure AI.

Conexión del Búsqueda de Azure AI al proyecto

Si el proyecto ya tiene una conexión de Búsqueda de Azure AI, vaya a Instale el CLI de Azure e inicie sesión.

En el portal de Foundry, compruebe si hay un recurso conectado Búsqueda de Azure AI.

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 Búsqueda de Azure AI, 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 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 Microsoft Entra ID autenticación, que requiere los roles Search Index Data Contributor y Search Service Contributor (configurados en Requisitos previos). Para obtener más información, consulte Conectar a Búsqueda de Azure AI usando 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 nuevo 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 de VS Code Python Tutorial para obtener la manera más sencilla 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, la ejecución de python o pip desde la línea de comandos usa el intérprete de Python en la carpeta .venv de la 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 Azure AI Projects, azure-ai-inference, python-dotenv.

2. Instale los paquetes necesarios:

   pip install -r requirements.txt
   

Configuración de las variables de entorno

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

Cree un archivo 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 su cadena de conexión en el proyecto Foundry que creó en el inicio rápido del Foundry playground. Abra el proyecto y busque el cadena de conexión en la página Overview. 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 . 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 para que coincidan con los nombres que usó.

Instalación del CLI de Azure e inicio de sesión

Instale el 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 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 CLI de Azure si estos comandos no funcionan para su sistema operativo o configuración específicos.

Después de instalar el CLI de Azure, inicie sesión con el comando /> /

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.

Comprobación de la configuración

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

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

# Check the SDK version
print(f"Azure AI Projects SDK version: {azure.ai.projects.__version__}")

# Test that you can connect to your project
project = AIProjectClient.from_connection_string(
    conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
)
print("✓ Setup verified! Ready to build your RAG app.")

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

Referencias: biblioteca cliente de Azure AI Projects, 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 Azure AI Projects. 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.

Limpieza de recursos

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

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 ia de Azure. En la siguiente parte de esta serie de tutoriales, creará la aplicación personalizada.