はじめる

バグ報告用の最小再現例を作成する

UltralyticsのYOLOリポジトリにバグを報告する際は、最小再現例(MRE)を提示することが重要です。MREは、発生している問題を示す、小規模で自己完結したコードです。MREを提示すると、メンテナーや貢献者が問題を理解し、より効率的に修正に取り組めます。このガイドでは、Ultralytics YOLOリポジトリにバグを報告する際のMREの作成方法を説明します。

1. 問題を切り分ける#

MREを作成する最初の手順は、問題を切り分けることです。問題に直接関係のないコードや依存関係を削除してください。問題の原因となっているコード部分に焦点を当て、関係のない箇所を取り除いてください。

2. 公開モデルとデータセットを使用する#

MREを作成する際は、問題を再現するために一般公開されているモデルとデータセットを使用してください。たとえば、YOLO26nモデル(yolo26n.pt)とCOCO8データセット(coco8.yaml)を使用します。これにより、メンテナーやコントリビューターは、独自データやカスタムモデルにアクセスすることなく、サンプルを簡単に実行して問題を調査できます。

3. 必要な依存関係をすべて含める#

MREに必要な依存関係をすべて含めてください。コードが外部ライブラリに依存している場合は、必要なパッケージとそのバージョンを明記してください。理想的には、yolo checksを使用してバグレポートに依存関係を記載し、ultralyticsがインストールされている場合はその方法を、その他のツールにはpip listを使用してください。

4. 問題を明確に説明する#

発生している問題を明確かつ簡潔に説明してください。期待される動作と、実際に発生している動作を説明してください。該当する場合は、関連するエラーメッセージやログも記載してください。

5. コードを適切にフォーマットする#

問題の説明では、コードブロックを使用してコードを適切にフォーマットしてください。これにより、他の人がコードを読み、理解しやすくなります。GitHubでは、コードを3つのバッククォート(```)で囲み、言語を指定してコードブロックを作成できます。

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

6. MREをテストする#

MREを提出する前にテストし、問題を正確に再現することを確認してください。他の人が問題や変更を加えずに例を実行できることを確認してください。

MREの例#

以下は、仮想的なバグ報告におけるMREの例です。

バグの説明:

0チャンネルの画像で推論を実行すると、入力テンソルの次元に関するエラーが発生します。

MRE:

import torch

from ultralytics import YOLO

# モデルを読み込みます
model = YOLO("yolo26n.pt")

# 0チャンネルの画像を読み込む
image = torch.rand(1, 0, 640, 640)

# モデルを実行する
results = model(image)

エラーメッセージ:

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

依存関係:

  • torch==2.8.0
  • ultralytics==8.4.142

この例のMREは、最小限のコードで問題を示し、公開モデル("yolo26n.pt")を使用し、必要な依存関係をすべて含み、エラーメッセージとともに問題を明確に説明しています。

これらのガイドラインに従うことで、Ultralytics YOLOリポジトリのメンテナーやコントリビューターが問題を理解し、より効率的に解決できるようになります。

よくある質問#

  • Ultralytics YOLOリポジトリのバグ報告に効果的な最小再現例(MRE)を作成するには、次の手順に従ってください。

    1. 問題を切り分ける:問題に直接関係のないコードや依存関係を削除してください。
    2. 公開モデルとデータセットを使用する:再現性を高めるため、yolo26n.ptやcoco8.yamlなどの公開リソースを使用してください。
    3. 必要な依存関係をすべて含める:必要なパッケージとそのバージョンを明記してください。ultralyticsをインストールしている場合はyolo checksを、それ以外の場合はpip listを使用して依存関係を記載できます。
    4. 問題を明確に説明する:エラーメッセージやログも含め、期待される動作と実際の動作を説明してください。
    5. コードを適切にフォーマットする:コードブロックを使ってコードをフォーマットし、読みやすくしてください。
    6. MREをテストする:変更を加えなくてもMREで問題を再現できることを確認してください。

    詳しいガイドについては、最小再現例の作成をご覧ください。

  • MREに公開されているモデルやデータセットを使用すると、メンテナーは独自データにアクセスすることなく、例を簡単に実行できます。そのため、問題をより迅速かつ効率的に解決できます。たとえば、yolo26n.ptモデルとcoco8.yamlデータセットを使用すると、デバッグの手順を標準化し、簡素化できます。公開モデルとデータセットについて詳しくは、公開モデルとデータセットを使用するセクションをご覧ください。

  • Ultralytics YOLOの包括的なバグ報告には、次の内容を含めてください。

    • 明確な説明:問題、期待される動作、実際の動作を説明してください。
    • エラーメッセージ:関連するエラーメッセージやログを記載してください。
    • 依存関係:必要な依存関係とそのバージョンを列挙してください。
    • MRE:最小再現例を提示してください。
    • 再現手順:問題の再現に必要な手順を説明してください。

    チェックリスト全体については、問題を明確に説明するセクションをご覧ください。

  • GitHubでバグを報告するときにコードを適切にフォーマットするには、次のようにします。

    • 3つのバッククォート(```)を使ってコードブロックを作成します。
    • 構文をハイライト表示するため、```pythonのようにプログラミング言語を指定します。
    • 読みやすさを考慮して、コードが正しくインデントされていることを確認します。

    例:

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

    コードのフォーマットに関するヒントについては、コードを適切にフォーマットするをご覧ください。

  • MREを提出する前に、次の点を確認してください。

    • 問題を再現できることを確認します。
    • すべての依存関係が正しく記載されていることを確認します。
    • 不要なコードを削除します。
    • 変更を加えなくても問題を再現できることを確認するため、MREをテストします。

    詳しいチェックリストについては、MREをテストするセクションをご覧ください。

コントリビューター

コメント5

質問したり、結果を共有したり、ほかの人をサポートしたりできます。

  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.