callbacks.py
utils\callbacks.py
目录
1.所需的库和模块
import threading2.class Callbacks:
# 这段代码定义了一个名为 Callbacks 的类，它用于管理和执行在训练过程中的不同阶段调用的回调函数。
class Callbacks:
# 处理 YOLOv5 Hooks 的所有已注册回调。
""""
Handles all registered callbacks for YOLOv5 Hooks
"""
# 这段代码是 Callbacks 类的构造函数 __init__ 的定义，它初始化类的实例变量。
# 这是类的构造函数，当创建 Callbacks 类的新实例时会自动调用。
def __init__(self):
# Define the available callbacks 定义可用的回调。
# 初始化一个名为 _callbacks 的实例变量，它是一个字典，用于存储不同训练阶段的回调函数列表。
# 字典的键是字符串，代表不同的训练阶段或事件（例如 'on_train_start' , 'on_train_batch_end' 等）。
# 字典的值是列表，每个列表用于存储对应事件的回调函数。
self._callbacks = {
# 在预训练例程开始时触发。
'on_pretrain_routine_start': [],
# 在预训练例程结束时触发。
'on_pretrain_routine_end': [],
# 在训练开始时触发。
'on_train_start': [],
# 在每个训练周期（epoch）开始时触发。
'on_train_epoch_start': [],
# 在每个训练批次（batch）开始时触发。
'on_train_batch_start': [],
# 在优化器执行一步更新后触发。
'optimizer_step': [],
# 在梯度归零之前触发。
'on_before_zero_grad': [],
# 在每个训练批次结束时触发。
'on_train_batch_end': [],
# 在每个训练周期结束时触发。
'on_train_epoch_end': [],
# 在验证开始时触发。
'on_val_start': [],
# 在每个验证批次开始时触发。
'on_val_batch_start': [],
# 在每个验证图像处理结束时触发（通常用于实时数据增强）。
'on_val_image_end': [],
# 在每个验证批次结束时触发。
'on_val_batch_end': [],
# 在验证结束时触发。
'on_val_end': [],
# 在每个训练和验证周期结束时触发（ fit 通常指一个完整的训练和验证周期）。
'on_fit_epoch_end': [], # fit = train + val
# 在模型保存时触发。
'on_model_save': [],
# 在训练结束时触发。
'on_train_end': [],
# 在模型参数更新时触发。
'on_params_update': [],
# 在训练流程完全结束时触发，用于清理资源。
'teardown': [],}
# 初始化一个名为 stop_training 的实例变量，它是一个布尔值，用于控制训练过程是否应该提前终止。 如果这个变量被设置为 True ，则可以在训练过程中的任何点中断训练。
self.stop_training = False # set True to interrupt training
# 这个构造函数定义了 Callbacks 类的基本结构，使其能够注册、存储和执行训练过程中的各种回调函数。这些回调函数可以用于执行多种任务，例如记录训练进度、评估模型性能、保存模型状态等。通过这种方式， Callbacks 类提供了一种灵活的机制来扩展和自定义训练流程。
# 这段代码是 Callbacks 类的 register_action 方法的定义，它用于向特定的回调钩子（hook）注册一个新的回调函数。
# 这是 Callbacks 类的一个方法，定义了如何注册一个新的回调函数。
# 1.self : 指代类的当前实例。
# 2.hook : 要注册回调函数的钩子名称。
# 3.name : 回调函数的名称，这是一个可选参数，默认为空字符串。
# 4.callback : 实际的回调函数，这也是一个可选参数，默认为 None 。
def register_action(self, hook, name='', callback=None):
# 将新操作注册到回调钩子。
"""
Register a new action to a callback hook
Args:
hook: The callback hook name to register the action to
name: The name of the action for later reference
callback: The callback to fire
"""
# 这是一个断言，用于检查提供的 hook 是否存在于 self._callbacks 字典中。 如果 hook 不存在，将抛出一个 AssertionError ，并显示一个错误消息，指出未找到指定的钩子。
assert hook in self._callbacks, f"hook '{hook}' not found in callbacks {self._callbacks}" # 在回调 {self._callbacks} 中未找到钩子 '{hook}'。
# callable(object)
# 在Python中， callable() 函数用于检查一个对象是否可被调用，即是否是一个函数或者实现了 __call__ 方法的实例。如果对象是可调用的， callable() 返回 True ；否则返回 False 。
# 参数 ：
# object ：要检查是否可调用的对象。
# 返回值 :
# 如果 object 是可调用的，则返回 True 。 否则返回 False 。
# callable() 函数是Python内置的，不需要手动定义，它在 builtins 模块中，可以直接使用。
# 这是另一个断言，用于检查提供的 callback 是否是一个可调用的对象（例如函数）。 如果 callback 不是可调用的，将抛出一个 AssertionError ，并显示一个错误消息，指出回调不可调用。
assert callable(callback), f"callback '{callback}' is not callable" # 回调‘{callback}’不可调用。
# 如果上述检查通过，这行代码将新的回调函数添加到 self._callbacks 字典中对应钩子的列表里。 每个回调函数被存储为一个字典，包含 name 和 callback 两个键。
self._callbacks[hook].append({'name': name, 'callback': callback})
# 这个方法使得用户可以在训练的不同阶段（如每个批次开始、每个批次结束等）注册自定义的回调函数，从而允许在这些特定时刻执行特定的操作。通过这种方式， Callbacks 类提供了一种灵活的机制来扩展和自定义训练流程。
# 这段代码是 Callbacks 类的 get_registered_actions 方法的定义，它用于获取注册到特定钩子（hook）的所有回调函数，或者如果没有指定钩子，则返回所有注册的回调函数。
# 这是 Callbacks 类的一个方法，用于获取注册的回调函数。
# 1.self : 指代类的当前实例。
# 2.hook : 可选参数，指定要获取回调函数的钩子名称。如果为 None ，则返回所有钩子的回调函数。
def get_registered_actions(self, hook=None):
# 返回所有通过回调钩子注册的操作。
""""
Returns all the registered actions by callback hook
Args:
hook: The name of the hook to check, defaults to all
"""
# 这行代码是一个条件表达式，根据 hook 参数的值返回不同的结果。
# 如果 hook 参数被提供（即不是 None ），则返回 self._callbacks 字典中与该钩子关联的回调函数列表。
# 如果 hook 参数为 None ，则返回整个 self._callbacks 字典，其中包含了所有钩子及其关联的回调函数列表。
return self._callbacks[hook] if hook else self._callbacks
# 这个方法允许用户查询特定钩子的回调函数，或者获取所有钩子的回调函数列表，以便于进行进一步的处理或调试。
# 这段代码是 Callbacks 类的 run 方法的定义，它用于执行注册到特定钩子（hook）的所有回调函数。
# 这是 Callbacks 类的一个方法，用于触发并执行注册到特定钩子的回调函数。
# 1.self : 指代类的当前实例。
# 2.hook : 要触发的钩子名称。
# 3.*args : 传递给回调函数的位置参数，使用星号(*)表示可变数量。
# 4.thread : 一个布尔值参数，指示是否在新线程中执行回调函数，默认为 False 。
# 5.**kwargs : 传递给回调函数的关键字参数，使用双星号(**)表示可变数量。
def run(self, hook, *args, thread=False, **kwargs):
# 循环遍历已注册的操作并在主线程上触发所有回调。
"""
Loop through the registered actions and fire all callbacks on main thread
Args:
hook: The name of the hook to check, defaults to all
args: Arguments to receive from YOLOv5
thread: (boolean) Run callbacks in daemon thread
kwargs: Keyword Arguments to receive from YOLOv5
"""
# 这是一个断言，用于检查提供的 hook 是否存在于 self._callbacks 字典中。 如果 hook 不存在，将抛出一个 AssertionError ，并显示一个错误消息，指出未找到指定的钩子。
assert hook in self._callbacks, f"hook '{hook}' not found in callbacks {self._callbacks}" # 在回调 {self._callbacks} 中未找到钩子 '{hook}'。
# 遍历 self._callbacks 字典中与指定 hook 关联的回调函数列表。
for logger in self._callbacks[hook]:
# 检查 thread 参数是否为 True ，即是否需要在新线程中执行回调函数。
if thread:
# 如果 thread 为 True ，则为每个回调函数创建一个新的线程，并开始执行。
# target=logger['callback'] 指定线程执行的目标函数，即回调函数。 args=args 和 kwargs=kwargs 分别传递位置参数和关键字参数给回调函数。 daemon=True 表示该线程是守护线程，当主程序退出时，守护线程会自动结束。
threading.Thread(target=logger['callback'], args=args, kwargs=kwargs, daemon=True).start()
# 如果 thread 为 False ，则直接在当前线程中执行回调函数。 使用 *args 和 **kwargs 将位置参数和关键字参数传递给回调函数。
else:
logger['callback'](*args, **kwargs)
# 这个方法允许用户在训练的不同阶段触发执行注册的回调函数，可以选择在新线程中异步执行，或者在当前线程中同步执行。这种设计提高了训练流程的灵活性和可扩展性。
# 这个 Callbacks 类的设计允许用户在训练的不同阶段插入自定义的回调函数，以执行特定的操作，例如记录日志、保存模型、调整学习率等。这种设计提高了训练流程的灵活性和可扩展性。