Isolamento de arquivos do interpretador#

A proteção de arquivos do interpretador limita o código Python aos arquivos do Chat atual, aos dados temporários e às bibliotecas necessárias. A configuração é feita por um administrador do servidor com acesso ao Docker e ao diretório de instalação.

Preparação do servidor#

O interpretador protegido requer Linux com Landlock ABI 1 ou posterior habilitado. A política é aplicada antes da execução do código e herdada pelos processos filhos. Se o kernel, a arquitetura ou a política do Docker não oferecerem suporte à restrição, o código Python não será executado.

Nos kernels com Landlock ABI 1 ou 2, a configuração do contêiner também é verificada antes da execução do código. O processo deve ser executado com UID 1000 e todas as capabilities do Linux desabilitadas. O sistema de arquivos raiz do contêiner e o script de inicialização /opt/main.py devem ser montados somente para leitura. Não são permitidas montagens adicionais com acesso de gravação fora da configuração padrão do Docker. A configuração de inicialização do Docker fornecida define essas restrições. Se uma verificação falhar, o código não será executado. Não existe alternativa de execução sem isolamento.

É necessário atualizar em conjunto as imagens aiserver e aiserver-code-interpreter e o arquivo docker-compose.yml do mesmo pacote de distribuição. A imagem mypy deve conter as bibliotecas necessárias. Consulte as instruções de preparação da imagem.

Configuração do token de serviço#

A comunicação do backend com o interpretador requer AI_INTERPRETER_SERVICE_TOKEN com pelo menos 32 caracteres. O instalador e o script de atualização geram um token aleatório em .env, preservam um valor existente e definem as permissões do arquivo como 600. Um valor existente curto demais causa falha na configuração.

Na instalação manual, é necessário gerar um token:

python3 -c 'import secrets; print(secrets.token_hex(32))'

É necessário salvar o resultado como valor de AI_INTERPRETER_SERVICE_TOKEN em .env. Os serviços aiserver e aiserver-code-interpreter devem receber o mesmo valor. Não envie o token para um Chat nem o inclua em logs de diagnóstico.

Após carregar o pacote de imagens correspondente e configurar .env, é necessário recriar os dois serviços durante uma janela de manutenção acordada:

docker compose up -d --no-deps --force-recreate aiserver aiserver-code-interpreter

O backend fica temporariamente indisponível durante a recriação. Reiniciar um contêiner antigo não aplica as novas imagens e os parâmetros. A porta 3001 não é publicada no host. As solicitações ao interpretador passam pelo backend.

Trabalho com arquivos do Chat#

Em um Chat, o Python acessa os arquivos em /sandbox. Eles permanecem entre solicitações no mesmo Chat. Outro Chat recebe um diretório separado.

No modo de interpretador, os arquivos anexados e o conteúdo das pastas do Assistente, incluindo subpastas, são transferidos para o diretório do Chat atual. Por padrão, são processados até 40 arquivos por solicitação. LLM_MAX_ATTACHMENT_FILES define o limite. Arquivos ausentes no disco são ignorados. Um arquivo novo com o mesmo nome substitui o anterior. No modo de Agente, uma ferramenta separada transfere o arquivo selecionado.

O upload e o download aceitam arquivos comuns de até 100 MiB e nomes em russo. Links simbólicos, arquivos especiais e caminhos fora do diretório do Chat não são fornecidos. É necessário salvar os resultados diretamente em /sandbox, com um nome sem diretórios aninhados.

Para verificar o funcionamento, é necessário enviar um CSV pequeno no modo de interpretador e solicitar o cálculo de uma soma e um resultado em XLSX. O resultado deve estar disponível para download. Outra solicitação no mesmo Chat deve ver o CSV. Um Chat novo sem o upload não deve vê-lo.

Restrições e recuperação#

É proibido listar /etc, /opt e /home, bem como ler /etc/passwd ou scripts de serviço. Os diretórios necessários de bibliotecas e fontes e determinados utilitários são permitidos para importações. As bibliotecas permitidas continuam acessíveis ao código. Seu inventário e metadados individuais de arquivos não são secretos. Não inclua tokens, senhas ou configuração da aplicação na imagem mypy.

Se aparecer Sandbox requires enabled Landlock ABI 1 or newer, o administrador deve verificar o suporte do kernel ao Landlock e se o Docker permite suas chamadas de sistema. Sem suporte, é necessário atualizar o ambiente. Se a verificação da configuração do contêiner falhar com ABI 1 ou 2, é necessário restaurar as restrições da configuração do Docker fornecida.

Em caso de erro de autenticação, é necessário verificar se os dois serviços recebem o mesmo token e recriá-los após alterar .env. Se uma biblioteca exigir um recurso adicional do sistema, forneça ao administrador seu nome e a mensagem de erro, sem conteúdo de arquivos nem segredos.