PyTorch Lightning 2.0 升级指南：普通用户迁移清单与源码级解读

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

本文基于 docs/source-pytorch/upgrade/sections/2_0_regular.rst 编写，系统梳理从 Lightning 1.x 迁移到 2.0 时普通用户（Regular User）必须关注的 7 类行为变更：PyTorch 版本要求、FSDP 参数引用方式、TPU 核心索引、批次计数 API、设备自动选择语义以及安装方式调整。读完本文，你将能够对照官方迁移表逐项完成代码适配，并理解这些变更背后的源码实现与原因，避免升级后踩坑。

本文针对的迁移文档是 2.0 升级指南（migration_guide.rst）中面向"普通用户"的部分，完整迁移指南还包含 2.0 高级用户（Advanced）与开发者（Developer）两个层级，本文聚焦普通用户最常遇到的兼容性变更。

1. 升级总览：2.0 对普通用户的兼容性变更一览

官方迁移表以"If → Then → Ref"三列形式，列出了从 1.x 升级到 2.0 时，普通用户代码中需要逐一对照检查的 8 项变更（其中devices="auto"在笔记本环境的行为变化在表中出现了重复记录，实际变更点为 7 类）。下表完整继承了原文档的全部条目：

这些变更点均在 src/lightning/pytorch/CHANGELOG.md 的 2.0.0 变更日志中有对应记录，是官方确认的实现事实。下面按主题分节深入展开每一类变更的具体含义、迁移步骤与源码依据。

2. 环境与安装变更

2.1 PyTorch 最低版本提升至 2.1（PR #18691）

变更内容：2.0 系列正式移除对 PyTorch 1.11 的支持，最低要求为 PyTorch 2.1 或更高版本。对应 CHANGELOG 记录为"Removed support for PyTorch 1.11"（#18691）。

迁移操作：

pip install -U "torch>=2.1"

源码佐证：当前仓库 requirements/pytorch/base.txt 中的依赖声明为torch >=2.6.0, <2.14.0，可见项目对 PyTorch 的版本约束随迭代持续收紧。升级 PyTorch 时建议同时关注torchmetrics等配套依赖的兼容范围（当前仓库要求torchmetrics >0.7.0, <1.9.0）。

注意：如果项目中使用了自定义 CUDA 扩展、旧版算子或依赖 PyTorch 1.x 行为的第三方库，请先验证其在 PyTorch 2.1+ 下的兼容性，再升级 Lightning。

2.2lightning.app改为可选依赖（PR #18386）

变更内容：从 2.0 开始，pip install lightning不再默认安装lightning.app及其依赖。只有明确需要lightning.app时才需要通过 extras 显式安装。

迁移操作：

# 普通安装（不含 lightning.app） pip install lightning # 需要 lightning.app 时 pip install "lightning[app]"

源码佐证：仓库的打包逻辑集中在 src/lightning/setup.py，其中_prepare_extras()会读取 requirements 目录下各子项目的*.txt依赖文件，将其组装为pytorch-*、fabric-*等 extras 分组，并以pip install "lightning[dev, docs]"之类的方式按需安装（见 src/lightning/setup.py）。这也是lightning[app]这类 extras 语法能够生效的机制基础。

3. FSDP 策略下的参数引用方式（PR #17309）

变更内容：此前在 FSDP（Fully Sharded Data Parallel）策略下，LightningModule.configure_optimizers()中需要通过self.trainer.model.parameters()来获取模型参数；从 2.0 起（配合 PyTorch 2.0+），直接调用self.parameters()即可。

迁移操作：将configure_optimizers()中的参数引用从：

def configure_optimizers(self): # 2.0 之前：FSDP 下必须通过 trainer.model 引用参数 optimizer = torch.optim.Adam(self.trainer.model.parameters(), lr=1e-3) return optimizer

改为：

def configure_optimizers(self): # 2.0 之后：直接引用自身参数即可，同时支持多参数组 optimizer = torch.optim.Adam(self.parameters(), lr=1e-3) return optimizer

源码佐证与原因：这一变更的根源在于 FSDP 策略的默认参数初始化方式。在 src/lightning/pytorch/strategies/fsdp.py 中，FSDPStrategy 构造时会默认设置self.kwargs.setdefault("use_orig_params", True)，代码注释明确写道："Avoids the need for user to reference params inconfigure_optimizersviaself.trainer.model.parameters()and enables support for multiple parameter groups"——即use_orig_params=True让用户无需再绕道trainer.model引用参数，并且使得在configure_optimizers()中定义多个优化器参数组成为可能。CHANGELOG 中对应记录了"Added support for multiple optimizer parameter groups when using the FSDP strategy"（#17309）以及"Removed the limitation to callself.trainer.model.parameters()inLightningModule.configure_optimizers()"（#17309）。

提示：若你在升级后仍遇到"optimizer does not seem to reference any FSDP parameters"之类的报错，请检查是否在setup()之前就创建了优化器；FSDP 要求优化器在模型完成 shard 之后再创建。

4. TPU 相关变更：核心索引与 torch_xla 版本

4.1 TPU 核心索引改为 0 基（PR #17227）

变更内容：Trainer(accelerator="tpu", devices=[i])中的设备索引语义从 1 基改为 0 基。即此前devices=[1]表示第 1 个 TPU 核心，2.0 之后devices=[1]表示第 2 个核心（0 基下的索引 1）。

迁移操作：

# 2.0 之前：devices=[1] 表示第 1 个 TPU 核心 trainer = Trainer(accelerator="tpu", devices=[1]) # 2.0 之后：devices=[0] 表示第 1 个 TPU 核心 trainer = Trainer(accelerator="tpu", devices=[0])

源码佐证：CHANGELOG 中记录为 "Trainer(accelerator="tpu", devices=[i])now selects the i-th TPU core (0-based, previously it was 1-based)"，同时该 PR（#17227）还带来了 TPU-v4 架构支持与无效 TPU 设备输入的校验逻辑。从源码结构看，TPU 相关实现分布在 src/lightning/pytorch/accelerators/xla.py、src/lightning/pytorch/strategies/launchers/xla.py 等文件中，这些模块通过torch_xla.core.xla_model与 XLA 设备交互，其设备解析逻辑统一采用 0 基索引。

4.2 torch_xla 最低版本提升至 1.13（PR #17368）

变更内容：2.0 系列要求torch_xla >= 1.13，低于 1.13 的旧版本不再受支持。

迁移操作：

pip install -U "torch_xla>=1.13"

源码佐证：CHANGELOG 记录为 "Increased the minimum XLA requirement to 1.13"（#17368）。该版本门槛与 TPU-v4 支持、PyTorch 2.x 的 XLA 适配直接相关，升级后请同步确认torch、torch_xla与驱动版本三者的匹配关系。

5. 批次数量 API 语义变更（PR #18441）

变更内容：trainer.num_val_batches、trainer.num_test_batches、trainer.num_sanity_val_batches三个属性的返回值从单个整数变为每个 DataLoader 批次数组成的列表。这是为了支持多 DataLoader 场景（如CombinedLoader或返回多个验证 DataLoader 的val_dataloader()）。

迁移操作：任何对这些属性做求和、取平均值或进度条计算的代码都需要适配：

# 2.0 之前：返回单个整数 total_val_batches = trainer.num_val_batches # 2.0 之后：返回列表，需要 sum() 汇总 total_val_batches = sum(trainer.num_val_batches) total_test_batches = sum(trainer.num_test_batches) total_sanity_batches = sum(trainer.num_sanity_val_batches)

源码佐证：在 src/lightning/pytorch/trainer/trainer.py 中，这三个属性的返回类型注解均为list[Union[int, float]]，并且各有明确的语义注释：

• num_sanity_val_batches：返回[min(self.num_sanity_val_steps, batches) for batches in max_batches]，即按 sanity check 步数逐 DataLoader 截断后的批次数列表；
• num_val_batches：在trainer.validate()时返回validate_loop.max_batches，在fit场景下则通过fit_loop.epoch_loop.val_loop._max_batches获取（刻意使用受保护访问，避免把 sanity check 阶段的批次数混入其中）；
• num_test_batches：直接返回test_loop.max_batches。

测试用例也印证了这一语义：在 tests/tests_pytorch/trainer/flags/test_limit_batches.py 中，断言isinstance(trainer.num_val_batches, list)且trainer.num_val_batches[0]等于预期的批次数（如limit_val_batches=64时为 64），证明升级后的 API 确实是"按 DataLoader 返回列表"。此外 tests/tests_pytorch/callbacks/progress/test_tqdm_progress_bar.py 等处也直接消费这一列表语义。

提示：这三个属性返回的元素类型是Union[int, float]，当 DataLoader 长度为未知（无限迭代器）时可能返回浮点inf或特殊值，求和时请留意这一边界情况。

6.devices="auto"在笔记本环境的行为变化（PR #18291）

变更内容：出于稳定性考虑，在 Jupyter / IPython 等交互式笔记本环境中，Trainer(devices="auto")（这也是 Trainer 的默认值）不再自动选择所有可用 GPU，而是只使用 1 个 GPU。若确实需要跑满所有 GPU，需显式传入devices=-1。

迁移操作：

# 笔记本环境中：devices="auto"（默认）现在只使用 1 块 GPU trainer = Trainer() # 等价于 Trainer(devices="auto") # 需要所有可用 GPU 时，显式指定 trainer = Trainer(devices=-1)

源码佐证：该逻辑实现在 src/lightning/pytorch/trainer/connectors/accelerator_connector.py 的_set_devices_flag_if_auto_passed()方法中：当devices标志为"auto"且检测到交互式环境（_IS_INTERACTIVE）且 CUDA 加速器可用设备数大于 1 时，会将设备数强制设为 1，并打印提示信息："Trainer will use only 1 of N GPUs because it is running inside an interactive / notebook environment. You may try to setTrainer(devices=N)but please note that multi-GPU inside interactive / notebook environments is considered experimental and unstable."；否则才回退到accelerator.auto_device_count()自动探测全部设备。CHANGELOG 对应记录为 "Due to lack of reliability, Trainer now only runs on one GPU instead of all GPUs in a Jupyter notebook ifdevices="auto"(default)"（#18291）。

另外注意：在交互式环境下即使显式指定了多设备，策略选择也会自动落到ddp_fork（见 accelerator_connector.py），并在多进程场景下建议使用Trainer(strategy='ddp_notebook')。生产环境请始终以脚本方式（而非笔记本）运行多 GPU 任务。

7. 迁移后的验证与常见问题

完成上述适配后，建议按以下步骤在升级环境中验证：

1. 环境检查：确认torch >= 2.1（当前仓库要求>=2.6.0，见 requirements/pytorch/base.txt）、torch_xla >= 1.13，并确认pip list中没有残留旧版本；
2. API 回归：搜索代码中所有num_val_batches、num_test_batches、num_sanity_val_batches的使用点，确认均已加sum()；搜索trainer.model.parameters()，确认 FSDP 场景已改为self.parameters()；
3. TPU 索引核对：检查所有Trainer(accelerator="tpu", devices=[...])调用，将索引整体减 1（0 基化）；
4. 运行环境确认：如果你长期在笔记本里跑Trainer()且依赖多 GPU，请改为脚本执行或显式devices=-1；
5. 依赖裁剪：若安装lightning后提示缺少lightning.app相关模块，按需改为pip install "lightning[app]"。

如果迁移过程中遇到本文未覆盖的高级场景（如回调状态、Checkpoint 兼容、策略 API 变更），请进一步查阅同一升级指南中的 高级用户章节 与开发者章节，两者分别对应sections/2_0_advanced.rst与sections/2_0_devel.rst，可覆盖更底层的迁移细节。

8. 小结

Lightning 2.0 面向普通用户的破坏性变更集中在依赖版本门槛、FSDP 参数语义、TPU 索引约定、批次计数 API 与设备自动选择五个方面。多数变更都源自底层架构演进：use_orig_params=True使 FSDP 参数引用更自然、多 DataLoader 支持使批次计数改为列表、交互式环境的多 GPU 不稳定促使"auto"默认降级为单卡。对照本文的迁移表逐项检查代码，并结合 CHANGELOG（src/lightning/pytorch/CHANGELOG.md）与源码实现理解变更原因，即可平滑完成 2.0 升级。

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