Creare un esempio minimo riproducibile per le segnalazioni di bug
Quando invii una segnalazione di bug per i repository Ultralytics YOLO, è essenziale fornire un esempio minimo riproducibile (MRE). Un MRE è un frammento di codice piccolo e autonomo che mostra il problema riscontrato. Fornire un MRE aiuta i responsabili della manutenzione e i contributori a comprendere il problema e a lavorare più efficacemente a una soluzione. Questa guida spiega come creare un MRE quando invii segnalazioni di bug per i repository Ultralytics YOLO.
1. Isola il problema#
Il primo passaggio per creare un MRE consiste nell'isolare il problema. Rimuovi il codice o le dipendenze non direttamente correlati al problema. Concentrati sulla parte specifica del codice che causa il problema ed elimina le sezioni non pertinenti.
2. Usa modelli e dataset pubblici#
Quando crei un MRE, usa modelli e dataset disponibili pubblicamente per riprodurre il problema. Ad esempio, usa il modello YOLO26n (yolo26n.pt) e il dataset COCO8 (coco8.yaml). In questo modo, manutentori e collaboratori potranno eseguire facilmente il tuo esempio e analizzare il problema senza dover accedere a dati proprietari o modelli personalizzati.
3. Includi tutte le dipendenze necessarie#
Assicurati che il tuo MRE includa tutte le dipendenze necessarie. Se il codice si basa su librerie esterne, specifica i pacchetti richiesti e le relative versioni. Idealmente, elenca le dipendenze nella segnalazione di bug usando yolo checks se hai installato ultralytics, oppure pip list per altri strumenti.
4. Descrivi il problema in modo chiaro#
Descrivi il problema riscontrato in modo chiaro e conciso. Spiega il comportamento previsto e quello effettivo. Se pertinente, includi eventuali messaggi di errore o log rilevanti.
5. Formatta correttamente il codice#
Formatta correttamente il codice usando blocchi di codice nella descrizione del problema. Così sarà più facile per gli altri leggere e comprendere il codice. Su GitHub, puoi creare un blocco di codice racchiudendo il codice tra tre accenti gravi (```) e specificando il linguaggio:
```python
# Your Python code goes here
```6. Verifica il tuo MRE#
Prima di inviare il tuo MRE, verificalo per assicurarti che riproduca fedelmente il problema. Assicurati che gli altri possano eseguire il tuo esempio senza problemi né modifiche.
Esempio di MRE#
Ecco un esempio di MRE per una segnalazione di bug ipotetica:
Descrizione del bug:
Quando eseguo l'inferenza su un'immagine con 0 canali, ricevo un errore relativo alle dimensioni del tensore di input.
MRE:
import torch
from ultralytics import YOLO
# Carica il modello
model = YOLO("yolo26n.pt")
# Carica un'immagine con 0 canali
image = torch.rand(1, 0, 640, 640)
# Esegui il modello
results = model(image)Messaggio di errore:
RuntimeError: Expected input[1, 0, 640, 640] to have 3 channels, but got 0 channels insteadDipendenze:
torch==2.8.0ultralytics==8.4.142
In questo esempio, l'MRE mostra il problema con una quantità minima di codice, usa un modello pubblico ("yolo26n.pt"), include tutte le dipendenze necessarie e fornisce una descrizione chiara del problema insieme al messaggio di errore.
Seguendo queste indicazioni, aiuterai i manutentori e i collaboratori dei repository Ultralytics YOLO a comprendere e risolvere il tuo problema in modo più efficiente.
Domande frequenti#
Per creare un esempio minimo riproducibile (MRE) efficace per le segnalazioni di bug nei repository Ultralytics YOLO, segui questi passaggi:
- Isola il problema: rimuovi il codice o le dipendenze non direttamente correlati al problema.
- Usa modelli e dataset pubblici: utilizza risorse pubbliche come
yolo26n.ptecoco8.yamlper semplificare la riproducibilità. - Includi tutte le dipendenze necessarie: specifica i pacchetti richiesti e le relative versioni. Puoi elencare le dipendenze usando
yolo checksse hai installatoultralytics, oppurepip list. - Descrivi il problema in modo chiaro: spiega il comportamento previsto e quello effettivo, includendo eventuali messaggi di errore o log.
- Formatta correttamente il codice: usa i blocchi di codice per formattare il codice e renderlo più facile da leggere.
- Verifica il tuo MRE: assicurati che il tuo MRE riproduca il problema senza modifiche.
Per una guida dettagliata, consulta Creare un esempio minimo riproducibile.
Usare modelli e dataset disponibili pubblicamente nel tuo MRE permette ai responsabili della manutenzione di eseguire facilmente il tuo esempio senza dover accedere a dati proprietari. Questo consente di risolvere i problemi in modo più rapido ed efficiente. Ad esempio, usare il modello
yolo26n.pte il datasetcoco8.yamlaiuta a standardizzare e semplificare il processo di debug. Scopri di più sui modelli e dataset pubblici nella sezione Usa modelli e dataset pubblici.Una segnalazione di bug completa per Ultralytics YOLO dovrebbe includere:
- Descrizione chiara: spiega il problema, il comportamento previsto e quello effettivo.
- Messaggi di errore: includi eventuali messaggi di errore o log pertinenti.
- Dipendenze: elenca le dipendenze richieste e le relative versioni.
- MRE: fornisci un esempio minimo riproducibile.
- Passaggi per riprodurre il problema: descrivi i passaggi necessari per riprodurre il problema.
Per una checklist completa, consulta la sezione Descrivi il problema in modo chiaro.
Per formattare correttamente il codice quando invii una segnalazione di bug su GitHub:
- Usa tre accenti gravi (```) per creare blocchi di codice.
- Specifica il linguaggio di programmazione per evidenziare la sintassi, ad esempio ```python.
- Assicurati che il codice sia indentato correttamente per facilitarne la lettura.
Esempio:
```python # Your Python code goes here ```Per altri suggerimenti sulla formattazione del codice, consulta Formatta correttamente il codice.
Prima di inviare il tuo MRE, assicurati di:
- Verificare che il problema sia riproducibile.
- Assicurarti che tutte le dipendenze siano elencate e corrette.
- Rimuovere il codice non necessario.
- Verificare che il MRE riproduca il problema senza modifiche.
Per una checklist dettagliata, consulta la sezione Verifica il tuo MRE.
Commenti5
Fai una domanda, condividi i tuoi risultati o aiuta qualcun altro.
AVON257
Thanks for this, I'll get back to you as soon as I can, although it was the lvis dataset that produced these errors.
Does that make any difference?
On Wed, 26 Feb 2025, 17:00 Glenn Jocher, @.***> wrote:
@AVON257 https://github.com/AVON257 hi Tom, thanks for reporting this. To help us investigate, please create a Minimum Reproducible Example using the COCO8-OBB dataset and share your exact training/validation commands, dependency versions (yolo checks), and complete error logs. The validation logic is handled in the Val mode - you can review the source code in the Ultralytics repository.
For potential contributions, we welcome PRs that follow our Contributing Guide including signed CLA and Google-style docstrings. The community will appreciate your improvements to YOLO compatibility across hardware platforms.
— Reply to this email directly, view it on GitHub https://github.com/orgs/ultralytics/discussions/19445#discussioncomment-12328645, or unsubscribe https://github.com/notifications/unsubscribe-auth/AMWQGN6XUAOONBP7JBOKO7L2RXXLTAVCNFSM6AAAAABX5TFNQWVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTEMZSHA3DINI . You are receiving this because you were mentioned.Message ID: @.*** com>
Glenn JocherUltralytics@AVON257 hi there! While the LVIS dataset context is helpful, we still need a Minimum Reproducible Example with the COCO8-OBB dataset (or another public dataset) to efficiently investigate this issue. Please share your exact training/validation commands,
yolo checksoutput, and full error traceback when using a public dataset. This standardized approach helps us resolve issues faster for everyone. For MRE guidelines, see Creating a Minimum Reproducible Example. 😊
AVON257
Hi, I'd just like to mention that I have found a bug on the validation model (if it is a bug), where when I train a nano sized OBB model on YOLO 12 unfortunately it either produces Nan's during training or it won't validate on my RTX3090, even though it isn't showing that it's using too much memory when I try it with any batch size.
Any ideas on this?
Thanks,
Tom T.
P.S. I am actively working on combining this with quantum circuits but in order to do that, I need to be able to test it against the classical baseline, and curiously it seems okay on Colab when I tried it on an A100 but not on my RTX3090.
P.P.S. I would very much like to submit a commit to you once I finish my current work on the latest version of Ultralytics if you don't mind, although I should tell you that it will only work with optimal performance on Nvidia hardware at the moment. It can work on other things too, it just won't work as fast that way.
AVON257
In fact I would debug it myself if I could figure out which part of ultralytics deals with validation, any ideas?
Glenn JocherUltralytics@AVON257 hi Tom, thanks for reporting this. To help us investigate, please create a Minimum Reproducible Example using the COCO8-OBB dataset and share your exact training/validation commands, dependency versions (
yolo checks), and complete error logs. The validation logic is handled in the Val mode - you can review the source code in the Ultralytics repository.For potential contributions, we welcome PRs that follow our Contributing Guide including signed CLA and Google-style docstrings. The community will appreciate your improvements to YOLO compatibility across hardware platforms.