Guía de Hyperparameter Tuning de Ultralytics YOLO#

La optimización de hiperparámetros en Ultralytics YOLO es una búsqueda automatizada e iterativa que optimiza ajustes —como la tasa de aprendizaje, los pesos de pérdida y la intensidad de aumento— para maximizar las métricas de rendimiento de un modelo de machine learning como la precisión, la exactitud y la recuperación. En lugar de probar estos valores manualmente, Ultralytics YOLO explora el espacio de hiperparámetros con un algoritmo genético que muta y evalúa configuraciones candidatas a lo largo de muchos entrenamientos cortos.

¿Qué son los hiperparámetros?#

Los hiperparámetros son ajustes estructurales de alto nivel para el algoritmo. Se definen antes de la fase de entrenamiento y permanecen constantes durante la misma. Estos son algunos de los hiperparámetros que se suelen ajustar en Ultralytics YOLO:

• Tasa de aprendizaje lr0: Determina el tamaño del paso en cada iteración mientras se avanza hacia un mínimo en la loss function.
• Batch Size batch: Número de imágenes procesadas simultáneamente en una pasada hacia adelante.
• Número de Epochs epochs: Una época es una pasada completa hacia adelante y hacia atrás de todos los ejemplos de entrenamiento.
• Especificaciones de la arquitectura: Como recuento de canales, número de capas, tipos de funciones de activación, etc. Estos elementos se encuentran en la configuración YAML del modelo en lugar de en los argumentos de entrenamiento.

De estos cuatro, solo la tasa de aprendizaje se encuentra en el espacio de búsqueda predeterminado: batch, epochs y la arquitectura permanecen fijos. El sintonizador también muta la planificación, las ganancias de pérdida y las aumentaciones enumeradas abajo.

Para ver una lista completa de los hiperparámetros de aumento utilizados en YOLO26, consulta la configurations page.

Evolución genética y mutación#

Ultralytics YOLO utiliza genetic algorithms para optimizar los hiperparámetros. Los algoritmos genéticos están inspirados en el mecanismo de la selección natural y la genética.

• Cruce: Cada iteración combina genes de hasta nueve de las configuraciones con mejor aptitud encontradas hasta el momento, utilizando el cruce BLX-α con selección de padres ponderada por aptitud.
• Mutación: El candidato recombinado se perturba mediante un factor multiplicativo log-normal aplicado a cada hiperparámetro (con una probabilidad de 0.5 por parámetro). La fuerza de mutación sigma decae linealmente de 0.2 a 0.1 durante las primeras 300 iteraciones, de modo que el algoritmo explora ampliamente al principio y se refina a medida que converge. La iteración 1 no tiene padres con los que cruzarse y utiliza los hiperparámetros de entrenamiento predeterminados como referencia.

Preparación para el ajuste de hiperparámetros#

Antes de comenzar el proceso de ajuste, es importante:

1. Identifica las métricas: El sintonizador integrado (use_ray=False) clasifica las pruebas según la puntuación de fitness de la tarea, mientras que use_ray=True utiliza la métrica de la tarea. Decide qué métricas secundarias vas a inspeccionar, como AP50 o la puntuación F1.
2. Establecer el presupuesto de ajuste: Define cuántos recursos computacionales estás dispuesto a asignar. El ajuste de hiperparámetros puede consumir muchos recursos.

Cómo funciona el bucle de ajuste#

Para cada iteración, el ajustador integrado repite el siguiente bucle:

1. Inicializa los hiperparámetros: comienza desde una línea base razonable, ya sea los hiperparámetros predeterminados establecidos por Ultralytics YOLO o valores basados en tu conocimiento del dominio o en experimentos previos.
2. Mutar hiperparámetros — la Tuner class produce automáticamente un nuevo conjunto de hiperparámetros a partir del conjunto existente con su método _mutate.
3. Entrena el modelo: entrena usando los hiperparámetros mutados y, a continuación, evalúa el rendimiento del entrenamiento con las métricas que hayas elegido.
4. Evalúa el modelo: el proceso de evaluación produce la puntuación de adecuación de la iteración, que se compara con las iteraciones anteriores para determinar si los hiperparámetros actuales suponen una mejora.
5. Registra los resultados: guarda tanto las métricas de rendimiento como los hiperparámetros correspondientes para futuras consultas. Ultralytics YOLO guarda automáticamente estos resultados en formato NDJSON.
6. Repite: continúa hasta alcanzar el número establecido de iteraciones, donde cada iteración se basa en el conocimiento obtenido de ejecuciones anteriores. El sintonizador integrado ejecuta todas las iterations; Ray Tune informa de las métricas después de cada época de ajuste, lo que permite a ASHA detener las pruebas débiles una vez transcurrido su periodo de gracia.

Iteraciones y tamaño de población#

Con el sintonizador integrado (use_ray=False), iterations controla el número total de pruebas secuenciales. Cada prueba entrena un modelo con una configuración de hiperparámetros —por ejemplo, iterations=40 con epochs=50 programa 40 entrenamientos independientes de 50 épocas, no un único entrenamiento de 50 épocas con una población separada de 40 candidatos.

El algoritmo genético integrado no tiene un parámetro explícito de tamaño de población. Una vez que existen ensayos previos, toma como padres hasta nueve de las configuraciones con mejor aptitud, aplica cruce BLX-α y mutación, y genera un candidato por iteración.

Para pruebas en paralelo o estrategias de búsqueda más avanzadas, configura use_ray=True para utilizar Ray Tune, el cual recibe iterations como num_samples. Consulta la Ray Tune integration guide para obtener más detalles.

Espacio de búsqueda predeterminado#

La siguiente tabla enumera los parámetros del espacio de búsqueda predeterminados para la optimización de hiperparámetros en YOLO26. Cada parámetro tiene un rango de valores específico definido por una tupla (min, max).

Ejemplo de espacio de búsqueda personalizado#

Así es como se define un espacio de búsqueda y se utiliza el método model.tune() para emplear la clase Tuner en la optimización de hiperparámetros de YOLO26n en COCO8 durante 30 épocas con un optimizador AdamW, omitiendo la creación de gráficos, los puntos de control y la validación excepto en la época final para lograr una sintonización más rápida.

from ultralytics import YOLO

# Initialize the YOLO model
model = YOLO("yolo26n.pt")

# Define search space
search_space = {
    "lr0": (1e-5, 1e-2),
    "degrees": (0.0, 45.0),
}

# Tune hyperparameters on COCO8 for 30 epochs
model.tune(
    data="coco8.yaml",
    epochs=30,
    iterations=300,
    optimizer="AdamW",
    space=search_space,
    plots=False,
    save=False,
    val=False,
)

Reanudar una sesión de ajuste de hiperparámetros interrumpida#

Puedes reanudar una sesión de ajuste de hiperparámetros interrumpida pasando resume=True. Opcionalmente, puedes pasar el directorio name utilizado en runs/{task} para reanudarla. Si no se incluye un name, se reanuda el directorio llamado literalmente tune, que es el nombre predeterminado en lugar de la sesión que se haya ejecutado más recientemente, así que pasa name para cualquier ejecución que hayas iniciado con uno personalizado. También debes proporcionar todos los argumentos de entrenamiento anteriores, incluidos data, epochs, iterations y space.

from ultralytics import YOLO

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

# Define search space
search_space = {
    "lr0": (1e-5, 1e-2),
    "degrees": (0.0, 45.0),
}

# Resume previous run
results = model.tune(data="coco8.yaml", epochs=50, iterations=300, space=search_space, resume=True)

# Resume tuning run with name 'tune_exp'
results = model.tune(data="coco8.yaml", epochs=50, iterations=300, space=search_space, name="tune_exp", resume=True)

Resultados#

Después de completar con éxito el proceso de ajuste de hiperparámetros, obtendrás varios archivos y directorios que encapsulan los resultados. A continuación se describe cada uno:

Estructura de archivos#

Así es como se verá la estructura de directorios de los resultados. Los directorios de entrenamiento como train/ y train-2/ contienen iteraciones de ajuste individuales, es decir, un modelo entrenado con un conjunto de hiperparámetros. El directorio tune/ contiene los resultados del ajuste de todos los entrenamientos de modelos individuales:

runs/
└── detect/
    ├── train/
    ├── train-2/
    ├── ...
    └── tune/
        ├── best_hyperparameters.yaml
        ├── tune_fitness.png
        ├── tune_results.ndjson
        ├── tune_scatter_plots.png
        └── weights/
            ├── last.pt
            └── best.pt

Descripciones de archivos#

best_hyperparameters.yaml#

Este archivo YAML contiene los hiperparámetros con mejor rendimiento encontrados durante el proceso de ajuste. Puedes usar este archivo para inicializar futuros entrenamientos con estos ajustes optimizados.

• Formato: YAML

• Uso: Resultados de hiperparámetros

• Ejemplo:

  # 558/900 iterations complete ✅ (45536.81s)
  # Results saved to /usr/src/ultralytics/runs/detect/tune
  # Best fitness=0.64297 observed at iteration 498
  # Best fitness metrics are {'metrics/precision(B)': 0.87247, 'metrics/recall(B)': 0.71387, 'metrics/mAP50(B)': 0.79106, 'metrics/mAP50-95(B)': 0.62651, 'val/box_loss': 2.79884, 'val/cls_loss': 2.72386, 'val/l1_loss': 0.68503, 'fitness': 0.64297}
  # Best fitness model is /usr/src/ultralytics/runs/detect/tune/weights
  # Best fitness hyperparameters are printed below.
  
  lr0: 0.00269
  lrf: 0.00288
  momentum: 0.73375
  weight_decay: 0.00015
  warmup_epochs: 1.22935
  warmup_momentum: 0.1525
  box: 18.27875
  cls: 1.32899
  dfl: 0.56016
  hsv_h: 0.01148
  hsv_s: 0.53554
  hsv_v: 0.13636
  degrees: 0.0
  translate: 0.12431
  scale: 0.07643
  shear: 0.0
  perspective: 0.0
  flipud: 0.0
  fliplr: 0.08631
  mosaic: 0.42551
  mixup: 0.0
  copy_paste: 0.0

tune_fitness.png#

Este es un gráfico que muestra la aptitud (fitness) frente al número de iteraciones. Te ayuda a visualizar cómo se desempeñó el algoritmo genético a lo largo del tiempo.

• Formato: PNG
• Uso: Visualización del rendimiento

El gráfico contiene:

• Un marcador por iteración por conjunto de datos, por lo que una ejecución de conjunto de datos único muestra un punto por iteración, y una ejecución de múltiples conjuntos de datos muestra un punto por conjunto de datos por iteración.
• Una línea punteada de "media suavizada" calculada como un suavizado gaussiano (sigma=3) sobre los valores de aptitud de nivel superior por iteración.

tune_results.ndjson#

Un archivo NDJSON que contiene resultados detallados de cada iteración de ajuste. Cada línea es un objeto JSON con la aptitud agregada, los hiperparámetros ajustados y las métricas por conjunto de datos. El ajuste de conjunto de datos único y el de múltiples conjuntos de datos usan el mismo formato de archivo.

• Formato: NDJSON
• Uso: Seguimiento de resultados por iteración.
• Ejemplo:

A continuación se muestra un ejemplo con formato bonito para facilitar la lectura; en el archivo .ndjson real, cada objeto se almacena en una sola línea.

{
    "iteration": 1,
    "fitness": 0.48628,
    "hyperparameters": {
        "lr0": 0.01,
        "lrf": 0.01,
        "momentum": 0.937,
        "weight_decay": 0.0005
    },
    "datasets": {
        "coco8": {
            "metrics/precision(B)": 0.65666,
            "metrics/recall(B)": 0.85,
            "metrics/mAP50(B)": 0.85086,
            "metrics/mAP50-95(B)": 0.64104,
            "val/box_loss": 1.57958,
            "val/cls_loss": 1.04986,
            "val/l1_loss": 1.32641,
            "fitness": 0.64104
        },
        "coco8-grayscale": {
            "metrics/precision(B)": 0.6582,
            "metrics/recall(B)": 0.51667,
            "metrics/mAP50(B)": 0.59106,
            "metrics/mAP50-95(B)": 0.33152,
            "val/box_loss": 1.95424,
            "val/cls_loss": 1.64059,
            "val/l1_loss": 1.70226,
            "fitness": 0.33152
        }
    },
    "save_dirs": {
        "coco8": "runs/detect/coco8",
        "coco8-grayscale": "runs/detect/coco8-grayscale"
    }
}

El valor de nivel superior fitness es la media aritmética de los valores fitness por conjunto de datos. Para la sintonización con un solo conjunto de datos, el diccionario datasets tiene una entrada cuyo valor fitness es igual al fitness de nivel superior. Se registra un objeto JSON por cada iteración completada. Las rutas de save_dirs reales son absolutas; se han abreviado arriba para facilitar la lectura.

tune_scatter_plots.png#

Este archivo contiene diagramas de dispersión generados a partir de tune_results.ndjson, que te ayudan a visualizar las relaciones entre los diferentes hiperparámetros y las métricas de rendimiento. Los hiperparámetros cuyo valor predeterminado es 0 (por ejemplo, degrees y shear a continuación) pueden evolucionar lentamente desde su semilla inicial porque el factor de mutación multiplicativo tiene muy poco margen de expansión desde un valor cercano a cero.

• Formato: PNG
• Uso: Análisis exploratorio de datos

weights/#

Este directorio contiene los modelos de PyTorch guardados de la iteración con la mejor adecuación de la ejecución de ajuste. Ambos archivos proceden de esa misma iteración:

• last.pt: last.pt contiene los pesos de la última época de entrenamiento.
• best.pt: best.pt contiene los pesos de la iteración que obtuvo la mejor puntuación de aptitud.

Utilizando estos resultados, puedes tomar decisiones más informadas para futuros entrenamientos y análisis de modelos.

Conclusión#

La optimización de hiperparámetros en Ultralytics YOLO es fácil de iniciar y potente bajo el capó, ya que combina el cruce BLX-α con la mutación log-normal en un algoritmo genético. Seguir el bucle descrito en esta guía te permite sintonizar sistemáticamente tu modelo para obtener un mejor rendimiento, y luego reutilizar el archivo best_hyperparameters.yaml resultante para inicializar futuros entrenamientos. Para escalar la sintonización en pruebas paralelas y algoritmos de búsqueda más avanzados, continúa con la Ray Tune integration guide, o ejecuta trabajos gestionados con hiperparámetros configurables y seguimiento de métricas en tiempo real en Ultralytics Platform mediante cloud training.

Para configuraciones que ningún argumento expone, como tasas de aprendizaje por capa o una métrica de adecuación personalizada, crea una subclase del entrenador en su lugar. Para obtener información más detallada, explora el código fuente de la clase Tuner. Si tienes preguntas o solicitudes de funciones, ponte en contacto a través de GitHub o Discord.

FAQ#