Callbacks#

Ultralytics-Callbacks sind spezialisierte Einstiegspunkte, die während wichtiger Phasen von Modellvorgängen wie Training, Validierung, Export und Vorhersage ausgelöst werden. Mit diesen Callbacks kannst du an bestimmten Stellen des Prozesses benutzerdefinierte Funktionen einbinden und so den Arbeitsablauf erweitern und anpassen. Je nach Art des Vorgangs akzeptiert jeder Callback ein Objekt vom Typ Trainer, Validator oder Predictor. Ausführliche Informationen zu den Eigenschaften dieser Objekte findest du auf den Referenzseiten BaseTrainer, BaseValidator und BasePredictor.

Um einen Callback zu verwenden, definiere eine Funktion und füge sie dem Modell mit der Methode model.add_callback() hinzu. Hier ein Beispiel, wie du bei der Vorhersage zusätzliche Informationen zurückgibst:

from ultralytics import YOLO

def on_predict_batch_end(predictor):
    """Handle prediction batch end by combining results with corresponding frames; modifies predictor results."""
    _, image, _ = predictor.batch
    image = image if isinstance(image, list) else [image]
    predictor.results = zip(predictor.results, image)

model = YOLO("yolo26n.pt")
model.add_callback("on_predict_batch_end", on_predict_batch_end)
for result, frame in model.predict():
    pass

Passe deine Ultralytics-Trainingsroutine an, indem du an bestimmten Stellen des Trainingsprozesses eigene Logik einfügst. Ultralytics YOLO bietet verschiedene Trainings-Callbacks wie on_train_start, on_train_end und on_train_batch_end, mit denen du benutzerdefinierte Metriken, Verarbeitungsschritte oder Protokollierung hinzufügen kannst.

So protokollierst du die Lernrate jeder Parametergruppe des Optimizers am Ende jeder Trainingsepoche:

from ultralytics import YOLO

def log_learning_rates(trainer):
    """Print the current learning rates after each training epoch."""
    print(f"Epoch {trainer.epoch + 1}: {trainer.lr}")

model = YOLO("yolo26n.pt")
model.add_callback("on_train_epoch_end", log_learning_rates)
model.train(data="coco8.yaml", epochs=3)

Weitere Informationen zur effektiven Verwendung von Trainings-Callbacks findest du im Trainingsleitfaden.

Callbacks während der Validierung in Ultralytics YOLO verbessern die Modellauswertung, indem sie benutzerdefinierte Verarbeitung, Protokollierung oder Metrikberechnung ermöglichen. Callbacks wie on_val_start, on_val_batch_end und on_val_end bieten Einstiegspunkte, an denen du eigene Logik einfügen kannst. So lassen sich detaillierte und umfassende Validierungsabläufe sicherstellen.

So kannst du beispielsweise alle Validierungs-Batches statt nur der ersten drei darstellen:

import inspect

from ultralytics import YOLO

def plot_samples(validator):
    frame = inspect.currentframe().f_back.f_back
    v = frame.f_locals
    validator.plot_val_samples(v["batch"], v["batch_i"])
    validator.plot_predictions(v["batch"], v["preds"], v["batch_i"])

model = YOLO("yolo26n.pt")
model.add_callback("on_val_batch_end", plot_samples)
model.val(data="coco.yaml")

Weitere Informationen zum Einbinden von Callbacks in deinen Validierungsprozess findest du im Validierungsleitfaden.

Um in Ultralytics YOLO einen benutzerdefinierten Callback für den Vorhersagemodus hinzuzufügen, definiere eine Callback-Funktion und registriere sie beim Vorhersageprozess. Zu den gängigen Vorhersage-Callbacks gehören on_predict_start, on_predict_batch_end und on_predict_end. Damit kannst du Vorhersageausgaben ändern und zusätzliche Funktionen wie die Datenprotokollierung oder die Umwandlung von Ergebnissen integrieren.

Hier ein Beispiel für einen benutzerdefinierten Callback, der Vorhersagen abhängig davon speichert, ob ein Objekt einer bestimmten Klasse vorhanden ist:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

class_id = 2

def save_on_object(predictor):
    r = predictor.results[0]
    if class_id in r.boxes.cls:
        predictor.args.save = True
    else:
        predictor.args.save = False

model.add_callback("on_predict_postprocess_end", save_on_object)
results_stream = model("pedestrians.mp4", stream=True, save=True)

for result in results_stream:
    pass

Eine ausführlichere Anleitung mit detaillierten Anweisungen und weiteren Anpassungsmöglichkeiten findest du im Vorhersageleitfaden.

Ultralytics YOLO unterstützt verschiedene praktische Callback-Implementierungen, mit denen du unterschiedliche Phasen wie Training, Validierung und Vorhersage erweitern und anpassen kannst. Beispiele aus der Praxis:

• Benutzerdefinierte Metriken protokollieren: Protokolliere zusätzliche Metriken in verschiedenen Phasen, etwa am Ende von Trainings- oder Validierungsepochen.
• Datenerweiterung: Führe während der Vorhersage oder der Trainings-Batches benutzerdefinierte Datentransformationen oder -erweiterungen durch.
• Zwischenergebnisse: Speichere Zwischenergebnisse wie Vorhersagen oder Frames zur weiteren Analyse oder Visualisierung.

Beispiel: Frames während der Vorhersage mit den Vorhersageergebnissen kombinieren, indem du on_predict_batch_end verwendest:

from ultralytics import YOLO

def on_predict_batch_end(predictor):
    """Combine prediction results with frames."""
    _, image, _ = predictor.batch
    image = image if isinstance(image, list) else [image]
    predictor.results = zip(predictor.results, image)

model = YOLO("yolo26n.pt")
model.add_callback("on_predict_batch_end", on_predict_batch_end)
for result, frame in model.predict():
    pass

Weitere Möglichkeiten und Beispiele findest du im Quellcode der Callbacks.