Risoluzione dei problemi più comuni di YOLO#

Questa guida tratta i problemi più comuni che potresti incontrare lavorando con Ultralytics YOLO26, suddivisi in base alla fase in cui si verificano: installazione, addestramento del modello, predizione e distribuzione. Vai alla categoria corrispondente al tuo errore oppure consulta le FAQ per trovare rapidamente una risposta. Ogni voce descrive il problema e una soluzione concreta che puoi applicare direttamente.

Problemi comuni#

Errori di installazione#

Gli errori di installazione possono dipendere da vari motivi, ad esempio versioni incompatibili, dipendenze mancanti o configurazioni errate dell'ambiente. Per prima cosa, verifica di aver eseguito queste operazioni:

• Stai usando Python 3.8 o versioni successive, come consigliato.
• Assicurati di aver installato la versione corretta di PyTorch (1.8 o successiva).
• Valuta l'uso di ambienti virtuali per evitare conflitti.
• Segui passo dopo passo la guida ufficiale all'installazione.

Ecco inoltre alcune soluzioni ai problemi di installazione più comuni.

Errori di importazione o problemi con le dipendenze#

Se ricevi errori durante l'importazione di YOLO26 o riscontri conflitti tra dipendenze, prova a seguire questi passaggi:

• Nuova installazione: partire da un'installazione pulita può risolvere problemi imprevisti, soprattutto dopo aggiornamenti che modificano la struttura o le funzionalità del pacchetto.
• Aggiornamenti regolari: usa la versione più recente della libreria, perché le release meno recenti potrebbero non essere compatibili con gli aggiornamenti recenti.
• Verifica delle dipendenze: controlla che tutte le dipendenze richieste siano installate correttamente e abbiano versioni compatibili.
• Esamina le modifiche: se hai installato una versione meno recente, consulta la documentazione ufficiale o il changelog per capire quali modifiche strutturali importanti sono state apportate.

Eseguire YOLO26 su GPU#

Se hai problemi a eseguire YOLO26 su una GPU, prova a seguire questi passaggi per la risoluzione dei problemi:

• Verifica della compatibilità e dell'installazione di CUDA: assicurati che la GPU sia compatibile con CUDA e che CUDA sia installato correttamente. Usa il comando nvidia-smi per controllare lo stato della GPU NVIDIA e la versione di CUDA.
• Verifica dell'integrazione tra PyTorch e CUDA: assicurati che PyTorch possa usare CUDA eseguendo import torch; print(torch.cuda.is_available()) in un terminale Python. Se restituisce 'True', PyTorch è configurato per usare CUDA.
• Attivazione dell'ambiente: assicurati di trovarti nell'ambiente corretto, in cui sono installati tutti i pacchetti necessari.
• Aggiorna i pacchetti: i pacchetti obsoleti potrebbero non essere compatibili con la tua GPU. Mantienili aggiornati.
• Configurazione del programma: controlla se il codice richiede l'uso della GPU. Puoi impostare l'argomento device durante l'addestramento o la predizione (ad esempio, device=0).

import torch

cap = torch.cuda.get_device_capability(0) if torch.cuda.is_available() else (0, 0)
cudnn = torch.backends.cudnn.version() or 0
ok = "not compatible" if cudnn >= 91100 and (cap[0] < 7 or (cap[0] == 7 and cap[1] < 5)) else "should be ok"
print(f"Compute capability: SM {cap[0]}.{cap[1]}, cuDNN: {cudnn} => {ok}")

Problemi di addestramento del modello#

Di seguito trovi i problemi di addestramento più comuni e le relative soluzioni.

Verifica delle impostazioni di configurazione#

Problema: non sai se le impostazioni di configurazione nel file .yaml vengono applicate correttamente durante l'addestramento del modello.

Soluzione: le impostazioni del dataset e quelle di addestramento si trovano in file .yaml distinti e vengono passate tramite argomenti diversi di model.train(). Per assicurarti che queste impostazioni siano applicate correttamente, segui questi passaggi:

• Verifica che i percorsi dei file .yaml siano corretti.

• Passa .yaml del dataset (percorsi, nomi delle classi, split) come argomento data e un .yaml personalizzato per le impostazioni di addestramento (ad esempio epochs o lr0) come argomento cfg. Gli argomenti passati direttamente a model.train() hanno la precedenza su entrambi:

  model.train(data="/path/to/your/data.yaml", cfg="/path/to/your/cfg.yaml", batch=4)

Accelerare l'addestramento con più GPU#

Problema: l'addestramento è lento su una singola GPU e vuoi velocizzarlo usando più GPU.

Soluzione: aumentare la dimensione del batch può accelerare l'addestramento, ma è essenziale considerare la capacità di memoria della GPU. Per velocizzare l'addestramento con più GPU, segui questi passaggi:

• Assicurati di avere più GPU disponibili.

• Imposta l'argomento device su un elenco di indici GPU, ad esempio device=[0,1,2,3].

• Aumenta la dimensione del batch in modo adeguato per sfruttare appieno le GPU senza superare i limiti di memoria.

• Modifica il comando di addestramento per usare più GPU:

  # # Regola la dimensione del batch e le altre impostazioni secondo necessità per ottimizzare la velocità di addestramento
  model.train(data="/path/to/your/data.yaml", batch=32, device=[0, 1, 2, 3])

Parametri da monitorare costantemente#

Problema: vuoi sapere quali parametri monitorare costantemente durante l'addestramento, oltre alla loss.

Soluzione: la loss è una metrica fondamentale da monitorare, ma è importante tenere traccia anche di altre metriche per ottimizzare le prestazioni del modello. Tra le metriche principali da monitorare durante l'addestramento ci sono:

• Precisione
• Richiamo
• Precisione media (mAP)

Puoi consultare queste metriche nei log di addestramento o usare strumenti come TensorBoard o Weights & Biases per visualizzarle. Implementare l'early stopping sulla base di queste metriche può aiutarti a ottenere risultati migliori.

Strumenti per monitorare i progressi dell'addestramento#

Problema: cerchi consigli sugli strumenti per monitorare i progressi dell'addestramento.

Soluzione: per monitorare e visualizzare i progressi dell'addestramento, puoi valutare l'uso dei seguenti strumenti:

• TensorBoard: TensorBoard è uno strumento diffuso per visualizzare le metriche di addestramento, tra cui la loss, l'accuratezza e altro ancora. Puoi integrarlo nel flusso di addestramento di YOLO26.
• Comet: Comet offre un toolkit completo per il monitoraggio e il confronto degli esperimenti. Ti permette di tenere traccia delle metriche, degli iperparametri e persino dei pesi del modello. L'integrazione con i modelli YOLO è semplice e ti offre una panoramica completa del ciclo dell'esperimento.
• Piattaforma Ultralytics: Ultralytics Platform offre un ambiente specializzato per monitorare i modelli YOLO e una piattaforma unica per gestire metriche e dataset e collaborare con il tuo team. Essendo pensata specificamente per YOLO, offre opzioni di monitoraggio più personalizzate.

Come verificare se l'addestramento viene eseguito sulla GPU#

Problema: il valore 'device' nei log di addestramento è 'null' e non sai se l'addestramento viene eseguito sulla GPU.

Soluzione: in genere, il valore 'device' impostato su 'null' indica che il processo di addestramento è configurato per selezionare automaticamente una GPU disponibile, che è il comportamento predefinito. Per addestrare su una GPU specifica, imposta l'argomento device all'avvio dell'addestramento. device è un argomento di addestramento, quindi impostarlo nel file .yaml del dataset non ha effetto:

from ultralytics import YOLO

# Carica un modello
model = YOLO("yolo26n.pt")

# # Usa la GPU 0; device=[0, 1] per più GPU, device="cpu" per la CPU
model.train(data="path/to/data.yaml", device=0)

Controlla la cartella 'runs' per consultare i log e le metriche e monitorare efficacemente i progressi dell'addestramento.

Aspetti fondamentali per un addestramento efficace del modello#

Ecco alcuni aspetti da tenere presenti se riscontri problemi relativi all'addestramento del modello.

Formato del dataset ed etichette

• Importanza: le fondamenta di qualsiasi modello di machine learning sono la qualità e il formato dei dati su cui viene addestrato.
• Consiglio: assicurati che il tuo dataset personalizzato e le relative etichette rispettino il formato previsto. È fondamentale verificare che le annotazioni siano accurate e di alta qualità. Annotazioni errate o scadenti possono compromettere l'apprendimento del modello e portare a risultati imprevedibili.

Convergenza del modello

• Importanza: raggiungere la convergenza del modello garantisce che il modello abbia appreso a sufficienza dai dati di addestramento.
• Consiglio: quando addestri un modello 'da zero', è fondamentale assicurarsi che raggiunga un livello di convergenza soddisfacente. Potrebbe essere necessario prolungare l'addestramento e aumentare il numero di epoche rispetto al fine-tuning di un modello esistente.

Learning rate e dimensione del batch

• Importanza: questi iperparametri svolgono un ruolo fondamentale nel determinare come il modello aggiorna i propri pesi durante l'addestramento.
• Consiglio: valuta regolarmente se il learning rate e la dimensione del batch scelti sono ottimali per il tuo dataset specifico. Parametri non adatti alle caratteristiche del dataset possono compromettere le prestazioni del modello.

Distribuzione delle classi

• Importanza: la distribuzione delle classi nel dataset può influenzare le tendenze del modello nelle predizioni.
• Consiglio: valuta regolarmente la distribuzione delle classi nel dataset. Se le classi sono sbilanciate, il modello rischia di sviluppare un bias a favore della classe più frequente. Questo bias può emergere nella matrice di confusione, in cui il modello potrebbe predire prevalentemente la classe maggioritaria.

Verifica incrociata con pesi preaddestrati

• Importanza: sfruttare pesi preaddestrati può fornire una solida base per l'addestramento del modello, soprattutto quando i dati sono limitati.
• Raccomandazione: come passaggio diagnostico, valuta di addestrare il modello sugli stessi dati, inizializzandolo però con pesi preaddestrati. Se questo approccio produce una matrice di confusione ben formata, potrebbe indicare che il modello addestrato «da zero» richiede ulteriore addestramento o alcune modifiche.

Problemi relativi alle previsioni del modello#

Di seguito sono descritti i problemi più comuni che si verificano durante le previsioni del modello e le relative soluzioni.

Ottenere previsioni dei riquadri di delimitazione con il tuo modello YOLO26 personalizzato#

Problema: quando esegui previsioni con un modello YOLO26 personalizzato, puoi incontrare difficoltà con il formato e la visualizzazione delle coordinate dei riquadri di delimitazione.

Soluzione:

• Formato delle coordinate: YOLO26 fornisce le coordinate dei riquadri di delimitazione in valori assoluti di pixel. Per convertirle in coordinate relative (comprese tra 0 e 1), devi dividerle per le dimensioni dell'immagine. Per esempio, supponiamo che l'immagine abbia dimensioni 640x640. In tal caso, procedi così:

  # Converti le coordinate assolute in coordinate relative
  x1 = x1 / 640  # Dividi le coordinate x per la larghezza dell'immagine
  x2 = x2 / 640
  y1 = y1 / 640  # Dividi le coordinate y per l'altezza dell'immagine
  y2 = y2 / 640

• Nome del file: per ottenere il nome del file dell'immagine su cui esegui la previsione, leggi il percorso del file immagine dall'attributo path di ciascun oggetto risultato (ad esempio result.path) all'interno del ciclo di previsione.

Filtrare gli oggetti nelle previsioni YOLO26#

Problema: difficoltà a filtrare e visualizzare solo determinati oggetti nei risultati delle previsioni quando esegui YOLO26 con la libreria Ultralytics.

Soluzione: per rilevare classi specifiche, usa l'argomento classes per specificare le classi da includere nell'output. Per esempio, per rilevare solo le auto (supponendo che la classe delle «auto» abbia indice 2):

yolo segment predict model=yolo26n-seg.pt source='path/to/car.mp4' show=True classes=2

Comprendere le metriche di precisione in YOLO26#

Problema: confusione sulle differenze tra la precisione dei riquadri, quella delle maschere e quella della matrice di confusione in YOLO26.

Soluzione: la precisione dei riquadri misura l'accuratezza dei riquadri di delimitazione previsti rispetto ai riquadri di riferimento effettivi, usando IoU (intersezione sull'unione) come metrica. La precisione delle maschere valuta la corrispondenza tra le maschere di segmentazione previste e quelle di riferimento nella classificazione degli oggetti a livello di pixel. La precisione della matrice di confusione, invece, si concentra sull'accuratezza complessiva della classificazione di tutte le classi e non considera l'accuratezza geometrica delle previsioni. È importante notare che un riquadro di delimitazione può essere geometricamente accurato (vero positivo) anche se la previsione della classe è errata, generando una differenza tra la precisione dei riquadri e quella della matrice di confusione. Queste metriche valutano aspetti diversi delle prestazioni di un modello e dimostrano la necessità di usare metriche di valutazione differenti per le varie attività.

Estrarre le dimensioni degli oggetti in YOLO26#

Problema: difficoltà a recuperare la lunghezza e l'altezza degli oggetti rilevati in YOLO26, soprattutto quando nell'immagine vengono rilevati più oggetti.

Soluzione: per recuperare le dimensioni dei riquadri di delimitazione, usa innanzitutto il modello Ultralytics YOLO26 per prevedere gli oggetti in un'immagine. Quindi, estrai le informazioni su larghezza e altezza dei riquadri di delimitazione dai risultati della previsione.

from ultralytics import YOLO

# Load a pretrained YOLO26 model
model = YOLO("yolo26n.pt")

# Specify the source image
source = "https://ultralytics.com/images/bus.jpg"

# Make predictions
results = model.predict(source, save=True, imgsz=320, conf=0.25)

# Extract bounding box dimensions
boxes = results[0].boxes.xywh.cpu()
for box in boxes:
    x, y, w, h = box
    print(f"Width of Box: {w}, Height of Box: {h}")

Problemi di distribuzione#

Problemi di distribuzione su GPU#

Problema: la distribuzione dei modelli in un ambiente multi-GPU può talvolta causare comportamenti imprevisti, come un utilizzo imprevisto della memoria o risultati incoerenti tra le GPU.

Soluzione: controlla l'inizializzazione predefinita della GPU. Alcuni framework, come PyTorch, potrebbero inizializzare le operazioni CUDA su una GPU predefinita prima di passare alle GPU designate. Per evitare inizializzazioni predefinite impreviste, specifica direttamente la GPU durante la distribuzione e l'esecuzione delle previsioni. Usa quindi degli strumenti per monitorare in tempo reale l'utilizzo della GPU e della memoria e individuare eventuali anomalie. Assicurati inoltre di usare la versione più recente del framework o della libreria.

Problemi di conversione/esportazione dei modelli#

Problema: durante la conversione o l'esportazione dei modelli di machine learning in formati o piattaforme diversi, potresti incontrare errori o comportamenti imprevisti.

Soluzione: consulta i formati supportati e le opzioni disponibili per ciascun formato nella documentazione della modalità di esportazione, quindi esegui questi controlli:

• Controllo della compatibilità: assicurati di usare versioni di librerie e framework compatibili tra loro. Le versioni non corrispondenti possono causare errori imprevisti durante la conversione.
• Ripristino dell'ambiente: se usi un ambiente interattivo come Jupyter o Colab, valuta di riavviarlo dopo modifiche o installazioni importanti. Ripartire da un ambiente pulito può talvolta risolvere problemi sottostanti.
• Documentazione ufficiale: fai sempre riferimento alla documentazione ufficiale dello strumento o della libreria che usi per la conversione. Spesso include indicazioni specifiche e best practice per l'esportazione dei modelli.
• Supporto della community: controlla il repository ufficiale della libreria o del framework per verificare se altri utenti hanno segnalato problemi simili. I responsabili della manutenzione o la community potrebbero aver fornito soluzioni o metodi alternativi nelle discussioni.
• Aggiornamenti regolari: assicurati di usare la versione più recente dello strumento o della libreria. Gli sviluppatori rilasciano spesso aggiornamenti che correggono bug noti o migliorano le funzionalità.
• Test incrementali: prima di eseguire una conversione completa, prova il processo con un modello o un dataset più piccolo per individuare per tempo eventuali problemi.

Community e supporto#

Chiedi aiuto e condividi soluzioni tramite questi canali e risorse.

Forum e canali per ricevere aiuto#

Segnalazioni su GitHub: Il repository di Ultralytics su GitHub ha una scheda Issues in cui puoi porre domande, segnalare bug e proporre nuove funzionalità. La community e i maintainer sono attivi e questo è un ottimo posto per ricevere aiuto su problemi specifici.

Server Discord di Ultralytics: Ultralytics ha un server Discord in cui puoi interagire con altri utenti e con gli sviluppatori.

Documentazione e risorse ufficiali#

Documentazione Ultralytics YOLO26: la documentazione ufficiale offre una panoramica completa di YOLO26 e include guide all'installazione, all'utilizzo e alla risoluzione dei problemi.

Conclusione#

La maggior parte dei problemi di YOLO26 dipende da poche cause: versioni incompatibili, formattazione del dataset e configurazione della GPU. Se qui non trovi un errore, cerca nella scheda GitHub Issues oppure chiedi sul server Discord: probabilmente qualcuno ha già trovato una soluzione. Per problemi più complessi di addestramento, consulta la guida ai consigli per l'addestramento dei modelli, che offre suggerimenti pratici per ottenere risultati migliori nei tuoi progetti di visione artificiale.

Domande frequenti#