Link to this sectionGuida rapida di Docker per Ultralytics#

Ultralytics Docker Package Visual

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.

Link to this sectionCosa 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 🎉

Link to this sectionPrerequisiti#

Assicurati che Docker sia installato sul tuo sistema. In caso contrario, puoi scaricarlo e installarlo dal sito web di Docker.
Assicurati che il tuo sistema disponga di una GPU NVIDIA e che i driver NVIDIA siano installati.
Se utilizzi dispositivi NVIDIA Jetson, assicurati di avere installato la versione corretta di JetPack. Consulta la guida NVIDIA Jetson per ulteriori dettagli.

Link to this sectionConfigurazione di Docker con supporto NVIDIA#

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

nvidia-smi

Link to this sectionInstallazione 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

Aggiorna gli elenchi dei pacchetti e installa il pacchetto nvidia-container-toolkit:

sudo apt-get update

Installa l'ultima versione di nvidia-container-toolkit:

sudo apt-get install -y nvidia-container-toolkit \
  nvidia-container-toolkit-base libnvidia-container-tools \
  libnvidia-container1

Opzionale: Installa una versione specifica di nvidia-container-toolkit

Facoltativamente, puoi installare una versione specifica di nvidia-container-toolkit impostando la variabile d'ambiente NVIDIA_CONTAINER_TOOLKIT_VERSION:

export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.17.8-1
sudo apt-get install -y \
  nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Link to this sectionVerifica il Runtime NVIDIA con Docker#

Esegui docker info | grep -i runtime per assicurarti che nvidia appaia nell'elenco dei runtime:

docker info | grep -i runtime

Link to this sectionInstallazione delle immagini Docker di Ultralytics#

Ultralytics offre diverse immagini Docker ottimizzate per varie piattaforme e casi d'uso:

Dockerfile: immagine GPU, ideale per l'addestramento.
Dockerfile-arm64: Per architettura ARM64, adatta a dispositivi come Raspberry Pi.
Dockerfile-cpu: Versione solo CPU per inferenza e ambienti senza GPU.
Dockerfile-jetson-jetpack4: Ottimizzato per dispositivi NVIDIA Jetson che eseguono NVIDIA JetPack 4.
Dockerfile-jetson-jetpack5: Ottimizzato per dispositivi NVIDIA Jetson che eseguono NVIDIA JetPack 5.
Dockerfile-jetson-jetpack6: Ottimizzato per dispositivi NVIDIA Jetson che eseguono NVIDIA JetPack 6.
Dockerfile-jupyter: Per sviluppo interattivo usando JupyterLab nel browser.
Dockerfile-nvidia-arm64: Per dispositivi NVIDIA ARM64 come Jetson AGX Thor e DGX Spark, con supporto per JetPack 7.0 e DGX OS.
Dockerfile-python: Ambiente Python minimale per applicazioni leggere.
Dockerfile-python-export: Immagine Python minimale estesa con funzionalità di esportazione complete per la conversione di modelli YOLO.
Dockerfile-conda: Include Miniconda3 e il pacchetto Ultralytics installato tramite Conda.
Dockerfile-export: Immagine GPU con tutte le dipendenze per i formati di esportazione preinstallate per conversione di modelli e benchmarking.

Per scaricare l'ultima immagine:

# Set image name as a variable
t=ultralytics/ultralytics:latest

# Pull the latest Ultralytics image from Docker Hub
sudo docker pull $t

Link to this sectionEsecuzione di Ultralytics in un container Docker#

Ecco come eseguire il container Docker di Ultralytics:

Link to this sectionUtilizzando solo la CPU#

# Run without GPU
sudo docker run -it --ipc=host $t

Link to this sectionUtilizzando le GPU#

# Run with all GPUs
sudo docker run -it --ipc=host --runtime=nvidia --gpus all $t

# Run specifying which GPUs to use
sudo docker run -it --ipc=host --runtime=nvidia --gpus '"device=2,3"' $t

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 --gpus consente al container di accedere alle GPU dell'host.

Link to this sectionNota 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 --runtime=nvidia --gpus all -v /path/on/host:/path/in/container $t

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.

Link to this sectionMantenimento 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.

Link to this sectionEsegui applicazioni con interfaccia grafica (GUI) in un container Docker#

Altamente sperimentale - L'utente si assume tutti i rischi

Le seguenti istruzioni sono sperimentali. Condividere un socket X11 con un container Docker comporta potenziali rischi per la sicurezza. Pertanto, si consiglia di testare questa soluzione solo in un ambiente controllato. Per ulteriori informazioni, consulta queste risorse su come usare xhost⁽¹⁾⁽²⁾.

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.

Link to this sectionEsecuzione di un container Docker con una GUI#

Esempio

Usa le GPU

Se stai usando le GPU, puoi aggiungere il flag --gpus all al comando.

Flag del runtime Docker

Se la tua installazione di Docker non usa il runtime nvidia per impostazione predefinita, puoi aggiungere il flag --runtime=nvidia 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 $t

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

Link to this sectionUtilizzo 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

Test

Un modo semplice per convalidare 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 Docker di Ultralytics per testare l'accesso al server X11 del tuo server grafico 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 di informazioni di debug, aiutando nel processo di risoluzione dei problemi.

Link to this sectionQuando hai finito con la GUI di Docker#

Revoca l'accesso

In entrambi i casi, non dimenticare di revocare l'accesso dal gruppo Docker quando hai finito.

xhost -local:docker

Vuoi visualizzare i risultati delle immagini direttamente nel terminale?

Fai riferimento alla seguente guida su come visualizzare i risultati delle immagini usando un terminale

Ora sei pronto a usare Ultralytics con Docker e a sfruttare le sue funzionalità. Per metodi di installazione alternativi, consulta la documentazione di avvio rapido di Ultralytics.

Link to this sectionFAQ#

Link to this sectionCome 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.

Link to this sectionQuali 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 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à. Per l'addestramento basato su GPU, Ultralytics fornisce immagini Docker ottimizzate come Dockerfile per l'uso generale della GPU e Dockerfile-jetson per i dispositivi NVIDIA Jetson. Esplora Ultralytics Docker Hub per ulteriori dettagli.

Link to this sectionCome 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 --runtime=nvidia --gpus 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.

Link to this sectionCome 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.

Link to this sectionPosso 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 --runtime=nvidia --gpus 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.

Collaboratori

GLglenn-jocher¹⁵ ONonuralpszr³ RIRizwanMunawar² RAraimbekovm¹ PDpderrenger¹ SHSHOscarChen¹ PIpicsalex¹ LAlakshanthad¹ FRFruchtzwerg94¹ BUBurhan-Q¹JOJoão Fonseca¹

Creato 12 nov 2023Aggiornato 3 giorni fa