Esercitazione: Usare sessioni dell'interprete di codice in LangChain con App Azure Container

LangChain è un framework progettato per semplificare la creazione di applicazioni usando modelli di linguaggio di grandi dimensioni. Quando si compila un agente di intelligenza artificiale con LangChain, un LLM interpreta l'input dell'utente e genera una risposta. L'agente di intelligenza artificiale spesso lotta quando deve eseguire ragionamenti matematici e simbolici per produrre una risposta. Integrando le sessioni dinamiche di App Azure Container con LangChain, si assegna all'agente un interprete di codice da usare per eseguire attività specializzate.

Questa esercitazione illustra come eseguire un agente di intelligenza artificiale LangChain in un'API Web. L'API accetta l'input dell'utente e restituisce una risposta generata dall'agente di intelligenza artificiale. L'agente usa un interprete di codice nelle sessioni dinamiche per eseguire calcoli.

Prerequisiti

• Un account Azure con una sottoscrizione attiva.
  • Se non hai un account, puoi crearlo gratuitamente.
• Installare l'interfaccia della riga di comando di Azure.
• Git.
• Python 3.10 o versione successiva.

Creazione di risorse Azure

L'app di esempio in questa guida introduttiva usa un LLM di Azure OpenAI. Usa anche le sessioni di App Contenitore di Azure per eseguire il codice generato dall'LLM.

1. Aggiornare l'interfaccia della riga di comando di Azure alla versione più recente.

    az upgrade
   

2. Rimuovere l'estensione App Azure Container se è già installata e installare una versione di anteprima dell'estensione App Azure Container contenente i comandi per le sessioni:

   az extension remove --name containerapp
   az extension add \
       --name containerapp \
       --allow-preview true -y
   

3. Accedere ad Azure:

   az login
   

4. Impostare le variabili usate in questa guida introduttiva:

   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
   

   Sostituire <UNIQUE_OPEN_AI_NAME> con un nome univoco per creare l'account OpenAI di Azure.

5. Creare un gruppo di risorse:

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

6. Creare un account 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. Creare una distribuzione di modelli GPT 3.5 Turbo denominata gpt-35-turbo nell'account 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. Creare un pool di sessioni dell'interprete del codice:

   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
   

Eseguire l'app di esempio in locale

Prima di distribuire l'app in App Contenitore di Azure, è possibile eseguirla in locale per testarla.

Clonare l'app

1. Clonare il repository di esempi di sessioni di App Azure Container.

   git clone https://github.com/Azure-Samples/container-apps-dynamic-sessions-samples.git
   

2. Passare alla directory che contiene l'app di esempio:

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

Configurare l'app

1. Creare un ambiente virtuale Python e attivarlo:

   python3.11 -m venv .venv
   source .venv/bin/activate
   

   Modificare la versione di Python nel comando se si usa una versione diversa. È consigliabile usare Python 3.10 o versione successiva.

   Nota

   Se si usa Windows, sostituire .venv/bin/activate con .venv\Scripts\activate.

2. Installare i pacchetti Python necessari:

   python -m pip install -r requirements.txt
   

3. Per eseguire l'app, è necessario configurare le variabili di ambiente.

   1. Recuperare l'endpoint dell'account OpenAI di Azure:

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

   2. Recuperare l'endpoint di gestione del pool di sessioni di App Azure Container:

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

   3. Creare un .env file nella radice della directory dell'app di esempio (stessa posizione di main.py). Aggiungere il seguente contenuto nel file:

      AZURE_OPENAI_ENDPOINT=<AZURE_OPENAI_ENDPOINT>
      POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGEMENT_ENDPOINT>
      

      Sostituire <AZURE_OPENAI_ENDPOINT> con l'endpoint dell'account OpenAI di Azure e <SESSION_POOL_MANAGEMENT_ENDPOINT> con l'endpoint di gestione del pool di sessioni.

4. L'app usa DefaultAzureCredential per eseguire l'autenticazione con i servizi di Azure. Nel computer locale usa le credenziali di accesso correnti dell'interfaccia della riga di comando di Azure. È necessario assegnare a se stessi il ruolo utente OpenAI di Servizi cognitivi nell'account OpenAI di Azure per consentire all'app di accedere agli endpoint del modello e al ruolo Executor sessione di Azure ContainerApps nel pool di sessioni per consentire all'app di accedere al pool di sessioni.

   1. Recuperare il nome utente dell'interfaccia della riga di comando di Azure:

      az account show --query user.name --output tsv
      

   2. Eseguire i comandi seguenti per recuperare l'ID risorsa dell'account Azure OpenAI:

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

   3. Assegnare il ruolo utente OpenAI di Servizi cognitivi all'utente dell'interfaccia della riga di comando di Azure nell'account OpenAI di Azure:

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

      Sostituire <CLI_USERNAME> con il nome utente dell'interfaccia della riga di comando di Azure e <AZURE_OPENAI_RESOURCE_ID> con l'ID risorsa dell'account OpenAI di Azure.

   4. Eseguire i comandi seguenti per recuperare l'ID risorsa del pool di sessioni:

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

   5. Assegnare il ruolo Di executor sessione di Azure ContainerApps usando il relativo ID all'utente dell'interfaccia della riga di comando di Azure nel pool di sessioni:

      az role assignment create \
          --role "Azure ContainerApps Session Executor" \
          --assignee <CLI_USERNAME> \
          --scope <SESSION_POOL_RESOURCE_ID>
      

      Sostituire <CLI_USERNAME> con il nome utente dell'interfaccia della riga di comando di Azure e <SESSION_POOL_RESOURCE_ID> con l'ID risorsa del pool di sessioni.

Eseguire l'app

Prima di eseguire l'app di esempio, aprire main.py in un editor ed esaminare il codice. L'app usa FastAPI per creare un'API Web che accetta un messaggio utente nella stringa di query.

Le righe di codice seguenti creano un'istanza di SessionPythonREPLTool e la forniscono all'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 è necessario eseguire calcoli, l'agente usa SessionPythonREPLTool per eseguire il codice. Il codice viene eseguito in una sessione nel pool di sessioni. Per impostazione predefinita, viene generato un identificatore di sessione casuale quando si crea un'istanza dello strumento. Se l'agente usa lo strumento per eseguire più frammenti di codice Python, usa la stessa sessione. Per garantire che ogni utente finale abbia una sessione univoca, usare un agente e uno strumento separati per ogni utente.

SessionPythonREPLTool è disponibile nel langchain-azure-dynamic-sessions pacchetto.

1. Eseguire l'app di esempio:

   fastapi dev main.py
   

2. Aprire un browser e passare a http://localhost:8000/docs. Viene visualizzata l'interfaccia utente di Swagger per l'app di esempio.

3. Espandere l'endpoint /chat e selezionare Prova.

4. Immettere What time is it right now? nel message campo e selezionare Esegui.

   L'agente risponde con l'ora corrente. Nel terminale vengono visualizzati i log che mostrano il codice Python generato dall'agente per ottenere l'ora corrente ed eseguirlo in una sessione dell'interprete del codice.

5. Per arrestare l'app, immettere Ctrl+C nel terminale.

Facoltativo: distribuire l'app di esempio in App Azure Container

Per distribuire l'app FastAPI in App Contenitore di Azure, è necessario creare un'immagine del contenitore ed eseguirne il push in un registro contenitori. È quindi possibile distribuire l'immagine in App Azure Container. Il az containerapp up comando combina questi passaggi in un singolo comando.

È quindi necessario configurare l'identità gestita per l'app e assegnargli i ruoli appropriati per accedere ad Azure OpenAI e al pool di sessioni.

1. Impostare le variabili per l'ambiente app contenitore e il nome dell'app:

   ENVIRONMENT_NAME=aca-sessions-tutorial-env
   CONTAINER_APP_NAME=chat-api
   

2. Compilare e distribuire l'app in App Azure Container:

   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 .
   

   Sostituire <OPEN_AI_ENDPOINT> con l'endpoint dell'account OpenAI di Azure e <SESSION_POOL_MANAGMENT_ENDPOINT> con l'endpoint di gestione del pool di sessioni.

3. Abilitare l'identità gestita assegnata dal sistema per l'app:

   az containerapp identity assign \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --system-assigned
   

4. Per consentire all'app di accedere ad Azure OpenAI e al pool di sessioni, è necessario assegnare l'identità gestita ai ruoli appropriati.

   1. Recuperare l'ID entità dell'identità gestita:

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

   2. Recuperare l'ID risorsa del pool di sessioni:

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

   3. Assegnare l'identità gestita ai Azure ContainerApps Session Executor ruoli e Contributor nel pool di sessioni:

      Prima di eseguire il comando seguente, sostituire <PRINCIPAL_ID> e <SESSION_POOL_RESOURCE_ID> con i valori recuperati nei passaggi precedenti.

      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. Recuperare l'ID risorsa dell'account OpenAI di Azure:

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

   5. Assegnare l'identità gestita al Cognitive Services OpenAI User ruolo nell'account OpenAI di Azure:

      Prima di eseguire il comando seguente, sostituire <PRINCIPAL_ID> e <AZURE_OPENAI_RESOURCE_ID> con i valori recuperati nei passaggi precedenti.

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

5. Recuperare il nome di dominio completo (FQDN) dell'app:

   az containerapp show \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --query properties.configuration.ingress.fqdn \
       --output tsv
   

6. Aprire il browser per https://<FQDN>/docs testare l'app distribuita.

Pulire le risorse

Al termine delle risorse, è possibile eliminarle per evitare di incorrere in addebiti:

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

Passaggi successivi

Sessioni dell'interprete di codice