开始使用

回调

Ultralytics 框架支持回调,可作为 train、val、predict 和 export 模式中关键阶段的入口。根据操作类型,每个回调接收 Trainer、Validator、Predictor 或 Exporter 对象。



观看: 如何使用 Ultralytics 回调 | 预测、训练、验证和导出回调 | 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 前向钩子#

model.train() 根据模型配置构建训练模型,并将已加载的权重迁移到该模型中。在调用此方法之前直接在 model.model 上注册的 PyTorch 钩子属于运行时状态,因此重建后的训练模型不会继承这些钩子。请在模型设置完成后,于 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.predict() 或 model.track() 之前,在 model.model 上注册钩子;之后添加的钩子不会传递到缓存的预测器。在新进程中加载检查点后,请重新注册运行时钩子。

使用 on_model_save 回调访问模型指标#

此示例展示了如何使用 on_model_save 回调,在保存检查点后获取训练详情,例如 best_fitness 分数、total_loss 和其他指标。

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在每个训练 epoch 开始时触发,且在批次迭代开始之前执行。
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 或 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 层设为评估模式。

    有关如何有效使用训练回调的更多详情,请参阅训练指南。

  • 验证回调可让你在模型评估过程中添加自定义处理、日志记录或指标计算。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 支持多种实用的回调实现,可增强和自定义训练、验证和预测等不同阶段。以下是一些实用示例:

    • 记录自定义指标:在不同阶段记录额外指标,例如训练或验证 epoch 结束时。
    • 数据增强:在预测或训练批次期间实现自定义数据转换或增强。
    • 中间结果:保存预测或帧等中间结果,以供进一步分析或可视化。

    示例:使用 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.