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

LangChain é uma estrutura projetada para simplificar a criação de aplicativos usando LLMs (modelos de linguagem grande). Ao cria um agente de IA com o LangChain, 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 LangChain, 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 LangChain 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.

Observação

As sessões dinâmicas dos Aplicativos de Contêiner do Azure estão atualmente em versão prévia. Confira as limitações de visualização para obter mais informações.

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/langchain-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 SessionPythonREPLTool e fornecem-no ao agente LangChain:

repl = SessionsPythonREPLTool(pool_management_endpoint=pool_management_endpoint)

tools = [repl]
prompt = hub.pull("hwchase17/openai-functions-agent")
agent = agents.create_tool_calling_agent(llm, tools, prompt)

Quando ele precisa executar cálculos, o agente usa o SessionPythonREPLTool 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 ao criar uma instância da ferramenta. Se o agente usar a 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.

SessionPythonREPLTool está disponível no pacote langchain-azure-dynamic-sessions.

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