Docker pour les charges de travail GPU NVIDIA

Cette skill documente les conventions Docker génériques sur lesquelles s'appuient les charges de travail des conteneurs GPU. Les skills de modèle et de données spécifient quelle image et quelle commande exécuter ; cette skill couvre comment exécuter docker de manière à satisfaire les exigences GPU + NVIDIA Container.

Sources : référence officielle de la CLI Docker (https://docs.docker.com/reference/cli/docker/) et documentation NVIDIA Container Toolkit.

Prérequis

Runtime GPU sur l'hôte — branche NVIDIA driver 580, CUDA Toolkit 13.0 et NVIDIA Container Toolkit 1.19.0. Vérifiez avec la skill tao-setup-nvidia-gpu-host avant de commencer un workflow GPU.
Docker — docker --version doit retourner ≥ 20.10. Installation : https://docs.docker.com/engine/install/.
Clé API NGC pour les pulls nvcr.io/*. Obtenez-la sur https://ngc.nvidia.com/.

TAO_SKILL_BANK_ROOT="${TAO_SKILL_BANK_ROOT:-$PWD}"
SETUP_SCRIPT="${TAO_SKILL_BANK_ROOT}/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 (append --yes for non-interactive agent runs):"
  echo "  bash \"$SETUP_SCRIPT\" --backend docker --install"
  exit 1
}

docker --version
docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi
[ -n "$NGC_KEY" ] || echo "NGC_KEY unset — cannot pull nvcr.io images"

Authentification NGC

echo "$NGC_KEY" | docker login nvcr.io -u '$oauthtoken' --password-stdin

Persiste dans ~/.docker/config.json après redémarrage. Réexécutez en cas d'erreurs unauthorized.

`docker run` — flags canoniques

docker run \
  --gpus all \                        # tous les GPUs (nécessite nvidia-container-toolkit)
  --rm \                              # supprimer le conteneur à la sortie (l'image est préservée)
  --shm-size=8g \                     # mémoire partagée pour torchrun / DataLoader
  -v /host/data:/data \               # bind-mount en entrée
  -v /host/results:/results \         # bind-mount en sortie
  -e HF_TOKEN -e NGC_KEY \            # passage de variables d'env (valeurs du shell parent)
  <image> \
  <command>

Notes :

--gpus '"device=0,1"' — GPUs spécifiques (guillemets doubles échappés). Sans nvidia-container-toolkit : could not select device driver "" with capabilities: [[gpu]].
--rm — nettoie le conteneur à la sortie ; omettez-le si vous voulez docker logs après la sortie.
--shm-size=8g — torchrun + PyTorch DataLoaders épuisent le /dev/shm par défaut de 64 MB sinon ; dimensionnez-le pour l'entraînement multi-GPU et augmentez-le (par ex. 16g) si vous rencontrez Bus error.
-v host:container — bind mount ; la commande ne référence que les chemins du conteneur.
-e VAR — passage du shell parent (aucune valeur nécessaire si déjà définie). Utilisez cette forme pour les secrets.

Collision de noms de conteneurs

docker run --name X échoue si un conteneur nommé X existe déjà. Motif défensif avant réutilisation d'un nom :

docker stop my-worker 2>/dev/null; docker rm my-worker 2>/dev/null
docker run --name my-worker ...

Motif détaché + exec

Pour les workflows multi-étapes sur le même conteneur (télécharger → exécuter → post-traiter), évitez le coût du redémarrage :

docker run -d --name <worker> \
  --gpus all --shm-size=8g \
  -v <mounts...> -e <envs...> \
  --entrypoint sh \
  <image> -c "tail -f /dev/null"

docker exec <worker> <step_1>
docker exec <worker> <step_2>

docker stop <worker> && docker rm <worker>

Idiome pull-if-missing

docker image inspect <image> >/dev/null 2>&1 || docker pull <image>

Labels pour la découverte

Taggez les conteneurs pour les lister avec filtres plus tard :

docker run --label tao-toolkit ...
docker ps --filter 'label=tao-toolkit'

Motifs de montage

Le conteneur attend ses données dans des chemins conventionnels définis par l'image (souvent /data, /results, /workspace/checkpoints). Le côté hôte est arbitraire. La commande dans docker run référence seulement les chemins du conteneur.

Conventions de variables d'env

Variables courantes de passage pour les charges de travail de style TAO (la skill appelante déclare celles dont elle a besoin) :

NGC_KEY — pulls nvcr.io ; certains runtimes les lisent aussi à l'exécution
HF_TOKEN — téléchargements de modèles HuggingFace gérés
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL — I/O S3 dans le conteneur
WANDB_API_KEY — logging W&B optionnel

Utilisez -e VAR (sans =value) quand la variable se trouve dans le shell parent. Évitez de placer les secrets sur la ligne de commande.

Sélection GPU alternative : -e NVIDIA_VISIBLE_DEVICES=0,1 (ou all) et -e NVIDIA_DRIVER_CAPABILITIES=all au lieu de --gpus. Le flag --gpus est préféré sur les hôtes x86 standard ; la forme env-var est plus ancienne et est ce que runtime=nvidia (Tegra/Jetson) nécessite.

Inspection de conteneur

docker ps                                # conteneurs en cours d'exécution seulement
docker ps -a                             # tous les conteneurs, y compris les arrêtés
docker ps --filter status=running --format '{{.Names}} {{.Image}}'
docker logs <name_or_id>                 # stdout/stderr
docker logs -f <name_or_id>              # follow (équivalent tail -f)
docker logs --tail 100 <name_or_id>      # dernières N lignes
docker inspect <name_or_id>              # configuration complète, montages, env, réseau, état (JSON)
docker inspect --format '{{.State.Status}}' <name_or_id>
docker stats                             # CPU/mem/réseau/block I/O en direct
docker stats --no-stream                 # un snapshot, non-interactif

docker inspect est la source canonique de vérité pour les montages, l'env, la cmd, le réseau et le code de sortie d'un conteneur. Utilisez-le pour déboguer pourquoi un conteneur ne se comporte pas comme prévu.

Gestion des images

docker pull <image>
docker image ls
docker system df                # utilisation disque
docker system prune -a --volumes # récupérer l'espace — destructif, supprime les images et volumes inutilisés

Pull une fois par hôte ; docker run réutilise l'image en cache. Les images NVIDIA font généralement 5-40GB.

Relocalisation de data-root sur disque divisé

Certains fournisseurs de GPU cloud livrent un petit volume racine + un plus grand éphémère. Docker écrit par défaut dans /var/lib/docker sur la racine — les grandes images la remplissent. Vérifiez :

df -h /         # taille/espace libre du volume racine
lsblk           # tous les appareils bloc et points de montage

Si / est plus petit que votre empreinte d'image totale et qu'il y a un disque plus grand monté ailleurs, relocalisez avant de pull les images :

sudo systemctl stop docker
sudo mkdir -p <large_volume_path>/docker
sudo rsync -aP /var/lib/docker/ <large_volume_path>/docker/
sudo mv /var/lib/docker /var/lib/docker.old

sudo tee /etc/docker/daemon.json <<'EOF'
{ "data-root": "<large_volume_path>/docker" }
EOF

sudo systemctl start docker
docker info | grep 'Docker Root Dir'
sudo rm -rf /var/lib/docker.old

Réseaux (motifs multi-conteneurs)

Pour les conteneurs microservices qui communiquent par nom, créez un réseau docker et attachez-y les conteneurs :

docker network create tao-net
docker run --network tao-net --name api ...
docker run --network tao-net --name worker ...   # peut résoudre `api` par nom

La plupart des charges de travail d'entraînement TAO n'en ont pas besoin — un conteneur par job.

Modes d'erreur courants

could not select device driver "" with capabilities: [[gpu]] — NVIDIA Container Toolkit manquant ou Docker n'est pas configuré pour le runtime NVIDIA. Exécutez tao-setup-nvidia-gpu-host avec --backend docker --install après approbation de l'utilisateur (ajoutez --yes pour un agent non-interactif), puis redémarrez Docker.

unauthorized: authentication required sur docker pull — clé NGC invalide/manquante. Réexécutez docker login nvcr.io.

no space left on device — volume racine plein. docker system df pour inspecter ; relocalisez data-root (ci-dessus) ou docker system prune -a --volumes.

Bus error / DataLoader worker exited unexpectedly — /dev/shm trop petit. Augmentez la mémoire partagée avec --shm-size (par ex. --shm-size=16g).

permission denied sur les chemins bind-montés — container UID ≠ host UID. Soit -u $(id -u):$(id -g), soit pré-créez les fichiers d'hôte propriété de l'utilisateur d'hôte, soit chmod 777 (dev seulement).

Error: No such container: <name> après docker run -d — le conteneur a crashé au démarrage. docker ps -a affiche exited ; docker logs <name> pour la cause. Supprimez --rm lors du débogage.

Limite de périmètre

Cette skill couvre le comment d'exécution de docker sur un hôte GPU. Le layering spécifique à la plateforme (comment accéder à l'hôte, dispatcher via un wrapper CLI) se trouve dans :

tao-skill-bank:tao-run-on-brev — exécution de docker via brev exec sur une instance Brev
tao-skill-bank:tao-run-platform — couche Python optionnelle enrobant les invocations docker avec Job handles, persistance d'état et I/O S3

Les skills de modèle et de données spécifient quelle image et commande ; elles se réfèrent à cette skill pour le comment.

tao-run-on-docker

Docker pour les charges de travail GPU NVIDIA

Prérequis

Authentification NGC

`docker run` — flags canoniques

Collision de noms de conteneurs

Motif détaché + exec

Idiome pull-if-missing

Labels pour la découverte

Motifs de montage

Conventions de variables d'env

Inspection de conteneur

Gestion des images

Relocalisation de data-root sur disque divisé

Réseaux (motifs multi-conteneurs)

Modes d'erreur courants

Limite de périmètre

Skills similaires

Docker pour les charges de travail GPU NVIDIA

Prérequis

Authentification NGC

docker run — flags canoniques

Collision de noms de conteneurs

Motif détaché + exec

Idiome pull-if-missing

Labels pour la découverte

Motifs de montage

Conventions de variables d'env

Inspection de conteneur

Gestion des images

Relocalisation de data-root sur disque divisé

Réseaux (motifs multi-conteneurs)

Modes d'erreur courants

Limite de périmètre

Skills similaires

`docker run` — flags canoniques