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

LangChain é uma estrutura projetada para simplificar a criação de aplicações usando grandes modelos de linguagem (LLMs). Quando você cria um agente de IA com LangChain, 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 LangChain, 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 LangChain 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. Iniciar sessão 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/langchain-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 SessionPythonREPLTool e o fornecem 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 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 quando você instancia a ferramenta. Se o agente 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 agente e uma ferramenta separados para cada usuário.

SessionPythonREPLTool está disponível no langchain-azure-dynamic-sessions 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_MANAGEMENT_ENDPOINT>" \
       --source .
   

   Substitua <OPEN_AI_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.

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