人工智能深度学习机器学习预训练分布式训练微调【免费下载链接】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点击查看免费下载本文基于 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 项变更其中devicesauto在笔记本环境的行为变化在表中出现了重复记录实际变更点为 7 类。下表完整继承了原文档的全部条目原用法If升级后的写法Then关联 PR使用 PyTorch 1.11升级到 PyTorch 2.1 或更高版本#18691在 FSDP 下于LightningModule.configure_optimizers()中调用self.trainer.model.parameters()PyTorch 2.0 之后直接调用self.parameters()#17309使用Trainer(acceleratortpu, devices[i])选择基于 1 的 TPU 核心索引索引现在基于 0#17227使用torch_xla 1.13升级到torch_xla 1.13#17368使用trainer.num_val_batches获取所有验证 DataLoader 的总批次数改用sum(trainer.num_val_batches)#18441使用trainer.num_test_batches获取所有测试 DataLoader 的总批次数改用sum(trainer.num_test_batches)#18441使用trainer.num_sanity_val_batches获取 sanity check 阶段验证 DataLoader 的总批次数改用sum(trainer.num_sanity_val_batches)#18441使用Trainer(devicesauto)在 Jupyter 笔记本中自动选择所有可用 GPU改用Trainer(devices-1)#18291pip install lightning安装lightning.app依赖需要lightning.app时使用pip install lightning[app]#18386这些变更点均在 src/lightning/pytorch/CHANGELOG.md 的 2.0.0 变更日志中有对应记录是官方确认的实现事实。下面按主题分节深入展开每一类变更的具体含义、迁移步骤与源码依据。2. 环境与安装变更2.1 PyTorch 最低版本提升至 2.1PR #18691变更内容2.0 系列正式移除对 PyTorch 1.11 的支持最低要求为 PyTorch 2.1 或更高版本。对应 CHANGELOG 记录为Removed support for PyTorch 1.11#18691。迁移操作pip install -U torch2.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变更内容此前在 FSDPFully 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(), lr1e-3) return optimizer改为def configure_optimizers(self): # 2.0 之后直接引用自身参数即可同时支持多参数组 optimizer torch.optim.Adam(self.parameters(), lr1e-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_paramsTrue让用户无需再绕道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(acceleratortpu, devices[i])中的设备索引语义从 1 基改为 0 基。即此前devices[1]表示第 1 个 TPU 核心2.0 之后devices[1]表示第 2 个核心0 基下的索引 1。迁移操作# 2.0 之前devices[1] 表示第 1 个 TPU 核心 trainer Trainer(acceleratortpu, devices[1]) # 2.0 之后devices[0] 表示第 1 个 TPU 核心 trainer Trainer(acceleratortpu, devices[0])源码佐证CHANGELOG 中记录为 Trainer(acceleratortpu, 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.13PR #17368变更内容2.0 系列要求torch_xla 1.13低于 1.13 的旧版本不再受支持。迁移操作pip install -U torch_xla1.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_batches64时为 64证明升级后的 API 确实是按 DataLoader 返回列表。此外 tests/tests_pytorch/callbacks/progress/test_tqdm_progress_bar.py 等处也直接消费这一列表语义。提示这三个属性返回的元素类型是Union[int, float]当 DataLoader 长度为未知无限迭代器时可能返回浮点inf或特殊值求和时请留意这一边界情况。6.devicesauto在笔记本环境的行为变化PR #18291变更内容出于稳定性考虑在 Jupyter / IPython 等交互式笔记本环境中Trainer(devicesauto)这也是 Trainer 的默认值不再自动选择所有可用 GPU而是只使用 1 个 GPU。若确实需要跑满所有 GPU需显式传入devices-1。迁移操作# 笔记本环境中devicesauto默认现在只使用 1 块 GPU trainer Trainer() # 等价于 Trainer(devicesauto) # 需要所有可用 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(devicesN)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 ifdevicesauto(default)#18291。另外注意在交互式环境下即使显式指定了多设备策略选择也会自动落到ddp_fork见 accelerator_connector.py并在多进程场景下建议使用Trainer(strategyddp_notebook)。生产环境请始终以脚本方式而非笔记本运行多 GPU 任务。7. 迁移后的验证与常见问题完成上述适配后建议按以下步骤在升级环境中验证环境检查确认torch 2.1当前仓库要求2.6.0见 requirements/pytorch/base.txt、torch_xla 1.13并确认pip list中没有残留旧版本API 回归搜索代码中所有num_val_batches、num_test_batches、num_sanity_val_batches的使用点确认均已加sum()搜索trainer.model.parameters()确认 FSDP 场景已改为self.parameters()TPU 索引核对检查所有Trainer(acceleratortpu, devices[...])调用将索引整体减 10 基化运行环境确认如果你长期在笔记本里跑Trainer()且依赖多 GPU请改为脚本执行或显式devices-1依赖裁剪若安装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_paramsTrue使 FSDP 参数引用更自然、多 DataLoader 支持使批次计数改为列表、交互式环境的多 GPU 不稳定促使auto默认降级为单卡。对照本文的迁移表逐项检查代码并结合 CHANGELOGsrc/lightning/pytorch/CHANGELOG.md与源码实现理解变更原因即可平滑完成 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人工智能深度学习机器学习预训练分布式训练微调pysam 0.24 迁移指南从 0.23 升级到 HTSlib 1.23.1 的完整检查清单与源码级解读pysam 0.24 迁移指南从 0.23 升级到 HTSlib 1.23.1 的完整检查清单与源码级解读 本指南以开源仓库 scientific agentAI 技能科研生物信息学数据科学PyTorch Lightning 2.0 开发者升级指南XLAStrategy 与 SingleTPUStrategy 的 is_distributed 属性移除PyTorch Lightning 2.0 开发者升级指南XLAStrategy 与 SingleTPUStrategy 的 is_distributed 属人工智能深度学习机器学习预训练分布式训练微调创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考