Files
Kohya S.andClaude Opus 4.8 b1f32e5820 Refactor for ai agents (#2372)
* refactor(phase0): 不要ファイルの削除と補助スクリプトの整理

- 非推奨スクリプトを削除: train_controlnet.py, sdxl_train_control_net_lllite_old.py,
  networks/merge_lora_old.py, train_textual_inversion_XTI.py
- 不要ディレクトリを削除: bitsandbytes_windows/, wuerstchen/
- XTI_hijack.py を gen_img_diffusers.py にインライン化して削除
- pytest 用 5–6 行スタブテストを削除(test_train.py 等 10 件)
- 開発補助スクリプトを tools/dev/ へ移動: manual_test_anima_*.py, visualize_masks.py

インペインティングテストランナー (run_*_inpainting_test.*) と密結合する
_verify_inpainting_checkpoint.py / generate_inpainting_test_data.py /
download_training_data.py は tests/ に維持。

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase1a): library.subset を train_util.py から分離

BaseSubset / DreamBoothSubset / FineTuningSubset / ControlNetSubset の 4 クラスを
新規モジュール library/subset.py に移動。train_util.py 側は後方互換のため
re-export shim を残す。

- library/subset.py: 新規(typing 以外の依存なし)
- library/train_util.py: クラス定義 270 行を削除し re-export に置換
- library/config_util.py: subset クラスの import 元を library.subset に切替

動作仕様の変更なし。train_util.py 経由の既存 import は引き続き動作する。

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase1b): library.caching を train_util.py から分離

VAE latent / text encoder output のキャッシュ関連 8 関数を新規モジュール
library/caching.py に移動。train_util.py 側は後方互換のため re-export。

PR-1(dataset 系)の 2 つ目の PR。BaseDataset がこれらの caching 関数を
内部で呼び出すため、後続の dataset.py 抽出(PR-1c)に先立って caching を
独立させ、循環依存を回避する。

- library/caching.py: 新規 8 関数
  - is_disk_cached_latents_is_expected
  - trim_and_resize_if_required
  - load_images_and_masks_for_caching
  - cache_batch_latents
  - cache_batch_text_encoder_outputs
  - cache_batch_text_encoder_outputs_sd3
  - save_text_encoder_outputs_to_disk
  - load_text_encoder_outputs_from_disk
- library/train_util.py: 上記 8 関数の定義を削除し re-export に置換
- library/strategy_base.py: caching.load_images_and_masks_for_caching を直接 import
- finetune/prepare_buckets_latents.py: caching.* を直接 import

train_util.py には BucketManager / load_image / HIGH_VRAM / get_hidden_states_sdxl
が残るため、caching は循環回避のため関数内で `_tu()` 経由で参照する
(PR-1c で dataset.py へ移動した後に整理予定)。

動作仕様の変更なし。両方向の import 順序で動作確認済み。

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase1c): library.dataset を train_util.py から分離

データセット骨格となる以下の要素を新規モジュール library/dataset.py に移動。
train_util.py 側は後方互換のため re-export shim を残す。

PR-1(dataset 系)の 3 つ目の PR。約 1,800 行の最大級の抽出。

## 移動した要素(library/dataset.py、約 1,960 行)

定数:
- IMAGE_EXTENSIONS(pillow_avif / jxl の条件付き拡張含む)
- IMAGE_TRANSFORMS
- TEXT_ENCODER_OUTPUTS_CACHE_SUFFIX / _SD3

クラス:
- ImageInfo(画像メタデータ)
- BucketManager(アスペクト比 bucket)
- BucketBatchIndex(NamedTuple)
- AugHelper(color augmentation)
- BaseDataset(DreamBooth/FineTuning/ControlNet 共通の抽象データセット、約 1,260 行)
- DatasetGroup(torch.utils.data.ConcatDataset サブクラス)
- MinimalDataset(ユーザー定義データセット用)

関数:
- split_train_val
- debug_dataset
- glob_images / glob_images_pathlib
- load_arbitrary_dataset
- load_image

## 後方互換

DreamBoothDataset / FineTuningDataset / ControlNetDataset の 3 つは引き続き
train_util.py に残る(PR-1d で移動予定)。BaseDataset を継承する関係で、
train_util 内のサブクラスは re-export 経由で BaseDataset を参照する。

## 循環依存の整理

caching.py を更新:
- _ds() ヘルパーを追加し、library.dataset の BucketManager / load_image /
  IMAGE_TRANSFORMS を遅延参照
- _tu() は HIGH_VRAM / get_hidden_states_sdxl 用に維持
- caching.py 内の重複 IMAGE_TRANSFORMS 定義を削除(library.dataset を単一の
  ソースに)

## 内部参照の切替

- tests/test_validation.py: from library.dataset import split_train_val
- finetune/prepare_buckets_latents.py: dataset.BucketManager / dataset.ImageInfo を直接使用

学習スクリプト(train_*.py、fine_tune.py 等)の train_util.X 属性アクセスは
shim 経由で動作するため、後続 PR で順次切替予定。

## 動作確認

- ✅ library.dataset / caching / train_util / config_util / strategy_base 単独 import
- ✅ 両方向の import 順序
- ✅ 全主要学習スクリプト(fine_tune, train_db, train_network, sdxl/sd3/flux/lumina/anima 系)の py_compile

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* fix(phase1c): dataset.py の glob エイリアス除去

import glob as _glob としていたため、glob_images / glob_images_pathlib 内の
glob.glob(...) / glob.escape(...) 呼び出しが NameError になっていた。
元コードと同じ import glob に戻す。

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* fix(phase1c): dataset.py に欠落していた import を追加

抽出時に top-level import が漏れていたため、BaseDataset のメソッドが
実行時 NameError になっていた:

- tqdm: from tqdm import tqdm
- re: import re
- Future / ThreadPoolExecutor: from concurrent.futures import ...

また、HIGH_VRAM の参照を _tu().HIGH_VRAM に修正(HIGH_VRAM は train_util に
mutable global として残存しており、本モジュールには無いため)。

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase1d): DreamBooth/FineTuning/ControlNet データセットを分離

PR-1(dataset 系)の最終 PR。BaseDataset を継承する 3 つの具象データセット
クラスを、それぞれ独立したモジュールに移動。

## 新規モジュール

- library/dreambooth_dataset.py: DreamBoothDataset(約 379 行)
- library/finetuning_dataset.py: FineTuningDataset(約 280 行)
- library/controlnet_dataset.py: ControlNetDataset(約 279 行)

## 後方互換

train_util.py 側は約 760 行を削除し、3 クラスを re-export shim で維持:

    from library.dreambooth_dataset import DreamBoothDataset
    from library.finetuning_dataset import FineTuningDataset
    from library.controlnet_dataset import ControlNetDataset

## モジュール間依存

ControlNetDataset は内部で DreamBoothDataset / DreamBoothSubset を委譲先として
利用するため、library.controlnet_dataset → library.dreambooth_dataset の
依存がある。

## PR-1 シリーズ完了

これで train_util.py からのデータセット系分割(PR-1a〜1d)が完了。
- library/subset.py(PR-1a, #2333)
- library/caching.py(PR-1b, #2334)
- library/dataset.py(PR-1c, #2335)
- library/dreambooth_dataset.py / finetuning_dataset.py / controlnet_dataset.py
  (本 PR)

train_util.py は 6,888 行 → 3,774 行に縮小(約 45% 削減)。

## 動作確認

- ✅ 3 つの新規モジュール単独 import
- ✅ 全 PR-1 系列の identity(library.* と train_util re-export が同じクラス)
- ✅ 継承関係(DreamBoothDataset / FineTuningDataset / ControlNetDataset が
  BaseDataset のサブクラス)
- ✅ 全主要学習スクリプト(fine_tune, train_db, train_network, sdxl/sd3/flux/
  lumina/anima 系および各 control_net 系)の py_compile

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase2): 引数定義と設定ヘルパーを library/args.py に分離

train_util.py の add_*_arguments, verify_*, get_sanitized_config_or_none,
read_config_from_file, resume_from_local_or_hf_if_specified の計 12 関数を
library/args.py に移動。train_util.py は re-export shim として維持。
enable_high_vram は accelerator 系(PR-3 で accelerator_setup.py 行き)の
ため train_util.py に残し、verify_training_args からは関数内 import で参照。

train_util.py: 3,774 → 2,600 行 (1,174 行削減)
library/args.py: 1,221 行(新規)

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase3a): hidden states 関連を library/hidden_states.py に分離

train_util.py の get_hidden_states / pool_workaround / get_hidden_states_sdxl
を library/hidden_states.py に移動。train_util.py は re-export shim として維持。
caching.py は循環依存が無いため _tu() 経由ではなく直接 import に変更。

train_util.py: 2,600 → 2,449 行
library/hidden_states.py: 173 行(新規)

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase3b): model I/O・hash・metadata 系を library/model_io.py に分離

train_util.py から以下を library/model_io.py に移動:
- ハッシュ系: model_hash / calculate_sha256 / addnet_hash_legacy /
  addnet_hash_safetensors / precalculate_safetensors_hashes / get_git_revision_hash
- attention 切替: replace_unet_modules
- safetensors metadata: load_metadata_from_safetensors
- ss_* metadata: SS_METADATA_KEY_* 定数 + SS_METADATA_MINIMUM_KEYS +
  build_minimum_network_metadata
- SAI ModelSpec: get_sai_model_spec / get_sai_model_spec_dataclass
- model loader: _load_target_model / load_target_model

計 13 関数 + 7 定数。train_util.py は re-export shim として維持。
networks/lora_interrogator.py が train_util._load_target_model を参照しているため
shim にも _load_target_model を含める。

train_util.py: 2,449 → 2,103 行
library/model_io.py: 421 行(新規)

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase3c): accelerator setup を library/accelerator_setup.py に分離

train_util.py から以下を library/accelerator_setup.py に移動:
- HIGH_VRAM (mutable module-level flag)
- enable_high_vram
- prepare_dataset_args
- prepare_accelerator
- prepare_dtype
- patch_accelerator_for_fp16_training

train_util.py は関数の re-export shim を維持しつつ、HIGH_VRAM 属性アクセスは
module-level __getattr__ で accelerator_setup.HIGH_VRAM へ動的転送する。
これにより train_util.HIGH_VRAM 形式の参照(外部スクリプト互換性)でも
最新値が読み取れる。

リポジトリ内コードは shim に依存しない方針に従い、HIGH_VRAM の参照を
新パス直接参照に切替:
- library/args.py: enable_high_vram の参照
- library/caching.py: _tu().HIGH_VRAM → accelerator_setup.HIGH_VRAM
  (HIGH_VRAM のためだけに残っていた _tu() ヘルパーは削除)
- library/dataset.py: 同上 (_tu() ヘルパー削除)
- library/strategy_{sd,flux,sd3,lumina,anima,hunyuan_image}.py 6 ファイル:
  train_util.HIGH_VRAM → accelerator_setup.HIGH_VRAM

train_util.py: 2,103 → 1,969 行
library/accelerator_setup.py: 186 行(新規)

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase3d): optimizer / scheduler を library/optimizer.py に分離

train_util.py から以下を library/optimizer.py に移動:
- get_optimizer (AdamW / 8bit / Lion / DAdaptation / Prodigy / Adafactor /
  schedule-free / 任意の module.Class 形式に対応する統合ディスパッチャ)
- get_optimizer_train_eval_fn / is_schedulefree_optimizer / get_dummy_scheduler
- get_scheduler_fix (LR scheduler ファクトリ)
- append_lr_to_logs / append_lr_to_logs_with_names

get_my_scheduler は noise scheduler でサンプリング系のため対象外(PR-4 で
sampling.py 行きの予定)。

train_util.py は re-export shim を維持。tests/test_optimizer.py は明示 import
していたため、shim 非依存方針に従い from library.optimizer import に切替。

train_util.py: 1,969 → 1,379 行
library/optimizer.py: 637 行(新規)
累計 6,888 → 1,379 行(80% 削減、PR-3 完了)

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase4a): logging / tracker helpers を library/logging_util.py に分離

train_util.py から init_trackers と LossRecorder を library/logging_util.py
へ切り出し、旧位置は re-export shim に置換。

呼び出し側はすべて train_util.init_trackers / train_util.LossRecorder
の属性アクセスで利用しているため shim 経由で動作し、修正不要。

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase4a): 当リポジトリ内の参照を library.logging_util へ切替

train_util.init_trackers / train_util.LossRecorder を logging_util.* で
直接参照する形に変更。15 ファイルで logging_util の import 追加と
属性アクセスの置換を実施。

train_util.py 経由の re-export shim は fork 互換のため引き続き維持。

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase4b): loss / noise scheduling helpers を library/loss.py に分離

train_util.py から以下を library/loss.py に移動:
- get_timesteps (バッチ単位の diffusion timestep サンプリング)
- get_noise_noisy_latents_and_timesteps (noise offset / multires noise /
  IP noise 適用後のノイズ付き latents 生成)
- get_huber_threshold_if_needed (Huber/Smooth-L1 用の per-timestep
  threshold スケジュール: exponential / snr / constant)
- conditional_loss (l2 / l1 / huber / smooth_l1 のディスパッチャ)

train_util.py は re-export shim を維持。当リポジトリ内 14 ファイルの呼び出し
を loss_util.* (alias) に切替。loss というローカル変数名と衝突するため
import library.loss as loss_util の形で導入。

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase4c): checkpoint 保存系を library/checkpoint_io.py に分離

train_util.py から以下を library/checkpoint_io.py に移動:
- ファイル名テンプレート定数 (EPOCH_FILE_NAME / STEP_STATE_NAME 等 10 個)
- default_if_none / get_epoch_ckpt_name / get_step_ckpt_name /
  get_last_ckpt_name (チェックポイント名ビルダ)
- get_remove_epoch_no / get_remove_step_no
  (--save_last_n_epochs / --save_last_n_steps の rotate 計算)
- save_sd_model_on_epoch_end_or_stepwise(_common) /
  save_sd_model_on_train_end(_common)
  (SD 1.x/2.x checkpoint 保存 + HF Hub upload + rotate)
- save_and_remove_state_on_epoch_end / save_and_remove_state_stepwise /
  save_state_on_train_end (accelerator state 保存 + rotate)

train_util.py は re-export shim を維持。当リポジトリ内 14 トップレベル
スクリプトと library/{anima,flux,leco,lumina,sd3,sdxl}_train_util.py 6 ファイル
の参照を checkpoint_io.* (alias) に切替。

train_util.py: 1,275 → 975 行 (250 行削減)。
library/checkpoint_io.py: 348 行 (新規)。

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase4d): sample 画像生成系を library/sampling.py に分離

train_util.py から以下を library/sampling.py に移動 (498 行):
- noise scheduler 定数 (SCHEDULER_LINEAR_START / _END / _TIMESTEPS / SCHEDLER_SCHEDULE)
- get_my_scheduler (--sample_sampler 名 → diffusers Scheduler ファクトリ)
- line_to_prompt_dict / load_prompts (.txt / .toml / .json プロンプト解析)
- sample_images / sample_images_common / sample_image_inference
  (multi-GPU 分配・RNG 退避・inpainting 入力・W&B 画像 upload)

train_util.py は re-export shim を維持。当リポジトリ内 16 トップレベル
+ 5 library/*_train_util.py = 21 ファイルの参照を sampling.* (alias) に切替。

循環依存対策: sampling.py → sdxl_lpw_stable_diffusion → sdxl_train_util →
train_util → sampling のループになるため、SdxlStableDiffusionLongPromptWeightingPipeline
は sample_image_inference 内で遅延 import (isinstance チェックでのみ使用)。

train_util.py: 975 → 555 行 (420 行削減)。

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(cleanup): train_util.py の残置 import / コメント遺物を整理

- 旧本体時代の unused top-level imports 80件を削除
- F811 重複定義 2件を解消 (logging / UNet2DConditionModel)
- replace_unet_modules / replace_vae_modules / load_latents_from_disk
  などのコメントアウト遺物を削除
- 各 shim block の noqa を F401, E402 へ更新
- clean_memory_on_device は strategy_lumina.py からの train_util.X
  参照が残るため shim として維持

train_util.py 555 → 295 行 (47% 削減)、ruff check clean、pytest 150 passed

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(cleanup): train_util.py の小ヘルパーと前処理クラスを再配置

- EPSILON / exists / default は参照ゼロのため完全削除(shim も置かない)
- ImageLoadingDataset を finetune/image_loading_dataset.py 新設に移動
  - 参照元 (finetune/prepare_buckets_latents.py / make_captions_by_git.py)
    の 2 箇所を新パス参照に書き換え
  - train_util shim は置かない(参照元が finetune/ 内に閉じているため)
- collator_class を library/dataset.py に移動し train_util から re-export
  - 学習スクリプト 15 ファイルの train_util.collator_class 参照は
    shim 経由でそのまま動作するため書き換え不要

train_util.py 295 → 222 行、pytest 150 passed

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(cleanup): 旧 cache_latents / cache_text_encoder_outputs 系メソッドを削除

学習スクリプト・tools/cache_*.py はすべて new_cache_latents /
new_cache_text_encoder_outputs に切り替わっており、以下の旧 API はどこからも呼ばれていない。

- BaseDataset.cache_latents
- BaseDataset.cache_text_encoder_outputs / _sd3 / _common
- DatasetGroup.cache_latents / cache_text_encoder_outputs / _sd3
- ControlNetDataset.cache_latents

合計 224 行を削除。pytest 全 150 件パス + 実機スモークテスト確認済。

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(cleanup): caching.py の連鎖デッド関数と未使用 import を整理

PR #2348 で BaseDataset.cache_text_encoder_outputs_common 等が削除された結果、
それらからのみ呼ばれていた caching.py 内の以下が完全にデッドになったため削除。

- cache_batch_text_encoder_outputs
- cache_batch_text_encoder_outputs_sd3
- save_text_encoder_outputs_to_disk
- load_text_encoder_outputs_from_disk

これに伴う未使用 import の整理:
- library/caching.py: sd3_utils / get_hidden_states_sdxl の import 削除
- library/dataset.py: cache_batch_* / is_disk_cached_latents_is_expected の import 削除、
  古いコメント遺物 1 行削除
- library/{controlnet,dreambooth,finetuning}_dataset.py: caching からの旧 import ブロック
  全削除、TEXT_ENCODER_OUTPUTS_CACHE_SUFFIX* も未使用のため削除
- library/train_util.py: 削除済み関数の re-export 5 行削除(fork 側も new_* に
  移行する必要があるため shim 維持の意義なし)

合計 -121 / +4 行。pytest 全 150 件パス。

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(cleanup): caching_mode 系のデッドコードを削除

strategy パターン導入以降、DatasetGroup.set_caching_mode は外部から呼ばれて
おらず、self.caching_mode は永遠に None。連鎖して以下が完全にデッドコード化
していたため削除。

- BaseDataset.set_caching_mode / DatasetGroup.set_caching_mode
- self.caching_mode 属性 (init=None)
- BaseDataset.__getitem__ 内の caching_mode 分岐
- BaseDataset.get_item_for_caching
- BaseDataset.get_input_ids
  - self.tokenizers / self.tokenizer_max_length 属性が BaseDataset で
    一度も代入されておらず、呼ばれた時点で AttributeError になる構造で、
    実行されていないことの裏付けにもなっていた

加えて、上記参照を含むコメントアウト遺物を削除し、MinimalDataset の docstring
内例の self.get_input_ids 参照を strategy ベース (self.tokenize_strategy.tokenize)
に更新。

合計 -154/+1 行。pytest 全 150 件パス。

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(cleanup): SdxlNetworkTrainer.get_text_cond のデッドコードを削除

`SdxlNetworkTrainer.get_text_cond` はリポジトリ内のどこからも呼ばれていない
デッドコードとなっていた(SDXL の text encoder 出力取得は
`strategy_sdxl.SdxlTextEncodingStrategy` 経由に完全移行済)。これを削除する。

連鎖的にデッド化する `library.hidden_states.get_hidden_states_sdxl` は、
fork 側で `train_util.get_hidden_states_sdxl` を直接参照している可能性に
配慮し、関数本体・shim ともに残す。代わりに「もはや当リポジトリからは
呼ばれておらず、将来削除候補である」旨をモジュール docstring と関数直前の
コメントに明記した。

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase2-1): NetworkTrainer.train() からメタデータ構築を _build_metadata() に分離

- 約 230 行のメタデータ構築ブロック(基本設定 / データセット / モデルハッシュ / minimum_metadata 抽出)を専用メソッドに切り出し
- train() 内のインライン処理を 17 行のメソッド呼び出しに置換
- サブクラスの update_metadata フックは現状の (metadata, args) シグネチャを維持
- 動作仕様は変更なし。dump 比較で session_id / training_started_at 以外の差分がないことを確認

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* fix: split_train_val をインポート

* refactor(phase2-2): step版/epoch版 validation の重複を _run_validation_loop() に統合

- 重複していた validation ブロック (step 版 67 行 + epoch 版 70 行) を共通メソッドに集約
- mode: Literal["step", "epoch"] 引数で tqdm desc / progress postfix / log キー名 / log 送信関数 (step_logging vs epoch_logging) を切替
- on_step_start と args.min/max_timestep 代入の順序を step 版に統一 (元の epoch 版は順序が逆だったが、ベース/全サブクラスの on_step_start は args.min_timestep を参照しないため実質的影響なし)
- epoch 版にあった avr_loss 中間変数は削除し loss_recorder.moving_average を直接利用 (step 版の書き方に揃える)
- 呼出側 (train() 内) は setup (optimizer_eval_fn / network.eval / switch_rng_state) と teardown (restore_rng_state / args 復元 / optimizer_train_fn / network.train / progress_bar.unpause) を保持

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase2-3): save_model/remove_model クロージャを method 化

train_network.py の train() 内にあった save_model / remove_model クロージャを
_save_model / _remove_model メソッドに昇格。設計方針(案 C):
- 不変な state: self._metadata / self._minimum_metadata に格上げ
- 呼び出し局所の値: args / accelerator / save_dtype / ckpt_name 等を kw-only 引数
  で受け取る(_run_validation_loop のシグネチャ流儀を踏襲)

これに伴い _build_metadata() は返り値を廃止し self._metadata / self._minimum_metadata
を直接設定する形に変更。train() 内に残存していた metadata["ss_epoch"] /
metadata["ss_training_finished_at"] のローカル参照も self._metadata[...] に置換。

検証: py_compile OK / AST 未解決名チェック clean / 全サブクラス
(sdxl/flux/sd3/lumina/anima/hunyuan_image) import OK / pytest 150 passed。
動作ロジックは同型変換のため不変。

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* refactor(phase4e): train_util shim 経由の内部参照を直 import に切替

リポジトリ内の train_util.* 属性アクセス約 500 箇所 (69 ファイル) を
canonical モジュール (dataset / caching / args / optimizer / model_io /
checkpoint_io / accelerator_setup / hidden_states / loss / sampling /
logging_util / device_utils 等) への直 import に変換。

- モジュール修飾は `import library.X as X`、ローカル変数と衝突する
  モジュールは loss_util / optimizer_util / args_util / dataset_util を使用
- クラス・定数は from-import (例: from library.dataset import DatasetGroup)
- config_util.py の相対 import (from .train_util import ...) も
  dataset / dreambooth_dataset / finetuning_dataset / controlnet_dataset へ分解
- strategy_anima / strategy_flux / strategy_hunyuan_image / strategy_sd3 に
  欠落していた accelerator_setup の import を追加 (HIGH_VRAM 参照の既存バグ修正)
- test_lumina_train_network.py の patch 対象を library.model_io へ更新
- leco_train_util.py の未使用 train_util import を削除

train_util.py の re-export shim は fork 互換のため引き続き維持。
内部からの参照は gen_img_diffusers.py の load_tokenizer (shim に存在しない
既存の壊れた参照) を除きゼロになった。

Co-Authored-By: Claude Fable 5 <[email protected]>

* doc: 01-overview.md をリファクタ後のモジュール構成に更新

train_util.py 分割後の 15 モジュールの所在マップと import 規約
(直 import / エイリアス / shim の位置付け) を AI 向け context に追記。

Co-Authored-By: Claude Fable 5 <[email protected]>

* fix: code-review 指摘のクラッシュ 3 件と import 重複を修正

- finetune/prepare_buckets_latents.py, make_captions_by_git.py:
  `from finetune.image_loading_dataset import ...` は finetune/ が
  パッケージでないため script 実行時に ModuleNotFoundError になる。
  既存の make_captions.py と同じ sys.path.append + 同階層 import に変更
- prepare_buckets_latents.py: モジュールエイリアス dataset がローカル変数
  `dataset = ImageLoadingDataset(...)` に遮蔽され UnboundLocalError に
  なっていた問題を修正 (二重 import を削除し dataset_util に統一)
- prepare_buckets_latents.py: is_disk_cached_latents_is_expected に
  欠けていた第 4 引数 alpha_mask=False を追加 (dev 由来の既存バグ、
  --skip_existing 指定時に TypeError)
- train_network.py: phase4e 変換で二重挿入された import ブロック
  (lines 42-49) と from-import 内の sai_model_spec 重複を削除

検証: 両スクリプトの --help 実行 OK、compileall OK、pytest 150 passed

Co-Authored-By: Claude Fable 5 <[email protected]>

* fix: code-review 指摘 5-7 (doc 残存・stale docstring・未使用 import) を解消

- docs/train_README-ja.md / zh.md: 廃止済み XTI:P+ (train_textual_inversion_XTI.py)
  への言及を削除し、廃止の注記を追加
- library/dataset.py: docstring の「specializations は train_util にあり
  PR-1d で移動予定」という stale な記述を、移動済みの 3 モジュール
  (dreambooth/finetuning/controlnet_dataset) を指す記述に更新
- gen_img.py / sdxl_gen_img.py / hunyuan_image_train_network.py:
  使用箇所ゼロの train_util import を削除 (実使用は sdxl_train_util のみ)。
  リポジトリ全体をスイープし他に未使用 train_util import が無いことを確認

検証: import スモーク OK、pytest 150 passed

Co-Authored-By: Claude Fable 5 <[email protected]>

* fix: code-review 指摘 8 (dataset 系 3 モジュールの未使用 import) を一掃

Co-Authored-By: Claude Fable 5 <[email protected]>

* fix: code-review 指摘 9 (model_io の diffusers/model_util/original_unet を遅延 import 化)

networks/ 配下の軽量 CLI が hashing/metadata ヘルパーのためだけに
model_io を import する際の起動時間を約 2.7 秒短縮。

Co-Authored-By: Claude Fable 5 <[email protected]>

* refactor: code-review 指摘 10 (caching<->dataset 双方向依存を utils への葉モジュール化で解消)

- IMAGE_TRANSFORMS / load_image / get_crop_ltrb / trim_and_resize_if_required
  を library/utils.py へ移動 (dataset.py / caching.py からは再 export で互換維持、
  BucketManager.get_crop_ltrb は委譲 staticmethod として存続)
- caching.py の _ds() 遅延アクセサを撤去し utils 直 import に
- strategy_base.py の関数内 `from library import caching` を top-level に昇格
- utils.py の未使用関数 swap_weight_devices / weighs_to_device を削除
  (custom_offloading_utils.py に使用中の別実装があり、こちらは孤立した古いコピー)

Co-Authored-By: Claude Fable 5 <[email protected]>

* docs: fine-tuning メタデータファイル仕様を新設し、既存 README から誘導

finetuning_dataset.py が読み込む契約 (caption/tags/image_size、json/jsonl
両形式、画像パス解決・キャッシュ関係) を docs/dataset_metadata.md に仕様化。
config_README-en/ja の metadata_file 説明からリンクし、train_README-ja/zh の
陳腐化した「メタデータファイルの作成」節を仕様への誘導に置き換え。

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

---------

Co-authored-by: Claude Opus 4.7 <[email protected]>
2026-06-11 21:30:09 +09:00

973 lines
44 KiB
Python

# training with captions
import argparse
import math
import os
from multiprocessing import Value
from typing import List
import toml
from tqdm import tqdm
import torch
from library.device_utils import init_ipex, clean_memory_on_device
init_ipex()
from accelerate.utils import set_seed
from diffusers import DDPMScheduler
from library import deepspeed_utils, sdxl_model_util, strategy_base, strategy_sd, strategy_sdxl, sai_model_spec
import library.accelerator_setup as accelerator_setup
import library.args as args_util
import library.dataset as dataset_util
import library.model_io as model_io
import library.optimizer as optimizer_util
import library.logging_util as logging_util
import library.loss as loss_util
import library.checkpoint_io as checkpoint_io
from library.utils import setup_logging, add_logging_arguments
setup_logging()
import logging
logger = logging.getLogger(__name__)
import library.config_util as config_util
import library.sdxl_train_util as sdxl_train_util
from library.config_util import (
ConfigSanitizer,
BlueprintGenerator,
)
import library.custom_train_functions as custom_train_functions
from library.custom_train_functions import (
apply_snr_weight,
prepare_scheduler_for_custom_training,
scale_v_prediction_loss_like_noise_prediction,
add_v_prediction_like_loss,
apply_debiased_estimation,
apply_masked_loss,
)
from library.sdxl_original_unet import SdxlUNet2DConditionModel
UNET_NUM_BLOCKS_FOR_BLOCK_LR = 23
def get_block_params_to_optimize(unet: SdxlUNet2DConditionModel, block_lrs: List[float]) -> List[dict]:
block_params = [[] for _ in range(len(block_lrs))]
for i, (name, param) in enumerate(unet.named_parameters()):
if name.startswith("time_embed.") or name.startswith("label_emb."):
block_index = 0 # 0
elif name.startswith("input_blocks."): # 1-9
block_index = 1 + int(name.split(".")[1])
elif name.startswith("middle_block."): # 10-12
block_index = 10 + int(name.split(".")[1])
elif name.startswith("output_blocks."): # 13-21
block_index = 13 + int(name.split(".")[1])
elif name.startswith("out."): # 22
block_index = 22
else:
raise ValueError(f"unexpected parameter name: {name}")
block_params[block_index].append(param)
params_to_optimize = []
for i, params in enumerate(block_params):
if block_lrs[i] == 0: # 0のときは学習しない do not optimize when lr is 0
continue
params_to_optimize.append({"params": params, "lr": block_lrs[i]})
return params_to_optimize
def append_block_lr_to_logs(block_lrs, logs, lr_scheduler, optimizer_type):
names = []
block_index = 0
while block_index < UNET_NUM_BLOCKS_FOR_BLOCK_LR + 2:
if block_index < UNET_NUM_BLOCKS_FOR_BLOCK_LR:
if block_lrs[block_index] == 0:
block_index += 1
continue
names.append(f"block{block_index}")
elif block_index == UNET_NUM_BLOCKS_FOR_BLOCK_LR:
names.append("text_encoder1")
elif block_index == UNET_NUM_BLOCKS_FOR_BLOCK_LR + 1:
names.append("text_encoder2")
block_index += 1
optimizer_util.append_lr_to_logs_with_names(logs, lr_scheduler, optimizer_type, names)
def train(args):
args_util.verify_training_args(args)
accelerator_setup.prepare_dataset_args(args, True)
sdxl_train_util.verify_sdxl_training_args(args)
deepspeed_utils.prepare_deepspeed_args(args)
setup_logging(args, reset=True)
assert (
not args.weighted_captions or not args.cache_text_encoder_outputs
), "weighted_captions is not supported when caching text encoder outputs / cache_text_encoder_outputsを使うときはweighted_captionsはサポートされていません"
assert (
not args.train_text_encoder or not args.cache_text_encoder_outputs
), "cache_text_encoder_outputs is not supported when training text encoder / text encoderを学習するときはcache_text_encoder_outputsはサポートされていません"
if args.block_lr:
block_lrs = [float(lr) for lr in args.block_lr.split(",")]
assert (
len(block_lrs) == UNET_NUM_BLOCKS_FOR_BLOCK_LR
), f"block_lr must have {UNET_NUM_BLOCKS_FOR_BLOCK_LR} values / block_lrは{UNET_NUM_BLOCKS_FOR_BLOCK_LR}個の値を指定してください"
else:
block_lrs = None
cache_latents = args.cache_latents
use_dreambooth_method = args.in_json is None
if args.seed is not None:
set_seed(args.seed) # 乱数系列を初期化する
tokenize_strategy = strategy_sdxl.SdxlTokenizeStrategy(args.max_token_length, args.tokenizer_cache_dir)
strategy_base.TokenizeStrategy.set_strategy(tokenize_strategy)
tokenizers = [tokenize_strategy.tokenizer1, tokenize_strategy.tokenizer2] # will be removed in the future
# prepare caching strategy: this must be set before preparing dataset. because dataset may use this strategy for initialization.
if args.cache_latents:
latents_caching_strategy = strategy_sd.SdSdxlLatentsCachingStrategy(
False, args.cache_latents_to_disk, args.vae_batch_size, args.skip_cache_check
)
strategy_base.LatentsCachingStrategy.set_strategy(latents_caching_strategy)
# データセットを準備する
if args.dataset_class is None:
blueprint_generator = BlueprintGenerator(ConfigSanitizer(True, True, args.masked_loss, True))
if args.dataset_config is not None:
logger.info(f"Load dataset config from {args.dataset_config}")
user_config = config_util.load_user_config(args.dataset_config)
ignored = ["train_data_dir", "in_json"]
if any(getattr(args, attr) is not None for attr in ignored):
logger.warning(
"ignore following options because config file is found: {0} / 設定ファイルが利用されるため以下のオプションは無視されます: {0}".format(
", ".join(ignored)
)
)
else:
if use_dreambooth_method:
logger.info("Using DreamBooth method.")
user_config = {
"datasets": [
{
"subsets": config_util.generate_dreambooth_subsets_config_by_subdirs(
args.train_data_dir, args.reg_data_dir
)
}
]
}
else:
logger.info("Training with captions.")
user_config = {
"datasets": [
{
"subsets": [
{
"image_dir": args.train_data_dir,
"metadata_file": args.in_json,
}
]
}
]
}
blueprint = blueprint_generator.generate(user_config, args)
train_dataset_group, val_dataset_group = config_util.generate_dataset_group_by_blueprint(blueprint.dataset_group)
else:
train_dataset_group = dataset_util.load_arbitrary_dataset(args)
val_dataset_group = None
current_epoch = Value("i", 0)
current_step = Value("i", 0)
ds_for_collator = train_dataset_group if args.max_data_loader_n_workers == 0 else None
collator = dataset_util.collator_class(current_epoch, current_step, ds_for_collator)
train_dataset_group.verify_bucket_reso_steps(32)
if args.debug_dataset:
dataset_util.debug_dataset(train_dataset_group, True)
return
if len(train_dataset_group) == 0:
logger.error(
"No data found. Please verify the metadata file and train_data_dir option. / 画像がありません。メタデータおよびtrain_data_dirオプションを確認してください。"
)
return
if cache_latents:
assert (
train_dataset_group.is_latent_cacheable()
), "when caching latents, either color_aug or random_crop cannot be used / latentをキャッシュするときはcolor_augとrandom_cropは使えません"
if args.cache_text_encoder_outputs:
assert (
train_dataset_group.is_text_encoder_output_cacheable()
), "when caching text encoder output, either caption_dropout_rate, shuffle_caption, token_warmup_step or caption_tag_dropout_rate cannot be used / text encoderの出力をキャッシュするときはcaption_dropout_rate, shuffle_caption, token_warmup_step, caption_tag_dropout_rateは使えません"
# acceleratorを準備する
logger.info("prepare accelerator")
accelerator = accelerator_setup.prepare_accelerator(args)
# mixed precisionに対応した型を用意しておき適宜castする
weight_dtype, save_dtype = accelerator_setup.prepare_dtype(args)
vae_dtype = torch.float32 if args.no_half_vae else weight_dtype
# モデルを読み込む
(
load_stable_diffusion_format,
text_encoder1,
text_encoder2,
vae,
unet,
logit_scale,
ckpt_info,
) = sdxl_train_util.load_target_model(args, accelerator, "sdxl", weight_dtype)
# logit_scale = logit_scale.to(accelerator.device, dtype=weight_dtype)
# verify load/save model formats
if load_stable_diffusion_format:
src_stable_diffusion_ckpt = args.pretrained_model_name_or_path
src_diffusers_model_path = None
else:
src_stable_diffusion_ckpt = None
src_diffusers_model_path = args.pretrained_model_name_or_path
if args.save_model_as is None:
save_stable_diffusion_format = load_stable_diffusion_format
use_safetensors = args.use_safetensors
else:
save_stable_diffusion_format = args.save_model_as.lower() == "ckpt" or args.save_model_as.lower() == "safetensors"
use_safetensors = args.use_safetensors or ("safetensors" in args.save_model_as.lower())
# assert save_stable_diffusion_format, "save_model_as must be ckpt or safetensors / save_model_asはckptかsafetensorsである必要があります"
# Diffusers版のxformers使用フラグを設定する関数
def set_diffusers_xformers_flag(model, valid):
def fn_recursive_set_mem_eff(module: torch.nn.Module):
if hasattr(module, "set_use_memory_efficient_attention_xformers"):
module.set_use_memory_efficient_attention_xformers(valid)
for child in module.children():
fn_recursive_set_mem_eff(child)
fn_recursive_set_mem_eff(model)
# モデルに xformers とか memory efficient attention を組み込む
if args.diffusers_xformers:
# もうU-Netを独自にしたので動かないけどVAEのxformersは動くはず
accelerator.print("Use xformers by Diffusers")
# set_diffusers_xformers_flag(unet, True)
set_diffusers_xformers_flag(vae, True)
else:
# Windows版のxformersはfloatで学習できなかったりするのでxformersを使わない設定も可能にしておく必要がある
accelerator.print("Disable Diffusers' xformers")
model_io.replace_unet_modules(unet, args.mem_eff_attn, args.xformers, args.sdpa)
if torch.__version__ >= "2.0.0": # PyTorch 2.0.0 以上対応のxformersなら以下が使える
vae.set_use_memory_efficient_attention_xformers(args.xformers)
# 学習を準備する
if cache_latents:
vae.to(accelerator.device, dtype=vae_dtype)
vae.requires_grad_(False)
vae.eval()
train_dataset_group.new_cache_latents(vae, accelerator)
vae.to("cpu")
clean_memory_on_device(accelerator.device)
accelerator.wait_for_everyone()
# 学習を準備する:モデルを適切な状態にする
if args.gradient_checkpointing:
unet.enable_gradient_checkpointing()
train_unet = args.learning_rate != 0
train_text_encoder1 = False
train_text_encoder2 = False
text_encoding_strategy = strategy_sdxl.SdxlTextEncodingStrategy()
strategy_base.TextEncodingStrategy.set_strategy(text_encoding_strategy)
if args.train_text_encoder:
# TODO each option for two text encoders?
accelerator.print("enable text encoder training")
if args.gradient_checkpointing:
text_encoder1.gradient_checkpointing_enable()
text_encoder2.gradient_checkpointing_enable()
lr_te1 = args.learning_rate_te1 if args.learning_rate_te1 is not None else args.learning_rate # 0 means not train
lr_te2 = args.learning_rate_te2 if args.learning_rate_te2 is not None else args.learning_rate # 0 means not train
train_text_encoder1 = lr_te1 != 0
train_text_encoder2 = lr_te2 != 0
# caching one text encoder output is not supported
if not train_text_encoder1:
text_encoder1.to(weight_dtype)
if not train_text_encoder2:
text_encoder2.to(weight_dtype)
text_encoder1.requires_grad_(train_text_encoder1)
text_encoder2.requires_grad_(train_text_encoder2)
text_encoder1.train(train_text_encoder1)
text_encoder2.train(train_text_encoder2)
else:
text_encoder1.to(weight_dtype)
text_encoder2.to(weight_dtype)
text_encoder1.requires_grad_(False)
text_encoder2.requires_grad_(False)
text_encoder1.eval()
text_encoder2.eval()
# TextEncoderの出力をキャッシュする
if args.cache_text_encoder_outputs:
# Text Encodes are eval and no grad
text_encoder_output_caching_strategy = strategy_sdxl.SdxlTextEncoderOutputsCachingStrategy(
args.cache_text_encoder_outputs_to_disk, None, False, is_weighted=args.weighted_captions
)
strategy_base.TextEncoderOutputsCachingStrategy.set_strategy(text_encoder_output_caching_strategy)
text_encoder1.to(accelerator.device)
text_encoder2.to(accelerator.device)
with accelerator.autocast():
train_dataset_group.new_cache_text_encoder_outputs([text_encoder1, text_encoder2], accelerator)
accelerator.wait_for_everyone()
if not cache_latents:
vae.requires_grad_(False)
vae.eval()
vae.to(accelerator.device, dtype=vae_dtype)
unet.requires_grad_(train_unet)
if not train_unet:
unet.to(accelerator.device, dtype=weight_dtype) # because of unet is not prepared
training_models = []
params_to_optimize = []
if train_unet:
training_models.append(unet)
if block_lrs is None:
params_to_optimize.append({"params": list(unet.parameters()), "lr": args.learning_rate})
else:
params_to_optimize.extend(get_block_params_to_optimize(unet, block_lrs))
if train_text_encoder1:
training_models.append(text_encoder1)
params_to_optimize.append({"params": list(text_encoder1.parameters()), "lr": args.learning_rate_te1 or args.learning_rate})
if train_text_encoder2:
training_models.append(text_encoder2)
params_to_optimize.append({"params": list(text_encoder2.parameters()), "lr": args.learning_rate_te2 or args.learning_rate})
# calculate number of trainable parameters
n_params = 0
for group in params_to_optimize:
for p in group["params"]:
n_params += p.numel()
accelerator.print(f"train unet: {train_unet}, text_encoder1: {train_text_encoder1}, text_encoder2: {train_text_encoder2}")
accelerator.print(f"number of models: {len(training_models)}")
accelerator.print(f"number of trainable parameters: {n_params}")
# 学習に必要なクラスを準備する
accelerator.print("prepare optimizer, data loader etc.")
if args.fused_optimizer_groups:
# fused backward pass: https://pytorch.org/tutorials/intermediate/optimizer_step_in_backward_tutorial.html
# Instead of creating an optimizer for all parameters as in the tutorial, we create an optimizer for each group of parameters.
# This balances memory usage and management complexity.
# calculate total number of parameters
n_total_params = sum(len(params["params"]) for params in params_to_optimize)
params_per_group = math.ceil(n_total_params / args.fused_optimizer_groups)
# split params into groups, keeping the learning rate the same for all params in a group
# this will increase the number of groups if the learning rate is different for different params (e.g. U-Net and text encoders)
grouped_params = []
param_group = []
param_group_lr = -1
for group in params_to_optimize:
lr = group["lr"]
for p in group["params"]:
# if the learning rate is different for different params, start a new group
if lr != param_group_lr:
if param_group:
grouped_params.append({"params": param_group, "lr": param_group_lr})
param_group = []
param_group_lr = lr
param_group.append(p)
# if the group has enough parameters, start a new group
if len(param_group) == params_per_group:
grouped_params.append({"params": param_group, "lr": param_group_lr})
param_group = []
param_group_lr = -1
if param_group:
grouped_params.append({"params": param_group, "lr": param_group_lr})
# prepare optimizers for each group
optimizers = []
for group in grouped_params:
_, _, optimizer = optimizer_util.get_optimizer(args, trainable_params=[group])
optimizers.append(optimizer)
optimizer = optimizers[0] # avoid error in the following code
logger.info(f"using {len(optimizers)} optimizers for fused optimizer groups")
else:
_, _, optimizer = optimizer_util.get_optimizer(args, trainable_params=params_to_optimize)
# prepare dataloader
# strategies are set here because they cannot be referenced in another process. Copy them with the dataset
# some strategies can be None
train_dataset_group.set_current_strategies()
# DataLoaderのプロセス数:0 は persistent_workers が使えないので注意
n_workers = min(args.max_data_loader_n_workers, os.cpu_count()) # cpu_count or max_data_loader_n_workers
train_dataloader = torch.utils.data.DataLoader(
train_dataset_group,
batch_size=1,
shuffle=True,
collate_fn=collator,
num_workers=n_workers,
persistent_workers=args.persistent_data_loader_workers,
)
# 学習ステップ数を計算する
if args.max_train_epochs is not None:
args.max_train_steps = args.max_train_epochs * math.ceil(
len(train_dataloader) / accelerator.num_processes / args.gradient_accumulation_steps
)
accelerator.print(
f"override steps. steps for {args.max_train_epochs} epochs is / 指定エポックまでのステップ数: {args.max_train_steps}"
)
# データセット側にも学習ステップを送信
train_dataset_group.set_max_train_steps(args.max_train_steps)
# lr schedulerを用意する
if args.fused_optimizer_groups:
# prepare lr schedulers for each optimizer
lr_schedulers = [optimizer_util.get_scheduler_fix(args, optimizer, accelerator.num_processes) for optimizer in optimizers]
lr_scheduler = lr_schedulers[0] # avoid error in the following code
else:
lr_scheduler = optimizer_util.get_scheduler_fix(args, optimizer, accelerator.num_processes)
# 実験的機能:勾配も含めたfp16/bf16学習を行う モデル全体をfp16/bf16にする
if args.full_fp16:
assert (
args.mixed_precision == "fp16"
), "full_fp16 requires mixed precision='fp16' / full_fp16を使う場合はmixed_precision='fp16'を指定してください。"
accelerator.print("enable full fp16 training.")
unet.to(weight_dtype)
text_encoder1.to(weight_dtype)
text_encoder2.to(weight_dtype)
elif args.full_bf16:
assert (
args.mixed_precision == "bf16"
), "full_bf16 requires mixed precision='bf16' / full_bf16を使う場合はmixed_precision='bf16'を指定してください。"
accelerator.print("enable full bf16 training.")
unet.to(weight_dtype)
text_encoder1.to(weight_dtype)
text_encoder2.to(weight_dtype)
# freeze last layer and final_layer_norm in te1 since we use the output of the penultimate layer
if train_text_encoder1:
text_encoder1.text_model.encoder.layers[-1].requires_grad_(False)
text_encoder1.text_model.final_layer_norm.requires_grad_(False)
if args.deepspeed:
ds_model = deepspeed_utils.prepare_deepspeed_model(
args,
unet=unet if train_unet else None,
text_encoder1=text_encoder1 if train_text_encoder1 else None,
text_encoder2=text_encoder2 if train_text_encoder2 else None,
)
# most of ZeRO stage uses optimizer partitioning, so we have to prepare optimizer and ds_model at the same time. # pull/1139#issuecomment-1986790007
ds_model, optimizer, train_dataloader, lr_scheduler = accelerator.prepare(
ds_model, optimizer, train_dataloader, lr_scheduler
)
training_models = [ds_model]
else:
# acceleratorがなんかよろしくやってくれるらしい
if train_unet:
unet = accelerator.prepare(unet)
if train_text_encoder1:
text_encoder1 = accelerator.prepare(text_encoder1)
if train_text_encoder2:
text_encoder2 = accelerator.prepare(text_encoder2)
optimizer, train_dataloader, lr_scheduler = accelerator.prepare(optimizer, train_dataloader, lr_scheduler)
# TextEncoderの出力をキャッシュするときにはCPUへ移動する
if args.cache_text_encoder_outputs:
# move Text Encoders for sampling images. Text Encoder doesn't work on CPU with fp16
text_encoder1.to("cpu", dtype=torch.float32)
text_encoder2.to("cpu", dtype=torch.float32)
clean_memory_on_device(accelerator.device)
else:
# make sure Text Encoders are on GPU
text_encoder1.to(accelerator.device)
text_encoder2.to(accelerator.device)
# 実験的機能:勾配も含めたfp16学習を行う PyTorchにパッチを当ててfp16でのgrad scaleを有効にする
if args.full_fp16:
# During deepseed training, accelerate not handles fp16/bf16|mixed precision directly via scaler. Let deepspeed engine do.
# -> But we think it's ok to patch accelerator even if deepspeed is enabled.
accelerator_setup.patch_accelerator_for_fp16_training(accelerator)
# resumeする
args_util.resume_from_local_or_hf_if_specified(accelerator, args)
if args.fused_backward_pass:
# use fused optimizer for backward pass: other optimizers will be supported in the future
import library.adafactor_fused
library.adafactor_fused.patch_adafactor_fused(optimizer)
for param_group in optimizer.param_groups:
for parameter in param_group["params"]:
if parameter.requires_grad:
def __grad_hook(tensor: torch.Tensor, param_group=param_group):
if accelerator.sync_gradients and args.max_grad_norm != 0.0:
accelerator.clip_grad_norm_(tensor, args.max_grad_norm)
optimizer.step_param(tensor, param_group)
tensor.grad = None
parameter.register_post_accumulate_grad_hook(__grad_hook)
elif args.fused_optimizer_groups:
# prepare for additional optimizers and lr schedulers
for i in range(1, len(optimizers)):
optimizers[i] = accelerator.prepare(optimizers[i])
lr_schedulers[i] = accelerator.prepare(lr_schedulers[i])
# counters are used to determine when to step the optimizer
global optimizer_hooked_count
global num_parameters_per_group
global parameter_optimizer_map
optimizer_hooked_count = {}
num_parameters_per_group = [0] * len(optimizers)
parameter_optimizer_map = {}
for opt_idx, optimizer in enumerate(optimizers):
for param_group in optimizer.param_groups:
for parameter in param_group["params"]:
if parameter.requires_grad:
def optimizer_hook(parameter: torch.Tensor):
if accelerator.sync_gradients and args.max_grad_norm != 0.0:
accelerator.clip_grad_norm_(parameter, args.max_grad_norm)
i = parameter_optimizer_map[parameter]
optimizer_hooked_count[i] += 1
if optimizer_hooked_count[i] == num_parameters_per_group[i]:
optimizers[i].step()
optimizers[i].zero_grad(set_to_none=True)
parameter.register_post_accumulate_grad_hook(optimizer_hook)
parameter_optimizer_map[parameter] = opt_idx
num_parameters_per_group[opt_idx] += 1
# epoch数を計算する
num_update_steps_per_epoch = math.ceil(len(train_dataloader) / args.gradient_accumulation_steps)
num_train_epochs = math.ceil(args.max_train_steps / num_update_steps_per_epoch)
if (args.save_n_epoch_ratio is not None) and (args.save_n_epoch_ratio > 0):
args.save_every_n_epochs = math.floor(num_train_epochs / args.save_n_epoch_ratio) or 1
# 学習する
# total_batch_size = args.train_batch_size * accelerator.num_processes * args.gradient_accumulation_steps
accelerator.print("running training / 学習開始")
accelerator.print(f" num examples / サンプル数: {train_dataset_group.num_train_images}")
accelerator.print(f" num batches per epoch / 1epochのバッチ数: {len(train_dataloader)}")
accelerator.print(f" num epochs / epoch数: {num_train_epochs}")
accelerator.print(
f" batch size per device / バッチサイズ: {', '.join([str(d.batch_size) for d in train_dataset_group.datasets])}"
)
# accelerator.print(
# f" total train batch size (with parallel & distributed & accumulation) / 総バッチサイズ(並列学習、勾配合計含む): {total_batch_size}"
# )
accelerator.print(f" gradient accumulation steps / 勾配を合計するステップ数 = {args.gradient_accumulation_steps}")
accelerator.print(f" total optimization steps / 学習ステップ数: {args.max_train_steps}")
progress_bar = tqdm(range(args.max_train_steps), smoothing=0, disable=not accelerator.is_local_main_process, desc="steps")
global_step = 0
noise_scheduler = DDPMScheduler(
beta_start=0.00085, beta_end=0.012, beta_schedule="scaled_linear", num_train_timesteps=1000, clip_sample=False
)
prepare_scheduler_for_custom_training(noise_scheduler, accelerator.device)
if args.zero_terminal_snr:
custom_train_functions.fix_noise_scheduler_betas_for_zero_terminal_snr(noise_scheduler)
if accelerator.is_main_process:
init_kwargs = {}
if args.wandb_run_name:
init_kwargs["wandb"] = {"name": args.wandb_run_name}
if args.log_tracker_config is not None:
init_kwargs = toml.load(args.log_tracker_config)
accelerator.init_trackers(
"finetuning" if args.log_tracker_name is None else args.log_tracker_name,
config=args_util.get_sanitized_config_or_none(args),
init_kwargs=init_kwargs,
)
# For --sample_at_first
sdxl_train_util.sample_images(
accelerator, args, 0, global_step, accelerator.device, vae, tokenizers, [text_encoder1, text_encoder2], unet
)
if len(accelerator.trackers) > 0:
# log empty object to commit the sample images to wandb
accelerator.log({}, step=0)
loss_recorder = logging_util.LossRecorder()
for epoch in range(num_train_epochs):
accelerator.print(f"\nepoch {epoch+1}/{num_train_epochs}")
current_epoch.value = epoch + 1
for m in training_models:
m.train()
for step, batch in enumerate(train_dataloader):
current_step.value = global_step
if args.fused_optimizer_groups:
optimizer_hooked_count = {i: 0 for i in range(len(optimizers))} # reset counter for each step
with accelerator.accumulate(*training_models):
if "latents" in batch and batch["latents"] is not None:
latents = batch["latents"].to(accelerator.device).to(dtype=weight_dtype)
else:
with torch.no_grad():
# latentに変換
latents = vae.encode(batch["images"].to(vae_dtype)).latent_dist.sample().to(weight_dtype)
# NaNが含まれていれば警告を表示し0に置き換える
if torch.any(torch.isnan(latents)):
accelerator.print("NaN found in latents, replacing with zeros")
latents = torch.nan_to_num(latents, 0, out=latents)
latents = latents * sdxl_model_util.VAE_SCALE_FACTOR
text_encoder_outputs_list = batch.get("text_encoder_outputs_list", None)
if text_encoder_outputs_list is not None:
# Text Encoder outputs are cached
encoder_hidden_states1, encoder_hidden_states2, pool2 = text_encoder_outputs_list
encoder_hidden_states1 = encoder_hidden_states1.to(accelerator.device, dtype=weight_dtype)
encoder_hidden_states2 = encoder_hidden_states2.to(accelerator.device, dtype=weight_dtype)
pool2 = pool2.to(accelerator.device, dtype=weight_dtype)
else:
input_ids1, input_ids2 = batch["input_ids_list"]
with torch.set_grad_enabled(args.train_text_encoder):
# Get the text embedding for conditioning
if args.weighted_captions:
input_ids_list, weights_list = tokenize_strategy.tokenize_with_weights(batch["captions"])
encoder_hidden_states1, encoder_hidden_states2, pool2 = (
text_encoding_strategy.encode_tokens_with_weights(
tokenize_strategy,
[text_encoder1, text_encoder2, accelerator.unwrap_model(text_encoder2)],
input_ids_list,
weights_list,
)
)
else:
input_ids1 = input_ids1.to(accelerator.device)
input_ids2 = input_ids2.to(accelerator.device)
encoder_hidden_states1, encoder_hidden_states2, pool2 = text_encoding_strategy.encode_tokens(
tokenize_strategy,
[text_encoder1, text_encoder2, accelerator.unwrap_model(text_encoder2)],
[input_ids1, input_ids2],
)
if args.full_fp16:
encoder_hidden_states1 = encoder_hidden_states1.to(weight_dtype)
encoder_hidden_states2 = encoder_hidden_states2.to(weight_dtype)
pool2 = pool2.to(weight_dtype)
# get size embeddings
orig_size = batch["original_sizes_hw"]
crop_size = batch["crop_top_lefts"]
target_size = batch["target_sizes_hw"]
embs = sdxl_train_util.get_size_embeddings(orig_size, crop_size, target_size, accelerator.device).to(weight_dtype)
# concat embeddings
vector_embedding = torch.cat([pool2, embs], dim=1).to(weight_dtype)
text_embedding = torch.cat([encoder_hidden_states1, encoder_hidden_states2], dim=2).to(weight_dtype)
# Sample noise, sample a random timestep for each image, and add noise to the latents,
# with noise offset and/or multires noise if specified
noise, noisy_latents, timesteps = loss_util.get_noise_noisy_latents_and_timesteps(args, noise_scheduler, latents)
noisy_latents = noisy_latents.to(weight_dtype) # TODO check why noisy_latents is not weight_dtype
if batch["masks"] is not None:
with torch.no_grad():
masked_latents = vae.encode(
batch["masked_images"].to(vae_dtype)
).latent_dist.sample().to(weight_dtype)
masked_latents = masked_latents * sdxl_model_util.VAE_SCALE_FACTOR
# Resize the mask to latents shape as we concatenate the mask to the latents
mask = torch.nn.functional.interpolate(
batch["masks"].to(weight_dtype), size=latents.shape[2:]
)
noisy_latents = torch.cat([noisy_latents, mask, masked_latents], dim=1)
# Predict the noise residual
with accelerator.autocast():
noise_pred = unet(noisy_latents, timesteps, text_embedding, vector_embedding)
if args.v_parameterization:
# v-parameterization training
target = noise_scheduler.get_velocity(latents, noise, timesteps)
else:
target = noise
huber_c = loss_util.get_huber_threshold_if_needed(args, timesteps, noise_scheduler)
if (
args.min_snr_gamma
or args.scale_v_pred_loss_like_noise_pred
or args.v_pred_like_loss
or args.debiased_estimation_loss
or args.masked_loss
):
# do not mean over batch dimension for snr weight or scale v-pred loss
loss = loss_util.conditional_loss(noise_pred.float(), target.float(), args.loss_type, "none", huber_c)
if args.masked_loss or ("alpha_masks" in batch and batch["alpha_masks"] is not None):
loss = apply_masked_loss(loss, batch)
loss = loss.mean([1, 2, 3])
if args.min_snr_gamma:
loss = apply_snr_weight(loss, timesteps, noise_scheduler, args.min_snr_gamma, args.v_parameterization)
if args.scale_v_pred_loss_like_noise_pred:
loss = scale_v_prediction_loss_like_noise_prediction(loss, timesteps, noise_scheduler)
if args.v_pred_like_loss:
loss = add_v_prediction_like_loss(loss, timesteps, noise_scheduler, args.v_pred_like_loss)
if args.debiased_estimation_loss:
loss = apply_debiased_estimation(loss, timesteps, noise_scheduler, args.v_parameterization)
loss = loss.mean() # mean over batch dimension
else:
loss = loss_util.conditional_loss(noise_pred.float(), target.float(), args.loss_type, "mean", huber_c)
accelerator.backward(loss)
if not (args.fused_backward_pass or args.fused_optimizer_groups):
if accelerator.sync_gradients and args.max_grad_norm != 0.0:
params_to_clip = []
for m in training_models:
params_to_clip.extend(m.parameters())
accelerator.clip_grad_norm_(params_to_clip, args.max_grad_norm)
optimizer.step()
lr_scheduler.step()
optimizer.zero_grad(set_to_none=True)
else:
# optimizer.step() and optimizer.zero_grad() are called in the optimizer hook
lr_scheduler.step()
if args.fused_optimizer_groups:
for i in range(1, len(optimizers)):
lr_schedulers[i].step()
# Checks if the accelerator has performed an optimization step behind the scenes
if accelerator.sync_gradients:
progress_bar.update(1)
global_step += 1
sdxl_train_util.sample_images(
accelerator,
args,
None,
global_step,
accelerator.device,
vae,
tokenizers,
[text_encoder1, text_encoder2],
unet,
)
# 指定ステップごとにモデルを保存
if args.save_every_n_steps is not None and global_step % args.save_every_n_steps == 0:
accelerator.wait_for_everyone()
if accelerator.is_main_process:
src_path = src_stable_diffusion_ckpt if save_stable_diffusion_format else src_diffusers_model_path
sdxl_train_util.save_sd_model_on_epoch_end_or_stepwise(
args,
False,
accelerator,
src_path,
save_stable_diffusion_format,
use_safetensors,
save_dtype,
epoch,
num_train_epochs,
global_step,
accelerator.unwrap_model(text_encoder1),
accelerator.unwrap_model(text_encoder2),
accelerator.unwrap_model(unet),
vae,
logit_scale,
ckpt_info,
)
current_loss = loss.detach().item() # 平均なのでbatch sizeは関係ないはず
if len(accelerator.trackers) > 0:
logs = {"loss": current_loss}
if block_lrs is None:
optimizer_util.append_lr_to_logs(logs, lr_scheduler, args.optimizer_type, including_unet=train_unet)
else:
append_block_lr_to_logs(block_lrs, logs, lr_scheduler, args.optimizer_type) # U-Net is included in block_lrs
accelerator.log(logs, step=global_step)
loss_recorder.add(epoch=epoch, step=step, loss=current_loss)
avr_loss: float = loss_recorder.moving_average
logs = {"avr_loss": avr_loss} # , "lr": lr_scheduler.get_last_lr()[0]}
progress_bar.set_postfix(**logs)
if global_step >= args.max_train_steps:
break
if len(accelerator.trackers) > 0:
logs = {"loss/epoch": loss_recorder.moving_average}
accelerator.log(logs, step=epoch + 1)
accelerator.wait_for_everyone()
if args.save_every_n_epochs is not None:
if accelerator.is_main_process:
src_path = src_stable_diffusion_ckpt if save_stable_diffusion_format else src_diffusers_model_path
sdxl_train_util.save_sd_model_on_epoch_end_or_stepwise(
args,
True,
accelerator,
src_path,
save_stable_diffusion_format,
use_safetensors,
save_dtype,
epoch,
num_train_epochs,
global_step,
accelerator.unwrap_model(text_encoder1),
accelerator.unwrap_model(text_encoder2),
accelerator.unwrap_model(unet),
vae,
logit_scale,
ckpt_info,
)
sdxl_train_util.sample_images(
accelerator,
args,
epoch + 1,
global_step,
accelerator.device,
vae,
tokenizers,
[text_encoder1, text_encoder2],
unet,
)
is_main_process = accelerator.is_main_process
# if is_main_process:
unet = accelerator.unwrap_model(unet)
text_encoder1 = accelerator.unwrap_model(text_encoder1)
text_encoder2 = accelerator.unwrap_model(text_encoder2)
accelerator.end_training()
if args.save_state or args.save_state_on_train_end:
checkpoint_io.save_state_on_train_end(args, accelerator)
del accelerator # この後メモリを使うのでこれは消す
if is_main_process:
src_path = src_stable_diffusion_ckpt if save_stable_diffusion_format else src_diffusers_model_path
sdxl_train_util.save_sd_model_on_train_end(
args,
src_path,
save_stable_diffusion_format,
use_safetensors,
save_dtype,
epoch,
global_step,
text_encoder1,
text_encoder2,
unet,
vae,
logit_scale,
ckpt_info,
)
logger.info("model saved.")
def setup_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser()
add_logging_arguments(parser)
args_util.add_sd_models_arguments(parser)
sai_model_spec.add_model_spec_arguments(parser)
args_util.add_dataset_arguments(parser, True, True, True)
args_util.add_training_arguments(parser, False)
args_util.add_masked_loss_arguments(parser)
deepspeed_utils.add_deepspeed_arguments(parser)
args_util.add_sd_saving_arguments(parser)
args_util.add_optimizer_arguments(parser)
config_util.add_config_arguments(parser)
custom_train_functions.add_custom_train_arguments(parser)
sdxl_train_util.add_sdxl_training_arguments(parser)
parser.add_argument(
"--learning_rate_te1",
type=float,
default=None,
help="learning rate for text encoder 1 (ViT-L) / text encoder 1 (ViT-L)の学習率",
)
parser.add_argument(
"--learning_rate_te2",
type=float,
default=None,
help="learning rate for text encoder 2 (BiG-G) / text encoder 2 (BiG-G)の学習率",
)
parser.add_argument(
"--diffusers_xformers", action="store_true", help="use xformers by diffusers / Diffusersでxformersを使用する"
)
parser.add_argument("--train_text_encoder", action="store_true", help="train text encoder / text encoderも学習する")
parser.add_argument(
"--no_half_vae",
action="store_true",
help="do not use fp16/bf16 VAE in mixed precision (use float VAE) / mixed precisionでも fp16/bf16 VAEを使わずfloat VAEを使う",
)
parser.add_argument(
"--block_lr",
type=str,
default=None,
help=f"learning rates for each block of U-Net, comma-separated, {UNET_NUM_BLOCKS_FOR_BLOCK_LR} values / "
+ f"U-Netの各ブロックの学習率、カンマ区切り、{UNET_NUM_BLOCKS_FOR_BLOCK_LR}個の値",
)
parser.add_argument(
"--fused_optimizer_groups",
type=int,
default=None,
help="number of optimizers for fused backward pass and optimizer step / fused backward passとoptimizer stepのためのoptimizer数",
)
return parser
if __name__ == "__main__":
parser = setup_parser()
args = parser.parse_args()
args_util.verify_command_line_training_args(args)
args = args_util.read_config_from_file(args, parser)
train(args)