Hyperparamètres

Définir les arguments

train() accepte des arguments nommés, et la CLI accepte les mêmes noms sous la forme key=value.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt")results = model.train(    data="my-dataset.yaml",    epochs=100,    batch=16,    imgsz=640,    lr0=0.01,) print(results["best_mAP50_95"])

libreyolo train model=LibreYOLO9s.pt data=my-dataset.yaml \  epochs=100 batch=16 imgsz=640 lr0=0.01

Les deux chemins aboutissent au même endroit. Les kwargs sont transmis à TrainConfig.from_kwargs(), qui construit la dataclass de configuration de la famille.

Une faute de frappe ne provoque pas d'erreur

from_kwargs() élimine toute clé qui n'est pas un champ de la configuration et émet un UserWarning qui la nomme. L'entraînement démarre alors avec la valeur par défaut :

# UserWarning : clés de configuration d'entraînement inconnues (ignorées) : ['learning_rate']model.train(data="my-dataset.yaml", learning_rate=0.001)

Rien n'échoue, l'exécution se termine et le learning rate n'a jamais eu la valeur demandée par l'appelant. Lisez les avertissements pendant la première époque d'une nouvelle recette. La CLI est plus stricte, car elle valide les noms des flags avant la construction de la configuration. Un flag CLI mal orthographié est donc rejeté immédiatement.

Valeurs par défaut propres à chaque famille

TrainConfig définit le champ et une valeur de base par défaut. Chaque famille en crée une sous-classe et remplace ce que sa recette publiée modifie. Il n'existe donc pas de réponse unique à la question « quel est le learning rate par défaut ? ».

Les valeurs de base par défaut sont optimizer="sgd", lr0=0.01, momentum=0.937, weight_decay=5e-4, scheduler="yoloxwarmcos", epochs=300, batch=16, imgsz=640 et amp=True. Voici trois exemples de l'écart d'une famille par rapport à cette base :

La détection avec D-FINE, DEIM, RT-DETRv4 et YOLO-NAS utilise par défaut amp=True avec amp_dtype="float16". Dome-DETR, PP-YOLOE et YOLO-NAS OBB conservent FP32 par défaut. Passez amp=False lorsque FP32 est nécessaire.

Pour lire les véritables valeurs par défaut d'une famille au lieu de les deviner :

from dataclasses import fields from libreyolo import LibreYOLO9from libreyolo.training.config import TrainConfig family_cfg = LibreYOLO9.TRAIN_CONFIG()base_cfg = TrainConfig() for f in fields(family_cfg):    family_value = getattr(family_cfg, f.name)    base_value = getattr(base_cfg, f.name, None)    if not hasattr(base_cfg, f.name) or family_value != base_value:        print(f"{f.name}: {family_value}")

# Affiche les valeurs par défaut de train, val et predict, remplacements inclus.libreyolo cfg

Taille de batch

batch est le batch global. Lors d'un entraînement multi-GPU, chaque rang charge batch // world_size, si bien que le nombre transmis est le nombre d'images par étape d'optimiseur quel que soit le nombre de GPU. Consultez l'entraînement multi-GPU.

batch=-1 active l'autobatch. Le trainer sonde le modèle en mode entraînement avec une véritable passe backward sur des puissances de deux, ajuste une droite à la courbe de mémoire et choisit la plus grande puissance de deux strictement inférieure à la valeur extrapolée qui tient dans 60 % de la VRAM totale.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # batch=-1 sonde la mémoire GPU et choisit une puissance de deux concrète.model.train(data="my-dataset.yaml", batch=-1, imgsz=640)

libreyolo train model=LibreYOLO9s.pt data=my-dataset.yaml batch=-1

Le point important est la sonde en mode entraînement avec une passe backward : une sonde en mode inférence ne tient pas compte des activations conservées et des tenseurs de gradients, qui représentent plusieurs fois l'empreinte de l'inférence pour un CNN profond. RF-DETR abaisse la fraction cible à 45 %, car la passe backward synthétique de la sonde sous-estime toujours le coût de son critère et des couches auxiliaires du décodeur.

L'autobatch est une fonctionnalité CUDA. Sur CPU ou MPS, il journalise une ligne et conserve le batch par défaut.

min_samples=0 laisse la longueur d'une époque inchangée. Un minimum positif échantillonne avec remise les datasets de détection plus courts. class_balanced=False, lorsqu'il est activé, applique un échantillonnage par facteur de répétition à chaque image ; il se combine avec min_samples et DDP. Les chargeurs spécialisés qui contournent l'échantillonneur partagé refusent cet équilibrage lorsqu'il est activé.

Accumulation de gradients

nbs définit la taille de batch nominale, ou effective. Le trainer accumule round(nbs / batch) micro-batchs par étape d'optimiseur.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # 4 micro-batchs de 16 par étape d'optimiseur, soit un batch effectif de 64.model.train(data="my-dataset.yaml", batch=16, nbs=64)

Avec la valeur par défaut None, l'accumulation est désactivée et l'entraînement reste inchangé.

Learning rate et schedule

lr0 est le learning rate initial et optimizer accepte sgd, adam et adamw. momentum correspond au momentum de SGD ou à beta1 d'Adam, weight_decay est le terme L2 et nesterov s'applique à SGD.

Le schedule est déterminé par scheduler, warmup_epochs, warmup_lr_start et min_lr_ratio. no_aug_epochs définit le nombre d'époques finales sans augmentation forte, et plusieurs schedules l'utilisent aussi pour façonner leur fin. Il ne s'agit donc pas uniquement d'un paramètre d'augmentation. Le comportement de chaque famille pour sa partie augmentation figure dans la page sur les augmentations.

Certaines familles ajoutent leurs propres paramètres de learning rate. backbone_lr_mult met à l'échelle le groupe du backbone par rapport à la tête, clip_max_norm définit l'écrêtage des gradients et SegFormer utilise head_lr_mult pour exécuter sa tête de décodage à dix fois le learning rate du backbone. Ces paramètres appartiennent à la sous-classe de configuration de la famille, pas à la classe de base.

clip_max_norm écrête la norme L2 du gradient à cette valeur avant chaque pas de l'optimiseur, et 0 désactive l'écrêtage. YOLOv9, YOLOv9-E2E et YOLOv9-P2 le fixent à 10 par défaut. D-FINE, Dome-DETR, DEIM, DEIMv2, TinyFormer, RT-DETR, RT-DETRv2, RT-DETRv4, RF-DETR, DINOv2, GTR et EC le fixent à 0.1 par défaut. Dans la CLI, c'est clip_max_norm= ou --clip-max-norm ; voir libreyolo train pour les familles qui l'y acceptent.

EMA

ema=True conserve une moyenne mobile exponentielle des poids à côté des poids entraînés. Elle est activée par défaut partout sauf pour FOMO.

ema_decay est le decay cible. Le decay augmente progressivement au lieu de commencer à sa cible : sa valeur effective à la mise à jour n est ema_decay * (1 - exp(-n / tau)), avec tau égal à 2000 par défaut. Les premières mises à jour suivent donc le modèle de plus près, tandis que les dernières le lissent. Les valeurs par défaut des familles vont de 0.997 pour la pose YOLO-NAS à 0.9998 pour YOLOX et 0.9999 pour YOLOv9 et la lignée DETR.

Les poids EMA sont ceux qui sont validés et stockés dans best.pt et last.pt. Les poids entraînés bruts sont aussi stockés sous la clé train_model, afin qu'une reprise continue depuis la trajectoire entraînée plutôt que depuis la moyenne.

Précision

amp=True exécute la passe forward sous autocast CUDA. amp_dtype sélectionne float16 (valeur par défaut) ou bfloat16 ; fp16 et bf16 sont des formes acceptées.

Float16 nécessite une mise à l'échelle dynamique de la loss et reçoit un GradScaler actif. La plage d'exposants plus large de Bfloat16 n'en a pas besoin, si bien que son scaler est construit mais désactivé, ce qui conserve un chemin d'optimiseur identique. Demander bfloat16 sur un appareil CUDA qui ne le prend pas en charge provoque une erreur pendant la configuration au lieu d'une dégradation silencieuse.

Sortie, checkpoints et arrêt

Les exécutions sont écrites dans project/name. project vaut runs/train par défaut partout, mais name fait partie des remplacements propres aux familles : la valeur de base par défaut est exp, tandis que YOLOv9 utilise yolo9_exp et D-FINE dfine_exp. Avec exist_ok=False, la valeur par défaut, un répertoire existant reçoit un suffixe incrémenté au lieu d'être écrasé.

save_period écrit un fichier weights/epoch_<N>.pt supplémentaire toutes les N époques, en plus de weights/last.pt après chaque époque et de weights/best.pt à chaque amélioration de la mesure suivie. eval_interval définit la fréquence de la validation, et la dernière époque est toujours validée ; val=False désactive la validation, et une telle exécution n'écrit aucun best.pt. patience arrête l'exécution après ce nombre d'époques sans amélioration, 0 désactivant l'early stopping.

cache accélère les époques répétées en conservant les images décodées en RAM (True ou "ram") ou dans des fichiers .npy à côté des sources ("disk"). Les lectures depuis le cache sont identiques octet par octet aux nouvelles lectures. Avec des workers de dataloader, "disk" est le choix le plus sûr.

average_best=0 désactive le moyennage des checkpoints ; un N positif écrit weights/average.pt à partir des N meilleurs snapshots au maximum. Les tenseurs flottants sont moyennés uniformément et les buffers entiers viennent du meilleur snapshot. export_check=False peut être activé pour échouer avant la première époque si l'export ONNX échoue. Les sorties brutes correspondantes sont comparées avec rtol=1e-3, atol=1e-4 ; les dispositions incompatibles entraînent la journalisation d'une comparaison ignorée.

precise_bn=0 désactive la recalibration finale de BatchNorm. Une valeur positive limite le nombre d'images du chargeur d'entraînement avant la validation finale ; sous DDP, le budget s'applique à chaque rang participant. Les BatchNorm gelées restent gelées. Des callbacks de score de sélection personnalisés peuvent choisir les meilleurs checkpoints et la patience.

Reprendre

resume=True poursuit une exécution interrompue à partir du checkpoint chargé ; resume="path/to/last.pt" la poursuit plutôt à partir de ce fichier.

from libreyolo import LibreYOLO # Chargez le checkpoint de l'exécution interrompue, puis demandez la reprise.model = LibreYOLO("runs/train/yolo9_exp/weights/last.pt")model.train(data="my-dataset.yaml", resume=True)

libreyolo train model=runs/train/yolo9_exp/weights/last.pt \  data=my-dataset.yaml resume=true

La reprise restaure les arguments d'entraînement enregistrés de l'exécution, et un argument passé explicitement remplace celui qui a été enregistré. Elle continue d'écrire dans le répertoire d'exécution du checkpoint. Elle restaure les poids entraînés, l'état de l'optimiseur, les poids EMA et le nombre de mises à jour, le suivi de la meilleure mesure, l'échelle du GradScaler, ainsi que les états aléatoires de PyTorch, CUDA et NumPy. Elle commence à l'époque qui suit celle du checkpoint et avance le schedule jusqu'à cette position.

Elle ne fait pas trois choses. resume=True ne peut pas être combiné à pretrained, ce qui provoque une erreur. Des poids publiés et une exécution qui a déjà atteint ses epochs n'ont rien à reprendre, et lèvent une ValueError qui l'indique. De plus, lorsque la clé de meilleure mesure du checkpoint diffère de celle de l'exécution actuelle, son suivi est remis à zéro avec un avertissement au lieu de comparer des valeurs qui n'ont pas la même signification.

Recettes dans un fichier

cfg= charge une correspondance YAML de noms de champs TrainConfig et la fusionne sous les arguments nommés explicites, si bien qu'un kwarg l'emporte toujours sur le fichier.

from libreyolo import LibreYOLO # Les clés du yaml sont des champs TrainConfig. Les kwargs explicites gagnent.model = LibreYOLO("LibreYOLO9s.pt")model.train(data="my-dataset.yaml", cfg="my-recipe.yaml", epochs=50)

size et num_classes sont retirés du fichier, car l'instance du modèle les possède déjà. Il n'existe aucun flag --cfg dans la CLI ; le chemin du fichier est un argument Python.

Pages connexes

• Datasets pour les valeurs acceptées par data=.
• Augmentations pour les paramètres d'augmentation et les familles qui les respectent.
• Gel des couches et LoRA pour entraîner une partie des poids.
• Validation et mesures pour les résultats rapportés par l'exécution.

Sélection des classes et pondération de la loss

Pour la détection YOLO9, RF-DETR, EdgeCrafter, RT-DETR, D-FINE, DEIM, TinyFormer et YOLO-NAS, classes=None conserve toutes les classes du dataset ; une liste filtre la supervision en préservant les identifiants d'origine, nc et names. single_cls=False peut être activé pour ramener les étiquettes conservées à la classe 0, nommée object. La reprise et la validation héritent des réglages enregistrés. L'entraînement OBB refuse single_cls.

ResNet, ConvNeXt, ConvNeXt V2, MobileNetV4, EfficientNetV2 et DINOv2 prennent en charge cls_pw=0.0 : les valeurs dans [0, 1] pondèrent chaque classe par sa fréquence inverse élevée à cette puissance, normalisée à une moyenne de 1. class_weights=False, lorsqu'il est activé, sélectionne la pondération alternative N / (C * n_c). Il ne se combine pas avec un cls_pw positif ; la reprise exige des réglages de pondération identiques.

plot_samples=8 fixe le budget d'images d'exemple de validation. Utilisez 0 pour aucune ou -1 pour toutes ; cela ne réduit pas les images évaluées.