PyTorch Lightning 1.5 到 2.0 升级完整指南从 Trainer 参数重构到 Strategy 架构迁移【免费下载链接】pytorch-lightningPretrain, finetune ANY AI model of ANY size on 1 or 10,000 GPUs with zero code changes.项目地址: https://gitcode.com/gh_mirrors/py/pytorch-lightning本文基于 from_1_5.rst 及 upgrade/sections 目录下全部章节1_5_*、1_6_*、1_7_*、1_8_*、1_9_*共 15 个分节系统梳理 PyTorch Lightning 从 1.5 升级到 2.0 的全部破坏性变更。升级横跨 1.5 → 1.6 → 1.7 → 1.8 → 1.9 → 2.0 六个版本段覆盖普通用户Regular、高级用户Advanced与开发者Developer三个层次从 Trainer 构造参数gpus、auto_lr_find、resume_from_checkpoint等的废弃替换到Plugin → Strategy架构重命名、Callback钩子细化拆分再到训练循环 API 的收敛与 Fabric 的替代迁移。读完本文你可以对照 If/Then 迁移表逐项完成代码改造理解每一项变更背后的架构动机并能在当前仓库源码中定位对应的新 API 实现。升级全景三阶段路线与三类读者从 1.5 升级到 2.0 并非一次性跳跃而是连续经历 1.6、1.7、1.8、1.9 四个中间版本每个版本都会引入一批废弃deprecation与移除removal。官方文档将升级对象划分为三个群体本文按此结构展开读者群体覆盖章节关注重点普通用户Regular User1_5_regular至1_9_regularTrainer 标志位、回调参数、接口重命名的直接替换高级用户Advanced User1_5_advanced至1_9_advanced钩子Hook、插件Plugin、策略Strategy层面的架构迁移开发者Developer1_5_devel至1_9_devel内部类、工具函数、基类与 mixin 的移除与替换三个层次存在清晰递进关系普通用户只需完成参数改名级别的机械替换高级用户需要理解回调钩子的新调用语义开发者则面对内部 API 的重组如Trainer.call_hook被拆分为多个受保护方法。建议先对照普通用户章节完成可运行性修复再逐层处理架构性问题。Regular UserTrainer 参数与回调的机械迁移普通用户面对的绝大多数变更都是一个参数换另一个参数。下面按版本顺序给出完整对照。1.5 → 1.6Dataloader 与回调参数改名dataloaders 参数统一PR7431原来trainer.fit(train_dataloaders...)、trainer.validate(val_dataloaders...)现在统一为trainer.fit(dataloaders...)、trainer.validate(dataloaders...)。当前源码中 trainer.py 的fit签名即统一接收dataloaders参数。DDP 插件参数移交 TrainerPR7026DDPPlugin/DDPSpawnPlugin不再接收num_nodes与sync_batchnorm这两个值由 Trainer 统一管理后传入策略。回调参数强制化与改名EarlyStopping的monitor变为必填参数PR7907不能再依赖默认值ModelCheckpoint的every_n_val_epochs改名为every_n_epochsPR8383。当前源码 model_checkpoint.py 中every_n_epochs表示间隔多少 epoch 保存一次检查点。Trainer 标志位替换reload_dataloaders_every_epoch→reload_dataloaders_every_n_epochsPR5043distributed_backend→strategyPR8575例如distributed_backendddp改为strategyddp。1.6 → 1.7监控、日志与进度条组件化1.6 的核心趋势是把原本内嵌在 Trainer 里的功能拆成独立 Callback。旧 Trainer 标志位新用法变更说明terminate_on_nandetect_anomaly改由 autograd 引擎检测异常PR9175weights_summaryModelSummary回调 max_depth摘要由回调控制PR9699checkpoint_callbackenable_checkpointing为True时自动配置默认ModelCheckpointPR9754stochastic_weight_avgStochasticWeightAveraging回调直接加入callbacks[...]列表PR8989flush_logs_every_n_steps传给 logger 初始化参数是否支持取决于具体 loggerPR9366log_gpu_memory/gpu_metricsDeviceStatsMonitor回调统一设备监控PR9921progress_bar_refresh_rateProgressBar回调的refresh_rate或enable_progress_barFalse关闭PR9616max_steps 语义修正PR9460Trainer(max_stepsNone)不再有任何效果需要显式传max_steps-1也是默认值来关闭步数上限。resume_from_checkpoint 移入 fitPR9693Trainer(resume_from_checkpoint...)改为trainer.fit(ckpt_path...)。当前源码中fit的ckpt_path参数支持普通路径也支持best、last、hpc、registry等特殊值见 trainer.py。模块级 API 迁移LightningModule.summarize()→pl.utilities.model_summary.summarize(model)PR8513LightningModule.model_size→pl.utilities.memory.get_model_size_mb(model)PR8495on_train_dataloader()/on_val_dataloader()/on_test_dataloader()/on_predict_dataloader()四个钩子全部移除直接用train_dataloader/val_dataloader/test_dataloader/predict_dataloaderPR9098on_keyboard_interrupt钩子 →on_exception钩子并指定异常类型PR9260TestTubeLogger移除改用TensorBoardLogger等 loggerPR9065ProgressBar基类 →TQDMProgressBar参数一致PR10134GPUStatsMonitor/XLAStatsMonitor→DeviceStatsMonitorPR9924。1.7 → 1.8Logger、DataModule 与 Trainer 属性收敛Logger 管理简化PR12147不再需要LoggerCollection包装多个 logger直接向 Trainer 传 logger 列表通过trainer.loggers访问。学习率调度器配置PR11443Trainer.lr_schedulers→trainer.lr_scheduler_configs返回 dataclass 而非字典。DataModule 钩子改名PR11887on_save→on_save_checkpointon_load→on_load_checkpoint。HPC 专用钩子合并PR14315on_hpc_load/on_hpc_save合并进通用钩子on_load_checkpoint/on_save_checkpoint。权重保存路径PR14424Trainer(weights_save_path...)改为在ModelCheckpoint回调中直接设置dirpathTrainer.weights_save_path属性一并删除。当前源码 model_checkpoint.py 明确dirpath指定保存目录并提示分布式环境建议显式提供以避免竞态。LightningCLI 参数PR12804seed_everything_defaultNone→False。导入路径调整pl.core.lightning→pl.core.modulePR12740Trainer.reset_train_val_dataloaders()→Trainer.fit_loop.setup_data()PR12184。1.8 → 1.9设备参数统一与 Tuner 解耦环境要求抬升1.9Python 需 3.8PR16579PyTorch 需 1.11PR16492。设备参数全面统一为devicesPR16171 / PR16184旧 Trainer 标志位新写法gpus2devices2tpu_cores8devices8ipus4devices4num_processes4devices4auto_select_gpusTruedevicesautopl.tuner.auto_gpu_select.pick_single_gpu/pick_multiple_gpusdevicesauto累积梯度调度器独立PR16729accumulate_grad_batches传字典的调度方式 → 使用GradientAccumulationScheduler回调。Tuner 与 Trainer 解耦Trainer.auto_lr_find、Trainer.auto_scale_batch_size及Trainer.tune()全部移除改用独立Tuner对象或LearningRateFinder/BatchSizeFinder回调相关说明见 tuner 目录下的文档与 tuner 源码。其他替换resume_from_checkpointTrainer 标志位第二次提及→Trainer.fit(ckpt_path...)PR10061profiler 导入路径pl.profiler→pl.profilersPR16359。Advanced User钩子、插件与策略层的架构迁移高级用户的变更触及 Lightning 的扩展机制理解这些迁移有助于把握 2.0 的架构走向插件Plugin让位于策略Strategy通用钩子细化为阶段专用钩子优化器控制权交还给用户manual optimization。1.5 → 1.6日志与 DataModule 内部细节self.log(sync_dist_op...)→self.log(reduce_fx...)仍支持mean但也可传可调用对象PR7891pytorch_lightning.utilities.model_helper.is_overridden参数model→instancePR7918training_step返回值不再自动.detach()需手动调用PR7994pl.utilities.distributed.rank_zero_warn→pl.utilities.rank_zero.rank_zero_warnDataModule 的has_prepared_data、has_setup_fit、has_setup_validate、has_setup_test、has_setup_predict、has_teardown_fit等 10 个生命周期属性全部移除数据生命周期由用户在自定义方法中管理PR7657DDPPlugin.task_idx→DDPStrategy.local_rankPR8203Trainer.disable_validation→not Trainer.enable_validationPR8291。1.6 → 1.7分布式与进度条 API 迁移prepare_data_per_node从 Trainer 参数改为DataHooks的属性在LightningModule/LightningDataModule中访问PR8958process_position→ 自定义ProgressBar回调的process_position参数PR9222LightningModule中的分布式工具方法add_to_queue/get_from_queue→DDPStrategy(start_methodspawn)的同名方法PR9118LightningModule.get_progress_bar_dict→pl.callbacks.progress.base.get_standard_metrics(module.trainer)PR9118Trainer.progress_bar_dict→ProgressBarBase.get_metricsLightningModule.on_post_move_to_device移除参数绑定parameter tying自动完成PR9525相关实现见 params_tyingLightningDistributed移除逻辑并入DDPStrategy(start_method...)PR9691Accelerator 上的集合通信 APIbarrier、broadcast、all_gather→ 直接调用Strategy的对应方法PR9677pytorch_lightning.core.decorators.parameter_validation→pytorch_lightning.utilities.params_tying.set_shared_parametersPR9525LearningRateMonitor.lr_sch_names→LearningRateMonitor.lrs.keys()PR10066旧DataModule的train_transforms、val_transforms、test_transforms、size、dims→ 迁移到LightningDataModulePR8851。1.7 → 1.8Plugin 到 Strategy 的大规模重命名这一阶段完成了 Lightning 1.x 后期最重要的架构正名——TrainingTypePlugin 体系全面更名为 Strategy 体系DDP2Strategy→DDPStrategyPR14026Trainer.training_type_plugin→Trainer.strategyPR11141所有*Plugin类 → 对应*Strategy类PR11120DistributedType→ 受保护的_StrategyTypePR10505DeviceType→ 受保护的_AcceleratorTypePR10503pl.utilities.meta函数 → 改用 torchdistx 内置支持PR13868。Callback 钩子全面细化PR14834通用钩子被拆分到具体阶段旧通用钩子新阶段专用钩子on_configure_sharded_modelsetupon_before_accelerator_backend_setupsetupon_batch_starton_train_batch_starton_batch_endon_train_batch_endon_epoch_starton_train_epoch_start/on_validation_epoch_start/on_test_epoch_starton_pretrain_routine_{start,end}on_fit_starton_init_start/on_init_endon_train_startTrainer 设备属性统一Trainer.num_processes、Trainer.gpus、Trainer.num_gpus、Trainer.ipus、Trainer.tpu_cores→ 全部由Trainer.num_devices取代PR12384-12437。检查点相关收敛Trainer.validated_ckpt_path/tested_ckpt_path/predicted_ckpt_path→ 统一只读属性Trainer.ckpt_path在validate/test/predict(ckpt_path...)加载时被设置PR11696Callback.on_save_checkpoint的返回值不再使用改为直接调用Callback.state_dictPR11887。logger API 简化PR11832 / PR11871agg_and_log_metrics→log_metricsagg_key_funcs/agg_default_func参数移除指标需显式记录。其他移除LightningIPUModule移除PR14830。1.8 → 1.9DP 弃用、FSDP 原生化与手动优化DataParallelDP与dp策略弃用PR16748strategydp需改用strategyddp或 DeepSpeedLightningParallelModule与相关 wrapper 一并弃用详见 1.9 devel 章节。epoch_end 钩子改名PR16520training_epoch_end/validation_epoch_end/test_epoch_end→on_train_epoch_end/on_validation_epoch_end/on_test_epoch_end。CombinedLoader 统一PR16800multiple_trainloader_mode→CombinedLoader(..., mode...)直接设置 mode。梯度与指标控制权移交move_metrics_to_cpu→ 在自定义 metric 或 torchmetrics 中实现 offload 逻辑PR16358track_grad_norm→ 覆写on_before_optimizer_step并直接传参配合LightningModule.log_grad_norm()PR16745replace_sampler_ddp→use_distributed_sampler且采样器不再只针对 DDP 策略创建当前源码见 trainer.py。混合精度统一到 PyTorch 原生 AMPPR16039using_native_amp、amp_backend、amp_level三个标志位/属性全部移除Apex 集成弃用统一使用torch.amp相关文档见 precision。FairScale 与 Sharded 系列迁移到原生 FSDPPR16400LightningShardedDataParallel、FullyShardedNativeMixedPrecisionPlugin、ShardedNativeMixedPrecisionPlugin、DDPFullyShardedStrategy、DDPShardedStrategy、DDPSpawnShardedStrategy全部替换为 PyTorch 原生 FSDP。手动优化接管优化器控制PR16537-16539PR16172以下 API 全部要求迁移到 manual optimization见 manual_optimizationLightningModule.optimizer_step中的on_tpu、using_lbfgs参数所有钩子中的optimizer_idx参数training_step、on_before_optimizer_step、configure_gradient_clipping、optimizer_step、optimizer_zero_grad、lr_scheduler_step、backwardconfigure_optimizers返回字典中声明的 optimizer 频率Trainer.optimizer_frequencies属性BaseFinetuning.finetune_function中的opt_idxTBPTTtruncated_bptt_steps、tbptt_split_batch、向training_step传hidden。批量级钩子职责收窄PR16791training_step_end/validation_step_end/test_step_end只保留 DP 输出的归约逻辑其余逻辑迁移到on_train_batch_end/on_validation_batch_end/on_test_batch_end。其他关键变更PL_INTER_BATCH_PARALLELISM环境变量移除PR16355Horovod、ColossalAI 集成移出主仓库改为独立包安装QuantizationAwareTraining回调移除直接用 PyTorch 原生量化PR16750DDPSpawnStrategy→DDPStrategy(start_methodspawn)PR16809进度条不再自动显示training_steploss 的滑动平均改用self.log(loss, ..., prog_barTrue)PR16192on_predict_epoch_end的outputs参数 →trainer.predict_loop.predictionsPR16655self.log()不再接受字典需逐个传入PR16389LightningCLI的save_config_overwrite/save_config_multifile→ 通过save_config_kwargs字典传递PR14998。Developer内部 API 重构与工具函数迁移开发者章节涉及 Lightning 内部实现细节若你依赖过以下 API需要同步调整。1.5 → 1.6内部结构与命名CheckpointConnector.hpc_load()→CheckpointConnector.restore()PR7652TrainerModelHooksMixin→ 使用 signature_utils 中的工具函数PR7422Trainer.train_loop→Trainer.fit_loopPR8025LightningModule.loaded_optimizer_states_dict属性移除PR8229。1.6 → 1.7Logger、Precision 与 ClusterEnvironmentLightningLoggerBase.close/LoggerCollection.close→finalizePR9422AcceleratorConnector.is_slurm_managing_tasks、configure_slurm_ddp设为受保护并建议不要直接使用PR10101ClusterEnvironment.creates_children()方法 → 属性creates_processes_externallyPR10106PrecisionPlugin.master_params()→main_params()PR10105。1.7 → 1.8Trainer 基类与钩子分发重构Trainer.get_deprecated_arg_names()移除PR14415Trainer.run_stage→ 按用途调用Trainer.{fit,validate,test,predict}PR11000rank 工具函数统一到pl.utilities.rank_zerorank_zero_only、rank_zero_debug、rank_zero_info、rank_zero_warn、rank_zero_deprecation、LightningDeprecationWarningPR11747Trainer.data_parallel_device_ids→Trainer.device_idsPR12072TrainerCallbackHookMixin→ 直接使用 Trainer 基类PR14401BaseProfiler→ProfilerPR12150分布式后端环境变量PL_TORCH_DISTRIBUTED_BACKEND→ 策略构造器的process_group_backend参数PR11745PrecisionPlugin.on_load_checkpoint/on_save_checkpoint→load_state_dictPR11978Trainer.root_gpu→Trainer.strategy.root_device.indexPR12262Trainer.use_amp/LightningModule.use_amp移除统一依赖 Torch 原生 AMPPR12312/12315Trainer.verbose_evaluate→EvaluationLoop(verbose...)PR10931Trainer.should_rank_save_checkpoint移除PR11068TrainerOptimizersMixin→ core/optimizer.pyPR11155TrainerDataLoadingMixin→ Trainer 与DataConnector的方法PR11282Trainer.lightning_optimizers→Strategy及其属性PR11444Trainer.call_hook→ 拆分为受保护方法_call_callback_hooks、_call_lightning_module_hook、_call_ttp_hook、_call_accelerator_hook不再对外使用PR10979SimpleProfiler.profile_iterable/AdvancedProfiler.profile_iterable移除PR12102on_train_batch_end(outputs, ...)的 outputs 维度从(n_optimizers, tbptt_steps)调整为(tbptt_steps, n_optimizers)可通过给钩子加new_formatTrue参数平滑过渡PR12182training_epoch_end(outputs)同理从(n_optimizers, n_batches, tbptt_steps)调整为(n_batches, tbptt_steps, n_optimizers)。1.8 → 1.9基类重构与工具函数移除基类统一PR12014 / PR12150 / PR12106自定义 logger 基类pytorch_lightning.loggers.base.LightningLoggerBase→pytorch_lightning.loggers.logger.Logger自定义 profiler 基类pytorch_lightning.profiler.base.BaseProfiler/AbstractProfiler→pytorch_lightning.profilers.profiler.Profiler。分布式 wrapper 收敛到 DDP/DeepSpeedPR16386 / PR16748pl_module参数改为必填的forward_moduleLightningDistributedModule、unwrap_lightning_module、DataParallelLightningParallelModule均建议改用 DDP 或 DeepSpeed见 gpu_expert。精度插件合并PR16039ApexMixedPrecisionPlugin弃用NativeMixedPrecisionPlugin改名为MixedPrecisionPlugin。工具函数与模块的迁移/移除fit_loop.min_steps/max_stepssetter → 用 Fabric 实现自定义训练循环PR16803Trainer.data_parallel属性 →isinstance(trainer.strategy, ParallelStrategy)PR16703pl.utilities.xla_device→pl.accelerators.XLAAccelerator.is_available()PR14514/14550pl.utilities.device_parser.*→lightning_fabric.utilities.device_parser.*PR14492/14753pl.utilities.cloud_io.*→lightning_fabric.utilities.cloud_io.*PR14515pl.utilities.apply_func.*→lightning_utilities.core.apply_func.*PR14516/14537pl.core.mixins→ 使用基类PR16424pl.utilities.distributed→ PyTorch 原生函数PR16390pl.utilities.data、pl.utilities.optimizer、pl.utilities.seed整体移除PR16440/16439/16422pl.utilities.finite_checks.print_nan_gradients/detect_nan_parameters、pl.utilities.parsing.flatten_dict、pl.utilities.metrics.metrics_to_scalars、pl.utilities.memory.get_model_size_mb、pl.strategies.utils.on_colab_kaggle移除AllGatherGradpl.utilities.distributed→ PyTorch 原生等价实现PR15364PL_RECONCILE_PROCESS1环境变量 → 自定义 loggerPR16204ModelIO.load_from_checkpointmixin → 依赖 core/module.py 的LightningModulePR16999Accelerator.setup_environment→Accelerator.setup_devicePR16436PL_FAULT_TOLERANT_TRAINING环境变量 → 用 Fabric 自行实现容错逻辑PR16516/16533IndexBatchSamplerWrapper设为受保护PR16826DataLoaderLoop、EvaluationEpochLoop、PredictionEpochLoop→ manual optimizationPR16726trainer.reset_*_dataloader()→ 顶层循环的Loop.setup_data()PR16726LightningModule.precision→ 使用 Trainer 的 precision 属性PR16203Trainer.modelsetter 移除模型改由fit/test/predict传入PR16462CombinedLoaderIterator→ 直接传入 dataloadersPR16714ProgressBarBase→pl.callbacks.progress.ProgressBarPR17058ProgressBarBase.train_batch_idx/val_batch_idx/test_batch_idx/predict_batch_idx→ 依赖 Trainer 内部循环的属性PR16760Trainer.prediction_writer_callbacks→ 依赖 precision pluginPR16759PrecisionPlugin.dispatch/Strategy.dispatch移除PR16618。argparse 体系整体迁移到 LightningCLIPR16708LightningDataModule.add_argparse_args/parse_argparser/from_argparse_args/get_init_arguments_and_types、Trainer.default_attributes/from_argparse_args/parse_argparser/match_env_arguments/add_argparse_args、以及pl.utilities.argparse与pl.utilities.parsing下的全部函数统一替换为LightningCLI文档见 lightning_cli。典型迁移案例三段式改造示例将以上规则落到实际代码以最常见的 1.5 代码为例展示完整改造路径改造前1.5 风格from pytorch_lightning import Trainer from pytorch_lightning.callbacks import EarlyStopping, ModelCheckpoint trainer Trainer( gpus2, distributed_backendddp, weights_summaryfull, checkpoint_callbackTrue, resume_from_checkpointlast.ckpt, terminate_on_nanTrue, flush_logs_every_n_steps50, ) trainer.fit(model, train_dataloaderstrain_loader, val_dataloadersval_loader)改造后2.0 风格from lightning.pytorch import Trainer from lightning.pytorch.callbacks import EarlyStopping, ModelCheckpoint checkpoint_callback ModelCheckpoint(dirpathcheckpoints/, every_n_epochs1) trainer Trainer( devices2, strategyddp, enable_model_summaryTrue, enable_checkpointingTrue, detect_anomalyTrue, callbacks[ checkpoint_callback, EarlyStopping(monitorval_loss), ], ) trainer.fit(model, dataloaderstrain_loader, ckpt_pathlast.ckpt)改造要点对照gpus2distributed_backendddp→devices2strategyddpresume_from_checkpoint→fit(ckpt_path...)weights_summary/terminate_on_nan/checkpoint_callback→enable_model_summary/detect_anomaly/enable_checkpointing 显式回调EarlyStopping必须显式提供monitordataloaders 参数统一为dataloaders。当前仓库的 examples/pytorch 目录提供了大量 2.0 风格的完整可运行示例如 basics 下的 autoencoder.py可作为迁移后的参考实现。迁移自检清单升级完成后建议对照以下清单逐项自检全部可在本仓库源码中验证所有 dataloader 相关调用统一为dataloaders参数trainer.pygpus/tpu_cores/num_processes等设备参数全部替换为devices断点续训统一走fit/validate/test/predict(ckpt_path...)检查点目录通过ModelCheckpoint(dirpath...)指定model_checkpoint.py学习率查找与批量大小缩放使用LearningRateFinder/BatchSizeFinder回调或独立Tuner所有*Plugin引用改为*Strategy所有通用 Callback 钩子按阶段拆分为on_train_*/on_validation_*/on_test_*混合精度统一使用torch.amp无 Apex /amp_backend/amp_level残留涉及多优化器的代码已迁移到 manual optimization自定义 logger / profiler 继承新的基类Logger/Profiler无pl.utilities.argparse、pl.utilities.data等已移除工具函数引用。延伸阅读升级总入口from_1_5.rst迁移细则分布在 sections 目录的1_5_*~1_9_*共 15 个文件中手动优化manual_optimization.rst混合精度precision.rstFSDP 相关gpu_expert.rstLightningCLI 替代 argparselightning_cli.rst2.0 迁移总览migration_guide.rst。【免费下载链接】pytorch-lightningPretrain, finetune ANY AI model of ANY size on 1 or 10,000 GPUs with zero code changes.项目地址: https://gitcode.com/gh_mirrors/py/pytorch-lightning创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考