Callback#
Il framework Ultralytics supporta i callback, che fungono da punti di ingresso in fasi strategiche durante le modalità train, val, export e predict. Ciascun callback accetta un oggetto Trainer, Validator o Predictor, a seconda del tipo di operazione. Tutte le proprietà di questi oggetti sono descritte in dettaglio nelle pagine di riferimento BaseTrainer, BaseValidator e BasePredictor.
Watch: How to use Ultralytics Callbacks | Predict, Train, Validate and Export Callbacks | Ultralytics YOLO🚀
Esempi#
Restituzione di informazioni aggiuntive con la predizione#
In questo esempio mostriamo 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()
passRegistrazione degli hook di forward di PyTorch prima dell'addestramento#
model.train() compila un modello di addestramento dalla configurazione del modello e vi trasferisce i pesi caricati. Gli hook di PyTorch registrati direttamente su model.model prima di questa chiamata costituiscono uno stato di runtime, quindi il modello di addestramento ricostruito non li erredita. Registra gli hook di addestramento in on_pretrain_routine_end, dopo che la configurazione del modello è stata completata:
from ultralytics import YOLO
from ultralytics.utils.torch_utils import unwrap_model
def preprocess_input(module, inputs):
"""Center each input channel before the first model layer."""
images = inputs[0]
return (images - images.mean(dim=(-2, -1), keepdim=True),)
def register_forward_pre_hook(trainer):
"""Attach preprocessing to the active training model."""
train_model = unwrap_model(trainer.model)
train_model.model[0].register_forward_pre_hook(preprocess_input)
model = YOLO("yolo26n.pt")
model.add_callback("on_pretrain_routine_end", register_forward_pre_hook)
model.train(data="coco8.yaml", epochs=1)unwrap_model() gestisce sia l'addestramento su singolo dispositivo sia quello DistributedDataParallel. Non associare un hook definito localmente a trainer.ema.ema, poiché i checkpoint di addestramento serializzano il modello EMA e un altro processo potrebbe non essere in grado di importare la callback durante il caricamento del checkpoint. Se la stessa preelaborazione deve essere eseguita durante la validazione dell'addestramento, implementala come componente del modello importabile anziché come hook di runtime.
Il model.val() autonomo copia il modello caricato per ogni chiamata. La predizione crea e memorizza nella cache una copia alla sua prima chiamata, quindi registra gli hook su model.model prima della prima chiamata a model.predict() o model.track(); gli hook aggiunti successivamente non raggiungono il predittore memorizzato nella cache. Registra nuovamente gli hook di runtime dopo aver caricato un checkpoint in un nuovo processo.
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, total_loss e altre metriche dopo che un checkpoint viene 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, fai riferimento al codice sorgente dei callback.
Callback del trainer#
| Callback | Descrizione |
|---|---|
on_pretrain_routine_start | Attivato all'inizio della routine di pre-addestramento, prima del caricamento dei dati e della configurazione del modello. |
on_pretrain_routine_end | Attivato alla fine della routine di pre-addestramento, dopo che il caricamento dei dati e la configurazione del modello sono completati. |
on_train_start | Attivato all'avvio dell'addestramento, prima che inizi la prima epoca. |
on_train_epoch_start | Attivato all'inizio di ciascuna epoca di addestramento, prima che inizi l'iterazione dei batch. |
on_train_batch_start | Attivato all'inizio di ciascun batch di addestramento, prima del passaggio in avanti. |
optimizer_step | Attivato durante il passaggio dell'ottimizzatore. Riservato a integrazioni personalizzate; non chiamato dal ciclo di addestramento predefinito. |
on_before_zero_grad | Attivato prima che i gradienti vengano azzerati. Riservato a integrazioni personalizzate; non chiamato dal ciclo di addestramento predefinito. |
on_train_batch_end | Attivato alla fine di ciascun batch di addestramento, dopo il passaggio all'indietro. Il passaggio dell'ottimizzatore potrebbe essere posticipato a causa dell'accumulo dei gradienti. |
on_train_epoch_end | Attivato alla fine di ciascuna epoca di addestramento, dopo che tutti i batch sono stati elaborati ma prima della validazione. Le metriche di validazione e il fitness potrebbero non essere ancora disponibili. |
on_model_save | Attivato quando il checkpoint del modello viene salvato, dopo la validazione. |
on_fit_epoch_end | Attivato alla fine di ogni epoca di adattamento (addestramento + validazione), dopo la validazione e qualsiasi salvataggio del checkpoint. Le metriche di validazione sono disponibili e il fitness è disponibile per la chiamata di addestramento per epoca. Questo callback viene chiamato anche durante la valutazione finale del modello migliore, in cui non si verifica alcun salvataggio del checkpoint e il fitness potrebbe non essere presente. |
on_train_end | Attivato quando il processo di addestramento termina, dopo la valutazione finale del modello migliore. |
on_params_update | Attivato quando i parametri del modello vengono aggiornati. Riservato a integrazioni personalizzate; non chiamato dal ciclo di addestramento predefinito. |
teardown | Attivato quando il processo di addestramento viene ripulito. |
Callback del validatore#
| Callback | Descrizione |
|---|---|
on_val_start | Attivato quando inizia la validazione. |
on_val_batch_start | Attivato all'inizio di ciascun batch di validazione. |
on_val_batch_end | Attivato alla fine di ciascun batch di validazione. |
on_val_end | Attivato quando termina la validazione. |
Callback del predittore#
| Callback | Descrizione |
|---|---|
on_predict_start | Attivato quando inizia il processo di predizione. |
on_predict_batch_start | Attivato all'inizio di ciascun batch di predizione. |
on_predict_postprocess_end | Attivato alla fine della post-elaborazione della predizione. |
on_predict_batch_end | Attivato alla fine di ciascun batch di predizione. |
on_predict_end | Attivato quando termina il processo di predizione. |
Callback dell'esportatore#
| Callback | Descrizione |
|---|---|
on_export_start | Attivato quando inizia il processo di esportazione. |
on_export_end | Attivato quando termina il processo di esportazione. |
FAQ#
I callback di Ultralytics sono punti di ingresso specializzati che vengono attivati durante fasi chiave delle operazioni del modello come addestramento, validazione, esportazione e predizione. Questi callback abilitano funzionalità personalizzate in punti specifici del processo, consentendo miglioramenti e modifiche al flusso di lavoro. Ciascun callback accetta un oggetto
Trainer,ValidatoroPredictor, a seconda del tipo di operazione. Per le proprietà dettagliate di questi oggetti, fai riferimento alle pagine di riferimentoBaseTrainer,BaseValidatoreBasePredictor.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(): passPersonalizza la tua routine di addestramento di Ultralytics iniettando logica in fasi specifiche del processo di addestramento. YOLO di Ultralytics fornisce una varietà di callback di addestramento, come
on_train_start,on_train_endeon_train_batch_end, che ti consentono di aggiungere metriche personalizzate, elaborazione o registrazione.Ecco come bloccare le statistiche di BatchNorm quando congeli i layer 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 su come usare efficacemente i callback di addestramento, consulta la Guida all'addestramento.
L'uso dei callback durante la validazione in YOLO di Ultralytics migliora la valutazione del modello consentendo elaborazione personalizzata, registrazione o calcolo delle metriche. Callback come
on_val_start,on_val_batch_endeon_val_endforniscono punti di ingresso per iniettare logica personalizzata, garantendo processi di validazione dettagliati e completi.Per esempio, per tracciare tutti i batch di validazione invece dei 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 spunti sull'incorporazione dei callback nel tuo processo di validazione, consulta la Guida alla validazione.
Per associare un callback personalizzato per la modalità di predizione in YOLO di Ultralytics, definisci una funzione di callback e registrala con il processo di predizione. I callback di predizione comuni includono
on_predict_start,on_predict_batch_endeon_predict_end. Questi consentono la modifica degli output di predizione e l'integrazione di funzionalità aggiuntive, come la registrazione dei dati o la trasformazione dei risultati.Ecco un esempio in cui un callback personalizzato salva le predizioni in base alla presenza o meno 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: passPer un utilizzo più completo, fai riferimento alla Guida alla predizione, che include istruzioni dettagliate e opzioni di personalizzazione aggiuntive.
YOLO di Ultralytics supporta varie implementazioni pratiche di callback per migliorare e personalizzare diverse fasi come addestramento, validazione e predizione. Alcuni esempi pratici includono:
- Registrazione di metriche personalizzate: Registra metriche aggiuntive in diverse fasi, come alla fine delle epoche di addestramento o validazione.
- Augmentation dei dati: Implementa trasformazioni o augmentation dei dati personalizzate durante i batch di predizione o addestramento.
- Risultati intermedi: Salva risultati intermedi, come predizioni o fotogrammi, per ulteriori analisi o visualizzazioni.
Esempio: Combinazione di fotogrammi con i 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(): passEsplora il codice sorgente dei callback per ulteriori opzioni ed esempi.