Serverlose Code-Interpreter-Sitzungen in Azure Container Apps

Artikel
10/24/2024

Dynamische Sitzungen in Azure Container Apps bieten schnellen und skalierbaren Zugriff auf einen Codeinterpreter. Jede Codeinterpretersitzung ist durch eine Hyper-V-Grenze vollständig isoliert und für das Ausführen von nicht vertrauenswürdigem Code konzipiert.

Anwendungsfälle für Codeinterpretersitzungen

Codeinterpretersitzungen eignen sich ideal für Szenarien, in denen Sie Code ausführen müssen, der potenziell schädlich ist oder dem Hostsystem oder anderen Benutzern schaden könnte, z. B.:

Code, der von einem großen Sprachmodell (LLM) generiert wird.
Code, der von einem Endbenutzer in einer Web- oder SaaS-Anwendung übermittelt wird.

Für beliebte LLM-Frameworks wie LangChain, LlamaIndex oder Semantic Kernel können Sie Tools und Plug-Ins verwenden, um KI-Apps in Codeinterpretersitzungen zu integrieren.

Ihre Anwendungen können auch mithilfe einer REST-API in Codeinterpretersitzungen integriert werden. Mit der API können Sie Code in einer Sitzung ausführen und Ergebnisse abrufen. Sie können Dateien auch in die Sitzung hochladen und daraus herunterladen. Sie können ausführbare Codedateien oder Datendateien hochladen und herunterladen, die Ihr Code verarbeiten kann.

Die integrierten Codeinterpretersitzungen unterstützen die häufigsten Codeausführungsszenarien, ohne dass Infrastruktur oder Container verwaltet werden müssen. Wenn Sie die vollständige Kontrolle über die Codeausführungsumgebung benötigen oder über ein anderes Szenario verfügen, das isolierte Sandboxes erfordert, können Sie benutzerdefinierte Codeinterpretersitzungenverwenden.

Codeinterpreter-Sitzungspool

Um Codeinterpretersitzungen zu verwenden, benötigen Sie eine Azure-Ressource, die als Sitzungspool bezeichnet wird und die die Konfiguration für Codeinterpretersitzungen definiert. Im Sitzungspool können Sie Einstellungen angeben, z. B. die maximale Anzahl gleichzeitiger Sitzungen und wie lange eine Sitzung im Leerlauf sein kann, bevor sie beendet wird.

Sie können einen Sitzungspool über das Azure-Portal, die Azure CLI oder mithilfe von Azure Resource Manager-Vorlagen erstellen. Nachdem Sie einen Sitzungspool erstellt haben, können Sie die API-Verwaltungsendpunkte des Pools verwenden, um Code innerhalb einer Sitzung zu verwalten und auszuführen.

Erstellen eines Sitzungspools mithilfe der Azure-Befehlszeilenschnittstelle

Um einen Codeinterpreter-Sitzungspool mit der Azure CLI zu erstellen, stellen Sie sicher, dass Sie über die neuesten Versionen der Azure CLI und der Azure Container Apps-Erweiterung verfügen. Verwenden Sie die folgenden Befehle:

# Upgrade the Azure CLI
az upgrade

# Install or upgrade the Azure Container Apps extension
az extension add --name containerapp --upgrade --allow-preview true -y

Verwenden Sie den az containerapps sessionpool create-Befehl, um den Pool zu erstellen. Im folgenden Beispiel wird ein Python-Codeinterpreter-Sitzungspool mit dem Namen my-session-pool erstellt. Ersetzen Sie <RESOURCE_GROUP> durch den Namen Ihrer Ressourcengruppe, bevor Sie den Befehl ausführen.

az containerapp sessionpool create \
    --name my-session-pool \
    --resource-group <RESOURCE_GROUP> \
    --location westus2 \
    --container-type PythonLTS \
    --max-sessions 100 \
    --cooldown-period 300 \
    --network-status EgressDisabled

Sie können beim Erstellen eines Sitzungspools die folgenden Einstellungen definieren:

Einstellung	Beschreibung
`--container-type`	Der Typ des zu verwendenden Codeinterpreters. Der einzige unterstützte Wert lautet `PythonLTS`.
`--max-sessions`	Die maximale Anzahl der zugewiesenen Sitzungen, die gleichzeitig zulässig sind. Der höchste Wert ist `600`.
`--cooldown-period`	Die Anzahl der zulässigen Leerlauf-Sekunden vor der Beendigung. Der Leerlaufzeitraum wird jedes Mal zurückgesetzt, wenn die API der Sitzung aufgerufen wird. Der gültige Bereich liegt zwischen `300` und `3600`.
`--network-status`	Legt fest, ob ausgehender Netzwerkdatenverkehr aus der Sitzung zulässig ist. Gültige Werte sind `EgressDisabled` (Standard) und `EgressEnabled`.

Wichtig

Wenn Sie ausgehenden Datenverkehr zulassen, kann Code, der in der Sitzung ausgeführt wird, auf das Internet zugreifen. Seien Sie vorsichtig, wenn der Code nicht vertrauenswürdig ist, da er für schädliche Aktivitäten wie Denial-of-Service-Angriffe verwendet werden kann.

Abrufen des API-Endpunkts für die Poolverwaltung mit der Azure CLI

Um Codeinterpretersitzungen mit LLM-Frameworkintegrationen oder durch direktes Aufrufen der API-Verwaltungsendpunkte des Pools zu verwenden, benötigen Sie den API-Verwaltungsendpunkt des Pools. Der Endpunkt weist folgendes Format auf: https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>.

Verwenden Sie den Befehl az containerapps sessionpool show, um den API-Verwaltungsendpunkt für einen Sitzungspool abzurufen. Ersetzen Sie <RESOURCE_GROUP> durch den Namen Ihrer Ressourcengruppe, bevor Sie den Befehl ausführen.

az containerapp sessionpool show \
    --name my-session-pool \
    --resource-group <RESOURCE_GROUP> \
    --query 'properties.poolManagementEndpoint' -o tsv

Codeausführung in einer Sitzung

Nachdem Sie einen Sitzungspool erstellt haben, kann Ihre Anwendung mit Sitzungen im Pool interagieren, indem sie eine Integration mit einem LLM-Framework oder direkt die API-Verwaltungsendpunkte des Pools verwendet.

Sitzungs-IDs

Wichtig

Der Sitzungsbezeichner ist eine vertrauliche Angabe. Sie benötigen einen sicheren Prozess zum Verwalten seines Werts. Im Rahmen dieses Prozesses muss Ihre Anwendung sicherstellen, dass jeder Benutzer oder Mandant nur Zugriff auf seine eigenen Sitzungen hat. Wenn Sie den Zugriff auf Sitzungen nicht sichern, kann dies zu Missbrauch oder unbefugtem Zugriff auf Daten führen, die in den Sitzungen Ihrer Benutzer gespeichert sind. Weitere Informationen finden Sie unter Sitzungs-IDs.

Wenn Sie mit Sitzungen in einem Pool interagieren, verwenden Sie eine Sitzungs-ID, um auf jede Sitzung zu verweisen. Eine Sitzungs-ID ist eine Zeichenfolge, die Sie definieren und die innerhalb des Sitzungspools eindeutig ist. Wenn Sie eine Webanwendung erstellen, können Sie die ID des Benutzers verwenden. Wenn Sie einen Chatbot erstellen, können Sie die Unterhaltungs-ID verwenden.

Wenn eine laufende Sitzung mit der ID vorhanden ist, wird die Sitzung wiederverwendet. Wenn keine laufende Sitzung mit der ID vorhanden ist, wird automatisch eine neue Sitzung erstellt.

Weitere Informationen zu Sitzungs-IDs finden Sie unter Sitzungsübersicht.

Authentifizierung

Die Authentifizierung erfolgt mithilfe von Microsoft Entra ID-Token (früher Azure Active Directory). Gültige Microsoft Entra-Token werden durch eine Identität generiert, die zu den Rollen Azure ContainerApps Session Executor und Mitwirkender im Sitzungspool gehört.

Wenn Sie eine LLM-Frameworkintegration verwenden, verarbeitet das Framework die Tokengenerierung und -verwaltung für Sie. Stellen Sie sicher, dass die Anwendung mit einer verwalteten Identität mit den erforderlichen Rollenzuweisungen im Sitzungspool konfiguriert ist.

Wenn Sie die API-Verwaltungsendpunkte des Pools direkt verwenden, müssen Sie ein Token generieren und in den Authorization-Header Ihrer HTTP-Anforderungen einschließen. Zusätzlich zu den zuvor erwähnten Rollenzuweisungen muss das Token einen Zielgruppenanspruch (aud) mit dem Wert https://dynamicsessions.io enthalten.

Weitere Informationen finden Sie unter Authentifizierung.

LLM-Frameworkintegrationen

Anstatt die Sitzungspoolverwaltungs-API direkt zu verwenden, bieten die folgenden LLM-Frameworks Integrationen mit Codeinterpretersitzungen:

Framework	Paket	Tutorial
LangChain	Python: `langchain-azure-dynamic-sessions`	Tutorial
LlamaIndex	Python: `llama-index-tools-azure-code-interpreter`	Tutorial
Semantischer Kernel	Python: `semantic-kernel` (Version 0.9.8-b1 oder höher)	Tutorial

API-Verwaltungsendpunkte

Wenn Sie keine LLM-Framework-Integration verwenden, können Sie mithilfe der API-Verwaltungsendpunkte direkt mit dem Sitzungspool interagieren.

Die folgenden Endpunkte stehen für die Verwaltung von Sitzungen in einem Pool zur Verfügung:

Endpunktpfad	Methode	Beschreibung
`code/execute`	`POST`	Ausführen von Code in einer Sitzung.
`files/upload`	`POST`	Hochladen einer Datei in eine Sitzung.
`files/content/{filename}`	`GET`	Herunterladen einer Datei aus einer Sitzung.
`files`	`GET`	Auflisten der Dateien in einer Sitzung.

Erstellen Sie die vollständige URL für jeden Endpunkt, indem Sie den API-Verwaltungsendpunkt des Pools mit dem Endpunktpfad verketten. Die Abfragezeichenfolge muss einen identifier-Parameter mit der Sitzungs-ID und einen api-version-Parameter mit dem Wert 2024-02-02-preview enthalten.

Beispiel: https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/code/execute?api-version=2024-02-02-preview&identifier=<IDENTIFIER>

Ausführen von Code in einer Sitzung

Um Code in einer Sitzung auszuführen, senden Sie eine POST-Anforderung an den code/execute-Endpunkt. Der auszuführende Code muss im Anforderungstext enthalten sein. In diesem Beispiel wird „Hello, world!“ in Python ausgegeben.

Ersetzen Sie vor dem Senden der Anforderung die Platzhalter zwischen den Klammern (<>) durch die entsprechenden Werte für Ihren Sitzungspool und die Sitzungs-ID.

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/code/execute?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Content-Type: application/json
Authorization: Bearer <token>

{
    "properties": {
        "codeInputType": "inline",
        "executionType": "synchronous",
        "code": "print('Hello, world!')"
    }
}

Wenn Sie eine Sitzung wiederverwenden möchten, geben Sie dieselbe Sitzungs-ID in nachfolgenden Anforderungen an.

Hochladen einer Datei in eine Sitzung

Um eine Datei in eine Sitzung hochzuladen, senden Sie eine POST-Anforderung an den uploadFile-Endpunkt in einer „multipart form data“-Anforderung. Fügen Sie die Dateidaten in den Anforderungstext ein. Die Datei muss einen Dateinamen enthalten.

Hochgeladene Dateien werden im Dateisystem der Sitzung unter dem Verzeichnis /mnt/data gespeichert.

Ersetzen Sie vor dem Senden der Anforderung die Platzhalter zwischen den Klammern (<>) durch Werte, die für Ihre Anforderung spezifisch sind.

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/upload?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Authorization: Bearer <token>

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="<FILE_NAME_AND_EXTENSION>"
Content-Type: application/octet-stream

(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Herunterladen einer Datei aus einer Sitzung

Um eine Datei aus dem /mnt/data-Verzeichnis einer Sitzung herunterzuladen, senden Sie eine GET-Anforderung an den file/content/{filename}-Endpunkt. Die Antwort enthält die Dateidaten.

Ersetzen Sie vor dem Senden der Anforderung die Platzhalter zwischen den Klammern (<>) durch Werte, die für Ihre Anforderung spezifisch sind.

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/content/<FILE_NAME_AND_EXTENSION>?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

Auflisten der Dateien in einer Sitzung

Um die Dateien im /mnt/data-Verzeichnis einer Sitzung aufzulisten, senden Sie eine GET-Anforderung an den files-Endpunkt.

Ersetzen Sie vor dem Senden der Anforderung die Platzhalter zwischen den Klammern (<>) durch Werte, die für Ihre Anforderung spezifisch sind.

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

Die Antwort enthält eine Liste der Dateien in der Sitzung.

Die folgende Auflistung zeigt ein Beispiel für den Typ der Antwort, die Sie beim Anfordern von Sitzungsinhalten erwarten können.

{
    "$id": "1",
    "value": [
        {
            "$id": "2",
            "properties": {
                "$id": "3",
                "filename": "test1.txt",
                "size": 16,
                "lastModifiedTime": "2024-05-02T07:21:07.9922617Z"
            }
        },
        {
            "$id": "4",
            "properties": {
                "$id": "5",
                "filename": "test2.txt",
                "size": 17,
                "lastModifiedTime": "2024-05-02T07:21:08.8802793Z"
            }
        }
    ]
}

Vorinstallierte Pakete

Python-Codeinterpretersitzungen umfassen beliebte Python-Pakete wie NumPy, Pandas und Scikit-Learn.

Rufen Sie zum Ausgeben der Liste der vorinstallierten Pakete den code/execute-Endpunkt mit dem folgenden Code auf.

Ersetzen Sie vor dem Senden der Anforderung die Platzhalter zwischen den Klammern (<>) durch Werte, die für Ihre Anforderung spezifisch sind.

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/identifier/<SESSION_ID>/code/execute?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Content-Type: application/json
Authorization: Bearer <TOKEN>

{
    "properties": {
        "codeInputType": "inline",
        "executionType": "synchronous",
        "code": "import pkg_resources\n[(d.project_name, d.version) for d in pkg_resources.working_set]"
    }
}

Logging

Codedolmetschersitzungen unterstützen die Protokollierung nicht direkt. Ihre Anwendung, die mit den Sitzungen interagiert, kann Anforderungen an die Sitzungspoolverwaltungs-API und deren Antworten protokollieren.

Abrechnung

Codedolmetschersitzungen werden basierend auf der Dauer jeder Sitzung abgerechnet. Weitere Informationen finden Sie unter Abrechnung.

Nächste Schritte

Schnellstart: Verwenden von Codeinterpretersitzungen mit LangChain

Freigeben über

Serverlose Code-Interpreter-Sitzungen in Azure Container Apps

Anwendungsfälle für Codeinterpretersitzungen

Codeinterpreter-Sitzungspool

Erstellen eines Sitzungspools mithilfe der Azure-Befehlszeilenschnittstelle

Abrufen des API-Endpunkts für die Poolverwaltung mit der Azure CLI

Codeausführung in einer Sitzung

Sitzungs-IDs

Authentifizierung

LLM-Frameworkintegrationen

API-Verwaltungsendpunkte

Ausführen von Code in einer Sitzung

Hochladen einer Datei in eine Sitzung

Herunterladen einer Datei aus einer Sitzung

Auflisten der Dateien in einer Sitzung

Vorinstallierte Pakete

Logging

Abrechnung

Nächste Schritte

Feedback

Zusätzliche Ressourcen