Solución de problemas habituales de YOLO#

Esta guía aborda los problemas más habituales que encontrarás al trabajar con Ultralytics YOLO26, organizados según dónde se producen: instalación, entrenamiento del modelo, predicción e implementación. Ve directamente a la categoría que corresponda a tu error o consulta las preguntas frecuentes para encontrar respuestas rápidas. Cada entrada describe el problema y una solución concreta que puedes aplicar directamente.

Problemas habituales#

Errores de instalación#

Los errores de instalación pueden deberse a diversos motivos, como versiones incompatibles, dependencias que faltan o una configuración incorrecta del entorno. En primer lugar, comprueba que haces lo siguiente:

• Usas Python 3.8 o una versión posterior, tal como se recomienda.
• Asegúrate de tener instalada la versión correcta de PyTorch (1.8 o posterior).
• Plantéate usar entornos virtuales para evitar conflictos.
• Sigue paso a paso la guía oficial de instalación.

Además, aquí tienes soluciones a problemas de instalación habituales.

Errores de importación o problemas con dependencias#

Si aparecen errores al importar YOLO26 o tienes conflictos entre dependencias, prueba estos pasos:

• Instalación limpia: Empezar con una instalación limpia puede resolver problemas inesperados, especialmente después de actualizaciones que modifican la estructura o las funciones del paquete.
• Actualiza con regularidad: Usa la versión más reciente de la biblioteca, ya que las versiones anteriores podrían no ser compatibles con las actualizaciones recientes.
• Comprueba las dependencias: Verifica que todas las dependencias necesarias estén instaladas correctamente y tengan versiones compatibles.
• Revisa los cambios: Si has instalado una versión anterior, consulta la documentación oficial o el registro de cambios para entender las modificaciones importantes de la estructura.

Ejecutar YOLO26 en una GPU#

Si tienes problemas para ejecutar YOLO26 en una GPU, prueba estos pasos para solucionarlos:

• Verifica la compatibilidad y la instalación de CUDA: Asegúrate de que tu GPU sea compatible con CUDA y de que CUDA esté instalado correctamente. Usa el comando nvidia-smi para comprobar el estado de tu GPU NVIDIA y la versión de CUDA.
• Comprueba la integración de PyTorch y CUDA: Asegúrate de que PyTorch pueda usar CUDA ejecutando import torch; print(torch.cuda.is_available()) en un terminal de Python. Si devuelve 'True', PyTorch está configurado para usar CUDA.
• Activación del entorno: Asegúrate de estar en el entorno correcto, donde estén instalados todos los paquetes necesarios.
• Actualiza tus paquetes: Es posible que los paquetes obsoletos no sean compatibles con tu GPU. Mantenlos actualizados.
• Configuración del programa: Comprueba si tu código solicita el uso de la GPU. Puedes establecer el argumento device al ejecutar el entrenamiento o la predicción (por ejemplo, device=0).

import torch

cap = torch.cuda.get_device_capability(0) if torch.cuda.is_available() else (0, 0)
cudnn = torch.backends.cudnn.version() or 0
ok = "not compatible" if cudnn >= 91100 and (cap[0] < 7 or (cap[0] == 7 and cap[1] < 5)) else "should be ok"
print(f"Compute capability: SM {cap[0]}.{cap[1]}, cuDNN: {cudnn} => {ok}")

Problemas con el entrenamiento del modelo#

A continuación se describen problemas habituales de entrenamiento y sus soluciones.

Verificación de los ajustes de configuración#

Problema: No tienes claro si los ajustes de configuración del archivo .yaml se aplican correctamente durante el entrenamiento del modelo.

Solución: Los ajustes del conjunto de datos y los del entrenamiento se encuentran en distintos archivos .yaml y se pasan mediante argumentos diferentes de model.train(). Para asegurarte de que estos ajustes se aplican correctamente, sigue estos pasos:

• Confirma que las rutas a tus archivos .yaml sean correctas.

• Pasa la configuración .yaml del conjunto de datos (rutas, nombres de clases y particiones) como argumento data, y una configuración personalizada .yaml para el entrenamiento (por ejemplo, epochs o lr0) como argumento cfg. Los argumentos que se pasan directamente a model.train() tienen prioridad sobre ambos:

  model.train(data="/path/to/your/data.yaml", cfg="/path/to/your/cfg.yaml", batch=4)

Acelerar el entrenamiento con varias GPU#

Problema: El entrenamiento es lento con una sola GPU y quieres acelerarlo usando varias GPU.

Solución: Aumentar el tamaño del lote puede acelerar el entrenamiento, pero es fundamental tener en cuenta la capacidad de memoria de la GPU. Para acelerar el entrenamiento con varias GPU, sigue estos pasos:

• Asegúrate de tener varias GPU disponibles.

• Establece el argumento device en una lista de índices de GPU, por ejemplo, device=[0,1,2,3].

• Aumenta el tamaño del lote según corresponda para aprovechar al máximo las varias GPU sin superar los límites de memoria.

• Modifica el comando de entrenamiento para usar varias GPU:

  # # Ajusta el tamaño del lote y otros parámetros según sea necesario para optimizar la velocidad del entrenamiento
  model.train(data="/path/to/your/data.yaml", batch=32, device=[0, 1, 2, 3])

Parámetros que hay que supervisar continuamente#

Problema: Quieres saber qué parámetros debes supervisar continuamente durante el entrenamiento, además de la pérdida.

Solución: Aunque la pérdida es una métrica fundamental que debes supervisar, también es importante seguir otras métricas para optimizar el rendimiento del modelo. Algunas métricas clave que debes supervisar durante el entrenamiento son:

• Precisión
• Exhaustividad
• Precisión media (mAP)

Puedes consultar estas métricas en los registros del entrenamiento o usar herramientas como TensorBoard o Weights & Biases para visualizarlas. Aplicar la parada temprana en función de estas métricas puede ayudarte a conseguir mejores resultados.

Herramientas para seguir el progreso del entrenamiento#

Problema: Buscas recomendaciones de herramientas para seguir el progreso del entrenamiento.

Solución: Para seguir y visualizar el progreso del entrenamiento, puedes plantearte usar las siguientes herramientas:

• TensorBoard: TensorBoard es una opción popular para visualizar métricas de entrenamiento, como la pérdida, la exactitud y otras. Puedes integrarlo en el proceso de entrenamiento de YOLO26.
• Comet: Comet ofrece un amplio conjunto de herramientas para el seguimiento y la comparación de experimentos. Te permite seguir métricas, hiperparámetros e incluso los pesos del modelo. También es fácil integrarlo con los modelos YOLO, lo que te ofrece una visión completa del ciclo del experimento.
• Plataforma Ultralytics: Ultralytics Platform ofrece un entorno especializado para hacer un seguimiento de los modelos YOLO y te proporciona una plataforma integral para gestionar métricas y conjuntos de datos, e incluso colaborar con tu equipo. Como está diseñada específicamente para YOLO, ofrece opciones de seguimiento más personalizadas.

Cómo comprobar si el entrenamiento se está ejecutando en la GPU#

Problema: El valor de 'device' en los registros del entrenamiento es 'null' y no sabes si el entrenamiento se está ejecutando en la GPU.

Solución: Por lo general, que el valor de 'device' sea 'null' significa que el proceso de entrenamiento está configurado para seleccionar automáticamente una GPU disponible, que es el comportamiento predeterminado. Para entrenar en una GPU específica, establece el argumento device al iniciar el entrenamiento. device es un argumento de entrenamiento, por lo que establecerlo en .yaml del conjunto de datos no tiene ningún efecto:

from ultralytics import YOLO

# Cargar un modelo
model = YOLO("yolo26n.pt")

# # Usa la GPU 0; device=[0, 1] para varias GPU, device="cpu" para la CPU
model.train(data="path/to/data.yaml", device=0)

Revisa la carpeta 'runs' para consultar los registros y las métricas y supervisar eficazmente el progreso del entrenamiento.

Aspectos clave para entrenar modelos de forma eficaz#

Si tienes problemas relacionados con el entrenamiento del modelo, ten en cuenta lo siguiente.

Formato del conjunto de datos y etiquetas

• Importancia: La base de cualquier modelo de aprendizaje automático está en la calidad y el formato de los datos con los que se entrena.
• Recomendación: Asegúrate de que tu conjunto de datos personalizado y las etiquetas asociadas respeten el formato esperado. Es fundamental comprobar que las anotaciones sean precisas y de alta calidad. Las anotaciones incorrectas o deficientes pueden desviar el proceso de aprendizaje del modelo y dar lugar a resultados impredecibles.

Convergencia del modelo

• Importancia: Lograr la convergencia del modelo garantiza que este haya aprendido lo suficiente a partir de los datos de entrenamiento.
• Recomendación: Al entrenar un modelo «desde cero», es fundamental asegurarse de que alcance un nivel de convergencia satisfactorio. Esto puede requerir un entrenamiento más largo y más épocas que cuando se ajusta un modelo existente.

Tasa de aprendizaje y tamaño del lote

• Importancia: Estos hiperparámetros desempeñan un papel fundamental a la hora de determinar cómo actualiza el modelo sus pesos durante el entrenamiento.
• Recomendación: Evalúa periódicamente si la tasa de aprendizaje y el tamaño del lote elegidos son óptimos para tu conjunto de datos concreto. Los parámetros que no se ajusten a las características del conjunto de datos pueden perjudicar el rendimiento del modelo.

Distribución de clases

• Importancia: La distribución de clases de tu conjunto de datos puede influir en las tendencias de predicción del modelo.
• Recomendación: Evalúa periódicamente la distribución de clases de tu conjunto de datos. Si hay un desequilibrio entre clases, existe el riesgo de que el modelo desarrolle un sesgo hacia la clase más frecuente. Este sesgo puede apreciarse en la matriz de confusión, donde el modelo podría predecir principalmente la clase mayoritaria.

Comprobación cruzada con pesos preentrenados

• Importancia: Aprovechar pesos preentrenados puede proporcionar una base sólida para entrenar el modelo, especialmente cuando hay pocos datos.
• Recomendación: Como paso de diagnóstico, considera entrenar el modelo con los mismos datos, pero inicializándolo con pesos preentrenados. Si este enfoque genera una matriz de confusión bien formada, podría indicar que el modelo «desde cero» necesita más entrenamiento o algunos ajustes.

Problemas relacionados con las predicciones del modelo#

A continuación se describen los problemas habituales que surgen al hacer predicciones con el modelo y cómo solucionarlos.

Obtener predicciones de cuadros delimitadores con tu modelo personalizado YOLO26#

Problema: Al hacer predicciones con un modelo YOLO26 personalizado, pueden surgir dificultades con el formato y la visualización de las coordenadas de los cuadros delimitadores.

Solución:

• Formato de las coordenadas: YOLO26 proporciona las coordenadas de los cuadros delimitadores en valores absolutos de píxeles. Para convertirlas en coordenadas relativas (entre 0 y 1), divídelas por las dimensiones de la imagen. Por ejemplo, supongamos que la imagen mide 640x640. En ese caso, harías lo siguiente:

  # Convierte las coordenadas absolutas en coordenadas relativas
  x1 = x1 / 640  # Divide las coordenadas x por el ancho de la imagen
  x2 = x2 / 640
  y1 = y1 / 640  # Divide las coordenadas y por la altura de la imagen
  y2 = y2 / 640

• Nombre del archivo: Para obtener el nombre del archivo de la imagen sobre la que haces la predicción, lee la ruta del archivo de imagen del atributo path de cada objeto de resultado (por ejemplo, result.path) dentro del bucle de predicción.

Filtrar objetos en las predicciones de YOLO26#

Problema: Dificultades para filtrar y mostrar únicamente determinados objetos en los resultados de predicción al ejecutar YOLO26 con la biblioteca Ultralytics.

Solución: Para detectar clases específicas, usa el argumento classes para indicar las clases que quieres incluir en la salida. Por ejemplo, para detectar solo coches (suponiendo que «coches» tenga el índice de clase 2):

yolo segment predict model=yolo26n-seg.pt source='path/to/car.mp4' show=True classes=2

Entender las métricas de precisión en YOLO26#

Problema: Confusión sobre la diferencia entre la precisión de los cuadros, la precisión de las máscaras y la precisión de la matriz de confusión en YOLO26.

Solución: La precisión de los cuadros mide la exactitud de los cuadros delimitadores predichos frente a los cuadros reales de referencia, utilizando IoU (intersección sobre unión) como métrica. La precisión de las máscaras evalúa la concordancia entre las máscaras de segmentación predichas y las máscaras de referencia en la clasificación de objetos píxel a píxel. Por su parte, la precisión de la matriz de confusión se centra en la exactitud general de la clasificación de todas las clases y no tiene en cuenta la exactitud geométrica de las predicciones. Es importante tener en cuenta que un cuadro delimitador puede ser geométricamente exacto (verdadero positivo) aunque la predicción de clase sea incorrecta, lo que da lugar a diferencias entre la precisión de los cuadros y la precisión de la matriz de confusión. Estas métricas evalúan distintos aspectos del rendimiento de un modelo, lo que refleja la necesidad de utilizar métricas de evaluación diferentes según la tarea.

Extraer las dimensiones de los objetos en YOLO26#

Problema: Dificultad para obtener la longitud y la altura de los objetos detectados en YOLO26, especialmente cuando se detectan varios objetos en una imagen.

Solución: Para obtener las dimensiones de los cuadros delimitadores, primero usa el modelo Ultralytics YOLO26 para predecir objetos en una imagen. Después, extrae la información sobre el ancho y la altura de los cuadros delimitadores de los resultados de la predicción.

from ultralytics import YOLO

# Load a pretrained YOLO26 model
model = YOLO("yolo26n.pt")

# Specify the source image
source = "https://ultralytics.com/images/bus.jpg"

# Make predictions
results = model.predict(source, save=True, imgsz=320, conf=0.25)

# Extract bounding box dimensions
boxes = results[0].boxes.xywh.cpu()
for box in boxes:
    x, y, w, h = box
    print(f"Width of Box: {w}, Height of Box: {h}")

Problemas de implementación#

Problemas de implementación en GPU#

Problema: Implementar modelos en un entorno con varias GPU puede provocar, a veces, comportamientos inesperados, como un uso de memoria imprevisto o resultados incoherentes entre GPU, entre otros.

Solución: Comprueba si la inicialización de la GPU está configurada de forma predeterminada. Algunos frameworks, como PyTorch, pueden inicializar operaciones CUDA en una GPU predeterminada antes de pasar a las GPU designadas. Para evitar inicializaciones predeterminadas inesperadas, especifica directamente la GPU durante la implementación y la predicción. Después, utiliza herramientas para supervisar en tiempo real la utilización de la GPU y el uso de memoria, e identificar anomalías. Asegúrate también de utilizar la versión más reciente del framework o la biblioteca.

Problemas al convertir o exportar modelos#

Problema: Durante la conversión o exportación de modelos de aprendizaje automático a distintos formatos o plataformas, pueden producirse errores o comportamientos inesperados.

Solución: Consulta los formatos compatibles y las opciones de cada formato en la documentación del modo de exportación y, a continuación, sigue estas comprobaciones:

• Comprobación de compatibilidad: Asegúrate de utilizar versiones de bibliotecas y frameworks que sean compatibles entre sí. Las versiones incompatibles pueden provocar errores inesperados durante la conversión.
• Restablecimiento del entorno: Si utilizas un entorno interactivo como Jupyter o Colab, considera la posibilidad de reiniciarlo después de hacer cambios importantes o instalar componentes. Empezar desde cero puede resolver algunos problemas subyacentes.
• Documentación oficial: Consulta siempre la documentación oficial de la herramienta o biblioteca que utilizas para la conversión. A menudo incluye directrices específicas y buenas prácticas para exportar modelos.
• Ayuda de la comunidad: Consulta el repositorio oficial de la biblioteca o el framework para ver si otros usuarios han informado de problemas similares. Es posible que los responsables del mantenimiento o la comunidad hayan ofrecido soluciones o alternativas en los hilos de debate.
• Actualiza con regularidad: Asegúrate de utilizar la versión más reciente de la herramienta o biblioteca. Los desarrolladores publican actualizaciones con frecuencia para corregir errores conocidos o mejorar la funcionalidad.
• Haz pruebas de forma incremental: Antes de realizar una conversión completa, prueba el proceso con un modelo o conjunto de datos más pequeño para identificar posibles problemas cuanto antes.

Comunidad y asistencia#

Obtén ayuda y comparte soluciones a través de estos canales y recursos.

Foros y canales de ayuda#

Problemas de GitHub: El repositorio de Ultralytics en GitHub tiene una pestaña de problemas donde puedes hacer preguntas, informar de errores y sugerir nuevas funciones. La comunidad y las personas responsables del mantenimiento participan activamente, así que es un buen lugar para obtener ayuda con problemas concretos.

Servidor de Discord de Ultralytics: Ultralytics tiene un servidor de Discord donde puedes interactuar con otros usuarios y con el equipo de desarrollo.

Documentación y recursos oficiales#

Documentación de Ultralytics YOLO26: La documentación oficial ofrece una visión general completa de YOLO26, junto con guías de instalación, uso y resolución de problemas.

Conclusión#

La mayoría de los problemas de YOLO26 se deben a unas pocas causas: incompatibilidades entre versiones, formato del conjunto de datos y configuración de la GPU. Si aquí no se aborda un error, busca en la pestaña GitHub Issues o pregunta en el servidor de Discord; es probable que alguien ya lo haya resuelto. Si tienes problemas más complejos de entrenamiento, consulta la guía Consejos para entrenar modelos, que ofrece recomendaciones prácticas para obtener mejores resultados en tus proyectos de visión artificial.

Preguntas frecuentes#