Tutorial: Verwenden von Codeinterpretersitzungen in Semantic Kernel mit Azure Container Apps

Semantic Kernel ist ein Open-Source-KI-Framework, das von Microsoft für .NET- und Python- und Java-Entwickler erstellt wurde, die mit großen Sprachmodellen (LLMs) arbeiten. Wenn Sie einen KI-Agenten mit Semantic Kernel erstellen, interpretiert ein LLM die Benutzereingabe und generiert eine Antwort. Der KI-Agent hat häufig Probleme beim Durchführen von mathematischen und symbolischen Begründungen, um eine Antwort zu erzeugen. Durch die Integration dynamischer Azure Container Apps-Sitzungen in Semantic Kernel geben Sie dem Agenten einen Codeinterpreter oder Codedolmetscher, um spezielle Aufgaben auszuführen.

In diesem Tutorial erfahren Sie, wie Sie einen Semantic Kernel KI-Agent in einer Web-API ausführen. Die API akzeptiert Benutzereingaben und gibt eine vom KI-Agenten generierte Antwort zurück. Der Agent verwendet einen Codeinterpreter in dynamischen Sitzungen, um Berechnungen durchzuführen.

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement.
  • Falls Sie keins haben, können Sie kostenlos eins erstellen.
• Installieren Sie die Azure CLI.
• Git.
• Python 3.10 oder höher.

Erstellen von Azure-Ressourcen

Die Beispiel-App in dieser Schnellstartanleitung verwendet ein LLM von Azure OpenAI. Außerdem werden Azure Container Apps-Sitzungen verwendet, um Code auszuführen, der vom LLM generiert wird.

1. Aktualisieren Sie die Azure CLI auf die neueste Version.

    az upgrade
   

2. Entfernen Sie die Azure Container Apps-Erweiterung, wenn sie bereits installiert ist, und installieren Sie eine Vorschauversion der Azure Container Apps-Erweiterung, die Befehle für Sitzungen enthält:

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

3. Melden Sie sich bei Azure an:

   az login
   

4. Legen Sie die Variablen fest, die in dieser Schnellstartanleitung verwendet werden:

   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
   

   Ersetzen Sie <UNIQUE_OPEN_AI_NAME> durch einen eindeutigen Namen, um Ihr Azure OpenAI-Konto zu erstellen.

5. Erstellen Sie eine Ressourcengruppe:

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

6. Erstellen Sie ein 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
   

7. Erstellen Sie eine GPT 3.5 Turbo-Modellimplementierung namens gpt-35-turbo im Azure OpenAI-Konto:

   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. Erstellen Sie einen Sitzungspool für den Codeinterpreter:

   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
   

Lokales Ausführen der Beispiel-App

Bevor Sie die App in Azure Container Apps bereitstellen, können Sie sie lokal ausführen, um sie zu testen.

Klonen der App

1. Klonen Sie das Repository mit Azure Container Apps-Sitzungsbeispielen.

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

2. Wechseln Sie zum Verzeichnis mit der Beispiel-App:

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

Konfigurieren der App

1. Erstellen Sie eine virtuelle Python-Umgebung, und aktivieren Sie sie:

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

   Ändern Sie die Python-Version im Befehl, wenn Sie eine andere Version verwenden. Es wird empfohlen, Python 3.10 oder höher zu verwenden.

   Hinweis

   Wenn Sie Windows verwenden, ersetzen Sie .venv/bin/activate durch .venv\Scripts\activate.

2. Installieren Sie die erforderlichen Python-Pakete:

   python -m pip install -r requirements.txt
   

3. Zum Ausführen der App müssen Sie Umgebungsvariablen konfigurieren.

   1. Rufen Sie den Azure OpenAI-Kontoendpunkt ab:

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

   2. Rufen Sie den Verwaltungsendpunkt für den Azure Container Apps-Sitzungspool ab:

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

   3. Erstellen Sie eine .env-Datei im Stammverzeichnis des Beispiel-App-Verzeichnisses (gleicher Speicherort wie main.py). Fügen Sie der Datei Folgendes hinzu:

      AZURE_OPENAI_ENDPOINT=<AZURE_OPENAI_ENDPOINT>
      POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGEMENT_ENDPOINT>
      

      Ersetzen Sie <AZURE_OPENAI_ENDPOINT> durch den Azure OpenAI-Kontoendpunkt und <SESSION_POOL_MANAGEMENT_ENDPOINT> durch den Verwaltungsendpunkt für den Sitzungspool.

4. Die App verwendet DefaultAzureCredential für die Authentifizierung mit Azure-Diensten. Auf Ihrem lokalen Computer verwendet sie Ihre aktuellen Azure CLI-Anmeldeinformationen. Sie müssen sich selbst die Rolle Cognitive Services OpenAI-Benutzer für das Azure OpenAI-Konto geben, damit die App auf die Modellendpunkte zugreifen kann. Weiterhin müssen Sie sich die Rolle Azure ContainerApps-Sitzungsausführer für den Sitzungspool geben, damit die App auf den Sitzungspool zugreifen kann.

   1. Rufen Sie Ihren Azure CLI-Benutzernamen ab:

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

   2. Führen Sie die folgenden Befehle aus, um die Ressourcen-ID des Azure OpenAI-Kontos abzurufen:

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

   3. Weisen Sie Ihrem Azure CLI-Benutzer für das Azure OpenAI-Konto die Rolle Cognitive Services OpenAI-Benutzer zu:

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

      Ersetzen Sie <CLI_USERNAME> durch Ihren Azure CLI-Benutzernamen und <AZURE_OPENAI_RESOURCE_ID> durch die Ressourcen-ID des Azure OpenAI-Kontos.

   4. Führen Sie die folgenden Befehle aus, um die Ressourcen-ID des Sitzungspools abzurufen:

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

   5. Weisen Sie Ihrem Azure CLI-Benutzer mit der ID die Rolle Azure ContainerApps-Sitzungsausführer für den Sitzungspool zu:

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

      Ersetzen Sie <CLI_USERNAME> durch Ihren Azure CLI-Benutzernamen und <SESSION_POOL_RESOURCE_ID> durch die Ressourcen-ID des Sitzungspools.

Ausführen der App

Öffnen Sie vor dem Ausführen der Beispiel-App main.py in einem Editor, und überprüfen Sie den Code. Die App verwendet FastAPI zum Erstellen einer Web-API, die eine Benutzernachricht in der Abfragezeichenfolge akzeptiert.

In den folgenden Codezeilen wird ein SessionsPythonTool instanziiert und für den Semantic Kernel-Agenten bereitgestellt:

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

Wenn es Berechnungen ausführen muss, verwendet der Kernel den Codedolmetscher in SessionsPythonTool, um den Code auszuführen. Der Code wird in einer Sitzung im Sitzungspool ausgeführt. Standardmäßig wird ein zufälliger Sitzungsbezeichner generiert, wenn Sie das Tool instanziieren. Wenn der Kernel das Tool zum Ausführen mehrerer Python-Codeschnipsel verwendet, wird dieselbe Sitzung verwendet. Um sicherzustellen, dass jeder Endbenutzer über eine eindeutige Sitzung verfügt, verwenden Sie einen separaten Kernel und ein eigenes Tool für jeden Benutzer.

SessionsPythonTool ist in Version 0.9.8b1 oder höher des semantic-kernel-Pakets verfügbar.

1. Führen Sie die Beispiel-App aus:

   fastapi dev main.py
   

2. Öffnen Sie einen Browser, und navigieren Sie zu http://localhost:8000/docs. Die Swagger-Benutzeroberfläche für die Beispiel-App wird angezeigt.

3. Erweitern Sie den Endpunkt /chat, und wählen Sie Ausprobieren aus.

4. Geben Sie What time is it right now? in das Feld message ein, und wählen Sie Ausführen aus.

   Der Agent antwortet mit der aktuellen Uhrzeit. Im Terminal sehen Sie die Protokolle, aus denen hervorgeht, dass der Agent Python-Code zum Abrufen der aktuellen Zeit generiert und in einer Codeinterpretersitzung ausgeführt hat.

5. Geben Sie zum Beenden der App Ctrl+C in das Terminal ein.

Optional: Bereitstellen der Beispiel-App in Azure Container Apps

Um die FastAPI-App in Azure Container Apps bereitzustellen, müssen Sie ein Containerimage erstellen und an eine Containerregistrierung übertragen. Dann können Sie das Image in Azure Container Apps bereitstellen. Der Befehl az containerapp up kombiniert diese Schritte in einem einzigen Befehl.

Anschließend müssen Sie die verwaltete Identität für die App konfigurieren und ihr die richtigen Rollen zuweisen, um auf Azure OpenAI und den Sitzungspool zuzugreifen.

1. Legen Sie die Variablen für die Container Apps-Umgebung und den App-Namen fest:

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

2. Erstellen Sie die App, und stellen Sie sie in Azure Container Apps bereit:

   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 .
   

   Ersetzen Sie <OPEN_AI_ENDPOINT> durch den Azure OpenAI-Kontoendpunkt und <SESSION_POOL_MANAGMENT_ENDPOINT> durch den Verwaltungsendpunkt für den Sitzungspool.

3. Aktivieren Sie die systemseitig zugewiesene verwaltete Identität für die App:

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

4. Damit die App auf Azure OpenAI und den Sitzungspool zugreifen kann, müssen Sie der verwalteten Identität die entsprechenden Rollen zuweisen.

   1. Rufen Sie die Prinzipal-ID der verwalteten Identität ab:

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

   2. Rufen Sie die Ressourcen-ID des Sitzungspools ab:

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

   3. Weisen Sie der verwalteten Identität die Rollen Azure ContainerApps Session Executor und Contributor für den Sitzungspool zu:

      Ersetzen Sie vor dem Ausführen des folgenden Befehls <PRINCIPAL_ID> und <SESSION_POOL_RESOURCE_ID> durch die Werte, die Sie in den vorherigen Schritten abgerufen haben.

      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. Rufen Sie die Ressourcen-ID für das Azure OpenAI-Konto ab:

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

   5. Weisen Sie der verwalteten Identität die Rolle Cognitive Services OpenAI User für das Azure OpenAI-Konto zu:

      Ersetzen Sie vor dem Ausführen des folgenden Befehls <PRINCIPAL_ID> und <AZURE_OPENAI_RESOURCE_ID> durch die Werte, die Sie in den vorherigen Schritten abgerufen haben.

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

5. Rufen Sie den vollqualifizierten Domänennamen (FQDN) der App ab:

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

6. Navigieren Sie im Browser zu https://<FQDN>/docs, um die bereitgestellte App zu testen.

Bereinigen von Ressourcen

Wenn Sie die Ressourcen nicht mehr benötigen, können Sie sie löschen, um Kosten zu vermeiden:

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

Nächste Schritte

Codeinterpretersitzungen