Callbacks
El framework de Ultralytics soporta callbacks, que sirven como puntos de entrada en etapas estratégicas durante el train
, val
, export
, y predict
modos. Cada callback acepta un Trainer
, Validator
, o Predictor
objeto, dependiendo del tipo de operación. Todas las propiedades de estos objetos se detallan en Sección de referencia de la documentación.
Ver: Cómo utilizar Callbacks de Ultralytics | Callbacks de predicción, entrenamiento, validación y exportación | Ultralytics YOLO🚀
Ejemplos
Devolviendo Información Adicional con la Predicción
En este ejemplo, demostramos 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
# 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("yolo11n.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
Acceda a las métricas del modelo utilizando el on_model_save
callback
Este ejemplo muestra cómo recuperar detalles del entrenamiento, como la puntuación best_fitness, la pérdida total y otras métricas después de guardar un punto de control utilizando el on_model_save
callback.
from ultralytics import YOLO
# Load a YOLO model
model = YOLO("yolo11n.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" admitidos. Para obtener más detalles, 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 pre-entrenamiento. |
on_pretrain_routine_end |
Se activa al final de la rutina de pre-entrenamiento. |
on_train_start |
Se activa cuando comienza el entrenamiento. |
on_train_epoch_start |
Se activa al inicio de cada época de entrenamiento. |
on_train_batch_start |
Se activa al inicio de cada lote de entrenamiento. |
optimizer_step |
Se activa durante el paso del optimizador. |
on_before_zero_grad |
Se activa antes de que los gradientes se pongan a cero. |
on_train_batch_end |
Se activa al final de cada lote de entrenamiento. |
on_train_epoch_end |
Se activa al final de cada época de entrenamiento. |
on_fit_epoch_end |
Se activa al final de cada época de ajuste. |
on_model_save |
Se activa cuando se guarda el modelo. |
on_train_end |
Se activa cuando finaliza el proceso de entrenamiento. |
on_params_update |
Se activa cuando se actualizan los parámetros del modelo. |
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 post-procesamiento 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
¿Qué son los callbacks de Ultralytics y cómo puedo usarlos?
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 habilitan la funcionalidad personalizada en puntos específicos del proceso, lo que permite mejoras y modificaciones en el flujo de trabajo. Cada callback acepta un Trainer
, Validator
, o Predictor
objeto, dependiendo del tipo de operación. Para obtener información detallada sobre las propiedades de estos objetos, consulte Sección de referencia.
Para usar un callback, defina una función y añádala al modelo usando el model.add_callback()
método. Aquí tiene 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("yolo11n.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 utilizando retrollamadas?
Personalice su rutina de entrenamiento de Ultralytics inyectando lógica en etapas específicas del proceso de entrenamiento. Ultralytics YOLO proporciona una variedad de devoluciones de llamada de entrenamiento, como on_train_start
, on_train_end
, y on_train_batch_end
, que le permiten añadir métricas personalizadas, procesamiento o registro.
Aquí se muestra cómo congelar las estadísticas de BatchNorm al congelar capas con retrollamadas:
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("yolo11n.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 el uso eficaz de los callbacks de entrenamiento, consulte 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
proporciona puntos de entrada para inyectar lógica personalizada, garantizando procesos de validación detallados y completos.
Por ejemplo, para trazar todos los lotes de validación en lugar de sólo 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("yolo11n.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 su proceso de validación, consulte la Guía de Validación.
¿Cómo adjunto un callback personalizado para el modo de predicción en Ultralytics YOLO?
Para adjuntar una retrollamada personalizada para el modo de predicción en Ultralytics YOLO, define una función de retrollamada y regístrala en el proceso de predicción. Las retrollamadas de predicción comunes incluyen on_predict_start
, on_predict_batch_end
, y on_predict_end
. Estos permiten la modificación de las salidas de predicción y la integración de funcionalidades adicionales, como el registro de datos o la transformación de resultados.
Aquí hay un ejemplo donde una retrollamada personalizada guarda las predicciones basándose en si un objeto de una clase en particular está presente:
from ultralytics import YOLO
model = YOLO("yolo11n.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 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 del entrenamiento o de las épocas de validación.
- Aumento de datos: Implementa transformaciones o aumentos de datos personalizados durante la predicción o los lotes de entrenamiento.
- Resultados intermedios: Guarde los resultados intermedios, como predicciones o fotogramas, para su posterior análisis o visualización.
Ejemplo: Combinación de fotogramas con resultados de predicción durante la predicción utilizando 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("yolo11n.pt")
model.add_callback("on_predict_batch_end", on_predict_batch_end)
for result, frame in model.predict():
pass
Explore el código fuente de la callback para obtener más opciones y ejemplos.