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

El ajuste de hiperparámetros en Ultralytics YOLO es una búsqueda automatizada e iterativa que optimiza parámetros —como la tasa de aprendizaje, los pesos de pérdida y la intensidad del aumento de datos— para maximizar las métricas de rendimiento de un modelo de aprendizaje automático, como la exactitud, la precisión y la recuperación. 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 numerosas ejecuciones de entrenamiento breves.

¿Qué son los hiperparámetros?#

Los hiperparámetros son parámetros estructurales de alto nivel del algoritmo. Se establecen antes de la fase de entrenamiento y permanecen constantes durante esta. Estos son algunos hiperparámetros que suelen ajustarse en Ultralytics YOLO:

• Tasa de aprendizaje lr0: Determina el tamaño del paso en cada iteración al avanzar 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 por todos los ejemplos de entrenamiento.
• Detalles de la arquitectura: Como el número de canales, el número de capas, los tipos de funciones de activación, etc. Estos parámetros se encuentran en la configuración YAML del modelo, no en los argumentos de entrenamiento.

De estos cuatro, solo la tasa de aprendizaje forma parte del espacio de búsqueda predeterminado: batch, epochs y la arquitectura permanecen fijos. El optimizador también modifica el plan de aprendizaje, las ganancias de pérdida y los aumentos de datos que se indican a continuación.

Para consultar la lista completa de hiperparámetros de aumento de datos que se usan en YOLO26, visita la página de configuraciones.

Evolución genética y mutación#

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 según su aptitud. Tras 30 resultados, el 20 % de los mejores resultados (hasta 30) también permite estimar la covarianza de los parámetros, cuya influencia aumenta a medida que se acumulan evidencias de las configuraciones mejor valoradas.
• 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 la confianza, de hasta el 40 %, usa pasos correlacionados; la reflexión mantiene esos pasos dentro de los límites sin acumular valores recortados. A medida que se acumulan pruebas sin mejoras, el tamaño de los pasos se reduce linealmente hasta un 20 % a lo largo de 25 pruebas y se restablece cuando se encuentra un nuevo mejor resultado. La iteración 1 no tiene configuración parental y usa los hiperparámetros de entrenamiento predeterminados como referencia.

Preparación para el ajuste de hiperparámetros#

Antes de iniciar el proceso de ajuste, es importante que:

1. Identifiques las métricas: El optimizador integrado (use_ray=False) clasifica las pruebas 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 examinar, como AP50 o la puntuación F1.
2. Establezcas 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 ciclo de ajuste#

En cada iteración, el optimizador integrado repite el siguiente ciclo:

1. Inicializar los hiperparámetros — parte de una configuración de referencia razonable, ya sean los hiperparámetros predeterminados de Ultralytics YOLO o valores basados en tus conocimientos del dominio o en experimentos anteriores.
2. Mutar los hiperparámetros — la clase Tuner genera automáticamente un nuevo conjunto de hiperparámetros a partir del conjunto existente mediante el método _mutate.
3. Entrenar el modelo — entrena con los hiperparámetros mutados y, después, evalúa el rendimiento del entrenamiento con las métricas que hayas elegido.
4. Evaluar el modelo — el proceso de evaluación genera 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 junto con los hiperparámetros correspondientes para consultarlos más adelante. Ultralytics YOLO guarda estos resultados automáticamente en formato NDJSON.
6. Repetir — continúa hasta alcanzar el número de iteraciones establecido; cada iteración aprovecha los conocimientos obtenidos en las ejecuciones anteriores. El optimizador integrado ejecuta todos los iterations; Ray Tune informa de las métricas después de cada época de ajuste, lo que permite a ASHA detener las pruebas poco prometedoras una vez transcurrido su periodo de gracia.

Iteraciones y tamaño de la población#

Con el optimizador integrado (use_ray=False), iterations controla el número total de pruebas secuenciales y su valor predeterminado es 300. Cada prueba 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 única ejecución de 50 épocas con una población aparte de 40 candidatos.

El algoritmo genético integrado no tiene un parámetro explícito para el tamaño de la población. Cuando ya hay pruebas anteriores, selecciona entre un máximo de nueve configuraciones con mayor aptitud y muta una candidata por iteración.

Para ejecutar pruebas en paralelo o usar estrategias de búsqueda más avanzadas, configura use_ray=True para usar Ray Tune, que también tiene un valor predeterminado de 300 pruebas 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 enumera 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 mediante una tupla (min, max).

Ejemplo de espacio de búsqueda personalizado#

Así se define un espacio de búsqueda y se usa el método model.tune() para utilizar la clase Tuner en el ajuste de hiperparámetros de YOLO26n con COCO8 durante 30 épocas, con un optimizador AdamW y sin generar gráficos, guardar puntos de control ni validar, salvo en la última época, para agilizar el ajuste.

from ultralytics import YOLO

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

# Define el espacio de búsqueda
search_space = {
    "lr0": (1e-5, 1e-2),
    "degrees": (0.0, 45.0),
}

# Ajusta los hiperparámetros con COCO8 durante 30 épocas
model.tune(
    data="coco8.yaml",
    epochs=30,
    iterations=300,
    optimizer="AdamW",
    space=search_space,
    plots=False,
    save=False,
    val=False,
)

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

Puedes reanudar una sesión interrumpida de ajuste de hiperparámetros pasando resume=True. Opcionalmente, puedes pasar el directorio name usado en runs/{task} para reanudar la sesión. Si no indicas name, se reanuda el directorio llamado literalmente tune, que es el nombre predeterminado y no el de la sesión ejecutada más recientemente. Por tanto, pasa name si iniciaste una ejecución 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 un modelo YOLO
model = YOLO("yolo26n.pt")

# Define el espacio de búsqueda
search_space = {
    "lr0": (1e-5, 1e-2),
    "degrees": (0.0, 45.0),
}

# Reanuda la ejecución anterior
results = model.tune(data="coco8.yaml", epochs=50, iterations=300, space=search_space, resume=True)

# Reanuda la ejecución de ajuste con el nombre 'tune_exp'
results = model.tune(data="coco8.yaml", epochs=50, iterations=300, space=search_space, name="tune_exp", resume=True)

Resultados#

Cuando hayas completado 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 barrido, como multitrain/ y multitrain-2/, contienen iteraciones de ajuste individuales; es decir, un modelo entrenado por conjunto de datos con un conjunto de hiperparámetros, en un subdirectorio con el nombre de cada conjunto de datos. Para ahorrar espacio, el optimizador elimina los directorios de ejecución por conjunto de datos de las iteraciones que no son las mejores actuales. El directorio tune/ contiene los resultados del ajuste de todos los entrenamientos individuales de modelos:

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

Descripciones de los archivos#

best_hyperparameters.yaml#

Este archivo YAML contiene los hiperparámetros con mejor rendimiento obtenidos durante el proceso de ajuste. Puedes usar este archivo para inicializar futuros entrenamientos con estos parámetros 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 gráfico muestra la aptitud en función del 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 y una ejecución con varios conjuntos muestra un punto por cada conjunto de datos e iteración.
• Una línea de «media suavizada» de puntos calculada mediante un suavizado gaussiano (sigma=3) de 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 del ajuste. Cada línea es un objeto JSON con la aptitud agregada, los hiperparámetros ajustados y las métricas de cada conjunto de datos. El ajuste con uno o varios conjuntos de datos utiliza el mismo formato de archivo.

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

A continuación se muestra un ejemplo con formato legible; en el archivo real .ndjson, cada objeto se guarda 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/multitrain/coco8",
        "coco8-grayscale": "runs/detect/multitrain/coco8-grayscale"
    }
}

El fitness de nivel superior es la media aritmética de los valores fitness de cada conjunto de datos. En el ajuste con un solo conjunto de datos, el diccionario datasets tiene 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; arriba se han abreviado 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 los distintos hiperparámetros y las métricas de rendimiento. La mutación utiliza el rango configurado para cada hiperparámetro, por lo que los valores pueden evolucionar a partir de valores predeterminados de cero, como degrees y shear.

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

weights/#

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

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

Conclusión#

El ajuste de hiperparámetros en Ultralytics YOLO es fácil de iniciar y potente por dentro, ya que utiliza una selección ponderada por aptitud y mutaciones normalizadas por rango en un algoritmo genético. Si sigues el ciclo descrito en esta guía, podrás ajustar sistemáticamente tu modelo para mejorar su 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 los ajustes que no estén disponibles mediante ningún argumento, como las tasas de aprendizaje por capa o una métrica de aptitud personalizada, crea una subclase del entrenador. Para profundizar, explora el código fuente de la clase Tuner. Si tienes preguntas o quieres solicitar una función, ponte en contacto con nosotros en GitHub o Discord.

Preguntas frecuentes#