企业官网建设流程全解析

• 人工智能
• 深度学习
• 机器学习
• 预训练
• 分布式训练
• 微调

本文基于 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_default=None中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 中，seed_everything_default=None表示"不要自动调用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, run=False, seed_everything_default=False) assert cli.config["seed_everything"] is False

以及命令行覆盖优先级：

# 命令行显式传入的 --seed_everything 3 会覆盖默认值 cli = LightningCLI(TestModel, run=False, seed_everything_default=10) assert cli.config["seed_everything"] == 3

LightningCLI的示例脚本见 tests/tests_pytorch/strategies/scripts/cli_script.py，其中使用了seed_everything_default=42的整数形式。

迁移建议

• 若你的旧代码seed_everything_default=None的意图是"关闭自动播种"，直接替换为False即可；
• 若你的意图是"每次固定随机种子以复现结果"，请改为显式整数（如42），而不是True，因为True每次生成的种子是随机的；
• 升级后运行时若出现AttributeError或类型校验错误，优先检查所有LightningCLI(...)构造点是否残留None。

三、Trainer 数据加载器重置：reset_train_val_dataloaders()改为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.py：FitLoop.setup_data()会检查_combined_loader是否已存在且无需重载，若limit_train_batches == 0或模型未重写training_step则提前返回，否则从trainer.fit_loop对应的数据源重建加载器；
• evaluation_loop.py：EvaluationLoop.setup_data()根据TrainerFn.FITTING判断是否需要重载验证集；
• prediction_loop.py：PredictionLoop.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

变更内容

旧路径pl.core.lightning文件名与文件内定义的核心类LightningModule命名不对应，容易造成困惑。官方在 PR #12740），2.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'，说明仍存在旧导入残留。

五、升级后的验证清单

完成上述三处修改后，建议按以下步骤验证迁移结果：

1. 静态检查：在仓库或项目目录中运行正则搜索，确认不再出现seed_everything_default=None、reset_train_val_dataloaders、core.lightning三种旧写法；

2. 导入自检：执行

   python -c "from lightning.pytorch import LightningModule; from lightning.pytorch.cli import LightningCLI; print('ok')"

3. 运行自检：用LightningCLI(...)实例化一个最小 Trainer（可参考 tests/tests_pytorch/strategies/scripts/cli_script.py），确认--seed_everything参数行为符合预期（False时不打印 seeding 信息，True时自动生成种子，int时固定种子）；

4. 数据流自检：在自定义回调中调用trainer.fit_loop.setup_data()触发一次加载器重建，确认训练/验证数据迭代正常。

六、小结

这三类变更覆盖了 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 的升级。

• 人工智能
• 深度学习
• 机器学习
• 预训练
• 分布式训练
• 微调