人工智能深度学习机器学习预训练分布式训练微调【免费下载链接】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点击查看免费下载本文基于 PyTorch Lightning 仓库中的官方升级文档 1.4 高级用户迁移章节系统梳理从 1.3 升级到 1.4 时针对高级用户的 7 项破坏性 API 变更涉及模型检查点保存、sanity check 状态查询、梯度范数计算、NaN 检测与打印、指标展平、以及 GPU 选择语义的调整。读完本文你将掌握每一项变更的旧写法与新写法对照、迁移操作步骤以及新 API 在当前仓库源码中的真实实现与使用边界可据此安全、无痛地完成代码升级。适用前提本文面向使用 PyTorch Lightning 1.4及后续 1.x的高级用户——即那些直接调用了Trainer内部 Mixin、LightningModule工具方法或ModelCheckpoint私有属性的开发者。普通应用层用户若未使用这些内部接口通常无需改动。一、升级背景1.4 为何要动这些接口PyTorch Lightning 1.4 是一次以「内部 API 公共化、职责下沉」为方向的大版本。此前许多实用功能梯度范数、NaN 检测、指标展平、sanity check 状态查询散落在Trainer的各个 Mixin 类与LightningModule的方法中耦合度高、难以独立复用。1.4 将这些工具函数统一收编到lightning.pytorch.utilities工具包并把底层能力通过公开方法暴露如Trainer.save_checkpoint同时收紧Trainer(gpus...)的语义为后续 2.0 的大规模重构gpus被devices取代、旧属性彻底移除铺路。仓库的 CHANGELOG.md 中保留了完整的演进痕迹1.4 时代先对这些接口发起废弃deprecation并给出替代方案PR #7201、#4945、#7292、#6834、#7180、#6388后续版本再逐步移除例如 #9209 移除running_sanity_check、#8680 移除save_function。因此本文的迁移建议不仅适用于 1.4也适用于任何仍然可见这些旧 API 的 1.x 版本。二、变更总览表以下表格完整继承自 1_4_advanced.rst并补充了「变更类型」与「影响模块」两列便于快速定位If旧写法Then新写法RefPR变更类型影响模块calledModelCheckpoint.save_functionnow callTrainer.save_checkpointPR #7201方法迁移回调 / Traineraccessed theTrainer.running_sanity_checkpropertynow access theTrainer.sanity_checkingpropertyPR #4945属性重命名Trainer 状态usedLightningModule.grad_normnow use thepl.utilities.grad_normutility function insteadPR #7292方法 → 工具函数LightningModule / utilitiesusedTrainerTrainingTricksMixin.detect_nan_tensorsnow usepl.utilities.grads.grad_normPR #6834方法迁移Trainer Mixin / utilitiesusedTrainerTrainingTricksMixin.print_nan_gradientsnow usepl.utilities.finite_checks.print_nan_gradientsPR #6834方法迁移Trainer Mixin / utilitiesrelied onTrainerLoggingMixin.metrics_to_scalarsnow usepl.utilities.metrics.metrics_to_scalarsPR #7180方法迁移Trainer Mixin / utilitiesselected the i-th GPU withTrainer(gpusi,j)now this will set the number of GPUs, just like passingTrainer(devicesi); select specific GPU viaCUDA_VISIBLE_DEVICESi,jPR #6388语义收紧Trainer 参数下面逐项展开每一节都给出「迁移前 → 迁移后」的代码对照与源码级佐证。三、模型检查点保存从ModelCheckpoint.save_function到Trainer.save_checkpoint3.1 迁移内容在 1.4 之前高级用户若要自定义检查点保存逻辑常会覆写或调用ModelCheckpoint回调上的save_function属性。1.4 起该属性被废弃保存动作统一收敛到Trainer.save_checkpoint。迁移前1.3 及更早from pytorch_lightning.callbacks import ModelCheckpoint checkpoint_callback ModelCheckpoint(...) # 旧写法直接操作回调上的保存函数 checkpoint_callback.save_function(trainer, filepath)迁移后1.4from lightning.pytorch import Trainer trainer Trainer() # 新写法由 Trainer 统一触发保存例行流程 trainer.save_checkpoint(filepathmy/checkpoint/file.ckpt)3.2 源码佐证新 API 的完整调用链当前仓库中Trainer.save_checkpoint的实现位于 src/lightning/pytorch/trainer/trainer.py其签名与流程如下def save_checkpoint( self, filepath: _PATH, weights_only: Optional[bool] None, storage_options: Optional[Any] None ) - None: if self.model is None: raise AttributeError( Saving a checkpoint is only possible if a model is attached to the Trainer. Did you call Trainer.save_checkpoint() before calling Trainer.{fit,validate,test,predict}? ) with self.profiler.profile(save_checkpoint): checkpoint self._checkpoint_connector.dump_checkpoint(weights_only) self.strategy.save_checkpoint(checkpoint, filepath, storage_optionsstorage_options) self.strategy.barrier(Trainer.save_checkpoint)三个关键细节值得注意前置条件调用前必须已将模型挂载到 Trainer 上即先执行过fit/validate/test/predict之一否则抛出AttributeError分布式协作文档注释明确说明——若所选策略DDP、FSDP、DeepSpeed 等处理分布式检查点则该方法需要在所有进程上调用这正是末尾self.strategy.barrier(...)存在的意义参数语义weights_onlyTrue时仅保存模型权重storage_options会透传给CheckpointIO插件如对象存储场景。同时内置的ModelCheckpoint回调内部也已经切换到新 API在 src/lightning/pytorch/callbacks/model_checkpoint.py 中_save_checkpoint方法直接调用trainer.save_checkpoint(filepath, self.save_weights_only)随后更新内部记录并向全局 rank 0 上的 logger 广播after_save_checkpoint事件。这也印证了Trainer.save_checkpoint已经成为所有保存路径的统一出口。四、Sanity Check 状态查询running_sanity_check→sanity_checking4.1 迁移内容训练前 Lightning 会先跑一个轻量验证sanity check以尽早暴露数据管线或模型错误。1.4 起查询「当前是否处于 sanity check 阶段」的属性由Trainer.running_sanity_check更名为Trainer.sanity_checking。迁移前if trainer.running_sanity_check: # 跳过某些耗时操作 pass迁移后if trainer.sanity_checking: # 跳过某些耗时操作 pass4.2 源码佐证属性定义与内部消费方当前实现位于 src/lightning/pytorch/trainer/trainer.pyproperty def sanity_checking(self) - bool: Whether sanity checking is running. Useful to disable some hooks, logging or callbacks during the sanity checking. return self.state.stage RunningStage.SANITY_CHECKING该属性本质上是对Trainer.state.stage与RunningStage.SANITY_CHECKING的相等判断属于只读状态查询因此从running_sanity_check改为sanity_checking是纯粹的重命名不涉及逻辑变化。它在仓库中被大量内置组件消费可参考以下使用点early_stopping.pysanity check 期间不触发早停判定model_checkpoint.pysanity check 期间不保存检查点progress_bar.pysanity check 阶段显示对应批次数throughput_monitor.py 与 batch_size_finder.py依据该状态跳过统计或调整行为。如果你的自定义回调或插件在on_validation_*钩子中需要区分「正常验证」与「sanity check」请使用新属性。五、梯度范数计算LightningModule.grad_norm→pl.utilities.grads.grad_norm5.1 迁移内容旧版LightningModule提供grad_norm方法用于计算并记录梯度范数1.4 起该方法被废弃改为独立工具函数lightning.pytorch.utilities.grads.grad_norm推荐以pl.utilities.grad_norm导入见 utilities/init.py 的公开导出。迁移前from pytorch_lightning import LightningModule class MyModel(LightningModule): def training_step(self, batch, batch_idx): ... norms self.grad_norm(norm_type2.0) # 旧写法迁移后from lightning.pytorch import LightningModule from lightning.pytorch.utilities.grads import grad_norm class MyModel(LightningModule): def training_step(self, batch, batch_idx): ... norms grad_norm(self, norm_type2.0) # 新写法5.2 源码佐证函数行为细节实现位于 src/lightning/pytorch/utilities/grads.pydef grad_norm(module: Module, norm_type: Union[float, int, str], group_separator: str /) - dict[str, float]: norm_type float(norm_type) if norm_type 0: raise ValueError(fnorm_type must be a positive number or inf (infinity norm). Got {norm_type}) norms { fgrad_{norm_type}_norm{group_separator}{name}: p.grad.data.norm(norm_type) for name, p in module.named_parameters() if p.grad is not None } if norms: total_norm torch.tensor(list(norms.values())).norm(norm_type) norms[fgrad_{norm_type}_norm_total] total_norm return norms使用要点返回字典结构每个「有梯度」的参数量化为其 p-范数key 形如grad_2.0_norm/{参数名}同时额外给出一个grad_2.0_norm_total表示把所有梯度拼接为单一向量后计算的整体范数与torch.nn.utils.clip_grad_norm_的整体范数口径一致norm_type支持浮点/整数 p-范数也支持字符串inf无穷范数内部统一float()转换传入非正数会抛出ValueError此校验由后续 PR #9765 补充写死在源码中group_separator默认/用于在日志中为各层梯度范数分组只统计p.grad is not None的参数天然兼容冻结层与无需梯度的参数。顺带一提1.4 同期PR #7025还将梯度裁剪内部实现切换到了torch.nn.utils.clip_grad_norm_与grad_norm的整体范数口径保持一致。六、NaN 检测与梯度打印从TrainerTrainingTricksMixin迁出6.1 迁移内容TrainerTrainingTricksMixin是 1.4 之前Trainer上承载「训练技巧类」私有工具的 Mixin其中两个方法在 1.4 被移出旧写法Mixin 方法新写法utilities 工具TrainerTrainingTricksMixin.detect_nan_tensorspl.utilities.grads.grad_norm按文档记录TrainerTrainingTricksMixin.print_nan_gradientspl.utilities.finite_checks.print_nan_gradients迁移前1.3 及更早通过 Trainer 实例访问trainer.print_nan_gradients(model) # 旧写法打印 NaN 梯度 trainer.detect_nan_tensors(...) # 旧写法检测 NaN 张量迁移后1.4from lightning.pytorch.utilities.finite_checks import print_nan_gradients print_nan_gradients(model, clip_val0.0, grad_norm_dict{...}) # 新写法6.2 迁移提示print_nan_gradients用于在训练步中扫描各参数梯度若发现 NaN 则打印参数名、梯度值并可按需打印梯度范数是定位梯度爆炸/梯度消失的经典调试手段。迁移后其路径为lightning.pytorch.utilities.finite_checks不再依赖 Trainer 实例可在任意模型对象上直接调用需要说明的是官方升级表将detect_nan_tensors的新位置记录为pl.utilities.grads.grad_normPR #6834 一并搬移了该 Mixin 下的多个工具。从后续仓库演化看lightning.pytorch.utilities.finite_checks.print_nan_gradients已在 2.x 中作为未使用函数被移除见 CHANGELOG.md #16682 条目因此在 2.x 上若仍需该能力建议直接基于torch.isnan在training_step中自行实现梯度扫描同类迁移的还有梯度范数工具见第五节两者共同印证了「Mixin 私有方法 → utilities 公共工具函数」这一 1.4 重构主线。七、指标展平TrainerLoggingMixin.metrics_to_scalars→pl.utilities.metrics.metrics_to_scalars7.1 迁移内容metrics_to_scalars负责把日志接口收到的各类指标值标量、张量、字典、列表等统一展平为标量字典是self.log内部与各 logger 之间的关键转换环节。1.4 起它从TrainerLoggingMixin迁出为公共工具函数。迁移前# 旧写法通过 Trainer 继承的 Mixin 方法访问 trainer.metrics_to_scalars(metrics)迁移后from lightning.pytorch.utilities.metrics import metrics_to_scalars metrics_to_scalars(metrics)7.2 迁移提示该函数属于纯函数式工具不持有 Trainer 状态迁移后调用更直接、更易单测仓库 CHANGELOG 显示该函数在 1.x 内持续被增强如 #7888 使其「对任意集合或值生效」、#8782 修正异常信息说明它承担了log链路中较复杂的递归展平逻辑与print_nan_gradients类似metrics_to_scalars也已在后续 2.x 中作为未使用函数被移除CHANGELOG.md #16681 条目。普通用户无需直接调用它——self.log内部已自动完成转换只有深度定制 logger 或指标管线的开发者才需要关心此 API。八、GPU 选择语义收紧Trainer(gpusi,j)只控制数量8.1 迁移内容这是 7 项变更中唯一改变行为语义的一项务必重点确认。1.4 之前Trainer(gpusi,j)这类字符串写法既指定数量、又隐式选择具体 GPU 编号i、j 号卡。1.4 起该语义被收紧迁移前1.3 及更早from pytorch_lightning import Trainer trainer Trainer(gpus2,3) # 旧行为使用第 2、3 号 GPU迁移后1.4import os from lightning.pytorch import Trainer os.environ[CUDA_VISIBLE_DEVICES] 2,3 # 先屏蔽其余 GPU编号重新映射为 0,1 trainer Trainer(gpus2) # 新行为仅表示使用 2 张 GPU可见设备的前 2 张8.2 行为差异说明Trainer(gpusi,j)在 1.4 起只表示 GPU 数量等价于Trainer(devicesi)即使用 i 张卡不再隐含「选择第 i、j 号物理卡」要精确选择物理 GPU必须借助 CUDA 标准的CUDA_VISIBLE_DEVICESi,j环境变量在进程启动前完成设备屏蔽此时可见 GPU 的编号会被 CUDA 重新映射为从 0 开始这一收紧为后续 2.0 将gpus参数整体替换为devices扫清了歧义——在 2.x 上请统一使用Trainer(devices...)配合CUDA_VISIBLE_DEVICES完成选卡。迁移自查如果代码中出现了gpus0,1、gpus1这类字符串写法请确认其意图是「数量」还是「指定卡号」。前者直接改为devicesN后者必须补上CUDA_VISIBLE_DEVICES环境变量设置。九、升级自查清单将上述变更整理为可直接对照的检查表全局搜索save_function改为调用trainer.save_checkpoint(filepath, weights_only...)全局搜索running_sanity_check改为trainer.sanity_checking全局搜索self.grad_norm(LightningModule 内改为grad_norm(self, norm_type..., group_separator...)norm_type必须为正数或inf检查是否直接使用了TrainerTrainingTricksMixin/TrainerLoggingMixin上的工具方法迁移到lightning.pytorch.utilities对应子模块检查Trainer(gpus...)字符串传参确认数量语义配合CUDA_VISIBLE_DEVICES选卡2.x 上改用devices确认自定义回调中ModelCheckpoint相关保存逻辑已通过trainer.save_checkpoint走统一出口。十、结语1.4 高级用户的这 7 项变更本质是 PyTorch Lightning「收敛内部接口、公开公共工具」的一次集中重构Trainer.save_checkpoint成为保存路径的统一出口sanity_checking取代了语义不清的旧属性名梯度与指标类工具下沉为可独立复用的utilities函数而gpus字符串的语义收紧则为 2.0 的devices参数铺路。按本文清单完成迁移后你的代码不仅在 1.4 上干净可用也能更平滑地过渡到后续大版本。相关演进过程可继续查阅仓库的 完整 1.4 升级说明 与 CHANGELOG.md各 API 的新实现则可在 src/lightning/pytorch/trainer/trainer.py、src/lightning/pytorch/utilities、src/lightning/pytorch/callbacks/model_checkpoint.py 中逐一验证。赞分享人工智能深度学习机器学习预训练分布式训练微调【免费下载链接】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点击查看免费下载相关推荐Hydra 1.4 破坏性变更完整指南从 1.3 升级到 1.4 的兼容性迁移清单Hydra 1.4 破坏性变更完整指南从 1.3 升级到 1.4 的兼容性迁移清单 Hydra 1.4 与 OmegaConf 2.4 是 Hydra 框架一开发工具后端CLIMatter协议升级实战指南从1.4到1.5的完整迁移方案Matter协议升级实战指南从1.4到1.5的完整迁移方案 智能家居设备厂商常面临协议碎片化挑战Matter 1.5通过标准化新增设备类型和优化能源管理集群物联网智能家居嵌入式通信Shaka Player v2.3 升级到 v2.5完整 API 变更指南与迁移实战Shaka Player v2.3 升级到 v2.5完整 API 变更指南与迁移实战 本文是基于 Shaka Player 官方升级文档 docs/upgra前端音视频创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/20 12:33:25 · 阅读 1.2k PyTorch Lightning 1.4 高级用户迁移指南：7 项 API 变更的完整升级方案
人工智能深度学习机器学习预训练分布式训练微调【免费下载链接】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点击查看免费下载本文基于 PyTorch Lightning 仓库中的官方升级文档 1.4 高级用户迁移章节系统梳理从 1.3 升级到 1.4 时针对高级用户的 7 项破坏性 API 变更涉及模型检查点保存、sanity check 状态查询、梯度范数计算、NaN 检测与打印、指标展平、以及 GPU 选择语义的调整。读完本文你将掌握每一项变更的旧写法与新写法对照、迁移操作步骤以及新 API 在当前仓库源码中的真实实现与使用边界可据此安全、无痛地完成代码升级。适用前提本文面向使用 PyTorch Lightning 1.4及后续 1.x的高级用户——即那些直接调用了Trainer内部 Mixin、LightningModule工具方法或ModelCheckpoint私有属性的开发者。普通应用层用户若未使用这些内部接口通常无需改动。一、升级背景1.4 为何要动这些接口PyTorch Lightning 1.4 是一次以「内部 API 公共化、职责下沉」为方向的大版本。此前许多实用功能梯度范数、NaN 检测、指标展平、sanity check 状态查询散落在Trainer的各个 Mixin 类与LightningModule的方法中耦合度高、难以独立复用。1.4 将这些工具函数统一收编到lightning.pytorch.utilities工具包并把底层能力通过公开方法暴露如Trainer.save_checkpoint同时收紧Trainer(gpus...)的语义为后续 2.0 的大规模重构gpus被devices取代、旧属性彻底移除铺路。仓库的 CHANGELOG.md 中保留了完整的演进痕迹1.4 时代先对这些接口发起废弃deprecation并给出替代方案PR #7201、#4945、#7292、#6834、#7180、#6388后续版本再逐步移除例如 #9209 移除running_sanity_check、#8680 移除save_function。因此本文的迁移建议不仅适用于 1.4也适用于任何仍然可见这些旧 API 的 1.x 版本。二、变更总览表以下表格完整继承自 1_4_advanced.rst并补充了「变更类型」与「影响模块」两列便于快速定位If旧写法Then新写法RefPR变更类型影响模块calledModelCheckpoint.save_functionnow callTrainer.save_checkpointPR #7201方法迁移回调 / Traineraccessed theTrainer.running_sanity_checkpropertynow access theTrainer.sanity_checkingpropertyPR #4945属性重命名Trainer 状态usedLightningModule.grad_normnow use thepl.utilities.grad_normutility function insteadPR #7292方法 → 工具函数LightningModule / utilitiesusedTrainerTrainingTricksMixin.detect_nan_tensorsnow usepl.utilities.grads.grad_normPR #6834方法迁移Trainer Mixin / utilitiesusedTrainerTrainingTricksMixin.print_nan_gradientsnow usepl.utilities.finite_checks.print_nan_gradientsPR #6834方法迁移Trainer Mixin / utilitiesrelied onTrainerLoggingMixin.metrics_to_scalarsnow usepl.utilities.metrics.metrics_to_scalarsPR #7180方法迁移Trainer Mixin / utilitiesselected the i-th GPU withTrainer(gpusi,j)now this will set the number of GPUs, just like passingTrainer(devicesi); select specific GPU viaCUDA_VISIBLE_DEVICESi,jPR #6388语义收紧Trainer 参数下面逐项展开每一节都给出「迁移前 → 迁移后」的代码对照与源码级佐证。三、模型检查点保存从ModelCheckpoint.save_function到Trainer.save_checkpoint3.1 迁移内容在 1.4 之前高级用户若要自定义检查点保存逻辑常会覆写或调用ModelCheckpoint回调上的save_function属性。1.4 起该属性被废弃保存动作统一收敛到Trainer.save_checkpoint。迁移前1.3 及更早from pytorch_lightning.callbacks import ModelCheckpoint checkpoint_callback ModelCheckpoint(...) # 旧写法直接操作回调上的保存函数 checkpoint_callback.save_function(trainer, filepath)迁移后1.4from lightning.pytorch import Trainer trainer Trainer() # 新写法由 Trainer 统一触发保存例行流程 trainer.save_checkpoint(filepathmy/checkpoint/file.ckpt)3.2 源码佐证新 API 的完整调用链当前仓库中Trainer.save_checkpoint的实现位于 src/lightning/pytorch/trainer/trainer.py其签名与流程如下def save_checkpoint( self, filepath: _PATH, weights_only: Optional[bool] None, storage_options: Optional[Any] None ) - None: if self.model is None: raise AttributeError( Saving a checkpoint is only possible if a model is attached to the Trainer. Did you call Trainer.save_checkpoint() before calling Trainer.{fit,validate,test,predict}? ) with self.profiler.profile(save_checkpoint): checkpoint self._checkpoint_connector.dump_checkpoint(weights_only) self.strategy.save_checkpoint(checkpoint, filepath, storage_optionsstorage_options) self.strategy.barrier(Trainer.save_checkpoint)三个关键细节值得注意前置条件调用前必须已将模型挂载到 Trainer 上即先执行过fit/validate/test/predict之一否则抛出AttributeError分布式协作文档注释明确说明——若所选策略DDP、FSDP、DeepSpeed 等处理分布式检查点则该方法需要在所有进程上调用这正是末尾self.strategy.barrier(...)存在的意义参数语义weights_onlyTrue时仅保存模型权重storage_options会透传给CheckpointIO插件如对象存储场景。同时内置的ModelCheckpoint回调内部也已经切换到新 API在 src/lightning/pytorch/callbacks/model_checkpoint.py 中_save_checkpoint方法直接调用trainer.save_checkpoint(filepath, self.save_weights_only)随后更新内部记录并向全局 rank 0 上的 logger 广播after_save_checkpoint事件。这也印证了Trainer.save_checkpoint已经成为所有保存路径的统一出口。四、Sanity Check 状态查询running_sanity_check→sanity_checking4.1 迁移内容训练前 Lightning 会先跑一个轻量验证sanity check以尽早暴露数据管线或模型错误。1.4 起查询「当前是否处于 sanity check 阶段」的属性由Trainer.running_sanity_check更名为Trainer.sanity_checking。迁移前if trainer.running_sanity_check: # 跳过某些耗时操作 pass迁移后if trainer.sanity_checking: # 跳过某些耗时操作 pass4.2 源码佐证属性定义与内部消费方当前实现位于 src/lightning/pytorch/trainer/trainer.pyproperty def sanity_checking(self) - bool: Whether sanity checking is running. Useful to disable some hooks, logging or callbacks during the sanity checking. return self.state.stage RunningStage.SANITY_CHECKING该属性本质上是对Trainer.state.stage与RunningStage.SANITY_CHECKING的相等判断属于只读状态查询因此从running_sanity_check改为sanity_checking是纯粹的重命名不涉及逻辑变化。它在仓库中被大量内置组件消费可参考以下使用点early_stopping.pysanity check 期间不触发早停判定model_checkpoint.pysanity check 期间不保存检查点progress_bar.pysanity check 阶段显示对应批次数throughput_monitor.py 与 batch_size_finder.py依据该状态跳过统计或调整行为。如果你的自定义回调或插件在on_validation_*钩子中需要区分「正常验证」与「sanity check」请使用新属性。五、梯度范数计算LightningModule.grad_norm→pl.utilities.grads.grad_norm5.1 迁移内容旧版LightningModule提供grad_norm方法用于计算并记录梯度范数1.4 起该方法被废弃改为独立工具函数lightning.pytorch.utilities.grads.grad_norm推荐以pl.utilities.grad_norm导入见 utilities/init.py 的公开导出。迁移前from pytorch_lightning import LightningModule class MyModel(LightningModule): def training_step(self, batch, batch_idx): ... norms self.grad_norm(norm_type2.0) # 旧写法迁移后from lightning.pytorch import LightningModule from lightning.pytorch.utilities.grads import grad_norm class MyModel(LightningModule): def training_step(self, batch, batch_idx): ... norms grad_norm(self, norm_type2.0) # 新写法5.2 源码佐证函数行为细节实现位于 src/lightning/pytorch/utilities/grads.pydef grad_norm(module: Module, norm_type: Union[float, int, str], group_separator: str /) - dict[str, float]: norm_type float(norm_type) if norm_type 0: raise ValueError(fnorm_type must be a positive number or inf (infinity norm). Got {norm_type}) norms { fgrad_{norm_type}_norm{group_separator}{name}: p.grad.data.norm(norm_type) for name, p in module.named_parameters() if p.grad is not None } if norms: total_norm torch.tensor(list(norms.values())).norm(norm_type) norms[fgrad_{norm_type}_norm_total] total_norm return norms使用要点返回字典结构每个「有梯度」的参数量化为其 p-范数key 形如grad_2.0_norm/{参数名}同时额外给出一个grad_2.0_norm_total表示把所有梯度拼接为单一向量后计算的整体范数与torch.nn.utils.clip_grad_norm_的整体范数口径一致norm_type支持浮点/整数 p-范数也支持字符串inf无穷范数内部统一float()转换传入非正数会抛出ValueError此校验由后续 PR #9765 补充写死在源码中group_separator默认/用于在日志中为各层梯度范数分组只统计p.grad is not None的参数天然兼容冻结层与无需梯度的参数。顺带一提1.4 同期PR #7025还将梯度裁剪内部实现切换到了torch.nn.utils.clip_grad_norm_与grad_norm的整体范数口径保持一致。六、NaN 检测与梯度打印从TrainerTrainingTricksMixin迁出6.1 迁移内容TrainerTrainingTricksMixin是 1.4 之前Trainer上承载「训练技巧类」私有工具的 Mixin其中两个方法在 1.4 被移出旧写法Mixin 方法新写法utilities 工具TrainerTrainingTricksMixin.detect_nan_tensorspl.utilities.grads.grad_norm按文档记录TrainerTrainingTricksMixin.print_nan_gradientspl.utilities.finite_checks.print_nan_gradients迁移前1.3 及更早通过 Trainer 实例访问trainer.print_nan_gradients(model) # 旧写法打印 NaN 梯度 trainer.detect_nan_tensors(...) # 旧写法检测 NaN 张量迁移后1.4from lightning.pytorch.utilities.finite_checks import print_nan_gradients print_nan_gradients(model, clip_val0.0, grad_norm_dict{...}) # 新写法6.2 迁移提示print_nan_gradients用于在训练步中扫描各参数梯度若发现 NaN 则打印参数名、梯度值并可按需打印梯度范数是定位梯度爆炸/梯度消失的经典调试手段。迁移后其路径为lightning.pytorch.utilities.finite_checks不再依赖 Trainer 实例可在任意模型对象上直接调用需要说明的是官方升级表将detect_nan_tensors的新位置记录为pl.utilities.grads.grad_normPR #6834 一并搬移了该 Mixin 下的多个工具。从后续仓库演化看lightning.pytorch.utilities.finite_checks.print_nan_gradients已在 2.x 中作为未使用函数被移除见 CHANGELOG.md #16682 条目因此在 2.x 上若仍需该能力建议直接基于torch.isnan在training_step中自行实现梯度扫描同类迁移的还有梯度范数工具见第五节两者共同印证了「Mixin 私有方法 → utilities 公共工具函数」这一 1.4 重构主线。七、指标展平TrainerLoggingMixin.metrics_to_scalars→pl.utilities.metrics.metrics_to_scalars7.1 迁移内容metrics_to_scalars负责把日志接口收到的各类指标值标量、张量、字典、列表等统一展平为标量字典是self.log内部与各 logger 之间的关键转换环节。1.4 起它从TrainerLoggingMixin迁出为公共工具函数。迁移前# 旧写法通过 Trainer 继承的 Mixin 方法访问 trainer.metrics_to_scalars(metrics)迁移后from lightning.pytorch.utilities.metrics import metrics_to_scalars metrics_to_scalars(metrics)7.2 迁移提示该函数属于纯函数式工具不持有 Trainer 状态迁移后调用更直接、更易单测仓库 CHANGELOG 显示该函数在 1.x 内持续被增强如 #7888 使其「对任意集合或值生效」、#8782 修正异常信息说明它承担了log链路中较复杂的递归展平逻辑与print_nan_gradients类似metrics_to_scalars也已在后续 2.x 中作为未使用函数被移除CHANGELOG.md #16681 条目。普通用户无需直接调用它——self.log内部已自动完成转换只有深度定制 logger 或指标管线的开发者才需要关心此 API。八、GPU 选择语义收紧Trainer(gpusi,j)只控制数量8.1 迁移内容这是 7 项变更中唯一改变行为语义的一项务必重点确认。1.4 之前Trainer(gpusi,j)这类字符串写法既指定数量、又隐式选择具体 GPU 编号i、j 号卡。1.4 起该语义被收紧迁移前1.3 及更早from pytorch_lightning import Trainer trainer Trainer(gpus2,3) # 旧行为使用第 2、3 号 GPU迁移后1.4import os from lightning.pytorch import Trainer os.environ[CUDA_VISIBLE_DEVICES] 2,3 # 先屏蔽其余 GPU编号重新映射为 0,1 trainer Trainer(gpus2) # 新行为仅表示使用 2 张 GPU可见设备的前 2 张8.2 行为差异说明Trainer(gpusi,j)在 1.4 起只表示 GPU 数量等价于Trainer(devicesi)即使用 i 张卡不再隐含「选择第 i、j 号物理卡」要精确选择物理 GPU必须借助 CUDA 标准的CUDA_VISIBLE_DEVICESi,j环境变量在进程启动前完成设备屏蔽此时可见 GPU 的编号会被 CUDA 重新映射为从 0 开始这一收紧为后续 2.0 将gpus参数整体替换为devices扫清了歧义——在 2.x 上请统一使用Trainer(devices...)配合CUDA_VISIBLE_DEVICES完成选卡。迁移自查如果代码中出现了gpus0,1、gpus1这类字符串写法请确认其意图是「数量」还是「指定卡号」。前者直接改为devicesN后者必须补上CUDA_VISIBLE_DEVICES环境变量设置。九、升级自查清单将上述变更整理为可直接对照的检查表全局搜索save_function改为调用trainer.save_checkpoint(filepath, weights_only...)全局搜索running_sanity_check改为trainer.sanity_checking全局搜索self.grad_norm(LightningModule 内改为grad_norm(self, norm_type..., group_separator...)norm_type必须为正数或inf检查是否直接使用了TrainerTrainingTricksMixin/TrainerLoggingMixin上的工具方法迁移到lightning.pytorch.utilities对应子模块检查Trainer(gpus...)字符串传参确认数量语义配合CUDA_VISIBLE_DEVICES选卡2.x 上改用devices确认自定义回调中ModelCheckpoint相关保存逻辑已通过trainer.save_checkpoint走统一出口。十、结语1.4 高级用户的这 7 项变更本质是 PyTorch Lightning「收敛内部接口、公开公共工具」的一次集中重构Trainer.save_checkpoint成为保存路径的统一出口sanity_checking取代了语义不清的旧属性名梯度与指标类工具下沉为可独立复用的utilities函数而gpus字符串的语义收紧则为 2.0 的devices参数铺路。按本文清单完成迁移后你的代码不仅在 1.4 上干净可用也能更平滑地过渡到后续大版本。相关演进过程可继续查阅仓库的 完整 1.4 升级说明 与 CHANGELOG.md各 API 的新实现则可在 src/lightning/pytorch/trainer/trainer.py、src/lightning/pytorch/utilities、src/lightning/pytorch/callbacks/model_checkpoint.py 中逐一验证。赞分享人工智能深度学习机器学习预训练分布式训练微调【免费下载链接】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点击查看免费下载相关推荐Hydra 1.4 破坏性变更完整指南从 1.3 升级到 1.4 的兼容性迁移清单Hydra 1.4 破坏性变更完整指南从 1.3 升级到 1.4 的兼容性迁移清单 Hydra 1.4 与 OmegaConf 2.4 是 Hydra 框架一开发工具后端CLIMatter协议升级实战指南从1.4到1.5的完整迁移方案Matter协议升级实战指南从1.4到1.5的完整迁移方案 智能家居设备厂商常面临协议碎片化挑战Matter 1.5通过标准化新增设备类型和优化能源管理集群物联网智能家居嵌入式通信Shaka Player v2.3 升级到 v2.5完整 API 变更指南与迁移实战Shaka Player v2.3 升级到 v2.5完整 API 变更指南与迁移实战 本文是基于 Shaka Player 官方升级文档 docs/upgra前端音视频创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考