Link to this sectionCallbacks#

Das Ultralytics-Framework unterstützt Callbacks, die als Einstiegspunkte in strategischen Phasen der Modi train, val, export und predict dienen. Jeder Callback akzeptiert je nach Operationstyp ein Trainer-, Validator- oder Predictor-Objekt. Alle Eigenschaften dieser Objekte sind im Referenzabschnitt der Dokumentation aufgeführt.

Link to this sectionBeispiele#

Link to this sectionZusätzliche Informationen mit Vorhersagen zurückgeben#

In diesem Beispiel zeigen wir, wie du zusammen mit jedem Ergebnisobjekt den ursprünglichen Frame zurückgibst:

from ultralytics import YOLO

def on_predict_batch_end(predictor):
    """Combine prediction results with corresponding frames."""
    _, image, _, _ = predictor.batch

    # Ensure that image is a list
    image = image if isinstance(image, list) else [image]

    # Combine the prediction results with the corresponding frames
    predictor.results = zip(predictor.results, image)

# Create a YOLO model instance
model = YOLO("yolo26n.pt")

# Add the custom callback to the model
model.add_callback("on_predict_batch_end", on_predict_batch_end)

# Iterate through the results and frames
for result, frame in model.predict():  # or model.track()
    pass

Link to this sectionAuf Modellmetriken über den on_model_save-Callback zugreifen#

Dieses Beispiel zeigt, wie du Trainingsdetails wie den best_fitness-Score, total_loss und andere Metriken nach dem Speichern eines Checkpoints mithilfe des on_model_save-Callbacks abrufst.

from ultralytics import YOLO

# Load a YOLO model
model = YOLO("yolo26n.pt")

def print_checkpoint_metrics(trainer):
    """Print trainer metrics and loss details after each checkpoint is saved."""
    print(
        f"Model details\n"
        f"Best fitness: {trainer.best_fitness}, "
        f"Loss names: {trainer.loss_names}, "  # List of loss names
        f"Metrics: {trainer.metrics}, "
        f"Total loss: {trainer.tloss}"  # Total loss value
    )

if __name__ == "__main__":
    # Add on_model_save callback.
    model.add_callback("on_model_save", print_checkpoint_metrics)

    # Run model training on custom dataset.
    results = model.train(data="coco8.yaml", epochs=3)

Link to this sectionAlle Callbacks#

Nachfolgend findest du alle unterstützten Callbacks. Weitere Einzelheiten findest du im Quellcode der Callbacks.

Link to this sectionTrainer-Callbacks#

Link to this sectionValidator-Callbacks#

Link to this sectionPredictor-Callbacks#

Link to this sectionExporter-Callbacks#

Link to this sectionFAQ#

Link to this sectionWas sind Ultralytics-Callbacks und wie kann ich sie verwenden?#

Ultralytics-Callbacks sind spezialisierte Einstiegspunkte, die während wichtiger Phasen von Modelloperationen wie Training, Validierung, Export und Vorhersage ausgelöst werden. Diese Callbacks ermöglichen benutzerdefinierte Funktionen an spezifischen Punkten im Prozess und erlauben Verbesserungen und Modifikationen des Workflows. Jeder Callback akzeptiert je nach Operationstyp ein Trainer-, Validator- oder Predictor-Objekt. Details zu den Eigenschaften dieser Objekte findest du im Referenzabschnitt.

Um einen Callback zu verwenden, definiere eine Funktion und füge sie dem Modell mithilfe der Methode model.add_callback() hinzu. Hier ist ein Beispiel für die Rückgabe zusätzlicher Informationen während der Vorhersage:

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

Link to this sectionWie kann ich die Ultralytics-Trainingsroutine mithilfe von Callbacks anpassen?#

Passe deine Ultralytics-Trainingsroutine an, indem du Logik in spezifischen Phasen des Trainingsprozesses einfügst. Ultralytics YOLO bietet eine Vielzahl von Trainings-Callbacks wie on_train_start, on_train_end und on_train_batch_end, mit denen du benutzerdefinierte Metriken, Verarbeitungen oder Protokollierungen hinzufügen kannst.

So frierst du BatchNorm-Statistiken ein, wenn du Schichten mit Callbacks fixierst:

from ultralytics import YOLO

# Add a callback to put the frozen layers in eval mode to prevent BN values from changing
def put_in_eval_mode(trainer):
    n_layers = trainer.args.freeze
    if not isinstance(n_layers, int):
        return

    for i, (name, module) in enumerate(trainer.model.named_modules()):
        if name.endswith("bn") and int(name.split(".")[1]) < n_layers:
            module.eval()
            module.track_running_stats = False

model = YOLO("yolo26n.pt")
model.add_callback("on_train_epoch_start", put_in_eval_mode)
model.train(data="coco.yaml", epochs=10)

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

Link to this sectionWarum sollte ich Callbacks während der Validierung in Ultralytics YOLO verwenden?#

Die Verwendung von Callbacks während der Validierung in Ultralytics YOLO verbessert die Modellbewertung durch benutzerdefinierte Verarbeitung, Protokollierung oder Metrikberechnung. Callbacks wie on_val_start, on_val_batch_end und on_val_end bieten Einstiegspunkte, um eigene Logik einzufügen und detaillierte, umfassende Validierungsprozesse sicherzustellen.

Um beispielsweise alle Validierungs-Batches anstatt nur die ersten drei zu plotten:

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 Einblicke in die Einbindung von Callbacks in deinen Validierungsprozess findest du im Validierungsleitfaden.

Link to this sectionWie hänge ich einen benutzerdefinierten Callback für den Vorhersagemodus in Ultralytics YOLO an?#

Um einen benutzerdefinierten Callback für den Vorhersagemodus in Ultralytics YOLO anzuhängen, definiere eine Callback-Funktion und registriere sie im Vorhersageprozess. Häufige Vorhersage-Callbacks sind on_predict_start, on_predict_batch_end und on_predict_end. Diese ermöglichen die Änderung von Vorhersageausgaben und die Integration zusätzlicher Funktionen, wie z. B. Datenprotokollierung oder Ergebnistransformation.

Hier ist ein Beispiel, bei dem ein benutzerdefinierter Callback Vorhersagen basierend darauf 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 = model("pedestrians.mp4", stream=True, save=True)

for results in results:
    pass

Für eine umfassendere Nutzung beziehe dich auf den Vorhersageleitfaden, der detaillierte Anweisungen und weitere Anpassungsoptionen enthält.

Link to this sectionWas sind einige praktische Beispiele für die Verwendung von Callbacks in Ultralytics YOLO?#

Ultralytics YOLO unterstützt verschiedene praktische Implementierungen von Callbacks, um verschiedene Phasen wie Training, Validierung und Vorhersage zu verbessern und anzupassen. Einige praktische Beispiele sind:

• Benutzerdefinierte Metriken protokollieren: Protokolliere zusätzliche Metriken in verschiedenen Stadien, beispielsweise am Ende von Trainings- oder Validierungs-Epochen.
• Datenaugmentation: Implementiere benutzerdefinierte Datentransformationen oder Augmentierungen während Vorhersage- oder Trainings-Batches.
• Zwischenergebnisse: Speichere Zwischenergebnisse wie Vorhersagen oder Frames für weitere Analysen oder Visualisierungen.

Beispiel: Kombinieren von Frames mit Vorhersageergebnissen während der Vorhersage mithilfe von on_predict_batch_end:

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

Erkunde den Quellcode der Callbacks für weitere Optionen und Beispiele.