Serverlösa kodtolksessioner i Azure Container Apps

Artikel
10/24/2024

Dynamiska sessioner i Azure Container Apps ger snabb och skalbar åtkomst till en kodtolkare. Varje kodtolkarsession är helt isolerad av en Hyper-V-gräns och är utformad för att köra kod som inte är betrodd.

Används för kodtolkarsessioner

Kodtolkarsessioner är idealiska för scenarier där du behöver köra kod som är potentiellt skadlig eller kan orsaka skada för värdsystemet eller andra användare, till exempel:

Kod som genereras av en stor språkmodell (LLM).
Kod som skickas av en slutanvändare i ett webb- eller SaaS-program.

För populära LLM-ramverk som LangChain, LlamaIndex eller Semantic Kernel kan du använda verktyg och plugin-program för att integrera AI-appar med kodtolksessioner.

Dina program kan också integreras med kodtolkarsessionen med hjälp av ett REST-API. Med API:et kan du köra kod i en session och hämta resultat. Du kan också ladda upp och ladda ned filer till och från sessionen. Du kan ladda upp och ladda ned körbara kodfiler eller datafiler som koden kan bearbeta.

De inbyggda kodtolkarsessionerna stöder de vanligaste scenarierna för kodkörning utan att behöva hantera infrastruktur eller containrar. Om du behöver fullständig kontroll över kodkörningsmiljön eller har ett annat scenario som kräver isolerade sandbox-miljöer kan du använda anpassade kodtolkarsessioner.

Sessionspool för kodtolkar

Om du vill använda kodtolkarsessioner behöver du en Azure-resurs som kallas en sessionspool som definierar konfigurationen för kodtolkarsessioner. I sessionspoolen kan du ange inställningar som maximalt antal samtidiga sessioner och hur länge en session kan vara inaktiv innan sessionen avslutas.

Du kan skapa en sessionspool med hjälp av mallarna Azure Portal, Azure CLI eller Azure Resource Manager. När du har skapat en sessionspool kan du använda poolens API-slutpunkter för hantering för att hantera och köra kod i en session.

Skapa en sessionspool med Azure CLI

Om du vill skapa en kodtolksessionspool med hjälp av Azure CLI kontrollerar du att du har de senaste versionerna av Azure CLI och Azure Container Apps-tillägget med följande kommandon:

# Upgrade the Azure CLI
az upgrade

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

az containerapps sessionpool create Använd kommandot för att skapa poolen. I följande exempel skapas en Python-kodtolkarsessionspool med namnet my-session-pool. Ersätt <RESOURCE_GROUP> med resursgruppens namn innan du kör kommandot.

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

Du kan definiera följande inställningar när du skapar en sessionspool:

Inställning	beskrivning
`--container-type`	Vilken typ av kodtolkare som ska användas. Det enda värde som stöds är `PythonLTS`.
`--max-sessions`	Det maximala antalet tilldelade sessioner som tillåts samtidigt. Maxvärdet är `600`.
`--cooldown-period`	Antalet tillåtna inaktiva sekunder före avslutning. Inaktivitetsperioden återställs varje gång sessionens API anropas. Det tillåtna intervallet är mellan `300` och `3600`.
`--network-status`	Anger om utgående nätverkstrafik tillåts från sessionen. Giltiga värden är `EgressDisabled` (standard) och `EgressEnabled`.

Viktigt!

Om du aktiverar utgående trafik kan kod som körs i sessionen komma åt Internet. Var försiktig när koden inte är betrodd eftersom den kan användas för att utföra skadliga aktiviteter, till exempel överbelastningsattacker.

Hämta API-slutpunkten för poolhantering med Azure CLI

Om du vill använda kodtolkarsessioner med LLM-ramverksintegreringar eller genom att anropa hanterings-API-slutpunkterna direkt behöver du poolens API-slutpunkt för hantering. Slutpunkten är i formatet https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>.

Använd kommandot för att hämta hanterings-API-slutpunkten för en sessionspool az containerapps sessionpool show . Ersätt <RESOURCE_GROUP> med resursgruppens namn innan du kör kommandot.

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

Kodkörning i en session

När du har skapat en sessionspool kan ditt program interagera med sessioner i poolen med hjälp av en integrering med ett LLM-ramverk eller med hjälp av poolens hanterings-API-slutpunkter direkt.

Sessionsidentifierare

Viktigt!

Sessionsidentifieraren är känslig information som kräver att du använder en säker process för att hantera dess värde. En del av den här processen kräver att programmet ser till att varje användare eller klient endast har åtkomst till sina egna sessioner. Om du inte kan skydda åtkomsten till sessioner kan det leda till missbruk eller obehörig åtkomst till data som lagras i användarnas sessioner. Mer information finns i Sessionsidentifierare

När du interagerar med sessioner i en pool använder du en sessionsidentifierare för att referera till varje session En sessionsidentifierare är en sträng som du definierar som är unik i sessionspoolen. Om du skapar ett webbprogram kan du använda användarens ID. Om du skapar en chattrobot kan du använda konversations-ID:t.

Om det finns en session som körs med identifieraren återanvänds sessionen. Om det inte finns någon session som körs med identifieraren skapas en ny session automatiskt.

Mer information om sessionsidentifierare finns i Översikt över sessioner.

Autentisering

Autentisering hanteras med hjälp av Microsoft Entra-token (tidigare Azure Active Directory). Giltiga Microsoft Entra-token genereras av en identitet som tillhör Azure ContainerApps sessionskörnings- och deltagarroller i sessionspoolen.

Om du använder en LLM-ramverksintegrering hanterar ramverket tokengenereringen och hanteringen åt dig. Kontrollera att programmet har konfigurerats med en hanterad identitet med nödvändiga rolltilldelningar i sessionspoolen.

Om du använder poolens API-slutpunkter för hantering direkt måste du generera en token och inkludera den Authorization i rubriken för dina HTTP-begäranden. Utöver de rolltilldelningar som tidigare nämnts måste token innehålla ett målgruppsanspråk (aud) med värdet https://dynamicsessions.io.

Mer information finns i Autentisering.

LLM-ramverksintegreringar

I stället för att använda API:et för hantering av sessionspooler direkt tillhandahåller följande LLM-ramverk integreringar med kodtolkarsessioner:

Ramverk	Paket	Självstudie
LangChain	Python: `langchain-azure-dynamic-sessions`	Handledning
LlamaIndex	Python: `llama-index-tools-azure-code-interpreter`	Handledning
Semantic Kernel	Python: `semantic-kernel` (version 0.9.8-b1 eller senare)	Handledning

Hanterings-API-slutpunkter

Om du inte använder en LLM-ramverksintegrering kan du interagera med sessionspoolen direkt med hjälp av hanterings-API-slutpunkterna.

Följande slutpunkter är tillgängliga för att hantera sessioner i en pool:

Slutpunktssökväg	Metod	beskrivning
`code/execute`	`POST`	Kör kod i en session.
`files/upload`	`POST`	Ladda upp en fil till en session.
`files/content/{filename}`	`GET`	Ladda ned en fil från en session.
`files`	`GET`	Visa en lista över filerna i en session.

Skapa den fullständiga URL:en för varje slutpunkt genom att sammanfoga poolens API-slutpunkt för hantering med slutpunktssökvägen. Frågesträngen måste innehålla en identifier parameter som innehåller sessionsidentifieraren och en api-version parameter med värdet 2024-02-02-preview.

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

Köra kod i en session

Om du vill köra kod i en session skickar du en POST begäran till code/execute slutpunkten med koden som ska köras i begärandetexten. I det här exemplet skrivs "Hello, world!" ut i Python.

Innan du skickar begäran ersätter du platshållarna mellan <> hakparenteserna med lämpliga värden för sessionspoolen och sessionsidentifieraren.

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!')"
    }
}

Om du vill återanvända en session anger du samma sessionsidentifierare i efterföljande begäranden.

Ladda upp en fil till en session

Om du vill ladda upp en fil till en session skickar du en POST begäran till uploadFile slutpunkten i en databegäran i flera delar. Inkludera fildata i begärandetexten. Filen måste innehålla ett filnamn.

Uppladdade filer lagras i sessionens filsystem under /mnt/data katalogen.

Innan du skickar begäran ersätter du platshållarna mellan <> hakparenteserna med värden som är specifika för din begäran.

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--

Ladda ned en fil från en session

Om du vill ladda ned en fil från en sessions /mnt/data katalog skickar du en GET begäran till file/content/{filename} slutpunkten. Svaret innehåller fildata.

Innan du skickar begäran ersätter du platshållarna mellan <> hakparenteserna med värden som är specifika för din begäran.

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>

Visa en lista över filerna i en session

Om du vill visa en lista över filerna i en sessions /mnt/data katalog skickar du en GET begäran till files slutpunkten.

Innan du skickar begäran ersätter du platshållarna mellan <> hakparenteserna med värden som är specifika för din begäran.

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>

Svaret innehåller en lista över filer i sessionen.

I följande lista visas ett exempel på vilken typ av svar du kan förvänta dig av att begära sessionsinnehåll.

{
    "$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"
            }
        }
    ]
}

Förinstallerade paket

Python-kodtolksessioner innehåller populära Python-paket som NumPy, Pandas och scikit-learn.

Om du vill mata ut listan över förinstallerade paket anropar du code/execute slutpunkten med följande kod.

Innan du skickar begäran ersätter du platshållarna mellan <> hakparenteserna med värden som är specifika för din begäran.

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]"
    }
}

Loggning

Kodtolkarsessioner stöder inte loggning direkt. Ditt program som interagerar med sessionerna kan logga begäranden till API:et för hantering av sessionspooler och dess svar.

Fakturering

Kodtolkarsessioner faktureras baserat på varaktigheten för varje session. Mer information finns i Fakturering .

Nästa steg

Snabbstart: Använda kodtolksessioner med LangChain

Dela via

Serverlösa kodtolksessioner i Azure Container Apps

Används för kodtolkarsessioner

Sessionspool för kodtolkar

Skapa en sessionspool med Azure CLI

Hämta API-slutpunkten för poolhantering med Azure CLI

Kodkörning i en session

Sessionsidentifierare

Autentisering

LLM-ramverksintegreringar

Hanterings-API-slutpunkter

Köra kod i en session

Ladda upp en fil till en session

Ladda ned en fil från en session

Visa en lista över filerna i en session

Förinstallerade paket

Loggning

Fakturering

Nästa steg

Feedback

Ytterligare resurser