Начать

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

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



Смотри: Как использовать колбэки Ultralytics | Колбэки для predict, train, validate и export | Ultralytics YOLO26 🚀

Примеры#

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

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

from ultralytics import YOLO

def on_predict_batch_end(predictor):
    """Combine prediction results with corresponding frames."""
    _, image, _ = predictor.batch

    # Убедись, что image — это список
    image = image if isinstance(image, list) else [image]

    # Объедини результаты предсказания с соответствующими кадрами
    predictor.results = zip(predictor.results, image)

# Создай экземпляр модели YOLO
model = YOLO("yolo26n.pt")

# Добавь пользовательский колбэк к модели
model.add_callback("on_predict_batch_end", on_predict_batch_end)

# Перебери результаты и кадры
for result, frame in model.predict():  # или model.track()
    pass

Регистрация PyTorch forward-хуков перед обучением#

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, и другой процесс может не иметь возможности импортировать колбэк при загрузке контрольной точки. Если одна и та же предобработка должна выполняться при валидации во время обучения, реализуй ее как импортируемый компонент модели, а не как хук времени выполнения. При восстановлении после NaN модель 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Вызывается в конце каждой эпохи обучения, после обработки всех батчей, но до валидации. Метрики валидации и fitness могут быть еще недоступны.
on_model_saveВызывается при сохранении контрольной точки модели, после валидации.
on_fit_epoch_endВызывается в конце каждой эпохи обучения (обучение + валидация), после валидации и сохранения контрольной точки, если оно выполнялось. Метрики валидации доступны, а fitness доступен для вызова обучения по эпохам. Этот колбэк также вызывается при итоговой оценке лучшей модели, когда контрольная точка не сохраняется и fitness может отсутствовать.
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 или Exporter.

    Чтобы использовать колбэк, определи функцию и добавь ее к модели с помощью метода 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, которые позволяют добавлять пользовательские метрики, обработку данных или журналирование.

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

    from ultralytics import YOLO
    
    def log_learning_rates(trainer):
        """Print the current learning rates after each training epoch."""
        print(f"Epoch {trainer.epoch + 1}: {trainer.lr}")
    
    model = YOLO("yolo26n.pt")
    model.add_callback("on_train_epoch_end", log_learning_rates)
    model.train(data="coco8.yaml", epochs=3)
    Совет

    При использовании freeze колбэк для заморозки статистики BatchNorm не нужен: в начале каждой эпохи тренер автоматически переводит слои BatchNorm замороженных слоев в режим eval.

    Подробнее об эффективном использовании колбэков обучения см. в руководстве по обучению.

  • Колбэки валидации позволяют добавлять пользовательскую обработку, журналирование или вычисление метрик при оценке модели. Такие колбэки, как 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

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

Участники

Комментарии15

Задай вопрос, поделись результатами или помоги кому-нибудь.

  1. drbilal216GitHub

    Hi can i and how use callback to freeze initial layers for number of epochs and unfreeze after that, is there any builtin function for that? i used freeze builtin function but it freezes for all the epochs.

    1. drbilal216GitHub

      also, after certain epochs the change in model training is minimal can we use callback then to change lr, how and what parameter to change ?

    2. Glenn JocherUltralytics

      @drbilal216 yes, you can use callbacks to freeze/unfreeze layers dynamically during training. Here's how to freeze initial layers for specific epochs then unfreeze them:

      from ultralytics import YOLO
      
      def dynamic_freeze_callback(trainer):
          freeze_epochs = 10  # Freeze for first 10 epochs
          freeze_layers = 10  # Number of layers to freeze
          
          if trainer.epoch < freeze_epochs:
              # Freeze layers
              for i, (name, param) in enumerate(trainer.model.named_parameters()):
                  if i < freeze_layers:
                      param.requires_grad = False
          else:
              # Unfreeze all layers
              for param in trainer.model.parameters():
                  param.requires_grad = True
      
      model = YOLO("yolo11n.pt")
      model.add_callback("on_train_epoch_start", dynamic_freeze_callback)
      model.train(data="coco8.yaml", epochs=20)

      For dynamic learning rate adjustment when training plateaus, you can modify the scheduler within a callback:

      def dynamic_lr_callback(trainer):
          if trainer.epoch > 50 and trainer.epoch % 10 == 0:  # Every 10 epochs after epoch 50
              for param_group in trainer.optimizer.param_groups:
                  param_group['lr'] *= 0.9  # Reduce LR by 10%
      
      model.add_callback("on_train_epoch_end", dynamic_lr_callback)
      1
    3. drbilal216GitHub

      @glenn-jocher Thanks for the code! I'm working on a low-quality PPE dataset. With a custom YAML, I improved YOLOv12n accuracy by 3%, and got similar results on YOLOv11n with better FPS.

      The default Nano model lets me use pretrained=True, but custom architectures start from scratch. Still, I can reuse best.pt as pretrained weights on the same YAML later.

      I'm now exploring argument tuning and callbacks for further improvements. I also tried freezing/unfreezing layers mid-training but saw no gains.

      Lastly, I integrated Flash into YOLOv12, but I don’t see any sign that it’s being used during training (tested on Colab and A100 80GB-server).

  2. jnance34GitHub

    Hello,

    I'm trying to implement a custom on_pretrain_routine_end callback with a model.tune() call, but it appears that the Tuner class isn't adding my custom callback function to the Tuner.callbacks list. Here's some pseudo code of what I'm trying to do:

    def my_custom_callback(trainer):
        print("I'm in my custom callback function!")
    
    model = YOLO("model/yolo11n.pt")
    model.add_callback('on_pretrain_routine_end', my_custom_function)
    model.tune(...)
    # Expect to see "I'm in my custom callback function" for each trial run...

    For some reason my custom callback function isn't getting called for each training run of the Tuner. Am I missing a step here? I've taken a look at the source code but don't see anything obviously wrong...

    Thanks!

    -James

    1. Glenn JocherUltralytics

      @ruslanraupoff for multi-GPU training with callbacks, ensure your callback function is properly registered in all processes. When using DDP mode, callbacks need to be added before the training starts and should be compatible with distributed training environments. If you're experiencing issues, verify that your callback logic is thread-safe and doesn't rely on process-specific resources. For implementation details, refer to our callbacks documentation: https://docs.ultralytics.com/usage/callbacks

      1
  3. D3RK0GitHub

    Hi, in the documentation above, I see that predictor.batch is used, which I assume refers to the current batch of the predictor. Is there a similar trainer.batch for a trainer? I need it in order to apply data augmentation during the training of my YOLOv8 classifier.

    1. Glenn JocherUltralytics(изменено)

      @D3RK0 trainer callbacks only receive the trainer object, so the current batch is not available there as trainer.batch. To apply custom augmentation to each training batch, subclass your trainer (e.g. ClassificationTrainer) and override preprocess_batch(self, batch), which receives every training batch before the forward pass.

    2. D3RK0GitHub(изменено)

      @glenn-jocher Many thanks for your quick response!

      I am dealing with following problem though:

      Problem

      When I do trainer.batch, I get the following error:

      Traceback (most recent call last):
        File "C:\Program Files\JetBrains\PyCharm Community Edition 2022.3.3\plugins\python-ce\helpers\pydev\pydevd.py", line 1534, in _exec
          pydev_imports.execfile(file, globals, locals)  # execute the script
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "C:\Program Files\JetBrains\PyCharm Community Edition 2022.3.3\plugins\python-ce\helpers\pydev\_pydev_imps\_pydev_execfile.py", line 18, in execfile
          exec(compile(contents+"\n", file, 'exec'), glob, loc)
        File "C:\Users\derk_\Documents\Universiteit\IRP\Research_Project\main.py", line 397, in <module>
          main()
        File "C:\Users\derk_\Documents\Universiteit\IRP\Research_Project\main.py", line 377, in main
          model.train(mode="classify",
        File "C:\Users\derk_\anaconda3\envs\cobra\Lib\site-packages\ultralytics\engine\model.py", line 802, in train
          self.trainer.train()
        File "C:\Users\derk_\anaconda3\envs\cobra\Lib\site-packages\ultralytics\engine\trainer.py", line 207, in train
          self._do_train(world_size)
        File "C:\Users\derk_\anaconda3\envs\cobra\Lib\site-packages\ultralytics\engine\trainer.py", line 368, in _do_train
          self.run_callbacks("on_train_batch_start")
        File "C:\Users\derk_\anaconda3\envs\cobra\Lib\site-packages\ultralytics\engine\trainer.py", line 168, in run_callbacks
          callback(self)
        File "C:\Users\derk_\Documents\Universiteit\IRP\Research_Project\main.py", line 185, in batch_augmentation_callback
          batch = trainer.batch  # Access the current batch
                  ^^^^^^^^^^^^^
      AttributeError: 'ClassificationTrainer' object has no attribute 'batch'

      My code

      model = YOLO("yolov8m-cls.pt")
      
      model.add_callback("on_train_batch_start", batch_augmentation_callback)
      
      model.train(mode="classify",
                  data=data_file_dir,
                  epochs=args.n_epochs)
      
      # Where batch_augmentation_callback is my callback function
      def batch_augmentation_callback(trainer):
          batch = trainer.batch                                        # This code line causes the error reported above
          images, labels = batch['img'], batch['label']
          # More code below to create data augmentation

      Content of trainer object that is passed into batch_augmentation_callback (my callback function)

      • trainer = {ClassificationTrainer} <ultralytics.models.yolo.classify.train.ClassificationTrainer object at 0x0000016929FA5010>
      • accumulate = {int} 4
      • amp = {bool} False
      • args = {IterableSimpleNamespace} IterableSimpleNamespace(task='classify', mode='train', model='yolov8m-cls.pt', data='C:/Users/derk_/Documents/Universiteit/IRP...ugment='randaugment', erasing=0.4, crop_fraction=1.0, cfg=None, tracker='botsort.yaml', save_dir='C:\runs\classify\train53')
      • batch_size = {int} 16
      • best = {WindowsPath} WindowsPath('C:/runs/classify/train53/weights/best.pt')
      • best_fitness = {NoneType} None
      • callbacks = {defaultdict: 25} defaultdict(<class 'list'>, {'on_pretrain_routine_start': [<function on_pretrain_routine_start at 0x0000016929C79440>, <functi...C7A2A0>, <function on_export_start at 0x000001692A55C220>], 'on_export_end': [<function on_export_end at 0x0000016929C7A340>]})
      • csv = {WindowsPath} WindowsPath('C:/runs/classify/train53/results.csv')
      • data = {dict: 5} {'names': {0: '1', 1: '10', 2: '100', 3: '101', 4: '102', 5: '11', 6: '12', 7: '13', 8: '14', 9: '15', 10: '16', 11: '17', 12: '18', 13: '19', 14: '2', 15: '20', 16: '21', 17: '22', 18: '23', 19: '24', 20: '25', 21: '26', 22: '27', 23: '28', 24: '29', 25:
      • device = {device} device(type='cpu')
      • ema = {ModelEMA} <ultralytics.utils.torch_utils.ModelEMA object at 0x000001692AC80C90>
      • epoch = {int} 0
      • epoch_time = {NoneType} None
      • epoch_time_start = {float} 1731355033.8569636
      • epochs = {int} 1
      • fitness = {NoneType} None
      • hub_session = {NoneType} None
      • last = {WindowsPath} WindowsPath('C:/runs/classify/train53/weights/last.pt')
      • loss = {NoneType} None
      • loss_names = {list: 1} ['loss']
      • metrics = {dict: 3} {'metrics/accuracy_top1': 0, 'metrics/accuracy_top5': 0, 'val/loss': 0}
      • model = {ClassificationModel} ClassificationModel(\n (model): Sequential(\n (0): Conv(\n (conv): Conv2d(3, 48, kernel_size=(3, 3), stride=(2, 2), padd...1)\n (drop): Dropout(p=0.0, inplace=True)\n (linear): Linear(in_features=1280, out_features=102, bias=True)\n )\n )\n)
      • optimizer = {AdamW} AdamW (\nParameter Group 0\n amsgrad: False\n base_momentum: 0.85\n betas: (0.9499811807836418, 0.999)\n capturable: Fa... lr: 0.004018066447703833\n max_lr: 0.1\n max_momentum: 0.95\n maximize: False\n min_lr: 4e-07\n weight_decay: 0.0\n)
      • plot_idx = {list: 6} [0, 1, 2, -3465, -3464, -3463]
      • plots = {dict: 0} {}
      • resume = {bool} False
      • save_dir = {WindowsPath} WindowsPath('C:/runs/classify/train53')
      • save_period = {int} 1
      • scaler = {GradScaler} <torch.amp.grad_scaler.GradScaler object at 0x000001692921A0D0>
      • scheduler = {OneCycleLR} <torch.optim.lr_scheduler.OneCycleLR object at 0x000001692ACF5210>
      • start_epoch = {int} 0
      • stop = {bool} False
      • stopper = {EarlyStopping} <ultralytics.utils.torch_utils.EarlyStopping object at 0x000001692ACF7190>
      • stride = {int} 32
      • test_loader = {InfiniteDataLoader: 32} <ultralytics.data.build.InfiniteDataLoader object at 0x000001692AAD7B50>
      • testset = {WindowsPath} WindowsPath('C:/Users/derk_/Documents/Universiteit/IRP/Research_Project/Oxford-Flower-dataset/jpg/val')
      • tloss = {NoneType} None
      • train_loader = {InfiniteDataLoader: 385} <ultralytics.data.build.InfiniteDataLoader object at 0x00000169297FFDD0>
      • train_time_start = {float} 1731355033.8569636
      • trainset = {WindowsPath} WindowsPath('C:/Users/derk_/Documents/Universiteit/IRP/Research_Project/Oxford-Flower-dataset/jpg/train')
      • validator = {ClassificationValidator} <ultralytics.models.yolo.classify.val.ClassificationValidator object at 0x000001692AC80BD0>
      • wdir = {WindowsPath} WindowsPath('C:/runs/classify/train53/weights')

      Question

      If it is right that trainer.batch does not exist (in this case), which other object in trainer - as listed above in the content of trainer - can I extract the current batch?

    3. Glenn JocherUltralytics(изменено)

      The trainer.batch attribute does not exist in the current implementation, and iterating trainer.train_loader inside a callback would draw a different batch rather than the current one. Instead, override preprocess_batch(self, batch) in a custom trainer subclass to modify each batch before it is used.

    4. D3RK0GitHub(изменено)

      @glenn-jocher Many thanks for answering!

      Okay, I have been able to access the batches via trainer.train_loader and subsequently apply data augmentation to each batch. However, ...

      Problem

      ... assigning the batch back (see also the code below) to trainer.train_loader is not possible, as I get:

      trainer.train_loader[i] = batch ~~~~~~~~~~~~~~~~~~~~^^^ TypeError: 'InfiniteDataLoader' object does not support item assignment

      Code

      def batches_augmentation_callback(trainer):
          for i, batch in enumerate(trainer.train_loader):
              images, labels = batch['img'], batch['cls']
              cutmix_or_mixup = LoadOxfordFlowerDataset.data_augmentation(n_classes_in_batch=args.n_classes)
              images, labels = cutmix_or_mixup(images, labels)
              batch = {"img": images, "cls": labels}
              trainer.train_loader[i] = batch     # BUG: trainer.train_loader object does not support item assignment

      Question

      How can I return the augmented batch to the trainer object if assignment does not work?

    5. Glenn JocherUltralytics

      You cannot directly assign to trainer.train_loader. Instead, apply your augmentation within the loop and yield the modified batch back to the training process. Consider using a custom data loader or modifying the dataset directly for more complex augmentations.