Callbacks

Le framework Ultralytics prend en charge les callbacks, qui servent de points d'entrée à des étapes stratégiques lors des modes train, val, export et predict. Chaque callback accepte un objet Trainer, Validator ou Predictor, selon le type d'opération. Toutes les propriétés de ces objets sont détaillées dans la section Référence de la documentation.

Watch: How to use Ultralytics Callbacks | Predict, Train, Validate and Export Callbacks | Ultralytics YOLO🚀

Exemples

Retourner des informations supplémentaires avec la prédiction

Dans cet exemple, nous montrons comment retourner l'image originale avec chaque objet résultat :

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

Accéder aux métriques du modèle en utilisant le callback `on_model_save`

Cet exemple montre comment récupérer les détails de l'entraînement, tels que le score best_fitness, total_loss et d'autres métriques après qu'un checkpoint a été enregistré en utilisant le callback on_model_save.

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)

Tous les callbacks

Tu trouveras ci-dessous tous les callbacks pris en charge. Pour plus de détails, réfère-toi au code source des callbacks.

Callbacks de l'entraîneur (Trainer)

Callback	Description
`on_pretrain_routine_start`	Déclenché au début de la routine de pré-entraînement, avant le chargement des données et la configuration du modèle.
`on_pretrain_routine_end`	Déclenché à la fin de la routine de pré-entraînement, une fois le chargement des données et la configuration du modèle terminés.
`on_train_start`	Déclenché au démarrage de l'entraînement, avant le début de la première époque.
`on_train_epoch_start`	Déclenché au début de chaque époque d'entraînement, avant que l'itération des lots (batches) ne commence.
`on_train_batch_start`	Déclenché au début de chaque lot d'entraînement, avant la passe avant (forward pass).
`optimizer_step`	Déclenché pendant l'étape de l'optimiseur. Réservé aux intégrations personnalisées ; non appelé par la boucle d'entraînement par défaut.
`on_before_zero_grad`	Déclenché avant que les gradients ne soient remis à zéro. Réservé aux intégrations personnalisées ; non appelé par la boucle d'entraînement par défaut.
`on_train_batch_end`	Déclenché à la fin de chaque lot d'entraînement, après la passe arrière (backward pass). L'étape de l'optimiseur peut être différée en raison de l'accumulation de gradients.
`on_train_epoch_end`	Déclenché à la fin de chaque époque d'entraînement, après le traitement de tous les lots mais avant la validation. Les métriques de validation et le score de fitness peuvent ne pas encore être disponibles.
`on_model_save`	Déclenché lors de l'enregistrement du checkpoint du modèle, après la validation.
`on_fit_epoch_end`	Déclenché à la fin de chaque époque d'ajustement (train + val), après la validation et toute sauvegarde de checkpoint. Les métriques de validation sont disponibles, et le fitness est disponible pour l'appel d'entraînement par époque. Ce callback est également appelé lors de l'évaluation finale du meilleur modèle, où aucune sauvegarde de checkpoint n'a lieu et le fitness peut ne pas être présent.
`on_train_end`	Déclenché lorsque le processus d'entraînement se termine, après l'évaluation finale du meilleur modèle.
`on_params_update`	Déclenché lorsque les paramètres du modèle sont mis à jour. Réservé aux intégrations personnalisées ; non appelé par la boucle d'entraînement par défaut.
`teardown`	Déclenché lorsque le processus d'entraînement est en cours de nettoyage.

Callbacks du validateur (Validator)

Callback	Description
`on_val_start`	Déclenché au démarrage de la validation.
`on_val_batch_start`	Déclenché au début de chaque lot de validation.
`on_val_batch_end`	Déclenché à la fin de chaque lot de validation.
`on_val_end`	Déclenché à la fin de la validation.

Callbacks du prédicteur (Predictor)

Callback	Description
`on_predict_start`	Déclenché au démarrage du processus de prédiction.
`on_predict_batch_start`	Déclenché au début de chaque lot de prédiction.
`on_predict_postprocess_end`	Déclenché à la fin du post-traitement de la prédiction.
`on_predict_batch_end`	Déclenché à la fin de chaque lot de prédiction.
`on_predict_end`	Déclenché à la fin du processus de prédiction.

Callbacks de l'exportateur (Exporter)

Callback	Description
`on_export_start`	Déclenché au démarrage du processus d'exportation.
`on_export_end`	Déclenché à la fin du processus d'exportation.

FAQ

Qu'est-ce que les callbacks Ultralytics et comment puis-je les utiliser ?

Les callbacks Ultralytics sont des points d'entrée spécialisés qui sont déclenchés lors d'étapes clés des opérations du modèle, telles que l'entraînement, la validation, l'exportation et la prédiction. Ces callbacks permettent d'ajouter des fonctionnalités personnalisées à des moments précis du processus, facilitant ainsi les améliorations et modifications du flux de travail. Chaque callback accepte un objet Trainer, Validator ou Predictor, selon le type d'opération. Pour les propriétés détaillées de ces objets, réfère-toi à la section Référence.

Pour utiliser un callback, définis une fonction et ajoute-la au modèle en utilisant la méthode model.add_callback(). Voici un exemple pour retourner des informations supplémentaires lors de la prédiction :

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

Comment puis-je personnaliser la routine d'entraînement Ultralytics en utilisant des callbacks ?

Personnalise ta routine d'entraînement Ultralytics en injectant une logique à des étapes spécifiques du processus d'entraînement. Ultralytics YOLO fournit une variété de callbacks d'entraînement, tels que on_train_start, on_train_end et on_train_batch_end, qui te permettent d'ajouter des métriques, un traitement ou une journalisation personnalisés.

Voici comment figer les statistiques de BatchNorm lors du gel de couches avec des callbacks :

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)

Pour plus de détails sur l'utilisation efficace des callbacks d'entraînement, consulte le Guide d'entraînement.

Pourquoi devrais-je utiliser des callbacks pendant la validation dans Ultralytics YOLO ?

L'utilisation de callbacks pendant la validation dans Ultralytics YOLO améliore l'évaluation du modèle en permettant un traitement personnalisé, une journalisation ou un calcul de métriques. Des callbacks comme on_val_start, on_val_batch_end et on_val_end fournissent des points d'entrée pour injecter une logique personnalisée, garantissant des processus de validation détaillés et complets.

Par exemple, pour tracer tous les lots de validation au lieu de seulement les trois premiers :

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

Pour plus d'informations sur l'intégration des callbacks dans ton processus de validation, consulte le Guide de validation.

Comment puis-je attacher un callback personnalisé pour le mode prédiction dans Ultralytics YOLO ?

Pour attacher un callback personnalisé pour le mode prédiction dans Ultralytics YOLO, définis une fonction de callback et enregistre-la avec le processus de prédiction. Les callbacks de prédiction courants incluent on_predict_start, on_predict_batch_end et on_predict_end. Ceux-ci permettent de modifier les sorties de prédiction et d'intégrer des fonctionnalités supplémentaires, comme la journalisation des données ou la transformation des résultats.

Voici un exemple où un callback personnalisé enregistre les prédictions selon la présence d'un objet d'une classe particulière :

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

Pour une utilisation plus complète, réfère-toi au Guide de prédiction, qui inclut des instructions détaillées et des options de personnalisation supplémentaires.

Quels sont quelques exemples pratiques d'utilisation des callbacks dans Ultralytics YOLO ?

Ultralytics YOLO prend en charge diverses implémentations pratiques de callbacks pour améliorer et personnaliser différentes phases comme l'entraînement, la validation et la prédiction. Voici quelques exemples pratiques :

Journalisation de métriques personnalisées : journalise des métriques supplémentaires à différentes étapes, comme à la fin des époques d'entraînement ou de validation.
Augmentation de données : implémente des transformations ou des augmentations de données personnalisées pendant les lots de prédiction ou d'entraînement.
Résultats intermédiaires : sauvegarde des résultats intermédiaires, tels que des prédictions ou des images, pour une analyse ou une visualisation ultérieure.

Exemple : Combiner des images avec des résultats de prédiction pendant la prédiction en utilisant 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

Explore le code source des callbacks pour plus d'options et d'exemples.

Contributors

GLglenn-jocher¹³ RIRizwanMunawar³ RAraimbekovm² Y-Y-T-G¹

Created 12 nov. 2023Updated le mois dernier