Sessões de interpretador de código sem servidor nos Aplicativos de Contêiner do Azure (versão prévia)

Artigo
07/26/2024

As sessões dinâmicas dos Aplicativos de Contêiner do Azure fornecem acesso rápido e escalonável a um interpretador de código. Cada sessão de interpretador de código é totalmente isolada por um limite do Hyper-V e foi projetada para executar código não confiável.

Observação

O recurso de sessões dinâmicas dos Aplicativos de Contêiner do Azure está atualmente em versão prévia. Confira as limitações de visualização para obter mais informações.

Usa para sessões de interpretador de código

As sessões de interpretador de código são ideais para cenários em que você precisa executar um código potencialmente mal-intencionado ou que possa causar danos ao sistema host ou a outros usuários, como:

Código gerado por um LLM (modelo de linguagem grande).
Código enviado por um usuário final em um aplicativo Web ou SaaS.

Para estruturas LLM populares, como LangChain, LlamaIndex ou Kernel Semântico, você pode usar ferramentas e plug-ins para integrar aplicativos de IA com sessões de interpretador de código.

Seus aplicativos também podem se integrar à sessão de interpretador de código usando uma API REST. A API permite que você execute o código em uma sessão e recupere os resultados. Você também pode carregar e baixar arquivos de e para a sessão. Você pode carregar e baixar arquivos de código executáveis ou arquivos de dados que seu código pode processar.

As sessões de interpretador de código internas dão suporte aos cenários de execução de código mais comuns sem a necessidade de gerenciar a infraestrutura ou os contêineres. Se você precisar de controle total sobre o ambiente de execução de código ou tiver um cenário diferente que exija áreas restritas isoladas, poderá usar sessões de interpretador de código personalizadas.

Pool de sessão do interpretador de código

Para usar sessões de interpretador de código, você precisa de um recurso do Azure chamado pool de sessão que defina a configuração para sessões de interpretador de código. No pool de sessões, você pode especificar configurações como o número máximo de sessões simultâneas e por quanto tempo uma sessão pode ficar ociosa antes de ser encerrada.

Você pode criar um pool de sessões usando o portal do Azure, a CLI do Azure ou os modelos do Azure Resource Manager. Depois de criar um pool de sessões, você pode usar os pontos de extremidade da API de gerenciamento do pool para gerenciar e executar o código dentro de uma sessão.

Criar um pool de sessões com a CLI do Azure

Para criar um pool de sessão de interpretador de código usando a CLI do Azure, verifique se você tem as versões mais recentes da CLI do Azure e a extensão Aplicativos de Contêiner do Azure com os seguintes comandos:

# Upgrade the Azure CLI
az upgrade

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

Use o comando az containerapps sessionpool create para criar o cliente. O exemplo a seguir cria um pool de sessão de interpretador de código do Python chamado my-session-pool. Substitua <RESOURCE_GROUP> pelo nome do grupo de recursos antes de executar o 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

Você pode definir as seguintes configurações ao criar um pool de sessões:

Configuração	Descrição
`--container-type`	O tipo de interpretador de código a ser usado. O único valor com suporte é `PythonLTS`.
`--max-sessions`	O número máximo de sessões alocadas permitidas simultaneamente. O valor máximo é `600`.
`--cooldown-period`	O número de segundos ociosos permitidos antes do encerramento. O período ocioso é redefinido sempre que a API da sessão é chamada. O intervalo permitido é entre `300` e `3600`.
`--network-status`	Designa se o tráfego de rede de saída é permitido na sessão. Os valores válidos são `EgressDisabled` (padrão) e `EgressEnabled`.

Importante

Se você habilitar a saída, o código em execução na sessão poderá acessar a Internet. Tenha cuidado quando o código não for confiável, pois ele pode ser usado para executar atividades mal-intencionadas, como ataques de negação de serviço.

Obter o ponto de extremidade da API de gerenciamento de pool com a CLI do Azure

Para usar sessões de interpretador de código com integrações da estrutura LLM ou chamando diretamente os pontos de extremidade da API de gerenciamento, você precisa do ponto de extremidade da API de gerenciamento do pool. O ponto de extremidade está no formato https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>.

Para recuperar o ponto de extremidade da API de gerenciamento para um pool de sessão, use o comando az containerapps sessionpool show. Substitua <RESOURCE_GROUP> pelo nome do grupo de recursos antes de executar o comando.

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

Execução de código em uma sessão

Depois de criar um pool de sessões, seu aplicativo pode interagir com sessões no pool usando uma integração com uma estrutura LLM ou usando os pontos de extremidade da API de gerenciamento do pool diretamente.

Identificadores de sessão

Importante

O identificador de sessão é as informações confidenciais que exigem que você use um processo seguro para gerenciar seu valor. Parte desse processo requer que seu aplicativo garanta que cada usuário ou locatário tenha acesso apenas a suas próprias sessões. A falha na proteção do acesso às sessões pode resultar no uso indevido ou no acesso não autorizado aos dados armazenados nas sessões dos usuários. Para obter mais informações, confira Identificadores de sessão

Ao interagir com sessões em um pool, você usa um identificador de sessão para referenciar cada sessão. Um identificador de sessão é uma cadeia de caracteres que você define como exclusiva dentro do pool de sessões. Se você estiver criando um aplicativo Web, poderá usar a ID do usuário. Se você estiver criando um chatbot, poderá usar a ID da conversa.

Se houver uma sessão em execução com o identificador, a sessão será reutilizada. Se não houver nenhuma sessão em execução com o identificador, uma nova sessão será criada automaticamente.

Para saber mais sobre identificadores de sessão, consulte Visão geral das sessões.

Autenticação

A autenticação é tratada por meio de tokens do Microsoft Entra ID (antigo Azure Active Directory) Tokens válidos do Microsoft Entra são gerados por uma identidade que pertence às funções Executor de Sessão dos Aplicativos de Contêiner do Azure e Colaborador no pool de sessão.

Se você estiver usando uma integração de estrutura LLM, a estrutura manipulará a geração e o gerenciamento de tokens para você. Verifique se o aplicativo está configurado com uma identidade gerenciada com as atribuições de função necessárias no pool de sessão.

Se você estiver usando diretamente os pontos de extremidade da API de gerenciamento do pool, deverá gerar um token e incluí-lo no cabeçalho Authorization de suas solicitações HTTP. Além das atribuições de função mencionadas anteriormente, o token precisa conter uma declaração de audiência (aud) com o valor https://dynamicsessions.io.

Para saber mais, confira Autenticação.

Integrações da estrutura LLM

Em vez de usar diretamente a API de gerenciamento do pool de sessão, as seguintes estruturas LLM fornecem integrações com sessões de interpretador de código:

Estrutura	Pacote	Tutorial
LangChain	Python: `langchain-azure-dynamic-sessions`	Tutorial
LlamaIndex	Python: `llama-index-tools-azure-code-interpreter`	Tutorial
Semantic Kernel	Python: `semantic-kernel` (versão 0.9.8-b1 ou posterior)	Tutorial

Pontos de extremidade da API de gerenciamento

Se você não estiver usando uma integração da estrutura LLM, poderá interagir com o pool de sessão diretamente usando os pontos de extremidade da API de gerenciamento.

Os seguintes pontos de extremidade estão disponíveis para gerenciar sessões em um pool:

Caminho do ponto de extremidade	Método	Descrição
`code/execute`	`POST`	Execute o código em uma sessão.
`files/upload`	`POST`	Carregue um arquivo em uma sessão.
`files/content/{filename}`	`GET`	Baixe um arquivo de uma sessão.
`files`	`GET`	Liste os arquivos em uma sessão.

Crie a URL completa para cada ponto de extremidade concatenando o ponto de extremidade da API de gerenciamento do pool com o caminho do ponto de extremidade. A cadeia de caracteres de consulta deve incluir um parâmetro identifier que contém o identificador de sessão e um parâmetro api-version com o valor 2024-02-02-preview.

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

Executar código em uma sessão

Para executar o código em uma sessão, envie uma solicitação POST para o ponto de extremidade code/execute com o código a ser executado no corpo da solicitação. Este exemplo imprime "Olá, mundo!" no Python.

Antes de enviar a solicitação, substitua os espaços reservados entre os colchetes <> pelos valores apropriados para o pool de sessão e o identificador de sessão.

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

Para reutilizar uma sessão, especifique o mesmo identificador de sessão nas solicitações subsequentes.

Carregar um arquivo em uma sessão

Para carregar um arquivo em uma sessão, envie uma solicitação POST para o ponto de extremidade uploadFile em uma solicitação de dados de formulário de várias partes. Inclua os dados do arquivo no corpo da solicitação. O arquivo deve incluir um nome de arquivo.

Os arquivos carregados são armazenados no sistema de arquivos da sessão no diretório /mnt/data.

Antes de enviar a solicitação, substitua os espaços reservados entre os colchetes <> por valores específicos à sua solicitação.

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

Baixar um arquivo de uma sessão

Para baixar um arquivo do diretório /mnt/data de uma sessão, envie uma solicitação GET para o ponto de extremidade file/content/{filename}. A resposta inclui os dados do arquivo.

Antes de enviar a solicitação, substitua os espaços reservados entre os colchetes <> por valores específicos à sua solicitação.

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>

Listar os arquivos em uma sessão

Para listar os arquivos no diretório de /mnt/data uma sessão, envie uma solicitação GET para o ponto de extremidade files.

Antes de enviar a solicitação, substitua os espaços reservados entre os colchetes <> por valores específicos à sua solicitação.

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>

A resposta contém uma lista de arquivos na sessão.

A listagem a seguir mostra um exemplo do tipo de resposta que você pode esperar da solicitação de conteúdo da sessão.

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

Pacotes pré-instalados

As sessões de interpretador de código Python incluem pacotes populares do Python, como NumPy, pandas e scikit-learn.

Para gerar a lista de pacotes pré-instalados, chame o ponto de extremidade code/execute com o código a seguir.

Antes de enviar a solicitação, substitua os espaços reservados entre os colchetes <> por valores específicos à sua solicitação.

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

Próximas etapas

Início Rápido: usar sessões de interpretador de código com LangChain

Compartilhar via

Sessões de interpretador de código sem servidor nos Aplicativos de Contêiner do Azure (versão prévia)

Usa para sessões de interpretador de código

Pool de sessão do interpretador de código

Criar um pool de sessões com a CLI do Azure

Obter o ponto de extremidade da API de gerenciamento de pool com a CLI do Azure

Execução de código em uma sessão

Identificadores de sessão

Autenticação

Integrações da estrutura LLM

Pontos de extremidade da API de gerenciamento

Executar código em uma sessão

Carregar um arquivo em uma sessão

Baixar um arquivo de uma sessão

Listar os arquivos em uma sessão

Pacotes pré-instalados

Próximas etapas

Comentários

Recursos adicionais