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

Artigo
11/19/2024

AutoGen é uma estrutura para o desenvolvimento de aplicativos de modelo de linguagem grande (LLM) usando vários agentes que conversam entre si para resolver tarefas. Os agentes construídos com 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 os 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 com o AutoGen, você dá ao agente um interpretador de código a ser usado para executar cálculos úteis e executar ações.

Neste tutorial, você aprenderá a executar um agente de IA criado no AutoGen em uma API da 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 subscrição ativa.
- Se não tiver uma, pode 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 um LLM do Azure OpenAI. Ele também usa sessões de Aplicativos de Contêiner do Azure para executar o código gerado pelo LLM.

Atualize a CLI do Azure para a versão mais recente.
```
 az upgrade
```
Remova a extensão Aplicativos de Contêiner do Azure se ela já estiver instalada e instale uma versão de visualização da extensão 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
```
Iniciar sessão 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 Azure OpenAI.

Criar um grupo de recursos:

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

Crie uma conta do 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

Crie uma implantação de modelo GPT 3.5 Turbo nomeada gpt-35-turbo na conta do 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"

Crie um pool de sessões 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ê pode executá-lo localmente para testá-lo.

Clone 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

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

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

Configurar o aplicativo

Crie um ambiente virtual Python e ative-o:
```
python3.11 -m venv .venv
source .venv/bin/activate
```
Altere a versão do Python no comando se estiver usando uma versão diferente. Recomenda-se o uso do Python 3.10 ou posterior.

Nota

Se estiver a utilizar o Windows, substitua .venv/bin/activate por .venv\Scripts\activate.

Instale os pacotes Python necessários:

python -m pip install -r requirements.txt

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

Recupere o ponto de extremidade da conta do Azure OpenAI:

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

Recupere a chave da API do Azure OpenAI:

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ões do Azure Container Apps:

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

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

O aplicativo usa DefaultAzureCredential para autenticar com os serviços do Azure. Em sua máquina local, ele usa suas credenciais de logon atuais da CLI do Azure. Você deve atribuir a si mesmo a função Executor de Sessão do Azure ContainerApps no pool de sessões para que o aplicativo acesse o pool de sessões.
1. Recupere seu 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ões:
```
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 Azure ContainerApps ao usuário da CLI do Azure no pool de sessões:
```
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ões.

Executar a aplicação

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

As seguintes linhas de código instanciam um ACASessionsExecutor e fornecem-no 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 precisa executar cálculos e tarefas, o agente usa o interpretador de código em 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ê instancia a ferramenta. Se o agente usa a mesma ferramenta para executar vários trechos de código Python, ele usa 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.

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

O agente responde com a hora atual. No terminal, você vê 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 parar o aplicativo, entre Ctrl+C no terminal.

Opcional: implantar o aplicativo de exemplo em Aplicativos de Contêiner do Azure

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

Em seguida, você precisa configurar a identidade gerenciada para o aplicativo e atribuir-lhe as funções adequadas para acessar o Azure OpenAI e o pool de sessões.

Defina as variáveis para o ambiente Container Apps e o nome do aplicativo:
```
ENVIRONMENT_NAME=aca-sessions-tutorial-env
CONTAINER_APP_NAME=chat-api
```

Crie e implante o aplicativo em 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 Azure OpenAI, <AZURE_OPENAI_KEY> pela chave do Azure OpenAI e <SESSION_POOL_MANAGEMENT_ENDPOINT> pelo ponto de extremidade de gerenciamento do pool de sessões.

Habilite a identidade gerenciada atribuída ao 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ões, você precisa atribuir à identidade gerenciada as funções adequadas.

Recupere o ID principal da identidade gerenciada:

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

Recupere o ID do recurso do pool de sessões:

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

Atribua a identidade gerenciada às Azure ContainerApps Session Executor e Contributor funções no pool de sessões:

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 https://<FQDN>/docs testar o aplicativo implantado.

Clean up resources (Limpar recursos)

Quando terminar de utilizar os recursos, pode eliminá-los para evitar incorrer em encargos:

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

Próximos passos

Sessões de intérprete de código

Partilhar via