Ultralytics 基础回调模块Base Callbacks源码级解析事件钩子、默认注册机制与自定义扩展【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics导读本文以 Ultralytics 仓库中的基础回调源码模块 ultralytics/utils/callbacks/base.py 为核心系统讲解驱动train、val、predict、export四种模式生命周期的全部事件钩子hook。你将从源码层面掌握事件钩子是如何定义与分组的、default_callbacks字典如何把 25 个事件名映射为默认回调、get_default_callbacks()与add_integration_callbacks()两条关键函数的作用以及如何在Trainer/Validator/Predictor/Exporter对象上通过add_callback自定义扩展行为。读完本文后你将能精确判断在哪个事件点插入自己的代码并能看懂框架内置日志与第三方实验平台ClearML、Comet、MLflow、TensorBoard、WB 等的接入原理。说明本文全部结论基于当前仓库快照中的实际源码、API 参考文档与测试用例。建议读者结合 utils/callbacks/init.py、engine/trainer.py、engine/model.py 与配套使用指南 docs/en/usage/callbacks.md 一起阅读。一、模块定位回调系统的“事件目录 空实现占位”在 Ultralytics 的训练、验证、预测与导出流程中回调callback是框架预留的“插桩点”让外部代码可以在关键阶段被自动调用。而 ultralytics/utils/callbacks/base.py 是这个子系统的最底层文件它承担两件事声明全部合法事件名以同名函数的形式定义训练、验证、预测、导出四个生命周期中可以被触发的所有事件提供每个事件的默认空实现这些函数只带清晰的 docstring 说明、函数体为空表示“框架默认对该事件不做额外处理”。因此从源码结构看base.py 实质上是整套回调系统的规范清单与占位符。真正的业务逻辑由两部分补齐一是引擎代码在特定位置主动调用事件见第三节二是各集成模块用真实逻辑替换/追加到这些事件上见第六节。模块注释里的定位模块 docstring 只有一句话却精准概括了职责Base callbacks for Ultralytics training, validation, prediction, and export processes.即它是面向Trainer、Validator、Predictor、Exporter四类对象的基础回调集合。回调函数统一签名约定base.py 中所有事件钩子都遵循同一签名约定——接收当前流程的宿主对象作为唯一参数训练类回调的形参命名为trainer运行时传入BaseTrainer子类实例验证类回调的形参为validator预测类回调的形参为predictor导出类回调的形参为exporter。通过宿主对象用户可以在回调内部访问到该阶段几乎全部上下文属性如trainer.model、trainer.args、predictor.results、validator.metrics等。这一约定是后续所有自定义回调编写的基础。二、base.py 导出的三类公共构件从模块层级看base.py 对外暴露三种内容构件类型作用25 个on_*/optimizer_step/teardown钩子函数函数空实现声明事件点并充当默认回调占位default_callbacks模块级字典建立“事件名 → 默认回调列表”的映射get_default_callbacks()函数返回深拷贝后的默认回调字典defaultdictadd_integration_callbacks(instance)函数向宿主实例动态追加事件统计与三方平台回调模块自身通过 utils/callbacks/init.py 对外公开三个名字from .base import add_integration_callbacks, default_callbacks, get_default_callbacks __all__ add_integration_callbacks, default_callbacks, get_default_callbacks也就是说其他模块在使用回调系统时通常只引用default_callbacks、get_default_callbacks()和add_integration_callbacks()三者。三、事件钩子全景四组生命周期 逐事件触发时机base.py 按“运行在哪个宿主里”把事件分为四组。下面按 API 参考文档的既有顺序逐一说明每组事件的定义与真实触发位置。触发位置均可在对应引擎源码中用run_callbacks(事件名)检索验证。3.1 Trainer 回调运行于训练流程共 14 个训练回调参数对象为trainer在 engine/trainer.py 的训练主循环中触发事件docstring 定义源码中的真实触发时机on_pretrain_routine_start预训练例行程序开始时、加载数据与模型搭建之前BaseTrainer.__init__阶段trainer.py在get_dataset()之前触发用于捕获原始args.data如ul://等远程 URIon_pretrain_routine_end预训练例行程序结束时、数据加载与模型搭建完成后setup_model()收尾处trainer.pyon_train_start训练开始、首个 epoch 开始前_do_train()中_setup_train()完成后立即触发trainer.pyon_train_epoch_start每个训练 epoch 开始、遍历 batch 之前每个 epoch 循环开头trainer.py早于scheduler.step()与 batch 迭代on_train_batch_start每个训练 batch 开始、前向传播之前每个 batch 迭代起点trainer.py可用于读改写 batchoptimizer_step优化器 step 时。预留给自定义集成默认训练循环不会调用见下注on_before_zero_grad梯度清零之前。预留给自定义集成默认训练循环不会调用见下注on_train_batch_end每个训练 batch 结束、反向传播之后优化器 step 可能因梯度累积而推迟batch 迭代末尾trainer.pyon_train_epoch_end每个训练 epoch 结束、所有 batch 处理完后但早于验证epoch 内 batch 循环结束后、验证前trainer.py。注意此时验证指标尚不可用on_fit_epoch_end每个 fit epoch训练验证结束时、验证与可能的 checkpoint 保存之后验证、指标落盘、on_model_save之后trainer.py最佳模型最终评估阶段也会调用trainer.py此时可能不保存权重、fitness可能缺失on_model_save模型 checkpoint 被保存时、验证之后save_model()返回真后触发trainer.pyon_train_end训练结束、对最佳模型完成最终评估之后训练主循环收尾、final_eval()之后trainer.py仅RANK in {-1, 0}进程触发on_params_update模型参数更新时。预留给自定义集成默认训练循环不会调用见下注teardown训练进程清理期间训练入口train()的finally尾部trainer.py非 DDP 模式下执行三个“预留给集成”事件optimizer_step、on_before_zero_grad、on_params_update在 base.py 的 docstring 中明确写着 “Reserved for custom integrations; not called by default.”。在默认训练循环中框架未调用它们而是为需要精准接管优化器 step、梯度清零与参数更新的第三方库如自定义 AMP 策略、梯度处理插件预留的接入点。这与on_train_batch_end不同——后者会被默认流程调用只是优化器 step 因梯度累积accumulate 1而相对 batch 边界有所推迟。注意测试套件还展示了一种非文档公开用法——默认训练循环会在每个 batch 记录时调用run_callbacks(on_batch_end)trainer.py它并未出现在default_callbacks字典中说明引擎允许事件名与默认回调表解耦。以官方文档为准自定义时应使用表中经过注册的事件名。3.2 Validator 回调运行于验证流程共 4 个验证回调参数对象为validator在 engine/validator.py 中触发事件触发时机对应源码行on_val_start验证流程开始时validator.py早于指标初始化on_val_batch_start每个验证 batch 开始时validator.pyon_val_batch_end每个验证 batch 结束时validator.py可用于批量绘图或统计on_val_end验证整体结束时validator.py此时validator.metrics已就绪一个典型应用是把“默认只绘制前三个 batch 样本”扩展为全部绘制在on_val_batch_end回调里访问当前帧局部变量并调用validator.plot_val_samples(...)/validator.plot_predictions(...)该写法示例见官方使用指南 docs/en/usage/callbacks.md。3.3 Predictor 回调运行于预测流程共 5 个预测回调参数对象为predictor在 engine/predictor.py 的stream_inference流程中触发事件触发时机对应源码行on_predict_start预测流程开始时predictor.pyon_predict_batch_start每个预测 batch 开始时predictor.pyon_predict_postprocess_end后处理结束、得到最终results后predictor.py。此时可改写predictor.results例如按类别条件决定是否保存on_predict_batch_end每个预测 batch 结束时predictor.pyon_predict_end预测流程整体结束时predictor.py官方示例中的“把原图与检测结果一起返回”正是挂在on_predict_batch_end上读取predictor.batch中的图像后执行predictor.results zip(predictor.results, image)即可在遍历结果时同时拿到对应帧。3.4 Exporter 回调运行于导出流程共 2 个导出回调参数对象为exporter在 engine/exporter.py 中触发事件触发时机对应源码行on_export_start模型导出开始时exporter.py早于格式检查与序列化on_export_end模型导出结束时exporter.py所有目标格式写出之后on_export_start同时被内置的事件统计用于记录一次匿名导出行为见第六节。四、default_callbacks事件名到默认回调的注册表base.py 中default_callbacks是一个模块级字典结构为“事件名 → 存放回调函数的列表”其完整键值可用如下方式获取from ultralytics.utils.callbacks import default_callbacks print(sorted(default_callbacks.keys()))其内容按宿主划分如下值与源码第 121–151 行一致default_callbacks { # Run in trainer —— 14 个训练事件 on_pretrain_routine_start: [on_pretrain_routine_start], on_pretrain_routine_end: [on_pretrain_routine_end], on_train_start: [on_train_start], on_train_epoch_start: [on_train_epoch_start], on_train_batch_start: [on_train_batch_start], optimizer_step: [optimizer_step], on_before_zero_grad: [on_before_zero_grad], on_train_batch_end: [on_train_batch_end], on_train_epoch_end: [on_train_epoch_end], on_fit_epoch_end: [on_fit_epoch_end], # fit train val on_model_save: [on_model_save], on_train_end: [on_train_end], on_params_update: [on_params_update], teardown: [teardown], # Run in validator —— 4 个验证事件 on_val_start: [on_val_start], on_val_batch_start: [on_val_batch_start], on_val_batch_end: [on_val_batch_end], on_val_end: [on_val_end], # Run in predictor —— 5 个预测事件 on_predict_start: [on_predict_start], on_predict_batch_start: [on_predict_batch_start], on_predict_postprocess_end: [on_predict_postprocess_end], on_predict_batch_end: [on_predict_batch_end], on_predict_end: [on_predict_end], # Run in exporter —— 2 个导出事件 on_export_start: [on_export_start], on_export_end: [on_export_end], }为什么值是“列表”每个事件名下挂一个函数列表而非单个函数意味着同一事件允许挂载多个回调并按注册顺序依次执行。这正是一开始 base 空实现、后续集成模块再追加实现的基础。值为什么是空实现函数default_callbacks中默认挂载的就是 base.py 里那些空函数因此不注册任何集成时的默认行为等价于“事件存在但什么都不做”。可见该注册表的主要价值是为引擎提供一份稳定的“合法事件集合”并为用户注册与三方集成提供挂载点。五、get_default_callbacks()返回安全的深拷贝def get_default_callbacks(): return defaultdict(list, deepcopy(default_callbacks))get_default_callbacks()base.py返回一个defaultdict(list, ...)用deepcopy深拷贝default_callbacks避免调用方增删回调时污染模块级字典这正是 API 参考中Examples所示用法的安全性保证外层包成defaultdict(list)当查询未注册的事件名时自动返回空列表而不是抛KeyError。该函数与default_callbacks的关系可理解为前者是后者的“只读模板”后者是所有宿主实例初始状态的唯一来源。在引擎中如何被消费engine/trainer.py 中BaseTrainer.__init__会尽早初始化回调字典# Callbacks - initialize early so on_pretrain_routine_start can capture original args.data self.callbacks _callbacks or callbacks.get_default_callbacks()即训练器支持通过构造参数_callbacks注入自定义初始回调表测试代码中亦有该注入模式否则使用get_default_callbacks()的深拷贝。随后引擎在训练、验证、预测、导出各引擎类中都实现了统一形态的三个方法源码可分别在 trainer.py、validator.py、predictor.py、exporter.py 中找到def add_callback(self, event: str, callback): Append the given callback to the events callback list. self.callbacks[event].append(callback) def set_callback(self, event: str, callback): Override the existing callbacks with the given callback for the specified event. self.callbacks[event] [callback] def run_callbacks(self, event: str): Run all existing callbacks associated with a particular event. for callback in self.callbacks.get(event, []): callback(self)add_callback追加到事件回调列表末尾不动默认项set_callback整体替换该事件下的回调为指定单个函数run_callbacks取出事件对应列表并逐个以宿主自身为参数调用——这也是所有事件钩子最终执行的统一入口。测试用例 tests/test_engine.py 中对四类宿主分别验证了注册闭环exporter.add_callback(on_export_start, test_func) assert test_func in exporter.callbacks[on_export_start] # 导出 trainer.add_callback(on_train_start, test_func) assert test_func in trainer.callbacks[on_train_start] # 训练 val.add_callback(on_val_start, test_func) assert test_func in val.callbacks[on_val_start] # 验证 pred.add_callback(on_predict_start, test_func) assert test_func in pred.callbacks[on_predict_start] # 预测六、add_integration_callbacks()内置集成如何挂载def add_integration_callbacks(instance): from ultralytics.utils.events import callbacks as events_cb callbacks_list [events_cb] if Trainer in instance.__class__.__name__: from .clearml import callbacks as clear_cb from .comet import callbacks as comet_cb from .dvc import callbacks as dvc_cb from .mlflow import callbacks as mlflow_cb from .platform import callbacks as platform_cb from .raytune import callbacks as tune_cb from .tensorboard import callbacks as tb_cb from .wb import callbacks as wb_cb callbacks_list.extend([platform_cb, clear_cb, comet_cb, dvc_cb, mlflow_cb, tune_cb, tb_cb, wb_cb]) for callbacks in callbacks_list: for k, v in callbacks.items(): if v not in instance.callbacks[k]: instance.callbacks[k].append(v)该函数base.py是所有宿主实例获得“增强回调”的必经之路行为要点每个实例都会获得事件统计回调从 ultralytics/utils/events.py 导入callbacks字典并挂载。该模块的匿名事件统计含限速与队列挂载在 4 个事件上见 events.pyon_train_end训练结束后、最终指标就绪时上报一次训练事件on_val_start仅在validator.args.mode val独立验证时上报避免与训练内嵌验证重复on_predict_end单张图速度信息就绪后上报预测事件on_export_start上报导出事件。仅训练器额外获得平台与实验日志回调通过Trainer in instance.__class__.__name__判断宿主类型注意是子串匹配DetectionTrainer、SegmentationTrainer等子类同样命中随后动态导入并追加来自clearml、comet、dvc、mlflow、platform、raytune、tensorboard、wb这 8 个模块各自的callbacks字典。这些模块位于 utils/callbacks 目录下分别对应用户可选装的第三方 MLOps/实验管理平台。去重追加if v not in instance.callbacks[k]保证同一函数只挂一次不会因重复初始化而叠加执行。调用时机BaseTrainer.__init__中在get_dataset()前执行callbacks.add_integration_callbacks(self)trainer.py验证器、预测器、导出器则在各自初始化阶段挂载从各引擎构造函数中对run_callbacks(on_*_start)的调用可推断宿主必然在触发首事件前完成挂载。七、面向用户的三种自定义方式虽然 base.py 只提供空实现但正是这套“事件清单”支撑了用户自定义。三种典型途径途径 1在 Model 层面注册最常用通过 engine/model.py 中Model的三方法直接操作回调表add_callback(event, func)把自定义函数追加到某事件model.pyclear_callback(event)把某事件回调列表清空含框架默认项需谨慎见 model.pyreset_callbacks()把全部事件恢复为default_callbacks中的默认函数清除此前所有自定义项model.py。最简示例——训练开始时打印提示from ultralytics import YOLO def on_train_start(trainer): print(Training is starting!) model YOLO(yolo26n.pt) model.add_callback(on_train_start, on_train_start) model.train(datacoco8.yaml, epochs3)由于model.train()最终把回调表交给BaseTrainer的_callbacks参数这些注册会在训练会话中生效。clear_callback与reset_callbacks的还原语义在测试 tests/test_python.py 中也有覆盖。途径 2在引擎实例层面注册对已构建的Trainer/Validator/Predictor/Exporter实例直接调用各自的add_callback(event, func)四个引擎类均有同名方法适用于在自定义训练器内部或集成代码中临时追加钩子。途径 3给默认回调表中的空函数“填空”直接覆写 base.py 的默认函数使所有使用默认回调表的实例都获得行为。做法是先get_default_callbacks()拿到副本修改后作为_callbacks注入或仿照集成模块把自己的callbacks字典经add_integration_callbacks挂入。自定义回调的设计要点回调应尽可能轻量训练 batch 级事件on_train_batch_start/on_train_batch_end在每 batch 都会触发重逻辑会显著拖慢训练注意数据可用性差异on_train_epoch_end早于验证此时无验证指标on_fit_epoch_end晚于验证且有trainer.metricson_model_save仅在权重落盘后触发on_train_end在最终评估后触发利用宿主对象取上下文如trainer.best_fitness、trainer.loss_names、trainer.metrics、trainer.tloss官方on_model_save示例即打印这些字段、predictor.results、predictor.args等一个事件可挂多个函数add_callback只追加不覆盖需要整体替换时使用引擎的set_callback或先clear_callback。八、总结一张图看懂回调子系统base.py本模块 ├── 25 个空实现事件函数四组生命周期的事件声明 ├── default_callbacks # 事件名 → [默认空实现] 的注册表模板 ├── get_default_callbacks() # deepcopy 成 defaultdict(list)供引擎实例初始化 └── add_integration_callbacks(instance) ├── events匿名统计on_train_end / on_val_start / on_predict_end / on_export_start └── Trainer 额外获得platform / clearml / comet / dvc / mlflow / raytune / tensorboard / wb 引擎侧trainer / validator / predictor / exporter └── run_callbacks(event) → for cb in self.callbacks[event]: cb(self) 自定义侧 └── model.add_callback / clear_callback / reset_callbacks核心结论base.py的价值不在于函数实现它们全部为空而在于它定义了整套回调系统的契约——合法事件名、签名约定、默认注册表与集成入口。理解它就掌握了向 Ultralytics 训练/验证/预测/导出流程中任意阶段注入自定义逻辑的“接线图”而真正的行为扩展则通过add_callback挂载用户函数、通过add_integration_callbacks挂载内置的第三方平台集成来实现。想要更系统地了解全部回调与可访问属性可进一步阅读 docs/en/usage/callbacks.md 及各引擎类的 API 参考。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考