ARTICLE · INTELLIGENCE

战地情报 · 详情页

来自尧图项目组的一线实战观察与深度解析

PyTorch Lightning 1.8 升级 2.0 迁移指南(Regular User 篇):API 变更与替换方案全解析

PyTorch Lightning 1.8 升级 2.0 迁移指南(Regular User 篇):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 官方升级文档 docs/source-pytorch/upgrade/sections/1_8_regular.rst 编写。PyTorch Lightning 1.8 到 2.0 是一次以清理废弃 API、统一模块命名为主的大版本升级普通用户Regular User最常遇到的破坏性变更集中在三处LightningCLI的seed_everything_default参数、Trainer.reset_train_val_dataloaders()方法以及pl.core.lightning模块的导入路径。读完本文你将掌握这三类变更的精确替换写法并理解其背后的源码演进逻辑从而在升级 2.0 时做到一次性迁移、无兼容性报错。一、为什么需要关注 1.8 到 2.0 的升级PyTorch Lightning 在 1.x 时代积累了大量历史遗留的命名模块文件与目录结构错位例如core/lightning.py与core/module.py并存、API 含义模糊如reset_train_val_dataloaders一次重置多个数据加载器、参数类型混乱如seed_everything_defaultNone中None与布尔值语义重叠等。2.0 版本通过先废弃1.8 起、后移除2.0 起的两步走策略完成清理这一过程在仓库 CHANGELOG 中有完整记录1.8 阶段相关 API 进入Deprecated状态仍可使用但会发出弃用警告2.0 阶段对应 API 被Removed直接使用会抛出 ImportError 或 AttributeError。因此从 1.8 直接升级到 2.0 的普通用户必须一次性完成下列替换不能依赖先升级 1.9 过渡来规避。二、LightningCLI 的 seed 参数None改为False变更内容如果你之前使用1.8 及更早请改为2.0 及以后LightningCLI(seed_everything_defaultNone)LightningCLI(seed_everything_defaultFalse)在 1.8 中seed_everything_defaultNone表示不要自动调用seed_everything。但由于None在 jsonargparse 解析体系中容易与未设置混淆且与True/False的布尔语义不一致官方在 PR #12804 中将其废弃统一改为显式布尔值False。参数语义与源码印证在 2.x 的 cli.py 中该参数的签名已经变为seed_everything_default: Union[bool, int] True,其完整语义为True默认值自动生成一个随机种子并注入到解析器的--seed_everything参数中False完全不调用seed_everything跳过自动播种int使用该整数作为固定种子值。对应地add_default_arguments_to_parser会为解析器注册--seed_everything参数见 cli.py类型为Union[bool, int]。仓库测试 tests/tests_pytorch/test_cli.py 覆盖了该参数的各种取值组合例如cli LightningCLI(TestModel, runFalse, seed_everything_defaultFalse) assert cli.config[seed_everything] is False以及命令行覆盖优先级# 命令行显式传入的 --seed_everything 3 会覆盖默认值 cli LightningCLI(TestModel, runFalse, seed_everything_default10) assert cli.config[seed_everything] 3LightningCLI的示例脚本见 tests/tests_pytorch/strategies/scripts/cli_script.py其中使用了seed_everything_default42的整数形式。迁移建议若你的旧代码seed_everything_defaultNone的意图是关闭自动播种直接替换为False即可若你的意图是每次固定随机种子以复现结果请改为显式整数如42而不是True因为True每次生成的种子是随机的升级后运行时若出现AttributeError或类型校验错误优先检查所有LightningCLI(...)构造点是否残留None。三、Trainer 数据加载器重置reset_train_val_dataloaders()改为fit_loop.setup_data()变更内容如果你之前使用1.8 及更早请改为2.0 及以后trainer.reset_train_val_dataloaders()trainer.fit_loop.setup_data()旧 API 的语义是一次同时重建训练与验证两个 DataLoader这种耦合设计在验证集可选的场景下只有训练、没有验证会触发不必要的重建逻辑。1.8 起该 API 被废弃见 CHANGELOG推荐改用更细粒度的reset_train_dataloader/reset_val_dataloader到 2.0 则进一步演进为直接调用训练循环FitLoop的setup_data()。底层原理在 2.x 源码中数据加载器的新建逻辑被下沉到各个 Loop 的setup_data()方法中fit_loop.pyFitLoop.setup_data()会检查_combined_loader是否已存在且无需重载若limit_train_batches 0或模型未重写training_step则提前返回否则从trainer.fit_loop对应的数据源重建加载器evaluation_loop.pyEvaluationLoop.setup_data()根据TrainerFn.FITTING判断是否需要重载验证集prediction_loop.pyPredictionLoop.setup_data()则调用_request_dataloader(source)并执行策略级 barrier。这种设计将数据准备与训练/验证/预测阶段解耦使得每个 Loop 只关心自己职责范围内的加载器也解释了为什么旧的一次性reset_train_val_dataloaders会被拆分替换。迁移示例# 旧写法1.8 及更早2.0 已移除 trainer.reset_train_val_dataloaders() # 新写法2.0 trainer.fit_loop.setup_data()迁移建议若你只在训练阶段前重置加载器直接使用trainer.fit_loop.setup_data()若你需要在验证或预测前单独重置可分别调用trainer.validate_loop.setup_data()、trainer.predict_loop.setup_data()对应 evaluation_loop.py 与 prediction_loop.py若你的自定义逻辑依赖旧 API 的同时重置行为请拆分为对训练循环与验证循环的两次调用。四、模块导入路径pl.core.lightning改为pl.core.module变更内容如果你之前使用1.8 及更早请改为2.0 及以后from pytorch_lightning.core.lightning import LightningModulefrom pytorch_lightning.core.module import LightningModule旧路径pl.core.lightning文件名与文件内定义的核心类LightningModule命名不对应容易造成困惑。官方在 PR #127402.0 移除旧路径。源码印证在当前仓库中core/module.py 是LightningModule的唯一实现位置而 core/init.py 统一从该文件导出from lightning.pytorch.core.module import LightningModule同时pytorch_lightning/与lightning/pytorch/双命名空间仓库通过 setup.py 与src/pytorch_lightning、src/lightning_fabric的软链/兼容层映射保证import pytorch_lightning与import lightning.pytorch均可用但内部实现统一收敛到lightning.pytorch.core.module。迁移建议全局搜索core.lightning替换为core.module更推荐的做法是直接使用包级导入from lightning.pytorch import LightningModule因为它经过init.py 的正式公开导出长期兼容性最好升级后运行python -c import pytorch_lightning自检若出现ModuleNotFoundError: No module named pytorch_lightning.core.lightning说明仍存在旧导入残留。五、升级后的验证清单完成上述三处修改后建议按以下步骤验证迁移结果静态检查在仓库或项目目录中运行正则搜索确认不再出现seed_everything_defaultNone、reset_train_val_dataloaders、core.lightning三种旧写法导入自检执行python -c from lightning.pytorch import LightningModule; from lightning.pytorch.cli import LightningCLI; print(ok)运行自检用LightningCLI(...)实例化一个最小 Trainer可参考 tests/tests_pytorch/strategies/scripts/cli_script.py确认--seed_everything参数行为符合预期False时不打印 seeding 信息True时自动生成种子int时固定种子数据流自检在自定义回调中调用trainer.fit_loop.setup_data()触发一次加载器重建确认训练/验证数据迭代正常。六、小结旧 API1.8 及更早新 API2.0变更性质LightningCLI(seed_everything_defaultNone)LightningCLI(seed_everything_defaultFalse)参数语义收敛为显式布尔/整数trainer.reset_train_val_dataloaders()trainer.fit_loop.setup_data()数据准备逻辑下沉到 Loopimport pl.core.lightningimport pl.core.module模块命名对齐实现内容这三类变更覆盖了 1.8 普通用户升级 2.0 时最典型的破坏面。对于高级用户与开发者层面的更多变更如pl.callbacks.base→pl.callbacks.callback、GPUAccelerator→CUDAAccelerator、LightningDeepSpeedModule移除等可继续查阅仓库中的 from_1_8.rst 总览文档及其引用的 1_8_advanced.rst、1_8_devel.rst 分节。遵循先废弃后移除的节奏对照本文逐项替换即可平滑完成从 1.8 到 2.0 的升级。赞分享人工智能深度学习机器学习预训练分布式训练微调【免费下载链接】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.8 → 2.0 升级指南开发者篇Logger 与 Profiler 基类迁移全解析PyTorch Lightning 1.8 → 2.0 升级指南开发者篇Logger 与 Profiler 基类迁移全解析 本篇技术指南面向 自定义 Li人工智能深度学习机器学习预训练分布式训练微调PyTorch Lightning 1.8/1.9 升级到 2.0 完整迁移指南API 变更、策略重构与代码改造清单PyTorch Lightning 1.8/1.9 升级到 2.0 完整迁移指南API 变更、策略重构与代码改造清单 本文是 PyTorch Lightnin人工智能深度学习机器学习预训练分布式训练微调PyTorch Lightning 1.4 高级用户迁移指南7 项 API 变更的完整升级方案PyTorch Lightning 1.4 高级用户迁移指南7 项 API 变更的完整升级方案 本文基于 PyTorch Lightning 仓库中的官方升级人工智能深度学习机器学习预训练分布式训练微调创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
RELATED READING

延伸阅读

更多一线实战笔记与深度复盘,助您持续精进