Guía de ajuste de hiperparámetros de Ultralytics YOLO#

El ajuste de hiperparámetros en Ultralytics YOLO es una búsqueda automatizada e iterativa que optimiza configuraciones —como la tasa de aprendizaje, los pesos de la función de pérdida y la intensidad de las aumentaciones— para maximizar métricas de rendimiento de un modelo de aprendizaje automático, como la exactitud, la precisión y la exhaustividad. En lugar de probar estos valores manualmente, Ultralytics YOLO explora el espacio de hiperparámetros mediante un algoritmo genético que muta y evalúa configuraciones candidatas en muchas ejecuciones de entrenamiento breves.

¿Qué son los hiperparámetros?#

Los hiperparámetros son configuraciones estructurales de alto nivel del algoritmo. Se establecen antes de la fase de entrenamiento y permanecen constantes durante ella. Estos son algunos hiperparámetros que se ajustan habitualmente 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 función de pérdida.
• Tamaño del lote batch: número de imágenes procesadas simultáneamente en una pasada hacia delante.
• Número de épocas epochs: una época es una pasada completa hacia delante y hacia atrás de todos los ejemplos de entrenamiento.
• Especificaciones de la arquitectura: como el número de canales, el número de capas, los tipos de funciones de activación, etc. Se encuentran en la configuración YAML del modelo, no en los argumentos de entrenamiento.

De estos cuatro, solo la tasa de aprendizaje está en el espacio de búsqueda predeterminado: batch, epochs y la arquitectura permanecen fijos. El ajustador también muta el plan, las ganancias de la pérdida y las aumentaciones que se indican a continuación.

Para consultar la lista completa de hiperparámetros de aumentación utilizados en YOLO26, consulta la página de configuraciones.

Evolución y mutación genética#

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

• Selección: en cada iteración se selecciona una de hasta nueve configuraciones con mayor aptitud, ponderadas por su aptitud. Después de 30 resultados, el 20 % de los mejores resultados (hasta 30) también estima la covarianza de los parámetros, con una influencia que aumenta a medida que se acumula evidencia de la élite.
• Mutación: en cada iteración se muta aproximadamente la mitad de los parámetros mediante pasos gaussianos normalizados según sus rangos de búsqueda. Cuando la covarianza está activa, una proporción ponderada por confianza de como máximo el 40 % utiliza pasos correlacionados, y la reflexión devuelve esos pasos dentro de los límites sin acumular valores recortados. A medida que se acumulan ensayos sin mejora, los tamaños de paso se reducen linealmente hasta un 20 % a lo largo de 25 ensayos y se restablecen cuando se encuentra un nuevo mejor resultado. La iteración 1 no tiene padre y utiliza los hiperparámetros de entrenamiento predeterminados como referencia.

Preparación del ajuste de hiperparámetros#

Antes de comenzar el proceso de ajuste, es importante:

1. Identificar las métricas: el ajustador integrado (use_ray=False) clasifica los ensayos según la puntuación fitness de la tarea, mientras que use_ray=True utiliza la métrica de la tarea. Decide qué métricas secundarias vas a revisar, 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 requerir muchos recursos computacionales.

Cómo funciona el bucle de ajuste#

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

1. Inicializar los hiperparámetros — parte de una referencia razonable, ya sean los hiperparámetros predeterminados establecidos por Ultralytics YOLO o valores basados en tus conocimientos del dominio o en experimentos anteriores.
2. Mutar los hiperparámetros — la clase Tuner produce automáticamente un nuevo conjunto de hiperparámetros a partir del conjunto existente mediante su método _mutate.
3. Entrenar el modelo — entrena utilizando los hiperparámetros mutados y evalúa después el rendimiento del entrenamiento con las métricas que hayas elegido.
4. Evaluar el modelo — el proceso de evaluación produce la puntuación de aptitud de la iteración, que se compara con las iteraciones anteriores para determinar si los hiperparámetros actuales suponen una mejora.
5. Registrar los resultados — guarda las métricas de rendimiento y los hiperparámetros correspondientes para consultarlos en el futuro. Ultralytics YOLO guarda automáticamente estos resultados en formato NDJSON.
6. Repetir — continúa hasta alcanzar el número establecido de iteraciones, de modo que cada iteración se basa en los conocimientos obtenidos de las ejecuciones anteriores. El ajustador 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 los ensayos débiles una vez transcurrido su periodo de gracia.

Iteraciones y tamaño de la población#

Con el ajustador integrado (use_ray=False), iterations controla el número total de ensayos secuenciales y tiene un valor predeterminado de 300. Cada ensayo entrena un modelo con una configuración de hiperparámetros —por ejemplo, iterations=40 con epochs=50 programa 40 ejecuciones de entrenamiento independientes de 50 épocas, no una ejecución de 50 épocas con una población independiente 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 anteriores, selecciona hasta nueve de las configuraciones con mayor aptitud y muta un candidato por iteración.

Para realizar ensayos en paralelo o utilizar estrategias de búsqueda más avanzadas, establece use_ray=True para usar Ray Tune, que utiliza el mismo valor predeterminado de 300 ensayos y recibe iterations como num_samples. Consulta la guía de integración de Ray Tune para obtener más información.

Espacio de búsqueda predeterminado#

La siguiente tabla muestra los parámetros del espacio de búsqueda predeterminado para el ajuste 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í puedes definir un espacio de búsqueda y utilizar el método model.tune() para emplear la clase Tuner en el ajuste de hiperparámetros de YOLO26n en COCO8 durante 30 épocas con un optimizador AdamW, omitiendo la generación de gráficos, los puntos de control y la validación, excepto en la época final, para acelerar el ajuste.

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. También puedes pasar opcionalmente el directorio name utilizado en runs/{task} para reanudarla. Sin un name, reanuda literalmente el directorio llamado tune, que es el nombre predeterminado y no el de la sesión ejecutada más recientemente; por tanto, pasa name para cualquier ejecución que hayas iniciado con un nombre 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 correctamente el proceso de ajuste de hiperparámetros, obtendrás varios archivos y directorios que contienen los resultados del ajuste. A continuación se describe cada uno:

Estructura de archivos#

Esta es la estructura de directorios que tendrán 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

Descripción de los archivos#

best_hyperparameters.yaml#

Este archivo YAML contiene los hiperparámetros con mejor rendimiento encontrados durante el proceso de ajuste. Puedes utilizarlo para inicializar futuros entrenamientos con estas configuraciones optimizadas.

• 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 gráfico muestra la aptitud frente al número de iteraciones. Te ayuda a visualizar el rendimiento del algoritmo genético a lo largo del tiempo.

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

El gráfico contiene:

• Un marcador por iteración y conjunto de datos, por lo que una ejecución con un solo conjunto de datos muestra un punto por iteración, mientras que una ejecución con varios conjuntos de datos muestra un punto por conjunto de datos e iteración.
• Una línea de «media suavizada» de puntos calculada mediante un suavizado gaussiano (sigma=3) sobre los valores de aptitud de nivel superior de cada iteración.

tune_results.ndjson#

Un archivo NDJSON que contiene los 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 con un solo conjunto de datos y con varios conjuntos de datos utiliza el mismo formato de archivo.

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

A continuación se muestra un ejemplo con formato legible; 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 fitness de nivel superior es la media aritmética de los valores fitness por conjunto de datos. En el ajuste con un solo conjunto de datos, el diccionario datasets contiene una entrada cuyo fitness es igual al fitness de nivel superior. Se registra un objeto JSON por cada iteración completada. Las rutas reales de save_dirs son absolutas; se abrevian arriba para facilitar la lectura.

tune_scatter_plots.png#

Este archivo contiene gráficos de dispersión generados a partir de tune_results.ndjson, que te ayudan a visualizar las relaciones entre distintos hiperparámetros y métricas de rendimiento. La mutación utiliza el rango configurado de cada hiperparámetro, por lo que los valores pueden evolucionar desde valores predeterminados iguales a cero, como degrees y shear.

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

weights/#

Este directorio contiene los modelos de PyTorch guardados de la iteración con mejor aptitud 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 logró la mejor puntuación de aptitud.

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

Conclusión#

El ajuste de hiperparámetros en Ultralytics YOLO es sencillo de iniciar y potente internamente, ya que utiliza selección ponderada por aptitud y mutación normalizada según el rango en un algoritmo genético. Si sigues el bucle descrito en esta guía, podrás ajustar sistemáticamente tu modelo para obtener un mejor rendimiento y reutilizar después el best_hyperparameters.yaml resultante para inicializar futuras ejecuciones de entrenamiento. Para ampliar el ajuste a ensayos en paralelo y algoritmos de búsqueda más avanzados, continúa con la guía de integración de Ray Tune, o ejecuta trabajos gestionados con hiperparámetros configurables y seguimiento de métricas en tiempo real en Ultralytics Platform mediante el entrenamiento en la nube.

Para las configuraciones que no expone ningún argumento, como las tasas de aprendizaje por capa o una métrica de aptitud personalizada, hereda del entrenador. Para obtener información más detallada, explora el código fuente de la clase Tuner. Si tienes preguntas o solicitudes de funcionalidades, ponte en contacto con nosotros en GitHub o Discord.

Preguntas frecuentes#