Compartilhar via

Sessões de interpretação 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 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.

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

  • Executar código em uma sessão e recuperar resultados

  • Carregue e baixe 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.

Para obter mais informações sobre como criar e configurar um pool de sessões, consulte Usar pools de sessão.

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 é uma informação sensível que exige o uso de um processo seguro para gerenciar seu valor. Parte desse processo exige que seu aplicativo garanta que cada usuário ou locatário tenha acesso apenas às suas próprias sessões.

A falha na proteção do 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 referenciar cada sessão Um identificador de sessão é uma cadeia de caracteres que você define que é 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.

Autenticação

A autenticação é tratada usando tokens do Microsoft Entra. 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, consulte a autenticação e autorização .

Trabalhar com arquivos

Você pode carregar e baixar arquivos e listar todos os arquivos em uma sessão de interpretador de código.

Caracteres com suporte

Nomes de arquivo e caminho devem usar apenas os seguintes caracteres com suporte:

  • Letras maiúsculas e minúsculas: A-Z, a-z
  • Dígitos: 0-9
  • Caracteres especiais: -, _, , ., @, $, &, =, ;, ,, #, %, ^, (, )
  • Caracteres Unicode: inclui caracteres chineses, japoneses e outros internacionais
  • O caminho não permite: .

Fazer upload de um arquivo

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.

O exemplo a seguir mostra como carregar um arquivo em uma sessão.

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

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.

O exemplo a seguir demonstra como formatar uma solicitação GET para baixar um 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

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

O exemplo a seguir mostra como listar os arquivos no diretório de uma sessão.

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

Segurança

As sessões de interpretador de código são projetadas para executar código não confiável em ambientes isolados, garantindo que seus aplicativos e dados permaneçam protegidos.

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:

Framework Pacote Tutorial
LangChain Python: langchain-azure-dynamic-sessions Tutorial
LlamaIndex Python: llama-index-tools-azure-code-interpreter Tutorial
Núcleo Semântico 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 de framework LLM, poderá interagir diretamente com o pool de sessões usando os endpoints da API de gerenciamento.

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.

O exemplo a seguir imprime Hello, world! em Python.

Antes de enviar a solicitação, substitua os espaços reservados entre os colchetes <> pelos valores apropriados do pool de sessão e do 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--

Observação

O limite de upload de arquivo é 128MB. Se isso for excedido, um erro HTTP 413 poderá ser retornado.

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

Registro em log

As sessões do interpretador de código não suportam registro de logs diretamente. Seu aplicativo que interage com as sessões pode registrar solicitações para a API de gerenciamento do pool de sessões e suas respectivas respostas.

Cobrança

As sessões de interpretação de código são cobradas com base na duração de cada sessão. Para obter mais informações, confira Cobrança.

Próximas etapas

Usar sessões de interpretador de código com LangChain

  • Last updated on