Guida rapida di Docker per Ultralytics#
Questa guida serve come introduzione completa alla configurazione di un ambiente Docker per i tuoi progetti Ultralytics. Docker è una piattaforma per sviluppare, distribuire ed eseguire applicazioni nei container. È particolarmente vantaggiosa per garantire che il software funzioni sempre allo stesso modo, indipendentemente da dove viene distribuito. Per maggiori dettagli, visita il repository Ultralytics Docker su Docker Hub.
Cosa imparerai#
- Configurazione di Docker con supporto NVIDIA
- Installazione delle immagini Docker di Ultralytics
- Esecuzione di Ultralytics in un container Docker con supporto CPU o GPU
- Utilizzo di un display server con Docker per mostrare i risultati di rilevamento di Ultralytics
- Montaggio di directory locali all'interno del container
Watch: How to Get started with Docker | Usage of Ultralytics Python Package inside Docker live demo 🎉
Prerequisiti#
- Assicurati che Docker sia installato sul tuo sistema. In caso contrario, puoi scaricarlo e installarlo dal sito web di Docker.
- Per l'accelerazione GPU, assicurati che il tuo sistema disponga di una GPU NVIDIA e dei driver NVIDIA installati. Le immagini CPU non richiedono hardware NVIDIA.
- Se utilizzi dispositivi NVIDIA Jetson, assicurati di avere installato la versione di JetPack appropriata. Fai riferimento alla guida a NVIDIA Jetson per maggiori dettagli.
Configurazione di Docker con supporto NVIDIA (facoltativo)#
Innanzitutto, verifica che i driver NVIDIA siano installati correttamente eseguendo:
nvidia-smiInstallazione del NVIDIA Container Toolkit#
Ora installiamo il NVIDIA Container Toolkit per abilitare il supporto GPU nei container 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.listAggiorna gli elenchi dei pacchetti e installa il NVIDIA Container Toolkit:
sudo apt-get updatesudo apt-get install -y nvidia-container-toolkitVerifica i dispositivi CDI con Docker#
Esegui nvidia-ctk cdi list per assicurarti che i dispositivi CDI della GPU siano disponibili (il servizio nvidia-cdi-refresh del toolkit genera e mantiene automaticamente la specifica sui toolkit >= 1.18):
nvidia-ctk cdi listDovresti visualizzare voci come nvidia.com/gpu=0 e nvidia.com/gpu=all. I dispositivi CDI rilevati compaiono anche in docker info.
Installazione delle immagini Docker di Ultralytics#
Ultralytics pubblica le seguenti immagini su Docker Hub. Ciascuna immagine viene compilata dal relativo Dockerfile tramite il flusso di lavoro di pubblicazione Docker.
| Tag | Piattaforma e scopo | Sorgente |
|---|---|---|
latest | Linux AMD64 con CUDA per addestramento e inferenza su GPU | Dockerfile |
latest-export | Linux AMD64 con CUDA e dipendenze di esportazione per conversione e benchmarking | Dockerfile-export |
latest-python | Immagine Linux AMD64 Python leggera per inferenza su CPU | Dockerfile-python |
latest-python-export | Immagine CPU Linux AMD64 con dipendenze di esportazione | Dockerfile-python-export |
latest-cpu | Immagine CPU Linux AMD64 con Bash come comando predefinito | Dockerfile-cpu |
latest-jupyter | Immagine CPU Linux AMD64 con JupyterLab e notebook di tutorial Ultralytics | Dockerfile-jupyter |
latest-arm64 | Immagine CPU Linux ARM64 per Apple silicon, Raspberry Pi e altri sistemi ARM64 | Dockerfile-arm64 |
latest-nvidia-arm64 | Linux ARM64 con supporto GPU NVIDIA per Jetson AGX Thor, DGX Spark, JetPack 7 e DGX OS | Dockerfile-nvidia-arm64 |
latest-jetson-jetpack6 | Linux ARM64 per dispositivi NVIDIA Jetson con JetPack 6 | Dockerfile-jetson-jetpack6 |
latest-jetson-jetpack5 | Linux ARM64 per dispositivi NVIDIA Jetson con JetPack 5 | Dockerfile-jetson-jetpack5 |
latest-jetson-jetpack4 | Linux ARM64 per dispositivi NVIDIA Jetson con JetPack 4 | Dockerfile-jetson-jetpack4 |
latest-runner | Immagine CUDA Linux AMD64 per un runner GPU GitHub Actions self-hosted | Dockerfile-runner |
latest-runner-cpu | Immagine Linux AMD64 per un runner CPU GitHub Actions self-hosted | Dockerfile-runner-cpu |
I tag che iniziano con latest tracciano la build del branch principale pubblicata più di recente. I tag con versione sostituiscono il prefisso latest con una release di Ultralytics, come VERSION, VERSION-cpu o VERSION-jetson-jetpack6. Usa un tag con versione per un ambiente riproducibile.
Per scaricare l'ultima immagine:
# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latestPer costruire invece un'immagine in autonomia, clona il repository e passa il Dockerfile corrispondente dalla tabella sopra, usando la root del repository come contesto di build:
# Build the CPU image locally from docker/Dockerfile-cpu
sudo docker build -t ultralytics/ultralytics:latest-cpu -f docker/Dockerfile-cpu .Esecuzione di Ultralytics in un container Docker#
Ecco come eseguire il container Docker di Ultralytics:
Utilizzando solo la CPU#
# Run without GPU
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpuUtilizzando le 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:latestIl flag -it assegna un pseudo-TTY e mantiene stdin aperto, permettendoti di interagire con il container. Il flag --ipc=host abilita la condivisione dello spazio dei nomi IPC dell'host, essenziale per condividere la memoria tra i processi. Il flag --device nvidia.com/gpu=... garantisce al container l'accesso alle GPU dell'host tramite CDI.
Su Linux, le richieste di dispositivi CDI richiedono Docker >= 28.2.0 (CDI abilitato per impostazione predefinita) e nvidia-container-toolkit >= 1.18 (generazione automatica delle specifiche CDI). Aggiorna gli host Linux meno recenti prima di eseguire i container GPU. Il flag legacy --gpus all può perdere l'accesso alla GPU (Failed to initialize NVML: Unknown Error) quando l'host ricarica systemd durante i normali aggiornamenti dei pacchetti (nvidia-container-toolkit#48). Le richieste CDI --device includono i nodi dei dispositivi nella configurazione del container, in modo che i container a lunga esecuzione come i worker di training o i runner CI mantengano l'accesso alla GPU tra i ricaricamenti.
Il supporto GPU di Docker Desktop su Windows attualmente utilizza --gpus all con il backend WSL 2 poiché i dispositivi NVIDIA CDI non sono disponibili lì. Windows non utilizza systemd di Linux, quindi il fallimento del ricaricamento del daemon menzionato sopra non si applica.
Nota sull'accessibilità dei file#
Per lavorare con i file sulla tua macchina locale all'interno del container, puoi usare i volumi 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:latestSostituisci /path/on/host con il percorso della directory sulla tua macchina locale e /path/in/container con il percorso desiderato all'interno del container Docker.
Mantenimento degli output di addestramento#
I risultati del training vengono salvati per impostazione predefinita in /ultralytics/runs/<task>/<name>/ all'interno del container. Senza montare una directory host, i risultati vengono persi quando il container viene rimosso.
Per mantenere gli output di addestramento:
# 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/runsQuesto salva tutti i risultati del training in ./runs sulla tua macchina host.
Esegui applicazioni con interfaccia grafica (GUI) in un container Docker#
Le seguenti istruzioni sono sperimentali. La condivisione di un socket X11 con un container Docker comporta potenziali rischi per la sicurezza. Pertanto, è consigliabile testare questa soluzione solo in un ambiente controllato. Per ulteriori informazioni, fai riferimento a queste risorse su come usare xhost(1)(2).
Docker viene utilizzato principalmente per containerizzare applicazioni in background e programmi CLI, ma può anche eseguire programmi grafici. Nel mondo Linux, due server grafici principali gestiscono la visualizzazione grafica: X11 (noto anche come X Window System) e Wayland. Prima di iniziare, è essenziale determinare quale server grafico stai attualmente utilizzando. Esegui questo comando per scoprirlo:
env | grep -E -i 'x11|xorg|wayland'La configurazione di un display server X11 o Wayland non rientra nell'ambito di questa guida. Se il comando sopra non restituisce nulla, dovrai iniziare assicurandoti che uno dei due funzioni sul tuo sistema prima di continuare.
Esecuzione di un container Docker con una GUI#
Usa le GPU
Se stai utilizzando GPU, puoi aggiungere il flag --device nvidia.com/gpu=all al comando.
Se stai usando X11, puoi eseguire il comando seguente per consentire al container Docker di accedere al 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:latestQuesto comando imposta la variabile d'ambiente DISPLAY sul display dell'host, monta il socket X11 e mappa il file .Xauthority nel container. Il comando xhost +local:docker consente al container Docker di accedere al server X11.
Utilizzo di Docker con una GUI#
Ora puoi visualizzare applicazioni grafiche all'interno del tuo container Docker. Ad esempio, puoi eseguire il seguente comando CLI per visualizzare le predizioni da un modello YOLO26:
yolo predict model=yolo26n.pt show=TrueTest
Un modo semplice per verificare che il gruppo Docker abbia accesso al server X11 è eseguire un container con un programma GUI come xclock o xeyes. In alternativa, puoi anche installare questi programmi nel container Ultralytics Docker per testare l'accesso al server X11 del tuo display server GNU-Linux. Se riscontri problemi, prendi in considerazione l'impostazione della variabile d'ambiente -e QT_DEBUG_PLUGINS=1. L'impostazione di questa variabile d'ambiente abilita l'output delle informazioni di debug, aiutando nel processo di risoluzione dei problemi.
Quando hai finito con la GUI di Docker#
In entrambi i casi, non dimenticare di revocare l'accesso dal gruppo Docker quando hai finito.
xhost -local:dockerVuoi visualizzare i risultati delle immagini direttamente nel terminale?
Fai riferimento alla seguente guida su come visualizzare i risultati delle immagini utilizzando un terminale
Ora sei pronto per usare Ultralytics con Docker e sfruttarne tutte le funzionalità. Per ospitare autonomamente l'applicazione web Ultralytics, consulta la guida Platform On-Premise. Per metodi alternativi di installazione del pacchetto Python, consulta la documentazione di avvio rapido di Ultralytics.
FAQ#
Per configurare Ultralytics con Docker, assicurati prima che Docker sia installato sul tuo sistema. Se disponi di una GPU NVIDIA, installa il NVIDIA Container Toolkit per abilitare il supporto GPU. Quindi, scarica l'ultima immagine Docker di Ultralytics da Docker Hub usando il seguente comando:
sudo docker pull ultralytics/ultralytics:latestPer passaggi dettagliati, consulta la nostra Guida rapida di Docker.
L'uso delle immagini Docker di Ultralytics garantisce un ambiente coerente su diverse macchine, replicando lo stesso software e le stesse dipendenze. Questo è particolarmente utile per collaborare tra team, eseguire modelli su vari hardware e mantenere la riproducibilità. Usa
latestper il training generale con GPU NVIDIA o seleziona l'immagine corrispondente alla tua versione di JetPack per un dispositivo NVIDIA Jetson. Consulta la tabella completa delle immagini o esplora Ultralytics Docker Hub.Innanzitutto, assicurati che il NVIDIA Container Toolkit sia installato e configurato. Quindi, usa il seguente comando per eseguire Ultralytics YOLO con supporto GPU:
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest # all GPUsQuesto comando configura un container Docker con accesso alla GPU. Per ulteriori dettagli, vedi la Guida rapida di Docker.
Per visualizzare i risultati delle predizioni YOLO con una GUI in un container Docker, devi consentire a Docker di accedere al tuo display server. Per i sistemi che eseguono X11, il comando è:
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v ~/.Xauthority:/root/.Xauthority \ -it --ipc=host ultralytics/ultralytics:latestPer i sistemi che eseguono Wayland, usa:
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \ --net=host -it --ipc=host ultralytics/ultralytics:latestUlteriori informazioni sono disponibili nella sezione Esecuzione di applicazioni con interfaccia utente grafica (GUI) in un container Docker.
Sì, puoi montare directory locali nel container Ultralytics Docker usando il flag
-v:sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latestSostituisci
/path/on/hostcon la directory sulla tua macchina locale e/path/in/containercon il percorso desiderato all'interno del container. Questa configurazione ti consente di lavorare con i tuoi file locali all'interno del container. Per ulteriori informazioni, fai riferimento alla sezione Nota sull'accessibilità dei file.