Risoluzione dei problemi comuni con YOLO#

Questa guida copre i problemi più comuni che incontrerai lavorando con Ultralytics YOLO26, raggruppati in base a dove si verificano: installation, model training, prediction e deployment. Vai alla categoria che corrisponde al tuo errore, oppure consulta le FAQ per risposte rapide. Ogni voce indica il problema e una soluzione concreta che puoi applicare direttamente.

Problemi comuni#

Errori di installazione#

Gli errori di installazione possono derivare da vari motivi, come versioni incompatibili, dipendenze mancanti o configurazioni dell'ambiente non corrette. Per prima cosa, assicurati di fare quanto segue:

• Stai usando Python 3.8 o versioni successive come raccomandato.
• Assicurati di avere installato la versione corretta di PyTorch (1.8 o successiva).
• Valuta l'utilizzo di ambienti virtuali per evitare conflitti.
• Segui la official installation guide passo dopo passo.

Inoltre, ecco le soluzioni ai problemi comuni di installazione.

Errori di importazione o problemi di dipendenze#

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

• Installazione pulita: Partire da un'installazione pulita può risolvere problemi imprevisti, specialmente dopo aggiornamenti che modificano la struttura o la funzionalità del pacchetto.
• Aggiorna regolarmente: Utilizza l'ultima versione della libreria, poiché le versioni precedenti potrebbero non essere compatibili con gli aggiornamenti recenti.
• Controlla le dipendenze: Verifica che tutte le dipendenze necessarie siano installate correttamente e che le loro versioni siano compatibili.
• Rivedi i cambiamenti: Se hai installato una versione precedente, fai riferimento alla documentazione ufficiale o al changelog per comprendere eventuali modifiche strutturali importanti.

Esecuzione di YOLO26 su GPU#

Se hai difficoltà a eseguire YOLO26 su una GPU, prendi in considerazione 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 verificare 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 essere nell'ambiente corretto dove sono installati tutti i pacchetti necessari.
• Aggiorna i tuoi pacchetti: I pacchetti obsoleti potrebbero non essere compatibili con la tua GPU. Mantienili aggiornati.
• Configurazione del programma: controlla se il tuo codice richiede l'uso della GPU. Puoi impostare l'argomento device durante l'esecuzione dell'addestramento o della previsione (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#

I problemi comuni di addestramento e le relative soluzioni sono trattati qui di seguito.

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 dovrebbero essere applicate quando si utilizza la funzione model.train(). Per assicurarti che queste impostazioni siano applicate correttamente, segui questi passaggi:

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

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

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

Accelerare l'addestramento con più GPU#

Problema: L'addestramento è lento su una singola GPU e vuoi velocizzare il processo utilizzando più GPU.

Soluzione: aumentare la batch size può accelerare l'addestramento, ma è essenziale considerare la capacità di memoria della GPU. Per accelerare l'addestramento con multiple GPUs, segui questi passaggi:

• Assicurati di avere più GPU a disposizione.

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

• Aumenta la dimensione del batch di conseguenza per utilizzare appieno le molteplici GPU senza superare i limiti di memoria.

• Modifica il tuo 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 di monitoraggio continuo#

Problema: Vuoi sapere quali parametri dovrebbero essere monitorati continuamente durante l'addestramento, oltre alla perdita (loss).

Soluzione: Sebbene la perdita sia una metrica cruciale da monitorare, è anche essenziale tracciare altre metriche per l'ottimizzazione delle prestazioni del modello. Alcune metriche chiave da monitorare durante l'addestramento includono:

• Precision
• Recall
• Mean Average Precision (mAP)

Puoi accedere a queste metriche dai log di addestramento o utilizzando strumenti come TensorBoard o wandb per la visualizzazione. Implementare l'interruzione anticipata (early stopping) basata su queste metriche può aiutarti a ottenere risultati migliori.

Strumenti per il tracciamento del progresso dell'addestramento#

Problema: Stai cercando consigli su strumenti per tracciare il progresso dell'addestramento.

Soluzione: Per tracciare e visualizzare il progresso dell'addestramento, puoi prendere in considerazione l'utilizzo dei seguenti strumenti:

• TensorBoard: TensorBoard è una scelta popolare per visualizzare le metriche di addestramento, inclusi perdita, accuracy e altro. Puoi integrarlo con il tuo processo di addestramento YOLO26.
• Comet: Comet offre un set di strumenti esteso per il tracciamento e il confronto degli esperimenti. Ti consente di tracciare metriche, iperparametri e persino i pesi del modello. L'integrazione con i modelli YOLO è inoltre semplice e ti offre una panoramica completa del ciclo dei tuoi esperimenti.
• Ultralytics Platform: Ultralytics Platform offre un ambiente specializzato per il tracciamento dei modelli YOLO, fornendoti una piattaforma centralizzata per gestire metriche, dataset e persino collaborare con il tuo team. Dato il suo focus mirato su YOLO, offre opzioni di tracciamento più personalizzate.

Come verificare se l'addestramento sta avvenendo sulla GPU#

Problema: Il valore 'device' nei log di addestramento è 'null' e non sei sicuro se l'addestramento stia avvenendo sulla GPU.

Soluzione: il valore 'device' impostato su 'null' significa tipicamente 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 quando avvii l'addestramento. device è un argomento di addestramento, quindi impostarlo nel .yaml del tuo 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 log e metriche per monitorare efficacemente il progresso dell'addestramento.

Considerazioni chiave per un addestramento efficace del modello#

Ecco alcune cose da tenere a mente, se stai affrontando 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 aderiscano al formato previsto. È cruciale verificare che le annotazioni siano accurate e di alta qualità. Annotazioni errate o di scarsa qualità possono compromettere il processo di apprendimento del modello, portando a risultati imprevedibili.

Convergenza del modello

• Importanza: raggiungere la convergenza del modello assicura che il modello abbia imparato a Sufficienza dai training data.
• Raccomandazione: quando addestri un modello 'da zero' (from scratch), è fondamentale assicurarsi che il modello raggiunga un livello soddisfacente di convergenza. Ciò potrebbe richiedere una durata di addestramento più lunga, con più epochs, rispetto a quando stai eseguendo il fine-tuning di un modello esistente.

Learning Rate e Batch Size

• Importanza: Questi iperparametri giocano un ruolo fondamentale nel determinare come il modello aggiorna i suoi pesi durante l'addestramento.
• Raccomandazione: Valuta regolarmente se il learning rate e la dimensione del batch scelti sono 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 di previsione del modello.
• Raccomandazione: Valuta regolarmente la distribuzione delle classi all'interno del tuo dataset. Se c'è uno squilibrio di classe, c'è il rischio che il modello sviluppi un pregiudizio verso la classe più prevalente. Questo pregiudizio può essere evidente nella matrice di confusione, dove il modello potrebbe prevedere prevalentemente la classe di maggioranza.

Verifica incrociata con pesi pre-addestrati

• Importanza: Sfruttare pesi pre-addestrati può fornire un solido punto di partenza per l'addestramento del modello, specialmente quando i dati sono limitati.
• Raccomandazione: Come passaggio diagnostico, considera di addestrare il tuo modello utilizzando gli stessi dati ma inizializzandolo con pesi pre-addestrati. Se questo approccio produce una matrice di confusione ben formata, potrebbe suggerire che il modello 'da zero' potrebbe richiedere ulteriore addestramento o aggiustamenti.

Problemi relativi alle previsioni del modello#

I problemi comuni riscontrati durante la predizione del modello e le relative soluzioni sono trattati qui di seguito.

Ottenere previsioni di bounding box con il tuo modello personalizzato YOLO26#

Problema: Quando si eseguono previsioni con un modello YOLO26 personalizzato, ci sono sfide con il formato e la visualizzazione delle coordinate del bounding box.

Soluzione:

• Formato delle coordinate: YOLO26 fornisce coordinate del bounding box in valori di pixel assoluti. Per convertirle in coordinate relative (che vanno da 0 a 1), devi dividere per le dimensioni dell'immagine. Ad esempio, diciamo che la dimensione della tua immagine è 640x640. Allora dovresti fare 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 effettuando la previsione, accedi direttamente al percorso del file immagine dall'oggetto risultato all'interno del tuo ciclo di previsione.

Filtrare oggetti nelle previsioni di YOLO26#

Problema: Affrontare problemi su come filtrare e visualizzare solo oggetti specifici nei risultati di previsione quando si esegue YOLO26 utilizzando la libreria Ultralytics.

Soluzione: Per rilevare classi specifiche usa l'argomento classes per specificare le classi che vuoi includere nell'output. Ad esempio, per rilevare solo le auto (assumendo che le 'auto' abbiano indice di classe 2):

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

Comprendere le metriche di precisione in YOLO26#

Problema: confusione riguardo alla differenza tra precisione del box, precisione della maschera e precisione della confusion matrix in YOLO26.

Soluzione: la precisione del box misura l'accuratezza dei bounding box predetti rispetto ai box di ground truth reali usando l'IoU (Intersection over Union) come metrica. La precisione della maschera valuta la corrispondenza tra le maschere di segmentazione predette e le maschere di ground truth nella classificazione degli oggetti a livello di pixel. La precisione della matrice di confusione, d'altra parte, si concentra sull'accuratezza di classificazione complessiva su tutte le classi e non considera l'accuratezza geometrica delle previsioni. È importante notare che un bounding box può essere geometricamente accurato (vero positivo) anche se la previsione della classe è errata, portando a differenze tra la precisione del box e la precisione della matrice di confusione. Queste metriche valutano aspetti distinti delle prestazioni di un modello, riflettendo la necessità di diverse metriche di valutazione in vari compiti.

Estrarre le dimensioni dell'oggetto in YOLO26#

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

Soluzione: per recuperare le dimensioni del bounding box, usa prima il modello Ultralytics YOLO26 per predict objects in un'immagine. Quindi, estrai le informazioni su larghezza e altezza dei bounding box 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}")

Sfide di distribuzione#

Problemi di distribuzione GPU#

Problema: Distribuire modelli in un ambiente multi-GPU può talvolta portare a comportamenti imprevisti come uso di memoria imprevisto, risultati incoerenti tra le GPU, ecc.

Soluzione: Controlla l'inizializzazione predefinita della GPU. Alcuni framework, come PyTorch, potrebbero inizializzare 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 previsione. Quindi, usa strumenti per monitorare l'utilizzo della GPU e l'uso della memoria per identificare eventuali anomalie in tempo reale. Inoltre, assicurati di utilizzare l'ultima versione del framework o della libreria.

Problemi di conversione/esportazione del modello#

Problema: Durante il processo di conversione o esportazione di modelli di machine learning verso formati o piattaforme diverse, gli utenti potrebbero riscontrare errori o comportamenti imprevisti.

Soluzione: rivedi i formati supportati e le opzioni per formato nella documentazione della Export mode, quindi procedi con questi controlli:

• Controllo di compatibilità: Assicurati di utilizzare versioni di librerie e framework che siano compatibili tra loro. Versioni non corrispondenti possono portare a errori imprevisti durante la conversione.
• Ripristino dell'ambiente: Se stai utilizzando un ambiente interattivo come Jupyter o Colab, valuta di riavviare il tuo ambiente dopo aver apportato cambiamenti o installazioni significative. Un nuovo inizio può talvolta risolvere problemi sottostanti.
• Documentazione ufficiale: Fai sempre riferimento alla documentazione ufficiale dello strumento o della libreria che stai utilizzando per la conversione. Contiene spesso linee guida specifiche e migliori pratiche per l'esportazione del modello.
• Supporto della community: Controlla il repository ufficiale della libreria o del framework per problemi simili segnalati da altri utenti. I manutentori o la community potrebbero aver fornito soluzioni o soluzioni alternative nei thread di discussione.
• Aggiorna regolarmente: Assicurati di utilizzare l'ultima versione dello strumento o della libreria. Gli sviluppatori rilasciano frequentemente aggiornamenti che correggono bug noti o migliorano la funzionalità.
• Testa in modo incrementale: Prima di eseguire una conversione completa, testa il processo con un modello o un dataset più piccolo per identificare potenziali problemi fin dall'inizio.

Community e supporto#

Ottieni aiuto e condividi soluzioni attraverso questi canali e risorse.

Forum e canali per ottenere aiuto#

GitHub Issues: Il repository YOLO26 su GitHub ha una Issues tab 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.

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

Documentazione ufficiale e risorse#

Ultralytics YOLO26 Docs: la official documentation fornisce una panoramica completa di YOLO26, insieme a guide su installazione, utilizzo e risoluzione dei problemi.

Conclusione#

La maggior parte dei problemi di YOLO26 è riconducibile a un pugno di cause: disallineamenti di versione, formattazione del dataset e configurazione della GPU. Quando un errore non è coperto qui, cerca nella scheda GitHub Issues o chiedi sul Discord server — è probabile che qualcuno lo abbia già risolto. Per problemi di training più complessi, consulta la guida Model Training Tips per consigli pratici su come ottenere risultati migliori con i tuoi progetti di computer vision.

FAQ#