Callback

Il framework Ultralytics supporta i callback, che fungono da punti di ingresso in fasi strategiche durante le modalità train, val, export e predict. Ogni callback accetta un oggetto Trainer, Validator o Predictor, a seconda del tipo di operazione. Tutte le proprietà di questi oggetti sono dettagliate nella sezione di riferimento della documentazione.

Esempi

Restituzione di informazioni aggiuntive con la predizione

In questo esempio, mostriamo come restituire il frame originale insieme a ciascun oggetto risultato:

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

Accedi alle metriche del modello usando il callback on_model_save

Questo esempio mostra come recuperare i dettagli dell'addestramento, come il punteggio best_fitness, total_loss e altre metriche dopo che un checkpoint è stato salvato utilizzando il 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)

Tutti i callback

Di seguito sono riportati tutti i callback supportati. Per maggiori dettagli, consulta il codice sorgente dei callback.

Callback del Trainer

Callback del Validator

Callback del Predictor

Callback dell'Exporter

FAQ

Cosa sono i callback di Ultralytics e come posso usarli?

I callback di Ultralytics sono punti di ingresso specializzati che vengono attivati durante le fasi chiave delle operazioni del modello, come addestramento, validazione, esportazione e predizione. Questi callback consentono funzionalità personalizzate in punti specifici del processo, permettendo miglioramenti e modifiche al flusso di lavoro. Ogni callback accetta un oggetto Trainer, Validator o Predictor, a seconda del tipo di operazione. Per le proprietà dettagliate di questi oggetti, consulta la sezione di riferimento.

Per usare un callback, definisci una funzione e aggiungila al modello usando il metodo model.add_callback(). Ecco un esempio di restituzione di informazioni aggiuntive durante la predizione:

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

Come posso personalizzare la routine di addestramento di Ultralytics usando i callback?

Personalizza la tua routine di addestramento Ultralytics inserendo logica in fasi specifiche del processo di addestramento. Ultralytics YOLO fornisce una varietà di callback di addestramento, come on_train_start, on_train_end e on_train_batch_end, che ti consentono di aggiungere metriche personalizzate, elaborazione o logging.

Ecco come bloccare le statistiche di BatchNorm quando si bloccano i livelli con i callback:

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)

Per maggiori dettagli sull'uso efficace dei callback di addestramento, consulta la Guida all'addestramento.

Perché dovrei usare i callback durante la validazione in Ultralytics YOLO?

L'uso dei callback durante la validazione in Ultralytics YOLO migliora la valutazione del modello consentendo elaborazione personalizzata, logging o calcolo delle metriche. Callback come on_val_start, on_val_batch_end e on_val_end forniscono punti di ingresso per inserire logica personalizzata, garantendo processi di validazione dettagliati e completi.

Ad esempio, per tracciare tutti i batch di validazione invece dei soli primi tre:

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

Per ulteriori approfondimenti sull'integrazione dei callback nel tuo processo di validazione, consulta la Guida alla validazione.

Come collego un callback personalizzato per la modalità di predizione in Ultralytics YOLO?

Per collegare un callback personalizzato per la modalità di predizione in Ultralytics YOLO, definisci una funzione di callback e registrala con il processo di predizione. I callback di predizione comuni includono on_predict_start, on_predict_batch_end e on_predict_end. Questi consentono la modifica degli output di predizione e l'integrazione di funzionalità aggiuntive, come il logging dei dati o la trasformazione dei risultati.

Ecco un esempio in cui un callback personalizzato salva le predizioni in base alla presenza di un oggetto di una particolare classe:

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

Per un utilizzo più completo, consulta la Guida alla predizione, che include istruzioni dettagliate e ulteriori opzioni di personalizzazione.

Quali sono alcuni esempi pratici dell'uso dei callback in Ultralytics YOLO?

Ultralytics YOLO supporta varie implementazioni pratiche di callback per migliorare e personalizzare diverse fasi come addestramento, validazione e predizione. Alcuni esempi pratici includono:

• Logging di metriche personalizzate: Logga metriche aggiuntive in diverse fasi, come alla fine di epoche di addestramento o validazione.
• Data Augmentation: Implementa trasformazioni o aumenti di dati personalizzati durante i batch di predizione o addestramento.
• Risultati intermedi: Salva risultati intermedi, come predizioni o frame, per ulteriori analisi o visualizzazione.

Esempio: Combinazione di frame con risultati di predizione durante la predizione usando 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

Esplora il codice sorgente del callback per ulteriori opzioni ed esempi.