Começar

Criar um exemplo mínimo reproduzível para relatórios de erros

Ao submeteres um relatório de erro para os repositórios Ultralytics YOLO, é essencial fornecer um exemplo mínimo reproduzível (MRE). Um MRE é um pequeno trecho de código autónomo que demonstra o problema que estás a encontrar. Fornecer um MRE ajuda os responsáveis pela manutenção e os contribuidores a compreender o problema e a trabalhar numa correção com mais eficiência. Este guia explica como criar um MRE ao submeter relatórios de erros para os repositórios Ultralytics YOLO.

1. Isolar o problema#

O primeiro passo para criar um MRE é isolar o problema. Remove qualquer código ou dependência desnecessários que não estejam diretamente relacionados com o problema. Concentra-te na parte específica do código que está a causar o problema e elimina quaisquer secções irrelevantes.

2. Utilizar modelos e conjuntos de dados públicos#

Ao criar um MRE, use modelos e conjuntos de dados disponíveis publicamente para reproduzir o problema. Por exemplo, use o modelo YOLO26n (yolo26n.pt) e o conjunto de dados COCO8 (coco8.yaml). Isso garante que os responsáveis pela manutenção e os colaboradores possam executar facilmente seu exemplo e investigar o problema sem precisar acessar dados proprietários ou modelos personalizados.

3. Incluir todas as dependências necessárias#

Certifica-te de que o teu MRE inclui todas as dependências necessárias. Se o teu código depender de bibliotecas externas, indica os pacotes necessários e as respetivas versões. Idealmente, lista as dependências no teu relatório de erro utilizando yolo checks se tiveres ultralytics instalado, ou pip list para outras ferramentas.

4. Descrever claramente o problema#

Descreve de forma clara e concisa o problema que estás a encontrar. Explica o comportamento esperado e o comportamento real que estás a observar. Se for pertinente, inclui mensagens de erro ou registos relevantes.

5. Formatar corretamente o código#

Formata corretamente o teu código utilizando blocos de código na descrição do problema. Assim, será mais fácil para outras pessoas lerem e compreenderem o teu código. No GitHub, podes criar um bloco de código colocando o teu código entre três acentos graves (```) e especificando a linguagem:

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

6. Testar o teu MRE#

Antes de submeteres o teu MRE, testa-o para garantir que reproduz fielmente o problema. Certifica-te de que outras pessoas conseguem executar o teu exemplo sem problemas nem modificações.

Exemplo de um MRE#

Segue-se um exemplo de MRE para um relatório de erro hipotético:

Descrição do erro:

Ao executar a inferência numa imagem com 0 canais, obtenho um erro relacionado com as dimensões do tensor de entrada.

MRE:

import torch

from ultralytics import YOLO

# Carrega o modelo
model = YOLO("yolo26n.pt")

# Carregar uma imagem com 0 canais
image = torch.rand(1, 0, 640, 640)

# Executar o modelo
results = model(image)

Mensagem de erro:

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

Dependências:

  • torch==2.8.0
  • ultralytics==8.4.142

Neste exemplo, o MRE demonstra o problema com uma quantidade mínima de código, utiliza um modelo público ("yolo26n.pt"), inclui todas as dependências necessárias e apresenta uma descrição clara do problema juntamente com a mensagem de erro.

Seguindo estas diretrizes, você ajudará os responsáveis pela manutenção e os colaboradores dos repositórios Ultralytics YOLO a entender e resolver seu problema com mais eficiência.

Perguntas frequentes#

  • Para criares um exemplo mínimo reproduzível (MRE) eficaz para relatórios de erros nos repositórios Ultralytics YOLO, segue estes passos:

    1. Isolar o problema: Remove qualquer código ou dependência que não esteja diretamente relacionado com o problema.
    2. Use modelos e conjuntos de dados públicos: use recursos públicos como yolo26n.pt e coco8.yaml para facilitar a reprodução.
    3. Incluir todas as dependências necessárias: Indica os pacotes necessários e as respetivas versões. Podes listar as dependências com yolo checks se tiveres ultralytics instalado, ou com pip list.
    4. Descrever claramente o problema: Explica o comportamento esperado e o comportamento real, incluindo quaisquer mensagens de erro ou registos.
    5. Formatar corretamente o código: Utiliza blocos de código para formatar o teu código e facilitar a leitura.
    6. Testar o teu MRE: Certifica-te de que o teu MRE reproduz o problema sem modificações.

    Para obteres um guia detalhado, consulta Criar um exemplo mínimo reproduzível.

  • A utilização de modelos e conjuntos de dados disponíveis publicamente no teu MRE garante que os responsáveis pela manutenção conseguem executar facilmente o teu exemplo sem precisarem de acesso a dados proprietários. Isto permite resolver os problemas mais rapidamente e com maior eficiência. Por exemplo, a utilização do modelo yolo26n.pt e do conjunto de dados coco8.yaml ajuda a uniformizar e simplificar o processo de depuração. Sabe mais sobre modelos e conjuntos de dados públicos na secção Utilizar modelos e conjuntos de dados públicos.

  • Um relatório de erro completo do Ultralytics YOLO deve incluir:

    • Descrição clara: Explica o problema, o comportamento esperado e o comportamento real.
    • Mensagens de erro: Inclui quaisquer mensagens de erro ou registos relevantes.
    • Dependências: Indica as dependências necessárias e as respetivas versões.
    • MRE: Fornece um exemplo mínimo reproduzível.
    • Passos para reproduzir: Indica os passos necessários para reproduzir o problema.

    Para obteres uma lista de verificação completa, consulta a secção Descrever claramente o problema.

  • Para formatares corretamente o teu código ao submeteres um relatório de erro no GitHub:

    • Utiliza três acentos graves (```) para criar blocos de código.
    • Especifica a linguagem de programação para realçar a sintaxe, por exemplo, ```python.
    • Certifica-te de que o código está corretamente indentado para facilitar a leitura.

    Exemplo:

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

    Para obteres mais dicas sobre formatação de código, consulta Formatar corretamente o código.

  • Antes de submeteres o teu MRE, certifica-te de que:

    • Verificas se é possível reproduzir o problema.
    • Confirmas que todas as dependências estão listadas e corretas.
    • Removes qualquer código desnecessário.
    • Testas o MRE para garantir que reproduz o problema sem modificações.

    Para obteres uma lista de verificação detalhada, consulta a secção Testar o teu MRE.

Comentários5

Faz uma pergunta, partilha os teus resultados ou ajuda alguém.

  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.