开始使用

为错误报告创建最小可复现示例

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