Guida rapida di Docker per Ultralytics#

Questa guida funge da introduzione completa alla configurazione di un ambiente Docker per i tuoi progetti Ultralytics. Docker è una piattaforma per sviluppare, distribuire ed eseguire applicazioni in container. È particolarmente vantaggiosa per garantire che il software funzioni sempre allo stesso modo, indipendentemente da dove viene distribuito. Per ulteriori dettagli, visita il repository Docker di Ultralytics 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

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 abbia una GPU NVIDIA e i driver NVIDIA installati. Le immagini CPU non richiedono hardware NVIDIA.
• Se utilizzi dispositivi NVIDIA Jetson, assicurati di avere installato la versione corretta di JetPack. Fai riferimento alla guida NVIDIA Jetson per maggiori dettagli.

Configurazione di Docker con supporto NVIDIA (facoltativo)#

Innanzitutto, verifica che i driver NVIDIA siano installati correttamente eseguendo:

nvidia-smi

Installazione 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.list

sudo apt-get update

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

Verifica i dispositivi CDI con Docker#

Esegui nvidia-ctk cdi list per assicurarti che i dispositivi GPU CDI siano disponibili (il servizio nvidia-cdi-refresh del toolkit genera e gestisce la specifica automaticamente su toolkit >= 1.18):

nvidia-ctk cdi list

Dovresti vedere voci come nvidia.com/gpu=0 e nvidia.com/gpu=all. I dispositivi CDI rilevati appaiono anche in docker info.

Installazione delle immagini Docker di Ultralytics#

Ultralytics pubblica le seguenti immagini su Docker Hub. Ogni immagine è costruita a partire dal relativo Dockerfile tramite il flusso di lavoro di pubblicazione Docker.

I tag che iniziano con latest seguono la build del ramo main 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:latest

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-cpu

Utilizzando 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:latest

Il 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.

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:latest

Sostituisci /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#

Gli output di addestramento vengono salvati per impostazione predefinita in /ultralytics/runs/<task>/<name>/ all'interno del container. Senza montare una directory dell'host, gli output 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/runs

Questo salva tutti gli output di addestramento in ./runs sulla tua macchina host.

Esegui applicazioni con interfaccia grafica (GUI) in un container Docker#

Docker è 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 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#

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

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=True

Quando hai finito con la GUI di Docker#

xhost -local:docker

Ora sei pronto per utilizzare Ultralytics con Docker e sfruttare le sue funzionalità. Per ospitare autonomamente l'applicazione web di Ultralytics, consulta la guida alla piattaforma On-Premise. Per metodi alternativi di installazione del pacchetto Python, consulta la documentazione di avvio rapido di Ultralytics.

FAQ#

Come configuro Ultralytics con Docker?#

Per configurare Ultralytics con Docker, assicurati innanzitutto che Docker sia installato sul tuo sistema. Se hai 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:latest

Per passaggi dettagliati, consulta la nostra Guida rapida di Docker.

Quali sono i vantaggi dell'utilizzo delle immagini Docker di Ultralytics per progetti di machine learning?#

L'utilizzo delle immagini Docker di Ultralytics garantisce un ambiente coerente tra macchine diverse, 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 latest per l'addestramento generale su 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.

Come posso eseguire Ultralytics YOLO in un container Docker con supporto GPU?#

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 GPUs

Questo comando configura un container Docker con accesso alla GPU. Per ulteriori dettagli, vedi la Guida rapida di Docker.

Come visualizzo i risultati delle predizioni YOLO in un container Docker con un display server?#

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:latest

Per 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:latest

Maggiori informazioni si possono trovare nella sezione Esegui applicazioni con interfaccia grafica (GUI) in un container Docker.

Posso montare directory locali nel container Docker di Ultralytics?#

Sì, puoi montare directory locali nel container Docker di Ultralytics usando il flag -v:

sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

Sostituisci /path/on/host con la directory sulla tua macchina locale e /path/in/container con il percorso desiderato all'interno del container. Questa configurazione ti consente di lavorare con i tuoi file locali all'interno del container. Per maggiori informazioni, consulta la sezione Nota sull'accessibilità dei file.