Commencer

Créer un exemple minimal reproductible pour les rapports de bogues

Lorsque tu soumets un rapport de bogue pour les dépôts Ultralytics YOLO, il est essentiel de fournir un exemple minimal reproductible (MRE). Un MRE est un petit extrait de code autonome qui illustre le problème rencontré. Fournir un MRE aide les responsables de maintenance et les contributeurs à comprendre le problème et à travailler plus efficacement à sa résolution. Ce guide explique comment créer un MRE lors de la soumission de rapports de bogues pour les dépôts Ultralytics YOLO.

1. Isoler le problème#

La première étape de la création d’un MRE consiste à isoler le problème. Supprime tout code ou dépendance inutile qui n’est pas directement lié au problème. Concentre-toi sur la partie précise du code qui provoque le problème et élimine les sections sans rapport.

2. Utiliser des modèles et des jeux de données publics#

Pour créer un MRE, utilise des modèles et des jeux de données accessibles au public afin de reproduire le problème. Par exemple, utilise le modèle YOLO26n (yolo26n.pt) et le jeu de données COCO8 (coco8.yaml). Ainsi, les responsables de la maintenance et les contributeurs peuvent facilement exécuter ton exemple et examiner le problème sans avoir accès à des données propriétaires ni à des modèles personnalisés.

3. Inclure toutes les dépendances nécessaires#

Veille à inclure toutes les dépendances nécessaires dans ton MRE. Si ton code s’appuie sur des bibliothèques externes, indique les paquets requis et leurs versions. Dans l’idéal, liste les dépendances dans ton rapport de bogue avec yolo checks si ultralytics est installé, ou avec pip list pour les autres outils.

4. Décrire clairement le problème#

Décris clairement et brièvement le problème rencontré. Explique le comportement attendu et le comportement observé. Le cas échéant, inclus les messages d’erreur ou les journaux pertinents.

5. Formater correctement ton code#

Formate correctement ton code à l’aide de blocs de code dans la description du problème. Cela permet aux autres de lire et de comprendre ton code plus facilement. Sur GitHub, tu peux créer un bloc de code en encadrant ton code de trois accents graves (```) et en indiquant le langage :

```python
# Your Python code goes here
```

6. Tester ton MRE#

Avant de soumettre ton MRE, teste-le pour vérifier qu’il reproduit fidèlement le problème. Assure-toi que les autres peuvent exécuter ton exemple sans problème ni modification.

Exemple de MRE#

Voici un exemple de MRE pour un rapport de bogue hypothétique :

Description du bogue :

Lors d’une inférence sur une image à 0 canal, je reçois une erreur liée aux dimensions du tenseur d’entrée.

MRE :

import torch

from ultralytics import YOLO

# Charger le modèle
model = YOLO("yolo26n.pt")

# Charger une image à 0 canal
image = torch.rand(1, 0, 640, 640)

# Exécuter le modèle
results = model(image)

Message d’erreur :

RuntimeError: Expected input[1, 0, 640, 640] to have 3 channels, but got 0 channels instead

Dépendances :

  • torch==2.8.0
  • ultralytics==8.4.142

Dans cet exemple, le MRE illustre le problème avec un minimum de code, utilise un modèle public ("yolo26n.pt"), inclut toutes les dépendances nécessaires et décrit clairement le problème avec le message d’erreur.

En suivant ces consignes, tu aideras les responsables de la maintenance et les contributeurs des dépôts Ultralytics YOLO à comprendre et à résoudre ton problème plus efficacement.

FAQ#

  • Pour créer un exemple minimal reproductible (MRE) efficace destiné aux rapports de bogues dans les dépôts Ultralytics YOLO, suis ces étapes :

    1. Isoler le problème : supprime tout code ou dépendance qui n’est pas directement lié au problème.
    2. Utilise des modèles et des jeux de données publics : utilise des ressources publiques comme yolo26n.pt et coco8.yaml pour faciliter la reproductibilité.
    3. Inclure toutes les dépendances nécessaires : indique les paquets requis et leurs versions. Tu peux répertorier les dépendances avec yolo checks si ultralytics est installé, ou avec pip list.
    4. Décrire clairement le problème : explique le comportement attendu et le comportement observé, en incluant les messages d’erreur ou les journaux éventuels.
    5. Formater correctement ton code : utilise des blocs de code pour le mettre en forme et le rendre plus facile à lire.
    6. Tester ton MRE : vérifie que ton MRE reproduit le problème sans modification.

    Pour obtenir un guide détaillé, consulte Créer un exemple minimal reproductible.

  • L’utilisation de modèles et de jeux de données accessibles au public dans ton MRE permet aux responsables de maintenance d’exécuter facilement ton exemple sans avoir besoin d’accéder à des données propriétaires. Cela accélère et améliore la résolution des problèmes. Par exemple, l’utilisation du modèle yolo26n.pt et du jeu de données coco8.yaml contribue à normaliser et à simplifier le processus de débogage. Pour en savoir plus sur les modèles et les jeux de données publics, consulte la section Utiliser des modèles et des jeux de données publics.

  • Un rapport de bogue complet pour Ultralytics YOLO doit inclure :

    • Description claire : explique le problème, le comportement attendu et le comportement observé.
    • Messages d’erreur : inclus les messages d’erreur ou les journaux pertinents.
    • Dépendances : liste les dépendances requises et leurs versions.
    • MRE : fournis un exemple minimal reproductible.
    • Étapes de reproduction : détaille les étapes nécessaires pour reproduire le problème.

    Pour obtenir une liste de vérification complète, consulte la section Décrire clairement le problème.

  • Pour formater correctement ton code lorsque tu soumets un rapport de bogue sur GitHub :

    • Utilise trois accents graves (```) pour créer des blocs de code.
    • Indique le langage de programmation pour la coloration syntaxique, par exemple : ```python.
    • Veille à ce que ton code soit correctement indenté pour en faciliter la lecture.

    Exemple :

    ```python
    # Your Python code goes here
    ```

    Pour obtenir d’autres conseils sur la mise en forme du code, consulte Formater correctement ton code.

  • Avant de soumettre ton MRE, veille à :

    • Vérifier que le problème est reproductible.
    • Vérifier que toutes les dépendances sont répertoriées et correctes.
    • Supprimer tout code inutile.
    • Tester le MRE pour vérifier qu’il reproduit le problème sans modification.

    Pour obtenir une liste de vérification détaillée, consulte la section Tester ton MRE.

Commentaires5

Pose une question, partage tes résultats ou aide quelqu’un d’autre.

  1. AVON257GitHub

    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>

    1. 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 checks output, 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. 😊

  2. AVON257GitHub

    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.

    1. AVON257GitHub

      In fact I would debug it myself if I could figure out which part of ultralytics deals with validation, any ideas?

    2. 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.