Transformers Trainer 超参数搜索完全指南从 Optuna、Ray Tune 到 WB 的实战与源码解析【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers本指南以 Transformers 官方文档 docs/source/ja/hpo_train.md英文原版见 docs/source/en/hpo_train.md为骨架系统讲解如何利用Trainer.hyperparameter_search在 Transformers 生态中自动搜索学习率、batch size 等超参数。你将掌握三种搜索后端Optuna、Ray Tune、WB的接入方式、多目标优化、DDP 分布式下的搜索机制并深入Trainer、hyperparameter_search.py、integrations/integration_utils.py与trainer_utils.py源码理解搜索流程的底层调用链。Trainer 超参数搜索机制概览Trainer是 Transformers 提供的统一训练接口源码位于 src/transformers/trainer.py它封装了训练循环、评估、日志、断点续训等能力让你无需手写训练循环。在此基础上Trainer还内置了一套完整的超参数搜索Hyperparameter SearchAPI每个 trial试验开始时通过model_init重新初始化一个全新的模型保证每次试验都从相同的初始权重出发不受前一次试验的状态污染从hp_space定义的搜索空间中采样一组新的超参数以这组超参数执行一次完整的训练循环训练结束后将compute_objective计算出的目标值上报给搜索后端后端依据该目标值指导下一轮试验的采样方向全部 trial 完成后返回最佳超参数组合封装在BestRun中返回给调用方。整个过程的关键入口是Trainer.hyperparameter_search方法src/transformers/trainer.py#L4285-L4364。从源码可以看到它的参数包括hp_space定义搜索空间的函数默认使用各后端内置的默认搜索空间compute_objective根据评估指标计算目标值的函数默认使用default_compute_objectiven_trials试验次数源码默认 100文档示例通常用 20/30directionminimize或maximize也支持列表形式实现多目标优化backendoptuna/ray/wandbhp_name为每个 trial 命名**kwargs透传给各后端运行器的额外参数如 Optuna 的timeout、n_jobsRay 的resources_per_trial等。方法内部会先解析后端然后调用ALL_HYPERPARAMETER_SEARCH_BACKENDS[backend]()获取对应的后端实例并执行ensure_available()检查依赖随后校验model_init是否存在最后调用backend_obj.run(self, n_trials, direction, **kwargs)完成搜索。安装搜索后端使用hyperparameter_search前必须先安装至少一个搜索后端。官方文档给出了三种安装方式任选其一即可pip install optuna pip install wandb pip install ray[tune]从 src/transformers/hyperparameter_search.py 的HyperParamSearchBackendBase可以看出后端注册表ALL_HYPERPARAMETER_SEARCH_BACKENDS包含三个实现类OptunaBackend、RayTuneBackend和WandbBackend。当你不显式指定backend时default_hp_search_backend()会从已安装的后端中按注册顺序optuna → ray → wandb挑选第一个可用的作为默认值若一个都没装则抛出RuntimeError并提示对应的pip install命令。用 model_init 为每次试验初始化全新模型超参数搜索的核心前提是每个 trial 都要从一个全新的模型开始训练以避免把上一次试验的优化器状态、权重更新等残留信息带进新的试验。为此Trainer要求你必须提供model_init函数而不是直接传入model。官方文档强调model与model_init不能同时传入否则Trainer会直接报错。from transformers import AutoModelForCausalLM def model_init(trial): return AutoModelForCausalLM.from_pretrained(Qwen/Qwen3-0.6B) trainer Trainer( model_initmodel_init, argsargs, train_datasettrain_dataset, eval_dataseteval_dataset, )model_init的调用逻辑在Trainer.call_model_initsrc/transformers/trainer.py#L4366-L4379中它会先通过number_of_arguments检查model_init的入参个数——0 个参数则直接调用self.model_init()1 个参数则把trial传进去这让你可以在model_init内部读取 trial 建议的超参数来构造模型例如调整中间层维度超过 1 个参数则抛出RuntimeError。同时若函数返回None也会报错。此外文档特别提醒hyperparameter_search与optimizers参数不兼容。如果需要自定义优化器/学习率调度器必须子类化Trainer并重写create_optimizer_and_scheduler方法见 src/transformers/trainer.py#L4300-L4307 的警告提示。定义搜索空间三种后端的不同写法搜索空间由hp_space函数定义不同后端要求不同的格式。若完全不定义hp_spaceTrainer会使用后端的默认搜索空间。以 Optuna 为例其默认空间定义在default_hp_space_optunasrc/transformers/trainer_utils.py#L452-L462覆盖learning_rate1e-6~1e-4对数均匀分布和per_device_train_batch_size候选值[4, 8, 16, 32, 64]Ray 的默认空间default_hp_space_ray与之等价WB 的默认空间定义在default_hp_space_wandb。OptunaOptuna 是一款轻量级超参数优化框架其搜索空间使用trial.suggest_*系列方法定义def optuna_hp_space(trial): return { learning_rate: trial.suggest_float(learning_rate, 1e-6, 1e-4, logTrue), per_device_train_batch_size: trial.suggest_categorical(per_device_train_batch_size, [16, 32, 64, 128]), }trial.suggest_float在区间内按对数均匀logTrue采样学习率trial.suggest_categorical从离散候选中选择 batch size。搜索空间不仅限于这两个参数——任何TrainingArguments中存在的字段都可以作为 key 写入如num_train_epochs、warmup_ratio、weight_decay等。Ray TuneRay Tune 是可扩展的调参库支持把 trial 分布到多台机器上执行。其搜索空间使用ray.tune的采样 APIfrom ray import tune def ray_hp_space(trial): return { learning_rate: tune.loguniform(1e-6, 1e-4), per_device_train_batch_size: tune.choice([16, 32, 64, 128]), }tune.loguniform对应对数均匀分布tune.choice对应离散取值。ray_hp_space中的参数trial实际上是被忽略的Ray 通过tune.run的config注入参数。Weights BiasesWBWB 是集成了超参数搜索Sweeps的实验跟踪平台支持贝叶斯、随机、网格等搜索策略。其搜索空间是一个 WB Sweep 配置字典而非采样函数def wandb_hp_space(trial): return { method: random, metric: {name: objective, goal: minimize}, parameters: { learning_rate: {distribution: uniform, min: 1e-6, max: 1e-4}, per_device_train_batch_size: {values: [16, 32, 64, 128]}, }, }注意这里的metric.name必须与上报的目标键名一致——Trainer会在评估后把compute_objective的结果写入metrics[objective]见下文_report_to_hp_search源码因此 WB 配置中的metric.name通常就是objective。构造 Trainer 并运行搜索带 model_init 的完整 Trainer 构造官方文档日文版给出了一个完整的构造示例其中model_init根据trial从预训练 checkpoint 初始化分类模型def model_init(trial): return AutoModelForSequenceClassification.from_pretrained( model_args.model_name_or_path, from_tfbool(.ckpt in model_args.model_name_or_path), configconfig, cache_dirmodel_args.cache_dir, revisionmodel_args.model_revision, ) trainer Trainer( modelNone, argstraining_args, train_datasetsmall_train_dataset, eval_datasetsmall_eval_dataset, compute_metricscompute_metrics, processing_classtokenizer, model_initmodel_init, data_collatordata_collator, )关键点在于modelNonemodel_initmodel_init这样每次 trial 都会由model_init重新实例化模型。单目标搜索compute_objective 与方向compute_objective决定优化的目标函数。如果不显式提供Trainer会使用default_compute_objectivesrc/transformers/trainer_utils.py#L431-L449其逻辑是从评估指标中剔除eval_loss、epoch以及*_runtime、*_per_second等速度类指标若剔除后没有其他指标则返回eval_loss作为目标值否则返回所有剩余指标值的总和。官方文档提醒这个总和回退逻辑并不可控建议显式传入compute_objective以避免依赖隐式行为。例如只关注验证损失def compute_objective(metrics): return metrics[eval_loss] best_run trainer.hyperparameter_search( hp_spacehp_space, compute_objectivecompute_objective, n_trials30, # 运行多少个 trial directionminimize, # 或 maximize如 accuracy/F1 这类越高越好的指标 backendoptuna, # optuna / ray / wandb )directionminimize表示目标越小越好典型如验证损失directionmaximize表示越大越好典型如 accuracy、F1。搜索结果封装在BestRunsrc/transformers/trainer_utils.py#L409-L428中返回它是一个NamedTuple包含run_id最佳 trial 的 ID若保存了模型对应 checkpoint 位于以run-{run_id}结尾的目录objective该 trial 取得的目标值hyperparameters产生该目标值的超参数组合字典run_summary可选Ray 后端为ray.tune.ExperimentAnalysis对象。best_run trainer.hyperparameter_search(...) best_run.objective # 0.38最佳 eval loss best_run.hyperparameters # {learning_rate: 5e-5, num_train_epochs: 4, ...}拿到best_run后把best_run.hyperparameters中的取值写入TrainingArguments再在全量数据集上重新训练即可。多目标搜索Pareto FrontOptuna 支持多目标优化Multi-objective HPO。你可以在hyperparameter_search中传入direction列表每个目标对应一个minimize/maximize并自定义返回多个目标值的compute_objectivebest_trials trainer.hyperparameter_search( direction[minimize, maximize], backendoptuna, hp_spaceoptuna_hp_space, n_trials20, compute_objectivecompute_objective, )此时返回值不再是单个BestRun而是 Pareto Front 上的最优解集合list[BestRun]。仓库测试 tests/trainer/test_trainer_hyperparameter.py#L84-L134 中的TrainerHyperParameterMultiObjectOptunaIntegrationTest就是这一用法的官方验证它定义了一个同时返回eval_loss与eval_accuracy的compute_objective并以direction[minimize, maximize]发起搜索。注意多目标搜索仅在 Optuna 后端得到验证支持测试类前标注了require_optuna。每个 trial 的超参数如何生效Trainer在每次 trial 训练前调用_hp_search_setupsrc/transformers/trainer.py#L4381-L4433将采样到的参数写入训练配置它从hp_space(trial)Optuna或 trial 字典Ray/WB中取出参数逐个通过setattr(self.args, key, value)写入TrainingArguments并在原值存在时做一次类型强制转换value type(old_attr)(value)若 key 不存在于TrainingArguments则记录警告并跳过。该函数还会处理 DeepSpeed 场景下的配置重建对args.deepspeed有强制要求并重新计算_train_batch_size后重建 Accelerator。训练中的指标上报与剪枝在训练/评估过程中Trainer通过_report_to_hp_searchsrc/transformers/trainer.py#L4435-L4460向后端实时上报中间指标Optuna调用trial.report(objective, step)上报每一步目标值若trial.should_prune()返回 True早期指标明显劣于其他 trial则触发提前终止并抛出optuna.TrialPruned实现 Trial 剪枝Pruning节省算力Ray Tune把objective写入metrics后调用ray.tune.report(metrics, checkpointcheckpoint)并在control.should_save时通过_tune_save_checkpoint保存模型、优化器、调度器与 trainer state 的 checkpoint供 Ray 在恢复/对比时使用WB目标值同样写入metrics[objective]用于 Sweep 统计。DDP 分布式训练下的超参数搜索官方文档特别说明目前针对 DDPDistributed Data Parallel的超参数搜索仅对Optuna后端启用其机制是只有 rank 0 进程生成搜索 trial并把采样参数广播给其他 rank。从源码 src/transformers/integrations/integration_utils.py#L235-L297 的run_hp_search_optuna可以看出整个 Optuna study 的创建与optimize只发生在trainer.args.process_index 0的进程上其他 rank 的进程则执行trainer.train()并配合trainer.objective的同步来完成分布式训练。因此使用 Optuna 时hp_space、compute_objective等在 rank 0 定义即可搜索逻辑天然避免多进程重复采样导致的重复试验若在 DDP 场景下使用其他后端Ray Tune、WB需要自行处理 trial 参数在多 rank 间的同步问题文档未承诺开箱即用。分布式下的最佳实践是把per_device_train_batch_size等按设备的参数放入搜索空间同时用TrainingArguments的per_device_train_batch_size×n_gpu语义理解实际全局 batch size源码在 src/transformers/trainer.py#L4431 处注释了train_batch_size在 HPO 下可能变化的问题并引用 PR #18918 说明该字段需要随 trial 重新计算。完整调用链总结结合源码一次trainer.hyperparameter_search(...)的完整调用链如下hyperparameter_search() # src/transformers/trainer.py#L4285 ├─ default_hp_search_backend() # 选择已安装的默认后端 ├─ ALL_HYPERPARAMETER_SEARCH_BACKENDS[backend]() # src/transformers/hyperparameter_search.py │ ├─ OptunaBackend / RayTuneBackend / WandbBackend ├─ backend_obj.ensure_available() # 校验依赖是否安装 ├─ 校验 model_init 是否提供否则 RuntimeError └─ backend_obj.run(trainer, n_trials, direction, **kwargs) ├─ optuna: run_hp_search_optuna # src/transformers/integrations/integration_utils.py#L235 │ └─ 每轮 trial: call_model_init() → train() → _hp_search_setup() → _report_to_hp_search() │ └─ trial.report / TrialPruned剪枝 ├─ ray: run_hp_search_ray # 同上 #L300 │ └─ ray.tune.report(metrics, checkpoint...)含 checkpoint 保存 └─ wandb: run_hp_search_wandb # 同上 #L444 └─ WB Sweep agent 驱动 trial └─ 返回 BestRun单目标或 list[BestRun]多目标 Pareto Front单目标搜索默认n_trials20文档示例至n_trials100源码默认值不等实际操作时建议根据算力预算权衡trial 越多越有可能逼近最优解但训练总耗时线性增长。合理利用 Optuna 的剪枝与 Ray Tune 的并行调度可以显著压缩搜索时间成本。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Transformers Trainer 超参数搜索完全指南：从 Optuna、Ray Tune 到 WB 的实战与源码解析
Transformers Trainer 超参数搜索完全指南从 Optuna、Ray Tune 到 WB 的实战与源码解析【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers本指南以 Transformers 官方文档 docs/source/ja/hpo_train.md英文原版见 docs/source/en/hpo_train.md为骨架系统讲解如何利用Trainer.hyperparameter_search在 Transformers 生态中自动搜索学习率、batch size 等超参数。你将掌握三种搜索后端Optuna、Ray Tune、WB的接入方式、多目标优化、DDP 分布式下的搜索机制并深入Trainer、hyperparameter_search.py、integrations/integration_utils.py与trainer_utils.py源码理解搜索流程的底层调用链。Trainer 超参数搜索机制概览Trainer是 Transformers 提供的统一训练接口源码位于 src/transformers/trainer.py它封装了训练循环、评估、日志、断点续训等能力让你无需手写训练循环。在此基础上Trainer还内置了一套完整的超参数搜索Hyperparameter SearchAPI每个 trial试验开始时通过model_init重新初始化一个全新的模型保证每次试验都从相同的初始权重出发不受前一次试验的状态污染从hp_space定义的搜索空间中采样一组新的超参数以这组超参数执行一次完整的训练循环训练结束后将compute_objective计算出的目标值上报给搜索后端后端依据该目标值指导下一轮试验的采样方向全部 trial 完成后返回最佳超参数组合封装在BestRun中返回给调用方。整个过程的关键入口是Trainer.hyperparameter_search方法src/transformers/trainer.py#L4285-L4364。从源码可以看到它的参数包括hp_space定义搜索空间的函数默认使用各后端内置的默认搜索空间compute_objective根据评估指标计算目标值的函数默认使用default_compute_objectiven_trials试验次数源码默认 100文档示例通常用 20/30directionminimize或maximize也支持列表形式实现多目标优化backendoptuna/ray/wandbhp_name为每个 trial 命名**kwargs透传给各后端运行器的额外参数如 Optuna 的timeout、n_jobsRay 的resources_per_trial等。方法内部会先解析后端然后调用ALL_HYPERPARAMETER_SEARCH_BACKENDS[backend]()获取对应的后端实例并执行ensure_available()检查依赖随后校验model_init是否存在最后调用backend_obj.run(self, n_trials, direction, **kwargs)完成搜索。安装搜索后端使用hyperparameter_search前必须先安装至少一个搜索后端。官方文档给出了三种安装方式任选其一即可pip install optuna pip install wandb pip install ray[tune]从 src/transformers/hyperparameter_search.py 的HyperParamSearchBackendBase可以看出后端注册表ALL_HYPERPARAMETER_SEARCH_BACKENDS包含三个实现类OptunaBackend、RayTuneBackend和WandbBackend。当你不显式指定backend时default_hp_search_backend()会从已安装的后端中按注册顺序optuna → ray → wandb挑选第一个可用的作为默认值若一个都没装则抛出RuntimeError并提示对应的pip install命令。用 model_init 为每次试验初始化全新模型超参数搜索的核心前提是每个 trial 都要从一个全新的模型开始训练以避免把上一次试验的优化器状态、权重更新等残留信息带进新的试验。为此Trainer要求你必须提供model_init函数而不是直接传入model。官方文档强调model与model_init不能同时传入否则Trainer会直接报错。from transformers import AutoModelForCausalLM def model_init(trial): return AutoModelForCausalLM.from_pretrained(Qwen/Qwen3-0.6B) trainer Trainer( model_initmodel_init, argsargs, train_datasettrain_dataset, eval_dataseteval_dataset, )model_init的调用逻辑在Trainer.call_model_initsrc/transformers/trainer.py#L4366-L4379中它会先通过number_of_arguments检查model_init的入参个数——0 个参数则直接调用self.model_init()1 个参数则把trial传进去这让你可以在model_init内部读取 trial 建议的超参数来构造模型例如调整中间层维度超过 1 个参数则抛出RuntimeError。同时若函数返回None也会报错。此外文档特别提醒hyperparameter_search与optimizers参数不兼容。如果需要自定义优化器/学习率调度器必须子类化Trainer并重写create_optimizer_and_scheduler方法见 src/transformers/trainer.py#L4300-L4307 的警告提示。定义搜索空间三种后端的不同写法搜索空间由hp_space函数定义不同后端要求不同的格式。若完全不定义hp_spaceTrainer会使用后端的默认搜索空间。以 Optuna 为例其默认空间定义在default_hp_space_optunasrc/transformers/trainer_utils.py#L452-L462覆盖learning_rate1e-6~1e-4对数均匀分布和per_device_train_batch_size候选值[4, 8, 16, 32, 64]Ray 的默认空间default_hp_space_ray与之等价WB 的默认空间定义在default_hp_space_wandb。OptunaOptuna 是一款轻量级超参数优化框架其搜索空间使用trial.suggest_*系列方法定义def optuna_hp_space(trial): return { learning_rate: trial.suggest_float(learning_rate, 1e-6, 1e-4, logTrue), per_device_train_batch_size: trial.suggest_categorical(per_device_train_batch_size, [16, 32, 64, 128]), }trial.suggest_float在区间内按对数均匀logTrue采样学习率trial.suggest_categorical从离散候选中选择 batch size。搜索空间不仅限于这两个参数——任何TrainingArguments中存在的字段都可以作为 key 写入如num_train_epochs、warmup_ratio、weight_decay等。Ray TuneRay Tune 是可扩展的调参库支持把 trial 分布到多台机器上执行。其搜索空间使用ray.tune的采样 APIfrom ray import tune def ray_hp_space(trial): return { learning_rate: tune.loguniform(1e-6, 1e-4), per_device_train_batch_size: tune.choice([16, 32, 64, 128]), }tune.loguniform对应对数均匀分布tune.choice对应离散取值。ray_hp_space中的参数trial实际上是被忽略的Ray 通过tune.run的config注入参数。Weights BiasesWBWB 是集成了超参数搜索Sweeps的实验跟踪平台支持贝叶斯、随机、网格等搜索策略。其搜索空间是一个 WB Sweep 配置字典而非采样函数def wandb_hp_space(trial): return { method: random, metric: {name: objective, goal: minimize}, parameters: { learning_rate: {distribution: uniform, min: 1e-6, max: 1e-4}, per_device_train_batch_size: {values: [16, 32, 64, 128]}, }, }注意这里的metric.name必须与上报的目标键名一致——Trainer会在评估后把compute_objective的结果写入metrics[objective]见下文_report_to_hp_search源码因此 WB 配置中的metric.name通常就是objective。构造 Trainer 并运行搜索带 model_init 的完整 Trainer 构造官方文档日文版给出了一个完整的构造示例其中model_init根据trial从预训练 checkpoint 初始化分类模型def model_init(trial): return AutoModelForSequenceClassification.from_pretrained( model_args.model_name_or_path, from_tfbool(.ckpt in model_args.model_name_or_path), configconfig, cache_dirmodel_args.cache_dir, revisionmodel_args.model_revision, ) trainer Trainer( modelNone, argstraining_args, train_datasetsmall_train_dataset, eval_datasetsmall_eval_dataset, compute_metricscompute_metrics, processing_classtokenizer, model_initmodel_init, data_collatordata_collator, )关键点在于modelNonemodel_initmodel_init这样每次 trial 都会由model_init重新实例化模型。单目标搜索compute_objective 与方向compute_objective决定优化的目标函数。如果不显式提供Trainer会使用default_compute_objectivesrc/transformers/trainer_utils.py#L431-L449其逻辑是从评估指标中剔除eval_loss、epoch以及*_runtime、*_per_second等速度类指标若剔除后没有其他指标则返回eval_loss作为目标值否则返回所有剩余指标值的总和。官方文档提醒这个总和回退逻辑并不可控建议显式传入compute_objective以避免依赖隐式行为。例如只关注验证损失def compute_objective(metrics): return metrics[eval_loss] best_run trainer.hyperparameter_search( hp_spacehp_space, compute_objectivecompute_objective, n_trials30, # 运行多少个 trial directionminimize, # 或 maximize如 accuracy/F1 这类越高越好的指标 backendoptuna, # optuna / ray / wandb )directionminimize表示目标越小越好典型如验证损失directionmaximize表示越大越好典型如 accuracy、F1。搜索结果封装在BestRunsrc/transformers/trainer_utils.py#L409-L428中返回它是一个NamedTuple包含run_id最佳 trial 的 ID若保存了模型对应 checkpoint 位于以run-{run_id}结尾的目录objective该 trial 取得的目标值hyperparameters产生该目标值的超参数组合字典run_summary可选Ray 后端为ray.tune.ExperimentAnalysis对象。best_run trainer.hyperparameter_search(...) best_run.objective # 0.38最佳 eval loss best_run.hyperparameters # {learning_rate: 5e-5, num_train_epochs: 4, ...}拿到best_run后把best_run.hyperparameters中的取值写入TrainingArguments再在全量数据集上重新训练即可。多目标搜索Pareto FrontOptuna 支持多目标优化Multi-objective HPO。你可以在hyperparameter_search中传入direction列表每个目标对应一个minimize/maximize并自定义返回多个目标值的compute_objectivebest_trials trainer.hyperparameter_search( direction[minimize, maximize], backendoptuna, hp_spaceoptuna_hp_space, n_trials20, compute_objectivecompute_objective, )此时返回值不再是单个BestRun而是 Pareto Front 上的最优解集合list[BestRun]。仓库测试 tests/trainer/test_trainer_hyperparameter.py#L84-L134 中的TrainerHyperParameterMultiObjectOptunaIntegrationTest就是这一用法的官方验证它定义了一个同时返回eval_loss与eval_accuracy的compute_objective并以direction[minimize, maximize]发起搜索。注意多目标搜索仅在 Optuna 后端得到验证支持测试类前标注了require_optuna。每个 trial 的超参数如何生效Trainer在每次 trial 训练前调用_hp_search_setupsrc/transformers/trainer.py#L4381-L4433将采样到的参数写入训练配置它从hp_space(trial)Optuna或 trial 字典Ray/WB中取出参数逐个通过setattr(self.args, key, value)写入TrainingArguments并在原值存在时做一次类型强制转换value type(old_attr)(value)若 key 不存在于TrainingArguments则记录警告并跳过。该函数还会处理 DeepSpeed 场景下的配置重建对args.deepspeed有强制要求并重新计算_train_batch_size后重建 Accelerator。训练中的指标上报与剪枝在训练/评估过程中Trainer通过_report_to_hp_searchsrc/transformers/trainer.py#L4435-L4460向后端实时上报中间指标Optuna调用trial.report(objective, step)上报每一步目标值若trial.should_prune()返回 True早期指标明显劣于其他 trial则触发提前终止并抛出optuna.TrialPruned实现 Trial 剪枝Pruning节省算力Ray Tune把objective写入metrics后调用ray.tune.report(metrics, checkpointcheckpoint)并在control.should_save时通过_tune_save_checkpoint保存模型、优化器、调度器与 trainer state 的 checkpoint供 Ray 在恢复/对比时使用WB目标值同样写入metrics[objective]用于 Sweep 统计。DDP 分布式训练下的超参数搜索官方文档特别说明目前针对 DDPDistributed Data Parallel的超参数搜索仅对Optuna后端启用其机制是只有 rank 0 进程生成搜索 trial并把采样参数广播给其他 rank。从源码 src/transformers/integrations/integration_utils.py#L235-L297 的run_hp_search_optuna可以看出整个 Optuna study 的创建与optimize只发生在trainer.args.process_index 0的进程上其他 rank 的进程则执行trainer.train()并配合trainer.objective的同步来完成分布式训练。因此使用 Optuna 时hp_space、compute_objective等在 rank 0 定义即可搜索逻辑天然避免多进程重复采样导致的重复试验若在 DDP 场景下使用其他后端Ray Tune、WB需要自行处理 trial 参数在多 rank 间的同步问题文档未承诺开箱即用。分布式下的最佳实践是把per_device_train_batch_size等按设备的参数放入搜索空间同时用TrainingArguments的per_device_train_batch_size×n_gpu语义理解实际全局 batch size源码在 src/transformers/trainer.py#L4431 处注释了train_batch_size在 HPO 下可能变化的问题并引用 PR #18918 说明该字段需要随 trial 重新计算。完整调用链总结结合源码一次trainer.hyperparameter_search(...)的完整调用链如下hyperparameter_search() # src/transformers/trainer.py#L4285 ├─ default_hp_search_backend() # 选择已安装的默认后端 ├─ ALL_HYPERPARAMETER_SEARCH_BACKENDS[backend]() # src/transformers/hyperparameter_search.py │ ├─ OptunaBackend / RayTuneBackend / WandbBackend ├─ backend_obj.ensure_available() # 校验依赖是否安装 ├─ 校验 model_init 是否提供否则 RuntimeError └─ backend_obj.run(trainer, n_trials, direction, **kwargs) ├─ optuna: run_hp_search_optuna # src/transformers/integrations/integration_utils.py#L235 │ └─ 每轮 trial: call_model_init() → train() → _hp_search_setup() → _report_to_hp_search() │ └─ trial.report / TrialPruned剪枝 ├─ ray: run_hp_search_ray # 同上 #L300 │ └─ ray.tune.report(metrics, checkpoint...)含 checkpoint 保存 └─ wandb: run_hp_search_wandb # 同上 #L444 └─ WB Sweep agent 驱动 trial └─ 返回 BestRun单目标或 list[BestRun]多目标 Pareto Front单目标搜索默认n_trials20文档示例至n_trials100源码默认值不等实际操作时建议根据算力预算权衡trial 越多越有可能逼近最优解但训练总耗时线性增长。合理利用 Optuna 的剪枝与 Ray Tune 的并行调度可以显著压缩搜索时间成本。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考