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

O LlamaIndex é uma estrutura poderosa para a criação de aplicativos LLM (modelo de linguagem aumentada) por contexto. Quando você cria um agente de IA com o LlamaIndex, um LLM interpreta a entrada do usuário e gera uma resposta. O agente de IA geralmente enfrenta dificuldades quando precisa executar o raciocínio matemático e simbólico para produzir uma resposta. Ao integrar sessões dinâmicas dos Aplicativos de Contêiner do Azure ao LlamaIndex, você fornece ao agente um interpretador de código a ser usado para executar tarefas especializadas.

Neste tutorial, você aprenderá a executar um agente de IA LlamaIndex 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.

1. Atualize a CLI do Azure para a versão mais recente.

    az upgrade
   

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

3. Entrar no Azure:

   az login
   

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

5. Crie um grupo de recursos:

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

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

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

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

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

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

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

Configurar o aplicativo

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

2. Instale os pacotes necessários do Python:

   python -m pip install -r requirements.txt
   

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

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

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

   3. 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:

      AZURE_OPENAI_ENDPOINT=<AZURE_OPENAI_ENDPOINT>
      POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGEMENT_ENDPOINT>
      

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

4. 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 fornecer a si mesmo a função de Usuário do OpenAI dos Serviços Cognitivos na conta do OpenAI do Azure, para que o aplicativo acesse os pontos de extremidade do modelo e 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 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 de conta do OpenAI do Azure:

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

   3. Atribua a função de Usuário OpenAI dos Serviços Cognitivos ao usuário da CLI do Azure na conta do OpenAI do Azure:

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

      Substitua <CLI_USERNAME> pelo nome de usuário da CLI do Azure e <AZURE_OPENAI_RESOURCE_ID> pela ID do recurso de conta do OpenAI do Azure.

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

   5. Atribua a função Executor de Sessão do Azure ContainerApps usando sua ID no 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ã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 AzureCodeInterpreterToolSpec e o fornecem ao 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)

Quando ele precisa executar cálculos, o agente usa o interpretador de código no AzureCodeInterpreterToolSpec 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.

AzureCodeInterpreterToolSpec está disponível no pacote llama-index-tools-azure-code-interpreter.

1. Executar o aplicativo de exemplo:

   fastapi dev main.py
   

2. Abra um navegador e navegue até http://localhost:8000/docs. Você visualizará a interface do usuário do Swagger para o aplicativo de exemplo.

3. Expanda o ponto de extremidade /chat e selecione Experimentar.

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

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

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

2. 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 "AZURE_OPENAI_ENDPOINT=<OPEN_AI_ENDPOINT>" "POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGMENT_ENDPOINT>" \
       --source .
   

   Substitua <OPEN_AI_ENDPOINT> pelo ponto de extremidade da conta do OpenAI do Azure e <SESSION_POOL_MANAGMENT_ENDPOINT> pelo ponto de extremidade de gerenciamento do pool de sessão.

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

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

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

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

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

   4. Recupere a ID do recurso de conta do OpenAI do Azure:

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

   5. Atribua a identidade gerenciada à função Cognitive Services OpenAI User na conta do OpenAI do Azure:

      Antes de executar o comando a seguir, substitua <PRINCIPAL_ID> e <AZURE_OPENAI_RESOURCE_ID> pelos valores recuperados nas etapas anteriores.

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

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

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