Empezar

Ajuste eficiente de hiperparámetros con Ray Tune y YOLO26

El ajuste de hiperparámetros busca el conjunto de hiperparámetros que ofrece el mejor rendimiento del modelo. Ejecuta pruebas con distintos valores de hiperparámetros y evalúa el rendimiento de cada una.

Acelera el ajuste con Ultralytics YOLO26 y Ray Tune#

Ultralytics YOLO26 integra Ray Tune para ajustar hiperparámetros. Con Ray Tune, puedes utilizar estrategias de búsqueda avanzadas, paralelismo y parada temprana para agilizar el proceso de ajuste.

Ray Tune#

Ray Tune hyperparameter optimization workflow

Ray Tune es una biblioteca de ajuste de hiperparámetros diseñada para ofrecer eficiencia y flexibilidad. Admite diversas estrategias de búsqueda, paralelismo y estrategias de parada temprana, y se integra con frameworks populares de aprendizaje automático, incluido Ultralytics YOLO26.

Integración con Weights & Biases#

YOLO26 también admite una integración opcional con Weights & Biases para supervisar el proceso de ajuste.

Instalación#

Para instalar los paquetes necesarios, ejecuta:

Instalación
# Install and update Ultralytics and Ray Tune packages
pip install -U ultralytics "ray[tune]" optuna

# Optionally install and enable W&B for per-trial logging
pip install wandb
yolo settings wandb=True

Uso#

Uso
from ultralytics import YOLO

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

# Empieza a ajustar los hiperparámetros del entrenamiento de YOLO26n con el conjunto de datos COCO8
result_grid = model.tune(data="coco8.yaml", use_ray=True)

Parámetros del método tune()#

El método tune() de YOLO26 ofrece una interfaz fácil de usar para ajustar hiperparámetros con Ray Tune. Acepta varios argumentos que te permiten personalizar el proceso de ajuste. A continuación, se explica cada parámetro en detalle:

ParámetroTipoDescripciónValor predeterminado
datastr or listEl archivo YAML del conjunto de datos para ejecutar el optimizador, que especifica las rutas de los datos de validación y de entrenamiento, además de otros ajustes específicos del conjunto de datos. Para la clasificación, se utiliza un directorio de conjunto de datos o el nombre de un conjunto de datos integrado (por ejemplo, imagenet10). Una lista entrena cada prueba con todos los conjuntos de datos e informa de la métrica media de la tarea.
spacedict, optionalDiccionario que define el espacio de búsqueda de hiperparámetros para Ray Tune. Cada clave corresponde al nombre de un hiperparámetro y el valor especifica el intervalo de valores que se explorará durante el ajuste. Si no se proporciona, YOLO26 utiliza un espacio de búsqueda predeterminado con varios hiperparámetros.
grace_periodint, optionalEl período de gracia en épocas para el programador ASHA en Ray Tune. El programador no terminará ningún ensayo antes de que transcurra este número de épocas (limitado a epochs). No se usa con search_alg="bohb".10
gpu_per_trialint, optionalNúmero de GPU que Ray asigna a cada prueba. Establécelo explícitamente para utilizar el entrenamiento con GPU; si se omite, las pruebas no recibirán recursos de GPU.None
iterationsint, optionalNúmero máximo de pruebas que se ejecutarán durante el ajuste. Este parámetro ayuda a controlar el número total de combinaciones de hiperparámetros evaluadas y evita que el proceso de ajuste se ejecute indefinidamente.300
search_algstr or Searcher, optionalEstrategia de búsqueda de Ray Tune que se utilizará. Puedes pasar directamente un objeto buscador de Ray o utilizar una cadena compatible, como optuna, hyperopt, bayesopt, bohb, hebo, nevergrad, zoopt, ax o random. Los buscadores especificados mediante cadenas utilizan automáticamente la métrica predeterminada de la tarea y mode="max". De forma predeterminada, se utiliza TPE multivariante de Optuna con sugerencias adaptadas al paralelismo."optuna"
**train_argsdict, optionalArgumentos adicionales que se pasarán al método train() durante el ajuste. Estos argumentos pueden incluir opciones como el número de épocas de entrenamiento, el tamaño del lote y otras configuraciones específicas del entrenamiento.{}

Personaliza estos parámetros para adaptar el proceso de optimización de hiperparámetros a tus necesidades específicas y a los recursos computacionales disponibles.

Descripción del espacio de búsqueda predeterminado#

La siguiente tabla enumera los parámetros del espacio de búsqueda predeterminado para ajustar hiperparámetros en YOLO26 con Ray Tune. Cada parámetro tiene un intervalo de valores específico definido por tune.uniform(), excepto close_mosaic, que utiliza tune.randint().

ParámetroIntervaloDescripción
lr0tune.uniform(1e-5, 1e-2)Tasa de aprendizaje inicial que controla el tamaño del paso durante la optimización. Los valores más altos aceleran el entrenamiento, pero pueden provocar inestabilidad.
lrftune.uniform(0.01, 1.0)Factor de la tasa de aprendizaje final que determina cuánto disminuye la tasa de aprendizaje al final del entrenamiento.
momentumtune.uniform(0.7, 0.98)Factor de momentum del optimizador que ayuda a acelerar el entrenamiento y a superar los mínimos locales.
weight_decaytune.uniform(0.0, 0.001)Parámetro de regularización que evita el sobreajuste penalizando los valores de pesos elevados.
warmup_epochstune.uniform(0.0, 5.0)Número de épocas durante las que la tasa de aprendizaje aumenta gradualmente para estabilizar las primeras fases del entrenamiento.
warmup_momentumtune.uniform(0.0, 0.95)Valor inicial del momentum, que aumenta gradualmente durante el periodo de calentamiento.
boxtune.uniform(1.0, 20.0)Peso del componente de pérdida de los cuadros delimitadores, que equilibra la precisión de localización del modelo.
clstune.uniform(0.1, 4.0)Peso del componente de pérdida de clasificación, que equilibra la precisión de predicción de clases del modelo.
cls_pwtune.uniform(0.0, 1.0)Potencia de ponderación de clases: desde desactivada (0.0) hasta la ponderación inversa completa por frecuencia (1.0).
dfltune.uniform(0.4, 12.0)Peso del componente de regresión de la distancia del cuadro, que prioriza una localización precisa de los cuadros delimitadores.
hsv_htune.uniform(0.0, 0.1)Intervalo de aumento del tono que introduce variabilidad cromática para ayudar al modelo a generalizar.
hsv_stune.uniform(0.0, 0.9)Intervalo de aumento de la saturación que varía la intensidad del color para mejorar la robustez.
hsv_vtune.uniform(0.0, 0.9)Intervalo de aumento del valor (brillo) que ayuda al modelo a funcionar en distintas condiciones de iluminación.
degreestune.uniform(0.0, 45.0)Intervalo de aumento de rotación en grados, que mejora el reconocimiento de objetos girados.
translatetune.uniform(0.0, 0.9)Intervalo de aumento de traslación que desplaza las imágenes horizontal y verticalmente.
scaletune.uniform(0.0, 0.95)Intervalo de aumento de escala que simula objetos a distintas distancias.
sheartune.uniform(0.0, 10.0)Intervalo de aumento de cizallamiento en grados, que simula cambios de perspectiva.
perspectivetune.uniform(0.0, 0.001)Intervalo de aumento de perspectiva que simula cambios de punto de vista en 3D.
flipudtune.uniform(0.0, 1.0)Probabilidad de aumento de volteo vertical, que incrementa la diversidad del conjunto de datos.
fliplrtune.uniform(0.0, 1.0)Probabilidad de aumento de volteo horizontal, útil para objetos simétricos.
bgrtune.uniform(0.0, 1.0)Probabilidad de aumento mediante intercambio de canales BGR, que ayuda a lograr invariancia cromática.
mosaictune.uniform(0.0, 1.0)Probabilidad de aumento Mosaic, que combina cuatro imágenes en una muestra de entrenamiento.
mixuptune.uniform(0.0, 1.0)Probabilidad de aumento MixUp, que mezcla dos imágenes y sus etiquetas.
cutmixtune.uniform(0.0, 1.0)Probabilidad de aumento CutMix, que combina regiones de imágenes y conserva las características locales.
copy_pastetune.uniform(0.0, 1.0)En el modo flip, fracción de objetos aptos que se copian en una imagen; en el modo mixup, también es la probabilidad de ejecutarlo.
close_mosaictune.randint(0, 11)Desactiva Mosaic durante las últimas N épocas para estabilizar el entrenamiento antes de finalizar.

Ejemplo de espacio de búsqueda personalizado#

Este ejemplo muestra cómo utilizar un espacio de búsqueda personalizado para ajustar hiperparámetros con Ray Tune y YOLO26. Al proporcionar un espacio de búsqueda personalizado, puedes centrar el proceso de ajuste en los hiperparámetros que te interesan.

Uso
from ray import tune

from ultralytics import YOLO

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

# Ejecuta Ray Tune en el modelo
result_grid = model.tune(
    data="coco8.yaml",
    space={"lr0": tune.uniform(1e-5, 1e-2)},
    epochs=50,
    use_ray=True,
)

El fragmento de código anterior crea un modelo YOLO a partir de los pesos preentrenados de YOLO26n y, después, llama al método tune() con la configuración del conjunto de datos coco8.yaml. Proporciona un espacio de búsqueda personalizado para la tasa de aprendizaje inicial lr0 como un diccionario con la clave "lr0" y el valor tune.uniform(1e-5, 1e-2). Por último, pasa argumentos de entrenamiento adicionales, como el número de épocas, directamente al método tune como epochs=50.

Ejemplo de algoritmo de búsqueda#

Puedes seleccionar una estrategia de búsqueda de Ray Tune por nombre. Para los algoritmos de búsqueda especificados mediante cadenas, Ultralytics utilizará automáticamente la métrica de optimización predeterminada de la tarea actual y mode="max". Si no se proporciona search_alg, Ultralytics utiliza TPE multivariante de Optuna con sugerencias adaptadas al paralelismo.

Uso de la cadena `search_alg` con `model.tune()`
from ultralytics import YOLO

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

result_grid = model.tune(
    data="coco8.yaml",
    epochs=50,
    search_alg="optuna",
    use_ray=True,
)

Si necesitas personalizar el muestreador del buscador o anular su métrica y modo de optimización, pasa un objeto buscador de Ray Tune instanciado en lugar de una cadena.

Uso del objeto `OptunaSearch` con `model.tune()`
from ray.tune.search.optuna import OptunaSearch

from ultralytics import YOLO

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

# Define un buscador
searcher = OptunaSearch(
    metric="metrics/mAP50-95(B)",
    mode="max",
)

result_grid = model.tune(
    data="coco8.yaml",
    epochs=50,
    search_alg=searcher,
    use_ray=True,
)

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

Puedes reanudar una sesión interrumpida de Ray Tune pasando resume=True. Si quieres, puedes pasar el directorio name que Ray Tune utiliza en runs/{task} para reanudarla. De lo contrario, se reanudará la última sesión interrumpida. No es necesario volver a proporcionar iterations ni space, pero sí debes proporcionar de nuevo el resto de los argumentos de entrenamiento, incluidos data y epochs.

Uso de `resume=True` con `model.tune()`
from ultralytics import YOLO

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

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

# Reanuda la ejecución de Ray Tune con el nombre 'tune_exp_2'
results = model.tune(use_ray=True, data="coco8.yaml", epochs=50, name="tune_exp_2", resume=True)

Procesamiento de los resultados de Ray Tune#

Después de ejecutar un experimento de ajuste de hiperparámetros con Ray Tune, quizá quieras analizar de distintas formas los resultados obtenidos. En esta guía, veremos flujos de trabajo habituales para procesar y analizar estos resultados.

Carga los resultados del experimento de Tune desde un directorio#

model.tune(use_ray=True) devuelve un ResultGrid de Ray y guarda el experimento en runs/{task}/tune o en el directorio name que hayas indicado. Para cargar esos resultados después de que se haya cerrado el script original, reanuda la sesión; así se restauran las pruebas guardadas y se devuelve el mismo ResultGrid:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")
result_grid = model.tune(data="coco8.yaml", epochs=50, use_ray=True, resume=True)

Análisis básico a nivel de experimento#

Obtén una visión general del rendimiento de las pruebas. Puedes comprobar rápidamente si se ha producido algún error durante las pruebas.

if result_grid.errors:
    print("One or more trials failed!")
else:
    print("No errors!")

Análisis básico a nivel de prueba#

Accede a las configuraciones de hiperparámetros de cada prueba y a las últimas métricas registradas.

for i, result in enumerate(result_grid):
    print(f"Trial #{i}: Configuration: {result.config}, Last Reported Metrics: {result.metrics}")

Representación gráfica del historial completo de métricas registradas de una prueba#

Puedes representar gráficamente el historial de métricas registradas de cada prueba para ver cómo han evolucionado con el tiempo.

import matplotlib.pyplot as plt

for i, result in enumerate(result_grid):
    plt.plot(
        result.metrics_dataframe["training_iteration"],
        result.metrics_dataframe["metrics/mAP50-95(B)"],
        label=f"Trial {i}",
    )

plt.xlabel("Training Iterations")
plt.ylabel("mAP50-95")
plt.legend()
plt.show()

Resumen#

En esta guía, hemos repasado flujos de trabajo habituales para analizar los resultados de experimentos ejecutados con Ray Tune mediante Ultralytics. Los pasos principales son cargar los resultados del experimento desde un directorio, realizar análisis básicos a nivel de experimento y de prueba, y representar gráficamente las métricas.

Para sacar el máximo partido a tus experimentos de ajuste de hiperparámetros, consulta la página de documentación Analizar resultados de Ray Tune.

Preguntas frecuentes#

  • Para ajustar los hiperparámetros de tu modelo Ultralytics YOLO26 con Ray Tune, sigue estos pasos:

    1. Instala los paquetes necesarios:

      pip install -U ultralytics "ray[tune]" optuna
      pip install wandb # optional for logging
      yolo settings wandb=True
    2. Carga tu modelo YOLO26 y empieza el ajuste:

      from ultralytics import YOLO
      
      # Carga un modelo YOLO26
      model = YOLO("yolo26n.pt")
      
      # Empieza el ajuste con el conjunto de datos COCO8
      result_grid = model.tune(data="coco8.yaml", use_ray=True)

    Esto utiliza las estrategias de búsqueda y el paralelismo de Ray Tune para optimizar eficazmente los hiperparámetros del modelo.

  • Ultralytics YOLO26 utiliza los siguientes hiperparámetros predeterminados para el ajuste con Ray Tune:

    ParámetroRango de valoresDescripción
    lr0tune.uniform(1e-5, 1e-2)Tasa de aprendizaje inicial
    lrftune.uniform(0.01, 1.0)Factor de la tasa de aprendizaje final
    momentumtune.uniform(0.7, 0.98)Momentum
    weight_decaytune.uniform(0.0, 0.001)Decaimiento de pesos
    warmup_epochstune.uniform(0.0, 5.0)Épocas de calentamiento
    boxtune.uniform(1.0, 20.0)Peso de la pérdida de los cuadros
    clstune.uniform(0.1, 4.0)Peso de la pérdida de clasificación
    cls_pwtune.uniform(0.0, 1.0)Potencia de ponderación de clases
    dfltune.uniform(0.4, 12.0)Peso de la pérdida de distancia de los cuadros
    hsv_htune.uniform(0.0, 0.1)Intervalo de aumento del tono
    translatetune.uniform(0.0, 0.9)Intervalo de aumento de traslación

    Puedes personalizar estos hiperparámetros para adaptarlos a tus necesidades específicas. Consulta la guía Ajuste de hiperparámetros para ver la lista completa y obtener más información.

  • Para integrar Weights & Biases (W&B) en el proceso de ajuste de Ultralytics YOLO26:

    1. Instala W&B:

      pip install wandb
      wandb login
      yolo settings wandb=True
    2. Ejecuta el ajustador:

      from ultralytics import YOLO
      
      # Cargar modelo YOLO
      model = YOLO("yolo26n.pt")
      
      # Cada prueba de Ray crea su propia ejecución de W&B en este proyecto
      result_grid = model.tune(data="coco8.yaml", project="YOLO-Tuning", use_ray=True)

    Esta configuración te permitirá supervisar el proceso de ajuste, hacer un seguimiento de las configuraciones de hiperparámetros y visualizar los resultados en W&B.

  • Ray Tune ofrece numerosas ventajas para la optimización de hiperparámetros:

    • Estrategias de búsqueda avanzadas: Utiliza algoritmos como la optimización bayesiana y HyperOpt para buscar parámetros de forma eficiente.
    • Paralelismo: Admite la ejecución en paralelo de varias pruebas, lo que acelera considerablemente el proceso de ajuste.
    • Parada temprana: Emplea estrategias como ASHA para detener pronto las pruebas con bajo rendimiento y ahorrar recursos computacionales.

    Ray Tune está integrado en Ultralytics YOLO26 mediante model.tune(use_ray=True).

  • Para definir un espacio de búsqueda personalizado para ajustar los hiperparámetros de YOLO26 con Ray Tune:

    from ray import tune
    
    from ultralytics import YOLO
    
    model = YOLO("yolo26n.pt")
    search_space = {"lr0": tune.uniform(1e-5, 1e-2), "momentum": tune.uniform(0.7, 0.98)}
    result_grid = model.tune(data="coco8.yaml", space=search_space, use_ray=True)

    Esto personaliza el rango de hiperparámetros, como la tasa de aprendizaje inicial y el momentum, que se explorarán durante el proceso de ajuste. Para ver configuraciones avanzadas, consulta la sección Ejemplo de espacio de búsqueda personalizado.

Comentarios40

Haz una pregunta, comparte tus resultados o ayuda a otra persona.

  1. supriamirGitHub

    Hi, I finish the hyperparameter tune, how to use the best parameter in best_hyperparameters.ymal for training?

    Currently i manually use the manually copy the htperparameter.

    model.train( data=str(dataset_yaml), epochs=epochs, imgsz=imgsz, batch=batch, project=project, name=f"fold_{k}", workers=0, patience=100, exist_ok=True, cache=False, device=0,

        lr0= 0.00254,
        lrf= 0.02718,
        momentum= 0.83225,
        weight_decay= 0.001,
        warmup_epochs= 2.22741,
        warmup_momentum= 0.72834,
        box= 8.86345,
        cls= 0.52365,
        dfl= 0.45493,
        hsv_h= 0.01544,
        hsv_s= 0.44438,
        hsv_v= 0.37867,
        degrees= 0.01115,
        translate= 0.10045,
        scale= 0.33157,
        shear= 0.0075,
        perspective= 6.0e-05,
        flipud= 0.00882,
        fliplr= 0.34916,
        bgr= 9.0e-05,
        mosaic= 0.63841,
        mixup= 0.00099,
        cutmix= 0.00361,
        copy_paste= 0.00051,
        close_mosaic= 6,
    )
    1. Glenn JocherUltralytics

      Yes — you can load best_hyperparameters.yaml and unpack it directly into model.train() instead of copying values by hand; see the Ray Tune integration guide and feel free to keep follow-ups here in Discussions so the Ultralytics team can see them.

      from pathlib import Path
      import yaml
      from ultralytics import YOLO
      
      model = YOLO("yolo26n.pt")
      
      hyp_path = Path("runs/detect/tune/best_hyperparameters.yaml")
      with hyp_path.open() as f:
          hyp = yaml.safe_load(f)
      
      model.train(
          data=str(dataset_yaml),
          epochs=epochs,
          imgsz=imgsz,
          batch=batch,
          project=project,
          name=f"fold_{k}",
          workers=0,
          patience=100,
          exist_ok=True,
          cache=False,
          device=0,
          **hyp,
      )
      1
  2. Emeyer87GitHub

    Hello,

    I've noticed that every Iteration with use_ray = True is downloading yolo11n.pt. I'm attempting to use this on an existing instance segmentation model I built but wanted to ensure the tuning is running against the model I've assigned, and not a fresh Detection model.

    from ultralytics import YOLO from ray import tune

    model_path = r"C:/Users/Me/Downloads/NashvilleSegmentation.pt" data_path = r"C:/Users/Me/Downloads/dataset/data.yaml" model=YOLO(model_path)

    search_space = { "degrees": tune.uniform(0.0, 12.0) }

    results = model.tune( data=data_path, epochs=20, # keep it tiny iterations=20, # exactly one trial optimizer="AdamW", space=search_space, device=0, seed=0, workers=2, amp=True, batch=16, patience=12, plots=False, save=False, project="test_tune", name="degrees_tune_01", lr0=0.00114, use_ray=True, gpu_per_trial=1

    )

    1. Glenn JocherUltralytics

      Glad it’s sorted—quick tip: to tune your existing segmentation model, load your .pt first (model = YOLO("path/to/your.pt")) and then run model.tune(..., use_ray=True); Ray trials will reuse that same model/task—verify in the logs that task=segment.

  3. Fatima-khanjarGitHub

    Subject: Questions Regarding Using Ray Tune for YOLOv11 Hyperparameter Tuning

    Hello!

    I hope this message finds you well.

    #hyperparameter tuning using tune()
    from ray import tune
    from ray.tune import ResultGrid
    from ray.tune.examples.mnist_pytorch import train_mnist
    from ultralytics import YOLO
    import os
    import torch
    import matplotlib.pyplot as plt
    
    # Define a YOLO model
    model = YOLO("yolo11s.pt").to('cuda')
    
    tune_dir = 'ray_results'
    os.makedirs(tune_dir, exist_ok=True)
    
    
    # Tune hyperparameters using ray tune
    result_grid = model.tune(
        data= "data.yaml",  
        epochs=10,                 
        iterations=10,             
        batch = 16,            
        device = 0,
        workers=0,
        use_ray=True,
        gpu_per_trial =1,
        name = "tuning",
        project = tune_dir
    )
    
    Now, load the results after the tuning experiment is finished
    exp_name = "tuning"
    experiment_path = f"{tune_dir}/{exp_name}"  # Get the name of the experiment
    print(f"Loading results from {experiment_path}...")
    
    restored_tuner = tune.Tuner.restore(experiment_path, trainable=train_mnist)
    result_grid = restored_tuner.get_results()
    
    # Basic Experiment-Level Analysis: Check for errors
    if result_grid.errors:
        print("One or more trials failed!")
    else:
        print("No errors!")
    
    # Basic Trial-Level Analysis: Print configurations and last reported metrics for each trial
    for i, result in enumerate(result_grid):
        print(f"Trial #{i}: Configuration: {result.config}, Last Reported Metrics: {result.metrics}")
    
    # Plotting the Entire History of Reported Metrics for a Trial
    # Assuming "mean_accuracy" is part of the metrics
    for i, result in enumerate(result_grid):
        plt.plot(
            result.metrics_dataframe["training_iteration"],
            result.metrics_dataframe["mean_accuracy"],  # Modify this depending on your metrics
            label=f"Trial {i}",
        )
    
    plt.xlabel("Training Iterations")
    plt.ylabel("Mean Accuracy")
    plt.legend()
    plt.show()
    

    #hyperparameter tuning using tuner.fit()
    import os 
    from ray import tune
    from ray.tune import ResultGrid
    from ray.tune.examples.mnist_pytorch import train_mnist
    from ray.tune import Result
    from pathlib import Path
    
    tune_dir = Path("ray_results").resolve().as_uri()
    exp_name = "tune_analyzing_results"
    
    tuner = tune.Tuner(
        trainable=train_mnist,
        param_space={
            "lr": tune.uniform(0.001, 0.1),
            "momentum": tune.uniform(0.1, 0.9),
        },
        run_config=tune.RunConfig(
            name=exp_name,
            stop={"training_iteration": 100},
            checkpoint_config=tune.CheckpointConfig(
                checkpoint_score_attribute="mean_accuracy",
                num_to_keep = 5,
            ),
            storage_path=tune_dir,
        ),
        tune_config=tune.TuneConfig(mode="max", metric="mean_accuracy", num_samples=3),
    )
    result_grid: ResultGrid = tuner.fit()
    
    
    experiment_path = os.path.join(tune_dir, exp_name)
    print(f"Loading results from {experiment_path}...")
    
    restored_tuner = tune.Tuner.restore(experiment_path, trainable=train_mnist)
    result_grid = restored_tuner.get_results()
    
    # Check if there have been errors
    if result_grid.errors:
        print("One of the trials failed!")
    else:
        print("No errors!")
    
    num_results = len(result_grid)
    print("Number of results:", num_results)
    
    # Iterate over results
    for i, result in enumerate(result_grid):
        if result.error:
            print(f"Trial #{i} had an error:", result.error)
            continue
    
        print(
            f"Trial #{i} finished successfully with a mean accuracy metric of:",
            result.metrics["mean_accuracy"]
        )
    
    results_df = result_grid.get_dataframe()
    results_df[["training_iteration", "mean_accuracy"]]
    
    print("Shortest training time:", results_df["time_total_s"].min())
    print("Longest training time:", results_df["time_total_s"].max())
    
    best_result_df = result_grid.get_dataframe(
        filter_metric="mean_accuracy", filter_mode="max"
    )
    best_result_df[["training_iteration", "mean_accuracy"]]
    
    
    # Get the result with the maximum test set `mean_accuracy`
    best_result: Result = result_grid.get_best_result()
    
    # Get the result with the minimum `mean_accuracy`
    worst_performing_result: Result = result_grid.get_best_result(
        metric="mean_accuracy", mode="min"
    )
    
    best_result.config
    best_result.path
    # Get the last Checkpoint associated with the best-performing trial
    best_result.checkpoint
    # Get the last reported set of metrics
    best_result.metrics
    result_df = best_result.metrics_dataframe
    result_df[["training_iteration", "mean_accuracy", "time_total_s"]]
    best_result.metrics_dataframe.plot("training_iteration", "mean_accuracy")
    ax = None
    for result in result_grid:
        label = f"lr={result.config['lr']:.3f}, momentum={result.config['momentum']}"
        if ax is None:
            ax = result.metrics_dataframe.plot("training_iteration", "mean_accuracy", label=label)
        else:
            result.metrics_dataframe.plot("training_iteration", "mean_accuracy", ax=ax, label=label)
    ax.set_title("Mean Accuracy vs. Training Iteration for All Trials")
    ax.set_ylabel("Mean Test Accuracy")

    I have been following your guide on using Ray Tune for hyperparameter tuning with YOLOv11. I was able to run the experiment using the use_ray=True argument, and it worked successfully—thank you for the helpful explanation!

    However, I still have a few questions and points of confusion:

    1. Naming the Trials: How can I change or customize the names of the individual trials when using model.tune(..., use_ray=True)? Right now, the trials are auto-named, and I’d like more meaningful names to help keep track of different configurations. image

    2. Retrieving the Best Hyperparameters: After the tuning process is complete, I would like to extract the best hyperparameter configuration to reuse it for future training. I noticed in other examples (e.g., train_mnist) that you use tuner.fit() to retrieve and analyze results, including the best configuration. So my question is: when using model.tune() directly (as in the case of YOLOv11), is there a method to extract the best hyperparameters without using tuner.fit()? Or is it necessary to re-structure the experiment using tune.Tuner to get access to that kind of detailed analysis?

    3. Using tune.Tuner() with YOLOv11: In your other examples, the tuning process is managed using tune.Tuner(...), but I’m not sure how to apply this approach to YOLOv11, since there’s no explicit trainable function like train_mnist. Should we always use model.tune() for YOLO models, or is there a way to integrate YOLOv11 into a Tuner workflow for more advanced customization and analysis?

    Thank you so much for your time and support! I would really appreciate any clarification or guidance on these points.

    Best regards,

    1. Glenn JocherUltralytics

      @Fatima-khanjar Thank you for your detailed questions about Ray Tune integration with YOLO11!

      1. Naming Trials: Currently, the high-level model.tune() API doesn't provide direct control over individual trial naming. Ray Tune automatically generates these names. You can use the name parameter to name the overall experiment (as you've done with "tuning"), but individual trial names remain auto-generated.

      2. Retrieving Best Hyperparameters: When using model.tune() with Ray Tune, the best hyperparameters are automatically saved to runs/[task]/tune/best_hyperparameters.yaml. This file contains the optimal configuration and can be loaded for future use. You can also examine tune_results.csv for all trial results.

      3. Using tune.Tuner(): While possible, creating a custom trainable function for YOLO with the low-level Ray Tune API requires more work. You'd need to wrap the YOLO training process in a function that configures and trains the model while reporting metrics to Ray Tune. For most users, the high-level model.tune() API is recommended as it handles this integration automatically.

      For more advanced customization, you might consider extending the Ray Tune integration in Ultralytics by referring to the source code in the ultralytics/utils/tuner.py file.

    2. Fatima-khanjarGitHub

      Hello! Thank you for your clarification. I will continue using model.tune() and use the following line to retrieve the best hyperparameters, since the best_hyperparameters.yaml file wasn’t automatically saved in the output directory of the Ray tuning: best_config = analysis.get_best_config(metric="metrics/mAP50(B)", mode="max")`

      I have a question: I read that Optuna uses the TPE (Tree-structured Parzen Estimator) search algorithm, which is more powerful than the default search algorithms in Ray Tune. Since Ray Tune provides scalability and distributed tuning, is it possible to combine both—using Optuna’s TPE algorithm with Ray Tune while still calling model.tune()? If so, how can I integrate them?

      I also have another question that’s unrelated. I noticed that YOLOv11 comes in different versions, from n to xl. I understand that the choice depends on the dataset size and the task complexity. But what are the actual criteria used to determine the complexity of a task?

      best regrads,

    3. Glenn JocherUltralytics

      @Fatima-khanjar

      Regarding using TPE with Ray Tune - yes, it's possible! Ray Tune already supports TPE through the HyperOpt integration. You can use it by installing the HyperOpt package and specifying the search algorithm:

      pip install hyperopt
      
      from ray.tune.search.hyperopt import HyperOptSearch
      from ray.tune.search import ConcurrencyLimiter
      
      hyperopt_search = HyperOptSearch(metric="metrics/mAP50(B)", mode="max")
      limited_search = ConcurrencyLimiter(hyperopt_search, max_concurrent=4)
      
      # Then in your model.tune() call
      model.tune(
          data="data.yaml",
          search_alg=limited_search,
          use_ray=True,
          # other parameters
      )

      For your question about YOLO11 model size selection, the criteria typically include:

      • Computational resources: Larger models (l, x, xl) require more GPU memory and processing power
      • Dataset complexity: More complex datasets with small/numerous objects benefit from larger models
      • Inference speed requirements: Smaller models (n, s) offer faster inference for real-time applications
      • Accuracy needs: Larger models generally provide higher accuracy at the cost of speed

      You can check the performance trade-offs in the Ultralytics documentation to make an informed decision based on your specific constraints.

      1
    4. Fatima-khanjarGitHub(editado)

      Hello, I hope this message finds you well.

      I followed your instructions to integrate Ray Tune with the TPE algorithm using HyperOpt:

      hyperopt_search = HyperOptSearch(metric="metrics/mAP50(B)", mode="max")
      limited_search = ConcurrencyLimiter(hyperopt_search, max_concurrent=1)

      Then, I used the following code to tune hyperparameters with Ray Tune:

      tuning_results = model.tune(
          data="data.yaml",
          epochs=50,                # Number of epochs for each tuning iteration
          iterations=100,           # Total number of tuning iterations
          batch=16,
          device=0,
          workers=0,
          grace_period=30,
          search_alg=limited_search,
          use_ray=True,
          gpu_per_trial=1,
          project=tune_dir
      )

      However, I encountered a syntax error: SyntaxError: 'search_alg' is not a valid YOLO argument. Could you please advise me on how to fix this?

      I have another question regarding the output directory of Ray Tune. It shows that inside the runs folder, there are subfolders named train (equal to the number of iterations) and a tune folder that contains subdirectories also equal to the number of iterations.

      Screenshot 2025-04-17 104229

      My question is: should I focus on the train directories? Why are they generated, and what's their purpose?

      Also, if I want to monitor the overall progress of the fine-tuning process — for example, in genetic tuning, we usually look at a graph of the fitness score vs. iteration — where should I look for that kind of visualization or information?

      best regards,

    5. Glenn JocherUltralytics(editado)

      @Fatima-khanjar

      Regarding your issues with HyperOptSearch and Ray Tune integration:

      1. The search_alg argument is passed through model.tune(use_ray=True). It defaults to "optuna" (TPE) and accepts either a string (such as "optuna", "hyperopt", "bohb" or "random") or a Ray Tune searcher instance like your HyperOptSearch, so you do not need to modify ultralytics/utils/tuner.py.

      2. About the directory structure:

        • The train directories (train1, train2, etc.) contain individual training runs for each trial with different hyperparameter sets
        • The tune directory contains the aggregated results of all trials and should be your primary focus
      3. For monitoring progress:

        • Check tune/tune_results.csv for all trial results
        • Look for tune/best_fitness.png which shows fitness score progression over iterations
        • tune/best_hyperparameters.yaml contains the optimal configuration found

      The plots in the tune directory (especially tune_scatter_plots.png if available) provide valuable visualizations of the hyperparameter search space and how different parameters affected model performance.

  4. Fatima-khanjarGitHub

    Hello!
    I hope this message finds you well.

    I'm trying to use Ray Tune for hyperparameter optimization with the following code:

    results = model.tune(
        data="data.yaml",  
        epochs=30,                 
        iterations=150,           
        batch=16,            
        optimizer="AdamW",         
        plots=False,               
        save=False,                
        val=False,                 
        device=0,
        workers=8,
        use_ray=True,
        project="ray_results"
    )

    However, I'm getting a path-related error that I can't figure out:

    FileNotFoundError: [WinError 3] The system cannot find the path specified...

    It seems to be related to the length of the path Ray is trying to create. Do you know how I can fix this?

    Also, I have a question. I came across Ray Tune while working with Genetic Algorithms, and I was wondering: would you recommend using Ray Tune or Genetic Algorithms for hyperparameter optimization? Are they similar in how they work, or are there major differences between them? What advantages does Ray Tune offer over Genetic Algorithms?

    Thank you for your help!

    1. Fatima-khanjarGitHub

      Hello Community!!

      Just following up on my own post — I managed to solve the issue on Windows 11.

      Here’s what worked for me:

      1. Opened gpedit.msc as Administrator
      2. Navigated to: Computer Configuration > Administrative Templates > System > Filesystem
      3. Enabled the setting “Enable Win32 long paths"

      After doing this, the problem was resolved.

      Posting this in case it helps someone else!

    2. Glenn JocherUltralytics

      @Fatima-khanjar Thank you for sharing your solution to the Windows path length issue! This is helpful information that could benefit other users experiencing similar problems.

      Regarding your question about Ray Tune versus Genetic Algorithms: They're different approaches to hyperparameter optimization. Ray Tune offers several advantages including:

      1. Multiple search strategies beyond genetic algorithms (Bayesian optimization, grid search, random search)
      2. Built-in parallel execution that efficiently utilizes available resources
      3. Early stopping via ASHA scheduler to terminate underperforming trials
      4. Distributed computing capabilities for scaling across multiple machines

      Ultralytics actually supports both approaches - the internal tuner uses genetic algorithms focusing on mutation, while the Ray Tune integration provides more advanced search strategies and better parallelization. Ray Tune is generally recommended for more complex search spaces and when you have multiple GPUs available.

      1
    1. wisroviGitHub

      tambien necesito:

      model.add_callback("on_train_start", self.on_train_start) model.add_callback("on_train_end", self.on_train_end)

      pero dichas funciones no se disparan

    2. wisroviGitHub

      agradezco mucho sus valiosas aportaciones, de verdad que es una funcionalidad increible y magnifica

    3. Glenn JocherUltralytics

      @wisrovi to integrate MLFlow with Ultralytics YOLO hyperparameter tuning, you'll need to create a custom Ray Tune reporter that logs metrics to MLFlow. While we don't have native MLFlow integration like Weights & Biases, you can implement it by adding MLFlow logging callbacks to your tuning script. The Ray Tune documentation provides guidance on MLFlow integration that you can adapt for YOLO workflows.

  5. NegroAmigoGitHub

    Which versions of YOLO are supported by Ray Tune? I have project with YOLOv8, will it be suitable to use with Ray Tune?

    1. Glenn JocherUltralytics

      @NegroAmigo yes, YOLOv8 fully supports Ray Tune integration for hyperparameter tuning. You can use the same model.tune() method shown in our Ray Tune integration guide by simply loading your YOLOv8 model (YOLO('yolov8n.pt')). The tuning process works identically across supported YOLO versions. For implementation details, see the Ultralytics Ray Tune documentation.

    1. Glenn JocherUltralytics

      @alifazeli00 the documentation currently focuses on the default hyperparameters and their tuning ranges. If you're looking for specific details on beta2 for AdamW, it might not be explicitly covered. For more information on hyperparameter tuning, you can explore the Ray Tune documentation linked in the guide.

    2. alifazeli00GitHub

      thank you, It has been mentioned that momentum is essentially beta1. Is this the same for beta2?

    3. Glenn JocherUltralytics

      Beta2 is not explicitly mentioned in the documentation as it typically defaults to 0.999 in AdamW, which is a common standard setting. For specific adjustments, you may need to modify the optimizer settings directly in your training script.

      1
  6. sirtrisGitHub

    Hi, you mention that the .tune() function integrates well with wandb. Are there any plans to make it work with mlflow as well? When I try to use it now no model metric, parameters or artifacts, etc. are logged. It would also be nice to have one hyperparameter sweep as a parent run and the individual runs as child runs of that parent run. Best,

    1. Glenn JocherUltralytics

      @sirtris currently, there are no plans to integrate the .tune() function with MLflow, but we appreciate your feedback and will consider it for future updates.

    2. sirtrisGitHub

      Could you point me to some resources so I could maybe look into it doing it myself?

    3. Glenn JocherUltralytics

      For resources on integrating MLflow with Ray Tune, I recommend checking the Ray Tune documentation for any updates or community contributions. This might provide insights into logging metrics and managing runs with MLflow.

  7. sachmatkrisGitHub

    unfortunately that is not the issue because the results are exactly the same for different learning rates - impossible.

    On Fri, 27 Sept 2024 at 19:06, Glenn Jocher @.***> wrote:

    @sachmatkris https://github.com/sachmatkris it seems like the issue might be with the search space configuration. Ensure that the hyperparameters have enough variability and that the dataset path is correctly set. If the problem persists, consider adjusting the search space or reviewing the dataset configuration. For more details, you can refer to the Ray Tune documentation https://docs.ultralytics.com/integrations/ray-tune/.

    — Reply to this email directly, view it on GitHub https://github.com/orgs/ultralytics/discussions/16505#discussioncomment-10777716, or unsubscribe https://github.com/notifications/unsubscribe-auth/A3WH6HFTKYE2WLTJVGR6HWTZYV7A5AVCNFSM6AAAAABO5HD4QCVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTANZXG43TCNQ . You are receiving this because you were mentioned.Message ID: @.*** com>

    1. Glenn JocherUltralytics

      @sachmatkris if you're seeing identical results for different learning rates, it might be worth checking the hyperparameter search space and ensuring the dataset configuration is correct. Adjusting these settings could help resolve the issue. For further guidance, please refer to the Ray Tune documentation.

  8. sachmatkrisGitHub

    I found out the issue was setting device = 0 in the model.tune() and specifying absolute path for the .data.yaml, which is not the same what YOLO does when started from within an opened folder on VScode.

    1. sachmatkrisGitHub(editado)

      @sachmatkris it seems like you've identified the issue with the device setting and path specification. If you need further assistance, feel free to ask!

      Another issue I have is using the following call all of my experiments with ray_tune return the same metrics:

      search_space = { 'lr0': tune.loguniform(1e-5, 1e-1), 'momentum': tune.uniform(0.6, 0.95), }

      result_grid = model.tune(data = 'C:/Users/Kristijonas/Desktop/Mokslo šaknys karčios/AI/Projects/masinu_numeriai/formated_dataset_new/data.yaml', imgsz = 1280, space = search_space, batch = 16, epochs = 50, patience = 5, use_ray = True, iterations = 20, device='cuda' )

      e.g.

      image

    2. Glenn JocherUltralytics

      @sachmatkris it seems like the issue might be with the search space configuration. Ensure that the hyperparameters have enough variability and that the dataset path is correctly set. If the problem persists, consider adjusting the search space or reviewing the dataset configuration. For more details, you can refer to the Ray Tune documentation.