PyTorch Lightning 版本历史指南：从 1.0 到 2.x 的演进脉络与升级路径

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

PyTorch Lightning 的Past Versions文档（docs/source-pytorch/past_versions.rst）是项目社区文档体系中的一个关键索引页：它以表格形式记录了 1.0 至 1.9 各次主要版本的核心特性亮点、每个主版本下发布的所有 bug-fix 小版本号，以及指向对应升级指南的入口。本文以该文档为主线，结合仓库内的版本策略文档、迁移指南及各版本的升级明细（如 1.9 升级指南、1.4 升级指南），为读者梳理版本历史全貌、理解各版本引入的关键能力，并提供从旧版本升级到 2.x 的实践路径。

一、版本历史的定位与使用方法

1.1 文档在社区体系中的位置

past_versions.rst被挂载在 Community 文档目录 的隐藏 toctree 中，与以下文档并列：

• Versioning Policy：阐述 PyTorch Lightning 的版本发布策略、API 稳定性承诺与兼容性矩阵；
• Migration Guide：2.x 系列升级的总入口；
• 各版本的升级分节文档（docs/source-pytorch/upgrade/目录下的from_1_x.rst系列）。

1.2 如何利用该页

该页的核心用途有三：

1. 快速定位历史文档：表格中每个主版本号都带官方发布页链接，标题列链接到该主版本系列的文档站；
2. 核对 bug-fix 版本：每个主版本下列出了全部已发布的小版本号（如 1.5.x 共发布到 1.5.10），方便锁定具体修复版本；
3. 跳转升级指南：1.4 至 1.9 均配有"从该版本升级到 2.0"的专项指南链接，升级路径一目了然。

二、PyTorch Lightning 版本演进全览（1.0 → 1.9）

下表完整整理了past_versions.rst中记录的版本信息（特性标题为官方发布说明原文摘要）：

2.1 逐版本解读：关键技术里程碑

• 1.0（GA）：发布 1.0.0，标志着 API 走向稳定。从版本策略文档可知，自此所有公开 API 除非明确标注 experimental，均视为稳定 API（见 versioning.rst）。
• 1.1：引入模型并行训练能力，并扩展日志器选项。
• 1.2：加入剪枝（Pruning）、量化（Quantization）与随机权重平均（SWA）等模型压缩与集成技术。
• 1.3：发布 Lightning CLI（命令行接口）、接入 PyTorch Profiler，并改进 Early Stopping 回调。
• 1.4：训练规模显著扩展——支持 TPU Pod 训练、Graphcore IPU 加速器、DeepSpeed Infinity 以及完全分片数据并行（FSDP）。
• 1.5：成为承上启下的重要版本：推出 LightningLite（Fabric 的前身）、容错训练、循环定制、LightningCLI v2、RichProgressBar、CheckpointIO 插件，并将Trainer的策略选择改为独立参数。
• 1.6：引入 Intel Habana（HPU）加速器支持、基于 Bagua 的高效 DDP 策略与手动容错机制。
• 1.7：全面支持 Apple Silicon（MPS）、原生 FSDP，并支持 Jupyter 场景下的多 GPU 训练。
• 1.8：新增 Colossal-AI 策略、Lightning Apps 的 Commands 与 Secrets 能力，并对 FSDP 做进一步改进。
• 1.9：聚焦稳定性与额外改进，为 2.0 大版本做铺垫。

2.2 从源码结构印证版本演进

当前仓库源码目录清晰地保留了这段演进史的痕迹：

• src/lightning/pytorch/_graveyard/目录存放被移除或废弃的模块，例如 graveyard 测试中还保留着对 TPU、HPU 与旧 precision 插件的兼容测试（见 tests/tests_pytorch/graveyard/）；
• src/lightning/fabric/_graveyard/tpu.py表明 Fabric 侧的 TPU 支持也已迁移至废弃区；
• 1.5 版本引入的 LightningLite 在版本策略文档中被明确标注为"Fabric 的前身，于 1.9 解耦为独立包"（见 versioning.rst）。

三、版本策略：理解 PyTorch Lightning 如何"升级"

要正确使用历史版本页，必须先理解项目的版本语义。PyTorch Lightning 使用自己的版本策略，而非严格遵循语义化版本（SemVer）（见 versioning.rst）：

• PATCH 版本（x.y.z 的 z）：只包含 bug 修复，不引入破坏性变更，官方建议用户始终升级到同一 minor 系列内的最新 patch 版本；
• MINOR 版本（x.y 的 y）：可能包含带弃用警告（deprecation）的向后不兼容变更——这与 SemVer 不同，同时还包含新特性与 bug 修复；
• MAJOR 版本（x 本身）：可能包含不带弃用警告的向后不兼容变更。

版本号遵循MAJOR.MINOR.PATCH三段式格式。每次发布都会更新变更日志（本项目对应 src/lightning/pytorch/CHANGELOG.md 与 src/lightning/fabric/CHANGELOG.md），列出新增、移除、弃用、变更与修复条目。

3.1 API 稳定性承诺

• 稳定 API：除明确标注 experimental 之外的公开 API 均视为稳定——不应变更；若确需变更，会先按策略发出弃用警告（versioning.rst）。
• 实验性 API：标注 experimental 的特性可能依赖活跃开发中的依赖、可能无预警地变更、性能未经充分验证、未经核心团队生产场景打磨，甚至可能随时移除。因此文档建议：使用实验特性时考虑固定（pin）依赖版本（versioning.rst）。
• 受保护成员：带下划线前缀的模块、函数、类与方法可在任意时刻变更或删除。

3.2 兼容性矩阵

版本策略文档还给出了一张覆盖 1.0 至 2.7 的兼容性矩阵，表格列出了lightning.pytorch、pytorch_lightning、lightning.fabric三个包与torch、torchmetrics、Python 的版本对应关系。几个关键结论：

• 项目遵循 NEP 29 弃用策略（与 PyTorch 一致）；
• 自 PyTorch 2.0 发布以来，Lightning 致力于在大版本内官方支持最新的 5 个 PyTorch minor 版本（versioning.rst）；
• 表格中"≥ X.Y"表示最低支持版本，"▼ X.Y"表示 CI 最后测试的版本（仅为信息性参考，不是硬性上限）；
• torchmetrics在 v1.3 之前是pytorch_lightning的一部分，之后才解耦为独立包；联合的lightning包于 1.8 首次发布；LightningLite于 1.5 随pytorch_lightning发布，1.9 解耦为独立的 Fabric 包（versioning.rst）。

当前仓库的实际版本信息可参见 src/version.info（内容为2.6.2），该文件由 src/lightning/version.py 读取，用于在打包与运行时暴露版本号。

四、升级指南：从 1.x 迁移到 2.x 的完整路径

4.1 迁移指南总入口

Migration Guide 是 2.x 升级的总导航页，其中按版本提供了以下升级卡片：

• 2.0.x：从 2.0.x 系列升级到 2.1（from_2_0）；
• 1.9.x→ 2.0（from_1_9）；
• 1.8.x→ 2.0（from_1_8）；
• 1.7.x→ 2.0（from_1_7）；
• 1.6.x→ 2.0（from_1_6）；
• 1.5.x→ 2.0（from_1_5）；
• 1.4.x→ 2.0（from_1_4）。

每份升级指南都按Regular User / Advanced User / Developer三个受众层次组织内容（以 from_1_9.rst 为例），对应docs/source-pytorch/upgrade/sections/下的1_x_regular.rst、1_x_advanced.rst、1_x_devel.rst分节文件。

4.2 典型案例：1.9 → 2.0 的常规用户迁移

从 1.9 常规用户迁移清单 中可以提炼出最具代表性的破坏性变更，这也解释了为何 2.0 是重要的大版本分水岭：

这批变更的完整演进背景在版本策略文档中有说明：Trainer(gpus=...)等 accelerator 参数自 1.7 起被弃用，但因为其影响面覆盖几乎所有用例，官方决定将破坏性变更推迟到 2.0 才落地（versioning.rst）。

4.3 典型案例：1.4 → 2.0 的常规用户迁移

1.4 常规用户迁移清单 展示了更早期的 API 演进，例如：

• on_train_epoch_end钩子中依赖outputs的用法被改变，需将输出挂到LightningModule实例属性上；
• LightningModule.write_predictions/write_predictions_dict被predict_step+Trainer.predict+ 回调取代；
• ModelCheckpoint(period=...)更名为ModelCheckpoint(every_n_epochs=...)；
• Profiler(output_filename=...)改为Profiler(dirpath=..., filename=...)；
• Callback.on_load_checkpoint(checkpoint)签名升级为Callback.on_load_checkpoint(trainer, pl_module, checkpoint)。

4.4 升级方法论建议

结合版本策略文档与迁移清单，可总结出面向读者的实践步骤：

1. 先确认当前版本：通过pip show pytorch-lightning或导入pytorch_lightning.__version__查看；
2. 对照迁移清单逐项排查：使用仓库中各from_1_x.rst的"如果……那么……"对照表，扫描代码中对应 API；
3. 关注弃用警告：2.x 之前（含 1.4–1.9）的弃用 API 在升级后运行时会输出LightningDeprecationWarning，可据此定位残留用法；
4. 固定依赖版本：若仍在使用实验性 API，建议将 lightning、torch 与 torchmetrics 的版本固定，避免意外的不兼容变更。

五、常见问题（FAQ）

Q1：1.3 及更早版本没有升级指南，如何升级到 2.0？从 past_versions.rst 表格可见，升级指南仅覆盖 1.4 及以上版本。更早版本建议先升级到 1.4+，再沿迁移路径逐级升级，期间优先处理各代弃用警告。

Q2：为什么 minor 版本也可能破坏兼容性？这是项目刻意设计的策略：minor 版本允许在发出弃用警告的前提下引入破坏性变更，与 SemVer 不同。这也是历史版本页与 版本策略文档 需要配合阅读的原因。

Q3：patch 版本应该追新吗？应该。patch 版本仅含 bug 修复、无破坏性变更，官方明确建议在 minor 版本内始终升级到最新 patch 版本。

Q4：如何查看某个具体版本的变更明细？每个版本发布都会更新变更日志，本仓库的 2.x 变更记录保存在 src/lightning/pytorch/CHANGELOG.md（Keep a Changelog 格式）中，包含 Added / Changed / Removed / Fixed 分类。

六、总结

past_versions.rst 虽然只是一个索引页，但它串联起了 PyTorch Lightning 从 1.0 GA 到 2.x 的完整演进图景：1.x 时代每代版本都在加速器支持、训练策略、CLI 与日志生态上稳步推进，最终在 2.0 以devices统一设备抽象、解耦 Fabric 等破坏性变更完成架构收敛。对仍在维护旧版本项目的开发者而言，这张表加上配套的版本策略与迁移指南，构成了从旧代码平滑升级到现代 PyTorch Lightning 的完整路线图。

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