Docker local

Plateforme d’exécution à nœud unique qui exécute les tâches TAO sous forme de conteneurs Docker nommés sur un démon Docker. Le démon peut être local sur l’hôte de l’agent ou distant via DOCKER_HOST=ssh://user@host / un contexte Docker. Il est utile pour le développement, le débogage, les petites exécutions et les workflows dans lesquels un agent de codage local soumet des tâches à un serveur GPU distant.

Utilisez Docker local lorsque les données se trouvent sur l’hôte Docker ou sont accessibles via des volumes montés ou des identifiants cloud. Ne l’utilisez pas pour la planification sur un cluster distant, l’entraînement multi-nœuds ou les tâches nécessitant une mise en file d’attente SLURM.

Utilisez Docker distant lorsque l’agent s’exécute sur une station de travail ou un ordinateur portable, mais que le démon Docker et les GPU se trouvent sur un autre serveur à GPU unique. En mode Docker distant, tous les chemins d’accès au système de fichiers local indiqués dans les spécifications sont interprétés sur l’hôte Docker distant, et non sur la machine de l’agent.

Pré-vérification

Le workflow doit vérifier l’environnement d’exécution GPU de l’hôte avant de lancer les tâches Docker. Si la vérification échoue, invitez l’utilisateur à approuver l’installation, exécutez la commande d’installation affichée, puis relancez la pré-vérification.

# 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

Si une vérification échoue, l’agent invite l’utilisateur à autoriser l’installation ou la correction via Bash avant de poursuivre. Les dépendances Python installables via pip et la création du réseau Docker mentionnées ci-dessus constituent des exceptions : installez-les ou créez-les automatiquement, puis relancez le contrôle préalable.

Identifiants

Aucun identifiant de la plateforme n’est requis au-delà de l’accès au démon Docker.

Environnement facultatif :

• DOCKER_HOST : URL facultative du démon Docker. Si elle n’est pas définie, le SDK utilise la résolution d’environnement normale ou la résolution de socket par défaut du client Python de Docker. Obligatoire pour l’ remote-docker option de plateforme.
• DOCKER_NETWORK : réseau Docker pour les conteneurs de tâches. La valeur par défaut est tao_default.
• DOCKER_USERNAME : nom d’utilisateur du registre. La valeur par défaut est $oauthtoken pour NGC.
• NGC_KEY : Utilisé lors de la récupération d’images privées depuis nvcr.io.
• HOST_SSH_PATH : Monté dans les conteneurs « brain » d’AutoML lorsqu’ils ont besoin de clés SSH pour surveiller les tâches enfants SLURM distantes.
• ACCESS_KEY, SECRET_KEY, S3_ENDPOINT_URL, S3_BUCKET_NAME : Paramètres de stockage compatibles S3 facultatifs pour les tâches qui continuent à lire/écrire dans le stockage cloud à partir d’un conteneur local.

Pré-vérification du lancement

Avant de générer des scripts ou de démarrer des conteneurs :

1. Vérifiez que le démon Docker est accessible, que NVIDIA Container Toolkit est enregistré en tant qu’environnement d’exécution Docker, que les GPU et la version du pilote sont détectés, et qu’un conteneur de test peut détecter les GPU avant le lancement. Pour Docker à distance, interrogez les GPU via docker run ... nvidia-smi le démon distant ; n’utilisez pas nvidia-smi depuis la machine agent.
2. Vérifiez que chaque annotation de jeu de données local(e) ou de fichier et chaque chemin d’accès aux médias existe sur l’ hôte Docker.
3. Pour les s3:// les ensembles de données/résultats, vérifiez ACCESS_KEY et SECRET_KEY sont définis et que les chemins d’accès exacts sont accessibles via aws s3 ls. Si aws manque, signalez la dépendance manquante et demandez confirmation avant de l'installer ; relancez la vérification préalable après l'installation.
4. Vérifiez les identifiants spécifiques au modèle, tels que HF_TOKEN avant le lancement.
5. Vérifiez l’occupation actuelle des GPU à l’aide de nvidia-smi et évitez les GPU déjà utilisés par d’autres tâches en cours d’exécution lorsque l’utilisateur a demandé cette contrainte. Affichez les identifiants des GPU sélectionnés dans la revue de lancement.
6. Pour les combinaisons modèle/conteneur présentant des limites d’architecture connues, comparez la capacité de calcul du GPU hôte avec la pile du conteneur avant le lancement. Si l’ image sélectionnée ne peut pas effectuer de compilation JIT ou exécuter de noyaux pour l’architecture de l’hôte, bloquez le processus dès le début et demandez une image ou une plateforme compatible.

Utilisez l’utilitaire fourni pour ces vérifications lorsque cela est possible :

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

Pour un démon Docker distant, utilisez la remote-docker paramètre « platform » et le paramètre « pass » ou « export » DOCKER_HOST. L’utilitaire vérifie la disponibilité du GPU et de l’environnement d’exécution à distance, et contrôle les chemins d’accès aux ensembles de données sur l’hôte distant via des montages liés en lecture seule :

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

Les --path valeurs ci-dessus doivent exister sur l’hôte Docker distant. Ne transmettez pas de chemins d’accès qui n’existent que sur l’ordinateur portable local ou l’hôte Codex.

Multi-GPU et multi-nœuds

Le mode multi-nœuds n’est pas pris en charge sur Docker local. Une tâche s’exécute sur l’hôte du démon Docker local sans coordination inter-hôtes.

Le multi-GPU sur l’hôte local est pris en charge via le drapeau --gpus (--gpus all ou --gpus '"device=0,1,2,3"'). DockerSDK.create_job(gpu_count=N) renvoie directement vers --gpus). L’initialisation distribuée sur un seul hôte utilise localhost; torchrun --nproc-per-node=N ou le DDP de PyTorch, comme d’habitude.

Détails du backend

Utilisez la valeur de backend du SDK local-docker. Le schéma de backend local ne comporte pas de détails supplémentaires sur le backend ; la plupart des routages sont donc contrôlés par les paramètres d'environnement et de tâche :

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

Conformément à la conception du SDK Brev, les valeurs de la plateforme et du plan de contrôle restent dans l’état du SDK et les étiquettes Docker. Le SDK n’injecte pas BACKEND, HOST_PLATFORM, MONGOSECRET, DOCKER_HOST, ni DOCKER_NETWORK dans le conteneur d’entraînement.

Exécution des conteneurs

Le gestionnaire Docker local du SDK TAO lance les conteneurs via le client Python de Docker :

• Le nom de la tâche backend utilise le tao-job- format utilisé par les gestionnaires du SDK.
• La commande est généralement ["/bin/bash", "-c", ""].
• Les conteneurs s’exécutent en mode détaché. Par défaut, le SDK conserve les conteneurs afin que leur état et leurs journaux restent consultables, sauf si DOCKER_AUTO_REMOVE=true.
• /dev/shm soit monté en tant que tmpfs.
• Le réseau Docker configuré est appliqué par le démon Docker au conteneur de la tâche ; il n’est pas transmis en tant que variable d’environnement du processus.
• Les conteneurs existants portant le même identifiant de tâche sont arrêtés et supprimés avant le démarrage d’un conteneur de remplacement.

Pour l’accès au GPU, le gestionnaire détecte automatiquement le type d’hôte :

• les hôtes Tegra ou Jetson utilisent runtime="nvidia" plus NVIDIA_VISIBLE_DEVICES et NVIDIA_DRIVER_CAPABILITIES=all.
• Les hôtes x86 standard utilisent Docker device_requests avec des capacités GPU.

Si num_gpus est 0, aucun GPU n’est attribué. Si num_gpus est -1, tous les GPU visibles sont sollicités. Privilégiez les nombres explicites de GPU pour les machines de développement partagées. Lorsque des identifiants de périphériques explicites sont disponibles, privilégiez-les par rapport à la sélection basée uniquement sur le nombre sur les machines partagées, afin que le lancement ne monopolise pas les GPU occupés par d’autres tâches.

Stockage

Docker local accepte les chemins d’accès locaux et file:// chemins d’accès locaux, car le conteneur s’exécute sur le même hôte Docker. Assurez-vous que chaque chemin d’accès de la spécification soit :

• monté dans le conteneur par le gestionnaire ou le service environnant,
• déjà accessible depuis l’intérieur du conteneur, ou
• une URI cloud avec des identifiants correspondants.

Pour les systèmes de fichiers distants/partagés, privilégiez la plateforme propriétaire de ce système de fichiers. Par exemple, utilisez SLURM avec lustre:///... pour les chemins d’accès Lustre sur un cluster.

Surveillance

• Le gestionnaire SDK mappe directement l’état du conteneur Docker : créé -> En attente, en cours d’exécution/redémarrage -> En cours d’exécution, en pause -> En pause, code de sortie 0 -> Terminé, code de sortie différent de zéro -> Erreur.
• Les journaux proviennent directement du conteneur nommé via le client Python de Docker (docker logs tao-job-).

Si le conteneur s’est arrêté, a cessé de fonctionner, est en cours de suppression ou est introuvable, le rapprochement d’état considère que le processus backend est terminé.

Annulation

L’annulation arrête le conteneur spécifié. La gestion du GPU est assurée par Docker / le runtime NVIDIA, et non par le gestionnaire de GPU local de TAO Core.

Facultatif : via le SDK TAO

Si vous souhaitez des identifiants de tâche, une gestion des E/S S3 via le SDK script_runner, ou la persistance entre les sessions :

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)

Cela encapsule la même docker run invocation sous un Job descripteur et achemine le point d’entrée via script_runner , ce qui inputs/outputs soit téléchargé depuis / ou vers S3 automatiquement. Si vous n’en avez pas besoin, utilisez simplement docker run directement — aucune installation de SDK n’est requise.

Modes d’échec

Client Docker non initialisé : vérifiez que le paquet Python de Docker est installé, configurez DOCKER_HOST si vous n’utilisez pas le socket local par défaut, et assurez-vous que le processus peut communiquer avec le démon.

Échec de l’attribution des GPU : les GPU demandés ne sont pas disponibles, le NVIDIA Container Toolkit n’est pas configuré ou le démon Docker ne peut pas créer de requêtes de périphériques GPU. Utilisez moins de GPU, attendez qu’une autre tâche se termine ou vérifiez docker run --gpus ... fonctionne sur l’hôte.

Échec de l’authentification pour le téléchargement de l’image : définissez un NGC_KEY pour les nvcr.io ou exécutez docker login nvcr.io -u '$oauthtoken' sur l’hôte Docker.

Le conteneur s'est arrêté de manière inattendue : vérifiez docker logs tao-job-, la configuration DOCKER_NETWORKet la commande générée par le moteur d’actions SDK.

Chemin d’accès manquant à l’intérieur du conteneur : un chemin d’accès local sur l’hôte n’est pas nécessairement monté dans le conteneur de la tâche. Utilisez une convention de chemin d’accès prise en charge par le moteur d’actions ou configurez un volume explicite via le service environnant.