tdrussell/diffusion-pipe

diffusion-pipe – パイプライン並列トレーニングによる拡散モデル用フレームワーク

概要

DeepSpeedのパイプライン並列処理を使用して、複数のGPUで大規模な拡散モデル（画像変換、テキストから画像、テキストから動画など）をトレーニングするためのオープンソースのトレーニングスクリプトです。
最近の拡散モデルファミリー（SDXL、Flux、Stable Diffusion 3、Qwen-Image、Cosmos、Hunyuan、MiniMax H3など）の幅広いリストをサポートし、画像データと動画データの両方で動作します。

主な機能

機能	重要性
パイプライン並列処理	単一のモデルを複数のGPUに分割し、1枚のカードに収まらないモデルでもトレーニング可能にします。
ハイブリッドデータ+パイプライン並列処理	残りのGPUをデータ並列処理に使用し、バッチサイズを自動的にスケーリングします。
TensorBoardロギングと評価指標	トレーニング中の損失、VRAM使用量、検証スコアを監視できます。
チェックポイントと再開	完全なトレーニング状態（重み、オプティマイザー、データローダー）を保存し、設定を再実行せずに任意のチェックポイントから再開できます。
潜在変数とテキスト埋め込みの事前キャッシュ	重いVAEおよびテキストエンコーダー処理を前処理ステップに移動し、メインモデル用のVRAMを解放します。
統一画像/動画パイプライン	静止画像と動画フレームの両方を同じコードパスで処理し、動画モデルではオプションでオーディオ処理もサポートします。
拡張可能なモデルインターフェース	新しい拡散モデルを追加するには、小さなサブクラスの実装のみが必要です。
低VRAMのテクニック	8ビットのAdamW、ブロックスワップ、アクティベーションチェックポイント、CUDAメモリアロケータのトリックを使用して、単一の24 GB GPUで140億パラメータのモデルをトレーニングする方法を示す設定例があります。

開始方法

リポジトリをクローン（サブモジュールを含む）

git clone --recurse-submodules https://github.com/tdrussell/diffusion-pipe

Conda環境を作成（Python 3.12が必要）

conda create -n diffusion-pipe python=3.12
conda activate diffusion-pipe

GPU/CUDAバージョンに一致するPyTorchをインストール（例：RTX 4090の場合torch==2.9.0+cu128）。

残りのPython依存関係をインストール

pip install -r requirements.txt
# 多くのモデルで推奨（オプション）
pip install flash-attn

（Cosmosビデオが必要な場合） READMEに記載されている環境変数のハックを使用してtransformer_engineをインストール。

トレーニングジョブの実行

examples/にあるサンプルTOML設定ファイル（メインはexamples/main_example.toml）を編集します。データセットのパス、出力ディレクトリ、学習率などを調整します。
DeepSpeedで起動します。例：
```
NCCL_P2P_DISABLE=1 NCCL_IB_DISABLE=1 \
deepspeed --num_gpus=4 train.py --deepspeed --config examples/hunyuan_video.toml
```
--num_gpusでDeepSpeedが使用するGPU数を指定します。設定内のpipeline_stagesで各モデルが分割されるパイプラインの数（分割数）を制御します。
再開するには、--resume_from_checkpoint <フォルダ>を追加し、まったく同じ設定ファイルを再利用します。

データ準備

メディアファイル（画像または動画）を1つ以上のディレクトリに整理します。
各メディアファイルに対して、同じベース名の.txtキャプションファイルを作成します。
画像はPillow互換の形式、動画はImageIO互換の形式（WebP動画は非対応）です。
スクリプトは、各データセットディレクトリ内のcache/サブフォルダにVAE潜在変数とCLIPスタイルのテキスト埋め込みをキャッシュします。

出力レイアウト

実行ごとに、output_dirの下に新しいサブフォルダが作成されます。
内部には以下があります：
- DeepSpeedチェックポイントフォルダ（global_stepXXXX）。
- safetensorsの重みとPEFTアダプターJSONを含むモデルスナップショット（epoch1/、epoch2/など）。
- 再現性のための元のdiffusion-pipe TOML設定。
- 損失/検証曲線用のTensorBoardイベントファイル。

プラットフォームに関する注意

Windowsネイティブでのトレーニングは、DeepSpeedのWindowsサポートが限られているため、おそらく機能しません。Windowsホストを使用する場合は、WSL 2を使用してください。

関連プロジェクト

作者は、大規模言語モデル用の同様のパイプライン並列トレーナーであるqlora-pipeもメンテナンスしています。

結論: diffusion-pipeは、単一GPUのメモリ予算を超える最先端の拡散モデルをトレーニングする必要がある研究者やエンジニアにとって、実用的で文書化がしっかりしたツールキットです。パイプライン並列処理、キャッシュ、チェックポイント管理の重い処理を処理し、データとハイパーパラメータに集中できます。