Docker local

Plataforma de execução de nó único que executa tarefas TAO como contêineres Docker nomeados em um daemon do Docker. O daemon pode estar localmente no host do agente ou remotamente por meio DOCKER_HOST=ssh://user@host / um contexto do Docker. É útil para desenvolvimento, depuração, pequenas execuções e fluxos de trabalho em que um agente de codificação local envia tarefas para uma máquina com GPU remota.

Use o Docker local quando os dados estiverem no host do Docker ou forem acessíveis por meio de volumes montados/credenciais de nuvem. Não o utilize para agendamento em cluster remoto, treinamento em múltiplos nós ou tarefas que exijam enfileiramento SLURM.

Use o Docker remoto quando o agente estiver em execução em uma estação de trabalho ou laptop, mas o daemon do Docker e as GPUs estiverem em outro servidor com uma única GPU. No modo Docker remoto, todos os caminhos do sistema de arquivos local nas especificações são interpretados no host remoto do Docker, não na máquina do agente.

Pré-verificação

O fluxo de trabalho deve verificar o ambiente de execução da GPU do host antes de iniciar tarefas do Docker. Se a verificação falhar, solicite ao usuário que aprove a instalação, execute o comando de instalação exibido e reexecute a verificação prévia.

# Host GPU runtime: NVIDIA driver 580, CUDA 13.0, NVIDIA Container Toolkit 1.19.0.
TAO_SKILL_BANK_ROOT="${TAO_SKILL_BANK_ROOT:-$PWD}"
SETUP_SCRIPT="${TAO_SKILL_BANK_ROOT}/skills/platform/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh"

bash "$SETUP_SCRIPT" --backend docker --check-only || {
  echo "MISSING: TAO GPU host runtime is not ready."
  echo "After user approval, run:"
  echo "  bash \"$SETUP_SCRIPT\" --backend docker --install --yes"
  exit 1
}

# Mode 1 — direct docker (no Python). All you need is docker + the GPU runtime.
docker info >/dev/null 2>&1 || { echo "MISSING: docker daemon not reachable. Start Docker."; exit 1; }
docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi >/dev/null 2>&1 || {
  echo "MISSING: NVIDIA Container Toolkit not installed/configured. See:"
  echo "  bash \"$SETUP_SCRIPT\" --backend docker --install --yes"
  exit 1
}

# Mode 2 — TAO SDK wrapper. Adds Job handles, S3 I/O wrapping, ActionWorkflow.
# Skip this block if Mode 1 is sufficient for the user's request.
# When Mode 2 is in scope, read `tao-skill-bank:tao-run-platform` for the DockerSDK
# kwarg contract, build_entrypoint, and monitoring patterns.
# nvidia-tao-sdk is on public PyPI; pin lives in versions.yaml (wheels.tao_sdk_docker).
PIN=$("${TAO_SKILL_BANK_PATH:?}/scripts/resolve_versions_key.py" wheels.tao_sdk_docker)
python -c "import tao_sdk" 2>/dev/null || python -m pip install "$PIN"
python -c "import docker" 2>/dev/null || python -m pip install "$PIN"
python -c "import tao_sdk, docker"

# DockerSDK attaches every job container to ${DOCKER_NETWORK:-tao_default}.
# Create the network if it is missing; the operation is local and idempotent.
DOCKER_NETWORK_NAME="${DOCKER_NETWORK:-tao_default}"
docker network inspect "$DOCKER_NETWORK_NAME" >/dev/null 2>&1 || \
  docker network create "$DOCKER_NETWORK_NAME" >/dev/null

Se uma verificação falhar, o agente solicita que o usuário autorize a instalação/correção via Bash antes de prosseguir. Os requisitos do Python instaláveis via pip e a criação da rede do Docker mencionados acima são exceções: instale-os/crie-os automaticamente e, em seguida, execute novamente a verificação prévia.

Credenciais

Não há necessidade de credenciais da plataforma além do acesso ao daemon do Docker.

Ambiente opcional:

• DOCKER_HOST: URL opcional do daemon do Docker. Se não estiver definida, o SDK usa a resolução normal de ambiente/soquete padrão do cliente Python do Docker. Obrigatório para a remote-docker opção de plataforma.
• DOCKER_NETWORK: Rede do Docker para contêineres de tarefas. O padrão é tao_default.
• DOCKER_USERNAME: Nome de usuário do registro. O padrão é $oauthtoken para o NGC.
• NGC_KEY: Usado ao baixar imagens privadas de nvcr.io.
• HOST_SSH_PATH: Montado nos contêineres do AutoML Brain quando eles precisam de chaves SSH para monitorar tarefas filhas remotas do SLURM.
• ACCESS_KEY, SECRET_KEY, S3_ENDPOINT_URL, S3_BUCKET_NAME: Configurações opcionais de armazenamento compatível com S3 para tarefas que ainda leem/gravam no armazenamento em nuvem a partir de um contêiner local.

Pré-verificação de inicialização

Antes de gerar scripts ou iniciar contêineres:

1. Verifique se o daemon do Docker está acessível, se o NVIDIA Container Toolkit está registrado como um runtime do Docker, se as GPUs e a versão do driver estão sendo reportadas e se um contêiner de teste consegue detectar as GPUs antes da inicialização. Para o Docker remoto, consulte as GPUs por meio docker run ... nvidia-smi o daemon remoto; não use nvidia-smi a partir da máquina agente.
2. Verifique se todas as anotações do conjunto de dados local/em arquivo e os caminhos de mídia existem no host do Docker.
3. Para s3:// conjuntos de dados/resultados, verifique ACCESS_KEY e SECRET_KEY estejam definidos e que os caminhos exatos sejam legíveis com aws s3 ls. Se aws estiver faltando, relate a dependência ausente e pergunte antes de instalá-la; execute novamente a verificação prévia após a instalação.
4. Verifique as credenciais específicas do modelo, como HF_TOKEN antes da inicialização.
5. Verifique a ocupação atual da GPU com nvidia-smi e evite GPUs já utilizadas por outros trabalhos em execução quando o usuário tiver solicitado essa restrição. Exiba os IDs das GPUs selecionadas na revisão de inicialização.
6. Para combinações de modelo/contêiner com limites de arquitetura conhecidos, compare a capacidade de computação da GPU do host com a pilha do contêiner antes da inicialização. Se a imagem selecionada não puder fazer JIT ou executar kernels para a arquitetura do host, bloqueie antecipadamente e solicite uma imagem ou plataforma compatível.

Use o auxiliar integrado para essas verificações, quando possível:

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/check_tao_launch_preflight.py \
  --platform local-docker \
  --container-image "" \
  --path train_annotation=/abs/path/to/annotations.json \
  --path train_media=/abs/path/to/media

Para um daemon Docker remoto, use a remote-docker plataforma e passe ou exporte DOCKER_HOST. O auxiliar verifica a disponibilidade da GPU/tempo de execução remotos e verifica os caminhos dos conjuntos de dados do host remoto por meio de montagens bind somente leitura:

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/check_tao_launch_preflight.py \
  --platform remote-docker \
  --docker-host ssh://user@gpu-host \
  --container-image "" \
  --gpu-smoke-image ubuntu:22.04 \
  --path train_annotation=/remote/data/train/annotations.json \
  --path train_media=/remote/data/train

Os --path valores acima devem existir no host remoto do Docker. Não passe caminhos que existam apenas no laptop local ou no host do Codex.

Multi-GPU e multinó

O recurso de múltiplos nós não é compatível com o Docker local. Um trabalho é executado no host do daemon do Docker local, sem coordenação entre hosts.

O suporte a múltiplas GPUs no host local é fornecido por meio do sinalizador --gpus (--gpus all ou --gpus '"device=0,1,2,3"'). DockerSDK.create_job(gpu_count=N) que se conecta diretamente ao --gpus. A inicialização distribuída em um único host usa localhost; torchrun --nproc-per-node=N ou o PyTorch DDP funcionam normalmente.

Detalhes do backend

Use o valor de backend do SDK local-docker. O esquema do backend local não possui detalhes adicionais de backend, portanto, a maior parte do roteamento é controlada por parâmetros de ambiente e de tarefa :

{
  "backend_type": "local-docker",
  "num_gpu": 1
}

Seguindo o design do SDK do Brev, os valores da plataforma/plano de controle permanecem no estado do SDK e nos rótulos do Docker. O SDK não injeta BACKEND, HOST_PLATFORM, MONGOSECRET, DOCKER_HOST, nem DOCKER_NETWORK no contêiner de treinamento.

Execução do contêiner

O manipulador Docker local do SDK do TAO inicia contêineres por meio do cliente Docker em Python :

• O nome da tarefa de back-end utiliza o tao-job- formato utilizado pelos manipuladores do SDK.
• O comando é geralmente ["/bin/bash", "-c", ""].
• Os contêineres são executados de forma independente. Por padrão, o SDK mantém os contêineres, de modo que o status e os logs permaneçam acessíveis para inspeção, a menos que DOCKER_AUTO_REMOVE=true.
• /dev/shm estejam montados como tmpfs.
• A rede do Docker configurada é aplicada pelo daemon do Docker ao contêiner da tarefa ; ela não é passada como uma variável de ambiente do processo.
• Os contêineres existentes com o mesmo ID de tarefa são interrompidos e removidos antes que um substituto seja iniciado.

Para acesso à GPU, o manipulador detecta automaticamente o tipo de host:

• Os hosts Tegra ou Jetson utilizam runtime="nvidia" além de NVIDIA_VISIBLE_DEVICES e NVIDIA_DRIVER_CAPABILITIES=all.
• Os hosts x86 padrão usam o Docker device_requests com recursos de GPU.

Se num_gpus for 0, nenhuma GPU é atribuída. Se num_gpus for -1, todas as GPUs visíveis são solicitadas. Dê preferência a contagens explícitas de GPUs em máquinas de desenvolvimento compartilhadas. Quando IDs explícitos de dispositivos estiverem disponíveis, dê preferência a eles em vez da seleção apenas por contagem em máquinas compartilhadas, para que a inicialização não ocupe GPUs já utilizadas por outras tarefas.

Armazenamento

O Docker local aceita caminhos locais e file:// caminhos, pois o contêiner é executado no mesmo host do Docker. Certifique-se de que cada caminho na especificação esteja:

• montado no contêiner pelo manipulador ou pelo serviço associado,
• já seja acessível de dentro do contêiner, ou
• um URI na nuvem com credenciais correspondentes.

Para sistemas de arquivos remotos/compartilhados, dê preferência à plataforma proprietária desse sistema de arquivos. Por exemplo, use o SLURM junto com lustre:///... para caminhos Lustre em um cluster.

Monitoramento

• O manipulador do SDK mapeia diretamente o estado do contêiner Docker: criado -> Pendente, em execução/reiniciando -> Em execução, pausado -> Pausado, código de saída 0 -> Concluído, código de saída diferente de zero -> Erro.
• Os logs vêm diretamente do contêiner especificado por meio do cliente Python do Docker (docker logs tao-job-).

Se o contêiner tiver sido encerrado, tiver falhado, estiver sendo removido ou não puder ser encontrado, a reconciliação de status trata o processo de back-end como encerrado.

Cancelamento

O cancelamento interrompe o contêiner especificado. A propriedade da GPU é gerenciada pelo Docker / o runtime da NVIDIA, e não pelo gerenciador de GPU local do TAO Core.

Opcional: via SDK do TAO

Se você deseja identificadores de tarefa, encapsulamento de E/S do S3 por meio do SDK script_runnerou durabilidade entre sessões:

from tao_sdk.platforms.docker import DockerSDK

sdk = DockerSDK()  # reads DOCKER_HOST, NGC_KEY, S3 creds from env
job = sdk.create_job(
    image='nvcr.io/nvidia/tao/tao-toolkit:6.26.3-pyt',
    command='dino train -e /tmp/spec.yaml',
    gpu_count=1,
    inputs={'/data/train.json': 's3://bucket/coco/train.json'},
    outputs=['/results/'],
)

status = sdk.get_job_status(job.id)
logs = sdk.get_job_logs(job.id, tail=200)

Isso encapsula a mesma docker run invocação sob um Job identificador e redireciona o ponto de entrada por meio de script_runner , de modo que inputs/outputs sejam baixados de / ou enviados para o S3 automaticamente. Se você não precisar disso, basta usar docker run diretamente — não é necessária a instalação do SDK.

Modos de falha

Cliente Docker não inicializado: verifique se o pacote Docker para Python está instalado, defina DOCKER_HOST se você não estiver usando o soquete local padrão e confirme se o processo consegue se comunicar com o daemon.

Falha na atribuição da GPU: as GPUs solicitadas não estão disponíveis, o NVIDIA Container Toolkit não está configurado ou o daemon do Docker não consegue criar solicitações de dispositivos de GPU. Use menos GPUs, aguarde a conclusão de outro trabalho ou verifique docker run --gpus ... funciona no host.

Falha na autenticação para baixar imagem: Defina uma NGC_KEY para nvcr.io ou execute docker login nvcr.io -u '$oauthtoken' no host do Docker.

O contêiner foi encerrado inesperadamente: verifique docker logs tao-job-se a configuração DOCKER_NETWORKe o comando gerado pelo executor de ações do SDK.

Caminho ausente dentro do contêiner: um caminho local no host não é necessariamente montado no contêiner da tarefa. Use uma convenção de caminho compatível com o executor de ações ou configure um volume explícito por meio do serviço associado.