使用 Trainer API 进行超参数搜索Transformers 内置 HPO 实战指南【免费下载链接】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 的Trainer类为中心讲解如何利用其内置的hyperparameter_searchAPI 接入 Optuna、Ray Tune 与 Weights Biaseswandb三种超参数搜索后端自动完成多轮试验trial并返回最优参数组合。读完本文你将掌握从定义搜索空间、编写model_init到发起搜索、解读BestRun结果的完整闭环并了解其在 DDP 分布式微调场景下的工作方式。超参数搜索的工作原理超参数搜索的核心思路是为每一轮试验采样一组超参数训练一个全新初始化的模型将评估结果作为目标值objective反馈给搜索后端由后端算法决定下一轮采样方向最终返回表现最优的那组参数。在 Transformers 中这一流程由Trainer.hyperparameter_search驱动包含四个关键步骤每轮试验开始时通过model_init初始化一个全新模型避免继承上一轮训练的状态按hp_space定义的搜索空间采样一组新的超参数使用Trainer运行完整训练循环并评估将目标值上报给搜索后端所有试验结束后最优超参数封装在BestRun中返回定义见 trainer_utils.py。从源码看hyperparameter_search的签名提供了hp_space、compute_objective、n_trials、direction、backend和hp_name等可配置项其中n_trials默认 20、direction默认minimize。在进入正文前需要强调一个前提要使用超参数搜索必须在创建Trainer时通过model_init传入模型初始化函数否则hyperparameter_search会直接抛出RuntimeError对应源码校验逻辑见 trainer.py。支持的搜索后端与安装Trainer目前支持三种超参数搜索后端通过backend参数以字符串形式指定后端字符串取值特点Optunaoptuna轻量级超参数优化框架支持 TPE、随机采样等算法与剪枝pruningRay Tuneray可扩展的调参库支持跨机器分布式执行多轮试验Weights Biaseswandb实验追踪平台内置 Sweeps支持贝叶斯、随机、网格等搜索策略使用前需按需安装对应依赖pip install optuna pip install wandb pip install ray[tune]从源码可以确认后端枚举定义在 trainer_utils.py 中HPSearchBackend.OPTUNA optuna、HPSearchBackend.RAY ray、HPSearchBackend.WANDB wandb。hyperparameter_search会通过default_hp_search_backend()自动探测已安装的后端若未显式指定backend优先使用已安装的 Optuna 或 Ray Tune若两者都已安装则默认 Optuna见 trainer.py。定义搜索空间不同后端对搜索空间的格式要求不同因此需要为每种后端编写对应的hp_space函数它接收一个trial对象并返回超参数字典。函数中返回的键名必须是TrainingArguments中真实存在的字段如learning_rate、per_device_train_batch_size否则会在训练启动时被跳过并打印警告——这是源码_hp_search_setup中的实际校验逻辑。Optuna 后端Optuna 的trial对象提供了suggest_float、suggest_categorical、suggest_int等采样方法 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]), ... }logTrue表示在对数尺度上均匀采样学习率适合跨度大的连续参数suggest_categorical则用于从离散候选中取值。Ray Tune 后端Ray Tune 使用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用于离散选择。使用时需先from ray import tune。Weights Biases 后端wandb 的 Sweeps 使用完整的配置字典描述搜索策略、优化目标与参数分布 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]}, ... }, ... }method可设为random、bayes、grid等metric.name必须与上报到 wandb 的目标指标名保持一致默认上报的指标名为objective因此配置中通常也指向它。不传hp_space时怎么办源码为三种后端都提供了默认搜索空间见 trainer_utils.pyOptuna 默认搜索learning_rate1e-6~1e-4对数、num_train_epochs1~5、seed1~40、per_device_train_batch_size[4, 8, 16, 32, 64]Ray Tune 与 wandb 的默认空间与之等价。这为你快速起步提供了开箱即用的兜底方案。通过 model_init 初始化模型每轮试验都必须从一个全新的模型开始避免上一轮试验的训练状态残留。model_init函数在每轮试验开始时被调用返回一个新的模型实例从而保证所有试验从相同的初始权重出发。 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, ... )关于model_init的实现细节call_model_init显示它会根据函数参数个数决定调用方式——0 个参数时直接调用model_init()1 个参数时传入当前trial这样可以在函数内读取trial的采样值来调整模型结构例如按试验动态选择隐藏层维度多于 1 个参数或返回None都会抛出RuntimeError。重要约束model与model_init不能同时传给Trainer同时传入会触发错误另外由于每轮试验需要重建优化器与调度器hyperparameter_search与optimizers参数不兼容如需自定义优化器/调度器应子类化Trainer并覆写create_optimizer_and_scheduler方法见 trainer.py 的警告说明。创建 Trainer 并发起搜索组装 Trainer将model_init函数、训练参数、训练/评估数据集以及评估函数一并传入Trainer trainer Trainer( ... modelNone, ... argstraining_args, ... train_datasetsmall_train_dataset, ... eval_datasetsmall_eval_dataset, ... compute_metricscompute_metrics, ... processing_classtokenizer, ... model_initmodel_init, ... data_collatordata_collator, ... )注意这里modelNone因为模型将由model_init按试验创建。调用 hyperparameter_search调用搜索并获取最优试验参数 best_trial trainer.hyperparameter_search( ... directionmaximize, ... backendoptuna, ... hp_spaceoptuna_hp_space, ... n_trials20, ... compute_objectivecompute_objective, ... )各参数含义backend取optuna、wandb或ray之一决定使用的搜索后端direction取minimize或maximize决定目标值是求最小如验证损失还是求最大如准确率、F1n_trials运行的试验轮数hp_space搜索空间函数不传则使用后端默认空间compute_objective自定义目标函数不传则使用默认实现。此外还支持hp_name定义试验/运行命名函数以及各后端专属的kwargsOptuna 接受timeout、n_jobs、gc_after_trial及optuna.study.create_study的参数Ray 接受tune.run的参数其中resources_per_trial未设置时默认使用 1 个 CPU 核和 1 块 GPU若可用见 trainer.py。目标函数 compute_objective你可以自定义compute_objective它接收evaluate返回的指标字典返回一个标量作为优化目标。若未定义则使用默认实现default_compute_objective其逻辑为若指标中只有eval_loss没有其他评估指标则直接返回eval_loss作为目标值若存在其他评估指标如eval_f1、eval_accuracy则返回所有指标值的总和会剔除epoch、*_runtime、*_per_second等速度类指标避免干扰目标值。需要说明的是韩文版文档描述默认目标为“f1 等评估指标之和”而英文版与当前源码实现更精确有 eval_loss 且无其他指标时默认目标就是 eval_loss否则才是指标之和。建议显式传入compute_objective以明确优化目标避免依赖兜底逻辑例如 def compute_objective(metrics): ... return metrics[eval_loss]读取搜索结果hyperparameter_search返回BestRun它是一个具名元组包含run_id最优试验的 ID若保存了模型对应 checkpoint 位于以run-{run_id}结尾的目录中objective该次试验取得的目标值float多目标优化时为list[float]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, ...}拿到最优参数后将其写入TrainingArguments再在完整数据集上重新训练即可。每轮试验在 Trainer 内部如何落地理解底层执行细节有助于排错与扩展。搜索过程中每轮试验都会触发两条关键内部路径均在 trainer.py 中_hp_search_setup在每轮试验开始前调用负责把采样到的超参数写回TrainingArguments。对 Optuna 后端它先调用hp_space(trial)得到参数字典对 Ray 与 wandb 后端参数直接来自trial。随后逐项检查键名是否存在于TrainingArguments不存在则告警跳过存在则按原字段类型做类型转换后写回setattr。若启用了 DeepSpeed还会重建 DeepSpeed 配置并重置 Accelerator 状态以适应变化的批大小等参数。_report_to_hp_search在每个评估节点把中间指标上报给后端。对 Optuna它调用trial.report(objective, step)并支持trial.should_prune()剪枝——即提前判定该试验无望时触发optuna.TrialPruned终止训练节省算力对 Ray Tune则通过ray.tune.report(metrics, checkpointcheckpoint)上报且当TrainerControl.should_save为真时会保存模型、优化器与调度器检查点见_tune_save_checkpoint实现试验中途断点续调。DDP 分布式微调下的超参数搜索对于 DDPDistributed Data Parallelism分布式数据并行场景当前仓库的实现中仅 Optuna 后端支持超参数搜索。工作方式是由顶层rank 0主进程发起并驱动整个超参数搜索过程再把选定的超参数结果传递给其他进程从而保证多卡环境下参数一致、试验有序进行参见韩文版文档 hpo_train.md 的 DDP 小节。在分布式环境中使用model_init时请确保初始化逻辑在各进程间可复现避免采样结果不一致。完整流程小结安装搜索后端依赖optuna/wandb/ray[tune]按需选择其一编写hp_space(trial)定义搜索空间或省略以使用默认空间编写model_init(trial)返回全新模型并传入Trainer注意勿同时传model可选编写compute_objective(metrics)明确优化目标调用trainer.hyperparameter_search(...)通过best_run.hyperparameters读取最优参数将最优参数写入TrainingArguments在完整数据集上重训并评估。除了本文档韩文版与英文版你还可以在仓库的 examples 中查看基于Trainer的完整文本分类微调示例配合Trainer与 trainer_utils.py 的源码进一步验证搜索空间、默认目标函数与BestRun的实际行为。【免费下载链接】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），仅供参考