Link to this sectionCallbacks#

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

Link to this sectionEjemplos#

Link to this sectionDevolver 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

Link to this sectionAcceder 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 usando 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)

Link to this sectionTodos los callbacks#

A continuación se muestran todos los callbacks admitidos. Para obtener más detalles, consulta el código fuente de los callbacks.

Link to this sectionCallbacks del Trainer#

Link to this sectionCallbacks del Validator#

Link to this sectionCallbacks del Predictor#

Link to this sectionCallbacks del Exporter#

Link to this sectionFAQ#

Link to this section¿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 entrenamiento, validación, exportación y predicción. Estos callbacks permiten funcionalidades personalizadas en momentos específicos del proceso, posibilitando 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 propiedades detalladas de estos objetos, consulta la sección de referencia.

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():
    pass

Link to this section¿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. 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 registros (logging) personalizados.

Aquí te mostramos cómo congelar 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 obtener más detalles sobre cómo usar eficazmente los callbacks de entrenamiento, consulta la Guía de entrenamiento.

Link to this section¿Por qué debería usar callbacks durante la validación en Ultralytics YOLO?#

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

Por ejemplo, para graficar 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 en tu proceso de validación, consulta la Guía de validación.

Link to this section¿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 en 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 la predicción y la integración de funcionalidades adicionales, como el registro de datos o la transformación de resultados.

Aquí tienes un ejemplo donde un callback personalizado guarda predicciones según si está presente un objeto de una clase 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.

Link to this section¿Cuáles son algunos ejemplos prácticos del 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 los lotes de predicción o 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 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

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