Compartir vía

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 Azure AI Foundry

  • Artículo

En este tutorial, usará el SDK de Azure AI Foundry (y otras bibliotecas) para compilar, configurar y evaluar una aplicación de chat para su empresa minorista denominada Contoso Trek. Su empresa minorista se especializa en ropa y equipo de camping al aire libre. La aplicación de chat debe responder a preguntas sobre sus productos y servicios. Por ejemplo, la aplicación de chat puede responder a preguntas como "¿Qué tienda es la más impermeable?" o "¿cuál es la mejor bolsa de dormir para tiempo frío?".

Este tutorial es la primera parte de un tutorial que consta de tres partes. Esta primera parte sirve como preparación para escribir código en la segunda parte y evaluar la aplicación de chat en la tercera parte. En esta parte, hará lo siguiente:

  • Creación de un proyecto
  • Creación de un índice de Búsqueda de Azure AI
  • Instale la CLI de Azure e inicie sesión.
  • Instalación de Python y paquetes
  • Implementación de modelos en el proyecto
  • Configuración de las variables de entorno

Si ha completado otros tutoriales o inicios rápidos, es posible que ya haya creado algunos de los recursos necesarios para este tutorial. Si ya lo ha hecho, no dude en omitir estos pasos.

Este tutorial es la primera parte de un tutorial de tres partes.

Importante

Los elementos marcados (versión preliminar) en este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios de las Versiones Preliminares de Microsoft Azure.

Prerrequisitos

  • Una cuenta de Azure con una suscripción activa. Si no tienes ninguna cuenta, crea una gratuita.

Creación de un proyecto

Para crear un proyecto en Azure AI Foundry, siga estos pasos:

  1. Vaya a la página Inicio de Azure AI Foundry.
  2. Seleccione + Crear proyecto.
  3. Escriba un nombre para el proyecto. Deje las demás opciones como predeterminadas.
  4. Los proyectos se crean en centros. Si ve Crear un nuevo centro, selecciónelo y especifique un nombre. Seleccione Siguiente. (Si no ve Crear nuevo centro, no se preocupe; se debe a que se crea uno nuevo para usted).
  5. Seleccione Personalizar para especificar las propiedades del centro.
  6. Use los valores que desee, excepto Región. Se recomienda usar Este de US2 o Centro de Suecia para la región de esta serie de tutoriales.
  7. Seleccione Next (Siguiente).
  8. Seleccione Create project (Crear proyecto).

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 de Azure AI 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 portal de AI Foundry catálogo de modelos:

  1. En el panel de navegación izquierdo, seleccione Catálogo de modelo.

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

    Recorte de pantalla de la página de detalles del modelo con un botón para implementar el modelo.

  4. Deje el nombre de implementación predeterminado. 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 establecer las respuestas del modelo en los datos personalizados. El índice de búsqueda se usa para recuperar documentos relevantes en función de la pregunta del usuario.

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

Nota:

La creación de un servicio de Búsqueda de Azure AI y los índices de búsqueda posteriores tienen costos asociados. Puede ver detalles sobre los planes de tarifa y precios del servicio de Búsqueda de Azure AI en la página de creación para confirmar el costo antes de crear el recurso.

Si ya tiene un servicio de Búsqueda de Azure AI, puede ir directamente a la sección siguiente.

De lo contrario, puede crear un servicio de Búsqueda de Azure AI mediante Azure Portal.

Sugerencia

Este paso es la única vez en la que se usa Azure Portal en esta serie de tutoriales. El resto del trabajo se realiza en el portal de Azure AI Foundry o en el entorno de desarrollo local.

  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. Puede ver detalles sobre los planes de tarifa y precios en esta página.
  3. Continúe con el asistente y seleccione Revisar y asignar para crear el recurso.
  4. Confirme los detalles del servicio de Búsqueda de Azure AI, 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 ya tiene una conexión de Búsqueda de Azure AI en el proyecto, puede ir directamente a Instalar la CLI de Azure e iniciar sesión.

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

  1. En Azure AI 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 Búsqueda de Azure AI, puede pasar directamente a la sección siguiente.

  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. Para seleccionar y usar la opción de autenticación recomendada de Microsoft Entra ID, también debe configurar el control de acceso para el servicio Búsqueda de Azure AI. Asigne los roles Colaborador de datos de índice de búsqueda y Colaborador del servicio Search a su cuenta de usuario. Para más información, consulte Conexión a Búsqueda de Azure AI mediante roles y control de acceso basado en roles en el portal de Azure AI Foundry.

  7. Seleccione Agregar conexión.

Instale la CLI de Azure e inicie sesión.

Instale la CLI de Azure e inicie sesión desde el entorno de desarrollo local, de modo que pueda usar las credenciales de usuario para llamar al servicio Azure OpenAI.

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

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

Creación de un entorno de Python

En primer lugar, debe crear un nuevo entorno de Python y usarlo para instalar el paquete que necesita para este tutorial. NO instale paquetes en la instalación global de Python. Siempre debe usar 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.

Se recomienda usar Python 3.10 o posterior, pero se requiere al menos Python 3.8. Si no tiene instalada una versión adecuada de Python, puede seguir las instrucciones del Tutorial de Python de VS Code para 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, puede crear un entorno virtual con los siguientes comandos:

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

La activación del entorno de Python significa que, al ejecutar python o pip desde la línea de comandos, se usa el intérprete de Python incluido en la carpeta .venv de la aplicación.

Nota:

Puede usar el comando deactivate para salir del entorno virtual de Python y, posteriormente, volver a activarlo cuando sea necesario.

Instalar paquetes

Instale azure-ai-projects(versión preliminar) y azure-ai-inference (versión preliminar), junto con otros paquetes necesarios.

  1. En primer lugar, cree un archivo denominado requirements.txt en la carpeta del proyecto. Agregue los siguientes paquetes al archivo:

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

  2. Instale los paquetes necesarios:

    pip install -r requirements.txt

Creación de script auxiliar

Cree una carpeta para el trabajo. Cree un archivo denominado config.py en esta carpeta. Este script auxiliar se usa en las dos partes siguientes de la serie de tutoriales. Agrega 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)

Configuración de las variables de entorno

Su cadena de conexión del proyecto es necesaria para llamar a Azure OpenAI Service desde el 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 de Azure AI Foundry que creó en el inicio rápido del área de juegos de AI 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.

    Recorte de pantalla que muestra la página de información general de un proyecto y la ubicación de la cadena de conexión.

  • 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ó.

Sugerencia

Si trabaja en VS Code, cierre y vuelva a abrir la ventana del terminal después de guardar los cambios en el archivo .env.

Advertencia

Asegúrese de que .env está en el archivo .gitignore para que no lo compruebe accidentalmente en el repositorio de Git.

Limpieza de recursos

Para evitar incurrir en costos innecesarios de Azure, debe eliminar 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.

Parte 2: Creación de una aplicación de chat personalizada con el SDK de Azure AI