Sessões de interpretador de código sem servidor em Aplicativos de Contêiner do Azure
As sessões dinâmicas dos Aplicativos de Contêiner do Azure fornecem acesso rápido e escalável a um interpretador de código. Cada sessão do interpretador de código é totalmente isolada por um limite do Hyper-V e foi projetada para executar código não confiável.
Usos 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 código potencialmente mal-intencionado ou que pode causar danos ao sistema host ou a outros usuários, como:
- Código gerado por um modelo de linguagem grande (LLM).
- Código enviado por um usuário final em um aplicativo web ou SaaS.
Para estruturas LLM populares, como LangChain, LlamaIndex ou Semantic Kernel, você pode usar ferramentas e plugins para integrar aplicativos de IA com sessões de interpretador de código.
Seus aplicativos também podem se integrar com a sessão do interpretador de código usando uma API REST. A API permite que você execute código em uma sessão e recupere resultados. Também pode carregar e descarregar ficheiros 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 internas do interpretador de código suportam os cenários de execução de código mais comuns sem a necessidade de gerenciar infraestrutura ou 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 personalizadas de interpretador de código.
Pool de sessões 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ões que define 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 que a sessão seja 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 código dentro de uma sessão.
Criar um pool de sessões com a CLI do Azure
Para criar um pool de sessões do interpretador de código usando a CLI do Azure, verifique se você tem as versões mais recentes da CLI do Azure e da 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 az containerapps sessionpool create comando para criar o pool. O exemplo a seguir cria um pool de sessões do interpretador de código Python chamado my-session-pool. Certifique-se de substituir <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:
| Definição | Descrição |
|---|---|
--container-type |
O tipo de interpretador de código a ser usado. O único valor suportado é 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 da rescisão. O período ocioso é redefinido cada vez 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 a partir da 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 maliciosas, 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 de estrutura LLM ou chamando os pontos de extremidade da API de gerenciamento diretamente, 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ões, use o az containerapps sessionpool show comando. Certifique-se de substituir <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 diretamente os pontos de extremidade da API de gerenciamento do pool.
Identificadores de sessão
Importante
O identificador de sessão é uma informação confidencial que requer 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 às suas próprias sessões. A falha em proteger o acesso às sessões pode resultar em uso indevido ou acesso não autorizado aos dados armazenados nas sessões dos usuários. Para obter mais informações, consulte Identificadores de sessão
Ao interagir com sessões em um pool, você usa um identificador de sessão para fazer referência a cada sessão Um identificador de sessão é uma cadeia de caracteres que você define que é exclusiva dentro do pool de sessões. Se estiver a criar uma aplicação Web, pode utilizar o ID do utilizador. Se você estiver criando um chatbot, poderá usar o ID da conversa.
Se houver uma sessão em execução com o identificador, a sessão será reutilizada. Se não houver uma 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 usando tokens do Microsoft Entra (anteriormente Azure Ative Directory). Os tokens válidos do Microsoft Entra são gerados por uma identidade pertencente às funções Executor de Sessão e Colaborador do Azure ContainerApps no pool de sessões.
Se você estiver usando uma integração de estrutura LLM, a estrutura lida com 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ões.
Se você estiver usando os pontos de extremidade da API de gerenciamento do pool diretamente, deverá gerar um token e incluí-lo no Authorization cabeçalho 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, consulte Autenticação.
Integrações de framework LLM
Em vez de usar a API de gerenciamento do pool de sessões diretamente, as seguintes estruturas LLM fornecem integrações com sessões de interpretador de código:
| Estrutura | Pacote | Tutorial |
|---|---|---|
| LangChain | Python: langchain-azure-dynamic-sessions |
Tutoriais |
| LlamaIndex | Python: llama-index-tools-azure-code-interpreter |
Tutoriais |
| Kernel Semântico | Python: semantic-kernel (versão 0.9.8-b1 ou posterior) |
Tutoriais |
Pontos de extremidade da API de gerenciamento
Se você não estiver usando uma integração de estrutura LLM, poderá interagir com o pool de sessões 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 | Description |
|---|---|---|
code/execute |
POST |
Execute código em uma sessão. |
files/upload |
POST |
Carregue um ficheiro para 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 identifier parâmetro contendo o identificador de sessão e um api-version parâmetro 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 código em uma sessão, envie uma POST solicitação para o code/execute ponto de extremidade com o código a ser executado no corpo da solicitação. Este exemplo imprime "Hello, world!" em Python.
Antes de enviar a solicitação, substitua os espaços reservados entre <> os colchetes pelos valores apropriados para o pool de sessões 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 em solicitações subsequentes.
Carregar um ficheiro para uma sessão
Para carregar um arquivo para uma sessão, envie uma POST solicitação para o uploadFile ponto de extremidade em uma solicitação de dados de formulário com 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 sob o /mnt/data diretório.
Antes de enviar a solicitação, substitua os espaços reservados entre <> colchetes por valores específicos para 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 de uma sessão /mnt/data , envie uma GET solicitação para o file/content/{filename} ponto de extremidade. A resposta inclui os dados do arquivo.
Antes de enviar a solicitação, substitua os espaços reservados entre <> colchetes por valores específicos para 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 uma sessão, envie uma GET solicitação para o files ponto de /mnt/data extremidade.
Antes de enviar a solicitação, substitua os espaços reservados entre <> colchetes por valores específicos para 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 Python populares como NumPy, pandas e scikit-learn.
Para gerar a lista de pacotes pré-instalados, chame o code/execute ponto de extremidade com o código a seguir.
Antes de enviar a solicitação, substitua os espaços reservados entre <> colchetes por valores específicos para 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]"
}
}
Registo
As sessões do interpretador de código não suportam o registro em log diretamente. Seu aplicativo que está interagindo com as sessões pode registrar solicitações na API de gerenciamento do pool de sessões e suas respostas.
Faturação
As sessões do intérprete de código são cobradas com base na duração de cada sessão. Consulte Faturação para obter mais informações.