Tutorial: Usar sessões de interpretador de código no Kernel Semântico com Aplicativos de Contêiner do Azure

O Semantic Kernel é um framework de IA de código aberto criado pela Microsoft para desenvolvedores .NET, Python e Java que trabalham com Large Language Models (LLMs). Quando você cria um agente de IA com Kernel Semântico, um LLM interpreta a entrada do usuário e gera uma resposta. O agente de IA muitas vezes se esforça quando precisa realizar raciocínios matemáticos e simbólicos para produzir uma resposta. Ao integrar sessões dinâmicas de Aplicativos de Contêiner do Azure com o Kernel Semântico, você dá ao agente um interpretador de código para usar para executar tarefas especializadas.

Neste tutorial, você aprenderá a executar um agente de IA do Kernel Semântico 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.

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

    az upgrade
   

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

3. Entre 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 Azure OpenAI.

5. Criar um grupo de recursos:

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

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

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

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

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. Mude para o diretório que contém o aplicativo de exemplo:

   cd container-apps-dynamic-sessions-samples/semantic-kernel-python-webapi
   

Configurar o aplicativo

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

2. Instale os pacotes Python necessários:

   python -m pip install -r requirements.txt
   

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

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

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

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

      AZURE_OPENAI_ENDPOINT=<AZURE_OPENAI_ENDPOINT>
      POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGEMENT_ENDPOINT>
      

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

4. 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 de Usuário OpenAI dos Serviços Cognitivos na conta do Azure OpenAI 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 o aplicativo acessar 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 de recurso da conta do Azure OpenAI:

      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 Azure OpenAI:

      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 de recurso da conta do Azure OpenAI.

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

   5. Atribua a função Executor de Sessão do Azure ContainerApps usando sua ID 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 SessionsPythonTool e o fornecem ao agente do Kernel Semântico:

sessions_tool = SessionsPythonTool(
    pool_management_endpoint,
    auth_callback=auth_callback_factory("https://dynamicsessions.io/.default"),
)
kernel.add_plugin(sessions_tool, "SessionsTool")

Quando precisa executar cálculos, o kernel usa o interpretador de código em SessionsPythonTool 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 kernel usa a 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 kernel e uma ferramenta separados para cada usuário.

SessionsPythonTool está disponível na versão 0.9.8b1 ou posterior do semantic-kernel pacote.

1. Execute o aplicativo de exemplo:

   fastapi dev main.py
   

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

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

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

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

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

2. 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 "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 Azure OpenAI e <SESSION_POOL_MANAGMENT_ENDPOINT> pelo ponto de extremidade de gerenciamento do pool de sessões.

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

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

   1. Recupere o ID principal da identidade gerenciada:

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

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

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

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

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

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

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