Руководство по быстрому запуску Docker для Ultralytics#
Это руководство служит подробным введением в настройку среды Docker для твоих проектов Ultralytics. Docker — это платформа для разработки, поставки и запуска приложений в контейнерах. Она особенно полезна для обеспечения одинаковой работы программного обеспечения независимо от места его развертывания. Дополнительные сведения см. в репозитории Ultralytics Docker на Docker Hub.
Чему ты научишься#
- Настройка Docker с поддержкой NVIDIA
- Установка Docker-образов Ultralytics
- Запуск Ultralytics в контейнере Docker с поддержкой CPU или GPU
- Использование графического сервера с Docker для отображения результатов детектирования Ultralytics
- Монтирование локальных каталогов в контейнер
Watch: How to Get started with Docker | Usage of Ultralytics Python Package inside Docker live demo 🎉
Предварительные требования#
- Убедись, что на твоей системе установлен 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Обнови списки пакетов и установи NVIDIA Container Toolkit:
sudo apt-get updatesudo apt-get install -y nvidia-container-toolkitПроверь CDI-устройства с помощью Docker#
Запусти nvidia-ctk cdi list, чтобы убедиться в доступности устройств CDI GPU (служба nvidia-cdi-refresh в toolkit автоматически генерирует и поддерживает спецификацию на версиях toolkit >= 1.18):
nvidia-ctk cdi listТы должен увидеть записи вроде nvidia.com/gpu=0 и nvidia.com/gpu=all. Обнаруженные устройства CDI также отображаются в docker info.
Установка Docker-образов Ultralytics#
Ultralytics публикует следующие образы на Docker Hub. Каждый образ собирается из связанного с ним Dockerfile с помощью рабочего процесса публикации Docker.
| Тег | Платформа и назначение | Источник |
|---|---|---|
latest | Linux AMD64 с CUDA для обучения и инференса на GPU | Dockerfile |
latest-export | Linux AMD64 с CUDA и зависимостями экспорта для конвертации и бенчмаркинга | Dockerfile-export |
latest-python | Легковесный образ Linux AMD64 Python для инференса на CPU | Dockerfile-python |
latest-python-export | Образ Linux AMD64 CPU с зависимостями экспорта | Dockerfile-python-export |
latest-cpu | Образ Linux AMD64 CPU с Bash в качестве команды по умолчанию | Dockerfile-cpu |
latest-jupyter | Образ Linux AMD64 CPU с JupyterLab и обучающими ноутбуками Ultralytics | Dockerfile-jupyter |
latest-arm64 | Образ Linux ARM64 CPU для Apple silicon, Raspberry Pi и других систем ARM64 | Dockerfile-arm64 |
latest-nvidia-arm64 | Linux ARM64 с поддержкой GPU NVIDIA для Jetson AGX Thor, DGX Spark, JetPack 7 и DGX OS | Dockerfile-nvidia-arm64 |
latest-jetson-jetpack6 | Linux ARM64 для устройств NVIDIA Jetson под управлением JetPack 6 | Dockerfile-jetson-jetpack6 |
latest-jetson-jetpack5 | Linux ARM64 для устройств NVIDIA Jetson под управлением JetPack 5 | Dockerfile-jetson-jetpack5 |
latest-jetson-jetpack4 | Linux ARM64 для устройств NVIDIA Jetson под управлением JetPack 4 | Dockerfile-jetson-jetpack4 |
latest-runner | Образ Linux AMD64 CUDA для self-hosted GPU-раннера GitHub Actions | Dockerfile-runner |
latest-runner-cpu | Образ Linux AMD64 для self-hosted CPU-раннера GitHub Actions | Dockerfile-runner-cpu |
Теги, начинающиеся с latest, отслеживают самую последнюю опубликованную сборку ветки main. Версионированные теги заменяют префикс 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 назначает псевдо-TTY и оставляет открытым стандартный ввод, позволяя взаимодействовать с контейнером. Флаг --ipc=host разрешает совместное использование пространства имен IPC хоста, что необходимо для обмена памятью между процессами. Флаг --device nvidia.com/gpu=... предоставляет контейнеру доступ к GPU хоста через CDI.
В Linux запросы устройств CDI требуют Docker >= 28.2.0 (CDI включен по умолчанию) и nvidia-container-toolkit >= 1.18 (автоматическая генерация спецификаций CDI). Обнови старые хосты Linux перед запуском контейнеров с GPU. Устаревший флаг --gpus all может потерять доступ к GPU (Failed to initialize NVML: Unknown Error), когда хост перезагружает systemd во время плановых обновлений пакетов (nvidia-container-toolkit#48). Запросы CDI --device включают узлы устройств в конфигурацию контейнера, поэтому долго работающие контейнеры, такие как обучающие воркеры или CI-раннеры, сохраняют доступ к GPU после перезагрузок.
Поддержка GPU в Docker Desktop на Windows в настоящее время использует --gpus all с бэкендом WSL 2, поскольку устройства NVIDIA CDI там недоступны. В Windows не используется Linux systemd, поэтому указанная выше ошибка перезагрузки демона неприменима.
Примечание о доступности файлов#
Чтобы работать с файлами на твоем локальном компьютере внутри контейнера, ты можешь использовать тома 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#
Следующие инструкции носят экспериментальный характер. Совместное использование сокета X11 с контейнером Docker создает потенциальные риски безопасности. Поэтому рекомендуется тестировать это решение только в контролируемой среде. Дополнительную информацию см. в этих ресурсах по использованию xhost(1)(2).
Docker в основном используется для контейнеризации фоновых приложений и программ CLI, но он также может запускать графические программы. В мире Linux два основных графических сервера обрабатывают графический вывод: X11 (также известный как X Window System) и Wayland. Перед началом работы важно определить, какой графический сервер ты используешь в данный момент. Выполни эту команду, чтобы узнать:
env | grep -E -i 'x11|xorg|wayland'Настройка и конфигурирование графического сервера X11 или Wayland выходит за рамки этого руководства. Если приведенная выше команда ничего не возвращает, тебе нужно будет начать с того, чтобы заставить один из них работать в твоей системе, прежде чем продолжать.
Запуск контейнера Docker с GUI#
Использовать GPU
Если ты используешь GPU, ты можешь добавить флаг --device nvidia.com/gpu=all к команде.
Если ты используешь X11, ты можешь выполнить следующую команду, чтобы разрешить контейнеру Docker доступ к сокету X11:
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Эта команда устанавливает переменную окружения DISPLAY на дисплей хоста, монтирует сокет X11 и сопоставляет файл .Xauthority с контейнером. Команда xhost +local:docker позволяет контейнеру Docker получить доступ к серверу X11.
Использование Docker с GUI#
Теперь ты можешь отображать графические приложения внутри своего контейнера Docker. Например, ты можешь запустить следующую команду CLI для визуализации предсказаний от модели YOLO26:
yolo predict model=yolo26n.pt show=TrueТестирование
Простой способ проверить, есть ли у группы Docker доступ к серверу X11 — запустить контейнер с программой GUI, такой как xclock или xeyes. Кроме того, ты можешь установить эти программы в контейнер Ultralytics Docker, чтобы проверить доступ к серверу X11 твоего дисплейного сервера GNU-Linux. Если у тебя возникли проблемы, попробуй установить переменную окружения -e QT_DEBUG_PLUGINS=1. Установка этой переменной окружения включает вывод отладочной информации, что помогает в процессе поиска и устранения неисправностей.
Когда закончишь работу с GUI в Docker#
В обоих случаях не забудь отозвать доступ у группы Docker, когда закончишь.
xhost -local:dockerХочешь просматривать результаты изображений прямо в терминале?
Ознакомься со следующим руководством по просмотру результатов изображений с помощью терминала
Теперь у тебя все настроено для использования Ultralytics с Docker, и ты готов воспользоваться его возможностями. Чтобы развернуть веб-приложение Ultralytics на собственном сервере, см. руководство по платформе On-Premise. О других методах установки пакета Python см. в документации по быстрому старту Ultralytics.
FAQ#
Чтобы настроить Ultralytics с Docker, сначала убедись, что Docker установлен на твоей системе. Если у тебя есть GPU NVIDIA, установи NVIDIA Container Toolkit, чтобы включить поддержку GPU. Затем загрузи последний образ Ultralytics Docker с Docker Hub с помощью следующей команды:
sudo docker pull ultralytics/ultralytics:latestДля получения подробных шагов обратись к нашему руководству по быстрому запуску Docker.
Использование образов Ultralytics Docker обеспечивает одинаковую среду на разных компьютерах, воспроизводя те же программные компоненты и зависимости. Это особенно полезно для совместной работы в командах, запуска моделей на различном оборудовании и поддержания воспроизводимости. Используй
latestдля общего обучения на GPU NVIDIA или выбери образ, соответствующий твоей версии JetPack для устройства NVIDIA Jetson. См. полную таблицу образов или изучи Ultralytics Docker Hub.Сначала убедись, что NVIDIA Container Toolkit установлен и настроен. Затем используй следующую команду для запуска Ultralytics YOLO с поддержкой GPU:
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest # all GPUsЭта команда настраивает контейнер Docker с доступом к GPU. Дополнительные подробности см. в руководстве по быстрому запуску Docker.
Чтобы визуализировать результаты предсказаний YOLO с помощью GUI в контейнере Docker, тебе нужно разрешить Docker доступ к твоему графическому серверу. Для систем под управлением X11 команда выглядит так:
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Для систем под управлением Wayland используй:
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \ --net=host -it --ipc=host ultralytics/ultralytics:latestБолее подробную информацию можно найти в разделе Запуск приложений с графическим интерфейсом (GUI) в контейнере Docker.
Да, ты можешь подключать локальные директории в контейнер Ultralytics Docker с помощью флага
-v: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— на желаемый путь внутри контейнера. Эта настройка позволяет работать с локальными файлами внутри контейнера. Дополнительные сведения см. в разделе Примечание о доступности файлов.