Självstudie: Använda kodtolksessioner i semantisk kernel med Azure Container Apps

Artikel
05/17/2024

Semantisk kernel är ett AI-ramverk med öppen källkod som skapats av Microsoft för .NET-, Python- och Java-utvecklare som arbetar med stora språkmodeller (LLM). När du skapar en AI-agent med semantisk kernel tolkar en LLM användarindata och genererar ett svar. AI-agenten kämpar ofta när den behöver utföra matematiska och symboliska resonemang för att skapa ett svar. Genom att integrera dynamiska Sessioner i Azure Container Apps med Semantic Kernel ger du agenten en kodtolk som ska användas för att utföra specialiserade uppgifter.

I den här självstudien får du lära dig hur du kör en Semantic Kernel AI-agent i ett webb-API. API:et accepterar användarindata och returnerar ett svar som genereras av AI-agenten. Agenten använder en kodtolkning i dynamiska sessioner för att utföra beräkningar.

Kommentar

Dynamiska Sessioner i Azure Container Apps är för närvarande i förhandsversion. Mer information finns i förhandsversionsbegränsningar .

Förutsättningar

Ett Azure-konto med en aktiv prenumeration.
- Om du inte har någon sådan nu kan du skapa en kostnadsfritt.
Installera Azure CLI.
Git.
Python 3.10 eller senare.

Skapa Azure-resurser

Exempelappen i den här snabbstarten använder en LLM från Azure OpenAI. Den använder också Azure Container Apps-sessioner för att köra kod som genereras av LLM.

Uppdatera Azure CLI till den senaste versionen.
```
 az upgrade
```
Ta bort Azure Container Apps-tillägget om det redan är installerat och installera en förhandsversion av Azure Container Apps-tillägget som innehåller kommandon för sessioner:
```
az extension remove --name containerapp
az extension add \
    --name containerapp \
    --allow-preview true -y
```
Logga in på Azure:
```
az login
```

Ange de variabler som används i den här snabbstarten:

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

Ersätt <UNIQUE_OPEN_AI_NAME> med ett unikt namn för att skapa ditt Azure OpenAI-konto.

Skapa en resursgrupp:

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

Skapa ett Azure OpenAI-konto:

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

Skapa en GPT 3.5 Turbo-modelldistribution med namnet gpt-35-turbo i Azure OpenAI-kontot:

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"

Skapa en kodtolkarsessionspool:

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

Kör exempelappen lokalt

Innan du distribuerar appen till Azure Container Apps kan du köra den lokalt för att testa den.

Klona appen

Klona lagringsplatsen för Azure Container Apps-sessioner.

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

Ändra till katalogen som innehåller exempelappen:

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

Konfigurera appen

Skapa en virtuell Python-miljö och aktivera den:
```
python3.11 -m venv .venv
source .venv/bin/activate
```
Ändra Python-versionen i kommandot om du använder en annan version. Vi rekommenderar att du använder Python 3.10 eller senare.

Kommentar

Om du använder Windows ersätter .venv/bin/activate du med .venv\Scripts\activate.

Installera nödvändiga Python-paket:

python -m pip install -r requirements.txt

Om du vill köra appen måste du konfigurera miljövariabler.

Hämta Azure OpenAI-kontoslutpunkten:

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

Hämta azure Container Apps-sessionspoolens hanteringsslutpunkt:

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

Skapa en .env fil i roten i exempelappkatalogen (samma plats som main.py). Lägg till följande innehåll i filen:
```
AZURE_OPENAI_ENDPOINT=<AZURE_OPENAI_ENDPOINT>
POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGEMENT_ENDPOINT>
```
Ersätt <AZURE_OPENAI_ENDPOINT> med Azure OpenAI-kontoslutpunkten och <SESSION_POOL_MANAGEMENT_ENDPOINT> med slutpunkten för hantering av sessionspooler.

Appen använder DefaultAzureCredential för att autentisera med Azure-tjänster. På den lokala datorn använder den dina aktuella Inloggningsuppgifter för Azure CLI. Du måste ge dig själv rollen Cognitive Services OpenAI-användare på Azure OpenAI-kontot för att appen ska få åtkomst till modellslutpunkterna och rollen Azure ContainerApps Session Executor i sessionspoolen för att appen ska få åtkomst till sessionspoolen.
1. Hämta ditt Azure CLI-användarnamn:
```
az account show --query user.name --output tsv
```
2. Kör följande kommandon för att hämta resurs-ID:t för Azure OpenAI-kontot:
```
az cognitiveservices account show --name $AZURE_OPENAI_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
```
3. Tilldela Cognitive Services OpenAI-användarrollen till din Azure CLI-användare på Azure OpenAI-kontot:
```
az role assignment create --role "Cognitive Services OpenAI User" --assignee <CLI_USERNAME> --scope <AZURE_OPENAI_RESOURCE_ID>
```
  Ersätt <CLI_USERNAME> med ditt Azure CLI-användarnamn och <AZURE_OPENAI_RESOURCE_ID> med resurs-ID:t för Azure OpenAI-kontot.
4. Kör följande kommandon för att hämta sessionspoolens resurs-ID:
```
az containerapp sessionpool show --name $SESSION_POOL_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
```
5. Tilldela azure ContainerApps-sessionskörningsrollen med hjälp av dess ID till din Azure CLI-användare i sessionspoolen:
```
az role assignment create \
    --role "Azure ContainerApps Session Executor" \
    --assignee <CLI_USERNAME> \
    --scope <SESSION_POOL_RESOURCE_ID>
```
  Ersätt <CLI_USERNAME> med ditt Azure CLI-användarnamn och <SESSION_POOL_RESOURCE_ID> med resurs-ID:t för sessionspoolen.

Kör appen

Innan du kör exempelappen öppnar du main.py i ett redigeringsprogram och granskar koden. Appen använder FastAPI för att skapa ett webb-API som accepterar ett användarmeddelande i frågesträngen.

Följande kodrader instansierar en SessionsPythonTool och anger den till semantisk kernelagent:

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

När den behöver utföra beräkningar använder kerneln kodtolkaren i SessionsPythonTool för att köra koden. Koden körs i en session i sessionspoolen. Som standard genereras en slumpmässig sessionsidentifierare när du instansierar verktyget. Om kerneln använder verktyget för att köra flera Python-kodfragment använder den samma session. För att säkerställa att varje slutanvändare har en unik session använder du en separat kernel och ett verktyg för varje användare.

SessionsPythonTool är tillgängligt i version 0.9.8b1 eller senare av semantic-kernel paketet.

Kör exempelappen:
```
fastapi dev main.py
```
Öppna en webbläsare och navigera till http://localhost:8000/docs. Du ser Swagger-användargränssnittet för exempelappen.
/chat Expandera slutpunkten och välj Prova.
Ange What time is it right now? i fältet message och välj Kör.

Agenten svarar med den aktuella tiden. I terminalen visas loggarna som visar agenten genererade Python-kod för att hämta den aktuella tiden och körde den i en kodtolkarsession.
Om du vill stoppa appen anger du Ctrl+C i terminalen.

Valfritt: Distribuera exempelappen till Azure Container Apps

Om du vill distribuera FastAPI-appen till Azure Container Apps måste du skapa en containeravbildning och skicka den till ett containerregister. Sedan kan du distribuera avbildningen till Azure Container Apps. Kommandot az containerapp up kombinerar de här stegen i ett enda kommando.

Sedan måste du konfigurera en hanterad identitet för appen och tilldela den rätt roller för åtkomst till Azure OpenAI och sessionspoolen.

Ange variablerna för Container Apps-miljön och appnamnet:

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

Skapa och distribuera appen till 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 .

Ersätt <OPEN_AI_ENDPOINT> med Azure OpenAI-kontoslutpunkten och <SESSION_POOL_MANAGMENT_ENDPOINT> med slutpunkten för hantering av sessionspooler.

Aktivera den systemtilldelade hanterade identiteten för appen:

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

För att appen ska få åtkomst till Azure OpenAI och sessionspoolen måste du tilldela den hanterade identiteten rätt roller.

Hämta den hanterade identitetens huvud-ID:

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

Hämta sessionspoolens resurs-ID:

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

Tilldela den hanterade identiteten Azure ContainerApps Session Executor och Contributor rollerna i sessionspoolen:

Innan du kör följande kommando ersätter <PRINCIPAL_ID> du och <SESSION_POOL_RESOURCE_ID> med de värden som du hämtade i föregående steg.

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>

Hämta resurs-ID:t för Azure OpenAI-kontot:

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

Tilldela den hanterade identiteten Cognitive Services OpenAI User rollen för Azure OpenAI-kontot:

Innan du kör följande kommando ersätter <PRINCIPAL_ID> du och <AZURE_OPENAI_RESOURCE_ID> med de värden som du hämtade i föregående steg.
```
az role assignment create \
    --role "Cognitive Services OpenAI User" \
    --assignee <PRINCIPAL_ID> \
    --scope <AZURE_OPENAI_RESOURCE_ID>
```

Hämta appens fullständigt kvalificerade domännamn (FQDN):

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

Öppna webbläsaren för att https://<FQDN>/docs testa den distribuerade appen.

Rensa resurser

När du är klar med resurserna kan du ta bort dem för att undvika avgifter:

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

Nästa steg

Kodtolkarsessioner

Dela via