Commencer

Optimisation efficace des hyperparamètres avec Ray Tune et YOLO26

L’optimisation des hyperparamètres recherche l’ensemble d’hyperparamètres qui offre les meilleures performances au modèle. Elle exécute des essais avec différentes valeurs d’hyperparamètres et évalue les performances de chaque essai.

Accélère l’optimisation avec Ultralytics YOLO26 et Ray Tune#

Ultralytics YOLO26 intègre Ray Tune pour l’optimisation des hyperparamètres. Ray Tune te permet d’utiliser des stratégies de recherche avancées, le parallélisme et l’arrêt anticipé afin d’accélérer le processus d’optimisation.

Ray Tune#

Ray Tune hyperparameter optimization workflow

Ray Tune est une bibliothèque d’optimisation des hyperparamètres conçue pour être efficace et flexible. Elle prend en charge diverses stratégies de recherche, le parallélisme et les stratégies d’arrêt anticipé, et s’intègre aux frameworks populaires de machine learning, notamment Ultralytics YOLO26.

Intégration avec Weights & Biases#

YOLO26 prend également en charge une intégration facultative avec Weights & Biases pour suivre le processus d’optimisation.

Installation#

Pour installer les paquets requis, exécute :

Installation
# 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

Utilisation#

Utilisation
from ultralytics import YOLO

# Charger un modèle YOLO26n
model = YOLO("yolo26n.pt")

# Lancer l’optimisation des hyperparamètres pour entraîner YOLO26n sur le jeu de données COCO8
result_grid = model.tune(data="coco8.yaml", use_ray=True)

Paramètres de la méthode tune()#

La méthode tune() de YOLO26 fournit une interface facile à utiliser pour optimiser les hyperparamètres avec Ray Tune. Elle accepte plusieurs arguments qui te permettent de personnaliser le processus d’optimisation. Voici une explication détaillée de chaque paramètre :

ParamètreTypeDescriptionValeur par défaut
datastr or listLe fichier YAML du jeu de données à utiliser avec l’optimiseur, qui précise les chemins des données de validation et d’entraînement, ainsi que d’autres paramètres propres au jeu de données. Pour la classification, il faut plutôt fournir un répertoire de jeu de données ou le nom d’un jeu de données intégré (par exemple, imagenet10). Une liste entraîne chaque essai sur tous les jeux de données et indique la métrique moyenne de la tâche.
spacedict, optionalUn dictionnaire qui définit l’espace de recherche des hyperparamètres pour Ray Tune. Chaque clé correspond au nom d’un hyperparamètre, et la valeur indique l’intervalle de valeurs à explorer pendant l’optimisation. Si aucun espace n’est fourni, YOLO26 utilise un espace de recherche par défaut couvrant plusieurs hyperparamètres.
grace_periodint, optionalLa période de grâce en époques pour le planificateur ASHA dans Ray Tune. Le planificateur ne mettra fin à aucun essai avant ce nombre d'époques (plafonné à epochs). Ce paramètre n'est pas utilisé avec search_alg="bohb".10
gpu_per_trialint, optionalLe nombre de GPU que Ray alloue à chaque essai. Définis explicitement cette valeur pour utiliser l’entraînement sur GPU ; si elle est omise, les essais ne reçoivent aucune ressource GPU.None
iterationsint, optionalLe nombre maximal d’essais à exécuter pendant l’optimisation. Ce paramètre permet de limiter le nombre total de combinaisons d’hyperparamètres testées et d’éviter que le processus d’optimisation ne s’exécute indéfiniment.300
search_algstr or Searcher, optionalStratégie de recherche Ray Tune à utiliser. Tu peux transmettre directement un objet de recherche Ray ou utiliser une chaîne prise en charge, telle que optuna, hyperopt, bayesopt, bohb, hebo, nevergrad, zoopt, ax ou random. Les chaînes de recherche utilisent automatiquement la métrique de tâche par défaut et mode="max". Par défaut, Optuna utilise TPE multivarié avec des suggestions adaptées au parallélisme."optuna"
**train_argsdict, optionalArguments supplémentaires à transmettre à la méthode train() pendant l’optimisation. Ils peuvent inclure des paramètres comme le nombre d’époques d’entraînement, la taille de lot et d’autres configurations propres à l’entraînement.{}

En personnalisant ces paramètres, tu peux adapter précisément le processus d’optimisation des hyperparamètres à tes besoins et aux ressources de calcul disponibles.

Description de l’espace de recherche par défaut#

Le tableau suivant répertorie les paramètres de l’espace de recherche par défaut pour optimiser les hyperparamètres de YOLO26 avec Ray Tune. Chaque paramètre possède un intervalle de valeurs défini par tune.uniform(), à l’exception de close_mosaic, qui utilise tune.randint().

ParamètrePlageDescription
lr0tune.uniform(1e-5, 1e-2)Taux d’apprentissage initial qui contrôle la taille du pas pendant l’optimisation. Des valeurs plus élevées accélèrent l’entraînement, mais peuvent provoquer une instabilité.
lrftune.uniform(0.01, 1.0)Facteur final du taux d’apprentissage qui détermine la diminution du taux d’apprentissage à la fin de l’entraînement.
momentumtune.uniform(0.7, 0.98)Facteur d’inertie de l’optimiseur qui contribue à accélérer l’entraînement et à sortir des minima locaux.
weight_decaytune.uniform(0.0, 0.001)Paramètre de régularisation qui évite le surapprentissage en pénalisant les valeurs de poids élevées.
warmup_epochstune.uniform(0.0, 5.0)Nombre d’époques pendant lesquelles le taux d’apprentissage augmente progressivement afin de stabiliser le début de l’entraînement.
warmup_momentumtune.uniform(0.0, 0.95)Valeur initiale de l’inertie, qui augmente progressivement pendant la période de préchauffage.
boxtune.uniform(1.0, 20.0)Poids de la composante de perte des boîtes englobantes, qui équilibre la précision de localisation du modèle.
clstune.uniform(0.1, 4.0)Poids de la composante de perte de classification, qui équilibre la précision de prédiction des classes du modèle.
cls_pwtune.uniform(0.0, 1.0)Puissance de pondération des classes, de la désactivation (0.0) à la pondération complète selon l’inverse de la fréquence (1.0).
dfltune.uniform(0.4, 12.0)Poids de la composante de régression de la distance des boîtes, qui favorise une localisation précise des boîtes englobantes.
hsv_htune.uniform(0.0, 0.1)Plage d’augmentation de la teinte, qui introduit une variabilité des couleurs pour aider le modèle à mieux généraliser.
hsv_stune.uniform(0.0, 0.9)Plage d’augmentation de la saturation, qui fait varier l’intensité des couleurs pour améliorer la robustesse.
hsv_vtune.uniform(0.0, 0.9)Plage d’augmentation de la valeur (luminosité), qui aide le modèle à fonctionner dans diverses conditions d’éclairage.
degreestune.uniform(0.0, 45.0)Plage d’augmentation de la rotation en degrés, qui améliore la reconnaissance des objets pivotés.
translatetune.uniform(0.0, 0.9)Plage d’augmentation de la translation, qui déplace les images horizontalement et verticalement.
scaletune.uniform(0.0, 0.95)Plage d’augmentation de l’échelle, qui simule des objets situés à différentes distances.
sheartune.uniform(0.0, 10.0)Plage d’augmentation du cisaillement en degrés, qui simule des changements de perspective.
perspectivetune.uniform(0.0, 0.001)Plage d’augmentation de la perspective, qui simule des changements de point de vue en 3D.
flipudtune.uniform(0.0, 1.0)Probabilité d’augmentation par retournement vertical, qui accroît la diversité du jeu de données.
fliplrtune.uniform(0.0, 1.0)Probabilité d’augmentation par retournement horizontal, utile pour les objets symétriques.
bgrtune.uniform(0.0, 1.0)Probabilité d’augmentation par permutation des canaux BGR, qui contribue à l’invariance des couleurs.
mosaictune.uniform(0.0, 1.0)Probabilité d’augmentation Mosaic, qui combine quatre images en un seul échantillon d’entraînement.
mixuptune.uniform(0.0, 1.0)Probabilité d’augmentation Mixup, qui mélange deux images et leurs étiquettes.
cutmixtune.uniform(0.0, 1.0)Probabilité d’augmentation Cutmix, qui combine des régions d’image tout en préservant les caractéristiques locales.
copy_pastetune.uniform(0.0, 1.0)En mode flip, fraction des objets éligibles copiés dans une image ; en mode mixup, probabilité d’exécuter également l’opération.
close_mosaictune.randint(0, 11)Désactive Mosaic pendant les N dernières époques afin de stabiliser l’entraînement avant son terme.

Exemple d’espace de recherche personnalisé#

Cet exemple montre comment utiliser un espace de recherche personnalisé pour optimiser les hyperparamètres avec Ray Tune et YOLO26. En définissant un espace de recherche personnalisé, tu peux concentrer le processus d’optimisation sur les hyperparamètres qui t’intéressent.

Utilisation
from ray import tune

from ultralytics import YOLO

# Définir un modèle YOLO
model = YOLO("yolo26n.pt")

# Exécuter Ray Tune sur le modèle
result_grid = model.tune(
    data="coco8.yaml",
    space={"lr0": tune.uniform(1e-5, 1e-2)},
    epochs=50,
    use_ray=True,
)

L’extrait de code ci-dessus crée un modèle YOLO à partir des poids préentraînés YOLO26n, puis appelle la méthode tune() avec la configuration du jeu de données coco8.yaml. Il fournit un espace de recherche personnalisé pour le taux d’apprentissage initial lr0, sous la forme d’un dictionnaire dont la clé est "lr0" et la valeur tune.uniform(1e-5, 1e-2). Enfin, il transmet directement à la méthode tune des arguments d’entraînement supplémentaires, tels que le nombre d’époques, sous la forme epochs=50.

Exemple d’algorithme de recherche#

Tu peux sélectionner une stratégie de recherche Ray Tune par son nom. Pour les algorithmes de recherche désignés par une chaîne, Ultralytics utilise automatiquement la métrique d’optimisation par défaut de la tâche en cours et mode="max". Si search_alg n’est pas fourni, Ultralytics utilise TPE multivarié d’Optuna avec des suggestions adaptées au parallélisme.

Utilisation de la chaîne `search_alg` avec `model.tune()`
from ultralytics import YOLO

# Définir un modèle YOLO
model = YOLO("yolo26n.pt")

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

Si tu dois personnaliser l’échantillonneur de l’outil de recherche ou remplacer sa métrique et son mode d’optimisation, transmets un objet d’outil de recherche Ray Tune instancié plutôt qu’une chaîne.

Utilisation de l’objet `OptunaSearch` avec `model.tune()`
from ray.tune.search.optuna import OptunaSearch

from ultralytics import YOLO

# Définir un modèle YOLO
model = YOLO("yolo26n.pt")

# Définir un outil de recherche
searcher = OptunaSearch(
    metric="metrics/mAP50-95(B)",
    mode="max",
)

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

Reprendre une session d’optimisation des hyperparamètres interrompue avec Ray Tune#

Tu peux reprendre une session Ray Tune interrompue en transmettant resume=True. Tu peux aussi transmettre le répertoire name utilisé par Ray Tune dans runs/{task} pour reprendre la session. Sinon, la dernière session interrompue reprend automatiquement. Il n’est pas nécessaire de fournir à nouveau iterations et space, mais tu dois transmettre de nouveau les autres arguments d’entraînement, notamment data et epochs.

Utiliser `resume=True` avec `model.tune()`
from ultralytics import YOLO

# Définir un modèle YOLO
model = YOLO("yolo26n.pt")

# Reprendre l’exécution précédente
results = model.tune(use_ray=True, data="coco8.yaml", epochs=50, resume=True)

# Reprendre l’exécution Ray Tune avec le nom 'tune_exp_2'
results = model.tune(use_ray=True, data="coco8.yaml", epochs=50, name="tune_exp_2", resume=True)

Traiter les résultats de Ray Tune#

Après avoir exécuté une expérience d’optimisation des hyperparamètres avec Ray Tune, tu peux vouloir effectuer différentes analyses des résultats obtenus. Ce guide te présente des flux de travail courants pour traiter et analyser ces résultats.

Charger les résultats d’une expérience Tune depuis un répertoire#

model.tune(use_ray=True) renvoie un objet Ray ResultGrid et enregistre l’expérience dans runs/{task}/tune, ou dans le name que tu as indiqué. Pour charger ces résultats après la fermeture du script d’origine, reprends la session ; les essais enregistrés seront restaurés et le même ResultGrid sera renvoyé :

from ultralytics import YOLO

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

Analyse de base au niveau de l’expérience#

Obtiens un aperçu des performances des essais. Tu peux vérifier rapidement s’ils ont rencontré des erreurs.

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

Analyse de base au niveau des essais#

Accède aux configurations d’hyperparamètres de chaque essai et aux dernières métriques rapportées.

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

Tracer l’historique complet des métriques rapportées pour un essai#

Tu peux tracer l’historique des métriques rapportées pour chaque essai afin de voir leur évolution au fil du temps.

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()

Résumé#

Dans ce guide, nous avons présenté des flux de travail courants pour analyser les résultats d’expériences exécutées avec Ray Tune et Ultralytics. Les principales étapes consistent à charger les résultats de l’expérience depuis un répertoire, à effectuer des analyses de base au niveau de l’expérience et des essais, puis à tracer les métriques.

Pour approfondir le sujet, consulte la page de documentation Analyser les résultats de Ray Tune afin de tirer le meilleur parti de tes expériences d’optimisation des hyperparamètres.

FAQ#

  • Pour optimiser les hyperparamètres de ton modèle Ultralytics YOLO26 avec Ray Tune, suis ces étapes :

    1. Installer les paquets requis :

      pip install -U ultralytics "ray[tune]" optuna
      pip install wandb # optional for logging
      yolo settings wandb=True
    2. Charger ton modèle YOLO26 et lancer l’optimisation :

      from ultralytics import YOLO
      
      # Charger un modèle YOLO26
      model = YOLO("yolo26n.pt")
      
      # Lancer l’optimisation avec le jeu de données COCO8
      result_grid = model.tune(data="coco8.yaml", use_ray=True)

    Cette approche utilise les stratégies de recherche et le parallélisme de Ray Tune pour optimiser efficacement les hyperparamètres de ton modèle.

  • Ultralytics YOLO26 utilise les hyperparamètres par défaut suivants pour l’optimisation avec Ray Tune :

    ParamètrePlage de valeursDescription
    lr0tune.uniform(1e-5, 1e-2)Taux d’apprentissage initial
    lrftune.uniform(0.01, 1.0)Facteur final du taux d’apprentissage
    momentumtune.uniform(0.7, 0.98)Inertie
    weight_decaytune.uniform(0.0, 0.001)Décroissance des poids
    warmup_epochstune.uniform(0.0, 5.0)Époques de préchauffage
    boxtune.uniform(1.0, 20.0)Poids de la perte des boîtes
    clstune.uniform(0.1, 4.0)Poids de la perte de classification
    cls_pwtune.uniform(0.0, 1.0)Puissance de pondération des classes
    dfltune.uniform(0.4, 12.0)Poids de la perte de distance des boîtes
    hsv_htune.uniform(0.0, 0.1)Plage d’augmentation de la teinte
    translatetune.uniform(0.0, 0.9)Plage d’augmentation de la translation

    Tu peux personnaliser ces hyperparamètres selon tes besoins. Pour obtenir la liste complète et plus de détails, consulte le guide Optimisation des hyperparamètres.

  • Pour intégrer Weights & Biases (W&B) à ton processus d’optimisation avec Ultralytics YOLO26 :

    1. Installer W&B :

      pip install wandb
      wandb login
      yolo settings wandb=True
    2. Exécuter l’optimiseur :

      from ultralytics import YOLO
      
      # Charger le modèle YOLO
      model = YOLO("yolo26n.pt")
      
      # Chaque essai Ray crée sa propre exécution W&B dans ce projet
      result_grid = model.tune(data="coco8.yaml", project="YOLO-Tuning", use_ray=True)

    Cette configuration te permettra de suivre le processus d’optimisation, de suivre les configurations des hyperparamètres et de visualiser les résultats dans W&B.

  • Ray Tune offre de nombreux avantages pour l’optimisation des hyperparamètres :

    • Stratégies de recherche avancées : utilise des algorithmes comme l’optimisation bayésienne et HyperOpt pour rechercher efficacement les paramètres.
    • Parallélisme : permet d’exécuter plusieurs essais en parallèle, ce qui accélère considérablement le processus d’optimisation.
    • Arrêt anticipé : utilise des stratégies comme ASHA pour arrêter rapidement les essais peu performants et économiser des ressources de calcul.

    Ray Tune est intégré à Ultralytics YOLO26 via model.tune(use_ray=True).

  • Pour définir un espace de recherche personnalisé pour optimiser les hyperparamètres de YOLO26 avec 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)

    Cela permet de personnaliser la plage des hyperparamètres, comme le taux d’apprentissage initial et la quantité de mouvement, à explorer pendant l’optimisation. Pour les configurations avancées, consulte la section Exemple d’espace de recherche personnalisé.

Commentaires40

Pose une question, partage tes résultats ou aide quelqu’un d’autre.

  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(modifié)

      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(modifié)

      @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(modifié)

      @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.