Empezar

Cómo crear un ejemplo mínimo reproducible para informar de errores

Al informar de un error en los repositorios de Ultralytics YOLO, es fundamental proporcionar un ejemplo mínimo reproducible (MRE). Un MRE es un fragmento de código pequeño y autónomo que muestra el problema que tienes. Proporcionar un MRE ayuda a los responsables del mantenimiento y a los colaboradores a comprender el problema y resolverlo con mayor eficacia. Esta guía explica cómo crear un MRE al informar de errores en los repositorios de Ultralytics YOLO.

1. Aísla el problema#

El primer paso para crear un MRE es aislar el problema. Elimina el código y las dependencias innecesarios que no estén directamente relacionados con el problema. Céntrate en la parte concreta del código que lo causa y elimina las secciones irrelevantes.

2. Utiliza modelos y conjuntos de datos públicos#

Al crear un MRE, utiliza modelos y conjuntos de datos disponibles públicamente para reproducir el problema. Por ejemplo, utiliza el modelo YOLO26n (yolo26n.pt) y el conjunto de datos COCO8 (coco8.yaml). Así, los responsables del mantenimiento y los colaboradores podrán ejecutar fácilmente tu ejemplo e investigar el problema sin necesitar acceso a datos privados ni a modelos personalizados.

3. Incluye todas las dependencias necesarias#

Asegúrate de incluir en el MRE todas las dependencias necesarias. Si tu código depende de bibliotecas externas, especifica los paquetes necesarios y sus versiones. Lo ideal es enumerar las dependencias en el informe del error mediante yolo checks si tienes instalado ultralytics, o mediante pip list para otras herramientas.

4. Describe el problema con claridad#

Describe de forma clara y concisa el problema que tienes. Explica cuál debería ser el comportamiento y cuál es el comportamiento real que observas. Si procede, incluye los mensajes de error o registros pertinentes.

5. Da el formato adecuado al código#

Da el formato adecuado al código con bloques de código en la descripción del problema. Así será más fácil que otras personas lean y entiendan tu código. En GitHub, puedes crear un bloque de código encerrándolo entre tres acentos graves (```) e indicando el lenguaje:

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

6. Prueba el MRE#

Antes de enviar el MRE, pruébalo para asegurarte de que reproduce fielmente el problema. Comprueba que otras personas puedan ejecutar tu ejemplo sin problemas ni modificaciones.

Ejemplo de MRE#

Este es un ejemplo de MRE para un informe de error hipotético:

Descripción del error:

Al ejecutar la inferencia en una imagen con 0 canales, aparece un error relacionado con las dimensiones del tensor de entrada.

MRE:

import torch

from ultralytics import YOLO

# Carga el modelo
model = YOLO("yolo26n.pt")

# Carga una imagen con 0 canales
image = torch.rand(1, 0, 640, 640)

# Ejecuta el modelo
results = model(image)

Mensaje de error:

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

Dependencias:

  • torch==2.8.0
  • ultralytics==8.4.142

En este ejemplo, el MRE muestra el problema con una cantidad mínima de código, utiliza un modelo público ("yolo26n.pt"), incluye todas las dependencias necesarias y describe claramente el problema junto con el mensaje de error.

Si sigues estas pautas, ayudarás a los responsables del mantenimiento y a los colaboradores de los repositorios YOLO de Ultralytics a entender y resolver tu problema con mayor eficacia.

Preguntas frecuentes#

  • Para crear un ejemplo mínimo reproducible (MRE) eficaz con el que informar de errores en los repositorios de Ultralytics YOLO, sigue estos pasos:

    1. Aísla el problema: elimina el código y las dependencias que no estén directamente relacionados con el problema.
    2. Utiliza modelos y conjuntos de datos públicos: usa recursos públicos como yolo26n.pt y coco8.yaml para facilitar la reproducción del problema.
    3. Incluye todas las dependencias necesarias: especifica los paquetes necesarios y sus versiones. Puedes enumerar las dependencias mediante yolo checks si tienes instalado ultralytics, o mediante pip list.
    4. Describe el problema con claridad: explica cuál debería ser el comportamiento y cuál es el comportamiento real, e incluye los mensajes de error o registros pertinentes.
    5. Da el formato adecuado al código: utiliza bloques de código para que sea más fácil leerlo.
    6. Prueba el MRE: asegúrate de que el MRE reproduzca el problema sin modificaciones.

    Para obtener una guía detallada, consulta Cómo crear un ejemplo mínimo reproducible.

  • Si utilizas modelos y conjuntos de datos disponibles públicamente en tu MRE, los responsables del mantenimiento podrán ejecutar fácilmente tu ejemplo sin necesitar acceso a datos propietarios. Esto permite resolver los problemas con mayor rapidez y eficacia. Por ejemplo, utilizar el modelo yolo26n.pt y el conjunto de datos coco8.yaml ayuda a estandarizar y simplificar el proceso de depuración. Descubre más sobre los modelos y conjuntos de datos públicos en la sección Utiliza modelos y conjuntos de datos públicos.

  • Un informe de errores completo de Ultralytics YOLO debe incluir:

    • Descripción clara: explica el problema, el comportamiento esperado y el comportamiento real.
    • Mensajes de error: incluye los mensajes de error o registros pertinentes.
    • Dependencias: enumera las dependencias necesarias y sus versiones.
    • MRE: proporciona un ejemplo mínimo reproducible.
    • Pasos para reproducirlo: detalla los pasos necesarios para reproducir el problema.

    Para consultar una lista de comprobación completa, visita la sección Describe el problema con claridad.

  • Para dar el formato adecuado a tu código al enviar un informe de errores en GitHub:

    • Utiliza tres acentos graves (```) para crear bloques de código.
    • Especifica el lenguaje de programación para resaltar la sintaxis, por ejemplo, ```python.
    • Asegúrate de aplicar la sangría correctamente para que el código sea fácil de leer.

    Ejemplo:

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

    Para obtener más consejos sobre el formato del código, consulta Da el formato adecuado al código.

  • Antes de enviar el MRE, asegúrate de lo siguiente:

    • Comprueba que el problema se puede reproducir.
    • Asegúrate de que todas las dependencias estén enumeradas y sean correctas.
    • Elimina el código innecesario.
    • Prueba el MRE para asegurarte de que reproduce el problema sin modificaciones.

    Para consultar una lista de comprobación detallada, visita la sección Prueba el MRE.

Comentarios5

Haz una pregunta, comparte tus resultados o ayuda a otra persona.

  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.