pytorch-lightning

PyTorch Lightning

概要

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

現在のアップストリーム： 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

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

次のような場合にこのスキルを使用してください：

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

主な機能

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 は、学習ループ、デバイス管理、勾配処理、コールバックを自動化します。主な機能：

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

クイックセットアップのリファレンス： 一般的な 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（デフォルト）
• 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、小規模なトランスフォーマー）向け
• FSDP - パラメーター数が5億以上のモデル（大規模なトランスフォーマー向け。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 - よく使われるパターン、ヒント、落とし穴

エージェントの作業手順

1. 環境を確認します。 Python 環境とライブラリのバージョン（python -c "import pkg; print(pkg.__version__)"）を確認し、データの形状、型、欠損値を調べます。
2. 入力を明確にします。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果に影響する値は推測せず、質問してください。
3. まず小規模に実行します。 最初はサンプルまたは単一のフォールドで実行し、実行時間とメモリを確認します。
4. 上記の指示と参考資料を使用して、タスク全体を実行します。
5. 結果を検証します。 ホールドアウトデータ、固定した乱数シード、適切なメトリクスを使用し、データリークがないか確認して、不確実性（信頼区間、シード間の標準偏差）を報告します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確認の事項を明記します。

このような場合	次のように対応します
メモリ不足、または実行が非常に遅い	サブサンプリング、チャンク化または遅延計算を使用するか、モデルサイズを小さくし、変更内容をユーザーに伝えます。
これらの指示にある関数、フラグ、エンドポイントがインストール済みのバージョンにない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して対応し、ユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに質問するか、実行前に前提を明示します。

整合性に関するルール

• 結果、パラメーター、識別子、引用、統計情報を捏造してはいけません。実行または検証できないことがあれば、率直に伝えます。
• このセッションで算出していないメトリクスを報告してはいけません。数値ごとに、その算出に使ったコードの経路を示します。
• ここに記載されたバージョン固有の情報は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認します。
• 費用が発生する、共有 GPU やクラウドのクォータを消費する、個人データや患者データを扱う、または取り消せない操作を行う前に、必ず許可を求めます。

関連スキル

• huggingface-accelerate：既存の PyTorch トレーニングスクリプトを HuggingFace Accelerate（Accelerator クラス、accelerate config、accelerate launch）でラップし、同じ c…
• pytorch-lightning-distributed：Trainer クラス、自動分散トレーニング（DDP/FSDP/DeepSpeed）、コールバックシステム、最小限のボイラープ…
• experiment-tracking-swanlab：SwanLab を使って ML 実験を追跡するオープンソースツールです。swanlab.init、設定とメトリクスのログ記録、スカラーグラフ、メディアのログ記録…