Solución de problemas habituales de YOLO#

Esta guía cubre los problemas más habituales que encontrarás al trabajar con Ultralytics YOLO26, agrupados según dónde se produzcan: instalación, entrenamiento del modelo, predicción y despliegue. Ve directamente a la categoría que corresponda a tu error o consulta las preguntas frecuentes para obtener 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 configuraciones incorrectas del entorno. Primero, comprueba que estás haciendo 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, estas son algunas soluciones para problemas habituales de instalación.

Errores de importación o problemas con las dependencias#

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

• Instalación desde cero: Empezar con una instalación limpia puede resolver problemas inesperados, especialmente después de actualizaciones que cambian la estructura o la funcionalidad del paquete.
• Actualiza periódicamente: Usa la versión más reciente de la biblioteca, ya que las versiones antiguas 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 antigua, consulta la documentación oficial o el registro de cambios para comprender cualquier cambio estructural importante.

Ejecutar YOLO26 en GPU#

Si tienes problemas para ejecutar YOLO26 en una GPU, considera los siguientes pasos de solución de problemas:

• 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 utilizar CUDA ejecutando import torch; print(torch.cuda.is_available()) en un terminal de Python. Si devuelve «True», PyTorch está configurado para usar CUDA.
• Activa el 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 de entrenamiento del modelo#

A continuación se describen los 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 están aplicando correctamente durante el entrenamiento del modelo.

Solución: Los ajustes de configuración del archivo .yaml deberían aplicarse al utilizar la función model.train(). Para asegurarte de que estos ajustes se aplican correctamente, sigue estos pasos:

• Confirma que la ruta al archivo de configuración .yaml sea correcta.

• Asegúrate de pasar la ruta al archivo .yaml como argumento data al llamar a model.train(), como se muestra a continuación:

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

Acelerar el entrenamiento con varias GPU#

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

Solución: Aumentar el tamaño del lote puede acelerar el entrenamiento, pero es esencial 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 en consecuencia para utilizar plenamente las varias GPU sin superar los límites de memoria.

• Modifica el comando de entrenamiento para utilizar varias GPU:

  # Adjust the batch size and other settings as needed to optimize training speed
  model.train(data="/path/to/your/data.yaml", batch=32, device=[0, 1, 2, 3])

Parámetros de supervisión continua#

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 se debe supervisar, también es esencial realizar un seguimiento de otras métricas para optimizar el rendimiento del modelo. Algunas métricas clave que conviene supervisar durante el entrenamiento son:

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

Puedes acceder a estas métricas desde los registros de entrenamiento o utilizando herramientas como TensorBoard o Weights & Biases para su visualización. Implementar la parada anticipada basada en estas métricas puede ayudarte a obtener mejores resultados.

Herramientas para realizar un seguimiento del progreso del entrenamiento#

Problema: Buscas recomendaciones sobre herramientas para realizar un seguimiento del progreso del entrenamiento.

Solución: Para realizar un seguimiento y visualizar el progreso del entrenamiento, puedes considerar las siguientes herramientas:

• TensorBoard: TensorBoard es una opción popular para visualizar métricas de entrenamiento, incluida la pérdida, la precisión y mucho más. Puedes integrarlo con tu proceso de entrenamiento de YOLO26.
• Comet: Comet ofrece un amplio conjunto de herramientas para realizar el seguimiento y la comparación de experimentos. Permite realizar un seguimiento de las métricas, los hiperparámetros e incluso los pesos del modelo. La integración con los modelos YOLO también es sencilla y te proporciona una visión completa del ciclo de tu experimento.
• Ultralytics Platform: Ultralytics Platform ofrece un entorno especializado para realizar el seguimiento de modelos YOLO, con una plataforma integral para gestionar métricas y conjuntos de datos, e incluso colaborar con tu equipo. Gracias a su enfoque específico en YOLO, ofrece opciones de seguimiento más personalizadas.

Cómo comprobar si el entrenamiento se realiza en la GPU#

Problema: El valor «device» de los registros de entrenamiento es «null» y no tienes claro si el entrenamiento se está realizando en la GPU.

Solución: Que el valor «device» sea «null» normalmente 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 de tu conjunto de datos no tiene ningún efecto:

from ultralytics import YOLO

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

# Use GPU 0; device=[0, 1] for multiple GPUs, device="cpu" for CPU
model.train(data="path/to/data.yaml", device=0)

Controla la carpeta «runs» para consultar los registros y las métricas y supervisar eficazmente el progreso del entrenamiento.

Consideraciones clave para un entrenamiento eficaz del modelo#

Estas son algunas cuestiones que debes tener en cuenta si tienes problemas relacionados con el entrenamiento del modelo.

Formato y etiquetas del conjunto de datos

• Importancia: La base de cualquier modelo de aprendizaje automático reside 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 sus etiquetas asociadas cumplan el formato esperado. Es fundamental verificar que las anotaciones sean precisas y de alta calidad. Las anotaciones incorrectas o deficientes pueden desviar el proceso de aprendizaje del modelo y provocar resultados impredecibles.

Convergencia del modelo

• Importancia: Lograr la convergencia del modelo garantiza que este haya aprendido lo suficiente 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 una mayor duración del entrenamiento, con más épocas, que cuando ajustas 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 específico. 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 las clases en tu conjunto de datos puede influir en las tendencias de predicción del modelo.
• Recomendación: Evalúa periódicamente la distribución de las clases de tu conjunto de datos. Si existe un desequilibrio entre clases, el modelo podría desarrollar un sesgo hacia la clase más frecuente. Este sesgo puede observarse en la matriz de confusión, donde el modelo podría predecir predominantemente la clase mayoritaria.

Comprobación cruzada con pesos preentrenados

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

Problemas relacionados con las predicciones del modelo#

A continuación se describen los problemas habituales que surgen durante la predicción del modelo y sus soluciones.

Obtener predicciones de BBox con tu modelo YOLO26 personalizado#

Problema: Al ejecutar predicciones con un modelo YOLO26 personalizado, surgen dificultades con el formato y la visualización de las coordenadas de los BBox.

Solución:

• Formato de las coordenadas: YOLO26 proporciona las coordenadas de los BBox en valores de píxeles absolutos. Para convertirlas en coordenadas relativas (entre 0 y 1), debes dividirlas por las dimensiones de la imagen. Por ejemplo, supongamos que el tamaño de tu imagen es 640x640. En ese caso, harías lo siguiente:

  # Convert absolute coordinates to relative coordinates
  x1 = x1 / 640  # Divide x-coordinates by image width
  x2 = x2 / 640
  y1 = y1 / 640  # Divide y-coordinates by image height
  y2 = y2 / 640

• Nombre del archivo: Para obtener el nombre del archivo de la imagen sobre la que realizas la predicción, accede directamente a la ruta del archivo de imagen desde el objeto de resultado dentro del bucle de predicción.

Filtrar objetos en las predicciones de YOLO26#

Problema: Tienes problemas para filtrar y mostrar únicamente objetos específicos 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 únicamente 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

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

Problema: Existe confusión sobre la diferencia entre la precisión de los BBox, 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 BBox mide la exactitud de los BBox predichos en comparación con los BBox 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 otro lado, la precisión de la matriz de confusión se centra en la exactitud general de la clasificación en todas las clases y no tiene en cuenta la exactitud geométrica de las predicciones. Es importante señalar que un BBox puede ser geométricamente preciso (verdadero positivo) aunque la predicción de clase sea incorrecta, lo que provoca diferencias entre la precisión de los BBox y la precisión de la matriz de confusión. Estas métricas evalúan aspectos distintos del rendimiento de un modelo y reflejan la necesidad de utilizar métricas de evaluación diferentes en varias tareas.

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 BBox, utiliza primero el modelo Ultralytics YOLO26 para predecir objetos en una imagen. Después, extrae la información de anchura y altura de los BBox a partir 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}")

Desafíos del despliegue#

Problemas de despliegue en GPU#

Problema: Desplegar modelos en un entorno con varias GPU puede provocar a veces comportamientos inesperados, como un uso de memoria inesperado, resultados incoherentes entre GPU, etc.

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

Problemas de conversión o exportación del modelo#

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

Solución: Revisa los formatos compatibles y las opciones específicas de cada formato en la documentación del modo de exportación y, a continuación, realiza estas comprobaciones:

• Comprobación de compatibilidad: Asegúrate de utilizar versiones de bibliotecas y frameworks 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 reiniciar el entorno después de realizar cambios importantes o instalaciones. Empezar de nuevo puede resolver a veces problemas subyacentes.
• Documentación oficial: Consulta siempre la documentación oficial de la herramienta o biblioteca que utilices para la conversión. A menudo contiene directrices específicas y prácticas recomendadas para exportar modelos.
• Asistencia de la comunidad: Consulta el repositorio oficial de la biblioteca o el framework para buscar problemas similares comunicados por otros usuarios. Es posible que los responsables del mantenimiento o la comunidad hayan proporcionado soluciones o alternativas en los hilos de debate.
• Actualiza periódicamente: asegúrate de usar 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 para obtener ayuda#

GitHub Issues: El repositorio de Ultralytics en GitHub tiene una pestaña de Issues en la que puedes hacer preguntas, informar de errores y sugerir nuevas funciones. La comunidad y los mantenedores están activos aquí, y es un gran lugar para obtener ayuda con problemas específicos.

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

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 sobre instalación, uso y resolución de problemas.

Conclusión#

La mayoría de los problemas de YOLO26 se deben a unas pocas causas: discrepancias 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 de GitHub Issues o pregunta en el servidor de Discord; es muy probable que alguien ya lo haya resuelto. Para 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 por ordenador.

Preguntas frecuentes#