버그 보고를 위한 최소 재현 예제 작성

Ultralytics YOLO 리포지토리에 버그를 보고할 때는 최소 재현 예제(MRE)를 제공하는 것이 중요합니다. MRE는 겪고 있는 문제를 보여 주는 작고 독립적인 코드 조각입니다. MRE를 제공하면 유지관리자와 기여자가 문제를 이해하고 더 효율적으로 수정할 수 있습니다. 이 가이드에서는 Ultralytics YOLO 리포지토리에 버그를 보고할 때 MRE를 작성하는 방법을 설명합니다.

1. 문제 분리#

MRE 작성의 첫 단계는 문제를 분리하는 것입니다. 문제와 직접 관련이 없는 불필요한 코드나 종속성을 제거하세요. 문제를 일으키는 코드의 특정 부분에 집중하고 관련 없는 부분은 모두 삭제하세요.

2. 공개 모델 및 데이터셋 사용#

MRE를 작성할 때는 공개적으로 이용 가능한 모델과 데이터셋을 사용해 문제를 재현하세요. 예를 들어 YOLO26n 모델(yolo26n.pt)과 COCO8 데이터셋(coco8.yaml)을 사용하세요. 이렇게 하면 유지관리자와 기여자가 독점 데이터나 사용자 지정 모델에 액세스하지 않고도 예제를 쉽게 실행하고 문제를 조사할 수 있습니다.

3. 필요한 종속성 모두 포함#

MRE에 필요한 종속성이 모두 포함되어 있는지 확인하세요. 코드가 외부 라이브러리에 의존하는 경우 필수 패키지와 버전을 명시하세요. 가능하면 ultralytics이 설치되어 있다면 yolo checks을 사용하고, 다른 도구를 사용하는 경우 pip list를 사용하여 버그 보고서에 종속성을 나열하세요.

4. 문제를 명확하게 설명#

겪고 있는 문제를 명확하고 간결하게 설명하세요. 예상 동작과 실제로 나타나는 동작을 설명하세요. 해당하는 경우 관련 오류 메시지나 로그를 포함하세요.

5. 코드 형식 올바르게 지정#

문제 설명에서 코드 블록을 사용하여 코드 형식을 올바르게 지정하세요. 그러면 다른 사람이 코드를 더 쉽게 읽고 이해할 수 있습니다. GitHub에서는 코드 앞뒤에 백틱 세 개(```)를 넣고 언어를 지정하여 코드 블록을 만들 수 있습니다:

```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에 버그 보고서를 제출할 때 코드 형식을 올바르게 지정하려면 다음을 따르세요:

    • 백틱 세 개(```)를 사용하여 코드 블록을 만드세요.
    • 구문 강조 표시를 위해 프로그래밍 언어를 지정하세요(예: ```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.