Callbacks

El framework 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 la sección de referencia de la documentación.

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

Ejemplos

Devolver información adicional con la predicción

En este ejemplo, demostramos cómo devolver el frame 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

    # 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

Acceder 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 checkpoint 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 más detalles, consulta el código fuente de los callbacks.

Callbacks del Trainer

Callback	Descripción
`on_pretrain_routine_start`	Se activa al principio de la rutina de preentrenamiento, antes de la carga de datos y la configuración del 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 adelante (forward pass).
`optimizer_step`	Se activa durante el paso del optimizador. Reservado para integraciones personalizadas; no es llamado por el bucle de entrenamiento predeterminado.
`on_before_zero_grad`	Se activa antes de que los gradientes se pongan a cero. Reservado para integraciones personalizadas; no es llamado por el bucle de entrenamiento predeterminado.
`on_train_batch_end`	Se activa al final de cada lote de entrenamiento, después de la pasada hacia atrás (backward pass). El paso del optimizador puede posponerse debido a la acumulación de gradientes.
`on_train_epoch_end`	Se activa al final de cada época de entrenamiento, después de que se procesen todos los lotes pero antes de la validación. Es posible que las métricas de validación y la adecuación (fitness) aún no estén disponibles.
`on_model_save`	Se activa cuando se guarda el checkpoint 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 cualquier guardado de checkpoint. Las métricas de validación están disponibles, y la adecuación (fitness) está disponible para la llamada de entrenamiento por época. Este callback también se invoca durante la evaluación final del mejor modelo, donde no se realiza ningún guardado de checkpoint y es posible que la adecuación no esté presente.
`on_train_end`	Se activa cuando termina el proceso de entrenamiento, tras la evaluación final del mejor modelo.
`on_params_update`	Se activa cuando se actualizan los parámetros del modelo. Reservado para integraciones personalizadas; no es llamado por el bucle de entrenamiento predeterminado.
`teardown`	Se activa cuando se está limpiando el proceso de entrenamiento.

Callbacks del Validator

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 termina 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 postprocesamiento de la predicción.
`on_predict_batch_end`	Se activa al final de cada lote de predicción.
`on_predict_end`	Se activa cuando termina el proceso de predicción.

Callbacks del Exporter

Callback	Descripción
`on_export_start`	Se activa cuando comienza el proceso de exportación.
`on_export_end`	Se activa cuando termina el proceso de exportación.

Preguntas frecuentes

¿Qué son los callbacks de Ultralytics y cómo puedo usarlos?

Los callbacks de Ultralytics son puntos de entrada especializados que se activan durante etapas clave de las operaciones del modelo, tales como el entrenamiento, la validación, la exportación y la predicción. Estos callbacks permiten una funcionalidad personalizada en puntos específicos del proceso, lo que facilita mejoras y modificaciones en el flujo de trabajo. Cada callback acepta un objeto Trainer, Validator o Predictor, según el tipo de operación. Para obtener las propiedades detalladas de estos objetos, consulta la sección de referencia.

Para usar un callback, define una función y añádela al modelo utilizando 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():
    pass

¿Cómo puedo personalizar la rutina de entrenamiento de Ultralytics mediante callbacks?

Personaliza tu rutina de entrenamiento de Ultralytics inyectando lógica en etapas específicas del proceso de entrenamiento. Ultralytics YOLO proporciona una variedad de callbacks de entrenamiento, como on_train_start, on_train_end y on_train_batch_end, que te permiten añadir métricas, procesamiento o registro personalizados.

Así es como se congelan las estadísticas de BatchNorm al congelar capas con 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)

Para más detalles sobre cómo utilizar eficazmente los callbacks de entrenamiento, consulta la Guía de entrenamiento.

¿Por qué debería usar callbacks durante la validación en Ultralytics YOLO?

El uso de callbacks durante la validación en Ultralytics YOLO mejora la evaluación del modelo al permitir el procesamiento personalizado, el registro o el cálculo de métricas. Callbacks como on_val_start, on_val_batch_end y on_val_end proporcionan puntos de entrada para inyectar lógica personalizada, garantizando procesos de validación detallados y exhaustivos.

Por ejemplo, para trazar 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 más información sobre la incorporación de callbacks en tu proceso de validación, consulta la Guía de validación.

¿Cómo adjunto un callback personalizado para el modo de predicción en Ultralytics YOLO?

Para adjuntar un callback personalizado para el modo de predicción en Ultralytics YOLO, define una función de callback y regístrala con el proceso de predicción. Los callbacks de predicción comunes incluyen on_predict_start, on_predict_batch_end y on_predict_end. Estos permiten la modificación de los resultados de las predicciones y la integración de funcionalidades adicionales, como el registro de datos o la transformación de resultados.

Aquí hay un ejemplo donde un callback personalizado guarda las predicciones según si está presente o no un objeto de una clase en particular:

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

Para un uso más completo, consulta la Guía de predicción, que incluye instrucciones detalladas y opciones de personalización adicionales.

¿Cuáles son algunos ejemplos prácticos de uso de callbacks en Ultralytics YOLO?

Ultralytics YOLO admite varias implementaciones prácticas de callbacks para mejorar y personalizar diferentes fases como el entrenamiento, la validación y la predicción. Algunos ejemplos prácticos incluyen:

Registro de métricas personalizadas: Registra métricas adicionales en diferentes 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 frames, para su posterior análisis o visualización.

Ejemplo: Combinar frames con resultados de predicción durante la predicción mediante 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

Explora el código fuente de los callbacks para más opciones y ejemplos.

Contributors

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

Created 12 nov 2023Updated el mes pasado