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 previsione#

In questo esempio, dimostriamo come restituire il fotogramma 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 utilizzando il callback on_model_save#

Questo esempio mostra come recuperare i dettagli dell'addestramento, come il punteggio best_fitness, la 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 ulteriori dettagli, consulta il codice sorgente dei callback.

Callback del Trainer#

Callback del Validator#

Callback del Predictor#

Callback dell'Exporter#

FAQ#

Cosa sono i callback Ultralytics e come posso usarli?#

I callback Ultralytics sono punti di ingresso specializzati che vengono attivati durante fasi chiave delle operazioni del modello come addestramento, validazione, esportazione e previsione. Questi callback consentono funzionalità personalizzate in momenti 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 utilizzare un callback, definisci una funzione e aggiungila al modello utilizzando il metodo model.add_callback(). Ecco un esempio di come restituire informazioni aggiuntive durante la previsione:

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 Ultralytics utilizzando i callback?#

Personalizza la tua routine di addestramento Ultralytics iniettando 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, elaborazioni o log personalizzati.

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 ulteriori dettagli sull'uso efficace dei callback di addestramento, vedi la Guida all'addestramento.

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

L'utilizzo dei callback durante la validazione in Ultralytics YOLO migliora la valutazione del modello consentendo elaborazioni personalizzate, log o calcoli di metriche. Callback come on_val_start, on_val_batch_end e on_val_end forniscono punti di ingresso per iniettare 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'incorporazione dei callback nel processo di validazione, vedi la Guida alla validazione.

Come posso collegare un callback personalizzato per la modalità di previsione in Ultralytics YOLO?#

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

Ecco un esempio in cui un callback personalizzato salva le previsioni 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_stream = model("pedestrians.mp4", stream=True, save=True)

for result in results_stream:
    pass

Per un utilizzo più completo, fai riferimento alla Guida alla previsione, che include istruzioni dettagliate e opzioni di personalizzazione aggiuntive.

Quali sono alcuni esempi pratici di utilizzo dei callback in Ultralytics YOLO?#

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

• Logging di metriche personalizzate: Registra metriche aggiuntive in fasi diverse, come alla fine di epoche di addestramento o validazione.
• Data Augmentation: Implementa trasformazioni o aumenti di dati personalizzati durante la previsione o i batch di addestramento.
• Risultati intermedi: Salva risultati intermedi, come previsioni o fotogrammi, per ulteriori analisi o visualizzazioni.

Esempio: Combinazione di fotogrammi con risultati di previsione durante la previsione utilizzando 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.