Краткое руководство по Docker для Ultralytics#

Это руководство представляет собой подробное введение в настройку среды Docker для твоих проектов Ultralytics. Docker — это платформа для разработки, доставки и запуска приложений в контейнерах. Она особенно полезна для обеспечения одинаковой работы программного обеспечения независимо от места его развертывания. Подробнее см. в репозитории Ultralytics Docker на Docker Hub.

Чему ты научишься#

• Настройка Docker с поддержкой NVIDIA
• Установка образов Ultralytics Docker
• Запуск Ultralytics в контейнере Docker с поддержкой CPU или GPU
• Использование сервера дисплея с Docker для отображения результатов детектирования Ultralytics
• Монтирование локальных каталогов в контейнер

Предварительные требования#

• Убедись, что Docker установлен в твоей системе. Если нет, скачай и установи его с веб-сайта Docker.
• Для ускорения на GPU убедись, что в твоей системе установлен GPU NVIDIA и драйверы NVIDIA. Образы для CPU не требуют оборудования NVIDIA.
• Если ты используешь устройства NVIDIA Jetson, убедись, что установлена подходящая версия JetPack. Подробнее см. в руководстве по NVIDIA Jetson.

Настройка Docker с поддержкой NVIDIA (необязательно)#

Сначала проверь правильность установки драйверов NVIDIA, выполнив:

nvidia-smi

Установка NVIDIA Container Toolkit#

Теперь установим NVIDIA Container Toolkit, чтобы включить поддержку GPU в контейнерах Docker:

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
    | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update

sudo apt-get install -y nvidia-container-toolkit

Проверка устройств CDI с помощью Docker#

Выполни nvidia-ctk cdi list, чтобы убедиться в доступности устройств GPU CDI (служба nvidia-cdi-refresh из набора инструментов автоматически создает спецификацию и поддерживает ее в актуальном состоянии в toolkit >= 1.18):

nvidia-ctk cdi list

Ты должен увидеть такие записи, как nvidia.com/gpu=0 и nvidia.com/gpu=all. Обнаруженные устройства CDI также отображаются в docker info.

Установка образов Ultralytics Docker#

Ultralytics публикует следующие образы на Docker Hub. Каждый образ собирается из связанного с ним Dockerfile рабочим процессом публикации Docker.

Образы GPU AMD64 (latest, latest-export и latest-runner) используют PyTorch 2.14 и CUDA 13.2. Проверь поддержку CUDA драйвером хоста с помощью nvidia-smi перед их запуском; установка более нового контейнера не обновляет драйвер хоста. CUDA 13 прекращает поддержку GPU архитектур Maxwell, Pascal и Volta, включая Tesla P100 и V100. См. примечания к выпуску CUDA от NVIDIA и требования к совместимости драйверов.

Образ NVIDIA ARM64 использует NVIDIA PyTorch 26.08 с CUDA 13.4 и TensorRT 11.2. Поддержка PyTorch для Thor не распространяется на TensorRT: NVIDIA не поддерживает TensorRT 11.2 на JetPack. Для экспорта Jetson TensorRT используй поддерживаемую среду выполнения TensorRT 10.x для своего выпуска JetPack. Следуй системным требованиям в руководстве по Jetson или руководстве по DGX Spark. Образы JetPack 4, 5 и 6 сохраняют свои отдельные стеки для конкретных устройств.

Dockerfile для Conda доступен для локальных сборок; автоматическая публикация latest-conda отключена, поэтому этот тег реестра не содержит данных обновлений.

Используй latest-python-export для экспорта LiteRT. Образ GPU latest-export сохраняет PyTorch 2.14 и не включает LiteRT, так как его текущая зависимость требует PyTorch ниже 2.14.

Теги, начинающиеся с latest, соответствуют последней опубликованной сборке основной ветки. В тегах с указанием версии префикс latest заменяется на релиз Ultralytics, например VERSION, VERSION-cpu или VERSION-jetson-jetpack6. Для воспроизводимой среды используй тег с указанием версии.

Чтобы загрузить последний образ:

# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latest

Чтобы вместо этого самостоятельно собрать образ, клонируй репозиторий и передай соответствующий Dockerfile из таблицы выше, используя корень репозитория в качестве контекста сборки:

# Build the CPU image locally from docker/Dockerfile-cpu
sudo docker build -t ultralytics/ultralytics:latest-cpu -f docker/Dockerfile-cpu .

Запуск Ultralytics в контейнере Docker#

Вот как запустить контейнер Ultralytics Docker:

Использование только CPU#

# Run without GPU
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpu

Использование GPU#

# Run with all GPUs
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest

# Run specifying which GPUs to use
sudo docker run -it --ipc=host --device nvidia.com/gpu=2 --device nvidia.com/gpu=3 ultralytics/ultralytics:latest

Флаг -it выделяет псевдотерминал и оставляет stdin открытым, позволяя тебе взаимодействовать с контейнером. Флаг --ipc=host включает совместное использование пространства имен IPC хоста, необходимое для обмена памятью между процессами. Флаг --device nvidia.com/gpu=... предоставляет контейнеру доступ к GPU хоста через CDI.

Примечание о доступности файлов#

Чтобы работать с файлами на локальном компьютере внутри контейнера, ты можешь использовать тома Docker:

# Mount a local directory into the container
sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

Замени /path/on/host путем к каталогу на локальном компьютере, а /path/in/container — нужным путем внутри контейнера Docker.

Сохранение результатов обучения#

По умолчанию результаты обучения сохраняются в /ultralytics/runs/<task>/<name>/ внутри контейнера. Без монтирования каталога хоста результаты будут потеряны при удалении контейнера.

Чтобы сохранить результаты обучения:

# Recommended: mount workspace and specify project path
sudo docker run --rm -it -v "$(pwd)":/w -w /w ultralytics/ultralytics:latest \
  yolo train model=yolo26n.pt data=coco8.yaml project=/w/runs

Все результаты обучения будут сохранены в ./runs на твоем хост-компьютере.

Запуск приложений графического интерфейса пользователя (GUI) в контейнере Docker#

Docker в основном используется для контейнеризации фоновых приложений и программ CLI, но он также может запускать графические программы. В мире Linux два основных графических сервера отвечают за отображение графики: X11 (также известен как оконная система X) и Wayland. Перед началом важно определить, какой графический сервер используется в данный момент. Выполни эту команду, чтобы узнать:

env | grep -E -i 'x11|xorg|wayland'

Настройка и конфигурация сервера дисплея X11 или Wayland выходят за рамки этого руководства. Если приведенная выше команда ничего не возвращает, сначала нужно настроить один из них в своей системе, прежде чем продолжить.

Запуск контейнера Docker с GUI#

xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v ~/.Xauthority:/root/.Xauthority \
  -it --ipc=host ultralytics/ultralytics:latest

Использование Docker с GUI#

Теперь ты можешь отображать графические приложения внутри контейнера Docker. Например, выполни следующую команду CLI, чтобы визуализировать предсказания модели YOLO26:

yolo predict model=yolo26n.pt show=True

После завершения работы с GUI Docker#

xhost -local:docker

Теперь ты настроил Ultralytics для работы с Docker и готов воспользоваться всеми его возможностями. Чтобы развернуть веб-приложение Ultralytics самостоятельно, см. руководство по локальному развертыванию платформы. Альтернативные способы установки пакета Python описаны в документации по быстрому началу работы с Ultralytics.

Часто задаваемые вопросы#