Lokale Docker-

Ein-Knoten-Ausführungsplattform, die TAO-Jobs als benannte Docker-Container auf einem Docker-Daemon ausführt. Der Daemon kann lokal auf dem Agenten-Host oder remote über DOCKER_HOST=ssh://user@host / einem Docker-Kontext betrieben werden. Dies ist nützlich für die Entwicklung, Fehlerbehebung, kleine Laufdurchgänge und Workflows, bei denen ein lokaler Codierungsagent Jobs an einen entfernten GPU-Rechner übermittelt.

Verwenden Sie „Lokaler Docker“, wenn sich die Daten lokal auf dem Docker-Host befinden oder über eingebundene Volumes/Cloud-Anmeldedaten zugänglich sind. Verwenden Sie ihn nicht für die Planung in Remote-Clustern, Training auf mehreren Knoten oder Jobs, die eine SLURM-Warteschlange erfordern.

Verwenden Sie Remote-Docker, wenn der Agent auf einer Workstation oder einem Laptop läuft, der Docker-Daemon und die GPUs sich jedoch auf einem anderen Server mit einer einzelnen GPU befinden. Im Remote-Docker-Modus werden alle lokalen Dateisystempfade in den Spezifikationen auf dem Remote-Docker-Host interpretiert, nicht auf dem Agentenrechner.

Vorabprüfung

Der Workflow muss die GPU-Laufzeitumgebung des Hosts vor dem Start von Docker-Jobs überprüfen. Falls die Überprüfung fehlschlägt, soll der Benutzer aufgefordert werden, die Installation zu genehmigen, den angezeigten Installationsbefehl auszuführen und die Vorabprüfung erneut durchzuführen.

# 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

Wenn eine Prüfung fehlschlägt, fordert der Agent den Benutzer auf, die Installation bzw. Korrektur über Bash zu autorisieren, bevor fortgefahren wird. Über „pip“ installierbare Python-Voraussetzungen und die oben beschriebene Einrichtung des Docker-Netzwerks bilden Ausnahmen: Diese sind automatisch zu installieren bzw. einzurichten, anschließend ist die Vorabprüfung erneut durchzuführen.

Anmeldedaten

Es sind keine Plattform-Anmeldedaten erforderlich, die über den Zugriff auf den Docker-Daemon hinausgehen.

Optionale Umgebungsvariable:

• DOCKER_HOST: Optionale URL des Docker-Daemons. Ist diese nicht gesetzt, verwendet das SDK die normale Umgebung bzw. die Standard-Socket-Auflösung des Docker-Python-Clients. Erforderlich für die remote-docker Plattformoption erforderlich.
• DOCKER_NETWORK: Docker-Netzwerk für Job-Container. Standardwert ist tao_default.
• DOCKER_USERNAME: Benutzername für das Registry. Standardwert ist $oauthtoken für NGC.
• NGC_KEY: Wird beim Abrufen privater Images von nvcr.io.
• HOST_SSH_PATH: Wird in AutoML-Brain-Container eingebunden, wenn diese SSH-Schlüssel benötigen, um entfernte SLURM-Unterjobs zu überwachen.
• ACCESS_KEY, SECRET_KEY, S3_ENDPOINT_URL, S3_BUCKET_NAME: Optionale S3-kompatible Speichereinstellungen für Jobs, die weiterhin Cloud-Speicher von einem lokalen Container aus lesen und beschreiben.

Vorabprüfung vor dem Start

Vor dem Generieren von Skripten oder dem Starten von Containern:

1. Stellen Sie sicher, dass der Docker-Daemon erreichbar ist, das NVIDIA Container Toolkit als Docker-Laufzeitumgebung registriert ist, GPUs und Treiberversion gemeldet werden und ein Smoke-Container vor dem Start die GPUs erkennen kann. Bei Remote-Docker fragen Sie die GPUs über docker run ... nvidia-smi über den Remote-Daemon ab; verwenden Sie keine lokalen nvidia-smi vom Agent-Rechner aus.
2. Stellen Sie sicher, dass alle lokalen/Datei-Datensatz-Annotationen und Medienpfade auf dem Docker-Host vorhanden sind.
3. Für s3:// Datensätze/Ergebnisse: Stellen Sie sicher, ACCESS_KEY und SECRET_KEY sind gesetzt und die genauen Pfade sind mit aws s3 ls. Falls aws fehlt, melden Sie die fehlende Abhängigkeit und fragen Sie vor der Installation nach; führen Sie den Preflight nach der Installation erneut durch.
4. Überprüfen Sie modellspezifische Anmeldedaten wie HF_TOKEN vor dem Start.
5. Überprüfen Sie die aktuelle GPU-Auslastung mit nvidia-smi und vermeiden Sie GPUs, die bereits von anderen laufenden Jobs genutzt werden, wenn der Benutzer diese Einschränkung angefordert hat. Zeigen Sie die ausgewählten GPU-IDs in der Startübersicht an.
6. Bei Modell-/Container-Kombinationen mit bekannten Architekturgrenzen die Rechenleistung der Host-GPU vor dem Start mit dem Container-Stack vergleichen. Wenn das ausgewählte Image kein JIT ausführen oder keine Kernel für die Host-Architektur ausführen kann, den Vorgang frühzeitig blockieren und nach einem kompatiblen Image oder einer kompatiblen Plattform fragen.

Verwenden Sie nach Möglichkeit das mitgelieferte Hilfsprogramm für diese Überprüfungen:

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

Bei einem Remote-Docker-Daemon die remote-docker „platform“ und übergeben oder exportieren Sie DOCKER_HOST. Der Helfer überprüft die Bereitschaft der Remote-GPU und der Laufzeitumgebung und kontrolliert die Datensatzpfade auf dem Remote-Host über schreibgeschützte Bind-Mounts:

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

Die --path oben genannten Werte müssen auf dem entfernten Docker-Host vorhanden sein. Geben Sie keine Pfade an, die nur auf dem lokalen Laptop oder dem Codex-Host vorhanden sind.

Multi-GPU und Multi-Knoten

Multi-Knoten wird auf lokalem Docker nicht unterstützt. Ein Job läuft auf dem Host des lokalen Docker-Daemons ohne hostübergreifende Koordination.

Multi-GPU auf dem lokalen Host wird über das NVIDIA Container Toolkit und das --gpus (--gpus all oder --gpus '"device=0,1,2,3"'). DockerSDK.create_job(gpu_count=N) wird an --gpus). Die verteilte Init-Funktion auf einem einzelnen Host nutzt localhost; torchrun --nproc-per-node=N oder PyTorch-DDP-Verfahren wie gewohnt.

Backend-Details

Verwenden Sie den SDK-Backend-Wert local-docker. Das lokale Backend-Schema enthält keine zusätzlichen Backend-Details, daher wird der Großteil des Routings durch Umgebungs- und Job-Parameter gesteuert:

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

Gemäß dem Brev-SDK-Design verbleiben die Werte für Plattform und Steuerungsebene im SDK- Zustand und in den Docker-Labels. Das SDK fügt keine BACKEND, HOST_PLATFORM, MONGOSECRET, DOCKER_HOSToder DOCKER_NETWORK in den Trainingscontainer ein.

Containerausführung

Der lokale Docker-Handler des TAO-SDK startet Container über den Docker-Python-Client :

• Der Name des Backend-Jobs verwendet das tao-job- Format, das von SDK-Handlern verwendet wird.
• Der Befehl lautet in der Regel ["/bin/bash", "-c", ""].
• Container werden im Detached-Modus ausgeführt. Das SDK behält Container standardmäßig bei, sodass Status und Protokolle weiterhin einsehbar sind, es sei denn, DOCKER_AUTO_REMOVE=true.
• /dev/shm als tmpfs eingebunden ist.
• Das konfigurierte Docker-Netzwerk wird vom Docker-Daemon für den Job-Container angewendet; es wird nicht als Prozessumgebungsvariable weitergegeben.
• Vorhandene Container mit derselben Job-ID werden angehalten und entfernt, bevor ein Ersatzcontainer gestartet wird.

Für den GPU-Zugriff erkennt der Handler automatisch den Host-Typ:

• Tegra- oder Jetson-Hosts verwenden runtime="nvidia" sowie NVIDIA_VISIBLE_DEVICES und NVIDIA_DRIVER_CAPABILITIES=all.
• Standard-x86-Hosts nutzen Docker device_requests mit GPU-Fähigkeiten.

Falls num_gpus ist 0, werden keine GPUs zugewiesen. Wenn num_gpus ist -1ist, werden alle sichtbaren GPUs angefordert. Bevorzugen Sie explizite GPU-Anzahlen bei gemeinsam genutzten Entwicklungsrechnern. Wenn explizite Geräte-IDs verfügbar sind, ziehen Sie diese der Auswahl nur nach Anzahl auf gemeinsam genutzten Rechnern vor, damit der Start keine GPUs beansprucht, die bereits von anderen Aufgaben belegt sind.

Speicher

Lokaler Docker akzeptiert lokale und file:// Pfade, da der Container auf dem selben Docker-Host läuft. Stellen Sie sicher, dass jeder Pfad in der Spezifikation entweder:

• vom Handler oder dem umgebenden Dienst in den Container eingebunden ist oder
• bereits von innerhalb des Containers erreichbar ist oder
• eine Cloud-URI mit passenden Anmeldedaten ist.

Bei entfernten/gemeinsam genutzten Dateisystemen sollten Sie die Plattform bevorzugen, zu der das Dateisystem gehört. Verwenden Sie beispielsweise SLURM in Verbindung mit lustre:///... für Lustre-Pfade in einem Cluster.

Überwachung

• Der SDK-Handler bildet den Status des Docker-Containers direkt ab: „created“ -> „Pending“, „running/restarting“ -> „Running“, „paused“ -> „Paused“, Exit-Code 0 -> „Complete“, Exit-Code ungleich Null -> „Error“.
• Protokolle kommen direkt vom genannten Container über den Docker-Python-Client (docker logs tao-job-).

Wenn der Container beendet wurde, abgestürzt ist, gerade entfernt wird oder nicht gefunden werden kann, behandelt die Statusabgleichung den Backend-Prozess als beendet.

Abbruch

Eine Abbruchanforderung stoppt den genannten Container. Die Verwaltung der GPU-Zuweisung erfolgt durch Docker bzw. die NVIDIA-Laufzeitumgebung, nicht durch den lokalen GPU-Manager von TAO Core.

Optional: über das TAO-SDK

Wenn Sie Job-Handles, S3-I/O-Wrapping über die script_runneroder sitzungsübergreifende Dauerhaftigkeit:

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)

Dies umhüllt denselben docker run Aufruf unter einem Job Handle und leitet den Einstiegspunkt durch script_runner , sodass inputs/outputs automatisch von S3 heruntergeladen bzw. auf S3 hochgeladen werden. Wenn Sie diese Funktionen nicht benötigen, nutzen Sie einfach docker run direkt – es ist keine SDK-Installation erforderlich.

Fehlermeldungen

Docker-Client nicht initialisiert: Überprüfen Sie, ob das Docker-Python-Paket installiert ist, legen Sie DOCKER_HOST , falls Sie nicht den lokalen Standard-Socket verwenden, und stellen Sie sicher, dass der Prozess mit dem Daemon kommunizieren kann.

GPU-Zuweisung fehlgeschlagen: Die angeforderten GPUs sind nicht verfügbar, das NVIDIA Container Toolkit ist nicht konfiguriert oder der Docker-Daemon kann keine GPU-Geräteanforderungen erstellen. Verwenden Sie weniger GPUs, warten Sie, bis ein anderer Job abgeschlossen ist, oder überprüfen Sie, docker run --gpus ... auf dem Host funktioniert.

Authentifizierung beim Abrufen des Images fehlgeschlagen: Legen Sie eine gültige NGC_KEY für private nvcr.io Images oder führen Sie docker login nvcr.io -u '$oauthtoken' auf dem Docker-Host aus.

Container wurde unerwartet beendet: Überprüfen Sie docker logs tao-job-, das konfigurierte DOCKER_NETWORKund den vom SDK-Action-Runner generierten Befehl.

Pfad im Container fehlt: Ein lokaler Pfad auf dem Host wird nicht zwangsläufig in den Job-Container eingebunden. Verwenden Sie eine vom Aktions-Runner unterstützte Pfadkonvention oder konfigurieren Sie ein explizites Volume über den umgebenden Dienst.