Локальный Docker

Одноузловая платформа выполнения, на которой задания TAO запускаются в виде именованных контейнеров Docker на демоне Docker. Демон может быть локальным на хосте агента или удаленным через DOCKER_HOST=ssh://user@host / контекста Docker. Это удобно для разработки, отладки, небольших запусков и рабочих процессов, в которых локальный агент-программист отправляет задания на удалённый сервер с GPU.

Используйте локальный Docker, если данные находятся локально на хосте Docker или доступны через смонтированные тома/учетные данные облачного сервиса. Не используйте его для планирования задач в удаленном кластере, обучения на нескольких узлах или заданий, требующих использования очередей SLURM.

Используйте удалённый Docker, когда агент работает на рабочей станции или ноутбуке, но демон Docker и графические процессоры находятся на другом сервере с одним графическим процессором. В режиме удалённого Docker все пути к локальной файловой системе в спецификациях интерпретируются на удалённом хосте Docker, а не на машине агента.

Предварительная проверка

Рабочий процесс должен проверить среду выполнения GPU хоста перед запуском заданий Docker. Если проверка завершится сбоем, предложите пользователю утвердить установку, выполните выведенную команду установки и повторно запустите предварительную проверку.

# 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

Если проверка завершилась неудачно, агент запрашивает у пользователя разрешение на установку/исправление через Bash перед продолжением работы. Исключениями являются требования Python, устанавливаемые с помощью pip, и создание сети Docker, описанное выше: их следует установить/создать автоматически, а затем повторно запустить предварительную проверку.

Учетные данные

Помимо доступа к демону Docker учетные данные платформы не требуются.

Необязательная переменная среды:

• DOCKER_HOST: Необязательный URL-адрес демона Docker. Если не задан, SDK использует стандартную среду клиента Docker для Python или разрешение сокетов по умолчанию. Требуется для remote-docker платформы.
• DOCKER_NETWORK: сеть Docker для контейнеров заданий. По умолчанию tao_default.
• DOCKER_USERNAME: имя пользователя в реестре. По умолчанию $oauthtoken для NGC.
• NGC_KEY: Используется при извлечении частных образов из nvcr.io.
• HOST_SSH_PATH: монтируется в контейнеры «мозга» AutoML, когда им требуются SSH-ключи для мониторинга удалённых дочерних заданий SLURM.
• ACCESS_KEY, SECRET_KEY, S3_ENDPOINT_URL, S3_BUCKET_NAME: Необязательные настройки хранилища, совместимого с S3, для заданий, которые по-прежнему осуществляют чтение/запись в облачное хранилище из локального контейнера.

Предварительная проверка запуска

Перед генерацией скриптов или запуском контейнеров:

1. Убедитесь, что демонический процесс Docker доступен, NVIDIA Container Toolkit зарегистрирован в качестве среды выполнения Docker, отображаются данные о графических процессорах и версии драйвера, а тестовый контейнер может обнаруживать графические процессоры перед запуском. Для удаленного Docker запрашивайте графические процессоры через docker run ... nvidia-smi удаленного демона; не используйте локальный nvidia-smi с машины-агента.
2. Убедитесь, что все аннотации локальных/файловых наборов данных и пути к мультимедиа существуют на хосте Docker.
3. Для s3:// наборов данных/результатов убедитесь, что ACCESS_KEY и SECRET_KEY заданы и точные пути доступны для чтения с помощью aws s3 ls. Если aws отсутствует, сообщите об отсутствующей зависимости и спросите, нужно ли её устанавливать; после установки запустите проверку заново.
4. Проверьте учетные данные, специфичные для модели, такие как HF_TOKEN перед запуском.
5. Проверьте текущую загрузку графических процессоров с помощью nvidia-smi и избегайте GPU, уже используемых другими запущенными заданиями, если пользователь указал это ограничение. Отображайте идентификаторы выбранных GPU в обзоре запуска.
6. Для комбинаций моделей и контейнеров с известными ограничениями архитектуры сравнивайте вычислительную способность графического процессора хоста со стеком контейнера перед запуском. Если выбранный образ не может выполнять JIT-компиляцию или запускать ядра для архитектуры хоста, заблокируйте запуск на ранней стадии и запросите совместимый образ или платформу.

По возможности используйте встроенную вспомогательную программу для этих проверок:

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

Для удалённого демона Docker используйте remote-docker platform и передавайте или экспортируйте DOCKER_HOST. Вспомогательная программа проверяет готовность удалённого GPU/среды выполнения и проверяет пути к наборам данных на удалённом хосте через привязки только для чтения:

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

Указанные --path указанные выше значения должны существовать на удалённом хосте Docker. Не передавайте пути, которые существуют только на локальном ноутбуке или хосте Codex.

Работа с несколькими графическими процессорами и на нескольких узлах

Работа с несколькими узлами не поддерживается в локальном Docker. Одно задание выполняется на хосте локального демона Docker без межхостовой координации.

Поддержка нескольких графических процессоров на локальном хосте обеспечивается с помощью флага --gpus (--gpus all или --gpus '"device=0,1,2,3"'). DockerSDK.create_job(gpu_count=N) проходит через --gpus. Распределённая инициализация на одном хосте использует localhost; torchrun --nproc-per-node=N или DDP в PyTorch работают как обычно.

Сведения о бэкенде

Используйте значение бэкенда SDK local-docker. Локальная схема бэкэнда не содержит дополнительных сведений о бэкэнде, поэтому большая часть маршрутизации контролируется параметрами среды и задания :

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

В соответствии с архитектурой SDK Brev значения платформы/управляющей плоскости сохраняются в состоянии SDK и метках Docker. SDK не вставляет BACKEND, HOST_PLATFORM, MONGOSECRET, DOCKER_HOST, или DOCKER_NETWORK в контейнер обучения.

Выполнение контейнера

Локальный обработчик Docker в TAO SDK запускает контейнеры через Python-клиент Docker :

• В имени задания бэкэнда используется tao-job- форма, используемая обработчиками SDK.
• Команда обычно имеет вид ["/bin/bash", "-c", ""].
• Контейнеры запускаются в отключенном режиме. По умолчанию SDK сохраняет контейнеры, поэтому статус и журналы остаются доступными для просмотра, если DOCKER_AUTO_REMOVE=true.
• /dev/shm не смонтирована в виде tmpfs.
• Настроенная сеть Docker применяется демоном Docker для контейнера задания ; она не передаётся в качестве переменной среды процесса.
• Существующие контейнеры с тем же идентификатором задания останавливаются и удаляются до того, как запустится новый контейнер.

Для доступа к GPU обработчик автоматически определяет тип хоста:

• Хосты Tegra или Jetson используют runtime="nvidia" плюс NVIDIA_VISIBLE_DEVICES , а NVIDIA_DRIVER_CAPABILITIES=all.
• Стандартные хосты x86 используют Docker device_requests с поддержкой GPU.

Если num_gpus значение равно 0, то графические процессоры не назначаются. Если num_gpus значение равно -1, запрашиваются все видимые графические процессоры. На общих машинах для разработки следует отдавать предпочтение явному указанию количества графических процессоров. При наличии явных идентификаторов устройств следует отдавать им предпочтение перед выбором только по количеству на общих машинах, чтобы запуск не захватывал графические процессоры, занятые другими задачами.

Хранение

Docker Local поддерживает как локальные, так и file:// пути, поскольку контейнер работает на том же хосте Docker. Убедитесь, что каждый путь в спецификации либо:

• смонтирован в контейнер обработчиком или окружающей службой,
• уже доступен изнутри контейнера, либо
• является облачным URI с соответствующими учетными данными.

Для удалённых/общих файловых систем отдавайте предпочтение платформе, которой принадлежит данная файловая система. Например, используйте SLURM в сочетании с lustre:///... для путей Lustre в кластере.

Мониторинг

• Обработчик SDK напрямую сопоставляет состояния контейнеров Docker: создан -> В ожидании, запущен/перезапускается -> Работает, приостановлен -> Приостановлен, код завершения 0 -> Завершено, код завершения, отличный от нуля -> Ошибка.
• Журналы поступают напрямую из указанного контейнера через Python-клиент Docker (docker logs tao-job-).

если контейнер завершил работу, вышел из строя, удаляется или не может быть найден, при синхронизации состояний бэкенд-процесс рассматривается как завершённый.

Отмена

Отмена останавливает указанный контейнер. Управление владением GPU осуществляется Docker / средой выполнения NVIDIA, а не локальным менеджером GPU TAO Core.

Дополнительно: через TAO SDK

Если вам нужны дескрипторы заданий, обертка ввода-вывода S3 через script_runnerили сохранение данных между сессиями:

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)

Это обертывает тот же docker run вызов под Job дескриптор и направляет точку входа через script_runner , так что inputs/outputs загружались из / загружались в S3 автоматически. Если вам это не нужно, просто используйте docker run непосредственно — установка SDK не требуется.

Возможные ошибки

Клиент Docker не инициализирован: убедитесь, что установлен пакет Docker для Python, установите DOCKER_HOST , если вы не используете локальный сокет по умолчанию, и убедитесь, что процесс может взаимодействовать с демоном.

Ошибка при назначении графических процессоров: запрашиваемые графические процессоры недоступны, NVIDIA Container Toolkit не настроен или демон Docker не может создавать запросы на устройства графических процессоров. Используйте меньшее количество графических процессоров, дождитесь завершения другого задания или проверьте, docker run --gpus ... работает на хосте.

Ошибка авторизации при загрузке образа: Укажите действительный NGC_KEY для частных nvcr.io образов или запустите docker login nvcr.io -u '$oauthtoken' на хосте Docker.

Контейнер неожиданно завершил работу: проверьте docker logs tao-job-, настроенные параметры DOCKER_NETWORKи команду, сгенерированную средством выполнения действий SDK.

Отсутствует путь внутри контейнера: локальный путь на хосте не обязательно монтируется в контейнер задания. Используйте соглашение об именовании путей, поддерживаемое средством выполнения действий, или настройте явный том через окружающую службу.