Addestra il tuo primo modello YOLO·Configurazione·Lezione 1/10

Lezioneprincipiante

Installa Ultralytics

Installa Ultralytics in un ambiente pulito, leggi il report dei controlli di yolo per verificare il dispositivo e convalida la configurazione con una predizione.

Un addestramento che passa silenziosamente alla CPU può durare un giorno invece di un'ora, e te ne accorgerai solo quando sarà troppo tardi. Anche un'installazione non funzionante si manifesta nello stesso modo: a metà lezione, con un errore di importazione o una GPU non rilevata.

Dieci minuti dedicati a questa fase evitano entrambi i problemi. Installerai il pacchetto ultralytics in un ambiente nuovo, leggerai riga per riga il report yolo checks ed eseguirai una prima predizione con YOLO26 per verificare che tutto sia collegato correttamente.

Esito

Puoi installare Ultralytics in un ambiente pulito e capire, da una sola riga di yolo checks, se verrà eseguito su CUDA, MPS o CPU.

Percorso rapido

Se sai già come muoverti, ecco la versione breve.

Crea e attiva un nuovo ambiente virtuale con Python 3.10 o versione successiva.
Su una macchina NVIDIA, installa prima PyTorch con CUDA; poi pip install ultralytics.
Esegui yolo checks e leggi il dispositivo alla fine della prima riga.
Esegui yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpg e apri l'immagine salvata.

Pratico

Crea un ambiente pulito#

Il pacchetto ultralytics si installa con Python 3.8 e versioni successive, ma le versioni attuali di PyTorch richiedono Python 3.10 o versioni successive; perciò, per i nuovi progetti, usa una versione recente come la 3.12. Un ambiente virtuale pulito tiene il pacchetto e le sue dipendenze separati dagli altri progetti:

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
python --version                 # 3.10 or newer

La guida rapida di Ultralytics descrive la stessa configurazione con Conda o Docker, se preferisci queste opzioni.

Installa la versione corretta di PyTorch, poi Ultralytics#

Selettore "Start Locally" di PyTorch: scelta di sistema operativo, gestore di pacchetti, linguaggio e piattaforma di calcolo per generare il comando pip install corrispondente

Ultralytics funziona con PyTorch e pip installa una versione predefinita di PyTorch se non ne trova già una installata. Questa versione predefinita è la causa principale dei problemi del tipo "perché sta usando la CPU?", quindi scegli prima la versione da installare:

La tua macchina	Prima fai questo	Poi
GPU NVIDIA	Installa la versione CUDA dal selettore PyTorch compatibile con il tuo driver	`pip install ultralytics` la mantiene
Mac con Apple Silicon	Niente: la versione predefinita include MPS	`pip install ultralytics`
Solo CPU	Niente	`pip install ultralytics`

pip install ultralytics

Con un solo comando installi il pacchetto Python ultralytics, lo strumento da riga di comando yolo e dipendenze come OpenCV e NumPy.

Leggi il report di `yolo checks`#

yolo checks stampa le versioni e l'hardware che Ultralytics userà. Output reale da un MacBook, in forma abbreviata:

Ultralytics 8.4.175 🚀 Python-3.12.12 torch-2.14.1 CPU (Apple M5 Pro)
Setup complete ✅ (18 CPUs, 48.0 GB RAM, 594.4/926.3 GB disk)

OS                     macOS-27.0.1-arm64-arm-64bit
Python                 3.12.12
Install                pip
GPU                    None

Analisi riga per riga:

Ultralytics 8.4.175 ... torch-2.14.1: le versioni del pacchetto e di PyTorch. Riportale in qualsiasi segnalazione di bug.
CPU (Apple M5 Pro): il dispositivo usato quando non specifichi device. È la riga più importante.
Setup complete ✅: l'installazione è a posto.
GPU None: PyTorch non rileva alcuna GPU CUDA. È normale su un Mac, ma è un problema su una macchina NVIDIA.

Intervieni in base al dispositivo indicato nella riga 1:

Per questo corso non ti serve una GPU: ogni esempio è dimensionato per completarsi in pochi minuti su una CPU di laptop. Una GPU diventa importante quando addestri a dimensione piena: in quel caso è spesso almeno 10 volte più veloce.

Verifica con una predizione#

Una predizione mette alla prova l'intero stack: scarica i pesi nano di YOLO26, recupera un'immagine, esegue il modello e salva una copia annotata.

yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpg

image 1/1 bus.jpg: 640x480 4 persons, 1 bus, 20.1ms
Speed: 0.7ms preprocess, 20.1ms inference, 0.5ms postprocess per image at shape (1, 3, 640, 480)
Results saved to runs/detect/predict

640x480 4 persons, 1 bus: l'immagine è stata ridimensionata a 640×480 per il modello, che ha rilevato cinque oggetti.
20.1ms: tempo di inferenza su questa CPU. Annota il tuo valore: sarà il tuo primo riferimento per la velocità.
runs/detect/predict: percorso in cui è stato salvato bus.jpg annotato. Esegui di nuovo il comando e otterrai predict-2: Ultralytics non sovrascrive mai un run precedente.

Tutte le impostazioni predefinite di quel comando — confidenza, dimensione dell'immagine e percorso di salvataggio — sono elencate nel riferimento di configurazione.

Risolvi i problemi più comuni#

Addestramento silenzioso sulla CPU

Sintomo: yolo checks mostra CPU e GPU None su una macchina con una GPU NVIDIA e l'addestramento è terribilmente lento. Causa: pip ha installato una versione di PyTorch solo CPU. Soluzione: disinstalla torch e torchvision, installa la build CUDA dal selettore di PyTorch e riesegui yolo checks finché la prima riga non indica CUDA:0.

yolo: comando non trovato

Causa: l'ambiente virtuale non è attivo in questo terminale, quindi lo script yolo non si trova nel tuo PATH. Soluzione: esegui source .venv/bin/activate (o il comando equivalente su Windows) in ogni nuovo terminale prima di usare yolo.

Sintomo	Causa	Soluzione
`requirements: ... not found, attempting AutoUpdate` quindi `No module named pip`	L'ambiente è stato creato senza pip, quindi Ultralytics non può installare automaticamente un pacchetto aggiuntivo	Installa il pacchetto indicato con lo strumento del tuo ambiente, ad esempio `uv pip install lap`
I download dei pesi o del dataset vanno in timeout	La rete blocca gli asset delle release di GitHub	Scarica `yolo26n.pt` una volta da un'altra posizione e specifica il relativo percorso locale
`PermissionError` scrive in `runs/`	La directory di lavoro è di sola lettura	`cd` in una cartella di progetto scrivibile

Per tutto il resto, la guida ai problemi comuni raccoglie le soluzioni note e le issue chiuse nel repository Ultralytics contengono spesso la risposta: cercale prima di aprirne una nuova.

Provalo

In un ambiente nuovo, installa Ultralytics, esegui yolo checks e avvia la predizione dell'autobus. Fornisci un resoconto della configurazione in tre righe: le versioni di Ultralytics e PyTorch, il dispositivo indicato nella prima riga di yolo checks (e, su una macchina NVIDIA, la prova che indica CUDA:0) e il tempo di inferenza riportato per bus.jpg.

Criteri di completamento

La lezione è completata quando tutte le seguenti condizioni sono soddisfatte.

yolo checks termina con Setup complete ✅ e indica il dispositivo previsto.
runs/detect/predict/bus.jpg è stato creato e mostra quattro persone e un autobus racchiusi nei riquadri.
Hai annotato le versioni, il dispositivo e il tempo di inferenza di bus.jpg.

Mostra la soluzione

python -m venv .venv
source .venv/bin/activate
# NVIDIA only: install the CUDA PyTorch build from pytorch.org first
pip install ultralytics
yolo checks
yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpg

Versions: Ultralytics 8.4.175, torch 2.14.1
Device:   CPU (Apple M5 Pro); use device=mps for the Apple GPU
bus.jpg:  20.1 ms inference at 640x480

Su una CPU di laptop, aspettati circa 10–60 ms per bus.jpg; su una GPU NVIDIA recente, pochi millisecondi. Se yolo checks indica il dispositivo sbagliato, correggi PyTorch prima di proseguire.

Prossimi passi

L'ambiente funziona. Ora esegui la stessa predizione da Python e impara a leggere ogni campo restituito dal modello.

Accedi per salvare i progressi

Get Started