Add documentation for LoRA training scripts for SD1/2, SDXL, FLUX.1 and SD3/3.5 models

This commit is contained in:
Kohya S
2025-04-11 08:07:24 +09:00
parent 5a18a03ffc
commit 8f5a2eba3d
4 changed files with 723 additions and 0 deletions

127
docs/flux_train_network.md Normal file
View File

@@ -0,0 +1,127 @@
# `flux_train_network.py` を用いたFLUX.1モデルのLoRA学習ガイド
このドキュメントでは、`sd-scripts`リポジトリに含まれる`flux_train_network.py`を使用して、FLUX.1モデルに対するLoRA (Low-Rank Adaptation) モデルを学習する基本的な手順について解説します。
## 1. はじめに
`flux_train_network.py`は、FLUX.1モデルに対してLoRAなどの追加ネットワークを学習させるためのスクリプトです。FLUX.1はStable Diffusionとは異なるアーキテクチャを持つ画像生成モデルであり、このスクリプトを使用することで、特定のキャラクターや画風を再現するLoRAモデルを作成できます。
このガイドは、基本的なLoRA学習の手順を理解しているユーザーを対象とし、`train_network.py`での学習経験があることを前提としています。基本的な使い方や共通のオプションについては、[`train_network.py`のガイド](how_to_use_train_network.md)を参照してください。
**前提条件:**
* `sd-scripts`リポジトリのクローンとPython環境のセットアップが完了していること。
* 学習用データセットの準備が完了していること。(データセットの準備については[データセット設定ガイド](link/to/dataset/config/doc)を参照してください)
## 2. `train_network.py` との違い
`flux_train_network.py``train_network.py`をベースに、FLUX.1モデルに対応するための変更が加えられています。主な違いは以下の通りです。
* **対象モデル:** FLUX.1モデルdev版またはschnell版を対象とします。
* **モデル構造:** Stable Diffusionとは異なり、FLUX.1はTransformerベースのアーキテクチャを持ちます。Text EncoderとしてCLIP-LとT5-XXLの二つを使用し、VAEの代わりに専用のAutoEncoder (AE) を使用します。
* **必須の引数:** FLUX.1モデル、CLIP-L、T5-XXL、AEの各モデルファイルを指定する引数が追加されています。
* **一部引数の非互換性:** Stable Diffusion向けの引数の一部例: `--v2`, `--clip_skip`, `--max_token_length`はFLUX.1の学習では使用されません。
* **FLUX.1特有の引数:** タイムステップのサンプリング方法やガイダンススケールなど、FLUX.1特有の学習パラメータを指定する引数が追加されています。
## 3. 準備
学習を開始する前に、以下のファイルが必要です。
1. **学習スクリプト:** `flux_train_network.py`
2. **FLUX.1モデルファイル:** 学習のベースとなるFLUX.1モデルの`.safetensors`ファイル(例: `flux1-dev.safetensors`)。
3. **Text Encoderモデルファイル:**
* CLIP-Lモデルの`.safetensors`ファイル。
* T5-XXLモデルの`.safetensors`ファイル。
4. **AutoEncoderモデルファイル:** FLUX.1に対応するAEモデルの`.safetensors`ファイル。
5. **データセット定義ファイル (.toml):** 学習データセットの設定を記述したTOML形式のファイル。詳細は[データセット設定ガイド](link/to/dataset/config/doc)を参照してください)。
* 例として`my_flux_dataset_config.toml`を使用します。
## 4. 学習の実行
学習は、ターミナルから`flux_train_network.py`を実行することで開始します。基本的なコマンドラインの構造は`train_network.py`と同様ですが、FLUX.1特有の引数を指定する必要があります。
以下に、基本的なコマンドライン実行例を示します。
```bash
accelerate launch --num_cpu_threads_per_process 1 flux_train_network.py
--pretrained_model_name_or_path="<path to FLUX.1 model>"
--clip_l="<path to CLIP-L model>"
--t5xxl="<path to T5-XXL model>"
--ae="<path to AE model>"
--dataset_config="my_flux_dataset_config.toml"
--output_dir="<output directory for training results>"
--output_name="my_flux_lora"
--save_model_as=safetensors
--network_module=networks.lora
--network_dim=16
--network_alpha=1
--learning_rate=1e-4
--optimizer_type="AdamW8bit"
--lr_scheduler="constant"
--sdpa
--max_train_epochs=10
--save_every_n_epochs=1
--mixed_precision="fp16"
--gradient_checkpointing
--apply_t5_attn_mask
--blocks_to_swap=18
```
※実際には1行で書くか、適切な改行文字`\` または `^`)を使用してください。
### 4.1. 主要なコマンドライン引数の解説(`train_network.py`からの追加・変更点)
[`train_network.py`のガイド](how_to_use_train_network.md)で説明されている引数に加え、以下のFLUX.1特有の引数を指定します。共通の引数(`--output_dir`, `--output_name`, `--network_module`, `--network_dim`, `--network_alpha`, `--learning_rate`など)については、上記ガイドを参照してください。
#### モデル関連 [必須]
* `--pretrained_model_name_or_path="<path to FLUX.1 model>"` **[必須]**
* 学習のベースとなるFLUX.1モデルdev版またはschnell版`.safetensors`ファイルのパスを指定します。Diffusers形式のディレクトリは現在サポートされていません。
* `--clip_l="<path to CLIP-L model>"` **[必須]**
* CLIP-L Text Encoderモデルの`.safetensors`ファイルのパスを指定します。
* `--t5xxl="<path to T5-XXL model>"` **[必須]**
* T5-XXL Text Encoderモデルの`.safetensors`ファイルのパスを指定します。
* `--ae="<path to AE model>"` **[必須]**
* FLUX.1に対応するAutoEncoderモデルの`.safetensors`ファイルのパスを指定します。
#### FLUX.1 学習パラメータ
* `--t5xxl_max_token_length=<integer>`
* T5-XXL Text Encoderで使用するトークンの最大長を指定します。省略した場合、モデルがschnell版なら256、dev版なら512が自動的に設定されます。データセットのキャプション長に合わせて調整が必要な場合があります。
* `--apply_t5_attn_mask`
* T5-XXLの出力とFLUXモデル内部Double Blockのアテンション計算時に、パディングトークンに対応するアテンションマスクを適用します。精度向上が期待できる場合がありますが、わずかに計算コストが増加します。
* `--guidance_scale=<float>`
* FLUX.1 dev版は特定のガイダンススケール値で蒸留されているため、学習時にもその値を指定します。デフォルトは`3.5`です。schnell版では通常無視されます。
* `--timestep_sampling=<choice>`
* 学習時に使用するタイムステップ(ノイズレベル)のサンプリング方法を指定します。`sigma`, `uniform`, `sigmoid`, `shift`, `flux_shift` から選択します。デフォルトは `sigma` です。
* `--sigmoid_scale=<float>`
* `timestep_sampling``sigmoid` または `shift`, `flux_shift` を指定した場合のスケール係数です。デフォルトは`1.0`です。
* `--model_prediction_type=<choice>`
* モデルが何を予測するかを指定します。`raw` (予測値をそのまま使用), `additive` (ノイズ入力に加算), `sigma_scaled` (シグマスケーリングを適用) から選択します。デフォルトは `sigma_scaled` です。
* `--discrete_flow_shift=<float>`
* Flow Matchingで使用されるスケジューラのシフト値を指定します。デフォルトは`3.0`です。
#### メモリ・速度関連
* `--blocks_to_swap=<integer>` **[実験的機能]**
* VRAM使用量を削減するために、モデルの一部TransformerブロックをCPUとGPU間でスワップする設定です。スワップするブロック数を整数で指定します例: `18`。値を大きくするとVRAM使用量は減りますが、学習速度は低下します。GPUのVRAM容量に応じて調整してください。`gradient_checkpointing`と併用可能です。
* `--cpu_offload_checkpointing`とは併用できません。
#### 非互換・非推奨の引数
* `--v2`, `--v_parameterization`, `--clip_skip`: Stable Diffusion特有の引数のため、FLUX.1学習では使用されません。
* `--max_token_length`: Stable Diffusion v1/v2向けの引数です。FLUX.1では`--t5xxl_max_token_length`を使用してください。
* `--split_mode`: 非推奨の引数です。代わりに`--blocks_to_swap`を使用してください。
### 4.2. 学習の開始
必要な引数を設定し、コマンドを実行すると学習が開始されます。基本的な流れやログの確認方法は[`train_network.py`のガイド](how_to_use_train_network.md#32-starting-the-training--学習の開始)と同様です。
## 5. 学習済みモデルの利用
学習が完了すると、指定した`output_dir`にLoRAモデルファイル例: `my_flux_lora.safetensors`が保存されます。このファイルは、FLUX.1モデルに対応した推論環境(例: ComfyUI + ComfyUI-FluxNodesで使用できます。
## 6. その他
`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`) を参照してください。

122
docs/sd3_train_network.md Normal file
View File

@@ -0,0 +1,122 @@
# `sd3_train_network.py` を用いたStable Diffusion 3/3.5モデルのLoRA学習ガイド
このドキュメントでは、`sd-scripts`リポジトリに含まれる`sd3_train_network.py`を使用して、Stable Diffusion 3 (SD3) および Stable Diffusion 3.5 (SD3.5) モデルに対するLoRA (Low-Rank Adaptation) モデルを学習する基本的な手順について解説します。
## 1. はじめに
`sd3_train_network.py`は、Stable Diffusion 3/3.5モデルに対してLoRAなどの追加ネットワークを学習させるためのスクリプトです。SD3は、MMDiT (Multi-Modal Diffusion Transformer) と呼ばれる新しいアーキテクチャを採用しており、従来のStable Diffusionモデルとは構造が異なります。このスクリプトを使用することで、SD3/3.5モデルに特化したLoRAモデルを作成できます。
このガイドは、基本的なLoRA学習の手順を理解しているユーザーを対象とし、`train_network.py`での学習経験があることを前提としています。基本的な使い方や共通のオプションについては、[`train_network.py`のガイド](how_to_use_train_network.md)を参照してください。
**前提条件:**
* `sd-scripts`リポジトリのクローンとPython環境のセットアップが完了していること。
* 学習用データセットの準備が完了していること。(データセットの準備については[データセット設定ガイド](link/to/dataset/config/doc)を参照してください)
* 学習対象のSD3/3.5モデルファイルが準備できていること。
## 2. `train_network.py` との違い
`sd3_train_network.py``train_network.py`をベースに、SD3/3.5モデルに対応するための変更が加えられています。主な違いは以下の通りです。
* **対象モデル:** Stable Diffusion 3 Medium / Large (3.0 / 3.5) モデルを対象とします。
* **モデル構造:** U-Netの代わりにMMDiT (Transformerベース) を使用します。Text EncoderとしてCLIP-L, CLIP-G, T5-XXLの三つを使用します。VAEはSDXLと互換性がありますが、入力のスケール処理が異なります。
* **引数:** SD3/3.5モデル、Text Encoder群、VAEを指定する引数があります。ただし、単一ファイルの`.safetensors`形式であれば、内部で自動的に分離されるため、個別のパス指定は必須ではありません。
* **一部引数の非互換性:** Stable Diffusion v1/v2向けの引数例: `--v2`, `--v_parameterization`, `--clip_skip`はSD3/3.5の学習では使用されません。
* **SD3特有の引数:** Text Encoderのアテンションマスクやドロップアウト率、Positional Embeddingの調整SD3.5向け)、タイムステップのサンプリングや損失の重み付けに関する引数が追加されています。
## 3. 準備
学習を開始する前に、以下のファイルが必要です。
1. **学習スクリプト:** `sd3_train_network.py`
2. **SD3/3.5モデルファイル:** 学習のベースとなるSD3/3.5モデルの`.safetensors`ファイル。単一ファイル形式Diffusers/ComfyUI/AUTOMATIC1111形式を推奨します。
* Text EncoderやVAEが別ファイルになっている場合は、対応する引数でパスを指定します。
3. **データセット定義ファイル (.toml):** 学習データセットの設定を記述したTOML形式のファイル。詳細は[データセット設定ガイド](link/to/dataset/config/doc)を参照してください)。
* 例として`my_sd3_dataset_config.toml`を使用します。
## 4. 学習の実行
学習は、ターミナルから`sd3_train_network.py`を実行することで開始します。基本的なコマンドラインの構造は`train_network.py`と同様ですが、SD3/3.5特有の引数を指定する必要があります。
以下に、基本的なコマンドライン実行例を示します。
```bash
accelerate launch --num_cpu_threads_per_process 1 sd3_train_network.py
--pretrained_model_name_or_path="<path to SD3 model>"
--dataset_config="my_sd3_dataset_config.toml"
--output_dir="<output directory for training results>"
--output_name="my_sd3_lora"
--save_model_as=safetensors
--network_module=networks.lora
--network_dim=16
--network_alpha=1
--learning_rate=1e-4
--optimizer_type="AdamW8bit"
--lr_scheduler="constant"
--sdpa
--max_train_epochs=10
--save_every_n_epochs=1
--mixed_precision="fp16"
--gradient_checkpointing
--apply_lg_attn_mask
--apply_t5_attn_mask
--weighting_scheme="sigma_sqrt"
--blocks_to_swap=32
```
※実際には1行で書くか、適切な改行文字`\` または `^`)を使用してください。
### 4.1. 主要なコマンドライン引数の解説(`train_network.py`からの追加・変更点)
[`train_network.py`のガイド](how_to_use_train_network.md)で説明されている引数に加え、以下のSD3/3.5特有の引数を指定します。共通の引数(`--output_dir`, `--output_name`, `--network_module`, `--network_dim`, `--network_alpha`, `--learning_rate`など)については、上記ガイドを参照してください。
#### モデル関連
* `--pretrained_model_name_or_path="<path to SD3 model>"` **[必須]**
* 学習のベースとなるSD3/3.5モデルの`.safetensors`ファイルのパスを指定します。単一ファイル形式Diffusers/ComfyUI/AUTOMATIC1111形式を想定しています。
* `--clip_l`, `--clip_g`, `--t5xxl`, `--vae`:
* ベースモデルが単一ファイル形式の場合、通常これらの指定は不要です(自動的にモデル内部から読み込まれます)。
* もしText EncoderやVAEが別ファイルとして提供されている場合は、それぞれの`.safetensors`ファイルのパスを指定します。
#### SD3/3.5 学習パラメータ
* `--t5xxl_max_token_length=<integer>`
* T5-XXL Text Encoderで使用するトークンの最大長を指定します。SD3のデフォルトは`256`です。データセットのキャプション長に合わせて調整が必要な場合があります。
* `--apply_lg_attn_mask`
* CLIP-LおよびCLIP-Gの出力に対して、パディングトークンに対応するアテンションマスクゼロ埋めを適用します。
* `--apply_t5_attn_mask`
* T5-XXLの出力に対して、パディングトークンに対応するアテンションマスクゼロ埋めを適用します。
* `--clip_l_dropout_rate`, `--clip_g_dropout_rate`, `--t5_dropout_rate`:
* 各Text Encoderの出力に対して、指定した確率でドロップアウト出力をゼロにするを適用します。過学習の抑制に役立つ場合があります。デフォルトは`0.0`(ドロップアウトなし)です。
* `--pos_emb_random_crop_rate=<float>` **[SD3.5向け]**
* MMDiTのPositional Embeddingに対してランダムクロップを適用する確率を指定します。SD3 5M (3.5) モデルで学習された機能であり、他のモデルでの効果は限定的です。デフォルトは`0.0`です。
* `--enable_scaled_pos_embed` **[SD3.5向け]**
* マルチ解像度学習時に、解像度に応じてPositional Embeddingをスケーリングします。SD3 5M (3.5) モデルで学習された機能であり、他のモデルでの効果は限定的です。
* `--training_shift=<float>`
* 学習時のタイムステップ(ノイズレベル)の分布を調整するためのシフト値です。`weighting_scheme`に加えて適用されます。`1.0`より大きい値はノイズの大きい(構造寄り)領域を、小さい値はノイズの小さい(詳細寄り)領域を重視する傾向になります。デフォルトは`1.0`です。
* `--weighting_scheme=<choice>`
* 損失計算時のタイムステップ(ノイズレベル)に応じた重み付け方法を指定します。`sigma_sqrt`, `logit_normal`, `mode`, `cosmap`, `uniform` (または`none`) から選択します。SD3の論文では`sigma_sqrt`が使用されています。デフォルトは`uniform`です。
* `--logit_mean`, `--logit_std`, `--mode_scale`:
* `weighting_scheme``logit_normal`または`mode`を選択した場合に、その分布を制御するためのパラメータです。通常はデフォルト値で問題ありません。
#### メモリ・速度関連
* `--blocks_to_swap=<integer>` **[実験的機能]**
* VRAM使用量を削減するために、モデルの一部MMDiTのTransformerブロックをCPUとGPU間でスワップする設定です。スワップするブロック数を整数で指定します例: `32`。値を大きくするとVRAM使用量は減りますが、学習速度は低下します。GPUのVRAM容量に応じて調整してください。`gradient_checkpointing`と併用可能です。
* `--cpu_offload_checkpointing`とは併用できません。
#### 非互換・非推奨の引数
* `--v2`, `--v_parameterization`, `--clip_skip`: Stable Diffusion v1/v2特有の引数のため、SD3/3.5学習では使用されません。
### 4.2. 学習の開始
必要な引数を設定し、コマンドを実行すると学習が開始されます。基本的な流れやログの確認方法は[`train_network.py`のガイド](how_to_use_train_network.md#32-starting-the-training--学習の開始)と同様です。
## 5. 学習済みモデルの利用
学習が完了すると、指定した`output_dir`にLoRAモデルファイル例: `my_sd3_lora.safetensors`が保存されます。このファイルは、SD3/3.5モデルに対応した推論環境(例: ComfyUIなどで使用できます。
## 6. その他
`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`) を参照してください。

160
docs/sdxl_train_network.md Normal file
View File

@@ -0,0 +1,160 @@
はい、承知いたしました。`sd-scripts` リポジトリに含まれる `sdxl_train_network.py` を使用した SDXL LoRA 学習に関するドキュメントを作成します。`how_to_use_train_network.md` との差分を中心に、初心者ユーザー向けに解説します。
---
# SDXL LoRA学習スクリプト `sdxl_train_network.py` の使い方
このドキュメントでは、`sd-scripts` リポジトリに含まれる `sdxl_train_network.py` を使用して、SDXL (Stable Diffusion XL) モデルに対する LoRA (Low-Rank Adaptation) モデルを学習する基本的な手順について解説します。
## 1. はじめに
`sdxl_train_network.py` は、SDXL モデルに対して LoRA などの追加ネットワークを学習させるためのスクリプトです。基本的な使い方は `train_network.py` ([LoRA学習スクリプト `train_network.py` の使い方](how_to_use_train_network.md) 参照) と共通ですが、SDXL モデル特有の設定が必要となります。
このガイドでは、SDXL LoRA 学習に焦点を当て、`train_network.py` との主な違いや SDXL 特有の設定項目を中心に説明します。
**前提条件:**
* `sd-scripts` リポジトリのクローンと Python 環境のセットアップが完了していること。
* 学習用データセットの準備が完了していること。(データセットの準備については[データセット準備ガイド](link/to/dataset/doc)を参照してください)
* [LoRA学習スクリプト `train_network.py` の使い方](how_to_use_train_network.md) を一読していること。
## 2. 準備
学習を開始する前に、以下のファイルが必要です。
1. **学習スクリプト:** `sdxl_train_network.py`
2. **データセット定義ファイル (.toml):** 学習データセットの設定を記述した TOML 形式のファイル。
### データセット定義ファイルについて
データセット定義ファイル (`.toml`) の基本的な書き方は `train_network.py` と共通です。[データセット設定ガイド](link/to/dataset/config/doc) および [LoRA学習スクリプト `train_network.py` の使い方](how_to_use_train_network.md#データセット定義ファイルについて) を参照してください。
SDXL では、高解像度のデータセットや、アスペクト比バケツ機能 (`enable_bucket = true`) の利用が一般的です。
ここでは、例として `my_sdxl_dataset_config.toml` という名前のファイルを使用することにします。
## 3. 学習の実行
学習は、ターミナルから `sdxl_train_network.py` を実行することで開始します。
以下に、SDXL LoRA 学習における基本的なコマンドライン実行例を示します。
```bash
accelerate launch --num_cpu_threads_per_process 1 sdxl_train_network.py
--pretrained_model_name_or_path="<SDXLベースモデルのパス>"
--dataset_config="my_sdxl_dataset_config.toml"
--output_dir="<学習結果の出力先ディレクトリ>"
--output_name="my_sdxl_lora"
--save_model_as=safetensors
--network_module=networks.lora
--network_dim=32
--network_alpha=16
--learning_rate=1e-4
--unet_lr=1e-4
--text_encoder_lr1=1e-5
--text_encoder_lr2=1e-5
--optimizer_type="AdamW8bit"
--lr_scheduler="constant"
--max_train_epochs=10
--save_every_n_epochs=1
--mixed_precision="bf16"
--gradient_checkpointing
--cache_text_encoder_outputs
--cache_latents
```
`train_network.py` の実行例と比較すると、以下の点が異なります。
* 実行するスクリプトが `sdxl_train_network.py` になります。
* `--pretrained_model_name_or_path` には SDXL のベースモデルを指定します。
* `--text_encoder_lr``--text_encoder_lr1``--text_encoder_lr2` に分かれていますSDXL は2つの Text Encoder を持つため)。
* `--mixed_precision``bf16` または `fp16` が推奨されます。
* `--cache_text_encoder_outputs``--cache_latents` は VRAM 使用量を削減するために推奨されます。
次に、`train_network.py` との差分となる主要なコマンドライン引数について解説します。共通の引数については、[LoRA学習スクリプト `train_network.py` の使い方](how_to_use_train_network.md#31-主要なコマンドライン引数) を参照してください。
### 3.1. 主要なコマンドライン引数(差分)
#### モデル関連
* `--pretrained_model_name_or_path="<モデルのパス>"` **[必須]**
* 学習のベースとなる **SDXL モデル**を指定します。Hugging Face Hub のモデル ID (例: `"stabilityai/stable-diffusion-xl-base-1.0"`) や、ローカルの Diffusers 形式モデルのディレクトリ、`.safetensors` ファイルのパスを指定できます。
* `--v2`, `--v_parameterization`
* これらの引数は SD1.x/2.x 用です。`sdxl_train_network.py` を使用する場合、SDXL モデルであることが前提となるため、通常は**指定する必要はありません**。
#### データセット関連
* `--dataset_config="<設定ファイルのパス>"`
* `train_network.py` と共通です。
* SDXL では高解像度データやバケツ機能 (`.toml``enable_bucket = true` を指定) の利用が一般的です。
#### 出力・保存関連
* `train_network.py` と共通です。
#### LoRA パラメータ
* `train_network.py` と共通です。
#### 学習パラメータ
* `--learning_rate=1e-4`
* 全体の学習率。`unet_lr`, `text_encoder_lr1`, `text_encoder_lr2` が指定されない場合のデフォルト値となります。
* `--unet_lr=1e-4`
* U-Net 部分の LoRA モジュールに対する学習率。指定しない場合は `--learning_rate` の値が使用されます。
* `--text_encoder_lr1=1e-5`
* **Text Encoder 1 (OpenCLIP ViT-G/14) の LoRA モジュール**に対する学習率。指定しない場合は `--learning_rate` の値が使用されます。U-Net より小さめの値が推奨されます。
* `--text_encoder_lr2=1e-5`
* **Text Encoder 2 (CLIP ViT-L/14) の LoRA モジュール**に対する学習率。指定しない場合は `--learning_rate` の値が使用されます。U-Net より小さめの値が推奨されます。
* `--optimizer_type="AdamW8bit"`
* `train_network.py` と共通です。
* `--lr_scheduler="constant"`
* `train_network.py` と共通です。
* `--lr_warmup_steps`
* `train_network.py` と共通です。
* `--max_train_steps`, `--max_train_epochs`
* `train_network.py` と共通です。
* `--mixed_precision="bf16"`
* 混合精度学習の設定。SDXL では `bf16` または `fp16` の使用が推奨されます。GPU が対応している方を選択してください。VRAM 使用量を削減し、学習速度を向上させます。
* `--gradient_accumulation_steps=1`
* `train_network.py` と共通です。
* `--gradient_checkpointing`
* `train_network.py` と共通です。SDXL はメモリ消費が大きいため、有効にすることが推奨されます。
* `--cache_latents`
* VAE の出力をメモリ(または `--cache_latents_to_disk` 指定時はディスクにキャッシュします。VAE の計算を省略できるため、VRAM 使用量を削減し、学習を高速化できます。画像に対する Augmentation (`--color_aug`, `--flip_aug`, `--random_crop` 等) が無効になります。SDXL 学習では推奨されるオプションです。
* `--cache_latents_to_disk`
* `--cache_latents` と併用し、キャッシュ先をディスクにします。データセットを最初に読み込む際に、VAE の出力をディスクにキャッシュします。二回目以降の学習で VAE の計算を省略できるため、学習データの枚数が多い場合に推奨されます。
* `--cache_text_encoder_outputs`
* Text Encoder の出力をメモリ(または `--cache_text_encoder_outputs_to_disk` 指定時はディスクにキャッシュします。Text Encoder の計算を省略できるため、VRAM 使用量を削減し、学習を高速化できます。キャプションに対する Augmentation (`--shuffle_caption`, `--caption_dropout_rate` 等) が無効になります。
* **注意:** このオプションを使用する場合、Text Encoder の LoRA モジュールは学習できません (`--network_train_unet_only` の指定が必須です)。
* `--cache_text_encoder_outputs_to_disk`
* `--cache_text_encoder_outputs` と併用し、キャッシュ先をディスクにします。
* `--no_half_vae`
* 混合精度 (`fp16`/`bf16`) 使用時でも VAE を `float32` で動作させます。SDXL の VAE は `float16` で不安定になることがあるため、`fp16` 指定時には有効にしてくだ
* `--clip_skip`
* SDXL では通常使用しません。指定は不要です。
* `--fused_backward_pass`
* 勾配計算とオプティマイザのステップを融合し、VRAM使用量を削減します。SDXLで利用可能です。現在 `Adafactor` オプティマイザのみ対応)
#### その他
* `--seed`, `--logging_dir`, `--log_prefix` などは `train_network.py` と共通です。
### 3.2. 学習の開始
必要な引数を設定し、コマンドを実行すると学習が開始されます。学習の進行状況はコンソールに出力されます。基本的な流れは `train_network.py` と同じです。
## 4. 学習済みモデルの利用
学習が完了すると、`output_dir` で指定したディレクトリに、`output_name` で指定した名前の LoRA モデルファイル (`.safetensors` など) が保存されます。
このファイルは、AUTOMATIC1111/stable-diffusion-webui 、ComfyUI などの SDXL に対応した GUI ツールで利用できます。
## 5. 補足: `train_network.py` との主な違い
* **対象モデル:** `sdxl_train_network.py` は SDXL モデル専用です。
* **Text Encoder:** SDXL は 2 つの Text Encoder を持つため、学習率の指定 (`--text_encoder_lr1`, `--text_encoder_lr2`) などが異なります。
* **キャッシュ機能:** `--cache_text_encoder_outputs` は SDXL で特に効果が高く、推奨されます。
* **推奨設定:** VRAM 使用量が大きいため、`bf16` または `fp16` の混合精度、`gradient_checkpointing`、キャッシュ機能 (`--cache_latents`, `--cache_text_encoder_outputs`) の利用が推奨されます。`fp16` 指定時は、VAE は `--no_half_vae``float32` 動作を推奨します。
その他の詳細なオプションについては、スクリプトのヘルプ (`python sdxl_train_network.py --help`) やリポジトリ内の他のドキュメントを参照してください。

314
docs/train_network.md Normal file
View File

@@ -0,0 +1,314 @@
# How to use the LoRA training script `train_network.py` / LoRA学習スクリプト `train_network.py` の使い方
This document explains the basic procedures for training LoRA (Low-Rank Adaptation) models using `train_network.py` included in the `sd-scripts` repository.
<details>
<summary>日本語</summary>
このドキュメントでは、`sd-scripts` リポジトリに含まれる `train_network.py` を使用して LoRA (Low-Rank Adaptation) モデルを学習する基本的な手順について解説します。
</details>
## 1. Introduction / はじめに
`train_network.py` is a script for training additional networks such as LoRA on Stable Diffusion models (v1.x, v2.x). It allows for additional training on the original model with a low computational cost, enabling the creation of models that reproduce specific characters or art styles.
This guide focuses on LoRA training and explains the basic configuration items.
**Prerequisites:**
* The `sd-scripts` repository has been cloned and the Python environment has been set up.
* The training dataset has been prepared. (For dataset preparation, please refer to [this guide](link/to/dataset/doc))
<details>
<summary>日本語</summary>
`train_network.py` は、Stable Diffusion モデルv1.x, v2.xに対して、LoRA などの追加ネットワークを学習させるためのスクリプトです。少ない計算コストで元のモデルに追加学習を行い、特定のキャラクターや画風を再現するモデルを作成できます。
このガイドでは、LoRA 学習に焦点を当て、基本的な設定項目を中心に説明します。
**前提条件:**
* `sd-scripts` リポジトリのクローンと Python 環境のセットアップが完了していること。
* 学習用データセットの準備が完了していること。(データセットの準備については[こちら](link/to/dataset/doc)を参照してください)
</details>
## 2. Preparation / 準備
Before starting training, you will need the following files:
1. **Training script:** `train_network.py`
2. **Dataset definition file (.toml):** A file in TOML format that describes the configuration of the training dataset.
### About the Dataset Definition File / データセット定義ファイルについて
The dataset definition file (`.toml`) contains detailed settings such as the directory of images to use, repetition count, caption settings, resolution buckets (optional), etc.
For more details on how to write the dataset definition file, please refer to the [Dataset Configuration Guide](link/to/dataset/config/doc).
In this guide, we will use a file named `my_dataset_config.toml` as an example.
<details>
<summary>日本語</summary>
学習を開始する前に、以下のファイルが必要です。
1. **学習スクリプト:** `train_network.py`
2. **データセット定義ファイル (.toml):** 学習データセットの設定を記述した TOML 形式のファイル。
**データセット定義ファイルについて**
データセット定義ファイル (`.toml`) には、使用する画像のディレクトリ、繰り返し回数、キャプションの設定、解像度バケツ(任意)などの詳細な設定を記述します。
データセット定義ファイルの詳しい書き方については、[データセット設定ガイド](link/to/dataset/config/doc)を参照してください。
ここでは、例として `my_dataset_config.toml` という名前のファイルを使用することにします。
</details>
## 3. Running the Training / 学習の実行
Training is started by executing `train_network.py` from the terminal. When executing, various training settings are specified as command-line arguments.
Below is a basic command-line execution example:
```bash
accelerate launch --num_cpu_threads_per_process 1 train_network.py
--pretrained_model_name_or_path="<path to Stable Diffusion model>"
--dataset_config="my_dataset_config.toml"
--output_dir="<output directory for training results>"
--output_name="my_lora"
--save_model_as=safetensors
--network_module=networks.lora
--network_dim=16
--network_alpha=1
--learning_rate=1e-4
--optimizer_type="AdamW8bit"
--lr_scheduler="constant"
--sdpa
--max_train_epochs=10
--save_every_n_epochs=1
--mixed_precision="fp16"
--gradient_checkpointing
```
In reality, you need to write this in a single line, but it's shown with line breaks for readability (on Linux or Mac, you can add `\` at the end of each line to break lines). For Windows, either write it in a single line without breaks or add `^` at the end of each line.
Next, we'll explain the main command-line arguments.
<details>
<summary>日本語</summary>
学習は、ターミナルから `train_network.py` を実行することで開始します。実行時には、学習に関する様々な設定をコマンドライン引数として指定します。
以下に、基本的なコマンドライン実行例を示します。
実際には1行で書く必要がありますが、見やすさのために改行していますLinux や Mac では `\` を行末に追加することで改行できます。Windows の場合は、改行せずに1行で書くか、`^` を行末に追加してください。
次に、主要なコマンドライン引数について解説します。
</details>
### 3.1. Main Command-Line Arguments / 主要なコマンドライン引数
#### Model Related / モデル関連
* `--pretrained_model_name_or_path="<path to model>"` **[Required]**
* Specifies the Stable Diffusion model to be used as the base for training. You can specify the path to a local `.ckpt` or `.safetensors` file, or a directory containing a Diffusers format model. You can also specify a Hugging Face Hub model ID (e.g., `"stabilityai/stable-diffusion-2-1-base"`).
* `--v2`
* Specify this when the base model is Stable Diffusion v2.x.
* `--v_parameterization`
* Specify this when training with a v-prediction model (such as v2.x 768px models).
#### Dataset Related / データセット関連
* `--dataset_config="<path to configuration file>"`
* Specifies the path to a `.toml` file describing the dataset configuration. (For details on dataset configuration, see [here](link/to/dataset/config/doc))
* It's also possible to specify dataset settings from the command line, but using a `.toml` file is recommended as it becomes lengthy.
#### Output and Save Related / 出力・保存関連
* `--output_dir="<output directory>"` **[Required]**
* Specifies the directory where trained LoRA models, sample images, logs, etc. will be output.
* `--output_name="<output filename>"` **[Required]**
* Specifies the filename of the trained LoRA model (excluding the extension).
* `--save_model_as="safetensors"`
* Specifies the format for saving the model. You can choose from `safetensors` (recommended), `ckpt`, or `pt`. The default is `safetensors`.
* `--save_every_n_epochs=1`
* Saves the model every specified number of epochs. If not specified, only the final model will be saved.
* `--save_every_n_steps=1000`
* Saves the model every specified number of steps. If both epoch and step saving are specified, both will be saved.
#### LoRA Parameters / LoRA パラメータ
* `--network_module=networks.lora` **[Required]**
* Specifies the type of network to train. For LoRA, specify `networks.lora`.
* `--network_dim=16` **[Required]**
* Specifies the rank (dimension) of LoRA. Higher values increase expressiveness but also increase file size and computational cost. Values between 4 and 128 are commonly used. There is no default (module dependent).
* `--network_alpha=1`
* Specifies the alpha value for LoRA. This parameter is related to learning rate scaling. It is generally recommended to set it to about half the value of `network_dim`, but it can also be the same value as `network_dim`. The default is 1. Setting it to the same value as `network_dim` will result in behavior similar to older versions.
#### Training Parameters / 学習パラメータ
* `--learning_rate=1e-4`
* Specifies the learning rate. For LoRA training (when alpha value is 1), relatively higher values (e.g., from `1e-4` to `1e-3`) are often used.
* `--unet_lr=1e-4`
* Used to specify a separate learning rate for the LoRA modules in the U-Net part. If not specified, the value of `--learning_rate` is used.
* `--text_encoder_lr=1e-5`
* Used to specify a separate learning rate for the LoRA modules in the Text Encoder part. If not specified, the value of `--learning_rate` is used. A smaller value than that for U-Net is recommended.
* `--optimizer_type="AdamW8bit"`
* Specifies the optimizer to use for training. Options include `AdamW8bit` (requires `bitsandbytes`), `AdamW`, `Lion` (requires `lion-pytorch`), `DAdaptation` (requires `dadaptation`), and `Adafactor`. `AdamW8bit` is memory-efficient and widely used.
* `--lr_scheduler="constant"`
* Specifies the learning rate scheduler. This is the method for changing the learning rate as training progresses. Options include `constant` (no change), `cosine` (cosine curve), `linear` (linear decay), `constant_with_warmup` (constant with warmup), and `cosine_with_restarts`. `constant`, `cosine`, and `constant_with_warmup` are commonly used.
* `--lr_warmup_steps=500`
* Specifies the number of warmup steps for the learning rate scheduler. This is the period during which the learning rate gradually increases at the start of training. Valid when the `lr_scheduler` supports warmup.
* `--max_train_steps=10000`
* Specifies the total number of training steps. If `max_train_epochs` is specified, that takes precedence.
* `--max_train_epochs=12`
* Specifies the number of training epochs. If this is specified, `max_train_steps` is ignored.
* `--sdpa`
* Uses Scaled Dot-Product Attention. This can reduce memory usage and improve training speed for LoRA training.
* `--mixed_precision="fp16"`
* Specifies the mixed precision training setting. Options are `no` (disabled), `fp16` (half precision), and `bf16` (bfloat16). If your GPU supports it, specifying `fp16` or `bf16` can improve training speed and reduce memory usage.
* `--gradient_accumulation_steps=1`
* Specifies the number of steps to accumulate gradients. This effectively increases the batch size to `train_batch_size * gradient_accumulation_steps`. Set a larger value if GPU memory is insufficient. Usually `1` is fine.
#### Others / その他
* `--seed=42`
* Specifies the random seed. Set this if you want to ensure reproducibility of the training.
* `--logging_dir="<log directory>"`
* Specifies the directory to output logs for TensorBoard, etc. If not specified, logs will not be output.
* `--log_prefix="<prefix>"`
* Specifies the prefix for the subdirectory name created within `logging_dir`.
* `--gradient_checkpointing`
* Enables Gradient Checkpointing. This can significantly reduce memory usage but slightly decreases training speed. Useful when memory is limited.
* `--clip_skip=1`
* Specifies how many layers to skip from the last layer of the Text Encoder. Specifying `2` will use the output from the second-to-last layer. `None` or `1` means no skip (uses the last layer). Check the recommended value for the model you are training.
<details>
<summary>日本語</summary>
#### モデル関連
* `--pretrained_model_name_or_path="<モデルのパス>"` **[必須]**
* 学習のベースとなる Stable Diffusion モデルを指定します。ローカルの `.ckpt` または `.safetensors` ファイルのパス、あるいは Diffusers 形式モデルのディレクトリを指定できます。Hugging Face Hub のモデル ID (例: `"stabilityai/stable-diffusion-2-1-base"`) も指定可能です。
* `--v2`
* ベースモデルが Stable Diffusion v2.x の場合に指定します。
* `--v_parameterization`
* v-prediction モデルv2.x の 768px モデルなど)で学習する場合に指定します。
#### データセット関連
* `--dataset_config="<設定ファイルのパス>"`
* データセット設定を記述した `.toml` ファイルのパスを指定します。(データセット設定の詳細は[こちら](link/to/dataset/config/doc)
* コマンドラインからデータセット設定を指定することも可能ですが、長くなるため `.toml` ファイルを使用することを推奨します。
#### 出力・保存関連
* `--output_dir="<出力先ディレクトリ>"` **[必須]**
* 学習済み LoRA モデルやサンプル画像、ログなどが出力されるディレクトリを指定します。
* `--output_name="<出力ファイル名>"` **[必須]**
* 学習済み LoRA モデルのファイル名(拡張子を除く)を指定します。
* `--save_model_as="safetensors"`
* モデルの保存形式を指定します。`safetensors` (推奨), `ckpt`, `pt` から選択できます。デフォルトは `safetensors` です。
* `--save_every_n_epochs=1`
* 指定したエポックごとにモデルを保存します。省略するとエポックごとの保存は行われません(最終モデルのみ保存)。
* `--save_every_n_steps=1000`
* 指定したステップごとにモデルを保存します。エポック指定 (`save_every_n_epochs`) と同時に指定された場合、両方とも保存されます。
#### LoRA パラメータ
* `--network_module=networks.lora` **[必須]**
* 学習するネットワークの種別を指定します。LoRA の場合は `networks.lora` を指定します。
* `--network_dim=16` **[必須]**
* LoRA のランク (rank / 次元数) を指定します。値が大きいほど表現力は増しますが、ファイルサイズと計算コストが増加します。一般的には 4〜128 程度の値が使われます。デフォルトは指定されていません(モジュール依存)。
* `--network_alpha=1`
* LoRA のアルファ値 (alpha) を指定します。学習率のスケーリングに関係するパラメータで、一般的には `network_dim` の半分程度の値を指定することが推奨されますが、`network_dim` と同じ値を指定する場合もあります。デフォルトは 1 です。`network_dim` と同じ値に設定すると、旧バージョンと同様の挙動になります。
#### 学習パラメータ
* `--learning_rate=1e-4`
* 学習率を指定します。LoRA 学習ではアルファ値が1の場合比較的高めの値例: `1e-4`から`1e-3`)が使われることが多いです。
* `--unet_lr=1e-4`
* U-Net 部分の LoRA モジュールに対する学習率を個別に指定する場合に使用します。指定しない場合は `--learning_rate` の値が使用されます。
* `--text_encoder_lr=1e-5`
* Text Encoder 部分の LoRA モジュールに対する学習率を個別に指定する場合に使用します。指定しない場合は `--learning_rate` の値が使用されます。U-Net よりも小さめの値が推奨されます。
* `--optimizer_type="AdamW8bit"`
* 学習に使用するオプティマイザを指定します。`AdamW8bit` (要 `bitsandbytes`), `AdamW`, `Lion` (要 `lion-pytorch`), `DAdaptation` (要 `dadaptation`), `Adafactor` などが選択可能です。`AdamW8bit` はメモリ効率が良く、広く使われています。
* `--lr_scheduler="constant"`
* 学習率スケジューラを指定します。学習の進行に合わせて学習率を変化させる方法です。`constant` (変化なし), `cosine` (コサインカーブ), `linear` (線形減衰), `constant_with_warmup` (ウォームアップ付き定数), `cosine_with_restarts` などが選択可能です。`constant``cosine``constant_with_warmup` がよく使われます。
* `--lr_warmup_steps=500`
* 学習率スケジューラのウォームアップステップ数を指定します。学習開始時に学習率を徐々に上げていく期間です。`lr_scheduler` がウォームアップをサポートする場合に有効です。
* `--max_train_steps=10000`
* 学習の総ステップ数を指定します。`max_train_epochs` が指定されている場合はそちらが優先されます。
* `--max_train_epochs=12`
* 学習のエポック数を指定します。これを指定すると `max_train_steps` は無視されます。
* `--sdpa`
* Scaled Dot-Product Attention を使用します。LoRA の学習において、メモリ使用量を削減し、学習速度を向上させることができます。
* `--mixed_precision="fp16"`
* 混合精度学習の設定を指定します。`no` (無効), `fp16` (半精度), `bf16` (bfloat16) から選択できます。GPU が対応している場合は `fp16` または `bf16` を指定することで、学習速度の向上とメモリ使用量の削減が期待できます。
* `--gradient_accumulation_steps=1`
* 勾配を累積するステップ数を指定します。実質的なバッチサイズを `train_batch_size * gradient_accumulation_steps` に増やす効果があります。GPU メモリが足りない場合に大きな値を設定します。通常は `1` で問題ありません。
#### その他
* `--seed=42`
* 乱数シードを指定します。学習の再現性を確保したい場合に設定します。
* `--logging_dir="<ログディレクトリ>"`
* TensorBoard などのログを出力するディレクトリを指定します。指定しない場合、ログは出力されません。
* `--log_prefix="<プレフィックス>"`
* `logging_dir` 内に作成されるサブディレクトリ名の接頭辞を指定します。
* `--gradient_checkpointing`
* Gradient Checkpointing を有効にします。メモリ使用量を大幅に削減できますが、学習速度は若干低下します。メモリが厳しい場合に有効です。
* `--clip_skip=1`
* Text Encoder の最後の層から数えて何層スキップするかを指定します。`2` を指定すると最後から 2 層目の出力を使用します。`None` または `1` はスキップなし(最後の層を使用)を意味します。学習対象のモデルの推奨する値を確認してください。
</details>
### 3.2. Starting the Training / 学習の開始
After setting the necessary arguments and executing the command, training will begin. The progress of the training will be output to the console. If `logging_dir` is specified, you can visually check the training status (loss, learning rate, etc.) with TensorBoard.
```bash
tensorboard --logdir <directory specified by logging_dir>
```
<details>
<summary>日本語</summary>
必要な引数を設定し、コマンドを実行すると学習が開始されます。学習の進行状況はコンソールに出力されます。`logging_dir` を指定した場合は、TensorBoard などで学習状況(損失や学習率など)を視覚的に確認できます。
</details>
## 4. Using the Trained Model / 学習済みモデルの利用
Once training is complete, a LoRA model file (`.safetensors` or `.ckpt`) with the name specified by `output_name` will be saved in the directory specified by `output_dir`.
This file can be used with GUI tools such as AUTOMATIC1111/stable-diffusion-webui, ComfyUI, etc.
<details>
<summary>日本語</summary>
学習が完了すると、`output_dir` で指定したディレクトリに、`output_name` で指定した名前の LoRA モデルファイル (`.safetensors` または `.ckpt`) が保存されます。
このファイルは、AUTOMATIC1111/stable-diffusion-webui 、ComfyUI などの GUI ツールで利用できます。
</details>
## 5. Other Features / その他の機能
`train_network.py` has many other options not introduced here.
* Sample image generation (`--sample_prompts`, `--sample_every_n_steps`, etc.)
* More detailed optimizer settings (`--optimizer_args`, etc.)
* Caption preprocessing (`--shuffle_caption`, `--keep_tokens`, etc.)
* Additional network settings (`--network_args`, etc.)
For these features, please refer to the script's help (`python train_network.py --help`) or other documents in the repository.
<details>
<summary>日本語</summary>
`train_network.py` には、ここで紹介した以外にも多くのオプションがあります。
* サンプル画像の生成 (`--sample_prompts`, `--sample_every_n_steps` など)
* より詳細なオプティマイザ設定 (`--optimizer_args` など)
* キャプションの前処理 (`--shuffle_caption`, `--keep_tokens` など)
* ネットワークの追加設定 (`--network_args` など)
これらの機能については、スクリプトのヘルプ (`python train_network.py --help`) やリポジトリ内の他のドキュメントを参照してください。
</details>