Risoluzione dei problemi comuni di YOLO#

Questa guida tratta i problemi più comuni che potresti incontrare lavorando con Ultralytics YOLO26, raggruppati in base al punto in cui si verificano: installazione, addestramento del modello, predizione e distribuzione. Vai direttamente 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, come versioni incompatibili, dipendenze mancanti o configurazioni dell'ambiente errate. Per prima cosa, verifica di eseguire le operazioni seguenti:

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

Inoltre, ecco 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:

• Installazione pulita: partire da un'installazione pulita può risolvere problemi imprevisti, soprattutto dopo aggiornamenti che modificano la struttura o le funzionalità del pacchetto.
• Aggiorna regolarmente: usa la versione più recente della libreria, poiché le versioni precedenti potrebbero non essere compatibili con gli aggiornamenti recenti.
• Controlla le dipendenze: verifica che tutte le dipendenze richieste siano installate correttamente e abbiano versioni compatibili.
• Esamina le modifiche: se hai installato una versione precedente, consulta la documentazione ufficiale o il changelog per comprendere eventuali modifiche strutturali importanti.

Esecuzione di YOLO26 su GPU#

Se riscontri problemi nell'esecuzione di YOLO26 su una GPU, valuta i seguenti passaggi per la risoluzione dei problemi:

• Verifica la compatibilità e l'installazione di CUDA: assicurati che la tua GPU sia compatibile con CUDA e che CUDA sia installato correttamente. Usa il comando nvidia-smi per controllare lo stato della tua GPU NVIDIA e la versione di CUDA.
• Controlla l'integrazione tra PyTorch e CUDA: assicurati che PyTorch possa utilizzare 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: verifica che il tuo codice richieda l'utilizzo 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 sono descritti i problemi di addestramento più comuni e le relative soluzioni.

Verifica delle impostazioni di configurazione#

Problema: non sei sicuro che le impostazioni di configurazione nel file .yaml vengano applicate correttamente durante l'addestramento del modello.

Soluzione: le impostazioni di configurazione nel file .yaml devono essere applicate quando si usa la funzione model.train(). Per assicurarti che queste impostazioni vengano applicate correttamente, segui questi passaggi:

• Conferma che il percorso del file di configurazione .yaml sia corretto.

• Assicurati di passare il percorso del file .yaml come argomento data quando chiami model.train(), come mostrato di seguito:

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

Accelerazione dell'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 è fondamentale 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 di conseguenza la dimensione del batch per utilizzare pienamente più GPU senza superare i limiti di memoria.

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

  # Adjust the batch size and other settings as needed to optimize training speed
  model.train(data="/path/to/your/data.yaml", batch=32, device=[0, 1, 2, 3])

Parametri da monitorare continuamente#

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

Soluzione: sebbene la loss sia una metrica fondamentale da monitorare, è altrettanto importante tenere sotto controllo altre metriche per ottimizzare le prestazioni del modello. Tra le metriche chiave da monitorare durante l'addestramento figurano:

• Precision
• Recall
• Precisione media media (mAP)

Puoi accedere a queste metriche dai log di addestramento o utilizzando strumenti come TensorBoard o Weights & Biases per la visualizzazione. L'implementazione dell'arresto anticipato (early stopping) basato su queste metriche può aiutarti a ottenere risultati migliori.

Strumenti per monitorare l'avanzamento dell'addestramento#

Problema: cerchi consigli sugli strumenti per monitorare l'avanzamento dell'addestramento.

Soluzione: per monitorare e visualizzare l'avanzamento dell'addestramento, puoi valutare l'utilizzo dei seguenti strumenti:

• TensorBoard: TensorBoard è una scelta diffusa per visualizzare le metriche di addestramento, tra cui la loss, l'accuratezza e altro ancora. Puoi integrarlo nel processo di addestramento di YOLO26.
• Comet: Comet offre un'ampia gamma di strumenti per il monitoraggio e il confronto degli esperimenti. Ti permette di monitorare metriche, iperparametri e persino i pesi del modello. L'integrazione con i modelli YOLO è inoltre semplice e ti offre una panoramica completa del ciclo del tuo esperimento.
• Ultralytics Platform: Ultralytics Platform offre un ambiente specializzato per monitorare i modelli YOLO, fornendoti una piattaforma unica per gestire metriche e dataset e collaborare con il tuo team. Grazie alla sua attenzione specifica per YOLO, offre opzioni di monitoraggio più personalizzate.

Come verificare se l'addestramento avviene sulla GPU#

Problema: il valore 'device' nei log dell'addestramento è 'null' e non sai se l'addestramento sta avvenendo sulla GPU.

Soluzione: in genere, il valore 'device' impostato su 'null' significa che il processo di addestramento è configurato per selezionare automaticamente una GPU disponibile, comportamento predefinito. Per eseguire l'addestramento su una GPU specifica, imposta l'argomento device quando avvii l'addestramento. device è un argomento di addestramento, quindi impostarlo in .yaml del dataset non ha alcun effetto:

from ultralytics import YOLO

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

# Use GPU 0; device=[0, 1] for multiple GPUs, device="cpu" for CPU
model.train(data="path/to/data.yaml", device=0)

Tieni d'occhio la cartella 'runs' per consultare log e metriche e monitorare efficacemente l'avanzamento dell'addestramento.

Considerazioni chiave 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 risiedono nella qualità e nel formato dei dati su cui viene addestrato.
• Raccomandazione: 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 di qualità insufficiente possono compromettere il processo di apprendimento del modello e portare a risultati imprevedibili.

Convergenza del modello

• Importanza: ottenere la convergenza del modello garantisce che il modello abbia appreso a sufficienza dai dati di addestramento.
• Raccomandazione: quando addestri un modello 'da zero', è fondamentale assicurarti che raggiunga un livello di convergenza soddisfacente. Potrebbe essere necessario un addestramento più lungo, con più epoche, rispetto al fine-tuning di un modello esistente.

Learning Rate e dimensione del batch

• Importanza: questi iperparametri svolgono un ruolo fondamentale nel determinare il modo in cui il modello aggiorna i propri pesi durante l'addestramento.
• Raccomandazione: valuta regolarmente se il learning rate e la dimensione del batch scelti siano ottimali per il tuo dataset specifico. Parametri non in armonia con le caratteristiche del dataset possono ostacolare le prestazioni del modello.

Distribuzione delle classi

• Importanza: la distribuzione delle classi nel tuo dataset può influenzare le tendenze del modello durante la predizione.
• Raccomandazione: valuta regolarmente la distribuzione delle classi nel tuo dataset. In presenza di uno sbilanciamento tra le classi, il modello potrebbe sviluppare una preferenza per la classe più frequente. Questo bias può essere evidente 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 un solido punto di partenza 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 strutturata, potrebbe indicare che il modello addestrato 'da zero' necessita di ulteriore addestramento o di alcune modifiche.

Problemi relativi alle predizioni del modello#

Di seguito sono descritti i problemi più comuni riscontrati durante la predizione del modello e le relative soluzioni.

Ottenere predizioni delle bounding box con il tuo modello YOLO26 personalizzato#

Problema: durante l'esecuzione delle predizioni con un modello YOLO26 personalizzato, si riscontrano difficoltà nel formato e nella visualizzazione delle coordinate delle bounding box.

Soluzione:

• Formato delle coordinate: YOLO26 fornisce le coordinate delle bounding box in valori assoluti dei pixel. Per convertirle in coordinate relative (comprese tra 0 e 1), devi dividerle per le dimensioni dell'immagine. Ad esempio, supponiamo che la dimensione dell'immagine sia 640x640. Dovrai quindi eseguire quanto segue:

  # Convert absolute coordinates to relative coordinates
  x1 = x1 / 640  # Divide x-coordinates by image width
  x2 = x2 / 640
  y1 = y1 / 640  # Divide y-coordinates by image height
  y2 = y2 / 640

• Nome del file: per ottenere il nome del file dell'immagine su cui stai eseguendo la predizione, accedi direttamente al percorso del file immagine dall'oggetto del risultato all'interno del ciclo di predizione.

Filtrare gli oggetti nelle predizioni di YOLO26#

Problema: riscontri difficoltà nel filtrare e visualizzare solo oggetti specifici nei risultati della predizione quando esegui YOLO26 usando la libreria Ultralytics.

Soluzione: per rilevare classi specifiche, usa l'argomento classes per specificare le classi da includere nell'output. Ad esempio, per rilevare solo le automobili (supponendo che 'automobili' abbia l'indice di classe 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: non è chiara la differenza tra la precisione delle box, la precisione delle maschere e la precisione della matrice di confusione in YOLO26.

Soluzione: la precisione delle box misura l'accuratezza delle bounding box predette rispetto alle box di riferimento effettive, usando IoU (Intersezione sull'unione) come metrica. La precisione delle maschere valuta la concordanza tra le maschere di segmentazione predette e le maschere di riferimento nella classificazione degli oggetti a livello di pixel. La precisione della matrice di confusione, invece, si concentra sull'accuratezza complessiva della classificazione per tutte le classi e non considera l'accuratezza geometrica delle predizioni. È importante notare che una bounding box può essere geometricamente accurata (vero positivo) anche se la predizione della classe è errata, causando differenze tra la precisione delle box e quella della matrice di confusione. Queste metriche valutano aspetti distinti delle prestazioni del modello e riflettono la necessità di metriche di valutazione diverse per attività differenti.

Estrarre le dimensioni degli oggetti in YOLO26#

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

Soluzione: per recuperare le dimensioni delle bounding box, usa prima il modello Ultralytics YOLO26 per predire gli oggetti in un'immagine. Quindi, estrai le informazioni relative alla larghezza e all'altezza delle bounding box dai risultati della predizione.

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 con più GPU può talvolta causare comportamenti imprevisti, come un utilizzo inatteso della memoria, risultati incoerenti tra le GPU e così via.

Soluzione: verifica 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 la predizione. Usa quindi strumenti per monitorare in tempo reale l'utilizzo della GPU e della memoria, così da identificare eventuali anomalie. Assicurati inoltre di usare la versione più recente del framework o della libreria.

Problemi di conversione/esportazione del modello#

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

Soluzione: consulta i formati supportati e le opzioni specifiche per formato nella documentazione della modalità di esportazione, quindi esegui queste verifiche:

• Verifica della compatibilità: assicurati di usare versioni di librerie e framework compatibili tra loro. Versioni non corrispondenti possono causare errori imprevisti durante la conversione.
• Ripristino dell'ambiente: se usi un ambiente interattivo come Jupyter o Colab, valuta di riavviare l'ambiente dopo modifiche o installazioni significative. Un nuovo avvio può talvolta risolvere problemi sottostanti.
• Documentazione ufficiale: consulta sempre la documentazione ufficiale dello strumento o della libreria che usi per la conversione. Spesso contiene linee guida specifiche e best practice per l'esportazione dei modelli.
• Supporto della community: controlla il repository ufficiale della libreria o del framework per trovare problemi simili segnalati da altri utenti. I responsabili del progetto o la community potrebbero aver fornito soluzioni o alternative nelle discussioni.
• Aggiorna regolarmente: assicurati di usare la versione più recente dello strumento o della libreria. Gli sviluppatori rilasciano frequentemente aggiornamenti che correggono bug noti o migliorano le funzionalità.
• Test incrementali: prima di eseguire una conversione completa, testa il processo con un modello o un dataset più piccoli per identificare tempestivamente i potenziali problemi.

Community e supporto#

Ottieni assistenza e condividi soluzioni attraverso questi canali e queste risorse.

Forum e canali per ricevere assistenza#

Problemi su GitHub: Il repository di Ultralytics su GitHub ha una scheda Problemi in cui puoi fare domande, segnalare bug e suggerire nuove funzionalità. La community e i maintainer sono attivi qui, ed è un ottimo posto per ricevere aiuto con problemi specifici.

Server Discord di Ultralytics: Ultralytics ha un server Discord dove 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, insieme a guide sull'installazione, l'utilizzo e la risoluzione dei problemi.

Conclusioni#

La maggior parte dei problemi di YOLO26 è riconducibile a una manciata di cause: incompatibilità tra versioni, formattazione del dataset e configurazione della GPU. Quando un errore non è trattato qui, cerca nella scheda Issues di GitHub o chiedi sul server Discord: è probabile che qualcuno abbia già risolto il problema. Per problemi più approfonditi di addestramento, consulta la guida Suggerimenti per l'addestramento dei modelli per consigli pratici su come ottenere risultati migliori nei tuoi progetti di computer vision.

FAQ#