Tutorial: Usar sessões de interpretador de código no AutoGen com Aplicativos de Contêiner do Azure

Artigo
10/11/2024

AutoGen é uma estrutura para desenvolver aplicativos LLM (modelo de linguagem grande) usando vários agentes que conversam entre si para resolver tarefas. Os agentes criados com o AutoGen podem operar em vários modos que empregam combinações de LLMs, entradas humanas e ferramentas. Um tipo importante de ferramenta para agentes AutoGen são executores de código. Eles permitem que os agentes executem tarefas complexas escrevendo e executando código. Ao integrar sessões dinâmicas dos Aplicativos de Contêiner do Azure ao AutoGen, você fornece ao agente um interpretador de código a ser usado para executar computações úteis e realizar ações.

Neste tutorial, você aprenderá a executar um agente de IA criado no AutoGen em uma API Web. A API aceita a entrada do usuário e retorna uma resposta gerada pelo agente de IA. O agente usa um interpretador de código em sessões dinâmicas para executar cálculos.

Pré-requisitos

Uma conta do Azure com uma assinatura ativa.
- Se não tiver uma, poderá criar uma gratuitamente.
Instale a CLI do Azure.
Git.
Python 3.10 ou posterior.

Criar recursos do Azure

O aplicativo de exemplo neste início rápido usa uma LLM do OpenAI do Azure. Ele também usa sessões de Aplicativos de Contêiner do Azure para executar o código gerado pela LLM.

Atualize a CLI do Azure para a versão mais recente.
```
 az upgrade
```
Remova a extensão dos Aplicativos de Contêiner do Azure se ela já estiver instalada e instale uma versão prévia da extensão dos Aplicativos de Contêiner do Azure que contém comandos para sessões:
```
az extension remove --name containerapp
az extension add \
    --name containerapp \
    --allow-preview true -y
```
Entrar no Azure:
```
az login
```

Defina as variáveis usadas neste início 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

Substitua <UNIQUE_OPEN_AI_NAME> por um nome exclusivo para criar sua conta do OpenAI do Azure.

Crie um grupo de recursos:

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

Crie uma conta do OpenAI do Azure:

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

Crie uma implantação do modelo GPT 3.5 Turbo nomeada gpt-35-turbo na conta do OpenAI do Azure:

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"

Crie um pool de sessão de interpretador 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

Executar o aplicativo de exemplo localmente

Antes de implantar o aplicativo nos Aplicativos de Contêiner do Azure, você poderá executá-lo localmente para testá-lo.

Clonar o aplicativo

Clone o repositório de exemplos de sessões de Aplicativos de Contêiner do Azure.

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

Altere para o diretório que contém o aplicativo de exemplo:

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

Configurar o aplicativo

Criar e ativar um ambiente virtual do Python:
```
python3.11 -m venv .venv
source .venv/bin/activate
```
Altere a versão do Python no comando se você estiver usando uma versão diferente. É recomendável usar o Python 3.10 ou posterior.

Observação

Caso esteja usando o Windows, substitua .venv/bin/activate por .venv\Scripts\activate.

Instale os pacotes necessários do Python:

python -m pip install -r requirements.txt

Para executar o aplicativo, você precisará configurar variáveis de ambiente.

Recupere o ponto de extremidade da conta do OpenAI do Azure:

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

Recupere chave de API do OpenAI do Azure:

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

Recupere o ponto de extremidade de gerenciamento do pool de sessão dos Aplicativos de Contêiner do Azure:

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

Crie um arquivo .env na raiz do diretório de aplicativo de exemplo (mesmo local que main.py). Adicione o seguinte conteúdo ao arquivo:
```
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>
```
Substitua <AZURE_OPENAI_ENDPOINT> pelo ponto de extremidade da conta do OpenAI do Azure, <AZURE_OPENAI_KEY> pela chave de API do OpenAI do Azure e <SESSION_POOL_MANAGEMENT_ENDPOINT> pelo ponto de extremidade de gerenciamento do pool de sessão.

O aplicativo usa DefaultAzureCredential para autenticar com os serviços do Azure. Em seu computador local, ele usa suas credenciais de logon da CLI do Azure atuais. Você deve atribuir a si mesmo a função Executor de Sessão de ContainerApps do Azure no pool de sessão do aplicativo para acessar o pool de sessão.
1. Recupere o nome de usuário da CLI do Azure:
```
az account show --query user.name --output tsv
```
2. Execute os seguintes comandos para recuperar a ID do recurso do pool de sessão:
```
az containerapp sessionpool show --name $SESSION_POOL_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
```
3. Atribua a função Executor de Sessão do ContainerApps do Azure ao usuário da CLI do Azure no pool de sessão:
```
az role assignment create \
    --role "Azure ContainerApps Session Executor" \
    --assignee <CLI_USERNAME> \
    --scope <SESSION_POOL_RESOURCE_ID>
```
  Substitua <CLI_USERNAME> pelo nome de usuário da CLI do Azure e <SESSION_POOL_RESOURCE_ID> pela ID do recurso do pool de sessão.

Executar o aplicativo

Antes de executar o aplicativo de exemplo, abra main.py em um editor e examine o código. O aplicativo usa FastAPI para criar uma API Web que aceita uma mensagem de usuário na cadeia de caracteres de consulta.

As seguintes linhas de código instanciam um ACASessionsExecutor e o fornecem ao agente 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()
)

Quando ele precisa executar cálculos e tarefas, o agente usa o interpretador de código no ACASessionsExecutor para executar o código. O código é executado em uma sessão no pool de sessões. Por padrão, um identificador de sessão aleatório é gerado quando você cria uma instância da ferramenta. Se o agente usar a mesma ferramenta para executar vários snippets de código do Python, ele usará a mesma sessão. Para garantir que cada usuário final tenha uma sessão exclusiva, use um agente e uma ferramenta separados para cada usuário.

ACASessionsExecutor é implementado em aca_sessions_executor.py.

Executar o aplicativo de exemplo:
```
fastapi dev main.py
```
Abra um navegador e navegue até http://localhost:8000/docs. Você visualizará a interface do usuário do Swagger para o aplicativo de exemplo.
Expanda o ponto de extremidade /chat e selecione Experimentar.
Insira What time is it right now? no campo message e selecione Executar.

O agente responde com a hora atual. No terminal, você visualizará os logs mostrando o código Python gerado pelo agente para obter a hora atual e executá-lo em uma sessão de interpretador de código.
Para interromper o aplicativo, insira Ctrl+C no terminal.

Opcional: implante o aplicativo de exemplo nos Aplicativos de Contêiner do Azure

Para implantar o aplicativo do FastAPI nos Aplicativos de Contêiner do Azure, você precisará criar uma imagem de contêiner e efetuá-la por push para um registro de contêiner. Em seguida, você poderá implantar a imagem nos Aplicativos de Contêiner do Azure. O comando az containerapp up combina essas etapas em um único comando.

Em seguida, você precisará configurar a identidade gerenciada para o aplicativo e atribuí-la às funções adequadas para acessar o OpenAI do Azure e o pool de sessões.

Defina as variáveis para o ambiente de Aplicativos de Contêiner e o nome do aplicativo:
```
ENVIRONMENT_NAME=aca-sessions-tutorial-env
CONTAINER_APP_NAME=chat-api
```

Crie e implante o aplicativo nos Aplicativos de Contêiner do Azure:

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 .

Substitua <AZURE_OPENAI_ENDPOINT> pelo ponto de extremidade da conta do OpenAI do Azure, <AZURE_OPENAI_KEY> pela chave do OpenAI do Azure e <SESSION_POOL_MANAGEMENT_ENDPOINT> pelo ponto de extremidade de gerenciamento do pool de sessão.

Habilite a identidade gerenciada atribuída pelo sistema para o aplicativo:

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

Para que o aplicativo acesse o pool de sessão, você precisará atribuir à identidade gerenciada as funções adequadas.

Recupere a ID da entidade de segurança da identidade gerenciada:

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

Recupere a ID do recurso do pool de sessão:

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

Atribua a identidade gerenciada e as funções Azure ContainerApps Session Executor e Contributor no pool de sessão:

Antes de executar o comando a seguir, substitua <PRINCIPAL_ID> e <SESSION_POOL_RESOURCE_ID> pelos valores recuperados nas etapas 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 o FQDN (nome de domínio totalmente qualificado) do aplicativo:

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

Abra o navegador para o https://<FQDN>/docs testar o aplicativo implantado.

Limpar os recursos

Quando terminar de usar os recursos, você poderá excluí-los para evitar incorrer em encargos:

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

Próximas etapas

Sessões de interpretador de código

Compartilhar via