alterlab-pytorch-lightning

PyTorch Lightning

概要

PyTorch Lightning は、柔軟性を完全に維持しながら定型コードをなくすために、PyTorch のコードを整理するディープラーニングフレームワークです。トレーニングワークフローや複数デバイスのオーケストレーションを自動化し、ニューラルネットワークのトレーニングと複数の GPU／TPU へのスケーリングに関するベストプラクティスを実装できます。

uv pip install lightning   # provides `import lightning as L` and `lightning.pytorch.*`

このスキルのすべてのコードでは、統合された lightning パッケージを使用します。別途公開されている pytorch-lightning パッケージをインストールすると、古い pytorch_lightning 名前空間が使われます。2 つの名前空間を同じプロジェクトで混在させないでください。クラスが別物であるためです（たとえば、lightning.Trainer.fit に pytorch_lightning.LightningModule を渡すと TypeError が発生します）。

このスキルを使用する場面

以下の場合にこのスキルを使用してください：

• PyTorch Lightning を使用してニューラルネットワークを構築、トレーニング、またはデプロイする
• PyTorch のコードを LightningModule に整理する
• 複数 GPU／TPU でのトレーニングに向けて Trainer を設定する
• LightningDataModule を使ってデータパイプラインを実装する
• コールバック、ロギング、分散トレーニング戦略（DDP、FSDP、DeepSpeed）を扱う
• ディープラーニングプロジェクトをプロフェッショナルな形に構成する

対象外

シナリオ	代わりに使用するもの
transformers の Trainer／パイプラインを使用して、事前学習済みの Hugging Face モデルをファインチューニングする	alterlab-transformers
グラフニューラルネットワークのレイヤーを設計する、またはグラフデータセットを読み込む（GCN、GAT、メッセージパッシング）	alterlab-torch-geometric
環境上でトレーニングする強化学習エージェント（PPO、SAC、DQN）	alterlab-stable-baselines3
表形式データに対する従来型の ML（ランダムフォレスト、勾配ブースティング、線形モデル）	alterlab-scikit-learn

主な機能

1. LightningModule - モデル定義

PyTorch モデルを、次の 6 つの論理的なセクションに整理します。

1. 初期化 - __init__() と setup()
2. トレーニングループ - training_step(batch, batch_idx)
3. 検証ループ - validation_step(batch, batch_idx)
4. テストループ - test_step(batch, batch_idx)
5. 予測 - predict_step(batch, batch_idx)
6. オプティマイザーの設定 - configure_optimizers()

クイックテンプレートリファレンス： 完全な定型コードについては、scripts/template_lightning_module.py を参照してください。

詳細ドキュメント： メソッド、フック、プロパティ、ベストプラクティスに関する包括的なドキュメントは、references/lightning_module.md を参照してください。

2. Trainer - トレーニングの自動化

Trainer は、トレーニングループ、デバイス管理、勾配処理、コールバックを自動化します。主な機能は次のとおりです。

• 戦略を選択して複数 GPU／TPU に対応（DDP、FSDP、DeepSpeed）
• 自動混合精度トレーニング
• 勾配の累積とクリッピング
• チェックポイントの保存と早期停止
• プログレスバーとロギング

クイックセットアップリファレンス： 一般的な Trainer の設定については、scripts/quick_trainer_setup.py を参照してください。

詳細ドキュメント： すべてのパラメーター、メソッド、設定オプションについては、references/trainer.md を参照してください。

3. LightningDataModule - データパイプラインの整理

すべてのデータ処理手順を、再利用可能なクラスにカプセル化します。

1. prepare_data() - データをダウンロードして処理する（単一プロセス）
2. setup() - データセットを作成し、変換を適用する（GPU ごと）
3. train_dataloader() - トレーニング用 DataLoader を返す
4. val_dataloader() - 検証用 DataLoader を返す
5. test_dataloader() - テスト用 DataLoader を返す

クイックテンプレートリファレンス： 完全な定型コードについては、scripts/template_datamodule.py を参照してください。

詳細ドキュメント： メソッドの詳細と使用パターンについては、references/data_module.md を参照してください。

4. コールバック - 拡張可能なトレーニングロジック

LightningModule を変更せずに、特定のトレーニングフックでカスタム機能を追加できます。組み込みのコールバックには次のものがあります。

• ModelCheckpoint - 最良または最新のモデルを保存します
• EarlyStopping - メトリクスが停滞したときに停止します
• LearningRateMonitor - LR スケジューラーの変更を追跡します
• BatchSizeFinder - 最適なバッチサイズを自動的に決定します

詳細なドキュメント： 組み込みコールバックとカスタムコールバックの作成については、references/callbacks.md をご覧ください。

5. ロギング - 実験の追跡

複数のロギングプラットフォームと連携できます。

• TensorBoard（tensorboard がインストールされている場合のデフォルト。未インストールの場合は CSV）
• Weights & Biases（WandbLogger）
• MLflow（MLFlowLogger）
• Comet（CometLogger）
• CSV（CSVLogger）

Neptune のホスト型サービスが終了したため（2026 年 3 月）、Lightning 2.6.4 で NeptuneLogger は削除されました。

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. ベストプラクティス

• デバイスに依存しないコード - .cuda() の代わりに self.device を使用します
• ハイパーパラメーターの保存 - __init__() で self.save_hyperparameters() を使用します
• メトリクスのロギング - デバイス間の自動集計には self.log() を使用します
• 再現性 - seed_everything() と Trainer(deterministic=True) を使用します
• デバッグ - Trainer(fast_dev_run=True) を使用して 1 バッチでテストします

詳細なドキュメント： 一般的なパターンと注意点については、references/best_practices.md をご覧ください。

クイックワークフロー

1. モデルを定義：

   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())
   

2. データを準備：

   # Option 1: Direct DataLoaders
   train_loader = DataLoader(train_dataset, batch_size=32)
   
   # Option 2: LightningDataModule (recommended for reusability)
   dm = MyDataModule(batch_size=32)
   

3. トレーニング：

   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/

各 PyTorch Lightning コンポーネントの詳細なドキュメントです。

• lightning_module.md - LightningModule の包括的なガイド（メソッド、フック、プロパティ）
• trainer.md - Trainer の設定とパラメーター
• data_module.md - LightningDataModule のパターンとメソッド
• callbacks.md - 組み込みおよびカスタムのコールバック
• logging.md - ロガーとの連携と使用方法
• distributed_training.md - DDP、FSDP、DeepSpeed の比較とセットアップ
• best_practices.md - 一般的なパターン、ヒント、注意点