企业官网建设流程全解析

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

本指南以 PyTorch Lightning 1.7 版本发布说明中的 devel 破坏性变更（Breaking Changes）清单为主体，逐一解读每一项变更的来龙去脉、迁移方法和源码依据，帮助你在升级到 1.7 时避免踩坑。读完本文，你将掌握：rank_zero系列工具的正确导入路径、Trainer内部 Mixin 体系的重构方向、分布式后端配置方式的变化、Profiler 与精度插件的 API 迁移，以及多优化器 + TBPTT 场景下outputs数据格式的交换规则。

PyTorch Lightning 1.7 是一次以"内部架构整理"为主题的版本升级。它移除了大量遗留 API、把分散的rank_zero工具统一收口、让Trainer的职责划分更清晰，并调整了多优化器与 TBPTT（Truncated Backpropagation Through Time）组合场景下的钩子输出格式。本文以仓库内 docs/source-pytorch/upgrade/sections/1_7_devel.rst 的变更表格为主体，结合 src/lightning/pytorch 下的实际源码，逐条讲解"之前怎么用、现在怎么改、为什么这么改"。

一、变更总览：1.7 的破坏性变更分四类

从1_7_devel.rst表格看，1.7 的变更可以归纳为四个主题：

下文按此四条主线展开，每条都给出可直接复制的迁移前后代码对照。

二、rank_zero 系列工具集中到pl.utilities.rank_zero

1.7 中最大的一类变更，是把散落在pl.utilities.distributed与pl.utilities.warnings中的 rank 相关工具统一收口到pl.utilities.rank_zero。完整映射如下：

迁移示例（旧写法）：

from pl.utilities.distributed import rank_zero_only, rank_zero_info from pl.utilities.warnings import rank_zero_warn, LightningDeprecationWarning

改为（新写法）：

from lightning.pytorch.utilities.rank_zero import ( rank_zero_only, rank_zero_info, rank_zero_warn, LightningDeprecationWarning, )

从当前源码看，这次收口是"物理层面"的整合而非简单转发。src/lightning/pytorch/utilities/rank_zero.py 是所有工具的最终出口，它从lightning.fabric.utilities.rank_zero重新导出LightningDeprecationWarning、rank_zero_debug、rank_zero_deprecation、rank_zero_info、rank_zero_only、rank_zero_warn等，并配置了 PL 自己的日志器：

# src/lightning/pytorch/utilities/rank_zero.py from lightning.fabric.utilities.rank_zero import ( LightningDeprecationWarning, WarningCache, rank_prefixed_message, rank_zero_debug, rank_zero_deprecation, rank_zero_info, rank_zero_module, rank_zero_only, rank_zero_warn, ) rank_zero_module.log = logging.getLogger(__name__)

而rank_zero_only的真正实现位于 src/lightning/fabric/utilities/rank_zero.py：它通过读取RANK、LOCAL_RANK、SLURM_PROCID、JSM_NAMESPACE_RANK等环境变量确定当前进程 rank（其中LOCAL_RANK优先于SLURM_PROCID判断，防止 SLURM 托管环境下误判），再把rank_zero_only.rank设定为实际 rank，保证装饰器在 0 号进程之外静默跳过。LightningDeprecationWarning也定义在同一文件中，并被注册为rank_zero_deprecation的默认警告类别：

class LightningDeprecationWarning(DeprecationWarning): """Deprecation warnings raised by Lightning.""" rank_zero_module.rank_zero_deprecation_category = LightningDeprecationWarning

也就是说，pl.utilities.warnings在 1.7 之后只保留PossibleUserWarning一类用户警告（见 src/lightning/pytorch/utilities/warnings.py），所有与 rank 相关的打印、调试、警告与弃用提示都应改从pl.utilities.rank_zero导入。仓库的 src/lightning/pytorch/CHANGELOG.md 中 1247-1252 行也明确列出了这六项替换。

三、Trainer 内部重构：公开 API 收敛，Mixin 体系拆除

1.7 对Trainer做了一次大规模"瘦身"，把历史遗留的 Mixin 基类合并进Trainer本体，并移除了一批长期废弃的方法与属性。

3.1Trainer.run_stage退役，改用具体方法

通用入口Trainer.run_stage被移除，必须根据目的调用专用方法：Trainer.fit、Trainer.validate、Trainer.test、Trainer.predict。从 src/lightning/pytorch/trainer/trainer.py 可以看到，fit内部实际调用的是self._run_stage()，即"带下划线的内部实现"；run_stage只是 1.7 之前暴露给外部的一个通用包装，如今外部使用者不再需要它，直接使用语义清晰的具体方法即可。

3.2 三个 Mixin 合并进 Trainer

旧版本中Trainer的能力由多个 Mixin 拼装而成，1.7 将其拆除：

如果你在自定义代码中isinstance(trainer, TrainerCallbackHookMixin)或从这些 Mixin 派生子类，需要改为依赖Trainer本身与core/optimizer.py中的LightningOptimizer类。这属于内部实现细节的收敛，一般用户代码中较少直接接触。

3.3 属性迁移：device_ids、root_device、移除项

Trainer 上多个属性发生变化：

• Trainer.data_parallel_device_ids→Trainer.device_ids：属性改名。当前Trainer.device_ids在 src/lightning/pytorch/trainer/trainer.py 中实现，它会优先返回策略暴露的并行设备列表，否则回退到[self.strategy.root_device]，并据此派生num_devices。
• Trainer.root_gpu→Trainer.strategy.root_device.index：GPU 场景下需要"主 GPU 编号"时，不再直接读 Trainer 属性，而是通过策略层获取：trainer.strategy.root_device.index。从 src/lightning/pytorch/strategies/ddp.py 可以看到root_device定义为self.parallel_devices[self.local_rank]，即"当前进程对应的那台设备"。
• Trainer.should_rank_save_checkpoint：直接移除，不再有任何替代。
• Trainer.lightning_optimizers→ 使用Strategy及其属性：优化器的查询与维护职责移交给策略对象。

3.4Trainer.call_hook变为受保护方法，禁止外部调用

旧的Trainer.call_hook被拆分并改为内部方法，不应在用户代码中使用：

• Trainer._call_callback_hooks
• Trainer._call_lightning_module_hook
• Trainer._call_ttp_hook
• Trainer._call_accelerator_hook

当前源码中，这些调用统一收口在 src/lightning/pytorch/trainer/call.py，例如其中定义了_call_callback_hooks(trainer, hook_name, ...)、_call_lightning_module_hook(trainer, hook_name, ...)以及_call_strategy_hook等，src/lightning/pytorch/plugins/precision/precision.py 的pre_backward也通过call._call_callback_hooks(...)/call._call_lightning_module_hook(...)触发钩子。以_开头即表明这些是私有契约，未来可能继续变动；自定义回调或插件应通过标准钩子接口工作，而不是直接调用它们。

3.5 AMP 与verbose_evaluate的处置

• Trainer.use_amp/LightningModule.use_amp：两处布尔属性都被移除，混合精度完全交给 PyTorch 原生 AMP（torch.autocast/torch.amp）。需要判断是否使用 AMP 时，应查询当前精度插件（trainer.precision_plugin）的配置，而不是依赖被移除的use_amp。
• Trainer.verbose_evaluate：被移除，评估循环的详细输出改由循环构造器控制：EvaluationLoop(verbose=...)。

3.6Trainer.get_deprecated_arg_names()移除

这个专用于收集"过期构造参数名"的遗留方法在 1.7 被直接删除。Trainer构造参数的校验逻辑早已迁入连接器（connector）体系，不再需要这个通用方法。

四、分布式后端配置：环境变量让位于策略构造参数

1.7 移除了通过环境变量PL_TORCH_DISTRIBUTED_BACKEND指定分布式后端的遗留方式，改为在策略构造函数中显式传入process_group_backend参数。

旧写法（1.7 之前，靠环境变量）：

export PL_TORCH_DISTRIBUTED_BACKEND=nccl python train.py

新写法（1.7 起，在策略构造器里配置）：

from lightning.pytorch import Trainer from lightning.pytorch.strategies import DDPStrategy strategy = DDPStrategy(process_group_backend="nccl") trainer = Trainer(strategy=strategy)

从源码看，process_group_backend已作为一等构造参数被多个策略支持：src/lightning/pytorch/strategies/ddp.py 的DDPStrategy.__init__接收process_group_backend: Optional[str] = None并保存在self._process_group_backend，随后在_get_process_group_backend中回退到_get_default_process_group_backend_for_device(self.root_device)（即根据设备类型推断默认后端，见 src/lightning/pytorch/strategies/ddp.py）。同样的参数也出现在DeepSpeedStrategy、FSDPStrategy、ModelParallelStrategy（见 src/lightning/pytorch/strategies/deepspeed.py、src/lightning/pytorch/strategies/fsdp.py、src/lightning/pytorch/strategies/model_parallel.py）中。CHANGELOG 中 src/lightning/pytorch/CHANGELOG.md 亦记录了该环境变量方式的移除。

这样做的好处是：后端选择成为策略对象的显式配置，与分布式环境、启动方式解耦，配置一目了然且可在同一进程内为不同策略指定不同后端。

五、精度插件：检查点钩子改为load_state_dict

PrecisionPlugin（现称Precision）的检查点相关钩子发生变更：

即把"加载 / 保存检查点"的职责从钩子形式统一为标准的state_dict/load_state_dict协议，与 PyTorch 模块的惯例保持一致。当前基类 src/lightning/pytorch/plugins/precision/precision.py 中class Precision(FabricPrecision, CheckpointHooks)；而具体插件，例如 AMP 插件，通过state_dict()返回GradScaler的状态、load_state_dict()恢复之（见 src/lightning/pytorch/plugins/precision/amp.py）：

@override def state_dict(self) -> dict[str, Any]: if self.scaler is not None: return self.scaler.state_dict() return {} @override def load_state_dict(self, state_dict: dict[str, Any]) -> None: if self.scaler is not None: self.scaler.load_state_dict(state_dict)

升级要点：如果你自定义了精度插件并覆写过on_load_checkpoint/on_save_checkpoint，请把它们重写为load_state_dict/state_dict。

六、性能分析器（Profiler）：基类合并，profile_iterable移除

6.1BaseProfiler→Profiler

旧的基类pytorch_lightning.profiler.BaseProfiler被合并为pytorch_lightning.profiler.Profiler。当前 src/lightning/pytorch/profilers/profiler.py 中的Profiler是一个抽象基类，定义了start(action_name)、stop(action_name)、summary()等抽象接口，并提供profile(action_name)上下文管理器、_prepare_filename、_prepare_streams、setup(stage, local_rank, log_dir)、teardown(stage)、describe()等通用基础设施。自定义分析器应继承Profiler并实现start/stop：

from lightning.pytorch.profilers import Profiler class MyProfiler(Profiler): def start(self, action_name: str) -> None: ... def stop(self, action_name: str) -> None: ... def summary(self) -> str: return "MyProfiler report"

6.2SimpleProfiler.profile_iterable/AdvancedProfiler.profile_iterable移除

这两个用于"包装可迭代对象并逐项计时"的辅助属性被删除。需要给可迭代对象逐项计时时，应改用Profiler.profile(action_name)上下文管理器包裹循环体内的工作（见 src/lightning/pytorch/profilers/profiler.py）：

profiler = MyProfiler() with profiler.profile("load training data"): # 加载/处理单个 batch 的代码 ...

SimpleProfiler与AdvancedProfiler本身继续存在（src/lightning/pytorch/profilers/simple.py、src/lightning/pytorch/profilers/advanced.py），只是不再提供profile_iterable。

七、重点行为变更：多优化器 + TBPTT 下outputs的维度交换

这是 1.7 中最容易在升级后"静默出错"的行为变更，涉及两个训练钩子的outputs参数维度顺序。

7.1on_train_batch_end(outputs, ...)：2D 列表维度交换

旧格式：outputs是形状为(n_optimizers, tbptt_steps)的 2D 列表； 新格式：outputs形状变为(tbptt_steps, n_optimizers)，即"优化器维度"与"TBPTT 时间步维度"互换。

# 旧写法：outputs[optimizer_idx][tbptt_step] def on_train_batch_end(self, outputs, batch, batch_idx): loss_opt0_step0 = outputs[0][0] # 新写法：outputs[tbptt_step][optimizer_idx] def on_train_batch_end(self, outputs, batch, batch_idx): loss_opt0_step0 = outputs[0][0]

注：仅当同时使用多个优化器且启用TBPTT时，该格式变更才生效；单一优化器或未开启 TBPTT 的场景不受影响。

7.2training_epoch_end(outputs)：3D 列表维度交换

旧格式：outputs形状为(n_optimizers, n_batches, tbptt_steps)； 新格式：形状变为(n_batches, tbptt_steps, n_optimizers)，即按"batch → tbptt 步 → 优化器"排列。

# 旧写法：outputs[optimizer_idx][batch_idx][tbptt_step] def training_epoch_end(self, outputs): ... # 新写法：outputs[batch_idx][tbptt_step][optimizer_idx] def training_epoch_end(self, outputs): ...

7.3 过渡期迁移开关：new_format=True

如果暂时不想改钩子内部的索引逻辑，可以在钩子签名中追加new_format=True参数临时使用新格式：

def on_train_batch_end(self, outputs, batch, batch_idx, new_format=True): # 直接按新维度顺序 (tbptt_steps, n_optimizers) 处理 ... def training_epoch_end(self, outputs, new_format=True): # 直接按新维度顺序 (n_batches, tbptt_steps, n_optimizers) 处理 ...

注意：new_format=True只是一个过渡兼容开关，最终都应迁移到新的维度顺序（即不带该参数、直接按新格式编写）。仓库 src/lightning/pytorch/CHANGELOG.md 记录了这两处格式废弃与替换的对应关系（PR #12182）。

八、回调与设备统计：DeviceStatsMonitor内部化键名前缀

device_stats_monitor.prefix_metric_keys这一公开属性在 1.7 被移除/内部化。从当前源码看，键名前缀逻辑已改为模块级私有函数_prefix_metric_keys(metrics_dict, prefix, separator)（src/lightning/pytorch/callbacks/device_stats_monitor.py），在回调内部把设备统计指标统一加上DeviceStatsMonitor.{hook_name}/前缀后交给 logger。DeviceStatsMonitor的公开 API 现在是cpu_stats与filter_keys两个构造参数（src/lightning/pytorch/callbacks/device_stats_monitor.py）：

from lightning.pytorch.callbacks import DeviceStatsMonitor # 只记录 GPU 显存的峰值与当前值 device_stats = DeviceStatsMonitor( filter_keys={"allocated_bytes.all.current", "allocated_bytes.all.peak"} ) trainer = Trainer(callbacks=[device_stats])

九、升级自查清单

把上述变更整理成一张可直接对照检查的清单：

1. 导入路径：全局搜索utilities.distributed与utilities.warnings中的rank_zero_*与LightningDeprecationWarning，统一改为from lightning.pytorch.utilities.rank_zero import ...。
2. 入口方法：确认代码中没有调用Trainer.run_stage，全部改用fit/validate/test/predict。
3. Trainer 属性：data_parallel_device_ids→device_ids；root_gpu→strategy.root_device.index；删除对should_rank_save_checkpoint、use_amp、verbose_evaluate、lightning_optimizers的引用。
4. 私有调用：不要从外部调用Trainer.call_hook；自定义插件/回调走标准钩子接口。
5. 分布式后端：删除PL_TORCH_DISTRIBUTED_BACKEND环境变量用法，改为DDPStrategy(process_group_backend=...)（DeepSpeed / FSDP / ModelParallel 同理）。
6. 精度插件：on_load_checkpoint→load_state_dict，on_save_checkpoint→state_dict。
7. Profiler：继承pytorch_lightning.profiler.Profiler；删除对BaseProfiler与profile_iterable的引用，改用profile()上下文管理器。
8. TBPTT 格式：多优化器 + TBPTT 场景下，按新维度顺序改写on_train_batch_end与training_epoch_end，过渡期可加new_format=True。

全部落实后，你的代码即可平滑升级到 1.7，并受益于更清晰的Trainer结构、统一的 rank 工具与更贴近 PyTorch 惯例的插件协议。若需结合版本间的历史迁移路径，可继续查阅仓库内的 docs/source-pytorch/upgrade/migration_guide.rst 与 docs/source-pytorch/upgrade/sections 目录下的其他版本小节。

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