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

Artículo
10/11/2024

AutoGen es un marco para desarrollar aplicaciones de modelo de lenguaje grande (LLM) con varios agentes que se comunican entre sí para resolver tareas. Los agentes creados con AutoGen pueden funcionar en varios modos que emplean combinaciones de LLM, entradas humanas y herramientas. Un tipo importante de herramienta para agentes de AutoGen es los ejecutores de código. Permiten a los agentes realizar tareas complejas escribiendo y ejecutando código. Mediante la integración de sesiones dinámicas de Azure Container Apps con AutoGen, se proporciona al agente un intérprete de código que se usará para realizar cálculos útiles y realizar acciones.

En este tutorial, aprenderá a ejecutar un agente de IA creado en AutoGen 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.

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.

Actualice la CLI de Azure a la versión más reciente.
```
 az upgrade
```
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
```
Inicie de sesión en Azure:
```
az login
```

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.

Cree un grupo de recursos:

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

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

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"

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

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

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

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

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

Configuración de la aplicación

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.

Instale los paquetes de Python necesarios:

python -m pip install -r requirements.txt

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

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

Recupere la clave de API de Azure OpenAI:

az cognitiveservices account keys list \
    --name $AZURE_OPENAI_NAME \
    --resource-group $RESOURCE_GROUP_NAME \
    --query key1 \
    --output tsv

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

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:
```
OAI_CONFIG_LIST=[{"model": "gpt-4", "api_key": "<AZURE_OPENAI_KEY>", "api_type": "azure", "base_url": "<AZURE_OPENAI_ENDPOINT>", "api_version": "2023-12-01-preview"}]
POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGEMENT_ENDPOINT>
```
Reemplace <AZURE_OPENAI_ENDPOINT> por el punto de conexión de la cuenta de Azure OpenAI, <AZURE_OPENAI_KEY> por la clave de API de Azure OpenAI y <SESSION_POOL_MANAGEMENT_ENDPOINT> por el punto de conexión de administración del grupo de sesiones.

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 proporcionarle 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 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
```
3. Asigne el rol ejecutor de sesión de Azure ContainerApps 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 ACASessionsExecutor y la proporcionan al agente de autogen:

aca_sessions_executor = ACASessionsExecutor(aca_pool_management_endpoint)
code_executor_agent = ConversableAgent(
    name="CodeExecutor",
    llm_config=False,
    code_execution_config={"executor": aca_sessions_executor},
    human_input_mode="NEVER",
    is_termination_msg=lambda msg: "TERMINATE" in msg.get("content", "").strip().upper()
)

Cuando necesita realizar cálculos y tareas, el agente usa el intérprete de código en ACASessionsExecutor 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.

ACASessionsExecutor se implementa en aca_sessions_executor.py.

Ejecute la aplicación de ejemplo:
```
fastapi dev main.py
```
Abra un explorador y vaya a http://localhost:8000/docs. Verá la interfaz de usuario de Swagger para la aplicación de ejemplo.
Expanda el punto de conexión /chat y seleccione Pruébelo.
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.
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.

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
```

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 'OAI_CONFIG_LIST=[{"model": "gpt-4", "api_key": "<AZURE_OPENAI_KEY>", "api_type": "azure", "base_url": "<AZURE_OPENAI_ENDPOINT>", "api_version": "2023-12-01-preview"}]' 'POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGEMENT_ENDPOINT>' \
    --source .

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

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

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

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

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

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>

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

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

Compartir a través de