Callbacks#
El framework de Ultralytics admite callbacks, que sirven como puntos de entrada en etapas estratégicas durante los modos train, val, export y predict. Cada callback acepta un objeto Trainer, Validator o Predictor, según el tipo de operación. Todas las propiedades de estos objetos se detallan en las páginas de referencia BaseTrainer, BaseValidator y BasePredictor.
Ver: Cómo usar las devoluciones de llamada de Ultralytics | Devoluciones de llamada para predecir, entrenar, validar y exportar | Ultralytics YOLO26 🚀
Ejemplos#
Devolver información adicional con la predicción#
En este ejemplo, mostramos cómo devolver el fotograma original junto con cada objeto de resultado:
from ultralytics import YOLO
def on_predict_batch_end(predictor):
"""Combine prediction results with corresponding frames."""
_, image, _ = predictor.batch
# Asegúrate de que image sea una lista
image = image if isinstance(image, list) else [image]
# Combina los resultados de la predicción con los fotogramas correspondientes
predictor.results = zip(predictor.results, image)
# Crea una instancia del modelo YOLO
model = YOLO("yolo26n.pt")
# Añade el callback personalizado al modelo
model.add_callback("on_predict_batch_end", on_predict_batch_end)
# Itera por los resultados y los fotogramas
for result, frame in model.predict(): # o model.track()
passRegistrar hooks de PyTorch forward antes del entrenamiento#
model.train() crea un modelo de entrenamiento a partir de la configuración del modelo y transfiere a él los pesos cargados. Los hooks de PyTorch registrados directamente en model.model antes de esta llamada son estado en tiempo de ejecución, por lo que el modelo de entrenamiento reconstruido no los hereda. Registra los hooks de entrenamiento en on_pretrain_routine_end, una vez completada la configuración del modelo:
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() gestiona tanto el entrenamiento en un solo dispositivo como el entrenamiento DistributedDataParallel. No asocies un hook definido localmente a trainer.ema.ema, porque los puntos de control del entrenamiento serializan el modelo EMA y es posible que otro proceso no pueda importar el callback al cargar el punto de control. Si el mismo preprocesamiento debe ejecutarse durante la validación del entrenamiento, impleméntalo como un componente del modelo importable en lugar de como un hook en tiempo de ejecución. La recuperación de NaN reconstruye el EMA a partir del modelo de entrenamiento, por lo que un hook registrado de este modo se copia en el EMA y en los puntos de control guardados después de la recuperación; define la función del hook en un módulo importable si es necesario cargar los puntos de control en otro proceso.
El model.val() independiente copia el modelo cargado en cada llamada. La predicción crea y almacena en caché una copia en la primera llamada, por lo que debes registrar los hooks en model.model antes de la primera llamada a model.predict() o model.track(); los hooks añadidos después no llegan al predictor almacenado en caché. Vuelve a registrar los hooks en tiempo de ejecución después de cargar un punto de control en un proceso nuevo.
Accede a las métricas del modelo mediante el callback on_model_save#
Este ejemplo muestra cómo recuperar detalles del entrenamiento, como la puntuación best_fitness, total_loss y otras métricas, después de guardar un punto de control mediante el 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)Todos los callbacks#
A continuación se muestran todos los callbacks compatibles. Para obtener más información, consulta el código fuente de los callbacks.
Callbacks del entrenador#
| Callback | Descripción |
|---|---|
on_pretrain_routine_start | Se activa al principio de la rutina de preentrenamiento, antes de cargar los datos y configurar el modelo. |
on_pretrain_routine_end | Se activa al final de la rutina de preentrenamiento, una vez completadas la carga de datos y la configuración del modelo. |
on_train_start | Se activa cuando comienza el entrenamiento, antes de que empiece la primera época. |
on_train_epoch_start | Se activa al inicio de cada época de entrenamiento, antes de que comience la iteración por lotes. |
on_train_batch_start | Se activa al inicio de cada lote de entrenamiento, antes de la pasada hacia delante. |
optimizer_step | Se activa durante el paso del optimizador. Reservado para integraciones personalizadas; el bucle de entrenamiento predeterminado no lo llama. |
on_before_zero_grad | Se activa antes de poner a cero los gradientes. Reservado para integraciones personalizadas; el bucle de entrenamiento predeterminado no lo llama. |
on_train_batch_end | Se activa al final de cada lote de entrenamiento, después de la pasada hacia atrás. El paso del optimizador puede aplazarse debido a la acumulación de gradientes. |
on_train_epoch_end | Se activa al final de cada época de entrenamiento, después de procesar todos los lotes, pero antes de la validación. Es posible que las métricas de validación y el fitness aún no estén disponibles. |
on_model_save | Se activa cuando se guarda el punto de control del modelo, después de la validación. |
on_fit_epoch_end | Se activa al final de cada época de ajuste (entrenamiento + validación), después de la validación y de guardar cualquier punto de control. Las métricas de validación están disponibles, y el fitness está disponible para la llamada de entrenamiento por época. Este callback también se llama durante la evaluación final del mejor modelo, cuando no se guarda ningún punto de control y puede que el fitness no esté presente. |
on_train_end | Se activa cuando finaliza el proceso de entrenamiento, después de la evaluación final del mejor modelo. |
on_params_update | Se activa cuando se actualizan los parámetros del modelo. Reservado para integraciones personalizadas; el bucle de entrenamiento predeterminado no lo llama. |
teardown | Se activa cuando se está limpiando el proceso de entrenamiento. |
Callbacks del validador#
| Callback | Descripción |
|---|---|
on_val_start | Se activa cuando comienza la validación. |
on_val_batch_start | Se activa al inicio de cada lote de validación. |
on_val_batch_end | Se activa al final de cada lote de validación. |
on_val_end | Se activa cuando finaliza la validación. |
Callbacks del predictor#
| Callback | Descripción |
|---|---|
on_predict_start | Se activa cuando comienza el proceso de predicción. |
on_predict_batch_start | Se activa al inicio de cada lote de predicción. |
on_predict_postprocess_end | Se activa al final del posprocesamiento de la predicción. |
on_predict_batch_end | Se activa al final de cada lote de predicción. |
on_predict_end | Se activa cuando finaliza el proceso de predicción. |
Callbacks del exportador#
| Callback | Descripción |
|---|---|
on_export_start | Se activa cuando comienza el proceso de exportación. |
on_export_end | Se activa cuando finaliza el proceso de exportación. |
Preguntas frecuentes#
Los callbacks de Ultralytics son puntos de entrada especializados que se activan durante las etapas clave de las operaciones del modelo, como el entrenamiento, la validación, la exportación y la predicción. Estos callbacks permiten añadir funciones personalizadas en momentos concretos del proceso, lo que permite mejorar y modificar el flujo de trabajo. Cada callback acepta un objeto
Trainer,ValidatoroPredictor, según el tipo de operación. Para consultar las propiedades detalladas de estos objetos, visita las páginas de referenciaBaseTrainer,BaseValidatoryBasePredictor.Para usar un callback, define una función y añádela al modelo mediante el método
model.add_callback(). Aquí tienes un ejemplo de cómo devolver información adicional durante la predicción: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(): passPersonaliza la rutina de entrenamiento de Ultralytics inyectando lógica en etapas específicas del proceso de entrenamiento. Ultralytics YOLO ofrece varios callbacks de entrenamiento, como
on_train_start,on_train_endyon_train_batch_end, que te permiten añadir métricas, procesamiento o registros personalizados.Así puedes registrar la tasa de aprendizaje de cada grupo de parámetros del optimizador al final de cada época de entrenamiento:
from ultralytics import YOLO def log_learning_rates(trainer): """Print the current learning rates after each training epoch.""" print(f"Epoch {trainer.epoch + 1}: {trainer.lr}") model = YOLO("yolo26n.pt") model.add_callback("on_train_epoch_end", log_learning_rates) model.train(data="coco8.yaml", epochs=3)ConsejoNo necesitas un callback para congelar las estadísticas de BatchNorm al usar
freeze: el entrenador pone automáticamente las capas BatchNorm de las capas congeladas en modo eval al inicio de cada época.Para obtener más información sobre el uso eficaz de los callbacks de entrenamiento, consulta la Guía de entrenamiento.
El uso de callbacks durante la validación en Ultralytics YOLO mejora la evaluación del modelo al permitir el procesamiento personalizado, el registro de datos o el cálculo de métricas. Los callbacks como
on_val_start,on_val_batch_endyon_val_endproporcionan puntos de entrada para inyectar lógica personalizada y garantizar procesos de validación detallados y exhaustivos.Por ejemplo, para representar todos los lotes de validación en lugar de solo los tres primeros:
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")Para obtener más información sobre cómo incorporar callbacks al proceso de validación, consulta la Guía de validación.
Para asociar un callback personalizado al modo de predicción de Ultralytics YOLO, define una función callback y regístrala en el proceso de predicción. Entre los callbacks de predicción habituales se incluyen
on_predict_start,on_predict_batch_endyon_predict_end. Estos permiten modificar los resultados de la predicción e integrar funcionalidades adicionales, como el registro de datos o la transformación de resultados.Aquí tienes un ejemplo de un callback personalizado que guarda predicciones según si está presente un objeto de una clase concreta:
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: passPara obtener información más completa sobre su uso, consulta la Guía de predicción, que incluye instrucciones detalladas y opciones de personalización adicionales.
Ultralytics YOLO admite diversas implementaciones prácticas de callbacks para mejorar y personalizar distintas fases, como el entrenamiento, la validación y la predicción. Algunos ejemplos prácticos son:
- Registro de métricas personalizadas: registra métricas adicionales en distintas etapas, como al final de las épocas de entrenamiento o validación.
- Aumento de datos: implementa transformaciones o aumentos de datos personalizados durante la predicción o los lotes de entrenamiento.
- Resultados intermedios: guarda resultados intermedios, como predicciones o fotogramas, para analizarlos o visualizarlos más adelante.
Ejemplo: combinar fotogramas con resultados de predicción durante la predicción 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(): passConsulta el código fuente de los callbacks para ver más opciones y ejemplos.