Kohya-ss-sd-scripts/docs/anima_train_network.md

LoRA Training Guide for Anima using anima_train_network.py / anima_train_network.py を用いたAnima モデルのLoRA学習ガイド

This document explains how to train LoRA (Low-Rank Adaptation) models for Anima using anima_train_network.py in the sd-scripts repository.

日本語

このドキュメントでは、sd-scriptsリポジトリに含まれるanima_train_network.pyを使用して、Anima モデルに対するLoRA (Low-Rank Adaptation) モデルを学習する基本的な手順について解説します。

1. Introduction / はじめに

anima_train_network.py trains additional networks such as LoRA for Anima models. Anima adopts a DiT (Diffusion Transformer) architecture based on the MiniTrainDIT design with Rectified Flow training. It uses a Qwen3-0.6B text encoder, an LLM Adapter (6-layer transformer bridge from Qwen3 to T5-compatible space), and a Qwen-Image VAE (16-channel, 8x spatial downscale).

Qwen-Image VAE and Qwen-Image VAE have same architecture, but official Anima weight is named for Qwen-Image VAE.

This guide assumes you already understand the basics of LoRA training. For common usage and options, see the train_network.py guide. Some parameters are similar to those in sd3_train_network.py and flux_train_network.py.

Prerequisites:

• The sd-scripts repository has been cloned and the Python environment is ready.
• A training dataset has been prepared. See the Dataset Configuration Guide.
• Anima model files for training are available.

日本語

anima_train_network.pyは、Anima モデルに対してLoRAなどの追加ネットワークを学習させるためのスクリプトです。AnimaはMiniTrainDIT設計に基づくDiT (Diffusion Transformer) アーキテクチャを採用しており、Rectified Flow学習を使用します。テキストエンコーダーとしてQwen3-0.6B、LLM Adapter (Qwen3からT5互換空間への6層Transformerブリッジ)、およびQwen-Image VAE (16チャンネル、8倍空間ダウンスケール) を使用します。

Qwen-Image VAEとQwen-Image VAEは同じアーキテクチャですが、Anima公式の重みはQwen-Image VAE用のようです。

このガイドは、基本的なLoRA学習の手順を理解しているユーザーを対象としています。基本的な使い方や共通のオプションについては、train_network.pyのガイドを参照してください。また一部のパラメータは sd3_train_network.py や flux_train_network.py と同様のものがあるため、そちらも参考にしてください。

前提条件:

• sd-scriptsリポジトリのクローンとPython環境のセットアップが完了していること。
• 学習用データセットの準備が完了していること。（データセットの準備についてはデータセット設定ガイドを参照してください）
• 学習対象のAnimaモデルファイルが準備できていること。

2. Differences from train_network.py / train_network.py との違い

anima_train_network.py is based on train_network.py but modified for Anima. Main differences are:

• Target models: Anima DiT models.
• Model structure: Uses a MiniTrainDIT (Transformer based) instead of U-Net. Employs a single text encoder (Qwen3-0.6B), an LLM Adapter that bridges Qwen3 embeddings to T5-compatible cross-attention space, and a Qwen-Image VAE (16-channel latent space with 8x spatial downscale).
• Arguments: Uses the common --pretrained_model_name_or_path for the DiT model path, --qwen3 for the Qwen3 text encoder, and --vae for the Qwen-Image VAE. The LLM adapter and T5 tokenizer can be specified separately with --llm_adapter_path and --t5_tokenizer_path.
• Incompatible arguments: Stable Diffusion v1/v2 options such as --v2, --v_parameterization and --clip_skip are not used. --fp8_base is not supported.
• Timestep sampling: Uses the same --timestep_sampling options as FLUX training (sigma, uniform, sigmoid, shift, flux_shift).
• LoRA: Uses regex-based module selection and per-module rank/alpha/learning rate control (network_reg_dims, network_reg_alphas, network_reg_lrs) instead of per-component arguments. Module exclusion/inclusion is controlled by exclude_patterns and include_patterns.

日本語

anima_train_network.pyはtrain_network.pyをベースに、Anima モデルに対応するための変更が加えられています。主な違いは以下の通りです。

• 対象モデル: Anima DiTモデルを対象とします。
• モデル構造: U-Netの代わりにMiniTrainDIT (Transformerベース) を使用します。テキストエンコーダーとしてQwen3-0.6B、Qwen3埋め込みをT5互換のクロスアテンション空間に変換するLLM Adapter、およびQwen-Image VAE (16チャンネル潜在空間、8倍空間ダウンスケール) を使用します。
• 引数: DiTモデルのパスには共通引数--pretrained_model_name_or_pathを、Qwen3テキストエンコーダーには--qwen3を、Qwen-Image VAEには--vaeを使用します。LLM AdapterとT5トークナイザーはそれぞれ--llm_adapter_path、--t5_tokenizer_pathで個別に指定できます。
• 一部引数の非互換性: Stable Diffusion v1/v2向けの引数（例: --v2, --v_parameterization, --clip_skip）は使用されません。--fp8_baseはサポートされていません。
• タイムステップサンプリング: FLUX学習と同じ--timestep_samplingオプション（sigma、uniform、sigmoid、shift、flux_shift）を使用します。
• LoRA: コンポーネント別の引数の代わりに、正規表現ベースのモジュール選択とモジュール単位のランク/アルファ/学習率制御（network_reg_dims、network_reg_alphas、network_reg_lrs）を使用します。モジュールの除外/包含はexclude_patternsとinclude_patternsで制御します。

3. Preparation / 準備

The following files are required before starting training:

1. Training script: anima_train_network.py
2. Anima DiT model file: .safetensors file for the base DiT model.
3. Qwen3-0.6B text encoder: Either a HuggingFace model directory, or a single .safetensors file (uses the bundled config files in configs/qwen3_06b/).
4. Qwen-Image VAE model file: .safetensors or .pth file for the VAE.
5. LLM Adapter model file (optional): .safetensors file. If not provided separately, the adapter is loaded from the DiT file if the key llm_adapter.out_proj.weight exists.
6. T5 Tokenizer (optional): If not specified, uses the bundled tokenizer at configs/t5_old/.
7. Dataset definition file (.toml): Dataset settings in TOML format. (See the Dataset Configuration Guide.) In this document we use my_anima_dataset_config.toml as an example.

Model files can be obtained from the Anima HuggingFace repository.

Notes:

• The T5 tokenizer only needs the tokenizer files (not the T5 model weights). It uses the vocabulary from google/t5-v1_1-xxl.

日本語

学習を開始する前に、以下のファイルが必要です。

1. 学習スクリプト: anima_train_network.py
2. Anima DiTモデルファイル: ベースとなるDiTモデルの.safetensorsファイル。
3. Qwen3-0.6Bテキストエンコーダー: HuggingFaceモデルディレクトリまたは単体の.safetensorsファイル（バンドル版のconfigs/qwen3_06b/の設定ファイルが使用されます）。
4. Qwen-Image VAEモデルファイル: VAEの.safetensorsまたは.pthファイル。
5. LLM Adapterモデルファイル（オプション）: .safetensorsファイル。個別に指定しない場合、DiTファイル内にllm_adapter.out_proj.weightキーが存在すればそこから読み込まれます。
6. T5トークナイザー（オプション）: 指定しない場合、configs/t5_old/のバンドル版トークナイザーを使用します。
7. データセット定義ファイル (.toml): 学習データセットの設定を記述したTOML形式のファイル。（詳細はデータセット設定ガイドを参照してください）。例としてmy_anima_dataset_config.tomlを使用します。

モデルファイルはHuggingFaceのAnimaリポジトリから入手できます。

注意:

• T5トークナイザーを別途指定する場合、トークナイザーファイルのみ必要です（T5モデルの重みは不要）。google/t5-v1_1-xxlの語彙を使用します。

4. Running the Training / 学習の実行

Execute anima_train_network.py from the terminal to start training. The overall command-line format is the same as train_network.py, but Anima specific options must be supplied.

Example command:

accelerate launch --num_cpu_threads_per_process 1 anima_train_network.py \
  --pretrained_model_name_or_path="<path to Anima DiT model>" \
  --qwen3="<path to Qwen3-0.6B model or directory>" \
  --vae="<path to Qwen-Image VAE model>" \
  --dataset_config="my_anima_dataset_config.toml" \
  --output_dir="<output directory>" \
  --output_name="my_anima_lora" \
  --save_model_as=safetensors \
  --network_module=networks.lora_anima \
  --network_dim=8 \
  --learning_rate=1e-4 \
  --optimizer_type="AdamW8bit" \
  --lr_scheduler="constant" \
  --timestep_sampling="sigmoid" \
  --discrete_flow_shift=1.0 \
  --max_train_epochs=10 \
  --save_every_n_epochs=1 \
  --mixed_precision="bf16" \
  --gradient_checkpointing \
  --cache_latents \
  --cache_text_encoder_outputs \
  --vae_chunk_size=64 \
  --vae_disable_cache

(Write the command on one line or use \ or ^ for line breaks.)

The learning rate of 1e-4 is just an example. Adjust it according to your dataset and objectives. This value is for alpha=1.0 (default). If increasing --network_alpha, consider lowering the learning rate.

If loss becomes NaN, ensure you are using PyTorch version 2.5 or higher.

Note: --vae_chunk_size and --vae_disable_cache are custom options in this repository to reduce memory usage of the Qwen-Image VAE.

日本語

学習は、ターミナルからanima_train_network.pyを実行することで開始します。基本的なコマンドラインの構造はtrain_network.pyと同様ですが、Anima特有の引数を指定する必要があります。

コマンドラインの例は英語のドキュメントを参照してください。

※実際には1行で書くか、適切な改行文字（\ または ^）を使用してください。

学習率1e-4はあくまで一例です。データセットや目的に応じて適切に調整してください。またこの値はalpha=1.0（デフォルト）での値です。--network_alphaを増やす場合は学習率を下げることを検討してください。

lossがNaNになる場合は、PyTorchのバージョンが2.5以上であることを確認してください。

注意: --vae_chunk_sizeおよび--vae_disable_cacheは当リポジトリ独自のオプションで、Qwen-Image VAEのメモリ使用量を削減するために使用します。

4.1. Explanation of Key Options / 主要なコマンドライン引数の解説

Besides the arguments explained in the train_network.py guide, specify the following Anima specific options. For shared options (--output_dir, --output_name, --network_module, etc.), see that guide.

Model Options [Required] / モデル関連 [必須]

• --pretrained_model_name_or_path="<path to Anima DiT model>" [Required]
  • Path to the Anima DiT model .safetensors file. The model config (channels, blocks, heads) is auto-detected from the state dict. ComfyUI format with net. prefix is supported.
• --qwen3="<path to Qwen3-0.6B model>" [Required]
  • Path to the Qwen3-0.6B text encoder. Can be a HuggingFace model directory or a single .safetensors file. The text encoder is always frozen during training.
• --vae="<path to Qwen-Image VAE model>" [Required]
  • Path to the Qwen-Image VAE model .safetensors or .pth file. Fixed config: dim=96, z_dim=16.

Model Options [Optional] / モデル関連 [オプション]

• --llm_adapter_path="<path to LLM adapter>" [Optional]
  • Path to a separate LLM adapter weights file. If omitted, the adapter is loaded from the DiT file when the key llm_adapter.out_proj.weight exists.
• --t5_tokenizer_path="<path to T5 tokenizer>" [Optional]
  • Path to the T5 tokenizer directory. If omitted, uses the bundled config at configs/t5_old/.

Anima Training Parameters / Anima 学習パラメータ

• --timestep_sampling=<choice>
  • Timestep sampling method. Choose from sigma, uniform, sigmoid (default), shift, flux_shift. Same options as FLUX training. See the flux_train_network.py guide for details on each method.
• --discrete_flow_shift=<float>
  • Shift for the timestep distribution in Rectified Flow training. Default 1.0. This value is used when --timestep_sampling is set to shift. The shift formula is t_shifted = (t * shift) / (1 + (shift - 1) * t).
• --sigmoid_scale=<float>
  • Scale factor when --timestep_sampling is set to sigmoid, shift, or flux_shift. Default 1.0.
• --qwen3_max_token_length=<integer>
  • Maximum token length for the Qwen3 tokenizer. Default 512.
• --t5_max_token_length=<integer>
  • Maximum token length for the T5 tokenizer. Default 512.
• --attn_mode=<choice>
  • Attention implementation to use. Choose from torch (default), xformers, flash, sageattn. xformers requires --split_attn. sageattn does not support training (inference only). This option overrides --xformers.
• --split_attn
  • Split attention computation to reduce memory usage. Required when using --attn_mode xformers.

Component-wise Learning Rates / コンポーネント別学習率

These options set separate learning rates for each component of the Anima model. They are primarily used for full fine-tuning. Set to 0 to freeze a component:

• --self_attn_lr=<float> - Learning rate for self-attention layers. Default: same as --learning_rate.
• --cross_attn_lr=<float> - Learning rate for cross-attention layers. Default: same as --learning_rate.
• --mlp_lr=<float> - Learning rate for MLP layers. Default: same as --learning_rate.
• --mod_lr=<float> - Learning rate for AdaLN modulation layers. Default: same as --learning_rate. Note: modulation layers are not included in LoRA by default.
• --llm_adapter_lr=<float> - Learning rate for LLM adapter layers. Default: same as --learning_rate.

For LoRA training, use network_reg_lrs in --network_args instead. See Section 5.2.

Memory and Speed / メモリ・速度関連

• --blocks_to_swap=<integer>
  • Number of Transformer blocks to swap between CPU and GPU. More blocks reduce VRAM but slow training. Maximum values depend on model size:
    • 28-block model: max 26 (Anima-Preview)
    • 36-block model: max 34
    • 20-block model: max 18
  • Cannot be used with --cpu_offload_checkpointing or --unsloth_offload_checkpointing.
• --unsloth_offload_checkpointing
  • Offload activations to CPU RAM using async non-blocking transfers (faster than --cpu_offload_checkpointing). Cannot be combined with --cpu_offload_checkpointing or --blocks_to_swap.
• --cache_text_encoder_outputs
  • Cache Qwen3 text encoder outputs to reduce VRAM usage. Recommended when not training text encoder LoRA.
• --cache_text_encoder_outputs_to_disk
  • Cache text encoder outputs to disk. Auto-enables --cache_text_encoder_outputs.
• --cache_latents, --cache_latents_to_disk
  • Cache Qwen-Image VAE latent outputs.
• --vae_chunk_size=<integer>
  • Chunk size for Qwen-Image VAE processing. Reduces VRAM usage at the cost of speed. Default is no chunking.
• --vae_disable_cache
  • Disable internal caching in Qwen-Image VAE to reduce VRAM usage.

EMA (Exponential Moving Average) / EMA (指数移動平均)

EMA maintains a shadow copy of the model parameters, averaging them over training steps. This produces smoother, more stable weights that often generalize better than the final training checkpoint. EMA is supported for both full fine-tuning (anima_train.py) and LoRA training (anima_train_network.py).

• --ema
  • Enable EMA. When enabled, an EMA model is saved alongside each regular checkpoint with an ema_ prefix on the filename (e.g., ema_anima-000010.safetensors). The EMA model has the same format as the regular model and can be used directly for inference.
• --ema_decay=<float> (default: 0.9999)
  • Decay rate for EMA. Higher values produce smoother weights but adapt more slowly to new training data. Typical values range from 0.999 to 0.99999.
• --ema_device=<choice> (default: cuda)
  • Device to store EMA shadow parameters. Choose cuda or cpu. Using cpu significantly reduces GPU VRAM usage (shadow params use the same amount of memory as the model) but makes EMA updates slower due to CPU-GPU data transfer.
• --ema_use_num_updates
  • Automatically adjust the EMA decay based on the number of update steps. The effective decay is calculated as min(decay, (1 + num_updates) / (10 + num_updates)). This makes the EMA warm up faster in early training steps.
• --ema_sample
  • Enable dual sampling: generate sample images with both training weights and EMA weights side by side. EMA sample images are saved with a _ema suffix (e.g., image_0000_000010_ema.png). EMA sampling is skipped at step 0 since EMA hasn't accumulated meaningful averages yet. This option works with the existing --sample_every_n_steps, --sample_every_n_epochs, and --sample_prompts arguments.
• --ema_resume_path=<path> [Optional]
  • Path to a previously saved EMA model (.safetensors) to resume EMA from. For full fine-tuning, the file should be a saved EMA DiT model. For LoRA training, the file should be a saved EMA LoRA file.
• --ema_use_feedback [Experimental]
  • Feed back EMA parameters into the training model after each update. This is an experimental feature and is not compatible with multi-GPU DDP training (it modifies parameters only on the main process, causing parameter desynchronization across GPUs).
• --ema_param_multiplier=<float> (default: 1.0) [Experimental]
  • Multiply shadow parameters by this value after each EMA update. This is an experimental feature and is not compatible with multi-GPU DDP training when set to a value other than 1.0.

Example — LoRA training with EMA:

accelerate launch --num_cpu_threads_per_process 1 anima_train_network.py \
  --pretrained_model_name_or_path="<path to Anima DiT model>" \
  --qwen3="<path to Qwen3-0.6B model>" \
  --vae="<path to Qwen-Image VAE model>" \
  --dataset_config="my_anima_dataset_config.toml" \
  --output_dir="<output directory>" \
  --output_name="my_anima_lora" \
  --save_model_as=safetensors \
  --network_module=networks.lora_anima \
  --network_dim=8 \
  --learning_rate=1e-4 \
  --optimizer_type="AdamW8bit" \
  --max_train_epochs=10 \
  --save_every_n_epochs=1 \
  --mixed_precision="bf16" \
  --gradient_checkpointing \
  --cache_latents \
  --cache_text_encoder_outputs \
  --ema \
  --ema_decay=0.9999 \
  --ema_device=cuda \
  --ema_sample \
  --sample_every_n_epochs=1 \
  --sample_prompts="<path to prompt file>"

Notes:

• When --ema_device=cpu is used, EMA shadow parameters are stored in system RAM instead of GPU VRAM. This is useful for large models where VRAM is limited, but EMA updates will be slower.
• For multi-GPU training, --ema_use_feedback and --ema_param_multiplier (when not 1.0) are not supported and will raise an error. Other EMA features work correctly with multi-GPU DDP.
• The EMA model file uses the same format as the regular model. For LoRA, the EMA LoRA file can be loaded the same way as a regular LoRA file.

Guidance Loss (Guidance Distillation) / ガイダンスロス（ガイダンス蒸留）

Guidance Loss bakes the effect of Classifier-Free Guidance (CFG) directly into the model during training. Instead of needing CFG at inference time, the model learns to produce guided outputs on its own. This requires an extra unconditional forward pass per training step, which roughly doubles the compute cost.

How it works: For each training step, the model runs an additional forward pass with an empty prompt to get the unconditional prediction. The training target is then modified using the CFG formula: target = uncond_pred + scale * (target - uncond_pred). The model learns to match this CFG-modified target directly.

• --do_guidance_loss
  • Enable guidance loss. Requires pre-computing empty prompt embeddings before training (done automatically). Roughly doubles compute per step due to the extra forward pass.
• --guidance_loss_scale=<float> (default: 1.0)
  • CFG scale for the guidance loss target computation. Higher values produce stronger guidance baked into the model. A value of 1.0 means no CFG effect (target is unchanged). Typical values: 1.0 to 5.0.
• --guidance_loss_cfg_zero
  • Use CFG-Zero* for guidance loss. Automatically reduces the CFG effect at high noise levels (early timesteps) by computing a projection coefficient alpha = dot(target, uncond_pred) / ||uncond_pred||^2. This prevents artifacts that can occur when applying strong CFG at high noise levels.

Differential Guidance / ディファレンシャルガイダンス

Differential Guidance amplifies the training loss in regions where the model's prediction differs most from the ground truth. It acts as an adaptive per-pixel gradient scaling, pushing the model harder where it is most wrong.

How it works: The target is extrapolated beyond the ground truth using the formula: target = model_pred + scale * (target - model_pred). This amplifies the error by scale^2 in the loss. Areas where the model already predicts well are barely affected, while areas with large errors receive much stronger gradients.

• --do_differential_guidance
  • Enable differential guidance. No extra forward pass needed (uses the existing model prediction).
• --differential_guidance_scale=<float> (default: 3.0)
  • Scale factor for differential guidance. Higher values amplify the loss more where the model is wrong. The effective loss is scaled by approximately scale^2 (e.g., scale=3.0 means ~9x loss amplification for large errors). Typical values: 1.0 to 5.0.

Combining Guidance Loss and Differential Guidance: Both features can be used together. When combined, Guidance Loss is applied first (modifying the target with CFG), then Differential Guidance amplifies the error relative to that CFG-modified target. This means the model learns to produce CFG-guided outputs while receiving stronger gradients where it struggles most.

Notes:

• Guidance Loss is compatible with --blocks_to_swap (block swap state is automatically reset for the extra forward pass).
• Differential Guidance adds no extra compute cost since it only modifies the target tensor.
• Both features work with both full fine-tuning (anima_train.py) and LoRA training (anima_train_network.py).

Incompatible or Unsupported Options / 非互換・非サポートの引数

• --v2, --v_parameterization, --clip_skip - Options for Stable Diffusion v1/v2 that are not used for Anima training.
• --fp8_base - Not supported for Anima. If specified, it will be disabled with a warning.

日本語

train_network.pyのガイドで説明されている引数に加え、以下のAnima特有の引数を指定します。共通の引数については、上記ガイドを参照してください。

モデル関連 [必須]

• --pretrained_model_name_or_path="<path to Anima DiT model>" [必須] - Anima DiTモデルの.safetensorsファイルのパスを指定します。モデルの設定はstate dictから自動検出されます。net.プレフィックス付きのComfyUIフォーマットもサポートしています。
• --qwen3="<path to Qwen3-0.6B model>" [必須] - Qwen3-0.6Bテキストエンコーダーのパスを指定します。HuggingFaceモデルディレクトリまたは単体の.safetensorsファイルが使用できます。
• --vae="<path to Qwen-Image VAE model>" [必須] - Qwen-Image VAEモデルのパスを指定します。

モデル関連 [オプション]

• --llm_adapter_path="<path to LLM adapter>" [オプション] - 個別のLLM Adapterの重みファイルのパス。
• --t5_tokenizer_path="<path to T5 tokenizer>" [オプション] - T5トークナイザーディレクトリのパス。

Anima 学習パラメータ

• --timestep_sampling - タイムステップのサンプリング方法。sigma、uniform、sigmoid（デフォルト）、shift、flux_shiftから選択。FLUX学習と同じオプションです。各方法の詳細はflux_train_network.pyのガイドを参照してください。
• --discrete_flow_shift - Rectified Flow学習のタイムステップ分布シフト。デフォルト1.0。--timestep_samplingがshiftの場合に使用されます。
• --sigmoid_scale - sigmoid、shift、flux_shiftタイムステップサンプリングのスケール係数。デフォルト1.0。
• --qwen3_max_token_length - Qwen3トークナイザーの最大トークン長。デフォルト512。
• --t5_max_token_length - T5トークナイザーの最大トークン長。デフォルト512。
• --attn_mode - 使用するAttentionの実装。torch（デフォルト）、xformers、flash、sageattnから選択。xformersは--split_attnの指定が必要です。sageattnはトレーニングをサポートしていません（推論のみ）。
• --split_attn - メモリ使用量を減らすためにattention時にバッチを分割します。--attn_mode xformers使用時に必要です。

コンポーネント別学習率

これらのオプションは、Animaモデルの各コンポーネントに個別の学習率を設定します。主にフルファインチューニング用です。0に設定するとそのコンポーネントをフリーズします：

• --self_attn_lr - Self-attention層の学習率。
• --cross_attn_lr - Cross-attention層の学習率。
• --mlp_lr - MLP層の学習率。
• --mod_lr - AdaLNモジュレーション層の学習率。モジュレーション層はデフォルトではLoRAに含まれません。
• --llm_adapter_lr - LLM Adapter層の学習率。

LoRA学習の場合は、--network_argsのnetwork_reg_lrsを使用してください。セクション5.2を参照。

メモリ・速度関連

• --blocks_to_swap - TransformerブロックをCPUとGPUでスワップしてVRAMを節約。--cpu_offload_checkpointingおよび--unsloth_offload_checkpointingとは併用できません。
• --unsloth_offload_checkpointing - 非同期転送でアクティベーションをCPU RAMにオフロード。--cpu_offload_checkpointingおよび--blocks_to_swapとは併用できません。
• --cache_text_encoder_outputs - Qwen3の出力をキャッシュしてメモリ使用量を削減。
• --cache_latents, --cache_latents_to_disk - Qwen-Image VAEの出力をキャッシュ。
• --vae_chunk_size - Qwen-Image VAEのチャンク処理サイズ。メモリ使用量を削減しますが速度が低下します。デフォルトはチャンク処理なし。
• --vae_disable_cache - Qwen-Image VAEの内部キャッシュを無効化してメモリ使用量を削減します。

EMA (指数移動平均)

EMAはモデルパラメータのシャドウコピーを維持し、学習ステップにわたって平均化します。これにより、最終的な学習チェックポイントよりも滑らかで安定した重みが得られ、汎化性能が向上することがあります。EMAはフルファインチューニング（anima_train.py）とLoRA学習（anima_train_network.py）の両方でサポートされています。

• --ema - EMAを有効にします。有効にすると、通常のチェックポイントと並行してema_プレフィックス付きのEMAモデルが保存されます（例: ema_anima-000010.safetensors）。EMAモデルは通常のモデルと同じフォーマットで、そのまま推論に使用できます。
• --ema_decay - EMAの減衰率。デフォルト0.9999。高い値ほど滑らかな重みになりますが、新しい学習データへの適応が遅くなります。
• --ema_device - EMAシャドウパラメータを保存するデバイス。cuda（デフォルト）またはcpu。cpuを使用するとGPU VRAMを大幅に節約できますが、更新速度が遅くなります。
• --ema_use_num_updates - 更新ステップ数に基づいてEMA減衰率を自動調整します。早期の学習ステップでEMAのウォームアップを速くします。
• --ema_sample - デュアルサンプリングを有効にします。学習重みとEMA重みの両方でサンプル画像を生成します。EMAサンプル画像は_emaサフィックス付きで保存されます。ステップ0ではEMAがまだ十分に蓄積されていないためスキップされます。
• --ema_resume_path - 以前保存したEMAモデルからEMAを再開するためのパス。
• --ema_use_feedback [実験的] - EMAパラメータを学習モデルにフィードバックします。マルチGPU DDP学習とは互換性がありません。
• --ema_param_multiplier [実験的] - 各EMA更新後にシャドウパラメータにこの値を乗算します。デフォルト1.0。1.0以外の場合、マルチGPU DDP学習とは互換性がありません。

注意:

• --ema_device=cpuを使用すると、EMAシャドウパラメータがGPU VRAMではなくシステムRAMに保存されます。大規模モデルでVRAMが限られている場合に有用です。
• マルチGPU学習では、--ema_use_feedbackおよび--ema_param_multiplier（1.0以外）はサポートされておらず、エラーが発生します。
• EMAモデルファイルは通常のモデルと同じフォーマットです。LoRAの場合、EMA LoRAファイルは通常のLoRAファイルと同じ方法で読み込めます。

ガイダンスロス（ガイダンス蒸留）

ガイダンスロスは、Classifier-Free Guidance (CFG) の効果を学習中にモデルに直接組み込みます。推論時にCFGを使用する必要がなくなり、モデルがガイダンスされた出力を単独で生成できるようになります。各学習ステップで追加の無条件フォワードパスが必要なため、計算コストはおよそ2倍になります。

仕組み: 各学習ステップで、空プロンプトによる追加のフォワードパスを実行して無条件予測を取得します。学習ターゲットはCFGの式で修正されます：target = uncond_pred + scale * (target - uncond_pred)。モデルはこのCFG修正済みターゲットに直接マッチするよう学習します。

• --do_guidance_loss - ガイダンスロスを有効にします。空プロンプトの埋め込みを事前に計算する必要があります（自動で行われます）。追加のフォワードパスにより、ステップあたりの計算量がおよそ2倍になります。
• --guidance_loss_scale - ガイダンスロスのターゲット計算に使用するCFGスケール。デフォルト1.0。高い値ほど強いガイダンスがモデルに組み込まれます。1.0ではCFG効果なし（ターゲット変更なし）。
• --guidance_loss_cfg_zero - ガイダンスロスにCFG-Zero*を使用します。高ノイズレベル（早期タイムステップ）でCFG効果を自動的に低減し、強いCFGによるアーティファクトを防止します。

ディファレンシャルガイダンス

ディファレンシャルガイダンスは、モデルの予測がグラウンドトゥルースと最も異なる領域で学習損失を増幅します。適応的なピクセル単位の勾配スケーリングとして機能し、モデルが最も間違っている箇所をより強く修正します。

仕組み: ターゲットはグラウンドトゥルースを超えて外挿されます：target = model_pred + scale * (target - model_pred)。これにより、損失はscale^2倍に増幅されます。モデルが既に正確に予測している領域はほとんど影響を受けず、大きな誤差がある領域にはより強い勾配が適用されます。

• --do_differential_guidance - ディファレンシャルガイダンスを有効にします。追加のフォワードパスは不要です。
• --differential_guidance_scale - ディファレンシャルガイダンスのスケール係数。デフォルト3.0。高い値ほど、モデルが間違っている箇所の損失をより増幅します。実効的な損失はおよそscale^2倍にスケールされます。

ガイダンスロスとディファレンシャルガイダンスの併用: 両機能は同時に使用できます。併用時は、最初にガイダンスロスが適用され（CFGでターゲットを修正）、次にディファレンシャルガイダンスがそのCFG修正済みターゲットに対する誤差を増幅します。

注意:

• ガイダンスロスは--blocks_to_swapと互換性があります（追加のフォワードパスのためにブロックスワップ状態が自動的にリセットされます）。
• ディファレンシャルガイダンスはターゲットテンソルを修正するだけなので、追加の計算コストはありません。
• 両機能ともフルファインチューニング（anima_train.py）とLoRA学習（anima_train_network.py）の両方で動作します。

非互換・非サポートの引数

• --v2, --v_parameterization, --clip_skip - Stable Diffusion v1/v2向けの引数。Animaの学習では使用されません。
• --fp8_base - Animaではサポートされていません。指定した場合、警告とともに無効化されます。

4.2. Starting Training / 学習の開始

After setting the required arguments, run the command to begin training. The overall flow and how to check logs are the same as in the train_network.py guide.

日本語

必要な引数を設定したら、コマンドを実行して学習を開始します。全体の流れやログの確認方法は、train_network.pyのガイドと同様です。

5. LoRA Target Modules / LoRAの学習対象モジュール

When training LoRA with anima_train_network.py, the following modules are targeted by default:

• DiT Blocks (Block): Self-attention (self_attn), cross-attention (cross_attn), and MLP (mlp) layers within each transformer block. Modulation (adaln_modulation), norm, embedder, and final layers are excluded by default.
• Embedding layers (PatchEmbed, TimestepEmbedding) and Final layer (FinalLayer): Excluded by default but can be included using include_patterns.
• LLM Adapter Blocks (LLMAdapterTransformerBlock): Only when --network_args "train_llm_adapter=True" is specified.
• Text Encoder (Qwen3): Only when --network_train_unet_only is NOT specified and --cache_text_encoder_outputs is NOT used.

The LoRA network module is networks.lora_anima.

5.1. Module Selection with Patterns / パターンによるモジュール選択

By default, the following modules are excluded from LoRA via the built-in exclude pattern:

.*(_modulation|_norm|_embedder|final_layer).*

You can customize which modules are included or excluded using regex patterns in --network_args:

• exclude_patterns - Exclude modules matching these patterns (in addition to the default exclusion).
• include_patterns - Force-include modules matching these patterns, overriding exclusion.

Patterns are matched against the full module name using re.fullmatch().

Example to include the final layer:

--network_args "include_patterns=['.*final_layer.*']"

Example to additionally exclude MLP layers:

--network_args "exclude_patterns=['.*mlp.*']"

5.2. Regex-based Rank, Alpha, and Learning Rate Control / 正規表現によるランク・アルファ・学習率の制御

You can specify different ranks (network_dim), alphas (network_alpha), and learning rates for modules matching specific regex patterns:

• network_reg_dims: Specify ranks for modules matching a regular expression. The format is a comma-separated string of pattern=rank.
  • Example: --network_args "network_reg_dims=.*self_attn.*=8,.*cross_attn.*=4,.*mlp.*=8"
  • This sets the rank to 8 for self-attention modules, 4 for cross-attention modules, and 8 for MLP modules.
• network_reg_alphas: Specify alphas for modules matching a regular expression. The format is a comma-separated string of pattern=alpha.
  • Example: --network_args "network_reg_alphas=.*self_attn.*=4,.*mlp.*=8"
  • This sets the alpha to 4 for self-attention modules and 8 for MLP modules.
  • Alpha controls the effective scaling of LoRA: effective_scale = alpha / dim. A lower alpha relative to dim reduces the LoRA's influence.
• network_reg_lrs: Specify learning rates for modules matching a regular expression. The format is a comma-separated string of pattern=lr.
  • Example: --network_args "network_reg_lrs=.*self_attn.*=1e-4,.*cross_attn.*=5e-5"
  • This sets the learning rate to 1e-4 for self-attention modules and 5e-5 for cross-attention modules.

Priority order:

1. network_reg_dims sets the rank for matched modules. If network_reg_alphas is also specified and matches the same module, that alpha is used; otherwise the global --network_alpha is used.
2. network_reg_alphas can override the alpha independently, even for modules not matched by network_reg_dims.
3. Modules not matched by any regex pattern fall back to the global --network_dim and --network_alpha.
4. network_reg_lrs overrides the learning rate independently of rank/alpha settings.

Notes:

• Settings via network_reg_dims, network_reg_alphas, and network_reg_lrs take precedence over the global --network_dim, --network_alpha, and --learning_rate settings.
• Patterns are matched using re.fullmatch() against the module's original name (e.g., blocks.0.self_attn.q_proj).

5.3. LLM Adapter LoRA / LLM Adapter LoRA

To apply LoRA to the LLM Adapter blocks:

--network_args "train_llm_adapter=True"

In preliminary tests, lowering the learning rate for the LLM Adapter seems to improve stability. Adjust it using something like: "network_reg_lrs=.*llm_adapter.*=5e-5".

5.4. Other Network Args / その他のネットワーク引数

• --network_args "verbose=True" - Print all LoRA module names and their dimensions.
• --network_args "rank_dropout=0.1" - Rank dropout rate.
• --network_args "module_dropout=0.1" - Module dropout rate.
• --network_args "loraplus_lr_ratio=2.0" - LoRA+ learning rate ratio.
• --network_args "loraplus_unet_lr_ratio=2.0" - LoRA+ learning rate ratio for DiT only.
• --network_args "loraplus_text_encoder_lr_ratio=2.0" - LoRA+ learning rate ratio for text encoder only.

日本語

anima_train_network.pyでLoRAを学習させる場合、デフォルトでは以下のモジュールが対象となります。

• DiTブロック (Block): 各Transformerブロック内のSelf-attention（self_attn）、Cross-attention（cross_attn）、MLP（mlp）層。モジュレーション（adaln_modulation）、norm、embedder、final layerはデフォルトで除外されます。
• 埋め込み層 (PatchEmbed, TimestepEmbedding) と最終層 (FinalLayer): デフォルトで除外されますが、include_patternsで含めることができます。
• LLM Adapterブロック (LLMAdapterTransformerBlock): --network_args "train_llm_adapter=True"を指定した場合のみ。
• テキストエンコーダー (Qwen3): --network_train_unet_onlyを指定せず、かつ--cache_text_encoder_outputsを使用しない場合のみ。

5.1. パターンによるモジュール選択

デフォルトでは以下のモジュールが組み込みの除外パターンによりLoRAから除外されます：

.*(_modulation|_norm|_embedder|final_layer).*

--network_argsで正規表現パターンを使用して、含めるモジュールと除外するモジュールをカスタマイズできます：

• exclude_patterns - これらのパターンにマッチするモジュールを除外（デフォルトの除外に追加）。
• include_patterns - これらのパターンにマッチするモジュールを強制的に含める（除外を上書き）。

パターンはre.fullmatch()を使用して完全なモジュール名に対してマッチングされます。

5.2. 正規表現によるランク・アルファ・学習率の制御

正規表現にマッチするモジュールに対して、異なるランク、アルファ、学習率を指定できます：

• network_reg_dims: 正規表現にマッチするモジュールに対してランクを指定します。pattern=rank形式の文字列をカンマで区切って指定します。
  • 例: --network_args "network_reg_dims=.*self_attn.*=8,.*cross_attn.*=4,.*mlp.*=8"
• network_reg_alphas: 正規表現にマッチするモジュールに対してアルファを指定します。pattern=alpha形式の文字列をカンマで区切って指定します。
  • 例: --network_args "network_reg_alphas=.*self_attn.*=4,.*mlp.*=8"
  • アルファはLoRAの実効的なスケーリングを制御します：effective_scale = alpha / dim。dimに対してアルファが低いほど、LoRAの影響が小さくなります。
• network_reg_lrs: 正規表現にマッチするモジュールに対して学習率を指定します。pattern=lr形式の文字列をカンマで区切って指定します。
  • 例: --network_args "network_reg_lrs=.*self_attn.*=1e-4,.*cross_attn.*=5e-5"

優先順位:

1. network_reg_dimsはマッチしたモジュールのランクを設定します。network_reg_alphasも指定されており同じモジュールにマッチする場合はそのアルファが使用されます。マッチしない場合はグローバルの--network_alphaが使用されます。
2. network_reg_alphasは、network_reg_dimsにマッチしていないモジュールに対してもアルファを独立して上書きできます。
3. どの正規表現パターンにもマッチしないモジュールは、グローバルの--network_dimと--network_alphaにフォールバックします。
4. network_reg_lrsはランク/アルファの設定とは独立して学習率を上書きします。

注意点:

• network_reg_dims、network_reg_alphas、network_reg_lrsでの設定は、全体設定である--network_dim、--network_alpha、--learning_rateよりも優先されます。
• パターンはモジュールのオリジナル名（例: blocks.0.self_attn.q_proj）に対してre.fullmatch()でマッチングされます。

5.3. LLM Adapter LoRA

LLM AdapterブロックにLoRAを適用するには：--network_args "train_llm_adapter=True"

簡易な検証ではLLM Adapterの学習率はある程度下げた方が安定するようです。"network_reg_lrs=.*llm_adapter.*=5e-5"などで調整してください。

5.4. その他のネットワーク引数

• verbose=True - 全LoRAモジュール名とdimを表示
• rank_dropout - ランクドロップアウト率
• module_dropout - モジュールドロップアウト率
• loraplus_lr_ratio - LoRA+学習率比率
• loraplus_unet_lr_ratio - DiT専用のLoRA+学習率比率
• loraplus_text_encoder_lr_ratio - テキストエンコーダー専用のLoRA+学習率比率

6. Using the Trained Model / 学習済みモデルの利用

When training finishes, a LoRA model file (e.g. my_anima_lora.safetensors) is saved in the directory specified by output_dir. Use this file with inference environments that support Anima, such as ComfyUI with appropriate nodes.

日本語

学習が完了すると、指定したoutput_dirにLoRAモデルファイル（例: my_anima_lora.safetensors）が保存されます。このファイルは、Anima モデルに対応した推論環境（例: ComfyUI + 適切なノード）で使用できます。

7. Advanced Settings / 高度な設定

7.1. VRAM Usage Optimization / VRAM使用量の最適化

Anima models can be large, so GPUs with limited VRAM may require optimization:

Key VRAM Reduction Options

• --blocks_to_swap <number>: Swaps blocks between CPU and GPU to reduce VRAM usage. Higher numbers save more VRAM but reduce training speed. See model-specific max values in section 4.1.

• --unsloth_offload_checkpointing: Offloads gradient checkpoints to CPU using async non-blocking transfers. Faster than --cpu_offload_checkpointing. Cannot be combined with --blocks_to_swap.

• --gradient_checkpointing: Standard gradient checkpointing to reduce VRAM at the cost of compute.

• --cache_text_encoder_outputs: Caches Qwen3 outputs so the text encoder can be freed from VRAM during training.

• --cache_latents: Caches Qwen-Image VAE outputs so the VAE can be freed from VRAM during training.

• Using Adafactor optimizer: Can reduce VRAM usage:

  --optimizer_type adafactor --optimizer_args "relative_step=False" "scale_parameter=False" "warmup_init=False" --lr_scheduler constant_with_warmup --max_grad_norm 0.0
  

日本語

Animaモデルは大きい場合があるため、VRAMが限られたGPUでは最適化が必要です。

主要なVRAM削減オプション：

• --blocks_to_swap: CPUとGPU間でブロックをスワップ
• --unsloth_offload_checkpointing: 非同期転送でアクティベーションをCPUにオフロード
• --gradient_checkpointing: 標準的な勾配チェックポイント
• --cache_text_encoder_outputs: Qwen3の出力をキャッシュ
• --cache_latents: Qwen-Image VAEの出力をキャッシュ
• Adafactorオプティマイザの使用

7.2. Training Settings / 学習設定

Timestep Sampling

The --timestep_sampling option specifies how timesteps are sampled. The available methods are the same as FLUX training:

• sigma: Sigma-based sampling like SD3.
• uniform: Uniform random sampling from [0, 1].
• sigmoid (default): Sample from Normal(0,1), multiply by sigmoid_scale, apply sigmoid. Good general-purpose option.
• shift: Like sigmoid, but applies the discrete flow shift formula: t_shifted = (t * shift) / (1 + (shift - 1) * t).
• flux_shift: Resolution-dependent shift used in FLUX training.

See the flux_train_network.py guide for detailed descriptions.

Discrete Flow Shift

The --discrete_flow_shift option (default 1.0) only applies when --timestep_sampling is set to shift. The formula is:

t_shifted = (t * shift) / (1 + (shift - 1) * t)

Loss Weighting

The --weighting_scheme option specifies loss weighting by timestep:

• uniform (default): Equal weight for all timesteps.
• sigma_sqrt: Weight by sigma^(-2).
• cosmap: Weight by 2 / (pi * (1 - 2*sigma + 2*sigma^2)).
• none: Same as uniform.
• logit_normal, mode: Additional schemes from SD3 training. See the sd3_train_network.md guide for details.

Caption Dropout

Caption dropout uses the caption_dropout_rate setting from the dataset configuration (per-subset in TOML). When using --cache_text_encoder_outputs, the dropout rate is stored with each cached entry and applied during training, so caption dropout is compatible with text encoder output caching.

If you change the caption_dropout_rate setting, you must delete and regenerate the cache.

Note: Currently, only Anima supports combining caption_dropout_rate with text encoder output caching.

日本語

タイムステップサンプリング

--timestep_samplingでタイムステップのサンプリング方法を指定します。FLUX学習と同じ方法が利用できます：

• sigma: SD3と同様のシグマベースサンプリング。
• uniform: [0, 1]の一様分布からサンプリング。
• sigmoid（デフォルト）: 正規分布からサンプリングし、sigmoidを適用。汎用的なオプション。
• shift: sigmoidと同様だが、離散フローシフトの式を適用。
• flux_shift: FLUX学習で使用される解像度依存のシフト。

詳細はflux_train_network.pyのガイドを参照してください。

離散フローシフト

--discrete_flow_shift（デフォルト1.0）は--timestep_samplingがshiftの場合のみ適用されます。

損失の重み付け

--weighting_schemeでタイムステップごとの損失の重み付けを指定します。

キャプションドロップアウト

キャプションドロップアウトにはデータセット設定（TOMLでのサブセット単位）のcaption_dropout_rateを使用します。--cache_text_encoder_outputs使用時は、ドロップアウト率が各キャッシュエントリとともに保存され、学習中に適用されるため、テキストエンコーダー出力キャッシュと同時に使用できます。

caption_dropout_rateの設定を変えた場合、キャッシュを削除し、再生成する必要があります。

※caption_dropout_rateをテキストエンコーダー出力キャッシュと組み合わせられるのは、今のところAnimaのみです。

7.3. Text Encoder LoRA Support / Text Encoder LoRAのサポート

Anima LoRA training supports training Qwen3 text encoder LoRA:

• To train only DiT: specify --network_train_unet_only
• To train DiT and Qwen3: omit --network_train_unet_only and do NOT use --cache_text_encoder_outputs

You can specify a separate learning rate for Qwen3 with --text_encoder_lr. If not specified, the default --learning_rate is used.

Note: When --cache_text_encoder_outputs is used, text encoder outputs are pre-computed and the text encoder is removed from GPU, so text encoder LoRA cannot be trained.

日本語

Anima LoRA学習では、Qwen3テキストエンコーダーのLoRAもトレーニングできます。

• DiTのみ学習: --network_train_unet_onlyを指定
• DiTとQwen3を学習: --network_train_unet_onlyを省略し、--cache_text_encoder_outputsを使用しない

Qwen3に個別の学習率を指定するには--text_encoder_lrを使用します。未指定の場合は--learning_rateが使われます。

注意: --cache_text_encoder_outputsを使用する場合、テキストエンコーダーの出力が事前に計算されGPUから解放されるため、テキストエンコーダーLoRAは学習できません。

8. Other Training Options / その他の学習オプション

• --loss_type: Loss function for training. Default l2.

  • l1: L1 loss.
  • l2: L2 loss (mean squared error).
  • huber: Huber loss.
  • smooth_l1: Smooth L1 loss.

• --huber_schedule, --huber_c, --huber_scale: Parameters for Huber loss when --loss_type is huber or smooth_l1.

• --ip_noise_gamma, --ip_noise_gamma_random_strength: Input Perturbation noise gamma values.

• --fused_backward_pass: Fuses the backward pass and optimizer step to reduce VRAM usage. Only works with Adafactor. For details, see the sdxl_train_network.py guide.

• --weighting_scheme, --logit_mean, --logit_std, --mode_scale: Timestep loss weighting options. For details, refer to the sd3_train_network.md guide.

日本語

• --loss_type: 学習に用いる損失関数。デフォルトl2。l1, l2, huber, smooth_l1から選択。
• --huber_schedule, --huber_c, --huber_scale: Huber損失のパラメータ。
• --ip_noise_gamma: Input Perturbationノイズガンマ値。
• --fused_backward_pass: バックワードパスとオプティマイザステップの融合。
• --weighting_scheme 等: タイムステップ損失の重み付け。詳細はsd3_train_network.mdを参照。

9. Related Tools / 関連ツール

networks/anima_convert_lora_to_comfy.py

A script to convert LoRA models to ComfyUI-compatible format. ComfyUI does not directly support sd-scripts format Qwen3 LoRA, so conversion is necessary (conversion may not be needed for DiT-only LoRA). You can convert from the sd-scripts format to ComfyUI format with:

python networks/convert_anima_lora_to_comfy.py path/to/source.safetensors path/to/destination.safetensors

Using the --reverse option allows conversion in the opposite direction (ComfyUI format to sd-scripts format). However, reverse conversion is only possible for LoRAs converted by this script. LoRAs created with other training tools cannot be converted.

日本語

networks/convert_anima_lora_to_comfy.py

LoRAモデルをComfyUI互換形式に変換するスクリプト。ComfyUIがsd-scripts形式のQwen3 LoRAを直接サポートしていないため、変換が必要です（DiTのみのLoRAの場合は変換不要のようです）。sd-scripts形式からComfyUI形式への変換は以下のコマンドで行います：

python networks/convert_anima_lora_to_comfy.py path/to/source.safetensors path/to/destination.safetensors

--reverseオプションを付けると、逆変換（ComfyUI形式からsd-scripts形式）も可能です。ただし、逆変換ができるのはこのスクリプトで変換したLoRAに限ります。他の学習ツールで作成したLoRAは変換できません。

10. Others / その他

Metadata Saved in LoRA Models

The following metadata is saved in the LoRA model file:

• ss_weighting_scheme
• ss_logit_mean
• ss_logit_std
• ss_mode_scale
• ss_timestep_sampling
• ss_sigmoid_scale
• ss_discrete_flow_shift

日本語

anima_train_network.pyには、サンプル画像の生成 (--sample_promptsなど) や詳細なオプティマイザ設定など、train_network.pyと共通の機能も多く存在します。これらについては、train_network.pyのガイドやスクリプトのヘルプ (python anima_train_network.py --help) を参照してください。

LoRAモデルに保存されるメタデータ

以下のメタデータがLoRAモデルファイルに保存されます：

• ss_weighting_scheme
• ss_logit_mean
• ss_logit_std
• ss_mode_scale
• ss_timestep_sampling
• ss_sigmoid_scale
• ss_discrete_flow_shift