回调和扩展

相关源文件

• src/transformers/hf_argparser.py
• src/transformers/modeling_attn_mask_utils.py
• src/transformers/modeling_utils.py
• src/transformers/safetensors_conversion.py
• src/transformers/testing_utils.py
• src/transformers/trainer.py
• src/transformers/trainer_callback.py
• src/transformers/trainer_pt_utils.py
• src/transformers/trainer_utils.py
• src/transformers/training_args.py
• src/transformers/utils/__init__.py
• src/transformers/utils/fx.py
• src/transformers/utils/import_utils.py
• src/transformers/utils/notebook.py
• tests/test_modeling_common.py
• tests/trainer/test_trainer.py
• tests/trainer/test_trainer_callback.py
• tests/utils/test_hf_argparser.py

本文档涵盖了 Transformers 训练基础设施中的回调和扩展系统。回调系统提供了一种灵活的机制，可以在不修改核心 Trainer 类的情况下，自定义训练行为、监控进度并与外部工具集成。有关核心 Trainer 类本身的信息，请参阅Trainer 类。有关训练配置的详细信息，请参阅训练参数。

核心回调架构

回调系统围绕几个关键组件构建，这些组件协同工作以提供可扩展的训练自定义功能

回调系统架构

CallbackHandler 作为中心协调器，管理 TrainerCallback 实例集合，并在特定的训练事件中编排它们的执行。每个回调都可以访问 TrainerState 进行监控，并访问 TrainerControl 来影响训练流程。

来源：src/transformers/trainer_callback.py80-89 src/transformers/trainer.py683-686

回调生命周期和事件

回调参与一个明确定义的生命周期，该生命周期与训练阶段相对应。系统在训练期间的预定点触发特定事件

训练期间的回调事件序列

回调事件为不同的训练阶段提供钩子

事件	目的	调用时机
on_init_end	初始化后设置	Trainer 初始化后
on_train_begin	训练启动逻辑	训练循环开始前
on_epoch_begin	轮次级初始化	每个轮次开始时
on_step_begin	步骤级设置	每个训练步骤前
on_pre_optimizer_step	优化前钩子	optimizer.step() 调用前
on_optimizer_step	优化后钩子	optimizer.step() 调用后
on_step_end	步骤级清理	每个训练步骤后
on_log	日志操作	满足日志记录条件时
on_evaluate	评估逻辑	触发评估时
on_save	检查点操作	满足保存条件时
on_epoch_end	轮次级清理	每个轮次结束时
on_train_end	训练结束	训练循环完成后

来源：src/transformers/trainer_callback.py35-79 src/transformers/trainer.py1815-1820

内置回调

Transformers 库提供了几个内置回调，用于处理常见的训练场景

核心回调

内置回调类型

DefaultFlowCallback

DefaultFlowCallback 处理核心训练流程逻辑，包括根据训练参数配置何时进行评估、日志记录和保存。

进度回调

进度回调在训练期间提供用户反馈

• ProgressCallback：用于终端环境的标准进度条
• NotebookProgressCallback：用于 Jupyter Notebooks 的增强进度显示，支持 HTML 格式

集成回调

集成回调将训练连接到外部监控和日志系统。这些回调会根据 TrainingArguments 中的 report_to 参数自动添加。

来源：src/transformers/trainer.py185-192 src/transformers/trainer_callback.py185-280 src/transformers/utils/notebook.py180-350

创建自定义回调

自定义回调扩展了 TrainerCallback 基类，并实现了特定的事件处理程序

基本自定义回调结构

回调状态管理

需要在训练会话之间持久化状态的回调可以实现 ExportableState 接口

有状态回调架构

有状态回调可以在检查点保存期间保存和恢复其内部状态，确保训练能够无缝恢复。

来源：src/transformers/trainer_callback.py95-120 tests/trainer/test_trainer_callback.py44-54

集成回调

集成回调提供了与外部工具和平台的无缝连接

集成回调加载

集成回调加载机制

集成回调会根据 TrainingArguments 中的 report_to 配置自动实例化并添加到回调处理器。这使得与外部监控系统能够无缝集成，无需手动管理回调。

集成回调特性

集成回调通常提供

• 自动将指标记录到外部系统
• 超参数跟踪
• 模型工件存储
• 训练可视化
• 实验比较功能

来源：src/transformers/integrations/__init__.py42-44 src/transformers/trainer.py681-682

回调控制流

回调可以通过 TrainerControl 对象影响训练执行

回调控制机制

TrainerControl 对象为回调提供了通过设置控制标志来修改训练行为的能力。主训练循环会检查这些标志，以确定何时执行特定操作。

控制标志用法

控制标志	效果	典型用例
should_training_stop	停止训练循环	提前停止，错误条件
should_evaluate	触发评估	自定义评估计划
should_log	触发日志记录	自定义日志记录间隔
should_save	触发检查点保存	自定义保存条件

来源：src/transformers/trainer_callback.py125-160 src/transformers/trainer.py1825-1850