Zelfstudie: Code-interpretersessies gebruiken in Semantische kernel met Azure Container Apps

Semantische kernel is een opensource AI-framework dat is gemaakt door Microsoft voor .NET-, Python- en Java-ontwikkelaars die werken met LLM's (Large Language Models). Wanneer u een AI-agent bouwt met Semantische kernel, interpreteert een LLM gebruikersinvoer en genereert een antwoord. De AI-agent worstelt vaak wanneer er wiskundige en symbolische redeneringen moeten worden uitgevoerd om een antwoord te produceren. Door dynamische sessies van Azure Container Apps te integreren met Semantic Kernel, geeft u de agent een code-interpreter om gespecialiseerde taken uit te voeren.

In deze zelfstudie leert u hoe u een Semantische Kernel AI-agent uitvoert in een web-API. De API accepteert gebruikersinvoer en retourneert een antwoord dat is gegenereerd door de AI-agent. De agent gebruikt een code-interpreter in dynamische sessies om berekeningen uit te voeren.

Vereisten

• Een Azure-account met een actief abonnement.
  • Als u geen account hebt, kunt u er gratis een maken.
• Installeer de Azure CLI.
• Git.
• Python 3.10 of hoger.

Azure-resources maken

De voorbeeld-app in deze quickstart maakt gebruik van een LLM van Azure OpenAI. Er worden ook Azure Container Apps-sessies gebruikt om code uit te voeren die is gegenereerd door de LLM.

1. Werk de Azure CLI bij naar de nieuwste versie.

    az upgrade
   

2. Verwijder de Azure Container Apps-extensie als deze al is geïnstalleerd en installeer een preview-versie van de Azure Container Apps-extensie met opdrachten voor sessies:

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

3. Meld u aan bij Azure:

   az login
   

4. Stel de variabelen in die in deze quickstart worden gebruikt:

   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
   

   Vervang door <UNIQUE_OPEN_AI_NAME> een unieke naam om uw Azure OpenAI-account te maken.

5. Een resourcegroep maken:

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

6. Maak een Azure OpenAI-account:

   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. Maak een GPT 3.5 Turbo-modelimplementatie met de naam gpt-35-turbo in het Azure OpenAI-account:

   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. Maak een sessiegroep voor code-interpreters:

   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
   

De voorbeeld-app lokaal uitvoeren

Voordat u de app implementeert in Azure Container Apps, kunt u deze lokaal uitvoeren om deze te testen.

De app klonen

1. Kloon de opslagplaats met voorbeelden van Azure Container Apps-sessies.

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

2. Ga naar de map met de voorbeeld-app:

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

De app configureren

1. Maak een virtuele Python-omgeving en activeer deze:

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

   Wijzig de Python-versie in de opdracht als u een andere versie gebruikt. Het is raadzaam python 3.10 of hoger te gebruiken.

   Notitie

   Als u Windows gebruikt, vervangt u door .venv/bin/activate .venv\Scripts\activate.

2. Installeer de vereiste Python-pakketten:

   python -m pip install -r requirements.txt
   

3. Als u de app wilt uitvoeren, moet u omgevingsvariabelen configureren.

   1. Haal het Eindpunt van het Azure OpenAI-account op:

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

   2. Haal het beheereindpunt van de Sessiegroep van Azure Container Apps op:

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

   3. Maak een .env bestand in de hoofdmap van de voorbeeld-app-map (dezelfde locatie als main.py). De volgende inhoud toevoegen aan het bestand:

      AZURE_OPENAI_ENDPOINT=<AZURE_OPENAI_ENDPOINT>
      POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGEMENT_ENDPOINT>
      

      Vervang <AZURE_OPENAI_ENDPOINT> door het Eindpunt van het Azure OpenAI-account en <SESSION_POOL_MANAGEMENT_ENDPOINT> door het eindpunt voor sessiegroepbeheer.

4. De app gebruikt DefaultAzureCredential voor verificatie met Azure-services. Op uw lokale computer worden uw huidige azure CLI-aanmeldingsreferenties gebruikt. U moet uzelf de Gebruikersrol Cognitive Services OpenAI geven in het Azure OpenAI-account voor de app om toegang te krijgen tot de modeleindpunten en de rol Azure ContainerApps Session Executor in de sessiegroep voor de app om toegang te krijgen tot de sessiegroep.

   1. Haal uw Azure CLI-gebruikersnaam op:

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

   2. Voer de volgende opdrachten uit om de resource-id van het Azure OpenAI-account op te halen:

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

   3. Wijs de Gebruikersrol Cognitive Services OpenAI toe aan uw Azure CLI-gebruiker in het Azure OpenAI-account:

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

      Vervang <CLI_USERNAME> door uw Azure CLI-gebruikersnaam en <AZURE_OPENAI_RESOURCE_ID> door de resource-id van het Azure OpenAI-account.

   4. Voer de volgende opdrachten uit om de resource-id van de sessiegroep op te halen:

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

   5. Wijs de azure ContainerApps Session Executor-rol toe met behulp van de id ervan aan uw Azure CLI-gebruiker in de sessiegroep:

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

      Vervang <CLI_USERNAME> door uw Azure CLI-gebruikersnaam en <SESSION_POOL_RESOURCE_ID> door de resource-id van de sessiegroep.

De app uitvoeren

Voordat u de voorbeeld-app uitvoert, opent u main.py in een editor en controleert u de code. De app maakt gebruik van FastAPI om een web-API te maken die een gebruikersbericht in de querytekenreeks accepteert.

De volgende regels code instantiëren een SessionsPythonTool en leveren deze aan de Semantische Kernel-agent:

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

Wanneer er berekeningen moeten worden uitgevoerd, gebruikt de kernel de code-interpreter in SessionsPythonTool om de code uit te voeren. De code wordt uitgevoerd in een sessie in de sessiegroep. Standaard wordt er een willekeurige sessie-id gegenereerd wanneer u het hulpprogramma instantiëren. Als de kernel het hulpprogramma gebruikt om meerdere Python-codefragmenten uit te voeren, wordt dezelfde sessie gebruikt. Gebruik een afzonderlijke kernel en een afzonderlijk hulpprogramma voor elke gebruiker om ervoor te zorgen dat elke eindgebruiker een unieke sessie heeft.

SessionsPythonTool is beschikbaar in versie 0.9.8b1 of hoger van het semantic-kernel pakket.

1. Voer de voorbeeld-app uit:

   fastapi dev main.py
   

2. Open een browser en ga naar http://localhost:8000/docs. U ziet de Swagger-gebruikersinterface voor de voorbeeld-app.

3. Vouw het /chat eindpunt uit en selecteer Uitproberen.

4. Voer What time is it right now? in het message veld in en selecteer Uitvoeren.

   De agent reageert met de huidige tijd. In de terminal ziet u de logboeken met de door de agent gegenereerde Python-code om de huidige tijd op te halen en deze uit te voeren in een code-interpretersessie.

5. Als u de app wilt stoppen, voert u Ctrl+C de terminal in.

Optioneel: De voorbeeld-app implementeren in Azure Container Apps

Als u de FastAPI-app wilt implementeren in Azure Container Apps, moet u een containerinstallatiekopieën maken en naar een containerregister pushen. Vervolgens kunt u de installatiekopieën implementeren in Azure Container Apps. De az containerapp up opdracht combineert deze stappen in één opdracht.

Vervolgens moet u een beheerde identiteit voor de app configureren en deze de juiste rollen toewijzen voor toegang tot Azure OpenAI en de sessiegroep.

1. Stel de variabelen in voor de Container Apps-omgeving en de app-naam:

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

2. Bouw en implementeer de app in Azure Container Apps:

   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 .
   

   Vervang <OPEN_AI_ENDPOINT> door het Eindpunt van het Azure OpenAI-account en <SESSION_POOL_MANAGMENT_ENDPOINT> door het eindpunt voor sessiegroepbeheer.

3. Schakel de door het systeem toegewezen beheerde identiteit in voor de app:

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

4. Voor toegang tot Azure OpenAI en de sessiegroep moet u de beheerde identiteit de juiste rollen toewijzen aan de app.

   1. Haal de principal-id van de beheerde identiteit op:

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

   2. Haal de resource-id van de sessiegroep op:

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

   3. Wijs de beheerde identiteit de Azure ContainerApps Session Executor en Contributor rollen in de sessiegroep toe:

      Voordat u de volgende opdracht uitvoert, vervangt <PRINCIPAL_ID> u de <SESSION_POOL_RESOURCE_ID> waarden die u in de vorige stappen hebt opgehaald.

      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. Haal de resource-id van het Azure OpenAI-account op:

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

   5. Wijs de beheerde identiteit Cognitive Services OpenAI User de rol toe aan het Azure OpenAI-account:

      Voordat u de volgende opdracht uitvoert, vervangt <PRINCIPAL_ID> u de <AZURE_OPENAI_RESOURCE_ID> waarden die u in de vorige stappen hebt opgehaald.

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

5. De FQDN (Fully Qualified Domain Name) van de app ophalen:

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

6. Open de browser om de geïmplementeerde app te https://<FQDN>/docs testen.

Resources opschonen

Wanneer u klaar bent met de resources, kunt u ze verwijderen om kosten te voorkomen:

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

Volgende stappen

Code-interpretersessies