Sessioni dell'interprete di codice serverless nelle app Azure Container

Le sessioni dinamiche di App contenitore di Azure offrono accesso rapido e scalabile a un interprete di codice. Ogni sessione dell'interprete di codice è completamente isolata da un limite Hyper-V ed è progettata per eseguire codice non attendibile.

Usi per le sessioni dell'interprete di codice

Le sessioni dell'interprete di codice sono ideali per scenari in cui è necessario eseguire codice potenzialmente dannoso o che potrebbe causare danni al sistema host o ad altri utenti, ad esempio:

• Codice generato da un modello linguistico di grandi dimensioni (LLM).
• Codice inviato da un utente finale in un'applicazione Web o SaaS.

Per i framework LLM più diffusi, ad esempio LangChain, LlamaIndex o Semantic Kernel, è possibile usare strumenti e plug-in per integrare le app di intelligenza artificiale con sessioni di interprete del codice.

Le applicazioni possono anche integrarsi con la sessione dell'interprete del codice usando un'API REST. L'API consente di eseguire codice in una sessione e recuperare i risultati. È anche possibile caricare e scaricare file da e verso la sessione. È possibile caricare e scaricare file di codice eseguibile o file di dati che il codice può elaborare.

Le sessioni di interprete di codice predefinite supportano gli scenari di esecuzione del codice più comuni senza la necessità di gestire l'infrastruttura o i contenitori. Se è necessario il controllo completo sull'ambiente di esecuzione del codice o si dispone di uno scenario diverso che richiede sandbox isolate, è possibile usare sessioni di interprete del codice personalizzate.

Pool di sessioni dell'interprete di codice

Per usare le sessioni dell'interprete del codice, è necessaria una risorsa di Azure denominata pool di sessioni che definisce la configurazione per le sessioni dell'interprete del codice. Nel pool di sessioni è possibile specificare impostazioni quali il numero massimo di sessioni simultanee e il tempo di inattività di una sessione prima che la sessione venga terminata.

È possibile creare un pool di sessioni usando il portale di Azure, l'interfaccia della riga di comando di Azure o i modelli di Azure Resource Manager. Dopo aver creato un pool di sessioni, è possibile usare gli endpoint API di gestione del pool per gestire ed eseguire il codice all'interno di una sessione.

Creare un pool di sessioni con l'interfaccia della riga di comando di Azure

Per creare un pool di sessioni di interprete di codice personalizzato usando l'interfaccia della riga di comando di Azure, assicurarsi di disporre delle versioni più recenti dell'interfaccia della riga di comando di Azure e dell'estensione App contenitore di Azure con i comandi seguenti:

# Upgrade the Azure CLI
az upgrade

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

Usare il comando az containerapps sessionpool create per creare il pool. L'esempio seguente crea un pool di sessioni dell'interprete del codice Python denominato my-session-pool. Assicurarsi di sostituire <RESOURCE_GROUP> con il nome del gruppo di risorse prima di eseguire il comando.

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

Quando si crea un pool di sessioni, è possibile definire le impostazioni seguenti:

Ottenere l'endpoint dell'API di gestione del pool con l'interfaccia della riga di comando di Azure

Per usare le sessioni dell'interprete del codice con integrazioni del framework LLM o chiamando direttamente gli endpoint dell'API di gestione, è necessario l'endpoint dell'API di gestione del pool. L'endpoint è nel formato https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>.

Per recuperare l'endpoint dell'API di gestione per un pool di sessioni, usare il comando az containerapps sessionpool show. Assicurarsi di sostituire <RESOURCE_GROUP> con il nome del gruppo di risorse prima di eseguire il comando.

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

Esecuzione del codice in una sessione

Dopo aver creato un pool di sessioni, l'applicazione può interagire con le sessioni nel pool usando un'integrazione con un framework LLM o usando direttamente gli endpoint API di gestione del pool.

Identificatori di sessione

Quando si interagisce con le sessioni in un pool, si usa un identificatore di sessione per fare riferimento a ogni sessione. Un identificatore di sessione è una stringa definita dall'utente univoca all'interno del pool di sessioni. Se si sta creando un'applicazione Web, è possibile usare l'ID dell'utente. Se si sta creando un chatbot, è possibile usare l'ID conversazione.

Se è presente una sessione in esecuzione con l'identificatore, la sessione viene riutilizzata. Se non è presente alcuna sessione in esecuzione con l'identificatore, viene creata automaticamente una nuova sessione.

Per altre informazioni sugli identificatori di sessione, vedere Panoramica sulla sessione.

Autenticazione

L'autenticazione viene gestita usando i token di Microsoft Entra (in precedenza Azure Active Directory). I token Microsoft Entra validi vengono generati da un'identità appartenente ai ruoli Esecutore di sessioni Azure ContainerApps e Collaboratore nel pool di sessioni.

Se si usa un'integrazione del framework LLM, il framework gestisce automaticamente la generazione e la gestione dei token. Assicurarsi che l'applicazione sia configurata con un'identità gestita con le assegnazioni di ruolo necessarie nel pool di sessioni.

Se si usano direttamente gli endpoint API di gestione del pool, è necessario generare un token e includerlo nell'intestazione Authorization delle richieste HTTP. Oltre alle assegnazioni di ruolo indicate in precedenza, il token deve contenere un'attestazione del gruppo di destinatari (aud) con il valore https://dynamicsessions.io.

Per altre informazioni, vedere Autenticazione.

Integrazioni del framework LLM

Anziché usare direttamente l'API di gestione del pool di sessioni, i framework LLM seguenti forniscono integrazioni con sessioni di interprete del codice:

Endpoint dell'API di gestione

Se non si usa un'integrazione del framework LLM, è possibile interagire con il pool di sessioni direttamente usando gli endpoint dell'API di gestione.

Per la gestione delle sessioni in un pool sono disponibili gli endpoint seguenti:

Compilare l'URL completo per ogni endpoint concatenando l'endpoint dell'API di gestione del pool con il percorso dell'endpoint. La stringa di query deve includere un parametro identifier contenente l'identificatore di sessione e un parametro api-version con il valore 2024-02-02-preview.

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

Eseguire il codice in una sessione

Per eseguire il codice in una sessione, inviare una richiesta POST all'endpoint code/execute con il codice da eseguire nel corpo della richiesta. Questo esempio riporta "Hello, world!" in Python.

Prima di inviare la richiesta, sostituire i segnaposto tra le parentesi <> con i valori appropriati per il pool di sessioni e l'identificatore di sessione.

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

Per riutilizzare una sessione, specificare lo stesso identificatore di sessione nelle richieste successive.

Caricare un file in una sessione

Per caricare un file in una sessione, inviare una richiesta POST all'endpoint uploadFile in una richiesta di dati in formato multipart. Includere i dati del file nel corpo della richiesta. Il file deve includere un nome file.

I file caricati vengono archiviati nel file system della sessione nella directory /mnt/data.

Prima di inviare la richiesta, sostituire i segnaposto tra le parentesi <> con valori specifici della richiesta.

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

Scaricare un file da una sessione

Per scaricare un file dalla directory /mnt/data di una sessione, inviare una richiesta GET all'endpoint file/content/{filename}. La risposta include i dati del file.

Prima di inviare la richiesta, sostituire i segnaposto tra le parentesi <> con valori specifici della richiesta.

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>

Elencare i file in una sessione

Per elencare i file nella directory /mnt/data di una sessione, inviare una richiesta GET all'endpoint files.

Prima di inviare la richiesta, sostituire i segnaposto tra le parentesi <> con valori specifici della richiesta.

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>

La risposta contiene un elenco di file nella sessione.

L'elenco seguente mostra un esempio del tipo di risposta che è possibile prevedere dalla richiesta del contenuto della sessione.

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

Pacchetti preinstallati

Le sessioni dell'interprete di codice Python includono pacchetti Python più diffusi, ad esempio NumPy, pandas e scikit-learn.

Per restituire l'elenco dei pacchetti preinstallati, chiamare l'endpoint code/execute con il codice seguente.

Prima di inviare la richiesta, sostituire i segnaposto tra le parentesi <> con valori specifici della richiesta.

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

Registrazione

Le sessioni dell'interprete del codice non supportano direttamente la registrazione. L'applicazione che interagisce con le sessioni può registrare le richieste all'API di gestione del pool di sessioni e alle relative risposte.

Fatturazione

Le sessioni dell'interprete del codice vengono fatturate in base alla durata di ogni sessione. Per altre informazioni, vedere Fatturazione .

Passaggi successivi