Начать

Создание минимального воспроизводимого примера для сообщений об ошибках

При отправке сообщения об ошибке в репозиториях Ultralytics YOLO важно предоставить минимальный воспроизводимый пример (MRE). MRE — это небольшой автономный фрагмент кода, демонстрирующий возникшую у тебя проблему. Такой пример помогает сопровождающим и участникам понять проблему и эффективнее найти решение. В этом руководстве объясняется, как создать MRE при отправке сообщений об ошибках в репозитории Ultralytics YOLO.

1. Изолируй проблему#

Первый шаг при создании MRE — изолировать проблему. Удали весь лишний код и зависимости, не связанные напрямую с проблемой. Сосредоточься на конкретной части кода, вызывающей проблему, и исключи все не относящиеся к делу фрагменты.

2. Используй общедоступные модели и наборы данных#

При создании MRE используй общедоступные модели и наборы данных, чтобы воспроизвести проблему. Например, возьми модель YOLO26n (yolo26n.pt) и набор данных COCO8 (coco8.yaml). Так сопровождающие и участники проекта смогут легко запустить твой пример и изучить проблему без доступа к проприетарным данным или пользовательским моделям.

3. Добавь все необходимые зависимости#

Укажи в MRE все необходимые зависимости. Если код использует внешние библиотеки, перечисли нужные пакеты и их версии. В идеале укажи зависимости в сообщении об ошибке с помощью yolo checks, если у тебя установлен ultralytics, или 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 быстрее понять и решить твою проблему.

Часто задаваемые вопросы#

  • Чтобы создать эффективный минимальный воспроизводимый пример (MRE) для сообщений об ошибках в репозиториях Ultralytics YOLO, выполни следующие шаги:

    1. Изолируй проблему: удали код и зависимости, не связанные напрямую с проблемой.
    2. Используй общедоступные модели и наборы данных: для удобного воспроизведения проблемы используй общедоступные ресурсы, например yolo26n.pt и coco8.yaml.
    3. Добавь все необходимые зависимости: укажи необходимые пакеты и их версии. Перечислить зависимости можно с помощью yolo checks, если у тебя установлен ultralytics, или 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.