Ultralytics YOLO27:

Обратные вызовы#

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



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

Регистрация PyTorch перенаправляющих хуков (Forward Hooks) перед началом обучения#

model.train() собирает обучаемую модель из конфигурации модели и переносит в нее загруженные веса. Хуки PyTorch, зарегистрированные непосредственно на model.model до этого вызова, представляют собой состояние среды выполнения, поэтому пересозданная обучаемая модель не наследует их. Регистрируй обучающие хуки в on_pretrain_routine_end, после завершения настройки модели:

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() поддерживает как обучение на одном устройстве, так и распределенное обучение (DistributedDataParallel). Не прикрепляй локально определенный хук к trainer.ema.ema, поскольку точки сохранения обучения сериализуют EMA-модель, и другой процесс может не суметь импортировать этот колбэк при загрузке точки сохранения. Если ту же предобработку нужно выполнять во время валидации при обучении, реализуй ее в виде импортируемого компонента модели вместо хука среды выполнения.

Автономный model.val() копирует загруженную модель при каждом вызове. Предсказание создает и кэширует копию при первом вызове, поэтому регистрируй хуки на model.model до первого вызова model.predict() или model.track(); хуки, добавленные позже, не попадут в кэшированный предиктор. Повторно регистрируй хуки среды выполнения после загрузки точки сохранения в новом процессе.

Доступ к метрикам модели с помощью обратного вызова 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)

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

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

Обратные вызовы тренера#

Обратный вызовОписание
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Вызывается в конце каждой эпохи обучения, после обработки всех батчей, но до валидации. Метрики валидации и пригодность могут быть еще недоступны.
on_model_saveВызывается при сохранении контрольной точки модели, после валидации.
on_fit_epoch_endВызывается в конце каждой эпохи подгонки (обучение + валидация), после валидации и сохранения любых контрольных точек. Метрики валидации доступны, а пригодность доступна для вызова обучения за эпоху. Этот обратный вызов также вызывается во время финальной оценки лучшей модели, где сохранение контрольной точки не происходит и пригодность может отсутствовать.
on_train_endВызывается по окончании процесса обучения, после финальной оценки лучшей модели.
on_params_updateВызывается при обновлении параметров модели. Зарезервировано для пользовательских интеграций; не вызывается циклом обучения по умолчанию.
teardownВызывается при очистке процесса обучения.

Обратные вызовы валидатора#

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

Обратные вызовы предиктора#

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

Обратные вызовы экспортера#

Обратный вызовОписание
on_export_startВызывается при запуске процесса экспорта.
on_export_endВызывается по окончании процесса экспорта.

Часто задаваемые вопросы#

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

    Чтобы использовать обратный вызов, определи функцию и добавь ее в модель с помощью метода 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 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 улучшает оценку модели, позволяя осуществлять пользовательскую обработку, логирование или расчет метрик. Обратные вызовы, такие как 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, определи функцию обратного вызова и зарегистрируй ее в процессе прогнозирования. Распространенные обратные вызовы прогнозирования включают 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_stream = model("pedestrians.mp4", stream=True, save=True)

for result in results_stream:
    pass

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

  • 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

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

Участники
GLglenn-jocher16RIRizwanMunawar3RAraimbekovm2A A Aswanth Raj1Y-Y-T-G1

Комментарии