Docker local

Plataforma de ejecución de un solo nodo que ejecuta trabajos de TAO como contenedores Docker con nombre en un demonio de Docker. El demonio puede ser local al host del agente o remoto a través DOCKER_HOST=ssh://user@host / un contexto de Docker. Resulta útil para el desarrollo, la depuración, ejecuciones de pequeño tamaño y flujos de trabajo en los que un agente de programación local envía trabajos a una máquina con GPU remota.

Utiliza Docker local cuando los datos se encuentren en el propio host de Docker o sean accesibles a través de volúmenes montados o credenciales en la nube. No lo utilices para la programación de clústeres remotos, el entrenamiento en múltiples nodos ni para trabajos que requieran colas SLURM.

Utilice Docker remoto cuando el agente se ejecute en una estación de trabajo o un portátil, pero el daemon de Docker y las GPU se encuentren en otro servidor con una sola GPU. En el modo Docker remoto, todas las rutas del sistema de archivos local en las especificaciones se interpretan en el host Docker remoto, no en la máquina del agente.

Comprobación previa

El flujo de trabajo debe verificar el entorno de ejecución de la GPU del host antes de iniciar los trabajos de Docker. Si la comprobación falla, se le pedirá al usuario que apruebe la instalación, que ejecute el comando de instalación mostrado y que vuelva a ejecutar la comprobación previa.

# 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 falla una comprobación, el agente solicita al usuario que autorice la instalación o la corrección a través de Bash antes de continuar. Los requisitos de Python instalables mediante pip y la creación de la red de Docker mencionados anteriormente son excepciones: instálalos o créalos automáticamente y, a continuación, vuelve a ejecutar la comprobación previa.

Credenciales

No se requieren credenciales de la plataforma más allá del acceso al daemon de Docker.

Entorno opcional:

• DOCKER_HOST: URL opcional del daemon de Docker. Si no se establece, el SDK utiliza la resolución de entorno/socket predeterminada del cliente de Python de Docker. Requerido para la remote-docker opción de plataforma.
• DOCKER_NETWORK: Red de Docker para los contenedores de tareas. El valor por defecto es tao_default.
• DOCKER_USERNAME: Nombre de usuario del registro. El valor por defecto es $oauthtoken para NGC.
• NGC_KEY: Se utiliza al descargar imágenes privadas desde nvcr.io.
• HOST_SSH_PATH: Se monta en los contenedores «brain» de AutoML cuando estos necesitan claves SSH para supervisar trabajos secundarios remotos de SLURM.
• ACCESS_KEY, SECRET_KEY, S3_ENDPOINT_URL, S3_BUCKET_NAME: Configuración opcional de almacenamiento compatible con S3 para trabajos que siguen leyendo/escribiendo en el almacenamiento en la nube desde un contenedor local.

Comprobación previa al inicio

Antes de generar scripts o iniciar contenedores:

1. Comprueba que se pueda acceder al daemon de Docker, que NVIDIA Container Toolkit esté registrado como entorno de ejecución de Docker, que se informen de las GPU y la versión del controlador, y que un contenedor de prueba pueda detectar las GPU antes del inicio. Para Docker remoto, consulta las GPU a través docker run ... nvidia-smi el daemon remoto; no utilices nvidia-smi desde la máquina agente.
2. Comprueba que todas las anotaciones de los conjuntos de datos locales o de archivos y todas las rutas de los archivos multimedia existan en el host de Docker.
3. Para s3:// conjuntos de datos y resultados, comprueba ACCESS_KEY que SECRET_KEY están configurados y que las rutas exactas sean legibles con aws s3 ls. Si aws falta, informa de la dependencia que falta y pregunta antes de instalarla; vuelve a ejecutar la comprobación previa tras la instalación.
4. Comprueba las credenciales específicas del modelo, como HF_TOKEN antes de iniciar la aplicación.
5. Comprueba la ocupación actual de las GPU con nvidia-smi y evita las GPU que ya estén siendo utilizadas por otros trabajos en ejecución cuando el usuario haya solicitado esa restricción. Muestra los ID de las GPU seleccionadas en la revisión de lanzamiento.
6. Para combinaciones de modelos y contenedores con límites de arquitectura conocidos, compara la capacidad de cálculo de la GPU del host con la pila del contenedor antes del inicio. Si la imagen seleccionada no puede realizar compilación JIT ni ejecutar kernels para la arquitectura del host, bloquea el proceso de forma temprana y solicita una imagen o plataforma compatible.

Utilice la herramienta de ayuda incluida para estas comprobaciones siempre que sea posible:

${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 un daemon de Docker remoto, utiliza la remote-docker plataforma y pase o exporte DOCKER_HOST. La herramienta auxiliar verifica la disponibilidad de la GPU y el entorno de ejecución remotos y comprueba las rutas de los conjuntos de datos del host remoto mediante montajes de enlace de solo lectura:

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

Los --path valores anteriores deben existir en el host de Docker remoto. No pases rutas que solo existan en el portátil local o en el host de Codex.

Multigpu y multinodo

La configuración multinodo no es compatible con Docker local. Un trabajo se ejecuta en el host del daemon de Docker local sin coordinación entre hosts.

La compatibilidad con múltiples GPU en el host local se ofrece mediante el indicador --gpus (--gpus all o --gpus '"device=0,1,2,3"'). DockerSDK.create_job(gpu_count=N) se transmite a --gpus). La inicialización distribuida en un único host utiliza localhost; torchrun --nproc-per-node=N o el DDP de PyTorch funciona como de costumbre.

Detalles del backend

Utiliza el valor del backend del SDK local-docker. El esquema del backend local no tiene detalles adicionales, por lo que la mayor parte del enrutamiento se controla mediante parámetros de entorno y de trabajo :

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

Siguiendo el diseño del SDK de Brev, los valores de la plataforma y del plano de control permanecen en el estado del SDK y en las etiquetas de Docker. El SDK no inyecta BACKEND, HOST_PLATFORM, MONGOSECRET, DOCKER_HOSTni DOCKER_NETWORK en el contenedor de entrenamiento.

Ejecución del contenedor

El gestor local de Docker del SDK de TAO inicia los contenedores a través del cliente de Docker en Python :

• El nombre del trabajo de backend utiliza el tao-job- formato utilizado por los controladores del SDK.
• El comando suele ser ["/bin/bash", "-c", ""].
• Los contenedores se ejecutan de forma independiente. El SDK mantiene los contenedores de forma predeterminada, de modo que el estado y los registros siguen siendo consultables, a menos que DOCKER_AUTO_REMOVE=true.
• /dev/shm esté montado como tmpfs.
• La red de Docker configurada la aplica el demonio de Docker al contenedor del trabajo ; no se transmite como variable de entorno del proceso.
• Los contenedores existentes con el mismo ID de trabajo se detienen y se eliminan antes de que comience uno de sustitución.

Para el acceso a la GPU, el controlador detecta automáticamente el tipo de host:

• Los hosts Tegra o Jetson utilizan runtime="nvidia" además NVIDIA_VISIBLE_DEVICES y NVIDIA_DRIVER_CAPABILITIES=all.
• los hosts x86 estándar utilizan Docker device_requests con capacidades de GPU.

Si num_gpus es 0, no se asignan GPU. Si num_gpus es -1, se solicitan todas las GPU visibles. Se recomienda especificar el número exacto de GPU en máquinas de desarrollo compartidas. Cuando se disponga de identificadores de dispositivo explícitos, se recomienda utilizarlos en lugar de la selección basada únicamente en el recuento en máquinas compartidas, para que el inicio no acapare las GPU ocupadas por otras tareas.

Almacenamiento

Docker local acepta rutas locales y file:// rutas locales, ya que el contenedor se ejecuta en el mismo host de Docker. Asegúrate de que cada ruta de la especificación esté:

• esté montada en el contenedor por el gestor o el servicio circundante,
• ya sea accesible desde el interior del contenedor, o
• una URI en la nube con las credenciales adecuadas.

En el caso de sistemas de archivos remotos o compartidos, da prioridad a la plataforma propietaria de dicho sistema de archivos. Por ejemplo, utiliza SLURM junto con lustre:///... para las rutas de Lustre en un clúster.

Supervisión

• El controlador del SDK asigna directamente el estado del contenedor de Docker: creado -> Pendiente, en ejecución/reiniciándose -> En ejecución, en pausa -> En pausa, código de salida 0 -> Completo, código de salida distinto de cero -> Error.
• Los registros proceden directamente del contenedor en cuestión a través del cliente Python de Docker (docker logs tao-job-).

Si el contenedor se ha cerrado, se ha bloqueado, se está eliminando o no se encuentra, la reconciliación de estado considera que el proceso de fondo se ha terminado.

Cancelación

La cancelación detiene el contenedor especificado. La gestión de la GPU corre a cargo de Docker / el entorno de ejecución de NVIDIA, no del gestor de GPU local de TAO Core.

Opcional: a través del SDK de TAO

Si deseas obtener identificadores de trabajo, envoltura de E/S de S3 a través del SDK script_runner, o la durabilidad entre sesiones:

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)

Esto envuelve la misma docker run invocación bajo un Job identificador y redirige el punto de entrada a través de script_runner de modo que inputs/outputs se descarguen desde / se suban a S3 automáticamente. Si no necesitas esas funciones, simplemente utiliza docker run directamente; no es necesario instalar ningún SDK.

Modos de fallo

Cliente de Docker no inicializado: comprueba que el paquete de Docker para Python esté instalado, configura DOCKER_HOST si no estás utilizando el socket local predeterminado y confirma que el proceso pueda comunicarse con el daemon.

Error en la asignación de GPU: las GPU solicitadas no están disponibles, el NVIDIA Container Toolkit no está configurado o el daemon de Docker no puede crear solicitudes de dispositivos GPU. Utiliza menos GPU, espera a que finalice otro trabajo o comprueba docker run --gpus ... funciona en el host.

Error de autenticación al descargar la imagen: Establece una NGC_KEY para las nvcr.io o ejecuta docker login nvcr.io -u '$oauthtoken' en el host de Docker.

El contenedor se cerró inesperadamente: comprueba docker logs tao-job-, la configuración DOCKER_NETWORKy el comando generado por el ejecutor de acciones del SDK.

Ruta no encontrada dentro del contenedor: una ruta local del host no tiene por qué estar montada en el contenedor del trabajo. Utilice una convención de rutas compatible con el ejecutor de acciones o configure un volumen explícito a través del servicio envolvente.