Dataloader 設定ファイル¶

以下は、multidatabackend.example.json としての最も基本的なデータローダ設定ファイルの例です。

[
  {
    "id": "something-special-to-remember-by",
    "type": "local",
    "instance_data_dir": "/path/to/data/tree",
    "crop": true,
    "crop_style": "center",
    "crop_aspect": "square",
    "resolution": 1024,
    "minimum_image_size": 768,
    "maximum_image_size": 2048,
    "minimum_aspect_ratio": 0.50,
    "maximum_aspect_ratio": 3.00,
    "target_downsample_size": 1024,
    "resolution_type": "pixel_area",
    "prepend_instance_prompt": false,
    "instance_prompt": "something to label every image",
    "only_instance_prompt": false,
    "caption_strategy": "textfile",
    "cache_dir_vae": "/path/to/vaecache",
    "repeats": 0
  },
  {
    "id": "an example backend for text embeds.",
    "dataset_type": "text_embeds",
    "default": true,
    "type": "aws",
    "aws_bucket_name": "textembeds-something-yummy",
    "aws_region_name": null,
    "aws_endpoint_url": "https://foo.bar/",
    "aws_access_key_id": "wpz-764e9734523434",
    "aws_secret_access_key": "xyz-sdajkhfhakhfjd",
    "aws_data_prefix": "",
    "cache_dir": ""
  }
]

設定オプション¶

`id`¶

説明: データセットの一意な識別子です。設定後は固定し、状態追跡エントリとの紐付けに使います。

`disabled`¶

値: true | false
説明: true にすると、このデータセットは学習中に完全にスキップされます。設定を削除せずに一時的に除外したい場合に便利です。
注記: 綴り disable も受け付けます。

`dataset_type`¶

値: image | video | audio | caption | text_embeds | image_embeds | conditioning_image_embeds | conditioning
説明: image、video、audio は主要な学習サンプルを含むデータセットです。text_embeds はテキストエンコーダのキャッシュ出力、image_embeds は VAE 潜在（モデルが使用する場合）を保持し、conditioning_image_embeds は条件画像埋め込み（例: Wan 2.2 I2V の CLIP ビジョン特徴）をキャッシュします。データセットを conditioning に設定した場合、conditioning_data オプションを介して image データセットと関連付けられます。
注記: テキスト埋め込みと画像埋め込みのデータセットは、画像データセットとは異なる定義です。テキスト埋め込みデータセットはテキスト埋め込みオブジェクトのみを保存し、画像データセットは学習データを保存します。
注記: 画像と動画を同一データセットに混在させないでください。分けてください。

`caption_file_extensions`¶

キャプション探索に使用する拡張子の空でないリストを指定できます（例：["jsonl"]）。既定値は ["txt", "json", "jsonl"] です。バックエンド自身のメタデータとバケットキャッシュの JSON は、保存済みファイル一覧から再開するときも必ず除外します。

`data_generator`¶

dataset_type: "caption"（単数形）でのみ利用できます。このオブジェクトを指定すると、画像・テキスト埋め込み・VAE のキャッシュ前に、各キャプションについて指定したすべての解像度の PNG とテキストを生成します。生成結果は通常の画像学習に使用され、蒸留器は不要です。指定しないキャプションデータセットには、引き続きキャプション対応の蒸留器が必要です。

resolutions（必須）：WIDTHxHEIGHT 文字列の空でないリスト。幅と高さは 32 の倍数です。解像度ごとに <id>-generated-<resolution> を作成し、元の短辺ピクセル数でクロップなしの学習を行います。元データセットの probability は各バケットへ均等に分配されます。
batch_size（既定値 1）：生成のバッチサイズで、学習バッチとは独立しています。アクセラレータのメモリ不足時は、その解像度の失敗バッチを半分にし、同じサンプルとシードで再試行します。成功した上限は生成マニフェストに保存されます。バッチ一でも不足する場合や、その他のエラーは生成を停止します。
num_inference_steps（既定値 40）、guidance_scale（1.0）、seed（0）：推論設定。Qwen Image ではガイダンスを true_cfg_scale に対応させ、一を超える場合は空のネガティブプロンプトを使います。検証用ガイダンス設定では上書きされません。
output_dir（省略可）：既定は cache_dir/generated-captions/<id>。出力は設定フィンガープリントごとに保存し、再起動時に再利用します。キャプション、推論設定、解決済み Hub リビジョン、ローカル重みのサイズと変更時刻を含みます。生成中はモデルファイルを変更しないでください。キャプション・モデル・推論設定を変更すると別のキャッシュになり、バッチサイズ変更では分離されません。

生成はアダプターを無効にしたベースモデルで行い、前処理のためにロードした変換器だけを解放します。元のキャプションは変更しません。生成は単一プロセスの準備実行で行ってください。複数プロセスでの data_generator はキャプション読み込み前に拒否されます。分散学習では生成先を通常の image データセットとして使用し、解像度ごとに分けて caption_strategy: "textfile"、crop: false、resolution_type: "pixel" を設定し、resolution にそのバケットの短辺を指定してください。生成器なしのキャプションデータセットでは、チェックポイントのサンプラー位置を保持するため dataloader_prefetch=false が必要です。キャプション一覧、解像度、データセット構成の変更後は新しい学習を開始する必要があります。生成キャッシュの再利用は、そのようなチェックポイント再開の互換性を保証しません。

ローカルキャプション探索では、生成先を入力の instance_data_dir の外に置いてください。重複するディレクトリは探索前に拒否されます。

{
  "id": "assistant-images",
  "type": "local",
  "dataset_type": "caption",
  "instance_data_dir": "data/prompts",
  "caption_strategy": "textfile",
  "data_generator": {
    "batch_size": 2,
    "resolutions": ["512x512", "768x1024"],
    "num_inference_steps": 40,
    "guidance_scale": 1.0,
    "seed": 42
  }
}

`default`¶

dataset_type=text_embeds のみに適用
true にすると、このテキスト埋め込みデータセットが SimpleTuner のテキスト埋め込みキャッシュ（例: 検証用プロンプト埋め込み）の保存先になります。画像データと対にならないため、専用の保存先が必要です。

`cache_dir`¶

dataset_type=text_embeds と dataset_type=image_embeds のみに適用
説明: このデータセットの埋め込みキャッシュファイルの保存先を指定します。text_embeds はテキストエンコーダ出力、image_embeds は VAE 潜在の保存先です。
注記: 主となる画像/動画データセットで VAE キャッシュの保存先を指定する cache_dir_vae とは異なります。

`train_batch_size`¶

学習時の挙動: 独立してサンプリングされる主要データセット (image, video, audio, caption) は、解決後の値を学習マイクロバッチサイズとして使用します。conditioning はペアとなる補助データです。解決後の値はメタデータのバケットサイズには使用されますが、独立した学習マイクロバッチを作成せず、オプティマイザ更新のサンプル数にも個別には加算されません。
説明: このデータセットでグローバルな --train_batch_size を上書きします。主要データセットでは、解決後の値がサンプラのマイクロバッチサイズ、バケットサイズ、および選択時の実際のサンプル数を制御します。conditioning ではメタデータとバケットの準備だけに影響します。未設定の場合はグローバル値を使います。
勾配蓄積: 1 つの蓄積ウィンドウで、解決後のマイクロバッチサイズが異なるデータセットが選択されることがあります。1 回のオプティマイザ更新におけるグローバルなサンプル総数は、すべての蓄積マイクロステップおよびデータ並列ランクにおける実際のローカルマイクロバッチサイズの合計です。上書きのないデータセットが選択された場合、そのランクではグローバル既定値を使います。
グローバル参照値: トレーナーレベルの学習率スケーリングや、単一の固定バッチサイズを必要とするその他の静的設定・レポートでは、引き続きグローバルな --train_batch_size を使用します。そのため、データセットごとの上書きを混在させる場合、通常のグローバル/有効バッチサイズ式は設定上の参照値であり、各オプティマイザ更新の正確なサンプル数ではありません。
勾配チェックポイント: 勾配チェックポイントはバッチサイズの計算に影響しません。
既定値: トレーナーの --train_batch_size 引数にフォールバックします。

`write_batch_size`¶

dataset_type=text_embeds のみに適用
説明: 1 回のバッチ操作で書き込むテキスト埋め込み数。値を大きくすると書き込みスループットは向上しますが、メモリ使用量が増えます。
既定値: トレーナーの --write_batch_size 引数（通常は 128）にフォールバックします。

`text_encoder_batch_size`¶

dataset_type=text_embeds のみに適用
説明: 未キャッシュのテキスト埋め込みを事前計算するとき、1 回のテキストエンコーダ forward でエンコードするキャプション数。値を大きくするとスループットは向上しますが、VRAM 使用量が増えます。
既定値: トレーナーの --text_encoder_batch_size 引数（既定値 1）にフォールバックします。

`text_cache_ondemand`¶

dataset_type=text_embeds のみに適用
値: true | false
説明: テキスト埋め込み全体の事前計算を省略します。既存エントリはこのキャッシュから読み込み、不足する埋め込みは学習または検証時にエンコードしてキャッシュへ書き込みます。
注記: この text_embeds バックエンドに割り当てたすべての画像・動画データセットがこの動作を継承します。一部のソースデータセットで異なる動作を使うには、別の text_embeds バックエンドを作成し、ソースデータセットの text_embeds フィールドで割り当ててください。

`text_cache_disable`¶

dataset_type=text_embeds のみに適用
値: true | false
説明: 既存のテキスト埋め込みは読み込みますが、新しくエンコードした埋め込みは書き込みません。不足エントリは学習または検証時にエンコードされるため、text_cache_ondemand を暗黙に有効化します。
注記: グローバルな --text_cache_disable はすべてのテキストキャッシュに適用されます。グローバル設定が false のとき、選択した text_embeds バックエンドだけ書き込みを無効化するにはこの設定を使います。

`text_embeds`¶

dataset_type=image のみに適用
未設定の場合は default の text_embeds データセットが使われます。既存の text_embeds データセットの id を設定すると、それが使われます。特定のテキスト埋め込みデータセットを画像データセットに関連付けられます。

`image_embeds`¶

dataset_type=image のみに適用
未設定の場合は VAE 出力が画像バックエンドに保存されます。既存の image_embeds データセットの id を設定すると、VAE 出力はそちらに保存されます。画像埋め込みデータセットを画像データに関連付けられます。

`conditioning_image_embeds`¶

dataset_type=image と dataset_type=video に適用
モデルが requires_conditioning_image_embeds を報告する場合、conditioning_image_embeds データセットの id を設定して条件画像埋め込みキャッシュ（例: Wan 2.2 I2V の CLIP ビジョン特徴）を保存します。未設定の場合、SimpleTuner は既定で cache/conditioning_image_embeds/<dataset_id> にキャッシュを書き込み、VAE キャッシュと衝突しないようにします。
これらの埋め込みが必要なモデルは、主要パイプライン経由で画像エンコーダを公開する必要があります。モデルがエンコーダを提供できない場合、前処理は空ファイルを黙って生成するのではなく早期に失敗します。

`cache_dir_conditioning_image_embeds`¶

条件画像埋め込みキャッシュの保存先を上書きするオプションです。
キャッシュを特定のファイルシステムに固定したい場合や、専用のリモートバックエンド（dataset_type=conditioning_image_embeds）を使う場合に設定します。省略時は上記の既定パスが自動的に使われます。

`conditioning_image_embed_batch_size`¶

条件画像埋め込みを生成する際のバッチサイズを上書きするオプションです。
明示的に指定しない場合、conditioning_image_embed_batch_size トレーナー引数、または VAE バッチサイズにフォールバックします。

音声データセット設定 (`dataset_type=audio`)¶

音声バックエンドは専用の audio ブロックをサポートし、メタデータとバケット計算が再生時間に合わせて行われます。例:

"audio": {
  "max_duration_seconds": 90,
  "channels": 2,
  "bucket_strategy": "duration",
  "duration_interval": 15,
  "truncation_mode": "beginning"
}

有効なメディアデータセットがすべて dataset_type: "audio" の場合、SUPPORTS_FAKE_VIDEO_STREAM を持つ動画モデルは自動的に音声のみトレーニングになります。LTX-2 はネイティブの音声専用ブランチを使用します。MiniMax-H3 は latent frame ごとに 1 個の偽動画空間トークンを保持し、動画 loss をマスクします。標準 LoRA では AUDIO_LORA_TARGET が自動選択され、明示した peft_lora_target_modules が優先されます。

bucket_strategy – 現在は duration が既定で、クリップを等間隔のバケットに切り詰め、GPU ごとのサンプリングがバッチ計算に合うようにします。
duration_interval – バケット丸めを秒単位で指定します（未設定時の既定は 3）。15 にすると、77 秒のクリップは 75 秒に丸められます。これにより、単一の長いクリップが他のランクを阻害するのを防ぎ、同じ間隔で切り詰められます。
max_duration_seconds – これを超える長さのクリップはメタデータ探索時に完全にスキップされるため、極端に長いトラックがバケットを予期せず消費しません。
truncation_mode – バケット間隔に揃える際に保持するクリップの部分を決めます。選択肢: beginning、end、random（既定: beginning）。
audio_only – 音声のみモードの互換用 override。音声のみの構成では LTX-2 と MiniMax-H3 に対して自動的に有効化されます。
target_resolution – レガシー override。自動 fake stream はモデルの最小トークン形状を使用します。
標準の音声設定（チャンネル数、キャッシュディレクトリなど）は simpletuner.helpers.data_backend.factory によって作成されるランタイム音声バックエンドに直接マッピングされます。パディングは意図的に回避され、クリップは延長ではなく切り詰められるため、ACE-Step のような拡散トレーナーの挙動と整合します。

S2V トレーニング用の音声設定¶

audio ブロックはビデオデータセットに配置して、ビデオファイルから自動的に音声を抽出できます。S2V（Sound-to-Video）トレーニングを必要とするモデル（例: Wan S2V）では、このブロックは自動的に注入されます。音声をサポートするが必須としないモデル（例: LTX-2）では、明示的に audio セクションを追加してオプトインする必要があります。追加しない場合、ビデオのみがトレーニングされ、オーディオ損失は自動的にマスクされます。

{
  "id": "my-videos",
  "type": "local",
  "dataset_type": "video",
  "instance_data_dir": "datasets/videos",
  "cache_dir_vae": "cache/vae/videos",
  "audio": {
    "auto_split": true,
    "sample_rate": 16000,
    "channels": 1,
    "allow_zero_audio": false
  }
}

これにより my-videos_audio データセットが自動的に作成され、s2v_datasets を通じてリンクされます。

フィールド	型	デフォルト	説明
`audio.auto_split`	bool	true	ビデオファイルからオーディオデータセットを自動生成。`audio` セクションが存在する場合、デフォルトは true。S2V 必須モデルでは `audio` セクションがなくてもデフォルトで true。
`audio.source_from_video`	bool	false	（自動設定）オーディオがビデオから抽出されたことを示す
`audio.allow_zero_audio`	bool	false	音声ストリームのないビデオに対してゼロ埋めオーディオを生成
`audio.audio_only`	bool	false	互換用 override。音声のみの構成では LTX-2 と MiniMax-H3 に対して自動的に有効化
`audio.target_resolution`	int	null	レガシー override。自動 fake stream はモデルファミリーの最小トークン形状を使用
`audio.sample_rate`	int	16000	音声抽出のターゲットサンプルレート
`audio.channels`	int	1	オーディオチャンネル数（1=モノラル、2=ステレオ）
`audio.bucket_strategy`	string	"duration"	オーディオサンプルのバケット戦略
`audio.duration_interval`	float	3.0	バケットグループ化の時間間隔（秒）
`audio.max_duration_seconds`	float	null	最大オーディオ長（超過するとスキップ）
`audio.truncation_mode`	string	"beginning"	長いオーディオの切り詰め方法："beginning"、"end"、"random"

音声キャプション（Hugging Face）¶

Hugging Face の音声データセットでは、キャプション（プロンプト）を構成する列と歌詞を含む列を指定できます:

"config": {
    "audio_caption_fields": ["prompt", "tags"],
    "lyrics_column": "lyrics"
}

* audio_caption_fields: 複数の列を結合してテキストプロンプトを作成します（テキストエンコーダで使用）。 * lyrics_column: 歌詞の列を指定します（歌詞エンコーダで使用）。

メタデータ探索中にローダは各ファイルの sample_rate、num_samples、num_channels、duration_seconds を記録します。CLI のバケットレポートは images ではなく samples を基準に出力され、空のデータセット診断では有効な bucket_strategy/duration_interval（および max_duration_seconds 制限）が表示されるため、ログを深掘りせずに間隔調整できます。

`type`¶

値: aws | local | memory | csv | huggingface | webshart
説明: このデータセットに使用するストレージバックエンド（ローカル、メモリ、csv、またはクラウド）を決定します。

メモリ（tmpfs および RAM disk）バックエンド¶

type: "memory" は、Linux の tmpfs または macOS ネイティブの RAM disk を使用する LocalDataBackend のサブクラス MemoryDataBackend を使用します。利用できるのは dataset_type: "text_embeds" または dataset_type: "image_embeds" のキャッシュストレージエントリだけです。主要な画像、動画、音声、conditioning、評価データセットには使用できません。SimpleTuner は別の空のファイルシステムをマウントし、設定済みの cache_dir が存在する場合はそこからコピーします。実行中の読み書きはメモリ上のコピーを使用し、解放時に破棄されます。変更は cache_dir に同期されません。

{
  "id": "memory-vae-cache",
  "type": "memory",
  "dataset_type": "image_embeds",
  "cache_dir": "/cache/vae",
  "memory_filesystem_path": "/tmp/simpletuner-memory/vae",
  "memory_filesystem_size": "512G",
  "memory_filesystem_sudo": false
}

memory_filesystem_path: 任意の空のマウントディレクトリ。既定値は OS の一時ディレクトリ内の simpletuner-memory/<dataset id> です。このパスと cache_dir は重複したり、一方が他方を内包したりしてはいけません。
memory_filesystem_size: 512G などのメモリファイルシステム容量。Linux では任意で、システムの tmpfs 既定値が適用され、80% のような割合も使用できます。macOS では必須で、割合ではなくバイトサイズを指定します。SimpleTuner が hdiutil に必要な 512 バイトセクタ数へ変換します。
memory_filesystem_sudo: Linux のみ。true の場合、mount と umount を sudo -n 経由で実行します。root 実行時は false のままにします。有効にする場合、パスワード不要の非対話 sudo を事前に設定する必要があります。macOS RAM disk はこのオプションなしで hdiutil と diskutil を使用します。

メモリバックエンドには Linux または macOS と、既存キャッシュおよび学習中に書き込まれるすべての埋め込みを保持できる十分な RAM または swap が必要です。大量メモリ環境で大規模な latent またはテキスト埋め込みキャッシュの反復読み込みがボトルネックになる場合に適しています。既存キャッシュのプリロードは起動時間を増やします。空のキャッシュから開始する場合は、空または存在しない cache_dir を使用してください。

`conditioning_type`¶

値: controlnet | mask | reference_strict | reference_loose
説明: conditioning データセットの条件付けの種類を指定します。
controlnet: コントロール信号学習用の ControlNet 条件入力。
mask: インペインティング学習用のバイナリマスク。
reference_strict: 厳密なピクセル整合の参照画像（Qwen Edit などの編集モデル向け）。
reference_loose: 緩い整合の参照画像。
Flow-DPO メモ: reference_strict は Flow-DPO でも使用され、preferred 学習サンプルごとの rejected/lose 画像 latent を渡します。

`source_dataset_id`¶

dataset_type=conditioning のみに適用（conditioning_type が reference_strict、reference_loose、mask の場合）
説明: 条件データセットをソースの画像/動画データセットに紐付け、ピクセル整合を取ります。設定すると、SimpleTuner はソースデータセットのメタデータを複製し、条件画像がターゲットと整合するようにします。
注記: 厳密な整合モードでは必須、緩い整合では任意です。

`conditioning_data`¶

値: 条件データセットの id 値、または id 値の配列
説明: ControlNet ガイドの説明どおり、image データセットはこのオプションを介して ControlNet または画像マスクデータに紐付けられます。
注記: 複数の条件データセットがある場合は id の配列を指定できます。Flux Kontext の学習時には、条件をランダムに切り替えたり入力を結合したりして、より高度な複数画像合成タスクの学習が可能です。
Flow-DPO: --distillation_method=flow_dpo を使う場合は、ここで reference_strict conditioning データセットをペアにします。

`data_transforms`¶

Values: transform オブジェクト、または transform オブジェクトの配列
Description: 通常の dataloader 設定が始まる前に、ソース dataset から 1 つ以上の生成済み training dataset を展開します。transform が明示的に metadata clone を要求しない限り、生成 dataset は通常の primary dataset として扱われます。
Audio identity transfer: {"task": "identity_transfer", "method": "rvc"} は dataset_type: "audio" の backend で利用できます。音声 identity transfer 用の生成 audio split を準備し、output directory に voice artifact と生成ファイルをキャッシュします。詳しくは Voice Cloning Data Transforms を参照してください。
Identity data: 変換したい音楽は audio backend の instance_data_dir、対象 voice examples は model.identity_data_dir、生成 split path は target.instance_data_dir に置きます。
Stem debugging: model.identity_stem_debug_dir を設定すると、RVC training が実際に使う分離後の identity vocals.wav と no_vocals.wav preview を保存できます。出力で楽器まで声として学習されたように聞こえる場合の確認に使います。
Status: 実験的な実装は、cache manifest の確認、huggingface-hub-rvc artifact layout による Hub artifact の reuse/push、DDP 対応の startup sharding、ローカル RVC log、そして小さな SimpleTuner voice-transfer trainer/converter を提供します。Full-song remix mode は Demucs で vocal separation を行い、vocal-stem mode では separation は不要です。

`instance_data_dir` / `aws_data_prefix`¶

Local: ファイルシステム上のデータパス。
AWS: バケット内のデータに対する S3 プレフィックス。aws_data_prefix は単一プレフィックスの文字列、または同じ bucket 内の複数プレフィックスを走査する文字列リストにできます。

`caption_strategy`¶

textfile は、image.png の隣に改行区切りで 1 つ以上のキャプションを含む image.txt があることを前提とします。これらの画像+テキストのペアは同じディレクトリにある必要があります。
instanceprompt は instance_prompt の値が必要で、その値のみをセット内のすべての画像のキャプションとして使用します。
filename は、ファイル名を変換・整形した文字列（例: アンダースコアを空白に置換）をキャプションとして使用します。
parquet は画像メタデータを含む parquet テーブルからキャプションを取得します。parquet フィールドで設定してください。Parquet caption strategy を参照。
webshart は Webshart shard metadata からキャプションを取得します。type: "webshart" と metadata_backend: "webshart" が必要です。

textfile と parquet は複数キャプションに対応します: - textfile は改行で分割され、各行が別キャプションになります。 - parquet テーブルはフィールドに iterable 型を持てます。

`disable_multiline_split`¶

true に設定すると、キャプションテキストファイルが改行で複数のキャプションバリアントに分割されなくなります。
意図的な改行を含むキャプションを単一のキャプションとして保持したい場合に便利です。
デフォルト: false（改行でキャプションを分割）

`caption_shuffle`¶

タグベースのキャプションの決定論的シャッフルバリアントを生成し、データ拡張に使用します。これにより、モデルはタグの順序が重要でないことを学習し、特定のタグシーケンスへの過学習を軽減します。

設定：

{
  "caption_shuffle": {
    "enable": true,
    "count": 3,
    "seed": 42,
    "split_on": "comma",
    "position_start": 1,
    "include_original": true
  }
}

パラメータ：

enable (bool): キャプションシャッフルを有効にするかどうか。デフォルト: false
count (int): キャプションごとに生成するシャッフルバリアントの数。デフォルト: 1
seed (int): 決定論的シャッフルのシード。指定されていない場合、グローバル --seed 値を使用します。
split_on (string): キャプションをタグに分割する区切り文字。オプション: comma、space、period。デフォルト: comma
position_start (int): 最初の N 個のタグを元の位置に保持（主題/スタイルタグを先頭に保持するのに便利）。デフォルト: 0
include_original (bool): シャッフルされていない元のキャプションをバリアントに含めるかどうか。デフォルト: true

例：

split_on: "comma"、position_start: 1、count: 2 の場合：

元: "dog, running, park, sunny day"
結果: ["dog, running, park, sunny day", "dog, park, sunny day, running", "dog, sunny day, running, park"]

最初のタグ「dog」は固定されたまま、残りのタグがシャッフルされます。

注意：

シャッフルはテキスト埋め込みのプリキャッシュ時に適用されるため、すべてのバリアントは一度に計算されます。
トレーニング中、サンプルごとに 1 つのバリアントがランダムに選択されます。
キャプションのタグ数が position_start + 2 より少ない場合、シャッフルはスキップされます（意味のあるシャッフルができないため）。
include_original: false だがシャッフルできない場合、警告とともに元のキャプションが含まれます。

`metadata_backend`¶

値: discovery | parquet | huggingface | webshart
説明: SimpleTuner がデータセット準備中に画像サイズなどのメタデータをどのように取得するかを制御します。
discovery（既定）: 実画像ファイルをスキャンして寸法を読み取ります。あらゆるストレージバックエンドで動作しますが、大規模データセットでは遅くなります。
parquet: parquet/JSONL ファイルの width_column と height_column から寸法を読み取り、ファイルアクセスを省略します。Parquet caption strategy を参照。
huggingface: Hugging Face データセットのメタデータを使用します。Hugging Face Datasets Support を参照。
webshart: Webshart shard metadata を使い、論理サンプル単位の aspect bucket と captions を画像バイトのスキャンなしで利用します。
注記: parquet を使う場合は width_column と height_column を含む parquet ブロックの設定も必要です。これにより大規模データセットの起動が大幅に高速化されます。

`metadata_update_interval`¶

値: 整数（秒）
説明: 学習中にデータセットメタデータを再取得する間隔（秒）。長時間の学習でデータセットが変更される可能性がある場合に有用です。
既定値: トレーナーの --metadata_update_interval 引数にフォールバックします。

クロップオプション¶

crop: 画像クロップを有効/無効にします。
crop_style: クロップ方法を選択します（random、center、corner、face）。
crop_aspect: クロップのアスペクト比を選択します（closest、random、square、preserve）。
crop_aspect_buckets: crop_aspect が closest または random の場合、このリストからバケットが選択されます。既定ではすべてのバケットが利用可能です（無制限のアップスケールを許可）。必要に応じて max_upscale_threshold でアップスケールを制限します。

`resolution`¶

resolution_type=area: 最終的な画像サイズはメガピクセル数で決まります。ここで 1.05 を指定すると、1024^2（1024x1024）相当の総ピクセル面積、約 1_050_000 ピクセルのアスペクトバケットになります。
resolution_type=pixel_area: area と同様に面積で決まりますが、メガピクセルではなくピクセルで測定します。ここで 1024 を指定すると、1024^2（1024x1024）相当の総ピクセル面積、約 1_050_000 ピクセルのアスペクトバケットになります。
resolution_type=pixel: 最終的な画像サイズは短辺がこの値になるように決定されます。

注記: 画像がアップスケール/ダウンスケール/クロップされるかどうかは、minimum_image_size、maximum_target_size、target_downsample_size、crop、crop_aspect の値に依存します。

`minimum_image_size`¶

サイズがこの値を下回る画像は学習から除外されます。
resolution をメガピクセルで指定する場合（resolution_type=area）、ここもメガピクセルで指定します（例: 1024x1024 面積未満を除外するなら 1.05）。
resolution をピクセルで指定する場合は同じ単位を使います（例: 1024px 短辺長未満を除外するなら 1024）。
推奨: 品質の低いアップスケール画像の学習を避けたい場合を除き、minimum_image_size は resolution と同じにしてください。

`minimum_aspect_ratio`¶

説明: 画像の最小アスペクト比です。これより小さいアスペクト比の画像は学習から除外されます。
注記: 除外対象が多すぎると、トレーナーがスキャンとバケット作成を試みるため起動時に時間を浪費する可能性があります。

注記: データセットのアスペクトおよびメタデータリストが作成済みであれば、skip_file_discovery="vae aspect metadata" を使うことで起動時のスキャンを防ぎ、大幅に時間を節約できます。

`maximum_aspect_ratio`¶

説明: 画像の最大アスペクト比です。これより大きいアスペクト比の画像は学習から除外されます。
注記: 除外対象が多すぎると、トレーナーがスキャンとバケット作成を試みるため起動時に時間を浪費する可能性があります。

注記: データセットのアスペクトおよびメタデータリストが作成済みであれば、skip_file_discovery="vae aspect metadata" を使うことで起動時のスキャンを防ぎ、大幅に時間を節約できます。

`conditioning`¶

値: 条件付け設定オブジェクトの配列
説明: ソース画像から条件データセットを自動生成します。各条件タイプは ControlNet 学習などに使用できる独立したデータセットを作成します。
注記: 指定すると、SimpleTuner は {source_id}_conditioning_{type} のような ID を持つ条件データセットを自動的に作成します。

各条件オブジェクトに含められる項目: - type: 生成する条件の種類（必須） - params: 種類固有のパラメータ（任意） - captions: 生成データセットのキャプション戦略（任意） - false を指定可能（キャプションなし） - 単一の文字列（すべての画像に対する instance prompt として使用） - 文字列の配列（各画像でランダムに選択） - 省略時はソースデータセットのキャプションを使用

利用可能な条件タイプ¶

`superresolution`¶

超解像学習向けに低品質版の画像を生成します:

{
  "type": "superresolution",
  "blur_radius": 2.5,
  "blur_type": "gaussian",
  "add_noise": true,
  "noise_level": 0.03,
  "jpeg_quality": 85,
  "downscale_factor": 2
}

`sdr` / `logc3_sdr`¶

ペア条件データセット向けに SDR/参照条件画像を生成します。既定の rec709 transform は、すでに Rec.709 SDR である入力を正規化してクリップし、LTX-2 HDR IC-LoRA の参照条件パスと一致します:

{
  "type": "sdr",
  "conditioning_type": "reference_strict",
  "transform": "rec709",
  "input_scale": 1.0,
  "exposure": 0.0,
  "captions": false
}

デコード済みソース値がリニアで、表示用 SDR プロキシが必要な場合は transform: "srgb" を使用します。LogC3 エンコードサンプルが明示的に必要な場合だけ transform: "logc3"（または logc3_sdr エイリアス）を使用してください。input_scale は exposure の前に適用され、デコード済み値の正規化が必要な場合に使えます。このジェネレータは現在、SimpleTuner の画像バックエンドがデコードできる画像サンプルを対象とします。

`jpeg_artifacts`¶

アーティファクト除去学習向けに JPEG 圧縮アーティファクトを作成します:

{
  "type": "jpeg_artifacts",
  "quality_mode": "range",
  "quality_range": [10, 30],
  "compression_rounds": 1,
  "enhance_blocks": false
}

`depth` / `depth_midas`¶

DPT モデルを使って深度マップを生成します:

{
  "type": "depth_midas",
  "model_type": "DPT"
}

注記: 深度生成には GPU が必要で、メインプロセスで動作します。CPU ベースのジェネレータより遅くなる場合があります。

`random_masks` / `inpainting`¶

インペインティング学習向けにランダムマスクを作成します:

{
  "type": "random_masks",
  "mask_types": ["rectangle", "circle", "brush", "irregular"],
  "min_coverage": 0.1,
  "max_coverage": 0.5,
  "output_mode": "mask"
}

`canny` / `edges`¶

Canny エッジ検出マップを生成します:

{
  "type": "canny",
  "low_threshold": 100,
  "high_threshold": 200
}

これらの条件データセットの使い方の詳細は ControlNet ガイドを参照してください。

例¶

動画データセット¶

動画データセットは（例: mp4）動画ファイルのフォルダと、通常のキャプション保存方法から構成されます。

[
  {
    "id": "disney-black-and-white",
    "type": "local",
    "dataset_type": "video",
    "crop": false,
    "resolution": 480,
    "minimum_image_size": 480,
    "maximum_image_size": 480,
    "target_downsample_size": 480,
    "resolution_type": "pixel_area",
    "cache_dir_vae": "cache/vae/ltxvideo/disney-black-and-white",
    "instance_data_dir": "datasets/disney-black-and-white",
    "disabled": false,
    "caption_strategy": "textfile",
    "metadata_backend": "discovery",
    "repeats": 0,
    "video": {
        "num_frames": 125,
        "min_frames": 125
    }
  },
  {
    "id": "text-embeds",
    "type": "local",
    "dataset_type": "text_embeds",
    "default": true,
    "cache_dir": "cache/text/ltxvideo",
    "disabled": false,
    "write_batch_size": 128
  }
]

video サブセクションでは次のキーを設定できます:
num_frames（任意、int）は学習に使うフレーム数です。
- 25 fps の場合、125 フレームは 5 秒で標準的な出力です。これを目標にしてください。
min_frames（任意、int）は学習対象として考慮する最小動画長を指定します。
- num_frames 以上である必要があります。未設定の場合は同じ値になります。
max_frames（任意、int）は学習対象として考慮する最大動画長を指定します。
is_i2v（任意、bool）はデータセットで i2v 学習を行うかどうかを指定します。
- LTX では既定で True に設定されていますが、無効化できます。
bucket_strategy（任意、string）は動画のバケット分け方法を指定します:
- aspect_ratio（既定）: 空間アスペクト比のみでバケット化（例: 1.78、0.75）。画像データセットと同じ挙動です。
- resolution_frames: 解像度とフレーム数を WxH@F 形式（例: 1920x1080@125）でバケット化します。解像度や長さが混在するデータセットの学習に有用です。
frame_interval（任意、int）: bucket_strategy: "resolution_frames" の場合、フレーム数はこの値の最も近い倍数に切り下げられます。モデルの必要とするフレーム数の係数に合わせて設定してください（モデルによっては num_frames - 1 が特定の値で割り切れる必要があります）。

自動フレーム数調整: SimpleTuner は、モデル固有の制約を満たすように動画のフレーム数を自動的に調整します。例えば、LTX-2 は frames % 8 == 1 を満たすフレーム数（例: 49、57、65、73、81 など）を必要とします。動画のフレーム数が異なる場合（例: 119 フレーム）、最も近い有効なフレーム数に自動的にトリミングされます（例: 113 フレーム）。調整後に min_frames より短くなる動画は警告メッセージとともにスキップされます。この自動調整は学習エラーを防ぎ、ユーザー側での設定は不要です。

注記: bucket_strategy: "resolution_frames" を num_frames と併用すると、単一のフレームバケットになり、num_frames より短い動画は破棄されます。より多くのフレームバケットと破棄の削減が必要なら num_frames を未設定にしてください。

混在解像度の動画データセットで resolution_frames バケットを使う例:

{
  "id": "mixed-resolution-videos",
  "type": "local",
  "dataset_type": "video",
  "resolution": 720,
  "resolution_type": "pixel_area",
  "instance_data_dir": "datasets/videos",
  "video": {
      "bucket_strategy": "resolution_frames",
      "frame_interval": 25,
      "min_frames": 25,
      "max_frames": 250
  }
}

この設定では 1280x720@100、1920x1080@125、640x480@75 などのバケットが作成されます。動画は学習解像度とフレーム数（最も近い 25 フレームに丸め）でグループ化されます。

Configuration¶

    "minimum_image_size": 1024,
    "resolution": 1024,
    "resolution_type": "pixel"

Outcome¶

短辺が 1024px 未満の画像はすべて学習から除外されます。
768x1024 や 1280x768 は除外されますが、1760x1024 と 1024x1024 は除外されません。
minimum_image_size が resolution と同じため、アップサンプリングは行われません。

Configuration¶

    "minimum_image_size": 1024,
    "resolution": 1024,
    "resolution_type": "pixel_area" # different from the above configuration, which is 'pixel'

Outcome¶

画像の総面積（幅 * 高さ）が最小面積（1024 * 1024）未満の場合、学習から除外されます。
1280x960 のような画像は (1280 * 960) が (1024 * 1024) を上回るため除外されません。
minimum_image_size が resolution と同じため、アップサンプリングは行われません。

Configuration¶

    "minimum_image_size": 0, # or completely unset, not present in the config
    "resolution": 1024,
    "resolution_type": "pixel",
    "crop": false

Outcome¶

アスペクト比を維持したまま短辺が 1024px になるようにリサイズされます。
サイズに基づいて除外される画像はありません。
小さい画像は PIL.resize の単純な方法でアップスケールされ、見た目は良くありません。
学習前に好みのアップスケーラーで手動拡大するのでなければ、アップスケールは避けることを推奨します。

`maximum_image_size` と `target_downsample_size`¶

maximum_image_size と target_downsample_size の両方が設定されている場合のみ、クロップ前に画像がリサイズされます。つまり、4096x4096 の画像は直接 1024x1024 へクロップされるため、望ましくない場合があります。

maximum_image_size はリサイズを開始する閾値を指定します。これを超える画像はクロップ前にダウンサンプリングされます。
target_downsample_size はリサンプル後、クロップ前の画像サイズを指定します。

例¶

Configuration¶

    "resolution_type": "pixel_area",
    "resolution": 1024,
    "maximum_image_size": 1536,
    "target_downsample_size": 1280,
    "crop": true,
    "crop_aspect": "square"

Outcome¶

ピクセル面積が (1536 * 1536) を超える画像は、元のアスペクト比を維持したまま (1280 * 1280) 程度の面積になるようにリサイズされます。
最終画像サイズは (1024 * 1024) のピクセル面積にランダムクロップされます。
例: 20 メガピクセルのデータセットを学習する際、クロップ前に大きくリサイズすることで、人物がタイル壁や背景のぼやけた一部だけになるような過度のコンテキスト損失を避けられます。

`max_upscale_threshold`¶

既定では、SimpleTuner は小さな画像を目標解像度に合わせてアップスケールするため、画質劣化が起こり得ます。max_upscale_threshold オプションを使うと、このアップスケール動作を制限できます。

既定値: null（無制限のアップスケールを許可）
設定時: 指定した閾値を超えるアップスケールが必要なアスペクトバケットを除外します
値の範囲: 0〜1（例: 0.2 = 最大 20% のアップスケールを許可）
適用範囲: crop_aspect が closest または random のときのアスペクトバケット選択

例¶

Configuration¶

    "resolution": 1024,
    "resolution_type": "pixel",
    "crop": true,
    "crop_aspect": "random",
    "crop_aspect_buckets": [1.0, 0.5, 2.0],
    "max_upscale_threshold": null

Outcome¶

すべてのアスペクトバケットが選択可能
256x256 の画像を 1024x1024 にアップスケール可能（4 倍）
非常に小さな画像では画質劣化が起こり得ます

Configuration¶

    "resolution": 1024,
    "resolution_type": "pixel",
    "crop": true,
    "crop_aspect": "random",
    "crop_aspect_buckets": [1.0, 0.5, 2.0],
    "max_upscale_threshold": 0.2

Outcome¶

20% 以内のアップスケールが必要なアスペクトバケットのみ利用可能
256x256 の画像を 1024x1024 に拡大しようとすると（4 倍 = 300% のアップスケール）、利用可能なバケットがありません
850x850 の画像は 1024/850 ≈ 1.2（20% のアップスケール）のためすべてのバケットを使用可能
低品質なアップスケール画像を除外し、学習品質の維持に役立ちます

`prepend_instance_prompt`¶

有効化すると、すべてのキャプションの先頭に instance_prompt の値が付加されます。

`only_instance_prompt`¶

prepend_instance_prompt に加えて、データセット内のすべてのキャプションを単一のフレーズまたはトリガーワードで置き換えます。

`timestep_sampling_offset`¶

このデータセットのフローマッチングのタイムステップサンプリングを、より高いまたは低いノイズレベルへシフトします。デフォルトの logit-normal（sigmoid）スケジュールに適用されます。
負の値はサンプリングを低ノイズのタイムステップへ偏らせ、細部（クローズアップやテクスチャの多いデータなど）の学習に重点を置きます。正の値は高ノイズのタイムステップへ偏らせ、全体の構造（全身や構図中心のデータなど）に重点を置きます。
値は sigmoid 適用前の正規サンプルに加算されます。有効な大きさは通常 -1.0 ～ 1.0 程度です。デフォルトは 0.0（バイアスなし、既存の動作と同一）です。
各バッチは単一のデータセットから取得されるため、画像を意味的な粒度でデータセットに分け、それぞれに timestep_sampling_offset を設定してください。

`repeats`¶

エポック中にデータセット内のすべてのサンプルが表示される回数を指定します。小さなデータセットの影響を強めたり、VAE キャッシュオブジェクトの使用率を最大化したりするのに有用です。
画像数が 1000 のデータセットと 100 のデータセットがある場合、後者には 9 以上の repeats を設定して合計 1000 画像相当にするのが一般的です。

ℹ️ この値は Kohya スクリプトの同名オプションとは挙動が異なり、Kohya では 1 が繰り返しなしですが、SimpleTuner では 0 が繰り返しなしです。Kohya の値から 1 を引いた値が SimpleTuner に相当します。そのため (dataset_length + repeats * dataset_length) の計算で 9 という値になります。

マルチ GPU 学習とデータセットサイズ¶

複数 GPU で学習する場合、データセットは次の 実効バッチサイズ を満たすだけの大きさが必要です:

effective_batch_size = データセットの train_batch_size × num_gpus × gradient_accumulation_steps

これはデータセットごとのバケットサイズ要件です。1 つの蓄積ウィンドウですべての設定済みデータセットが選択されることを意味せず、異なるマイクロバッチサイズを混在させたオプティマイザ更新の正確なサンプル数を表すものでもありません。

たとえば、GPU が 4 枚、データセットの train_batch_size=4、gradient_accumulation_steps=1 の場合、各アスペクトバケットには（repeats 適用後で）最低 16 サンプルが必要です。

重要: データセット設定から使用可能なバッチが 0 になる場合、SimpleTuner はエラーを出します。エラーメッセージには以下が表示されます: - 現在の設定値（バッチサイズ、GPU 数、repeats） - サンプル数が不足しているアスペクトバケット - 各バケットに必要な最小 repeats - 推奨される解決策

データセットの自動オーバーサブスクリプション¶

データセットが実効バッチサイズより小さい場合に repeats を自動調整するには、--allow_dataset_oversubscription フラグを使用します（OPTIONS.md 参照）。

有効化すると、SimpleTuner は次を行います: - サンプル数が不足している aspect bucket ごとに必要な最小 repeats を計算 - 実効バッチサイズを満たすため、その bucket だけをパディング - 調整内容を警告ログで出力 - 手動設定された repeats を尊重 - データセット設定で明示的に repeats を設定している場合、自動調整はスキップされます

特に次のような場合に有用です: - 小さなデータセット（100 枚未満）を学習する場合 - GPU 数が多くデータセットが小さい場合 - データセット設定を変更せずにバッチサイズを試行したい場合

例: - データセット: 25 枚 - 設定: GPU 8 枚、train_batch_size=4、gradient_accumulation_steps=1 - 実効バッチサイズ: 32 サンプル必要 - オーバーサブスクリプションなし: エラー - --allow_dataset_oversubscription あり: repeats が自動的に 1 へ設定（25 × 2 = 50 サンプル）

`max_num_samples`¶

説明： データセットの最大サンプル数を制限します。設定すると、完全なデータセットから指定されたサイズの決定論的なランダムサブセットが選択されます。
使用例： 大規模な正則化データセットで、小さなトレーニングセットを圧倒しないようにデータの一部のみを使用したい場合に便利です。
決定論的選択： ランダム選択はデータセット id をシードとして使用し、再現性のためにトレーニングセッション間で同じサブセットが選択されることを保証します。
デフォルト： null（制限なし、すべてのサンプルを使用）

例¶

{
  "id": "regularization-data",
  "max_num_samples": 1000,
  ...
}

これにより、データセットから 1000 サンプルが決定論的に選択され、トレーニングを実行するたびに同じ選択が使用されます。

`start_epoch` / `start_step`¶

データセットのサンプリング開始タイミングをスケジュールします。
start_epoch（既定: 1）はエポック番号でゲートし、start_step（既定: 0）は最適化ステップ（勾配蓄積後）でゲートします。両方の条件が満たされるまでサンプルは取得されません。
少なくとも 1 つのデータセットは start_epoch<=1 かつ start_step<=1 を満たす必要があります。そうでない場合、起動時にデータがないため学習がエラーになります。
開始条件を満たさないデータセット（例: start_epoch が --num_train_epochs を超える）はスキップされ、モデルカードに記載されます。
進行中にスケジュールされたデータセットが有効になるとエポック長が増えるため、進捗バーのステップ見積もりは概算になります。

`end_epoch` / `end_step`¶

データセットのサンプリング終了タイミングをスケジュールします（start_epoch/start_step を補完）。
end_epoch（既定: null = 制限なし）はこのエポック後にサンプリングを停止；end_step（既定: null = 制限なし）はこの最適化ステップ後にサンプリングを停止。
どちらかの条件が終了するとデータセットは停止します。両者は独立して動作します。
カリキュラム学習ワークフローに有用です：
早期に低解像度データで訓練し、その後高解像度データに切り替える。
ある時点以降、正則化データを段階的に廃止する。
単一の設定ファイル内で多段階訓練を作成する。

例：カリキュラム学習

[
  {
    "id": "lowres-512",
    "type": "local",
    "dataset_type": "image",
    "instance_data_dir": "/data/512",
    "end_step": 300
  },
  {
    "id": "highres-1024",
    "type": "local",
    "dataset_type": "image",
    "instance_data_dir": "/data/1024",
    "start_step": 300
  }
]

この例では、512px データセットはステップ 1-300 で使用され、その後ステップ 300 から 1024px データセットに引き継がれます。

`is_regularisation_data`¶

is_regularization_data と綴ることもできます。
親教師学習を有効化し、指定データセットに対して凍結ベースモデルの結果を優先する予測ターゲットにします。
ほとんどの diffusion family では現在 LyCORIS アダプタが必要です。
MiniMax Music 3 の language_model トレーニングでは、XM route selection を含む標準 PEFT LoRA の regularisation batch がサポートされます。ターゲットは凍結されたベース planner の次トークン分布です。

`delete_unwanted_images`¶

値: true | false
説明: 有効化すると、サイズやアスペクト比のフィルタ（例: minimum_image_size 未満、minimum_aspect_ratio/maximum_aspect_ratio の範囲外）に失敗した画像がデータセットディレクトリから完全に削除されます。
警告: 破壊的で元に戻せません。注意して使用してください。
既定値: トレーナーの --delete_unwanted_images 引数（既定: false）にフォールバックします。

`delete_problematic_images`¶

値: true | false
説明: 有効化すると、VAE エンコードで失敗した画像（破損ファイル、非対応形式など）がデータセットディレクトリから完全に削除されます。
警告: 破壊的で元に戻せません。注意して使用してください。
既定値: トレーナーの --delete_problematic_images 引数（既定: false）にフォールバックします。

`delete_nsfw_images`¶

値: true | false
説明: --enable_nsfw_check が有効な場合、NSFW 分類器で拒否されたサンプルを、このバックエンドが削除に対応していれば削除します。
警告: 破壊的で元に戻せません。Hugging Face データセットは読み取り専用で、現在の実行のメタデータから外されるだけです。
既定値: トレーナーの --delete_nsfw_images 引数（既定: false）にフォールバックします。

VAE キャッシュ中の NSFW 分類器チェック¶

--enable_nsfw_check=true を設定すると、SimpleTuner は VAE キャッシュ前処理中に Hugging Face Transformers の画像分類器で学習サンプルをスキャンできます。スキャンは bucket discovery の後、VAE エンコードの前に行われるため、拒否されたサンプルは latents が書き込まれる前に現在のメタデータ bucket から削除されます。

プライバシー、責任、法的文脈については NSFW.ja.md を参照してください。

このスキャンは、VAE キャッシュがこれから処理する未キャッシュのサンプルだけに適用されます。既存の VAE キャッシュは信頼され、skip_file_discovery=vae は NSFW enforcement を回避します。これは、trainer がユーザー自身のポリシーでデータセットが準備済みであるとみなすためです。評価データセットはスキャンされません。

分類器設定: - --nsfw_check_models は標準 Hugging Face Transformers 画像分類モデルの CSV リストです。model/repo:threshold=0.5 でモデルごとの閾値を指定できます。 - 既定値は Falconsai/nsfw_image_detection:threshold=0.5,AdamCodd/vit-base-nsfw-detector:threshold=0.5 です。 - trust_remote_code は有効化されず、timm やカスタムモデルコードが必要な分類器はサポートされません。 - --nsfw_check_min_votes は、1 フレームを拒否するために NSFW 判定を返す必要があるモデル数を制御します。

スコープ制御: - --nsfw_check_backend_types は all, local, huggingface, csv, aws などのバックエンド type 値を受け取ります。 - --nsfw_check_sample_types はデータセットの dataset_type 値を受け取ります。既定値は image,conditioning です。動画データセットをスキャンするには video を追加します。 - --delete_nsfw_images=true は変更可能なバックエンドから拒否サンプルを削除します。無効時は現在の実行のメタデータからのみ外されます。

動画と複数フレームサンプル: - --nsfw_check_video_frame_count はチェックするフレーム数を制御します。 - --nsfw_check_video_frame_selection は uniform, first, middle のいずれかです。 - --nsfw_check_video_min_flagged_frames はサンプル全体を拒否するために拒否される必要があるチェック済みフレーム数を制御します。

サンプルがスキャンされた場合、各 VAE キャッシュプロセスは VAE キャッシュディレクトリに nsfw_classifier_report_rank*.json を書き込みます。レポートにはモデル閾値、分類器の集計判定数、拒否サンプルパス、削除数が含まれます。

バックエンドごとの削除は multidatabackend.json で有効化できます。

{
  "id": "train",
  "type": "local",
  "dataset_type": "image",
  "instance_data_dir": "/data/training/images",
  "delete_nsfw_images": true
}

フィルタリング統計の確認¶

SimpleTuner がデータセットを処理する際、フィルタで除外されたファイルの数と理由を追跡します。これらの統計はデータセットのキャッシュファイル（aspect_ratio_bucket_indices_*.json）に保存され、WebUI で確認できます。

追跡される統計: - total_processed: 処理されたファイル数 - too_small: minimum_image_size 未満でフィルタされたファイル - too_long: 時間制限を超えたファイル（オーディオ/ビデオ） - metadata_missing: メタデータ不足でスキップされたファイル - not_found: 見つからなかったファイル - already_exists: キャッシュに既存のファイル（再処理なし） - nsfw: VAE キャッシュ前処理中に NSFW 分類器で拒否されたファイル - other: その他の理由でフィルタされたファイル

WebUI での確認:

WebUI のファイルブラウザでデータセットを閲覧する際、既存のデータセットがあるディレクトリを選択すると、フィルタリング統計が表示されます（利用可能な場合）。これは、データセットの使用可能なサンプル数が予想より少ない理由を診断するのに役立ちます。

フィルタされたファイルのトラブルシューティング:

多くのファイルが too_small としてフィルタされている場合: 1. minimum_image_size の設定を確認 — resolution と resolution_type に合わせる必要があります 2. resolution_type=pixel の場合、minimum_image_size は最小短辺の長さです 3. resolution_type=area または pixel_area の場合、minimum_image_size は最小総面積です

詳細は下記のトラブルシューティングセクションを参照してください。

`slider_strength`¶

値: 任意の浮動小数値（正、負、または 0）
説明: データセットをスライダー LoRA 学習に指定し、対照的な「反対概念」を学習して制御可能なコンセプトアダプタを作成します。
正の値（例: 0.5）: 「概念を強める」— 目を明るくする、笑顔を強くする等。
負の値（例: -0.5）: 「概念を弱める」— 目を暗くする、表情を中立にする等。
0 または未設定: 概念をどちらにも押し出さない中立例。
注記: データセットに slider_strength がある場合、SimpleTuner はバッチを固定サイクル（正 → 負 → 中立）で回します。各グループ内では標準のバックエンド確率が引き続き適用されます。
参照: スライダー LoRA 学習の完全なガイドは SLIDER_LORA.md を参照してください。

`vae_cache_clear_each_epoch`¶

有効化すると、各データセットの繰り返しサイクルの終了時に VAE キャッシュオブジェクトがファイルシステムから削除されます。大規模データセットでは負荷が大きいですが、crop_style=random や crop_aspect=random と併用する場合は、各画像から十分なクロップをサンプリングするために有効化することを推奨します。
実際、ランダムバケットやランダムクロップを使う場合は既定で有効になります。

`vae_cache_ondemand`¶

値: true | false
説明: データセットで有効にすると、不足している VAE 潜在表現を起動時に事前計算せず、学習中にエンコードしてそのデータセットの VAE キャッシュへ書き込みます。
注記: グローバルな --vae_cache_ondemand は引き続き全データセットに適用されます。グローバル設定が false のとき、選択したデータセットだけ VAE 潜在表現をオンデマンドでエンコードするには、このデータセット設定を使います。

`vae_cache_disable`¶

値: true | false
説明: データセットで有効化すると、そのデータセットは VAE 潜在をオンデマンドでエンコードし、新しく生成した潜在をディスクに書き込みません。ディスク容量が懸念される大規模データセットや書き込みが難しい環境に有用です。
注記: グローバルな --vae_cache_disable は引き続き全データセットに適用されます。グローバル設定が false のとき、選択したデータセットだけ VAE キャッシュ書き込みを無効化するにはこのデータセット設定を使います。削除された disable_vae_cache という名前は拒否されるため、vae_cache_disable を使ってください。

VAE キャッシュ方式の選択¶

vae_cache_ondemand は起動時間を短縮する代わりに学習中に処理を行うものであり、VRAM の最適化ではありません。想定されるキャッシュの再利用率と、学習中に VAE を利用可能な状態で維持できるかどうかに応じて、データセットごとに方式を選択してください。

非常に大規模で再利用が見込まれるデータセット: 完全な事前キャッシュによって学習開始が大幅に遅れる場合は、vae_cache_ondemand=true を設定します。全画像の処理を待たずに学習を開始でき、不足している潜在はキャッシュに書き込まれるため、以降のアクセスで再利用できます。
非常に高解像度のデータセット: 学習モデルがロードされた状態で VAE エンコードすると OOM の可能性がある場合は、vae_cache_ondemand=false のままにし、グローバル設定も false にします。既定の起動時事前キャッシュなら、学習前に VAE をアンロードできます。オンデマンドモードと vae_cache_disable はどちらも学習中の VAE エンコードを必要とするため、このメモリ制約の解決にはなりません。VAE のタイリングまたはスライシングにより、起動時事前キャッシュのピークメモリを削減できる場合があります。
再利用がほとんど見込めない Web スケールのデータセット: 数百万から数十億枚の画像があり、予定している学習が 1 エポック近くまで到達しない場合は、vae_cache_disable=true を設定します。サンプリングされた画像は引き続きオンデマンドでエンコードされますが、ほとんどの潜在が二度と読み込まれない場合のキャッシュ書き込みとストレージ増加を避けられます。学習中の VAE メモリ要件はオンデマンドキャッシュと同じです。

`skip_file_discovery`¶

ほとんどの場合は設定不要で、非常に大規模なデータセットでのみ有用です。
このパラメータは、例: vae metadata aspect text のようにカンマまたはスペース区切りの値を受け取り、ローダ設定の 1 つ以上の段階でファイル探索をスキップします。
コマンドラインオプション --skip_file_discovery と同等です。
すでに潜在/埋め込みが完全にキャッシュされているなど、起動時にスキャンしたくないデータセットがある場合に有用で、起動と学習再開が速くなります。

`preserve_data_backend_cache`¶

ほとんどの場合は設定不要で、非常に大規模な AWS データセットでのみ有用です。
skip_file_discovery と同様に、不要で長時間かつ高コストなファイルシステムスキャンを防ぐために使えます。
boolean 値を取り、true にすると生成されたファイルシステム一覧キャッシュが起動時に削除されません。
S3 やローカルの SMR スピニングディスクなど、応答が非常に遅いストレージに対して有用です。
さらに S3 ではバックエンドのリスト取得がコストになるため、避けるべきです。

⚠️ データが継続的に変更されている場合は設定できません。 トレーナーはプールに追加された新しいデータを認識できず、再度フルスキャンが必要になります。

`hash_filenames`¶

VAE キャッシュエントリのファイル名は常にハッシュ化されます。これはユーザー側で変更できず、非常に長いファイル名でもパス長の問題を回避できます。設定に hash_filenames があっても無視されます。

Grounding（空間アノテーション）¶

Grounding パイプラインは、エンティティごとのバウンディングボックスとマスクアノテーションを使用したトレーニング時の空間グラウンディングを可能にします。これはマルチサブジェクトファインチューニング時のサブジェクトブリーディング（subject bleeding）を防止するのに役立ちます。

Grounding の有効化¶

任意の画像または動画データセットに grounding ブロックを追加します：

{
  "id": "my-dataset",
  "type": "local",
  "dataset_type": "image",
  "instance_data_dir": "/path/to/images",
  "grounding": {
    "enabled": true
  }
}

また、--max_grounding_entities を 0 より大きい値（例: 8）に設定して Grounding パイプラインを有効にする必要があります。

バウンディングボックスの自動検出¶

既存の .bbox アノテーションがない場合、Florence-2 を使用して SimpleTuner に自動生成させることができます。grounding 設定内に auto_detect ブロックを追加します：

{
    "id": "my-images",
    "type": "local",
    "dataset_type": "image",
    "instance_data_dir": "/data/images",
    "grounding": {
        "enabled": true,
        "auto_detect": {
            "enabled": true,
            "model": "florence-community/Florence-2-large",
            "labels": ["person", "dog", "cat"],
            "batch_size": 4
        }
    }
}

キー	デフォルト	説明
`enabled`	`false`	自動検出を有効にします。
`model`	`florence-community/Florence-2-large`	HuggingFace Florence-2 モデル ID。
`labels`	`[]`	ガイド付き検出用のオプションのエンティティラベルリスト（`<OPEN_VOCABULARY_DETECTION>` を使用）。空の場合、Florence-2 は各画像を自動的にキャプションし、検出したフレーズをグラウンディングします（`<CAPTION>` + `<CAPTION_TO_PHRASE_GROUNDING>` を使用）。
`batch_size`	`4`	推論バッチあたりの画像数。

自動検出はデータセットセットアップ時に一度実行されます。既に .bbox サイドカーファイルがある画像はスキップされるため、中断後も安全に再開できます。モデルはアクセラレータデバイスにロードされ、検出完了後すぐに解放されます。

注意: 自動検出は type: "local" バックエンドのみサポートしています。

`.bbox` サイドカーファイル¶

各画像と同じベース名で .bbox ファイルを配置します。

.bbox ファイルは3つの形式をサポートしています：JSON 配列、JSON Lines、YOLO txt 形式。

バウンディングボックスの座標は XYXY 形式で [0, 1] に正規化されます。YOLO 形式は中心ベースの XYWH を使用し、自動的に変換されます。mask フィールドはオプションです。

Parquet / HuggingFace bbox カラム¶

parquet または HuggingFace データセットの場合、バックエンド設定で bbox_column を指定します。

サンプルのフィルタリング¶

`filter_func`¶

filter_func は任意のデータセットバックエンドのトップレベルに設定でき、メタデータバケットと VAE キャッシュを作成する前にサンプルを除外します。Hugging Face バックエンドでは従来の huggingface.filter_func も互換性のため引き続き使用できますが、両方がある場合はトップレベルの値が優先されます。

対応フィルタ:

collection: 行の collection フィールドに対する完全一致の許可リスト。
quality_thresholds: quality_column（既定は quality_assessment）内の数値の最小値。
min_width / min_height: 幅と高さのフィールドがある場合の最小寸法。
path_include / path_exclude: local、AWS、CSV、Hugging Face、parquet、Webshart データセットのファイル名/パスフィルタ。path_include は許可リスト、path_exclude はブロックリストです。両方に一致する場合は除外が優先されます。
path_match: パス一致モード。auto（フラットキーの既定）は通常文字列に substring match、* と ? に glob、re: prefix の pattern に regex を使います。contains、glob、regex、exact も指定できます。

{
  "filter_func": {
    "path_include": ["clothing", "notable", "*/curated/*.jpg"],
    "path_exclude": ["watermark", "bad"],
    "path_match": "auto"
  }
}

従来のネスト形式 filter_func.path.include / exclude / mode は既存 config の互換性のため引き続き使用できますが、新しい config では上記のフラットキーを使ってください。

キャプションのフィルタリング¶

`caption_filter_list`¶

テキスト埋め込みデータセットのみ対象です。 JSON リスト、txt ファイルへのパス、または JSON ドキュメントへのパスを指定できます。フィルタ文字列はキャプションから削除する単純語句でも正規表現でも構いません。さらに、sed 形式の s/search/replace/ エントリを使うと、削除ではなくキャプション内文字列の置換ができます。

フィルタリストの例¶

完全な例はこちらにあります。BLIP（一般版）、LLaVA、CogVLM が返しがちな反復的・ネガティブな文字列が含まれています。

以下は短い例で、後で説明します:

arafed
this .* has a
^this is the beginning of the string
s/this/will be found and replaced/

各行の動作は次のとおりです:

arafed（末尾にスペースあり）は、見つかったキャプションから削除されます。末尾スペースを含めると二重スペースが残らず、見た目が良くなります。必須ではありませんが、見栄えが良くなります。
this .* has a は正規表現で、「this ... has a」を含む文字列を削除します。.* は「一致する範囲すべて」を意味し、「has a」に到達した時点で停止します。
^this is the beginning of the string は、キャプションの先頭にある場合に限り「this is the beginning of the string」を削除します。
s/this/will be found and replaced/ は、キャプション内の最初の「this」を「will be found and replaced」に置換します。

❗正規表現のデバッグとテストには regex 101 を使用してください。

高度なテクニック¶

高度な設定例¶

[
  {
    "id": "something-special-to-remember-by",
    "type": "local",
    "instance_data_dir": "/path/to/data/tree",
    "crop": false,
    "crop_style": "random|center|corner|face",
    "crop_aspect": "square|preserve|closest|random",
    "crop_aspect_buckets": [0.33, 0.5, 0.75, 1.0, 1.25, 1.5, 1.75],
    "resolution": 1.0,
    "resolution_type": "area|pixel",
    "minimum_image_size": 1.0,
    "prepend_instance_prompt": false,
    "instance_prompt": "something to label every image",
    "only_instance_prompt": false,
    "caption_strategy": "filename|instanceprompt|parquet|textfile|webshart",
    "disable_multiline_split": false,
    "cache_dir_vae": "/path/to/vaecache",
    "vae_cache_clear_each_epoch": true,
    "probability": 1.0,
    "repeats": 0,
    "start_epoch": 1,
    "start_step": 0,
    "text_embeds": "alt-embed-cache",
    "image_embeds": "vae-embeds-example",
    "conditioning_image_embeds": "conditioning-embeds-example"
  },
  {
    "id": "another-special-name-for-another-backend",
    "type": "aws",
    "aws_bucket_name": "something-yummy",
    "aws_region_name": null,
    "aws_endpoint_url": "https://foo.bar/",
    "aws_access_key_id": "wpz-764e9734523434",
    "aws_secret_access_key": "xyz-sdajkhfhakhfjd",
    "aws_secret_access_key": "xyz-sdajkhfhakhfjd",
    "aws_data_prefix": "",
    "cache_dir_vae": "s3prefix/for/vaecache",
    "vae_cache_clear_each_epoch": true,
    "repeats": 0
  },
  {
      "id": "vae-embeds-example",
      "type": "local",
      "dataset_type": "image_embeds",
      "disabled": false,
  },
  {
      "id": "conditioning-embeds-example",
      "type": "local",
      "dataset_type": "conditioning_image_embeds",
      "disabled": false
  },
  {
    "id": "an example backend for text embeds.",
    "dataset_type": "text_embeds",
    "default": true,
    "type": "aws",
    "aws_bucket_name": "textembeds-something-yummy",
    "aws_region_name": null,
    "aws_endpoint_url": "https://foo.bar/",
    "aws_access_key_id": "wpz-764e9734523434",
    "aws_secret_access_key": "xyz-sdajkhfhakhfjd",
    "aws_data_prefix": "",
    "cache_dir": ""
  },
  {
    "id": "alt-embed-cache",
    "dataset_type": "text_embeds",
    "default": false,
    "type": "local",
    "cache_dir": "/path/to/textembed_cache"
  }
]

CSV URL リストから直接学習¶

注記: CSV には画像のキャプションが含まれている必要があります。

⚠️ これは高度かつ実験的な機能であり、問題が発生する可能性があります。その場合は issue を開いてください。

URL リストからデータを手動でダウンロードする代わりに、直接トレーナーへ渡すことができます。

注記: 画像データは手動でダウンロードするほうが常に望ましいです。ローカルディスク容量を節約したい場合は、代替策としてクラウドデータセットとローカルエンコーダキャッシュの併用を試すこともできます。

利点¶

データを直接ダウンロードする必要がない
SimpleTuner のキャプションツールキットを使って URL リストに直接キャプション付けできる
（該当する場合）画像埋め込みとテキスト埋め込みのみ保存するためディスク容量を節約できる

欠点¶

各画像をダウンロードしてメタデータを収集する高コストかつ低速なアスペクトバケットスキャンが必要
ダウンロード済み画像はオンディスクにキャッシュされ、大きく膨らむ可能性があります。現状のキャッシュ管理は非常に基本的で、書き込みのみ・削除なしのため改善余地があります
無効な URL が多い場合、現在は不良サンプルが URL リストから決して削除されないため、再開時に時間を浪費する可能性があります
提案: 事前に URL 検証タスクを実行して不良サンプルを削除してください。

設定¶

必須キー:

type: "csv"
csv_caption_column
csv_cache_dir
caption_strategy: "csv"

[
    {
        "id": "csvtest",
        "type": "csv",
        "csv_caption_column": "caption",
        "csv_file": "/Volumes/ml/dataset/test_list.csv",
        "csv_cache_dir": "/Volumes/ml/cache/csv/test",
        "cache_dir_vae": "/Volumes/ml/cache/vae/sdxl",
        "caption_strategy": "csv",
        "image_embeds": "image-embeds",
        "crop": true,
        "crop_aspect": "square",
        "crop_style": "center",
        "resolution": 1024,
        "maximum_image_size": 1024,
        "target_downsample_size": 1024,
        "resolution_type": "pixel",
        "minimum_image_size": 0,
        "disabled": false,
        "skip_file_discovery": "",
        "preserve_data_backend_cache": false
    },
    {
      "id": "image-embeds",
      "type": "local"
    },
    {
        "id": "text-embeds",
        "type": "local",
        "dataset_type": "text_embeds",
        "default": true,
        "cache_dir": "/Volumes/ml/cache/text/sdxl",
        "disabled": false,
        "preserve_data_backend_cache": false,
        "skip_file_discovery": "",
        "write_batch_size": 128
    }
]

Parquet キャプション戦略 / JSON Lines データセット¶

⚠️ これは高度な機能であり、ほとんどのユーザーには不要です。

数十万〜数百万枚規模の非常に大きなデータセットで学習する場合、メタデータを txt ファイルではなく parquet データベースに保存するのが最速です。特に学習データを S3 バケットに保存している場合に有効です。

parquet キャプション戦略を使うと、ファイル名を id 値で統一でき、キャプション列を変更する際に多数のテキストファイルを更新したりファイル名を変更したりする必要がありません。

以下は、photo-concept-bucket データセットのキャプションとデータを使用するデータローダ設定例です:

{
  "id": "photo-concept-bucket",
  "type": "local",
  "instance_data_dir": "/models/training/datasets/photo-concept-bucket-downloads",
  "caption_strategy": "parquet",
  "metadata_backend": "parquet",
  "parquet": {
    "path": "photo-concept-bucket.parquet",
    "filename_column": "id",
    "caption_column": "cogvlm_caption",
    "fallback_caption_column": "tags",
    "width_column": "width",
    "height_column": "height",
    "identifier_includes_extension": false
  },
  "resolution": 1.0,
  "minimum_image_size": 0.75,
  "maximum_image_size": 2.0,
  "target_downsample_size": 1.5,
  "prepend_instance_prompt": false,
  "instance_prompt": null,
  "only_instance_prompt": false,
  "disable": false,
  "cache_dir_vae": "/models/training/vae_cache/photo-concept-bucket",
  "probability": 1.0,
  "skip_file_discovery": "",
  "preserve_data_backend_cache": false,
  "vae_cache_clear_each_epoch": true,
  "repeats": 1,
  "crop": true,
  "crop_aspect": "closest",
  "crop_style": "random",
  "crop_aspect_buckets": [1.0, 0.75, 1.23],
  "resolution_type": "area"
}

この設定では:

caption_strategy は parquet に設定されます。
metadata_backend は parquet に設定されます。
新しいセクション parquet を定義する必要があります:
path は parquet または JSONL ファイルへのパスです。
filename_column はファイル名を含む列名です。この例では数値の id 列を使用しています（推奨）。
caption_column はキャプションを含む列名です。この例では cogvlm_caption 列を使用しています。LAION データセットでは TEXT フィールドに相当します。
width_column と height_column は、実際の画像寸法を示す文字列や int、単一エントリの Series 型などを含む列にできます。これにより実画像にアクセスせずに情報を取得でき、データセット準備時間が大幅に短縮されます。
fallback_caption_column は、主キャプションが空のときに使うフォールバックキャプション列名（任意）です。この例では tags 列を使用しています。
identifier_includes_extension は、ファイル名列に拡張子が含まれる場合は true に設定します。そうでない場合、拡張子は .png とみなされます。ファイル名列に拡張子を含めることを推奨します。

⚠️ Parquet の対応範囲はキャプションの読み取りに限定されています。画像サンプルは別途データソースに {id}.png のファイル名で配置してください。ヒントは scripts/toolkit/datasets ディレクトリのスクリプトを参照してください。

他のデータローダ設定と同様に:

prepend_instance_prompt と instance_prompt は通常どおり動作します。
学習実行の合間にサンプルのキャプションを更新すると新しい埋め込みがキャッシュされますが、古い（孤立した）ユニットは削除されません。
データセットに画像が存在しない場合、そのファイル名がキャプションとして使用され、エラーが出力されます。

クラウドデータセットとローカルキャッシュ¶

高価なローカル NVMe ストレージの利用を最大化するため、画像ファイル（png、jpg）のみを S3 バケットに置き、ローカルストレージにテキストエンコーダや VAE（該当する場合）の特徴マップをキャッシュする構成が有用です。

この設定例では:

画像データは S3 互換バケットに保存
VAE データは /local/path/to/cache/vae に保存
テキスト埋め込みは /local/path/to/cache/textencoder に保存

⚠️ resolution や crop など、他のデータセットオプションも忘れずに設定してください。

[
    {
        "id": "data",
        "type": "aws",
        "aws_bucket_name": "text-vae-embeds",
        "aws_endpoint_url": "https://storage.provider.example",
        "aws_access_key_id": "exampleAccessKey",
        "aws_secret_access_key": "exampleSecretKey",
        "aws_region_name": null,
        "cache_dir_vae": "/local/path/to/cache/vae/",
        "caption_strategy": "parquet",
        "metadata_backend": "parquet",
        "parquet": {
            "path": "train.parquet",
            "caption_column": "caption",
            "filename_column": "filename",
            "width_column": "width",
            "height_column": "height",
            "identifier_includes_extension": true
        },
        "preserve_data_backend_cache": false,
        "image_embeds": "vae-embed-storage"
    },
    {
        "id": "vae-embed-storage",
        "type": "local",
        "dataset_type": "image_embeds"
    },
    {
        "id": "text-embed-storage",
        "type": "local",
        "dataset_type": "text_embeds",
        "default": true,
        "cache_dir": "/local/path/to/cache/textencoder/",
        "write_batch_size": 128
    }
]

注記: image_embeds データセットにはデータパスを設定するオプションはありません。これらは画像バックエンドの cache_dir_vae で設定します。

Hugging Face Datasets 対応¶

SimpleTuner は Hugging Face Hub からデータセットを直接読み込み、ローカルに完全ダウンロードせずに扱えるようになりました。この実験的機能は次の用途に適しています:

Hugging Face にホストされる大規模データセット
メタデータや品質評価が組み込まれたデータセット
ローカルストレージを使わない素早い実験

この機能の詳細なドキュメントはこのドキュメントを参照してください。

Hugging Face データセットの基本的な使用例としては、データローダ設定で "type": "huggingface" を指定します:

{
  "id": "my-hf-dataset",
  "type": "huggingface",
  "dataset_name": "username/dataset-name",
  "caption_strategy": "huggingface",
  "metadata_backend": "huggingface",
  "caption_column": "caption",
  "image_column": "image"
}

Webshart Datasets¶

VAE キャッシュの準備では、Webshart は同じシャード内のすべてのアスペクトバケット群を処理してから、次のシャードに進みます。シャード全体のキャッシュにデータセットが収まらない場合、シャードの再ダウンロードを減らせます。キャッシュ済みのサンプルと他のランクに割り当てられたサンプルはグループ化前に除外され、学習サンプラーの順序は変わりません。

キャプションには文字列、ネイティブ JSON オブジェクト、または両者を混在させたリストを使用できます。オブジェクトはメタデータとキャプションキャッシュで保持され、テキストエンコーダーへの入力を準備する際に、 1つの JSON テキストプロンプトへ変換されます。各フィールドが別々のキャプション候補になることはありません。複数の候補にはリストを、フィールドの選択には webshart.caption_key を使用してください。ネイティブ JSON キャプションに対応した webshart が必要で、Ideogram の構造化キャプション正規化にも対応します。

Webshart データセットは webshart パッケージで WebDataset 形式の tar shard を読み込みます。この backend は論理サンプル metadata を aspect bucketing に使うため、ペアになった JSON sidecar は学習サンプルとして扱われません。

{
  "id": "cc12m-webshart",
  "type": "webshart",
  "dataset_type": "image",
  "source": "laion/conceptual-captions-12m-webdataset",
  "metadata": "webshart/conceptual-captions-12m-webdataset-metadata",
  "caption_strategy": "webshart",
  "metadata_backend": "webshart",
  "webshart": {
    "cache_dir": "cache/webshart/cc12m-webshart",
    "shard_cache_gb": 25,
    "parallel_downloads": 4
  }
}

source は必須で、Webshart が discover できる dataset source を指定します。
metadata は任意で、captions を含む別 metadata location を指定できます。webshart/conceptual-captions-12m-webdataset-metadata のような Hugging Face metadata repo では repo id だけを渡します。Webshart は source shard の data/ などのサブフォルダ構成に従います。
metadata_backend は webshart、caption_strategy は webshart または instanceprompt にします。
webshart.cache_dir は SimpleTuner metadata と Webshart caches を保存します。shard_cache_gb と parallel_downloads は Webshart の shard cache に渡されます。shard_cache_gb を 0 にすると、shard 全体の cache を無効にし、index 付き range read を維持します。
webshart.caption_key でキャプションのフィールドを選択できます。1つなら "long_caption"、複数なら ["long_caption", "short_caption"] を指定すると、その順で収集します。キーはパスではなくそのままの名前として、サンプルの JSON メタデータ、インデックスのメタデータ、それぞれの captions 辞書内の名前付き項目の順に検索し、最初にキーが見つかった場所を使います。文字列やリストの値は1つのプロンプトに連結せず、キャプション候補になります。欠落した値や空の値は無視されます。caption_strategy: "webshart" では、選択したキャプションがないサンプルは、既定のキャプションや .txt サイドカーがあってもスキップされます。省略すると既定の取得方法を維持します。JSON の内容がインデックスにない場合はサイドカーを読み込みます。キャプションとバケットのキャッシュは設定したキーに応じて分離されます。WebUI の Webshart 設定では1行に1つのキーを入力します。 JSON サイドカーの読み取りは設定済みの Webshart シャードキャッシュを使用し、キャプションの取得時に画像データをデコードしたり展開したりしません。
webshart_optimize_captions（別綴り webshart_optimise_captions。webshart ブロック内では optimize_captions/optimise_captions も受け付けます）は起動時に caption layout を probe し、captions が metadata index ではなく .txt/.json の sidecar tar member にある場合、それらをローカルの Webshart metadata cache に一度だけ統合します。このオプションがないと、sidecar caption の dataset（たとえば laion/conceptual-captions-12m-webdataset）は captions を列挙するたび — 起動時、checkpoint 時、model card 生成時 — にサンプルごとに 1 回の range read が発生します。metadata に captions が既に埋め込まれている dataset では、統合は自動的にスキップされます。

captions を事前に最適化する¶

同じ統合処理は Webshart CLI からも利用でき、修復済みの metadata を公開することもできるため、runtime オプションなしで dataset のすべての利用者が恩恵を受けられます:

webshart optimize-captions \
  --source organization/dataset \
  --metadata organization/dataset-metadata \
  --destination caption-metadata \
  --shard-cache-dir cache/shards \
  --push-to-hub organization/dataset-metadata

--destination はポータブルな shard ごとの metadata ツリーを書き出し、--push-to-hub はそれを metadata repository にアップロードします。その後、dataloader の metadata オプションをその repository に向けてください。--shard-cache-dir を指定すると、統合処理は sidecar ごとに 1 回の range read を発行する代わりに、完全に cache された shard を再利用できます。

アスペクト比と解像度のカスタムマッピング¶

SimpleTuner の初回起動時、10 進のアスペクト比を目標ピクセルサイズに対応付ける解像度別のマッピング一覧が生成されます。

独自のマッピングを作成すると、トレーナーが自動計算ではなく指定した目標解像度に合わせるようにできます。この機能は誤った設定で重大な影響を与える可能性があるため、自己責任で使用してください。

カスタムマッピングを作成するには:

下記の例に従ってファイルを作成する
ファイル名を aspect_ratio_map-{resolution}.json の形式にする
resolution=1.0 / resolution_type=area の場合、マッピングファイル名は aspect_resolution_map-1.0.json になります
このファイルを --output_dir で指定した場所に配置する
チェックポイントや検証画像が保存される場所と同じです
追加の設定フラグやオプションは不要です。名前と場所が正しければ自動的に検出されて使用されます。

マッピング設定例¶

これは SimpleTuner が生成するアスペクト比マッピングの例です。手動で設定する必要はありませんが、結果の解像度を完全に制御したい場合の出発点として提供されています。

データセットが 100 万枚以上の画像を含む
データローダの resolution が 1.0 に設定されている
データローダの resolution_type が area に設定されている

これは最も一般的な設定で、1 メガピクセルモデル向けに学習可能なアスペクトバケットの一覧です。

{
    "0.07": [320, 4544],    "0.38": [640, 1664],    "0.88": [960, 1088],    "1.92": [1472, 768],    "3.11": [1792, 576],    "5.71": [2560, 448],
    "0.08": [320, 3968],    "0.4": [640, 1600],     "0.89": [1024, 1152],   "2.09": [1472, 704],    "3.22": [1856, 576],    "6.83": [2624, 384],
    "0.1": [320, 3328],     "0.41": [704, 1728],    "0.94": [1024, 1088],   "2.18": [1536, 704],    "3.33": [1920, 576],    "7.0": [2688, 384],
    "0.11": [384, 3520],    "0.42": [704, 1664],    "1.06": [1088, 1024],   "2.27": [1600, 704],    "3.44": [1984, 576],    "8.0": [3072, 384],
    "0.12": [384, 3200],    "0.44": [704, 1600],    "1.12": [1152, 1024],   "2.5": [1600, 640],     "3.88": [1984, 512],
    "0.14": [384, 2688],    "0.46": [704, 1536],    "1.13": [1088, 960],    "2.6": [1664, 640],     "4.0": [2048, 512],
    "0.15": [448, 3008],    "0.48": [704, 1472],    "1.2": [1152, 960],     "2.7": [1728, 640],     "4.12": [2112, 512],
    "0.16": [448, 2816],    "0.5": [768, 1536],     "1.36": [1216, 896],    "2.8": [1792, 640],     "4.25": [2176, 512],
    "0.19": [448, 2304],    "0.52": [768, 1472],    "1.46": [1216, 832],    "3.11": [1792, 576],    "4.38": [2240, 512],
    "0.24": [512, 2112],    "0.55": [768, 1408],    "1.54": [1280, 832],    "3.22": [1856, 576],    "5.0": [2240, 448],
    "0.26": [512, 1984],    "0.59": [832, 1408],    "1.83": [1408, 768],    "3.33": [1920, 576],    "5.14": [2304, 448],
    "0.29": [576, 1984],    "0.62": [832, 1344],    "1.92": [1472, 768],    "3.44": [1984, 576],    "5.71": [2560, 448],
    "0.31": [576, 1856],    "0.65": [832, 1280],    "2.09": [1472, 704],    "3.88": [1984, 512],    "6.83": [2624, 384],
    "0.34": [640, 1856],    "0.68": [832, 1216],    "2.18": [1536, 704],    "4.0": [2048, 512],     "7.0": [2688, 384],
    "0.38": [640, 1664],    "0.74": [896, 1216],    "2.27": [1600, 704],    "4.12": [2112, 512],    "8.0": [3072, 384],
    "0.4": [640, 1600],     "0.83": [960, 1152],    "2.5": [1600, 640],     "4.25": [2176, 512],
    "0.41": [704, 1728],    "0.88": [960, 1088],    "2.6": [1664, 640],     "4.38": [2240, 512],
    "0.42": [704, 1664],    "0.89": [1024, 1152],   "2.7": [1728, 640],     "5.0": [2240, 448],
    "0.44": [704, 1600],    "0.94": [1024, 1088],   "2.8": [1792, 640],     "5.14": [2304, 448]
}

Stable Diffusion 1.5 / 2.0-base（512px）モデルには、次のマッピングが使用できます:

{
    "1.3": [832, 640], "1.0": [768, 768], "2.0": [1024, 512],
    "0.64": [576, 896], "0.77": [640, 832], "0.79": [704, 896],
    "0.53": [576, 1088], "1.18": [832, 704], "0.85": [704, 832],
    "0.56": [576, 1024], "0.92": [704, 768], "1.78": [1024, 576],
    "1.56": [896, 576], "0.67": [640, 960], "1.67": [960, 576],
    "0.5": [512, 1024], "1.09": [768, 704], "1.08": [832, 768],
    "0.44": [512, 1152], "0.71": [640, 896], "1.4": [896, 640],
    "0.39": [448, 1152], "2.25": [1152, 512], "2.57": [1152, 448],
    "0.4": [512, 1280], "3.5": [1344, 384], "2.12": [1088, 512],
    "0.3": [448, 1472], "2.71": [1216, 448], "8.25": [2112, 256],
    "0.29": [384, 1344], "2.86": [1280, 448], "6.2": [1984, 320],
    "0.6": [576, 960]
}

Dataloader 設定ファイル¶

設定オプション¶

id¶

disabled¶

dataset_type¶

caption_file_extensions¶

data_generator¶

default¶

cache_dir¶

train_batch_size¶

write_batch_size¶

text_encoder_batch_size¶

text_cache_ondemand¶

text_cache_disable¶

text_embeds¶

image_embeds¶

conditioning_image_embeds¶

cache_dir_conditioning_image_embeds¶

conditioning_image_embed_batch_size¶

音声データセット設定 (dataset_type=audio)¶

S2V トレーニング用の音声設定¶

音声キャプション（Hugging Face）¶

type¶

メモリ（tmpfs および RAM disk）バックエンド¶

conditioning_type¶

source_dataset_id¶

conditioning_data¶

data_transforms¶

instance_data_dir / aws_data_prefix¶

caption_strategy¶

disable_multiline_split¶

caption_shuffle¶

metadata_backend¶

metadata_update_interval¶

クロップオプション¶

resolution¶

minimum_image_size¶

minimum_aspect_ratio¶

maximum_aspect_ratio¶

conditioning¶

利用可能な条件タイプ¶

superresolution¶

sdr / logc3_sdr¶

jpeg_artifacts¶

depth / depth_midas¶

random_masks / inpainting¶

canny / edges¶

例¶

動画データセット¶

Configuration¶

Outcome¶

Configuration¶

Outcome¶

Configuration¶

Outcome¶

maximum_image_size と target_downsample_size¶

例¶

Configuration¶

Outcome¶

max_upscale_threshold¶

例¶

Configuration¶

Outcome¶

Configuration¶

Outcome¶

prepend_instance_prompt¶

only_instance_prompt¶

timestep_sampling_offset¶

repeats¶

マルチ GPU 学習とデータセットサイズ¶

データセットの自動オーバーサブスクリプション¶

max_num_samples¶

例¶

start_epoch / start_step¶

end_epoch / end_step¶

is_regularisation_data¶

delete_unwanted_images¶

delete_problematic_images¶

delete_nsfw_images¶

VAE キャッシュ中の NSFW 分類器チェック¶

`id`¶

`disabled`¶

`dataset_type`¶

`caption_file_extensions`¶

`data_generator`¶

`default`¶

`cache_dir`¶

`train_batch_size`¶

`write_batch_size`¶

`text_encoder_batch_size`¶

`text_cache_ondemand`¶

`text_cache_disable`¶

`text_embeds`¶

`image_embeds`¶

`conditioning_image_embeds`¶

`cache_dir_conditioning_image_embeds`¶

`conditioning_image_embed_batch_size`¶

音声データセット設定 (`dataset_type=audio`)¶

`type`¶

`conditioning_type`¶

`source_dataset_id`¶

`conditioning_data`¶

`data_transforms`¶

`instance_data_dir` / `aws_data_prefix`¶

`caption_strategy`¶

`disable_multiline_split`¶

`caption_shuffle`¶

`metadata_backend`¶

`metadata_update_interval`¶

`resolution`¶

`minimum_image_size`¶

`minimum_aspect_ratio`¶

`maximum_aspect_ratio`¶

`conditioning`¶

`superresolution`¶

`sdr` / `logc3_sdr`¶

`jpeg_artifacts`¶

`depth` / `depth_midas`¶

`random_masks` / `inpainting`¶

`canny` / `edges`¶

`maximum_image_size` と `target_downsample_size`¶

`max_upscale_threshold`¶

`prepend_instance_prompt`¶

`only_instance_prompt`¶

`timestep_sampling_offset`¶

`repeats`¶

`max_num_samples`¶

`start_epoch` / `start_step`¶

`end_epoch` / `end_step`¶

`is_regularisation_data`¶

`delete_unwanted_images`¶

`delete_problematic_images`¶

`delete_nsfw_images`¶

`slider_strength`¶

`vae_cache_clear_each_epoch`¶

`vae_cache_ondemand`¶

`vae_cache_disable`¶

`skip_file_discovery`¶

`preserve_data_backend_cache`¶

`hash_filenames`¶

`.bbox` サイドカーファイル¶

`filter_func`¶

`caption_filter_list`¶