Hyperparameter

Argumente festlegen

train() nimmt Schlüsselwortargumente entgegen. Die CLI verwendet dieselben Namen in der Form 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

Beide Wege enden an derselben Stelle. Die Schlüsselwortargumente werden an TrainConfig.from_kwargs() übergeben, das die Konfigurations-Dataclass der jeweiligen Familie erstellt.

Tippfehler lösen keinen Fehler aus

from_kwargs() verwirft jeden Schlüssel, der kein Feld der Konfiguration ist, und gibt eine UserWarning mit seinem Namen aus. Anschließend beginnt das Training mit dem Standardwert:

# UserWarning: Unbekannte Trainingskonfigurationsschlüssel (ignoriert): ['learning_rate']model.train(data="my-dataset.yaml", learning_rate=0.001)

Es tritt kein Fehler auf, der Lauf wird abgeschlossen und die Lernrate entspricht nie dem vom Aufrufer angeforderten Wert. Lies beim ersten Durchlauf eines neuen Rezepts die Warnungen in der ersten Epoche. Die CLI ist strenger, da sie die Namen der Optionen vor dem Erstellen der Konfiguration prüft. Eine falsch geschriebene CLI-Option wird deshalb direkt abgelehnt.

Familienspezifische Standardwerte

TrainConfig definiert das Feld und einen Basisstandardwert. Jede Familie leitet davon eine Unterklasse ab und überschreibt die Werte, die in ihrem veröffentlichten Rezept abweichen. Deshalb gibt es keine allgemeingültige Antwort auf die Frage „Wie lautet die Standardlernrate?“.

Die Basisstandardwerte sind optimizer="sgd", lr0=0.01, momentum=0.937, weight_decay=5e-4, scheduler="yoloxwarmcos", epochs=300, batch=16, imgsz=640 und amp=True. Drei Beispiele dafür, wie stark eine Familie davon abweichen kann:

D-FINE, DEIM, RT-DETRv4 und YOLO-NAS verwenden für Detektion standardmäßig amp=True mit amp_dtype="float16". Dome-DETR, PP-YOLOE und YOLO-NAS OBB behalten FP32 als Standard. Wenn FP32 benötigt wird, ist amp=False zu setzen.

So liest du die tatsächlichen Standardwerte einer Familie aus, statt zu raten:

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}")

# Gibt die Standardwerte für Training, Validierung und Vorhersage einschließlich familienspezifischer Überschreibungen aus.libreyolo cfg

Batchgröße

batch bezeichnet den globalen Batch. Beim Multi-GPU-Training lädt jeder Rang batch // world_size. Die übergebene Zahl ist daher unabhängig von der Anzahl der beteiligten GPUs die Zahl der Bilder pro Optimiererschritt. Siehe Multi-GPU-Training.

batch=-1 aktiviert Autobatch. Der Trainer prüft das Modell im Trainingsmodus mit einem echten Rückwärtsdurchlauf für Zweierpotenzen, passt eine Gerade an die Speicherkurve an und wählt die größte Zweierpotenz, die strikt unter dem extrapolierten Wert liegt und innerhalb von 60 Prozent des gesamten VRAM bleibt.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # batch=-1 prüft den GPU-Speicher und ermittelt eine konkrete Zweierpotenz.model.train(data="my-dataset.yaml", batch=-1, imgsz=640)

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

Die Prüfung im Trainingsmodus mit Rückwärtsdurchlauf ist entscheidend. Eine Prüfung im Inferenzmodus berücksichtigt weder zurückgehaltene Aktivierungen noch Gradiententensoren, die bei einem tiefen CNN ein Mehrfaches des Inferenzbedarfs ausmachen. RF-DETR senkt den Zielanteil auf 45 Prozent, weil der synthetische Rückwärtsdurchlauf der Prüfung die Kosten seiner Verlustfunktion und zusätzlichen Decoder-Schichten weiterhin unterschätzt.

Autobatch ist eine CUDA-Funktion. Auf CPU oder MPS protokolliert der Trainer eine Zeile und behält den Standard-Batch bei.

min_samples=0 lässt die Epochenlänge unverändert. Ein positiver Mindestwert zieht Stichproben mit Zurücklegen aus kürzeren Erkennungsdatensätzen. class_balanced=False aktiviert bei True bildweises Repeat-Factor-Sampling; es lässt sich mit min_samples und DDP kombinieren. Spezialisierte Loader, die den gemeinsamen Sampler umgehen, weisen aktiviertes Balancing zurück.

Gradientenakkumulation

nbs legt die nominelle oder effektive Batchgröße fest. Der Trainer akkumuliert round(nbs / batch) Mikro-Batches pro Optimiererschritt.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # 4 Mikro-Batches mit je 16 Elementen pro Optimiererschritt, effektive Batchgröße 64.model.train(data="my-dataset.yaml", batch=16, nbs=64)

Beim Standardwert None ist die Akkumulation deaktiviert und das Training bleibt unverändert.

Lernrate und Zeitplan

lr0 ist die anfängliche Lernrate. optimizer akzeptiert sgd, adam und adamw. momentum bezeichnet den SGD-Impuls oder Adam-Beta1, weight_decay ist der L2-Term und nesterov gilt für SGD.

Der Zeitplan wird von scheduler, warmup_epochs, warmup_lr_start und min_lr_ratio bestimmt. no_aug_epochs legt fest, wie viele abschließende Epochen ohne starke Augmentierung ausgeführt werden. Mehrere Zeitpläne verwenden den Wert auch zur Gestaltung ihres Endverlaufs, er ist also nicht nur ein Augmentierungsparameter. Wie die einzelnen Familien seine Augmentierungshälfte nutzen, steht unter Augmentierungen.

Einige Familien ergänzen eigene Lernratenparameter. backbone_lr_mult skaliert die Backbone-Gruppe relativ zum Kopf, clip_max_norm legt die Gradientenbegrenzung fest und SegFormer führt seinen Decoder-Kopf mit head_lr_mult bei der zehnfachen Lernrate des Backbones aus. Diese Felder gehören zur Konfigurationsunterklasse der Familie, nicht zur Basisklasse.

clip_max_norm beschneidet die L2-Norm des Gradienten vor jedem Optimizer-Schritt auf diesen Wert, und 0 schaltet das Clipping ab. YOLOv9, YOLOv9-E2E und YOLOv9-P2 setzen den Standard auf 10. D-FINE, Dome-DETR, DEIM, DEIMv2, TinyFormer, RT-DETR, RT-DETRv2, RT-DETRv4, RF-DETR, DINOv2, GTR und EC setzen ihn auf 0.1. In der CLI heißt er clip_max_norm= oder --clip-max-norm; die Familien, die ihn dort akzeptieren, findest du unter libreyolo train.

EMA

ema=True führt neben den trainierten Gewichten einen exponentiell gleitenden Mittelwert der Gewichte. Die Option ist überall außer bei FOMO standardmäßig aktiviert.

ema_decay ist der angestrebte Abklingfaktor. Der Wert steigt schrittweise an, statt direkt mit dem Zielwert zu beginnen. Der effektive Wert beim Update n lautet ema_decay * (1 - exp(-n / tau)), wobei tau standardmäßig 2000 beträgt. Frühe Updates folgen dem Modell dadurch enger, während späte Updates stärker geglättet werden. Die familienspezifischen Standardwerte reichen von 0.997 bei YOLO-NAS Pose über 0.9998 bei YOLOX bis 0.9999 bei YOLOv9 und der DETR-Reihe.

Die EMA-Gewichte werden validiert und in best.pt sowie last.pt gespeichert. Die unverarbeiteten trainierten Gewichte werden zusätzlich unter dem Schlüssel train_model abgelegt. Eine Fortsetzung setzt damit die trainierte Trajektorie fort und nicht den Mittelwert.

Genauigkeit

amp=True führt den Vorwärtsdurchlauf unter CUDA-Autocast aus. amp_dtype wählt float16 (Standard) oder bfloat16; fp16 und bf16 sind ebenfalls zulässige Schreibweisen.

Float16 benötigt dynamische Verlustskalierung und erhält einen aktiven GradScaler. Der größere Exponentenbereich von Bfloat16 macht dies überflüssig. Sein Scaler wird daher erstellt, aber deaktiviert, sodass der Optimiererpfad identisch bleibt. Wird bfloat16 auf einem CUDA-Gerät ohne bfloat16-Unterstützung angefordert, tritt der Fehler bei der Einrichtung auf, statt stillschweigend auf eine andere Genauigkeit zurückzufallen.

Ausgabe, Checkpoints und Abbruch

Läufe werden unter project/name gespeichert. project ist überall standardmäßig runs/train, während name zu den familienspezifischen Überschreibungen gehört. Der Basisstandardwert ist exp, YOLOv9 verwendet yolo9_exp und D-FINE dfine_exp. Bei exist_ok=False, dem Standardwert, erhält ein vorhandenes Verzeichnis einen hochgezählten Suffix, statt überschrieben zu werden.

save_period schreibt alle N Epochen zusätzlich eine Datei weights/epoch_<N>.pt. Dazu kommen weights/last.pt nach jeder Epoche und weights/best.pt, sobald sich die beobachtete Metrik verbessert. eval_interval bestimmt, wie oft die Validierung ausgeführt wird, und die letzte Epoche wird immer validiert; val=False schaltet die Validierung ab, und ein solcher Lauf schreibt kein best.pt. patience beendet den Lauf nach dieser Zahl von Epochen ohne Verbesserung, wobei 0 das frühzeitige Beenden deaktiviert.

cache beschleunigt wiederholte Epochen, indem decodierte Bilder im RAM (True oder "ram") oder als .npy-Dateien neben den Quellen ("disk") vorgehalten werden. Gecachte Lesevorgänge sind bytegenau identisch mit frischen. Bei Dataloader-Workern ist "disk" die sicherere Wahl.

average_best=0 deaktiviert die Checkpoint-Mittelung; ein positives N schreibt weights/average.pt aus bis zu N besten Snapshots. Gleitkommatensoren werden gleichgewichtet gemittelt; Integer-Puffer stammen aus dem besten Snapshot. export_check=False lässt sich aktivieren, um bei fehlgeschlagenem ONNX-Export vor Epoche eins abzubrechen. Passende Rohausgaben werden mit rtol=1e-3, atol=1e-4 verglichen; bei inkompatiblen Layouts wird das Überspringen des Vergleichs protokolliert.

precise_bn=0 deaktiviert die abschließende BatchNorm-Neukalibrierung. Ein positiver Wert begrenzt die Bilder aus dem Trainingsloader vor der abschließenden Validierung; unter DDP gilt das Budget je teilnehmendem Rank. Eingefrorene BatchNorm bleibt eingefroren. Eigene Fitness-Callbacks können die besten Checkpoints und die Patience bestimmen.

Fortsetzung

resume=True setzt einen unterbrochenen Lauf vom geladenen Checkpoint aus fort; resume="path/to/last.pt" setzt ihn stattdessen von dieser Datei aus fort.

from libreyolo import LibreYOLO # Checkpoint des unterbrochenen Laufs laden und anschließend die Fortsetzung anfordern.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

Beim Fortsetzen werden die gespeicherten Trainingsargumente des Laufs wiederhergestellt, und ein ausdrücklich übergebenes Argument hat Vorrang vor dem gespeicherten. Der Lauf schreibt weiter in das Laufverzeichnis des Checkpoints. Außerdem werden die trainierten Gewichte, der Optimiererzustand, die EMA-Gewichte und der Update-Zähler, die Verfolgung der besten Metrik, die GradScaler-Skalierung sowie die Zufallszustände von PyTorch, CUDA und NumPy wiederhergestellt. Der Lauf beginnt bei der Epoche nach der Checkpoint-Epoche und spult den Zeitplan bis zu dieser Position vor.

Drei Dinge sind nicht möglich. resume=True kann nicht mit pretrained kombiniert werden und löst dann einen Fehler aus. Veröffentlichte Gewichte und ein Lauf, der seine epochs bereits erreicht hat, enthalten nichts Fortzusetzendes und lösen einen ValueError aus, der das benennt. Und wenn sich der Schlüssel der besten Metrik im Checkpoint von dem des aktuellen Laufs unterscheidet, wird deren Verfolgung mit einer Warnung auf null zurückgesetzt, statt Werte mit unterschiedlicher Bedeutung zu vergleichen.

Rezepte in einer Datei

cfg= lädt eine YAML-Zuordnung aus TrainConfig-Feldnamen und führt sie unter den expliziten Schlüsselwortargumenten zusammen. Ein Schlüsselwortargument hat also immer Vorrang vor der Datei.

from libreyolo import LibreYOLO # Die Schlüssel in der YAML-Datei sind TrainConfig-Feldnamen. Explizite Schlüsselwortargumente haben Vorrang.model = LibreYOLO("LibreYOLO9s.pt")model.train(data="my-dataset.yaml", cfg="my-recipe.yaml", epochs=50)

size und num_classes werden aus der Datei entfernt, da sie bereits der Modellinstanz gehören. In der CLI gibt es keine Option --cfg. Der Dateipfad ist ein Python-Argument.

Verwandte Themen

• Datensätze erläutert, welche Werte data= akzeptiert.
• Augmentierungen beschreibt die Augmentierungsparameter und welche Familien sie berücksichtigen.
• Einfrieren von Schichten und LoRA erklären das Training einer Teilmenge der Gewichte.
• Validierung und Metriken beschreibt die vom Lauf ausgegebenen Werte.

Klassenauswahl und Loss-Gewichtung

Bei der Erkennung mit YOLO9, RF-DETR, EdgeCrafter, RT-DETR, D-FINE, DEIM, TinyFormer und YOLO-NAS behält classes=None alle Datensatzklassen bei. Eine Liste filtert die Trainingsziele unter Beibehaltung der ursprünglichen IDs, nc und names. single_cls=False lässt sich aktivieren, um beibehaltene Labels der Klasse 0 namens object zuzuordnen. Fortsetzen und Validierung übernehmen gespeicherte Einstellungen. Das OBB-Modelltraining weist single_cls zurück.

ResNet, ConvNeXt, ConvNeXt V2, MobileNetV4, EfficientNetV2 und DINOv2 unterstützen cls_pw=0.0: Werte in [0, 1] gewichten jede Klasse mit ihrer inversen Häufigkeit hoch diesem Wert, normiert auf Mittelwert 1. class_weights=False wählt bei Aktivierung die alternative Gewichtung N / (C * n_c). Sie lässt sich nicht mit positivem cls_pw kombinieren; das Fortsetzen erfordert übereinstimmende Gewichtungseinstellungen.

plot_samples=8 legt das Budget für Validierungsbeispielbilder fest. Verwende 0 für keine oder -1 für alle; die Anzahl ausgewerteter Bilder wird dadurch nicht reduziert.