Files
sd-scripts/train_textual_inversion.py
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

856 lines
40 KiB
Python

import argparse
import math
import os
from multiprocessing import Value
from typing import Any, List, Optional, Union
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 transformers import CLIPTokenizer
from library import deepspeed_utils, model_util, strategy_base, strategy_sd, 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
from library.dataset import DatasetGroup, MinimalDataset
import library.loss as loss_util
import library.checkpoint_io as checkpoint_io
import library.sampling as sampling
import library.huggingface_util as huggingface_util
import library.config_util as config_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.utils import setup_logging, add_logging_arguments
setup_logging()
import logging
logger = logging.getLogger(__name__)
imagenet_templates_small = [
"a photo of a {}",
"a rendering of a {}",
"a cropped photo of the {}",
"the photo of a {}",
"a photo of a clean {}",
"a photo of a dirty {}",
"a dark photo of the {}",
"a photo of my {}",
"a photo of the cool {}",
"a close-up photo of a {}",
"a bright photo of the {}",
"a cropped photo of a {}",
"a photo of the {}",
"a good photo of the {}",
"a photo of one {}",
"a close-up photo of the {}",
"a rendition of the {}",
"a photo of the clean {}",
"a rendition of a {}",
"a photo of a nice {}",
"a good photo of a {}",
"a photo of the nice {}",
"a photo of the small {}",
"a photo of the weird {}",
"a photo of the large {}",
"a photo of a cool {}",
"a photo of a small {}",
]
imagenet_style_templates_small = [
"a painting in the style of {}",
"a rendering in the style of {}",
"a cropped painting in the style of {}",
"the painting in the style of {}",
"a clean painting in the style of {}",
"a dirty painting in the style of {}",
"a dark painting in the style of {}",
"a picture in the style of {}",
"a cool painting in the style of {}",
"a close-up painting in the style of {}",
"a bright painting in the style of {}",
"a cropped painting in the style of {}",
"a good painting in the style of {}",
"a close-up painting in the style of {}",
"a rendition in the style of {}",
"a nice painting in the style of {}",
"a small painting in the style of {}",
"a weird painting in the style of {}",
"a large painting in the style of {}",
]
class TextualInversionTrainer:
def __init__(self):
self.vae_scale_factor = 0.18215
self.is_sdxl = False
def assert_extra_args(self, args, train_dataset_group: Union[DatasetGroup, MinimalDataset], val_dataset_group: Optional[DatasetGroup]):
train_dataset_group.verify_bucket_reso_steps(64)
if val_dataset_group is not None:
val_dataset_group.verify_bucket_reso_steps(64)
def load_target_model(self, args, weight_dtype, accelerator):
text_encoder, vae, unet, _ = model_io.load_target_model(args, weight_dtype, accelerator)
return model_util.get_model_version_str_for_sd1_sd2(args.v2, args.v_parameterization), [text_encoder], vae, unet
def get_tokenize_strategy(self, args):
return strategy_sd.SdTokenizeStrategy(args.v2, args.max_token_length, args.tokenizer_cache_dir)
def get_tokenizers(self, tokenize_strategy: strategy_sd.SdTokenizeStrategy) -> List[Any]:
return [tokenize_strategy.tokenizer]
def get_latents_caching_strategy(self, args):
latents_caching_strategy = strategy_sd.SdSdxlLatentsCachingStrategy(
True, args.cache_latents_to_disk, args.vae_batch_size, args.skip_cache_check
)
return latents_caching_strategy
def assert_token_string(self, token_string, tokenizers: CLIPTokenizer):
pass
def get_text_encoding_strategy(self, args):
return strategy_sd.SdTextEncodingStrategy(args.clip_skip)
def get_models_for_text_encoding(self, args, accelerator, text_encoders) -> List[Any]:
return text_encoders
def call_unet(self, args, accelerator, unet, noisy_latents, timesteps, text_conds, batch, weight_dtype):
noise_pred = unet(noisy_latents, timesteps, text_conds[0]).sample
return noise_pred
def sample_images(
self, accelerator, args, epoch, global_step, device, vae, tokenizers, text_encoders, unet, prompt_replacement
):
sampling.sample_images(
accelerator, args, epoch, global_step, device, vae, tokenizers[0], text_encoders[0], unet, prompt_replacement
)
def save_weights(self, file, updated_embs, save_dtype, metadata):
state_dict = {"emb_params": updated_embs[0]}
if save_dtype is not None:
for key in list(state_dict.keys()):
v = state_dict[key]
v = v.detach().clone().to("cpu").to(save_dtype)
state_dict[key] = v
if os.path.splitext(file)[1] == ".safetensors":
from safetensors.torch import save_file
save_file(state_dict, file, metadata)
else:
torch.save(state_dict, file) # can be loaded in Web UI
def load_weights(self, file):
if os.path.splitext(file)[1] == ".safetensors":
from safetensors.torch import load_file
data = load_file(file)
else:
# compatible to Web UI's file format
data = torch.load(file, map_location="cpu")
if type(data) != dict:
raise ValueError(f"weight file is not dict / 重みファイルがdict形式ではありません: {file}")
if "string_to_param" in data: # textual inversion embeddings
data = data["string_to_param"]
if hasattr(data, "_parameters"): # support old PyTorch?
data = getattr(data, "_parameters")
emb = next(iter(data.values()))
if type(emb) != torch.Tensor:
raise ValueError(f"weight file does not contains Tensor / 重みファイルのデータがTensorではありません: {file}")
if len(emb.size()) == 1:
emb = emb.unsqueeze(0)
return [emb]
def train(self, args):
if args.output_name is None:
args.output_name = args.token_string
use_template = args.use_object_template or args.use_style_template
args_util.verify_training_args(args)
accelerator_setup.prepare_dataset_args(args, True)
setup_logging(args, reset=True)
cache_latents = args.cache_latents
if args.seed is not None:
set_seed(args.seed)
tokenize_strategy = self.get_tokenize_strategy(args)
strategy_base.TokenizeStrategy.set_strategy(tokenize_strategy)
tokenizers = self.get_tokenizers(tokenize_strategy) # will be removed after sample_image is refactored
# prepare caching strategy: this must be set before preparing dataset. because dataset may use this strategy for initialization.
latents_caching_strategy = self.get_latents_caching_strategy(args)
strategy_base.LatentsCachingStrategy.set_strategy(latents_caching_strategy)
# 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
# モデルを読み込む
model_version, text_encoders, vae, unet = self.load_target_model(args, weight_dtype, accelerator)
# Convert the init_word to token_id
init_token_ids_list = []
if args.init_word is not None:
for i, tokenizer in enumerate(tokenizers):
init_token_ids = tokenizer.encode(args.init_word, add_special_tokens=False)
if len(init_token_ids) > 1 and len(init_token_ids) != args.num_vectors_per_token:
accelerator.print(
f"token length for init words is not same to num_vectors_per_token, init words is repeated or truncated / "
+ f"初期化単語のトークン長がnum_vectors_per_tokenと合わないため、繰り返しまたは切り捨てが発生します: tokenizer {i+1}, length {len(init_token_ids)}"
)
init_token_ids_list.append(init_token_ids)
else:
init_token_ids_list = [None] * len(tokenizers)
# tokenizerに新しい単語を追加する。追加する単語の数はnum_vectors_per_token
# token_stringが hoge の場合、"hoge", "hoge1", "hoge2", ... が追加される
# add new word to tokenizer, count is num_vectors_per_token
# if token_string is hoge, "hoge", "hoge1", "hoge2", ... are added
self.assert_token_string(args.token_string, tokenizers)
token_strings = [args.token_string] + [f"{args.token_string}{i+1}" for i in range(args.num_vectors_per_token - 1)]
token_ids_list = []
token_embeds_list = []
for i, (tokenizer, text_encoder, init_token_ids) in enumerate(zip(tokenizers, text_encoders, init_token_ids_list)):
num_added_tokens = tokenizer.add_tokens(token_strings)
assert (
num_added_tokens == args.num_vectors_per_token
), f"tokenizer has same word to token string. please use another one / 指定したargs.token_stringは既に存在します。別の単語を使ってください: tokenizer {i+1}, {args.token_string}"
token_ids = tokenizer.convert_tokens_to_ids(token_strings)
accelerator.print(f"tokens are added for tokenizer {i+1}: {token_ids}")
assert (
min(token_ids) == token_ids[0] and token_ids[-1] == token_ids[0] + len(token_ids) - 1
), f"token ids is not ordered : tokenizer {i+1}, {token_ids}"
assert (
len(tokenizer) - 1 == token_ids[-1]
), f"token ids is not end of tokenize: tokenizer {i+1}, {token_ids}, {len(tokenizer)}"
token_ids_list.append(token_ids)
# Resize the token embeddings as we are adding new special tokens to the tokenizer
text_encoder.resize_token_embeddings(len(tokenizer))
# Initialise the newly added placeholder token with the embeddings of the initializer token
token_embeds = text_encoder.get_input_embeddings().weight.data
if init_token_ids is not None:
for i, token_id in enumerate(token_ids):
token_embeds[token_id] = token_embeds[init_token_ids[i % len(init_token_ids)]]
# accelerator.print(token_id, token_embeds[token_id].mean(), token_embeds[token_id].min())
token_embeds_list.append(token_embeds)
# load weights
if args.weights is not None:
embeddings_list = self.load_weights(args.weights)
assert len(token_ids) == len(
embeddings_list[0]
), f"num_vectors_per_token is mismatch for weights / 指定した重みとnum_vectors_per_tokenの値が異なります: {len(embeddings)}"
# accelerator.print(token_ids, embeddings.size())
for token_ids, embeddings, token_embeds in zip(token_ids_list, embeddings_list, token_embeds_list):
for token_id, embedding in zip(token_ids, embeddings):
token_embeds[token_id] = embedding
# accelerator.print(token_id, token_embeds[token_id].mean(), token_embeds[token_id].min())
accelerator.print(f"weighs loaded")
accelerator.print(f"create embeddings for {args.num_vectors_per_token} tokens, for {args.token_string}")
# データセットを準備する
if args.dataset_class is None:
blueprint_generator = BlueprintGenerator(ConfigSanitizer(True, True, args.masked_loss, False))
if args.dataset_config is not None:
accelerator.print(f"Load dataset config from {args.dataset_config}")
user_config = config_util.load_user_config(args.dataset_config)
ignored = ["train_data_dir", "reg_data_dir", "in_json"]
if any(getattr(args, attr) is not None for attr in ignored):
accelerator.print(
"ignore following options because config file is found: {0} / 設定ファイルが利用されるため以下のオプションは無視されます: {0}".format(
", ".join(ignored)
)
)
else:
use_dreambooth_method = args.in_json is None
if use_dreambooth_method:
accelerator.print("Use 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("Train 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
self.assert_extra_args(args, train_dataset_group, val_dataset_group)
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)
# make captions: tokenstring tokenstring1 tokenstring2 ...tokenstringn という文字列に書き換える超乱暴な実装
if use_template:
accelerator.print(f"use template for training captions. is object: {args.use_object_template}")
templates = imagenet_templates_small if args.use_object_template else imagenet_style_templates_small
replace_to = " ".join(token_strings)
captions = []
for tmpl in templates:
captions.append(tmpl.format(replace_to))
train_dataset_group.add_replacement("", captions)
# サンプル生成用
if args.num_vectors_per_token > 1:
prompt_replacement = (args.token_string, replace_to)
else:
prompt_replacement = None
else:
# サンプル生成用
if args.num_vectors_per_token > 1:
replace_to = " ".join(token_strings)
train_dataset_group.add_replacement(args.token_string, replace_to)
prompt_replacement = (args.token_string, replace_to)
else:
prompt_replacement = None
if args.debug_dataset:
dataset_util.debug_dataset(train_dataset_group, show_input_ids=True)
return
if len(train_dataset_group) == 0:
accelerator.print("No data found. Please verify arguments / 画像がありません。引数指定を確認してください")
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は使えません"
# モデルに xformers とか memory efficient attention を組み込む
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)
clean_memory_on_device(accelerator.device)
accelerator.wait_for_everyone()
if args.gradient_checkpointing:
unet.enable_gradient_checkpointing()
for text_encoder in text_encoders:
text_encoder.gradient_checkpointing_enable()
# 学習に必要なクラスを準備する
accelerator.print("prepare optimizer, data loader etc.")
trainable_params = []
for text_encoder in text_encoders:
trainable_params += text_encoder.get_input_embeddings().parameters()
_, _, optimizer = optimizer_util.get_optimizer(args, trainable_params)
# 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を用意する
lr_scheduler = optimizer_util.get_scheduler_fix(args, optimizer, accelerator.num_processes)
# acceleratorがなんかよろしくやってくれるらしい
optimizer, train_dataloader, lr_scheduler = accelerator.prepare(optimizer, train_dataloader, lr_scheduler)
text_encoders = [accelerator.prepare(text_encoder) for text_encoder in text_encoders]
index_no_updates_list = []
orig_embeds_params_list = []
for tokenizer, token_ids, text_encoder in zip(tokenizers, token_ids_list, text_encoders):
index_no_updates = torch.arange(len(tokenizer)) < token_ids[0]
index_no_updates_list.append(index_no_updates)
# accelerator.print(len(index_no_updates), torch.sum(index_no_updates))
orig_embeds_params = accelerator.unwrap_model(text_encoder).get_input_embeddings().weight.data.detach().clone()
orig_embeds_params_list.append(orig_embeds_params)
# Freeze all parameters except for the token embeddings in text encoder
text_encoder.requires_grad_(True)
unwrapped_text_encoder = accelerator.unwrap_model(text_encoder)
unwrapped_text_encoder.text_model.encoder.requires_grad_(False)
unwrapped_text_encoder.text_model.final_layer_norm.requires_grad_(False)
unwrapped_text_encoder.text_model.embeddings.position_embedding.requires_grad_(False)
# text_encoder.text_model.embeddings.token_embedding.requires_grad_(True)
unet.requires_grad_(False)
unet.to(accelerator.device, dtype=weight_dtype)
if args.gradient_checkpointing: # according to TI example in Diffusers, train is required
# TODO U-Netをオリジナルに置き換えたのでいらないはずなので、後で確認して消す
unet.train()
else:
unet.eval()
text_encoding_strategy = self.get_text_encoding_strategy(args)
strategy_base.TextEncodingStrategy.set_strategy(text_encoding_strategy)
if not cache_latents: # キャッシュしない場合はVAEを使うのでVAEを準備する
vae.requires_grad_(False)
vae.eval()
vae.to(accelerator.device, dtype=vae_dtype)
# 実験的機能:勾配も含めたfp16学習を行う PyTorchにパッチを当ててfp16でのgrad scaleを有効にする
if args.full_fp16:
accelerator_setup.patch_accelerator_for_fp16_training(accelerator)
for text_encoder in text_encoders:
text_encoder.to(weight_dtype)
if args.full_bf16:
for text_encoder in text_encoders:
text_encoder.to(weight_dtype)
# resumeする
args_util.resume_from_local_or_hf_if_specified(accelerator, args)
# 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 train images * repeats / 学習画像の数×繰り返し回数: {train_dataset_group.num_train_images}")
accelerator.print(f" num reg images / 正則化画像の数: {train_dataset_group.num_reg_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 / バッチサイズ: {args.train_batch_size}")
accelerator.print(
f" total train batch size (with parallel & distributed & accumulation) / 総バッチサイズ(並列学習、勾配合計含む): {total_batch_size}"
)
accelerator.print(f" gradient ccumulation 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(
"textual_inversion" 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,
)
# function for saving/removing
def save_model(ckpt_name, embs_list, steps, epoch_no, force_sync_upload=False):
os.makedirs(args.output_dir, exist_ok=True)
ckpt_file = os.path.join(args.output_dir, ckpt_name)
accelerator.print(f"\nsaving checkpoint: {ckpt_file}")
sai_metadata = model_io.get_sai_model_spec(None, args, self.is_sdxl, False, True)
self.save_weights(ckpt_file, embs_list, save_dtype, sai_metadata)
if args.huggingface_repo_id is not None:
huggingface_util.upload(args, ckpt_file, "/" + ckpt_name, force_sync_upload=force_sync_upload)
def remove_model(old_ckpt_name):
old_ckpt_file = os.path.join(args.output_dir, old_ckpt_name)
if os.path.exists(old_ckpt_file):
accelerator.print(f"removing old checkpoint: {old_ckpt_file}")
os.remove(old_ckpt_file)
# For --sample_at_first
self.sample_images(
accelerator,
args,
0,
global_step,
accelerator.device,
vae,
tokenizers,
text_encoders,
unet,
prompt_replacement,
)
if len(accelerator.trackers) > 0:
# log empty object to commit the sample images to wandb
accelerator.log({}, step=0)
# training loop
for epoch in range(num_train_epochs):
accelerator.print(f"\nepoch {epoch+1}/{num_train_epochs}")
current_epoch.value = epoch + 1
for text_encoder in text_encoders:
text_encoder.train()
loss_total = 0
for step, batch in enumerate(train_dataloader):
current_step.value = global_step
with accelerator.accumulate(text_encoders[0]):
with torch.no_grad():
if "latents" in batch and batch["latents"] is not None:
latents = batch["latents"].to(accelerator.device).to(dtype=weight_dtype)
else:
# latentに変換
latents = vae.encode(batch["images"].to(dtype=vae_dtype)).latent_dist.sample().to(dtype=weight_dtype)
latents = latents * self.vae_scale_factor
if batch["masks"] is not None:
masked_latents = vae.encode(
batch["masked_images"].to(dtype=vae_dtype)
).latent_dist.sample().to(dtype=weight_dtype)
masked_latents = masked_latents * self.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:]
)
# Get the text embedding for conditioning
input_ids = [ids.to(accelerator.device) for ids in batch["input_ids_list"]]
text_encoder_conds = text_encoding_strategy.encode_tokens(
tokenize_strategy, self.get_models_for_text_encoding(args, accelerator, text_encoders), input_ids
)
if args.full_fp16:
text_encoder_conds = [c.to(weight_dtype) for c in text_encoder_conds]
# 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
)
if batch["masks"] is not None:
# Concatenate the noised latents with the mask and the masked latents
noisy_latents = torch.cat([noisy_latents, mask, masked_latents], dim=1)
# Predict the noise residual
with accelerator.autocast():
noise_pred = self.call_unet(
args, accelerator, unet, noisy_latents, timesteps, text_encoder_conds, batch, weight_dtype
)
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)
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])
loss_weights = batch["loss_weights"] # 各sampleごとのweight
loss = loss * loss_weights
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() # 平均なのでbatch_sizeで割る必要なし
accelerator.backward(loss)
if accelerator.sync_gradients and args.max_grad_norm != 0.0:
params_to_clip = accelerator.unwrap_model(text_encoder).get_input_embeddings().parameters()
accelerator.clip_grad_norm_(params_to_clip, args.max_grad_norm)
optimizer.step()
lr_scheduler.step()
optimizer.zero_grad(set_to_none=True)
# Let's make sure we don't update any embedding weights besides the newly added token
with torch.no_grad():
for text_encoder, orig_embeds_params, index_no_updates in zip(
text_encoders, orig_embeds_params_list, index_no_updates_list
):
# if full_fp16/bf16, input_embeddings_weight is fp16/bf16, orig_embeds_params is fp32
input_embeddings_weight = accelerator.unwrap_model(text_encoder).get_input_embeddings().weight
input_embeddings_weight[index_no_updates] = orig_embeds_params.to(input_embeddings_weight.dtype)[
index_no_updates
]
# Checks if the accelerator has performed an optimization step behind the scenes
if accelerator.sync_gradients:
progress_bar.update(1)
global_step += 1
self.sample_images(
accelerator,
args,
None,
global_step,
accelerator.device,
vae,
tokenizers,
text_encoders,
unet,
prompt_replacement,
)
# 指定ステップごとにモデルを保存
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:
updated_embs_list = []
for text_encoder, token_ids in zip(text_encoders, token_ids_list):
updated_embs = (
accelerator.unwrap_model(text_encoder)
.get_input_embeddings()
.weight[token_ids]
.data.detach()
.clone()
)
updated_embs_list.append(updated_embs)
ckpt_name = checkpoint_io.get_step_ckpt_name(args, "." + args.save_model_as, global_step)
save_model(ckpt_name, updated_embs_list, global_step, epoch)
if args.save_state:
checkpoint_io.save_and_remove_state_stepwise(args, accelerator, global_step)
remove_step_no = checkpoint_io.get_remove_step_no(args, global_step)
if remove_step_no is not None:
remove_ckpt_name = checkpoint_io.get_step_ckpt_name(args, "." + args.save_model_as, remove_step_no)
remove_model(remove_ckpt_name)
current_loss = loss.detach().item()
if len(accelerator.trackers) > 0:
logs = {"loss": current_loss, "lr": float(lr_scheduler.get_last_lr()[0])}
if (
args.optimizer_type.lower().startswith("DAdapt".lower()) or args.optimizer_type.lower() == "Prodigy".lower()
): # tracking d*lr value
logs["lr/d*lr"] = (
lr_scheduler.optimizers[0].param_groups[0]["d"] * lr_scheduler.optimizers[0].param_groups[0]["lr"]
)
accelerator.log(logs, step=global_step)
loss_total += current_loss
avr_loss = loss_total / (step + 1)
logs = {"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_total / len(train_dataloader)}
accelerator.log(logs, step=epoch + 1)
accelerator.wait_for_everyone()
updated_embs_list = []
for text_encoder, token_ids in zip(text_encoders, token_ids_list):
updated_embs = accelerator.unwrap_model(text_encoder).get_input_embeddings().weight[token_ids].data.detach().clone()
updated_embs_list.append(updated_embs)
if args.save_every_n_epochs is not None:
saving = (epoch + 1) % args.save_every_n_epochs == 0 and (epoch + 1) < num_train_epochs
if accelerator.is_main_process and saving:
ckpt_name = checkpoint_io.get_epoch_ckpt_name(args, "." + args.save_model_as, epoch + 1)
save_model(ckpt_name, updated_embs_list, epoch + 1, global_step)
remove_epoch_no = checkpoint_io.get_remove_epoch_no(args, epoch + 1)
if remove_epoch_no is not None:
remove_ckpt_name = checkpoint_io.get_epoch_ckpt_name(args, "." + args.save_model_as, remove_epoch_no)
remove_model(remove_ckpt_name)
if args.save_state:
checkpoint_io.save_and_remove_state_on_epoch_end(args, accelerator, epoch + 1)
self.sample_images(
accelerator,
args,
epoch + 1,
global_step,
accelerator.device,
vae,
tokenizers,
text_encoders,
unet,
prompt_replacement,
)
accelerator.log({})
# end of epoch
is_main_process = accelerator.is_main_process
if is_main_process:
text_encoder = accelerator.unwrap_model(text_encoder)
updated_embs = text_encoder.get_input_embeddings().weight[token_ids].data.detach().clone()
accelerator.end_training()
if is_main_process and (args.save_state or args.save_state_on_train_end):
checkpoint_io.save_state_on_train_end(args, accelerator)
if is_main_process:
ckpt_name = checkpoint_io.get_last_ckpt_name(args, "." + args.save_model_as)
save_model(ckpt_name, updated_embs_list, global_step, num_train_epochs, force_sync_upload=True)
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, False)
args_util.add_training_arguments(parser, True)
args_util.add_masked_loss_arguments(parser)
deepspeed_utils.add_deepspeed_arguments(parser)
args_util.add_optimizer_arguments(parser)
config_util.add_config_arguments(parser)
custom_train_functions.add_custom_train_arguments(parser, False)
parser.add_argument(
"--save_model_as",
type=str,
default="pt",
choices=[None, "ckpt", "pt", "safetensors"],
help="format to save the model (default is .pt) / モデル保存時の形式(デフォルトはpt)",
)
parser.add_argument(
"--weights", type=str, default=None, help="embedding weights to initialize / 学習するネットワークの初期重み"
)
parser.add_argument(
"--num_vectors_per_token", type=int, default=1, help="number of vectors per token / トークンに割り当てるembeddingsの要素数"
)
parser.add_argument(
"--token_string",
type=str,
default=None,
help="token string used in training, must not exist in tokenizer / 学習時に使用されるトークン文字列、tokenizerに存在しない文字であること",
)
parser.add_argument(
"--init_word", type=str, default=None, help="words to initialize vector / ベクトルを初期化に使用する単語、複数可"
)
parser.add_argument(
"--use_object_template",
action="store_true",
help="ignore caption and use default templates for object / キャプションは使わずデフォルトの物体用テンプレートで学習する",
)
parser.add_argument(
"--use_style_template",
action="store_true",
help="ignore caption and use default templates for stype / キャプションは使わずデフォルトのスタイル用テンプレートで学習する",
)
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を使う",
)
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)
trainer = TextualInversionTrainer()
trainer.train(args)