Обратные вызовы (Callbacks)

Фреймворк Ultralytics поддерживает обратные вызовы, которые служат точками входа на стратегических этапах работы в режимах train, val, export и predict. Каждый обратный вызов принимает объект Trainer, Validator или Predictor в зависимости от типа операции. Все свойства этих объектов подробно описаны в разделе справочных материалов документации.

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

Примеры

Возврат дополнительной информации при предсказании

В этом примере мы покажем, как возвращать исходный кадр вместе с каждым объектом результата:

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

Доступ к метрикам модели с помощью обратного вызова `on_model_save`

Этот пример показывает, как получить детали обучения, такие как показатель best_fitness, total_loss и другие метрики, после сохранения контрольной точки с помощью обратного вызова 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)

Все обратные вызовы

Ниже представлены все поддерживаемые обратные вызовы. Для получения дополнительных сведений обратись к исходному коду обратных вызовов.

Обратные вызовы для обучения (Trainer Callbacks)

Обратный вызов	Описание
`on_pretrain_routine_start`	Срабатывает в начале процедуры предварительного обучения, перед загрузкой данных и настройкой модели.
`on_pretrain_routine_end`	Срабатывает в конце процедуры предварительного обучения, после завершения загрузки данных и настройки модели.
`on_train_start`	Срабатывает при начале обучения, до начала первой эпохи.
`on_train_epoch_start`	Срабатывает в начале каждой эпохи обучения, перед началом итерации пакета.
`on_train_batch_start`	Срабатывает в начале каждого пакета обучения, перед прямым проходом.
`optimizer_step`	Срабатывает во время шага оптимизатора. Зарезервировано для пользовательских интеграций; не вызывается стандартным циклом обучения.
`on_before_zero_grad`	Срабатывает перед обнулением градиентов. Зарезервировано для пользовательских интеграций; не вызывается стандартным циклом обучения.
`on_train_batch_end`	Срабатывает в конце каждого пакета обучения, после обратного прохода. Шаг оптимизатора может быть отложен из-за накопления градиентов.
`on_train_epoch_end`	Срабатывает в конце каждой эпохи обучения, после того как все пакеты обработаны, но до проверки (валидации). Метрики валидации и показатель пригодности (fitness) могут быть еще недоступны.
`on_model_save`	Срабатывает при сохранении контрольной точки модели после валидации.
`on_fit_epoch_end`	Срабатывает в конце каждой эпохи соответствия (обучение + валидация), после валидации и любого сохранения контрольной точки. Метрики валидации и показатель пригодности доступны для вызова обучения по эпохам. Этот обратный вызов также вызывается во время финальной оценки лучшей модели, где сохранение контрольной точки не происходит, и показатель пригодности может отсутствовать.
`on_train_end`	Срабатывает при завершении процесса обучения, после финальной оценки лучшей модели.
`on_params_update`	Срабатывает при обновлении параметров модели. Зарезервировано для пользовательских интеграций; не вызывается стандартным циклом обучения.
`teardown`	Срабатывает при очистке процесса обучения.

Обратные вызовы для валидации (Validator Callbacks)

Обратный вызов	Описание
`on_val_start`	Срабатывает при начале валидации.
`on_val_batch_start`	Срабатывает в начале каждого пакета валидации.
`on_val_batch_end`	Срабатывает в конце каждого пакета валидации.
`on_val_end`	Срабатывает при завершении валидации.

Обратные вызовы для предсказания (Predictor Callbacks)

Обратный вызов	Описание
`on_predict_start`	Срабатывает при начале процесса предсказания.
`on_predict_batch_start`	Срабатывает в начале каждого пакета предсказания.
`on_predict_postprocess_end`	Срабатывает в конце постобработки предсказания.
`on_predict_batch_end`	Срабатывает в конце каждого пакета предсказания.
`on_predict_end`	Срабатывает при завершении процесса предсказания.

Обратные вызовы для экспорта (Exporter Callbacks)

Обратный вызов	Описание
`on_export_start`	Срабатывает при начале процесса экспорта.
`on_export_end`	Срабатывает при завершении процесса экспорта.

Часто задаваемые вопросы (FAQ)

Что такое обратные вызовы Ultralytics и как их использовать?

Обратные вызовы Ultralytics — это специализированные точки входа, которые срабатывают на ключевых этапах работы модели, таких как обучение, валидация, экспорт и предсказание. Эти вызовы позволяют добавить пользовательскую функциональность в конкретные моменты процесса, обеспечивая улучшение и модификацию рабочего процесса. Каждый обратный вызов принимает объект Trainer, Validator или Predictor в зависимости от типа операции. Подробную информацию о свойствах этих объектов см. в разделе справочных материалов.

Чтобы использовать обратный вызов, определи функцию и добавь ее к модели с помощью метода model.add_callback(). Вот пример возврата дополнительной информации во время предсказания:

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

Как настроить процедуру обучения Ultralytics с помощью обратных вызовов?

Настраивай свою процедуру обучения Ultralytics, внедряя логику на конкретных этапах процесса обучения. Ultralytics YOLO предоставляет множество обратных вызовов для обучения, таких как on_train_start, on_train_end и on_train_batch_end, которые позволяют добавлять пользовательские метрики, обработку или логирование.

Вот как заморозить статистику BatchNorm при заморозке слоев с помощью обратных вызовов:

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)

Более подробную информацию об эффективном использовании обратных вызовов при обучении см. в Руководстве по обучению.

Почему стоит использовать обратные вызовы при валидации в Ultralytics YOLO?

Использование обратных вызовов при валидации в Ultralytics YOLO улучшает процесс оценки модели, позволяя выполнять пользовательскую обработку, логирование или расчет метрик. Обратные вызовы, такие как on_val_start, on_val_batch_end и on_val_end, предоставляют точки входа для внедрения собственной логики, обеспечивая детальный и комплексный процесс валидации.

Например, чтобы построить графики для всех пакетов валидации, а не только для первых трех:

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")

Более подробную информацию о внедрении обратных вызовов в процесс валидации см. в Руководстве по валидации.

Как прикрепить пользовательский обратный вызов для режима предсказания в Ultralytics YOLO?

Чтобы прикрепить пользовательский обратный вызов для режима предсказания в Ultralytics YOLO, определи функцию обратного вызова и зарегистрируй ее в процессе предсказания. Распространенные обратные вызовы для предсказания включают on_predict_start, on_predict_batch_end и on_predict_end. Они позволяют изменять результаты предсказания и интегрировать дополнительные функциональные возможности, такие как логирование данных или преобразование результатов.

Ниже приведен пример, в котором пользовательский обратный вызов сохраняет результаты предсказания в зависимости от того, присутствует ли объект определенного класса:

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

Для более полного ознакомления обратись к Руководству по предсказанию, которое содержит подробные инструкции и дополнительные параметры настройки.

Какие существуют практические примеры использования обратных вызовов в Ultralytics YOLO?

Ultralytics YOLO поддерживает различные практические реализации обратных вызовов для улучшения и настройки таких фаз, как обучение, валидация и предсказание. Несколько практических примеров:

Логирование пользовательских метрик: логируй дополнительные метрики на разных этапах, например, в конце обучения или валидации эпох.
Аугментация данных: внедряй собственные преобразования или аугментации данных во время предсказания или для пакетов обучения.
Промежуточные результаты: сохраняй промежуточные результаты, такие как предсказания или кадры, для дальнейшего анализа или визуализации.

Пример: объединение кадров с результатами предсказания во время предсказания с использованием 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

Изучи исходный код обратных вызовов для получения дополнительных вариантов и примеров.

Contributors

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

Created 12 нояб. 2023 г.Updated в прошлом месяце