Guide de démarrage rapide de Docker pour Ultralytics#
Ce guide sert d'introduction complète à la configuration d'un environnement Docker pour tes projets Ultralytics. Docker est une plateforme permettant de développer, de distribuer et d'exécuter des applications dans des conteneurs. C'est particulièrement utile pour garantir que le logiciel s'exécutera toujours de la même manière, peu importe l'endroit où il est déployé. Pour plus de détails, visite le dépôt Docker d'Ultralytics sur Docker Hub.
Ce que tu vas apprendre#
- Configuration de Docker avec le support NVIDIA
- Installation des images Docker d'Ultralytics
- Exécution d'Ultralytics dans un conteneur Docker avec support CPU ou GPU
- Utilisation d'un serveur d'affichage avec Docker pour montrer les résultats de détection d'Ultralytics
- Montage de répertoires locaux dans le conteneur
Watch: How to Get started with Docker | Usage of Ultralytics Python Package inside Docker live demo 🎉
Prérequis#
- Assure-toi que Docker est installé sur ton système. Si ce n'est pas le cas, tu peux le télécharger et l'installer depuis le site web de Docker.
- Pour l'accélération par GPU, assure-toi que ton système dispose d'un GPU NVIDIA et que les pilotes NVIDIA sont installés. Les images CPU ne nécessitent pas de matériel NVIDIA.
- Si tu utilises des appareils NVIDIA Jetson, assure-toi d'avoir installé la version de JetPack appropriée. Consulte le guide NVIDIA Jetson pour plus de détails.
Configuration de Docker avec prise en charge NVIDIA (Optionnel)#
Tout d'abord, vérifie que les pilotes NVIDIA sont correctement installés en exécutant :
nvidia-smiInstallation du NVIDIA Container Toolkit#
Maintenant, installons le NVIDIA Container Toolkit pour activer la prise en charge des GPU dans les conteneurs 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.listMets à jour les listes de paquets et installe le NVIDIA Container Toolkit :
sudo apt-get updatesudo apt-get install -y nvidia-container-toolkitVérifie tes périphériques CDI avec Docker#
Exécute nvidia-ctk cdi list pour t'assurer que les périphériques CDI du GPU sont disponibles (le service nvidia-cdi-refresh de la boîte à outils génère et maintient automatiquement la spécification sur les versions de la boîte à outils >= 1.18) :
nvidia-ctk cdi listTu devrais voir des entrées telles que nvidia.com/gpu=0 et nvidia.com/gpu=all. Les périphériques CDI découverts apparaissent également dans docker info.
Installation des images Docker d'Ultralytics#
Ultralytics publie les images suivantes sur Docker Hub. Chaque image est construite à partir de son fichier Dockerfile lié par le flux de publication Docker.
| Tag | Plateforme et objectif | Source |
|---|---|---|
latest | Linux AMD64 avec CUDA pour l'entraînement et l'inférence GPU | Dockerfile |
latest-export | Linux AMD64 avec CUDA et dépendances d'exportation pour la conversion et le benchmarking | Dockerfile-export |
latest-python | Image légère Linux AMD64 Python pour l'inférence CPU | Dockerfile-python |
latest-python-export | Image Linux AMD64 CPU avec dépendances d'exportation | Dockerfile-python-export |
latest-cpu | Image Linux AMD64 CPU avec Bash comme commande par défaut | Dockerfile-cpu |
latest-jupyter | Image Linux AMD64 CPU avec JupyterLab et les notebooks de tutoriel Ultralytics | Dockerfile-jupyter |
latest-arm64 | Image CPU Linux ARM64 pour Apple silicon, Raspberry Pi et d'autres systèmes ARM64 | Dockerfile-arm64 |
latest-nvidia-arm64 | Linux ARM64 avec support GPU NVIDIA pour Jetson AGX Thor, DGX Spark, JetPack 7 et DGX OS | Dockerfile-nvidia-arm64 |
latest-jetson-jetpack6 | Linux ARM64 pour les appareils NVIDIA Jetson exécutant JetPack 6 | Dockerfile-jetson-jetpack6 |
latest-jetson-jetpack5 | Linux ARM64 pour les appareils NVIDIA Jetson exécutant JetPack 5 | Dockerfile-jetson-jetpack5 |
latest-jetson-jetpack4 | Linux ARM64 pour les appareils NVIDIA Jetson exécutant JetPack 4 | Dockerfile-jetson-jetpack4 |
latest-runner | Image Linux AMD64 CUDA pour un runner GPU GitHub Actions auto-hébergé | Dockerfile-runner |
latest-runner-cpu | Image Linux AMD64 pour un runner CPU GitHub Actions auto-hébergé | Dockerfile-runner-cpu |
Les balises commençant par latest suivent la compilation de la branche principale la plus récemment publiée. Les balises versionnées remplacent le préfixe latest par une version d'Ultralytics, telle que VERSION, VERSION-cpu ou VERSION-jetson-jetpack6. Utilise une balise versionnée pour un environnement reproductible.
Pour récupérer la dernière image :
# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latestPour construire une image toi-même à la place, clone le dépôt et passe le Dockerfile correspondant du tableau ci-dessus, en utilisant la racine du dépôt comme contexte de construction :
# Build the CPU image locally from docker/Dockerfile-cpu
sudo docker build -t ultralytics/ultralytics:latest-cpu -f docker/Dockerfile-cpu .Exécution d'Ultralytics dans un conteneur Docker#
Voici comment exécuter le conteneur Docker Ultralytics :
Utilisation uniquement du CPU#
# Run without GPU
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpuUtilisation des 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:latestL'indicateur -it attribue un pseudo-TTY et maintient l'entrée standard (stdin) ouverte, te permettant d'interagir avec le conteneur. L'indicateur --ipc=host permet le partage de l'espace de noms IPC de l'hôte, ce qui est essentiel pour partager de la mémoire entre les processus. L'indicateur --device nvidia.com/gpu=... donne au conteneur accès aux GPU de l'hôte via CDI.
Sous Linux, les requêtes de périphériques CDI nécessitent Docker >= 28.2.0 (CDI activé par défaut) et nvidia-container-toolkit >= 1.18 (génération automatique de spécifications CDI). Mets à niveau les anciens hôtes Linux avant d'exécuter des conteneurs GPU. L'indicateur hérité --gpus all peut perdre l'accès au GPU (Failed to initialize NVML: Unknown Error) lorsque l'hôte recharge systemd lors de mises à jour de paquets de routine (nvidia-container-toolkit#48). Les requêtes CDI --device incluent les nœuds de périphériques dans la configuration du conteneur, de sorte que les conteneurs de longue durée tels que les travailleurs d'entraînement ou les exécuteurs CI conservent l'accès au GPU lors des rechargements.
La prise en charge des GPU Docker Desktop sur Windows utilise actuellement --gpus all avec le backend WSL 2 car les périphériques NVIDIA CDI n'y sont pas disponibles. Windows n'utilise pas systemd Linux, donc l'échec du rechargement du démon mentionné ci-dessus ne s'applique pas.
Note sur l'accessibilité des fichiers#
Pour travailler avec des fichiers sur ta machine locale à l'intérieur du conteneur, tu peux utiliser des volumes 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:latestRemplace /path/on/host par le chemin du répertoire sur ta machine locale et /path/in/container par le chemin souhaité à l'intérieur du conteneur Docker.
Persistance des sorties d'entraînement#
Par défaut, les sorties d'entraînement sont enregistrées dans /ultralytics/runs/<task>/<name>/ à l'intérieur du conteneur. Sans montage d'un répertoire hôte, les sorties sont perdues lorsque le conteneur est supprimé.
Pour conserver les sorties d'entraînement :
# 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/runsCela enregistre toutes les sorties d'entraînement dans ./runs sur ta machine hôte.
Exécuter des applications d'interface graphique (GUI) dans un conteneur Docker#
Les instructions suivantes sont expérimentales. Le partage d'une socket X11 avec un conteneur Docker présente des risques de sécurité potentiels. Par conséquent, il est recommandé de tester cette solution uniquement dans un environnement contrôlé. Pour plus d'informations, consulte ces ressources sur la façon d'utiliser xhost(1)(2).
Docker est principalement utilisé pour conteneuriser des applications en arrière-plan et des programmes CLI, mais il peut également exécuter des programmes graphiques. Dans le monde Linux, deux serveurs graphiques principaux gèrent l'affichage graphique : X11 (également connu sous le nom de X Window System) et Wayland. Avant de commencer, il est essentiel de déterminer quel serveur graphique tu utilises actuellement. Exécute cette commande pour le savoir :
env | grep -E -i 'x11|xorg|wayland'L'installation et la configuration d'un serveur d'affichage X11 ou Wayland sortent du cadre de ce guide. Si la commande ci-dessus ne renvoie rien, tu devras commencer par faire fonctionner l'un ou l'autre pour ton système avant de continuer.
Exécution d'un conteneur Docker avec une interface graphique#
Utiliser des GPU
Si tu utilises des GPU, tu peux ajouter l'indicateur --device nvidia.com/gpu=all à la commande.
Si tu utilises X11, tu peux exécuter la commande suivante pour permettre au conteneur Docker d'accéder au socket 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:latestCette commande définit la variable d'environnement DISPLAY sur l'affichage de l'hôte, monte la socket X11 et mappe le fichier .Xauthority sur le conteneur. La commande xhost +local:docker permet au conteneur Docker d'accéder au serveur X11.
Utilisation de Docker avec une interface graphique#
Tu peux maintenant afficher des applications graphiques à l'intérieur de ton conteneur Docker. Par exemple, tu peux exécuter la commande CLI suivante pour visualiser les prédictions d'un modèle YOLO26 :
yolo predict model=yolo26n.pt show=TrueTest
Un moyen simple de valider que le groupe Docker a accès au serveur X11 est d'exécuter un conteneur avec un programme GUI comme xclock ou xeyes. Alternativement, tu peux également installer ces programmes dans le conteneur Docker d'Ultralytics pour tester l'accès au serveur X11 de ton serveur d'affichage GNU-Linux. Si tu rencontres des problèmes, envisage de définir la variable d'environnement -e QT_DEBUG_PLUGINS=1. La définition de cette variable d'environnement active la sortie des informations de débogage, ce qui facilite le processus de dépannage.
Lorsque tu as terminé avec l'interface graphique Docker#
Dans les deux cas, n'oublie pas de révoquer l'accès du groupe Docker lorsque tu as terminé.
xhost -local:dockerTu veux voir les résultats des images directement dans le terminal ?
Consulte le guide suivant sur la visualisation des résultats d'image à l'aide d'un terminal
Tu es maintenant prêt à utiliser Ultralytics avec Docker et à profiter de ses fonctionnalités. Pour auto-héberger l'application web d'Ultralytics, consulte le guide de la plateforme sur site (On-Premise). Pour d'autres méthodes d'installation du paquet Python, consulte la documentation de démarrage rapide d'Ultralytics.
FAQ#
L'utilisation des images Docker d'Ultralytics garantit un environnement cohérent sur différentes machines, reproduisant les mêmes logiciels et dépendances. C'est particulièrement utile pour collaborer au sein d'équipes, exécuter des modèles sur divers matériels et maintenir la reproductibilité. Utilise
latestpour l'entraînement général sur GPU NVIDIA ou sélectionne l'image correspondant à ta version de JetPack pour un appareil NVIDIA Jetson. Consulte le tableau complet des images ou explore Ultralytics Docker Hub.Tout d'abord, assure-toi que le NVIDIA Container Toolkit est installé et configuré. Ensuite, utilise la commande suivante pour exécuter Ultralytics YOLO avec la prise en charge des GPU :
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest # all GPUsCette commande configure un conteneur Docker avec accès GPU. Pour des détails supplémentaires, vois le guide de démarrage rapide Docker.
Pour visualiser les résultats de prédiction YOLO avec une interface graphique dans un conteneur Docker, tu dois autoriser Docker à accéder à ton serveur d'affichage. Pour les systèmes exécutant X11, la commande est :
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v ~/.Xauthority:/root/.Xauthority \ -it --ipc=host ultralytics/ultralytics:latestPour les systèmes exécutant Wayland, utilise :
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \ --net=host -it --ipc=host ultralytics/ultralytics:latestPlus d'informations peuvent être trouvées dans la section Exécuter des applications d'interface graphique (GUI) dans un conteneur Docker.
Oui, tu peux monter des répertoires locaux dans le conteneur Docker d'Ultralytics en utilisant l'indicateur
-v:sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latestRemplace
/path/on/hostpar le répertoire sur ta machine locale et/path/in/containerpar le chemin souhaité à l'intérieur du conteneur. Cette configuration te permet de travailler avec tes fichiers locaux à l'intérieur du conteneur. Pour plus d'informations, réfère-toi à la section Remarque sur l'accessibilité des fichiers.
Pour configurer Ultralytics avec Docker, assure-toi d'abord que Docker est installé sur ton système. Si tu possèdes un GPU NVIDIA, installe le NVIDIA Container Toolkit pour activer la prise en charge des GPU. Ensuite, télécharge la dernière image Docker d'Ultralytics depuis Docker Hub à l'aide de la commande suivante :
Pour des étapes détaillées, reporte-toi à notre guide de démarrage rapide Docker.