Tutorial: Uso de sesiones de intérprete de código en LlamaIndex con Azure Container Apps

LlamaIndex es un marco eficaz para crear aplicaciones de modelo de lenguaje aumentada por contexto (LLM). Al compilar un agente de IA con LlamaIndex, un LLM interpreta la entrada del usuario y genera una respuesta. A menudo, el agente de IA tiene dificultades cuando necesita realizar razonamiento matemático y simbólico para producir una respuesta. Al integrar sesiones dinámicas de Azure Container Apps con LlamaIndex, se proporciona al agente un intérprete de código para usar a realizar tareas especializadas.

En este tutorial, aprenderá a ejecutar un agente de IAl LlamaIndex en una API web. La API acepta la entrada del usuario y devuelve una respuesta generada por el agente de IA. El agente usa un intérprete de código en sesiones dinámicas para realizar cálculos.

Nota:

Las sesiones dinámicas de Azure Container Apps se encuentran actualmente en versión preliminar. Vea limitaciones de la versión preliminar para obtener más información.

Requisitos previos

• Una cuenta de Azure con una suscripción activa.
  • Si no tiene ninguna, puede crear una gratis.
• Instale la CLI de Azure.
• Git.
• Python 3.10 o posterior.

Creación de recursos de Azure

La aplicación de ejemplo de este inicio rápido usa un LLM de Azure OpenAI. También usa sesiones de Azure Container Apps para ejecutar código generado por LLM.

1. Actualice la CLI de Azure a la versión más reciente.

    az upgrade
   

2. Quite la extensión Azure Container Apps si ya está instalada e instale una versión preliminar de la extensión Azure Container Apps que contiene comandos para las sesiones:

   az extension remove --name containerapp
   az extension add \
       --name containerapp \
       --allow-preview true -y
   

3. Inicie de sesión en Azure:

   az login
   

4. Establezca las variables usadas en este inicio rápido:

   RESOURCE_GROUP_NAME=aca-sessions-tutorial
   AZURE_OPENAI_LOCATION=swedencentral
   AZURE_OPENAI_NAME=<UNIQUE_OPEN_AI_NAME>
   SESSION_POOL_LOCATION=eastasia
   SESSION_POOL_NAME=code-interpreter-pool
   

   Reemplace <UNIQUE_OPEN_AI_NAME> con un nombre único para crear la cuenta de Azure OpenAI.

5. Cree un grupo de recursos:

   az group create --name $RESOURCE_GROUP_NAME --location $SESSION_POOL_LOCATION
   

6. Cree una cuenta de Azure OpenAI:

   az cognitiveservices account create \
       --name $AZURE_OPENAI_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --location $AZURE_OPENAI_LOCATION \
       --kind OpenAI \
       --sku s0 \
       --custom-domain $AZURE_OPENAI_NAME
   

7. Cree una implementación de modelo GPT 3.5 Turbo denominada gpt-35-turbo en la cuenta de Azure OpenAI:

   az cognitiveservices account deployment create \
       --resource-group $RESOURCE_GROUP_NAME \
       --name $AZURE_OPENAI_NAME \
       --deployment-name gpt-35-turbo \
       --model-name gpt-35-turbo \
       --model-version "1106" \
       --model-format OpenAI \
       --sku-capacity "100" \
       --sku-name "Standard"
   

8. Cree un grupo de sesiones de intérprete de código:

   az containerapp sessionpool create \
       --name $SESSION_POOL_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --location $SESSION_POOL_LOCATION \
       --max-sessions 100 \
       --container-type PythonLTS \
       --cooldown-period 300
   

Ejecutará la aplicación de ejemplo localmente

Antes de implementar la aplicación en Azure Container Apps, puede ejecutarla localmente para probarla.

Clonación de la aplicación

1. Clone el Repositorio de ejemplos de sesiones de Azure Container Apps.

   git clone https://github.com/Azure-Samples/container-apps-dynamic-sessions-samples.git
   

2. Cambie al directorio que contiene la aplicación de ejemplo:

   cd container-apps-dynamic-sessions-samples/llamaindex-python-webapi
   

Configuración de la aplicación

1. Cree un entorno virtual de Python y actívelo:

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

   Cambie la versión de Python en el comando si usa una versión diferente. Se recomienda usar Python 3.10 o posterior.

   Nota:

   Si usa Windows, reemplace .venv/bin/activate con .venv\Scripts\activate.

2. Instale los paquetes de Python necesarios:

   python -m pip install -r requirements.txt
   

3. Para ejecutar la aplicación, debe configurar variables de entorno.

   1. Recupere el punto de conexión de la cuenta de Azure OpenAI:

      az cognitiveservices account show \
          --name $AZURE_OPENAI_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query properties.endpoint \
          --output tsv
      

   2. Recupere el punto de conexión de administración del grupo de sesiones de Azure Container Apps:

      az containerapp sessionpool show \
          --name $SESSION_POOL_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query properties.poolManagementEndpoint \
          --output tsv
      

   3. Cree un archivo .env en la raíz del directorio de la aplicación de ejemplo (la misma ubicación que main.py). Agregue el siguiente contenido al archivo:

      AZURE_OPENAI_ENDPOINT=<AZURE_OPENAI_ENDPOINT>
      POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGEMENT_ENDPOINT>
      

      Reemplace <AZURE_OPENAI_ENDPOINT> con el punto de conexión de la cuenta de Azure OpenAI y <SESSION_POOL_MANAGEMENT_ENDPOINT> con el punto de conexión de administración del grupo de sesiones.

4. La aplicación usa DefaultAzureCredential para autenticarse con los servicios de Azure. En el equipo local, usa las credenciales de inicio de sesión actuales de la CLI de Azure. Debe concederse el rol Usuario OpenAI de Cognitive Services en la cuenta de Azure OpenAI para que la aplicación acceda a los puntos de conexión del modelo y el rol Ejecutor de sesión de Azure ContainerApps en el grupo de sesiones para que la aplicación acceda al grupo de sesiones.

   1. Recupere el nombre de usuario de la CLI de Azure:

      az account show --query user.name --output tsv
      

   2. Ejecute los siguientes comandos para recuperar el id. de recurso de la cuenta de Azure OpenAI:

      az cognitiveservices account show --name $AZURE_OPENAI_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
      

   3. Asigne el rol Usuario de OpenAI de Cognitive Services a su usuario de la CLI de Azure en la cuenta de Azure OpenAI:

      az role assignment create --role "Cognitive Services OpenAI User" --assignee <CLI_USERNAME> --scope <AZURE_OPENAI_RESOURCE_ID>
      

      Reemplace <CLI_USERNAME> con el nombre de usuario de la CLI de Azure y <AZURE_OPENAI_RESOURCE_ID> con el id. de recurso de la cuenta de Azure OpenAI.

   4. Ejecute los comandos siguientes para recuperar el id. de recurso del grupo de sesiones:

      az containerapp sessionpool show --name $SESSION_POOL_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
      

   5. Asigne el rol Ejecutor de sesión de Azure ContainerApps mediante su identificador al usuario de la CLI de Azure en el grupo de sesiones:

      az role assignment create \
          --role "Azure ContainerApps Session Executor" \
          --assignee <CLI_USERNAME> \
          --scope <SESSION_POOL_RESOURCE_ID>
      

      Reemplace <CLI_USERNAME> con el nombre de usuario de la CLI de Azure y <SESSION_POOL_RESOURCE_ID> con el id. de recurso del grupo de sesiones.

Ejecución de la aplicación

Antes de ejecutar la aplicación de ejemplo, abra main.py en un editor y revise el código. La aplicación usa FastAPI para crear una API web que acepte un mensaje de usuario en la cadena de consulta.

Las siguientes líneas de código crean una instancia de un AzureCodeInterpreterToolSpec y la proporcionan al agente LlamaIndex:

code_interpreter_tool = AzureCodeInterpreterToolSpec(
    pool_managment_endpoint=pool_management_endpoint,
)
agent = ReActAgent.from_tools(code_interpreter_tool.to_tool_list(), llm=llm, verbose=True)

Cuando necesita realizar cálculos, el agente usa el intérprete de código en AzureCodeInterpreterToolSpec para ejecutar el código. El código se ejecuta en una sesión del grupo de sesiones. De forma predeterminada, se genera un identificador de sesión aleatorio al crear una instancia de la herramienta. Si el agente usa la misma herramienta para ejecutar varios fragmentos de código de Python, usa la misma sesión. Para asegurarse de que cada usuario final tiene una sesión única, use un agente y una herramienta independientes para cada usuario.

AzureCodeInterpreterToolSpec está disponible en el paquete llama-index-tools-azure-code-interpreter.

1. Ejecute la aplicación de ejemplo:

   fastapi dev main.py
   

2. Abra un explorador y vaya a http://localhost:8000/docs. Verá la interfaz de usuario de Swagger para la aplicación de ejemplo.

3. Expanda el punto de conexión /chat y seleccione Pruébelo.

4. Escriba What time is it right now? en el campo message y seleccione Ejecutar.

   El agente responde con la hora actual. En el terminal, verá los registros que muestran el código de Python generado por el agente para obtener la hora actual y ejecutarlo en una sesión de intérprete de código.

5. Para detener la aplicación, escriba Ctrl+C en el terminal.

Opcional: Implementación de la aplicación de ejemplo en Azure Container Apps

Para implementar la aplicación FastAPI en Azure Container Apps, debe crear una imagen de contenedor e insertarla en un registro de contenedor. Después, puede implementar la imagen en Azure Container Apps. El comando az containerapp up combina estos pasos en un solo comando.

A continuación, debe configurar la identidad administrada para la aplicación y asignarle los roles adecuados para acceder a Azure OpenAI y al grupo de sesiones.

1. Establezca las variables para el entorno de Container Apps y el nombre de la aplicación:

   ENVIRONMENT_NAME=aca-sessions-tutorial-env
   CONTAINER_APP_NAME=chat-api
   

2. Compile e implemente la aplicación en Azure Container Apps:

   az containerapp up \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --location $SESSION_POOL_LOCATION \
       --environment $ENVIRONMENT_NAME \
       --env-vars "AZURE_OPENAI_ENDPOINT=<OPEN_AI_ENDPOINT>" "POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGMENT_ENDPOINT>" \
       --source .
   

   Reemplace <OPEN_AI_ENDPOINT> con el punto de conexión de la cuenta de Azure OpenAI y <SESSION_POOL_MANAGMENT_ENDPOINT> con el punto de conexión de administración del grupo de sesiones.

3. Habilite la identidad administrada asignada por el sistema para la aplicación:

   az containerapp identity assign \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --system-assigned
   

4. Para que la aplicación acceda a Azure OpenAI y al grupo de sesiones, debe asignar a la identidad administrada los roles adecuados.

   1. Recupere el id. de entidad de seguridad de la identidad administrada:

      az containerapp show \
          --name $CONTAINER_APP_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query identity.principalId \
          --output tsv
      

   2. Recupere el id. de recurso del grupo de sesiones:

      az containerapp sessionpool show \
          --name $SESSION_POOL_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query id \
          --output tsv
      

   3. Asigne la identidad administrada a los roles de Azure ContainerApps Session Executor y Contributor en el grupo de sesiones:

      Antes de ejecutar el comando siguiente, reemplace <PRINCIPAL_ID> y <SESSION_POOL_RESOURCE_ID> con los valores que recuperó en los pasos anteriores.

      az role assignment create \
          --role "Azure ContainerApps Session Executor" \
          --assignee <PRINCIPAL_ID> \
          --scope <SESSION_POOL_RESOURCE_ID>
      
      az role assignment create \
          --role "Contributor" \
          --assignee <PRINCIPAL_ID> \
          --scope <SESSION_POOL_RESOURCE_ID>
      

   4. Recupere el id. de recurso de la cuenta de Azure OpenAI:

      az cognitiveservices account show \
          --name $AZURE_OPENAI_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query id \
          --output tsv
      

   5. Asigne la identidad administrada al rol Cognitive Services OpenAI User en la cuenta de Azure OpenAI:

      Antes de ejecutar el comando siguiente, reemplace <PRINCIPAL_ID> y <AZURE_OPENAI_RESOURCE_ID> con los valores que recuperó en los pasos anteriores.

      az role assignment create \
          --role "Cognitive Services OpenAI User" \
          --assignee <PRINCIPAL_ID> \
          --scope <AZURE_OPENAI_RESOURCE_ID>
      

5. Recupere el nombre de dominio completo de la aplicación (FQDN):

   az containerapp show \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --query properties.configuration.ingress.fqdn \
       --output tsv
   

6. Abra el explorador para; https://<FQDN>/docs para probar la aplicación implementada.

Limpieza de recursos

Cuando haya terminado con los recursos, puede eliminarlos para evitar incurrir en cargos:

az group delete --name $RESOURCE_GROUP_NAME --yes --no-wait

Pasos siguientes

Sesiones de intérprete de código