SuperAPI AI 工具集

pytorch-lightning

编程与开发

查看项目

更新于 10-21 16:24

技能介绍

用途

PyTorch Lightning 是一个深度学习框架,用于组织 PyTorch 代码,在保留完整灵活性的同时消除样板代码。它可自动化训练工作流、多设备编排,并实现神经网络训练与跨多 GPU/TPU 扩展的最佳实践。该技能适用于使用 PyTorch Lightning 构建、训练或部署神经网络,将 PyTorch 代码组织为 LightningModule,为多 GPU/TPU 训练配置 Trainer,使用 LightningDataModule 实现数据管道,处理回调、日志与分布式训练策略(DDP、FSDP、DeepSpeed),以及以专业方式组织深度学习项目。

版本与安装

当前上游版本为 lightning 2.6.4(PyPI,2026 年 5 月)。文档地址:lightning.ai/docs/pytorch/stable。使用 import lightning as L(pytorch-lightning 包名仍安装同一库)。

安装命令:

uv pip install lightning

可选扩展:

uv pip install lightning[extra] # loggers, strategies, etc. uv pip install wandb mlflow # specific loggers as needed

主要能力

1. LightningModule - 模型定义

将 PyTorch 模型组织为六个逻辑部分:初始化(init() 和 setup())、训练循环(training_step(batch, batch_idx))、验证循环(validation_step(batch, batch_idx))、测试循环(test_step(batch, batch_idx))、预测(predict_step(batch, batch_idx))、优化器配置(configure_optimizers())。完整样板可参考 scripts/template_lightning_module.py,详细方法、钩子、属性与最佳实践见 references/lightning_module.md。

2. Trainer - 训练自动化

Trainer 自动化训练循环、设备管理、梯度操作与回调。关键特性包括:多 GPU/TPU 支持与策略选择(DDP、FSDP、DeepSpeed)、自动混合精度训练、梯度累积与裁剪、检查点与早停、进度条与日志。常见配置见 scripts/quick_trainer_setup.py,全部参数、方法与配置选项见 references/trainer.md。

3. LightningDataModule - 数据管道组织

将所有数据处理步骤封装为可复用类:prepare_data()(下载与处理数据,单进程)、setup()(创建数据集并应用变换,每 GPU)、train_dataloader()、val_dataloader()、test_dataloader()。完整样板见 scripts/template_datamodule.py,方法细节与使用模式见 references/data_module.md。

4. Callbacks - 可扩展训练逻辑

在特定训练钩子处添加自定义功能,而无需修改 LightningModule。内置回调包括:ModelCheckpoint(保存最佳/最新模型)、EarlyStopping(指标停滞时停止)、LearningRateMonitor(跟踪学习率调度变化)、BatchSizeFinder(自动确定最优批大小)。内置回调与自定义回调创建见 references/callbacks.md。

5. Logging - 实验跟踪

可集成多种日志平台:TensorBoard(默认)、Weights & Biases(WandbLogger)、MLflow(MLFlowLogger)、Comet(CometLogger)、CSV(CSVLogger)。注意:NeptuneLogger 已在 lightning 2.6.4 中移除,请改用 W&B、MLflow 或 TensorBoard。在任意 LightningModule 方法中使用 self.log("metric_name", value) 记录指标。日志器设置与配置见 references/logging.md。

6. 分布式训练 - 扩展到多设备

根据模型规模选择合适策略:DDP 适用于小于 5 亿参数的模型(ResNet、较小的 transformer);FSDP 适用于 5 亿以上参数的模型(大型 transformer,推荐 Lightning 用户使用);DeepSpeed 适用于前沿特性与细粒度控制。配置方式:Trainer(strategy="ddp", accelerator="gpu", devices=4)。策略对比与配置见 references/distributed_training.md。

7. 最佳实践

设备无关代码:使用 self.device 而非 .cuda();超参数保存:在 init() 中使用 self.save_hyperparameters();指标日志:使用 self.log() 实现跨设备自动聚合;可复现性:使用 seed_everything() 与 Trainer(deterministic=True);调试:使用 Trainer(fast_dev_run=True) 以 1 个批次测试。常见模式与陷阱见 references/best_practices.md。

使用方式

快速工作流示例:

定义模型:

class MyModel(L.LightningModule): def init(self): super().init() self.save_hyperparameters() self.model = YourNetwork()

def training_step(self, batch, batch_idx):
    x, y = batch
    loss = F.cross_entropy(self.model(x), y)
    self.log("train_loss", loss)
    return loss

def configure_optimizers(self):
    return torch.optim.Adam(self.parameters())

准备数据:

Option 1: Direct DataLoaders

train_loader = DataLoader(train_dataset, batch_size=32)

Option 2: LightningDataModule (recommended for reusability)

dm = MyDataModule(batch_size=32)

训练:

trainer = L.Trainer(max_epochs=10, accelerator="gpu", devices=2) trainer.fit(model, train_loader) # or trainer.fit(model, datamodule=dm)

资源

scripts/ 目录提供常见 PyTorch Lightning 模式的可执行 Python 模板:template_lightning_module.py(完整 LightningModule 样板)、template_datamodule.py(完整 LightningDataModule 样板)、quick_trainer_setup.py(常见 Trainer 配置示例)。

references/ 目录提供各组件详细文档:lightning_module.md(LightningModule 综合指南:方法、钩子、属性)、trainer.md(Trainer 配置与参数)、data_module.md(LightningDataModule 模式与方法)、callbacks.md(内置与自定义回调)、logging.md(日志器集成与使用)、distributed_training.md(DDP、FSDP、DeepSpeed 对比与设置)、best_practices.md(常见模式、技巧与陷阱)。

适用场景

适用于使用 PyTorch Lightning 构建、训练或部署神经网络;将 PyTorch 代码组织为 LightningModule;为多 GPU/TPU 训练配置 Trainer;使用 LightningDataModule 实现数据管道;处理回调、日志与分布式训练策略;以专业方式组织深度学习项目。

限制与注意事项

Agent 操作流程要求:检查环境,确认 Python 环境与库版本(python -c "import pkg; print(pkg.version)")并检查数据形状、类型与缺失值;确定输入,从数据或用户处确认格式、标识符与参数,对任何会改变结果的取值应询问而非猜测;先运行小版本,在样本或单折上运行并检查运行时间与内存;使用上述说明与参考执行完整任务;验证结果,使用留出数据、固定随机种子与合适指标,检查泄漏,报告不确定性(置信区间、跨种子标准差);报告运行内容(版本、命令、参数)、已检查内容与仍不确定之处。

异常处理:内存不足或执行极慢时,进行子采样、使用分块或惰性计算,或减小模型规模,并告知用户所做的更改;若说明中的函数、标志或端点在已安装版本中缺失,应查阅已安装版本自身的文档(help()、--help、官方文档)并适配,同时告知用户,切勿臆造 API;若所需输入、标识符或参数不明确,应询问用户,或在运行前明确说明假设。

完整性规则:绝不捏造结果、参数、标识符、引用或统计;绝不报告本次会话中未计算的指标,展示产生每个数字的代码路径;将此处版本相关细节视为可能过时,对照已安装版本的官方文档确认;在涉及花钱、消耗共享 GPU 或云配额、触及个人或患者数据、或不可撤销的操作前应先询问。

相关技能:huggingface-accelerate、pytorch-lightning-distributed、experiment-tracking-swanlab。