Skip to content

Commit 8f5a2eb

Browse files
committed
Add documentation for LoRA training scripts for SD1/2, SDXL, FLUX.1 and SD3/3.5 models
1 parent 5a18a03 commit 8f5a2eb

File tree

4 files changed

+723
-0
lines changed

4 files changed

+723
-0
lines changed

docs/flux_train_network.md

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# `flux_train_network.py` を用いたFLUX.1モデルのLoRA学習ガイド
2+
3+
このドキュメントでは、`sd-scripts`リポジトリに含まれる`flux_train_network.py`を使用して、FLUX.1モデルに対するLoRA (Low-Rank Adaptation) モデルを学習する基本的な手順について解説します。
4+
5+
## 1. はじめに
6+
7+
`flux_train_network.py`は、FLUX.1モデルに対してLoRAなどの追加ネットワークを学習させるためのスクリプトです。FLUX.1はStable Diffusionとは異なるアーキテクチャを持つ画像生成モデルであり、このスクリプトを使用することで、特定のキャラクターや画風を再現するLoRAモデルを作成できます。
8+
9+
このガイドは、基本的なLoRA学習の手順を理解しているユーザーを対象とし、`train_network.py`での学習経験があることを前提としています。基本的な使い方や共通のオプションについては、[`train_network.py`のガイド](how_to_use_train_network.md)を参照してください。
10+
11+
**前提条件:**
12+
13+
* `sd-scripts`リポジトリのクローンとPython環境のセットアップが完了していること。
14+
* 学習用データセットの準備が完了していること。(データセットの準備については[データセット設定ガイド](link/to/dataset/config/doc)を参照してください)
15+
16+
## 2. `train_network.py` との違い
17+
18+
`flux_train_network.py``train_network.py`をベースに、FLUX.1モデルに対応するための変更が加えられています。主な違いは以下の通りです。
19+
20+
* **対象モデル:** FLUX.1モデル(dev版またはschnell版)を対象とします。
21+
* **モデル構造:** Stable Diffusionとは異なり、FLUX.1はTransformerベースのアーキテクチャを持ちます。Text EncoderとしてCLIP-LとT5-XXLの二つを使用し、VAEの代わりに専用のAutoEncoder (AE) を使用します。
22+
* **必須の引数:** FLUX.1モデル、CLIP-L、T5-XXL、AEの各モデルファイルを指定する引数が追加されています。
23+
* **一部引数の非互換性:** Stable Diffusion向けの引数の一部(例: `--v2`, `--clip_skip`, `--max_token_length`)はFLUX.1の学習では使用されません。
24+
* **FLUX.1特有の引数:** タイムステップのサンプリング方法やガイダンススケールなど、FLUX.1特有の学習パラメータを指定する引数が追加されています。
25+
26+
## 3. 準備
27+
28+
学習を開始する前に、以下のファイルが必要です。
29+
30+
1. **学習スクリプト:** `flux_train_network.py`
31+
2. **FLUX.1モデルファイル:** 学習のベースとなるFLUX.1モデルの`.safetensors`ファイル(例: `flux1-dev.safetensors`)。
32+
3. **Text Encoderモデルファイル:**
33+
* CLIP-Lモデルの`.safetensors`ファイル。
34+
* T5-XXLモデルの`.safetensors`ファイル。
35+
4. **AutoEncoderモデルファイル:** FLUX.1に対応するAEモデルの`.safetensors`ファイル。
36+
5. **データセット定義ファイル (.toml):** 学習データセットの設定を記述したTOML形式のファイル。(詳細は[データセット設定ガイド](link/to/dataset/config/doc)を参照してください)。
37+
38+
* 例として`my_flux_dataset_config.toml`を使用します。
39+
40+
## 4. 学習の実行
41+
42+
学習は、ターミナルから`flux_train_network.py`を実行することで開始します。基本的なコマンドラインの構造は`train_network.py`と同様ですが、FLUX.1特有の引数を指定する必要があります。
43+
44+
以下に、基本的なコマンドライン実行例を示します。
45+
46+
```bash
47+
accelerate launch --num_cpu_threads_per_process 1 flux_train_network.py
48+
--pretrained_model_name_or_path="<path to FLUX.1 model>"
49+
--clip_l="<path to CLIP-L model>"
50+
--t5xxl="<path to T5-XXL model>"
51+
--ae="<path to AE model>"
52+
--dataset_config="my_flux_dataset_config.toml"
53+
--output_dir="<output directory for training results>"
54+
--output_name="my_flux_lora"
55+
--save_model_as=safetensors
56+
--network_module=networks.lora
57+
--network_dim=16
58+
--network_alpha=1
59+
--learning_rate=1e-4
60+
--optimizer_type="AdamW8bit"
61+
--lr_scheduler="constant"
62+
--sdpa
63+
--max_train_epochs=10
64+
--save_every_n_epochs=1
65+
--mixed_precision="fp16"
66+
--gradient_checkpointing
67+
--apply_t5_attn_mask
68+
--blocks_to_swap=18
69+
```
70+
71+
※実際には1行で書くか、適切な改行文字(`\` または `^`)を使用してください。
72+
73+
### 4.1. 主要なコマンドライン引数の解説(`train_network.py`からの追加・変更点)
74+
75+
[`train_network.py`のガイド](how_to_use_train_network.md)で説明されている引数に加え、以下のFLUX.1特有の引数を指定します。共通の引数(`--output_dir`, `--output_name`, `--network_module`, `--network_dim`, `--network_alpha`, `--learning_rate`など)については、上記ガイドを参照してください。
76+
77+
#### モデル関連 [必須]
78+
79+
* `--pretrained_model_name_or_path="<path to FLUX.1 model>"` **[必須]**
80+
* 学習のベースとなるFLUX.1モデル(dev版またはschnell版)の`.safetensors`ファイルのパスを指定します。Diffusers形式のディレクトリは現在サポートされていません。
81+
* `--clip_l="<path to CLIP-L model>"` **[必須]**
82+
* CLIP-L Text Encoderモデルの`.safetensors`ファイルのパスを指定します。
83+
* `--t5xxl="<path to T5-XXL model>"` **[必須]**
84+
* T5-XXL Text Encoderモデルの`.safetensors`ファイルのパスを指定します。
85+
* `--ae="<path to AE model>"` **[必須]**
86+
* FLUX.1に対応するAutoEncoderモデルの`.safetensors`ファイルのパスを指定します。
87+
88+
#### FLUX.1 学習パラメータ
89+
90+
* `--t5xxl_max_token_length=<integer>`
91+
* T5-XXL Text Encoderで使用するトークンの最大長を指定します。省略した場合、モデルがschnell版なら256、dev版なら512が自動的に設定されます。データセットのキャプション長に合わせて調整が必要な場合があります。
92+
* `--apply_t5_attn_mask`
93+
* T5-XXLの出力とFLUXモデル内部(Double Block)のアテンション計算時に、パディングトークンに対応するアテンションマスクを適用します。精度向上が期待できる場合がありますが、わずかに計算コストが増加します。
94+
* `--guidance_scale=<float>`
95+
* FLUX.1 dev版は特定のガイダンススケール値で蒸留されているため、学習時にもその値を指定します。デフォルトは`3.5`です。schnell版では通常無視されます。
96+
* `--timestep_sampling=<choice>`
97+
* 学習時に使用するタイムステップ(ノイズレベル)のサンプリング方法を指定します。`sigma`, `uniform`, `sigmoid`, `shift`, `flux_shift` から選択します。デフォルトは `sigma` です。
98+
* `--sigmoid_scale=<float>`
99+
* `timestep_sampling``sigmoid` または `shift`, `flux_shift` を指定した場合のスケール係数です。デフォルトは`1.0`です。
100+
* `--model_prediction_type=<choice>`
101+
* モデルが何を予測するかを指定します。`raw` (予測値をそのまま使用), `additive` (ノイズ入力に加算), `sigma_scaled` (シグマスケーリングを適用) から選択します。デフォルトは `sigma_scaled` です。
102+
* `--discrete_flow_shift=<float>`
103+
* Flow Matchingで使用されるスケジューラのシフト値を指定します。デフォルトは`3.0`です。
104+
105+
#### メモリ・速度関連
106+
107+
* `--blocks_to_swap=<integer>` **[実験的機能]**
108+
* VRAM使用量を削減するために、モデルの一部(Transformerブロック)をCPUとGPU間でスワップする設定です。スワップするブロック数を整数で指定します(例: `18`)。値を大きくするとVRAM使用量は減りますが、学習速度は低下します。GPUのVRAM容量に応じて調整してください。`gradient_checkpointing`と併用可能です。
109+
* `--cpu_offload_checkpointing`とは併用できません。
110+
111+
#### 非互換・非推奨の引数
112+
113+
* `--v2`, `--v_parameterization`, `--clip_skip`: Stable Diffusion特有の引数のため、FLUX.1学習では使用されません。
114+
* `--max_token_length`: Stable Diffusion v1/v2向けの引数です。FLUX.1では`--t5xxl_max_token_length`を使用してください。
115+
* `--split_mode`: 非推奨の引数です。代わりに`--blocks_to_swap`を使用してください。
116+
117+
### 4.2. 学習の開始
118+
119+
必要な引数を設定し、コマンドを実行すると学習が開始されます。基本的な流れやログの確認方法は[`train_network.py`のガイド](how_to_use_train_network.md#32-starting-the-training--学習の開始)と同様です。
120+
121+
## 5. 学習済みモデルの利用
122+
123+
学習が完了すると、指定した`output_dir`にLoRAモデルファイル(例: `my_flux_lora.safetensors`)が保存されます。このファイルは、FLUX.1モデルに対応した推論環境(例: ComfyUI + ComfyUI-FluxNodes)で使用できます。
124+
125+
## 6. その他
126+
127+
`flux_train_network.py`には、サンプル画像の生成 (`--sample_prompts`など) や詳細なオプティマイザ設定など、`train_network.py`と共通の機能も多く存在します。これらについては、[`train_network.py`のガイド](how_to_use_train_network.md#5-other-features--その他の機能)やスクリプトのヘルプ (`python flux_train_network.py --help`) を参照してください。

docs/sd3_train_network.md

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# `sd3_train_network.py` を用いたStable Diffusion 3/3.5モデルのLoRA学習ガイド
2+
3+
このドキュメントでは、`sd-scripts`リポジトリに含まれる`sd3_train_network.py`を使用して、Stable Diffusion 3 (SD3) および Stable Diffusion 3.5 (SD3.5) モデルに対するLoRA (Low-Rank Adaptation) モデルを学習する基本的な手順について解説します。
4+
5+
## 1. はじめに
6+
7+
`sd3_train_network.py`は、Stable Diffusion 3/3.5モデルに対してLoRAなどの追加ネットワークを学習させるためのスクリプトです。SD3は、MMDiT (Multi-Modal Diffusion Transformer) と呼ばれる新しいアーキテクチャを採用しており、従来のStable Diffusionモデルとは構造が異なります。このスクリプトを使用することで、SD3/3.5モデルに特化したLoRAモデルを作成できます。
8+
9+
このガイドは、基本的なLoRA学習の手順を理解しているユーザーを対象とし、`train_network.py`での学習経験があることを前提としています。基本的な使い方や共通のオプションについては、[`train_network.py`のガイド](how_to_use_train_network.md)を参照してください。
10+
11+
**前提条件:**
12+
13+
* `sd-scripts`リポジトリのクローンとPython環境のセットアップが完了していること。
14+
* 学習用データセットの準備が完了していること。(データセットの準備については[データセット設定ガイド](link/to/dataset/config/doc)を参照してください)
15+
* 学習対象のSD3/3.5モデルファイルが準備できていること。
16+
17+
## 2. `train_network.py` との違い
18+
19+
`sd3_train_network.py``train_network.py`をベースに、SD3/3.5モデルに対応するための変更が加えられています。主な違いは以下の通りです。
20+
21+
* **対象モデル:** Stable Diffusion 3 Medium / Large (3.0 / 3.5) モデルを対象とします。
22+
* **モデル構造:** U-Netの代わりにMMDiT (Transformerベース) を使用します。Text EncoderとしてCLIP-L, CLIP-G, T5-XXLの三つを使用します。VAEはSDXLと互換性がありますが、入力のスケール処理が異なります。
23+
* **引数:** SD3/3.5モデル、Text Encoder群、VAEを指定する引数があります。ただし、単一ファイルの`.safetensors`形式であれば、内部で自動的に分離されるため、個別のパス指定は必須ではありません。
24+
* **一部引数の非互換性:** Stable Diffusion v1/v2向けの引数(例: `--v2`, `--v_parameterization`, `--clip_skip`)はSD3/3.5の学習では使用されません。
25+
* **SD3特有の引数:** Text Encoderのアテンションマスクやドロップアウト率、Positional Embeddingの調整(SD3.5向け)、タイムステップのサンプリングや損失の重み付けに関する引数が追加されています。
26+
27+
## 3. 準備
28+
29+
学習を開始する前に、以下のファイルが必要です。
30+
31+
1. **学習スクリプト:** `sd3_train_network.py`
32+
2. **SD3/3.5モデルファイル:** 学習のベースとなるSD3/3.5モデルの`.safetensors`ファイル。単一ファイル形式(Diffusers/ComfyUI/AUTOMATIC1111形式)を推奨します。
33+
* Text EncoderやVAEが別ファイルになっている場合は、対応する引数でパスを指定します。
34+
3. **データセット定義ファイル (.toml):** 学習データセットの設定を記述したTOML形式のファイル。(詳細は[データセット設定ガイド](link/to/dataset/config/doc)を参照してください)。
35+
* 例として`my_sd3_dataset_config.toml`を使用します。
36+
37+
## 4. 学習の実行
38+
39+
学習は、ターミナルから`sd3_train_network.py`を実行することで開始します。基本的なコマンドラインの構造は`train_network.py`と同様ですが、SD3/3.5特有の引数を指定する必要があります。
40+
41+
以下に、基本的なコマンドライン実行例を示します。
42+
43+
```bash
44+
accelerate launch --num_cpu_threads_per_process 1 sd3_train_network.py
45+
--pretrained_model_name_or_path="<path to SD3 model>"
46+
--dataset_config="my_sd3_dataset_config.toml"
47+
--output_dir="<output directory for training results>"
48+
--output_name="my_sd3_lora"
49+
--save_model_as=safetensors
50+
--network_module=networks.lora
51+
--network_dim=16
52+
--network_alpha=1
53+
--learning_rate=1e-4
54+
--optimizer_type="AdamW8bit"
55+
--lr_scheduler="constant"
56+
--sdpa
57+
--max_train_epochs=10
58+
--save_every_n_epochs=1
59+
--mixed_precision="fp16"
60+
--gradient_checkpointing
61+
--apply_lg_attn_mask
62+
--apply_t5_attn_mask
63+
--weighting_scheme="sigma_sqrt"
64+
--blocks_to_swap=32
65+
```
66+
67+
※実際には1行で書くか、適切な改行文字(`\` または `^`)を使用してください。
68+
69+
### 4.1. 主要なコマンドライン引数の解説(`train_network.py`からの追加・変更点)
70+
71+
[`train_network.py`のガイド](how_to_use_train_network.md)で説明されている引数に加え、以下のSD3/3.5特有の引数を指定します。共通の引数(`--output_dir`, `--output_name`, `--network_module`, `--network_dim`, `--network_alpha`, `--learning_rate`など)については、上記ガイドを参照してください。
72+
73+
#### モデル関連
74+
75+
* `--pretrained_model_name_or_path="<path to SD3 model>"` **[必須]**
76+
* 学習のベースとなるSD3/3.5モデルの`.safetensors`ファイルのパスを指定します。単一ファイル形式(Diffusers/ComfyUI/AUTOMATIC1111形式)を想定しています。
77+
* `--clip_l`, `--clip_g`, `--t5xxl`, `--vae`:
78+
* ベースモデルが単一ファイル形式の場合、通常これらの指定は不要です(自動的にモデル内部から読み込まれます)。
79+
* もしText EncoderやVAEが別ファイルとして提供されている場合は、それぞれの`.safetensors`ファイルのパスを指定します。
80+
81+
#### SD3/3.5 学習パラメータ
82+
83+
* `--t5xxl_max_token_length=<integer>`
84+
* T5-XXL Text Encoderで使用するトークンの最大長を指定します。SD3のデフォルトは`256`です。データセットのキャプション長に合わせて調整が必要な場合があります。
85+
* `--apply_lg_attn_mask`
86+
* CLIP-LおよびCLIP-Gの出力に対して、パディングトークンに対応するアテンションマスク(ゼロ埋め)を適用します。
87+
* `--apply_t5_attn_mask`
88+
* T5-XXLの出力に対して、パディングトークンに対応するアテンションマスク(ゼロ埋め)を適用します。
89+
* `--clip_l_dropout_rate`, `--clip_g_dropout_rate`, `--t5_dropout_rate`:
90+
* 各Text Encoderの出力に対して、指定した確率でドロップアウト(出力をゼロにする)を適用します。過学習の抑制に役立つ場合があります。デフォルトは`0.0`(ドロップアウトなし)です。
91+
* `--pos_emb_random_crop_rate=<float>` **[SD3.5向け]**
92+
* MMDiTのPositional Embeddingに対してランダムクロップを適用する確率を指定します。SD3 5M (3.5) モデルで学習された機能であり、他のモデルでの効果は限定的です。デフォルトは`0.0`です。
93+
* `--enable_scaled_pos_embed` **[SD3.5向け]**
94+
* マルチ解像度学習時に、解像度に応じてPositional Embeddingをスケーリングします。SD3 5M (3.5) モデルで学習された機能であり、他のモデルでの効果は限定的です。
95+
* `--training_shift=<float>`
96+
* 学習時のタイムステップ(ノイズレベル)の分布を調整するためのシフト値です。`weighting_scheme`に加えて適用されます。`1.0`より大きい値はノイズの大きい(構造寄り)領域を、小さい値はノイズの小さい(詳細寄り)領域を重視する傾向になります。デフォルトは`1.0`です。
97+
* `--weighting_scheme=<choice>`
98+
* 損失計算時のタイムステップ(ノイズレベル)に応じた重み付け方法を指定します。`sigma_sqrt`, `logit_normal`, `mode`, `cosmap`, `uniform` (または`none`) から選択します。SD3の論文では`sigma_sqrt`が使用されています。デフォルトは`uniform`です。
99+
* `--logit_mean`, `--logit_std`, `--mode_scale`:
100+
* `weighting_scheme``logit_normal`または`mode`を選択した場合に、その分布を制御するためのパラメータです。通常はデフォルト値で問題ありません。
101+
102+
#### メモリ・速度関連
103+
104+
* `--blocks_to_swap=<integer>` **[実験的機能]**
105+
* VRAM使用量を削減するために、モデルの一部(MMDiTのTransformerブロック)をCPUとGPU間でスワップする設定です。スワップするブロック数を整数で指定します(例: `32`)。値を大きくするとVRAM使用量は減りますが、学習速度は低下します。GPUのVRAM容量に応じて調整してください。`gradient_checkpointing`と併用可能です。
106+
* `--cpu_offload_checkpointing`とは併用できません。
107+
108+
#### 非互換・非推奨の引数
109+
110+
* `--v2`, `--v_parameterization`, `--clip_skip`: Stable Diffusion v1/v2特有の引数のため、SD3/3.5学習では使用されません。
111+
112+
### 4.2. 学習の開始
113+
114+
必要な引数を設定し、コマンドを実行すると学習が開始されます。基本的な流れやログの確認方法は[`train_network.py`のガイド](how_to_use_train_network.md#32-starting-the-training--学習の開始)と同様です。
115+
116+
## 5. 学習済みモデルの利用
117+
118+
学習が完了すると、指定した`output_dir`にLoRAモデルファイル(例: `my_sd3_lora.safetensors`)が保存されます。このファイルは、SD3/3.5モデルに対応した推論環境(例: ComfyUIなど)で使用できます。
119+
120+
## 6. その他
121+
122+
`sd3_train_network.py`には、サンプル画像の生成 (`--sample_prompts`など) や詳細なオプティマイザ設定など、`train_network.py`と共通の機能も多く存在します。これらについては、[`train_network.py`のガイド](how_to_use_train_network.md#5-other-features--その他の機能)やスクリプトのヘルプ (`python sd3_train_network.py --help`) を参照してください。

0 commit comments

Comments
 (0)