Add documentation

README_train_network-ja.md

@@ -0,0 +1,157 @@
+## LoRAの学習について
+
+[LoRA: Low-Rank Adaptation of Large Language Models](https://arxiv.org/abs/2106.09685)（arxiv）、[LoRA](https://github.com/microsoft/LoRA)（github）をStable Diffusionに適用したものです。
+
+[cloneofsimo氏のリポジトリ](https://github.com/cloneofsimo/lora)を大いに参考にさせていただきました。ありがとうございます。
+
+8GB VRAMでもぎりぎり動作するようです。
+
+## 学習したモデルに関する注意
+
+cloneofsimo氏のリポジトリ、およびd8ahazard氏の[Dreambooth Extension for Stable-Diffusion-WebUI](https://github.com/d8ahazard/sd_dreambooth_extension)とは、現時点では互換性がありません。いくつかの機能拡張を行っているためです（後述）。
+
+WebUI等で画像生成する場合には、学習したLoRAのモデルを学習元のStable Diffusionのモデルに、このリポジトリ内のスクリプトであらかじめマージしておく必要があります。マージ後のモデルファイルはLoRAの学習結果が反映されたものになります。
+
+なお当リポジトリ内の画像生成スクリプトで生成する場合はマージ不要です。
+
+## 学習方法
+
+train_network.pyを用います。
+
+DreamBoothの手法（identifier（sksなど）とclass、オプションで正則化画像を用いる）と、キャプションを用いるfine tuningの手法の両方で学習できます。
+
+どちらの方法も既存のスクリプトとほぼ同じ方法で学習できます。異なる点については後述します。
+
+### DreamBoothの手法を用いる場合
+
+note.com [環境整備とDreamBooth学習スクリプトについて](https://note.com/kohya_ss/n/nba4eceaa4594) を参照してデータを用意してください。
+
+学習するとき、train_db.pyの代わりにtrain_network.pyを指定してください。
+
+ほぼすべてのオプション（Stable Diffusionのモデル保存関係を除く）が使えますが、stop_text_encoder_trainingはサポートしていません。
+
+### キャプションを用いる場合
+
+[fine-tuningのガイド](./fine_tune_README_ja.md) を参照し、各手順を実行してください。
+
+学習するとき、fine_tune.pyの代わりにtrain_network.pyを指定してください。ほぼすべてのオプション（モデル保存関係を除く）がそのまま使えます。
+
+なお「latentsの事前取得」は行わなくても動作します。VAEから学習時（またはキャッシュ時）にlatentを取得するため学習速度は遅くなりますが、代わりにcolor_augが使えるようになります。
+
+### LoRAの学習のためのオプション
+
+train_network.pyでは--network_moduleオプションに、学習対象のモジュール名を指定します。LoRAに対応するのはnetwork.loraとなりますので、それを指定してください。
+
+なお学習率は通常のDreamBoothやfine tuningよりも高めの、1e-4程度を指定するとよいようです。
+
+以下はコマンドラインの例です（DreamBooth手法）。
+
+```
+accelerate launch --num_cpu_threads_per_process 12 train_network.py 
+    --pretrained_model_name_or_path=..\models\model.ckpt 
+    --train_data_dir=..\data\db\char1 --output_dir=..\lora_train1 
+    --reg_data_dir=..\data\db\reg1 --prior_loss_weight=1.0 
+    --resolution=448,640 --train_batch_size=1 --learning_rate=1e-4 
+    --max_train_steps=400 --use_8bit_adam --xformers --mixed_precision=fp16 
+    --save_every_n_epochs=1 --save_model_as=safetensors --clip_skip=2 --seed=42 --color_aug 
+    --network_module=networks.lora
+```
+
+--output_dirオプションで指定したディレクトリに、LoRAのモデルが保存されます。
+
+その他、以下のオプションが指定できます。
+
+* --network_dim
+  * LoRAの次元数を指定します（``--networkdim=4``など）。省略時は4になります。数が多いほど表現力は増しますが、学習に必要なメモリ、時間は増えます。また闇雲に増やしても良くないようです。
+* --network_weights
+  * 学習前に学習済みのLoRAの重みを読み込み、そこから追加で学習します。
+* --network_train_unet_only
+  * U-Netに関連するLoRAモジュールのみ有効とします。fine tuning的な学習で指定するとよいかもしれません。
+* --network_train_text_encoder_only
+  * Text Encoderに関連するLoRAモジュールのみ有効とします。Textual Inversion的な効果が期待できるかもしれません。
+* --unet_lr
+  * U-Netに関連するLoRAモジュールに、通常の学習率（--learning_rateオプションで指定）とは異なる学習率を使う時に指定します。
+* --text_encoder_lr
+  * Text Encoderに関連するLoRAモジュールに、通常の学習率（--learning_rateオプションで指定）とは異なる学習率を使う時に指定します。Text Encoderのほうを若干低めの学習率（5e-5など）にしたほうが良い、という話もあるようです。
+
+--network_train_unet_onlyと--network_train_text_encoder_onlyの両方とも未指定時（デフォルト）はText EncoderとU-Netの両方のLoRAモジュールを有効にします。
+
+## マージスクリプトについて
+
+merge_lora.pyでStable DiffusionのモデルにLoRAの学習結果をマージしたり、複数のLoRAモデルをマージしたりできます。
+
+### Stable DiffusionのモデルにLoRAのモデルをマージする
+
+マージ後のモデルは通常のStable Diffusionのckptと同様に扱えます。たとえば以下のようなコマンドラインになります。
+
+```
+python networks\merge_lora.py --sd_model ..\model\model.ckpt 
+    --save_to ..\lora_train1\model-char1-merged.safetensors 
+    --models ..\lora_train1\last.safetensors --ratios 0.8
+```
+
+Stable Diffusion v2.xのモデルで学習し、それにマージする場合は、--v2オプションを指定してください。
+
+--sd_modelオプションにマージの元となるStable Diffusionのモデルファイルを指定します（.ckptまたは.safetensorsのみ対応で、Diffusersは今のところ対応していません）。
+
+--save_toオプションにマージ後のモデルの保存先を指定します（.ckptまたは.safetensors、拡張子で自動判定）。
+
+--modelsに学習したLoRAのモデルファイルを指定します。複数指定も可能で、その時は順にマージします。
+
+--ratiosにそれぞれのモデルの適用率（どのくらい重みを元モデルに反映するか）を0~1.0の数値で指定します。例えば過学習に近いような場合は、適用率を下げるとマシになるかもしれません。モデルの数と同じだけ指定してください。
+
+複数指定時は以下のようになります。
+
+```
+python networks\merge_lora.py --sd_model ..\model\model.ckpt 
+    --save_to ..\lora_train1\model-char1-merged.safetensors 
+    --models ..\lora_train1\last.safetensors ..\lora_train2\last.safetensors --ratios 0.8 0.5
+```
+
+### 複数のLoRAのモデルをマージする
+
+結局のところSDモデルにマージしないと推論できないのであまり使い道はないかもしれません。ただ、複数のLoRAモデルをひとつずつSDモデルにマージしていく場合と、複数のLoRAモデルをマージしてからSDモデルにマージする場合とは、計算順序の関連で微妙に異なる結果になります。
+
+たとえば以下のようなコマンドラインになります。
+
+```
+python networks\merge_lora.py 
+    --save_to ..\lora_train1\model-char1-style1-merged.safetensors 
+    --models ..\lora_train1\last.safetensors ..\lora_train2\last.safetensors --ratios 0.6 0.4
+```
+
+--sd_modelオプションは指定不要です。
+
+--save_toオプションにマージ後のLoRAモデルの保存先を指定します（.ckptまたは.safetensors、拡張子で自動判定）。
+
+--modelsに学習したLoRAのモデルファイルを指定します。三つ以上も指定可能です。
+
+--ratiosにそれぞれのモデルの比率（どのくらい重みを元モデルに反映するか）を0~1.0の数値で指定します。二つのモデルを一対一でマージす場合は、「0.5 0.5」になります。「1.0 1.0」では合計の重みが大きくなりすぎて、恐らく結果はあまり望ましくないものになると思われます。
+
+v1で学習したLoRAとv2で学習したLoRA、次元数の異なるLoRAはマージできません。U-NetだけのLoRAとU-Net+Text EncoderのLoRAはマージできるはずですが、結果は未知数です。
+
+
+### その他のオプション
+
+* precision
+  * マージ計算時の精度をfloat、fp16、bf16から指定できます。省略時は精度を確保するためfloatになります。メモリ使用量を減らしたい場合はfp16/bf16を指定してください。
+* save_precision
+  * モデル保存時の精度をfloat、fp16、bf16から指定できます。省略時はprecisionと同じ精度になります。
+
+## 当リポジトリ内の画像生成スクリプトで生成する
+
+gen_img_diffusers.pyに、--network_module、--network_weights、--network_dim（省略可）の各オプションを追加してください。意味は学習時と同様です。
+
+--network_mulオプションで0~1.0の数値を指定すると、LoRAの適用率を変えられます。
+
+## 追加情報
+
+### cloneofsimo氏のリポジトリとの違い
+
+12/25時点では、当リポジトリはLoRAの適用個所をText EncoderのMLP、U-NetのFFN、Transformerのin/out projectionに拡大し、表現力が増しています。ただその代わりメモリ使用量は増え、8GBぎりぎりになりました。
+
+またモジュール入れ替え機構は全く異なります。
+
+### 将来拡張について
+
+LoRAだけでなく他の拡張にも対応可能ですので、それらも追加予定です。

README_train_network.md

@@ -0,0 +1,194 @@
+# Train network documentation translated from japanese
+## About learning LoRA
+
+[LoRA: Low-Rank Adaptation of Large Language Models](https://arxiv.org/abs/2106.09685) (arxiv), [LoRA](https://github.com/microsoft/LoRA) (github) to Stable Applied to Diffusion.
+
+[cloneofsimo's repository](https://github.com/cloneofsimo/lora) was a great reference. thank you.
+
+8GB VRAM seems to work just fine.
+
+## A Note about Trained Models
+
+Cloneofsimo's repository and d8ahazard's [Drebooth Extension for Stable-Diffusion-WebUI](https://github.com/d8ahazard/sd_drebooth_extension) are currently incompatible. Because we are doing some enhancements (see below).
+
+When generating images with WebUI etc., it is necessary to merge the learned LoRA model with the learning source Stable Diffusion model in advance using the script in this repository. The model file after merging will reflect the learning results of LoRA.
+
+Note that merging is not required when generating with the image generation script in this repository.
+
+## Learning method
+
+Use train_network.py.
+
+You can learn both the DreamBooth method (using identifiers (sks, etc.) and classes, optionally with regularized images) and the fine tuning method using captions.
+
+Both methods can be learned in much the same way as existing scripts. We will discuss the differences later.
+
+### Using the DreamBooth Method
+
+Please refer to note.com [Environment preparation and DreamBooth learning script](https://note.com/kohya_ss/n/nba4eceaa4594) to prepare the data.
+
+Specify train_network.py instead of train_db.py when training.
+
+Almost all options are available (except model saving related to Stable Diffusion), but stop_text_encoder_training is not supported.
+
+### When to use captions
+
+Please refer to [fine-tuning guide](./fine_tune_README_en.md) and perform each step.
+
+Specify train_network.py instead of fine_tune.py when training. Almost all options (except for model saving) can be used as is.
+
+In addition, it will work even if you do not perform "Pre-obtain latents". Since the latent is acquired from the VAE when learning (or caching), the learning speed will be slower, but color_aug can be used instead.
+
+### Options for Learning LoRA
+
+In train_network.py, specify the name of the module to be trained in the --network_module option. LoRA is compatible with network.lora, so please specify it.
+
+The learning rate should be set to about 1e-4, which is higher than normal DreamBooth and fine tuning.
+
+Below is an example command line (DreamBooth technique).
+
+```
+accelerate launch --num_cpu_threads_per_process 12 train_network.py
+     --pretrained_model_name_or_path=..\models\model.ckpt
+     --train_data_dir=..\data\db\char1 --output_dir=..\lora_train1
+     --reg_data_dir=..\data\db\reg1 --prior_loss_weight=1.0
+     --resolution=448,640 --train_batch_size=1 --learning_rate=1e-4
+     --max_train_steps=400 --use_8bit_adam --xformers --mixed_precision=fp16
+     --save_every_n_epochs=1 --save_model_as=safetensors --clip_skip=2 --seed=42 --color_aug
+     --network_module=networks.lora
+```
+
+The LoRA model will be saved in the directory specified by the --output_dir option.
+
+In addition, the following options can be specified.
+
+* --network_dim
+   * Specify the number of dimensions of LoRA (such as ``--networkdim=4``). Default is 4. The greater the number, the greater the expressive power, but the memory and time required for learning also increase. In addition, it seems that it is not good to increase it blindly.
+* --network_weights
+   * Load pretrained LoRA weights before training and additionally learn from them.
+* --network_train_unet_only
+   * Valid only for LoRA modules related to U-Net. It may be better to specify it in fine-tuning study.
+* --network_train_text_encoder_only
+   * Only LoRA modules related to Text Encoder are enabled. You may be able to expect a textual inversion effect.
+* --unet_lr
+   * Specify when using a learning rate different from the normal learning rate (specified with the --learning_rate option) for the LoRA module related to U-Net.
+* --text_encoder_lr
+   * Specify when using a learning rate different from the normal learning rate (specified with the --learning_rate option) for the LoRA module associated with the Text Encoder. Some people say that it is better to set the Text Encoder to a slightly lower learning rate (such as 5e-5).
+
+When neither --network_train_unet_only nor --network_train_text_encoder_only is specified (default), both Text Encoder and U-Net LoRA modules are enabled.
+
+### Options for Learning LoRA
+
+In train_network.py, specify the name of the module to be trained in the --network_module option. LoRA is compatible with network.lora, so please specify it.
+
+The learning rate should be set to about 1e-4, which is higher than normal DreamBooth and fine tuning.
+
+Below is an example command line (DreamBooth technique).
+
+```
+accelerate launch --num_cpu_threads_per_process 12 train_network.py
+     --pretrained_model_name_or_path=..\models\model.ckpt
+     --train_data_dir=..\data\db\char1 --output_dir=..\lora_train1
+     --reg_data_dir=..\data\db\reg1 --prior_loss_weight=1.0
+     --resolution=448,640 --train_batch_size=1 --learning_rate=1e-4
+     --max_train_steps=400 --use_8bit_adam --xformers --mixed_precision=fp16
+     --save_every_n_epochs=1 --save_model_as=safetensors --clip_skip=2 --seed=42 --color_aug
+     --network_module=networks.lora
+```
+
+The LoRA model will be saved in the directory specified by the --output_dir option.
+
+In addition, the following options can be specified.
+
+* --network_dim
+   * Specify the number of dimensions of LoRA (such as ``--networkdim=4``). Default is 4. The greater the number, the greater the expressive power, but the memory and time required for learning also increase. In addition, it seems that it is not good to increase it blindly.
+* --network_weights
+   * Load pretrained LoRA weights before training and additionally learn from them.
+* --network_train_unet_only
+   * Valid only for LoRA modules related to U-Net. It may be better to specify it in fine-tuning study.
+* --network_train_text_encoder_only
+   * Only LoRA modules related to Text Encoder are enabled. You may be able to expect a textual inversion effect.
+* --unet_lr
+   * Specify when using a learning rate different from the normal learning rate (specified with the --learning_rate option) for the LoRA module related to U-Net.
+* --text_encoder_lr
+   * Specify when using a learning rate different from the normal learning rate (specified with the --learning_rate option) for the LoRA module associated with the Text Encoder. Some people say that it is better to set the Text Encoder to a slightly lower learning rate (such as 5e-5).
+
+If both --network_train_unet_only and --network_train_text_encoder_only are not specified (default), both Text Encoder and U-Net LoRA modules will be enabled. ## About the merge script
+
+merge_lora.py allows you to merge LoRA training results into a Stable Diffusion model, or merge multiple LoRA models.
+
+### Merge LoRA model into Stable Diffusion model
+
+The model after merging can be handled in the same way as normal Stable Diffusion ckpt. For example, a command line like:
+
+```
+python networks\merge_lora.py --sd_model ..\model\model.ckpt
+     --save_to ..\lora_train1\model-char1-merged.safetensors
+     --models ..\lora_train1\last.safetensors --ratios 0.8
+```
+
+Specify the --v2 option if you want to train with a Stable Diffusion v2.x model and merge with it.
+
+Specify the Stable Diffusion model file to be merged in the --sd_model option (only .ckpt or .safetensors are supported, Diffusers is not currently supported).
+
+Specify the save destination of the model after merging in the --save_to option (.ckpt or .safetensors, automatically determined by extension).
+
+Specify the LoRA model file learned in --models. It is possible to specify more than one, in which case they will be merged in order.
+
+For --ratios, specify the application rate of each model (how much weight is reflected in the original model) with a numerical value from 0 to 1.0. For example, if it is close to overfitting, it may be better if the application rate is lowered. Specify as many as the number of models.
+
+When specifying multiple, it will be as follows.
+
+```
+python networks\merge_lora.py --sd_model ..\model\model.ckpt
+     --save_to ..\lora_train1\model-char1-merged.safetensors
+     --models ..\lora_train1\last.safetensors ..\lora_train2\last.safetensors --ratios 0.8 0.5
+```
+
+### Merge multiple LoRA models
+
+After all, it may not be very useful because it cannot be inferred unless it is merged into the SD model. However, when merging multiple LoRA models one by one into the SD model, and when merging multiple LoRA models and then merging them into the SD model, the result will be slightly different in relation to the calculation order.
+
+For example, a command line like:
+
+```
+python networks\merge_lora.py
+     --save_to ..\lora_train1\model-char1-style1-merged.safetensors
+     --models ..\lora_train1\last.safetensors ..\lora_train2\last.safetensors --ratios 0.6 0.4
+```
+
+The --sd_model option does not need to be specified.
+
+Specify the save destination of the merged LoRA model in the --save_to option (.ckpt or .safetensors, automatically determined by extension).
+
+Specify the LoRA model file learned in --models. Three or more can be specified.
+
+For --ratios, specify the ratio of each model (how much weight is reflected in the original model) with a numerical value from 0 to 1.0. If you merge two models one-to-one, it will be "0.5 0.5". "1.0 1.0" would give too much weight to the sum, and the result would probably be less desirable.
+
+LoRA trained with v1 and LoRA trained with v2, and LoRA with different number of dimensions cannot be merged. U-Net only LoRA and U-Net+Text Encoder LoRA should be able to merge, but the result is unknown.
+
+
+### Other Options
+
+* precision
+   * The precision for merge calculation can be specified from float, fp16, and bf16. If omitted, it will be float to ensure accuracy. Specify fp16/bf16 if you want to reduce memory usage.
+* save_precision
+   * You can specify the precision when saving the model from float, fp16, bf16. If omitted, the precision is the same as precision.
+
+## Generate with the image generation script in this repository
+
+Add options --network_module, --network_weights, --network_dim (optional) to gen_img_diffusers.py. The meaning is the same as when learning.
+
+You can change the LoRA application rate by specifying a value between 0 and 1.0 with the --network_mul option.
+
+## Additional Information
+
+### Differences from cloneofsimo's repository
+
+As of 12/25, this repository has expanded LoRA application points to Text Encoder's MLP, U-Net's FFN, and Transformer's in/out projection, increasing its expressiveness. However, the amount of memory used increased, and it became the last minute of 8GB instead.
+
+Also, the module replacement mechanism is completely different.
+
+### About future expansion
+
+It is possible to support not only LoRA but also other expansions, so we plan to add them as well.