merge

.gitignore

@@ -1,5 +1,9 @@
 *.code-workspace
 multidatabackend*json
+!simpletuner/examples/multidatabackend-small-video-480p+81f.json
+!simpletuner/examples/multidatabackend-small-video-720p+81f.json
+!simpletuner/examples/multidatabackend-small-video-720p+49f.json
+!simpletuner/examples/multidatabackend-small-video-1080p+49f.json
 # Python and virtual environment files
 output/
 temp/

Dockerfile

@@ -37,21 +37,28 @@ RUN apt-get update -y && apt-get install -y --no-install-recommends \
     && git lfs install
 
 # 2. Python Environment & Core Deps
+# Keep container CUDA deps explicit: the full cuda extra installs NVIDIA
+# library wheels that conflict with this CUDA base image.
 RUN python${PYTHON_VERSION} -m venv /opt/venv \
     && pip install --upgrade pip setuptools wheel \
     && pip install --no-cache-dir \
        "huggingface_hub[cli,hf_transfer]" \
        wandb \
        mpi4py \
        ninja \
-       "torchao>=0.17.0,<0.18.0"
+       "bitsandbytes>=0.45.0" \
+       "deepspeed>=0.17.2" \
+       "torchao>=0.17.0,<0.18.0" \
+       "nvidia-ml-py>=12.555" \
+       "lm-eval>=0.4.4" \
+       ramtorch
 
 # 3. Install SimpleTuner
 # Use main for current model integrations such as Boogu-Image.
 ARG SIMPLETUNER_BRANCH=main
 RUN git clone https://github.com/bghira/SimpleTuner --branch $SIMPLETUNER_BRANCH \
     && cd SimpleTuner \
-    && pip install --no-cache-dir -e .[jxl] \
+    && pip install --no-cache-dir -e ".[jxl]" \
     && pip install --no-build-isolation --no-cache-dir sageattention==1.0.6
 
 # 4. Setup Runtime

README.md

@@ -81,31 +81,31 @@ For deployment details, see the [Enterprise Guide](/documentation/experimental/s
 
 ### Model Architecture Support
 
-| Model | Parameters | PEFT LoRA | Lycoris | Full-Rank | ControlNet | Quantization | Flow Matching | Text Encoders |
-|-------|------------|-----------|---------|-----------|------------|--------------|---------------|---------------|
-| **Stable Diffusion XL** | 3.5B | ✓ | ✓ | ✓ | ✓ | int8/nf4 | ✗ | CLIP-L/G |
-| **Stable Diffusion 3** | 2B-8B | ✓ | ✓ | ✓* | ✓ | int8/fp8/nf4 | ✓ | CLIP-L/G + T5-XXL |
-| **Flux.1** | 12B | ✓ | ✓ | ✓* | ✓ | int8/fp8/nf4 | ✓ | CLIP-L + T5-XXL |
-| **Flux.2** | 32B | ✓ | ✓ | ✓* | ✗ | int8/fp8/nf4 | ✓ | Mistral-3 Small |
-| **Ideogram 4** | 9B | ✓ | ✓ | ✓* | ✗ | fp8/nf4 | ✓ | Qwen3-VL |
-| **ACE-Step** | 3.5B | ✓ | ✓ | ✓* | ✗ | int8 | ✓ | UMT5 |
-| **HeartMuLa** | 3B | ✓ | ✓ | ✓* | ✗ | int8 | ✗ | None |
-| **Chroma 1** | 8.9B | ✓ | ✓ | ✓* | ✗ | int8/fp8/nf4 | ✓ | T5-XXL |
-| **Auraflow** | 6.8B | ✓ | ✓ | ✓* | ✓ | int8/fp8/nf4 | ✓ | UMT5-XXL |
-| **PixArt Sigma** | 0.6B-0.9B | ✗ | ✓ | ✓ | ✓ | int8 | ✗ | T5-XXL |
-| **Sana** | 0.6B-4.8B | ✗ | ✓ | ✓ | ✗ | int8 | ✓ | Gemma2-2B |
-| **Lumina2** | 2B | ✓ | ✓ | ✓ | ✗ | int8 | ✓ | Gemma2 |
-| **Kwai Kolors** | 5B | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ChatGLM-6B |
-| **LTX Video** | 5B | ✓ | ✓ | ✓ | ✗ | int8/fp8 | ✓ | T5-XXL |
-| **LTX Video 2** | 19B | ✓ | ✓ | ✓* | ✗ | int8/fp8 | ✓ | Gemma3 |
-| **Wan Video** | 1.3B-14B | ✓ | ✓ | ✓* | ✗ | int8 | ✓ | UMT5 |
-| **HiDream** | 17B (8.5B MoE) | ✓ | ✓ | ✓* | ✓ | int8/fp8/nf4 | ✓ | CLIP-L + T5-XXL + Llama |
-| **Cosmos2** | 2B-14B | ✗ | ✓ | ✓ | ✗ | int8 | ✓ | T5-XXL |
-| **OmniGen** | 3.8B | ✓ | ✓ | ✓ | ✗ | int8/fp8 | ✓ | T5-XXL |
-| **Qwen Image** | 20B | ✓ | ✓ | ✓* | ✗ | int8/nf4 (req.) | ✓ | T5-XXL |
-| **SD 1.x/2.x (Legacy)** | 0.9B | ✓ | ✓ | ✓ | ✓ | int8/nf4 | ✗ | CLIP-L |
-
-*✓ = Supported, ✗ = Not supported, * = Requires DeepSpeed for full-rank training*
+| Model | Parameters | PEFT LoRA | Lycoris | Full-Rank | ControlNet | Ref Inputs | Quantization | Flow Matching | Text Encoders |
+|-------|------------|-----------|---------|-----------|------------|------------|--------------|---------------|---------------|
+| **Stable Diffusion XL** | 3.5B | ✓ | ✓ | ✓ | ✓ | ✗ | int8/nf4 | ✗ | CLIP-L/G |
+| **Stable Diffusion 3** | 2B-8B | ✓ | ✓ | ✓* | ✓ | ✗ | int8/fp8/nf4 | ✓ | CLIP-L/G + T5-XXL |
+| **Flux.1** | 12B | ✓ | ✓ | ✓* | ✓ | ✓ (Kontext) | int8/fp8/nf4 | ✓ | CLIP-L + T5-XXL |
+| **Flux.2** | 32B | ✓ | ✓ | ✓* | ✗ | ✓ opt | int8/fp8/nf4 | ✓ | Mistral-3 Small |
+| **Ideogram 4** | 9B | ✓ | ✓ | ✓* | ✗ | ✗ | fp8/nf4 | ✓ | Qwen3-VL |
+| **ACE-Step** | 3.5B | ✓ | ✓ | ✓* | ✗ | ✗ | int8 | ✓ | UMT5 |
+| **HeartMuLa** | 3B | ✓ | ✓ | ✓* | ✗ | ✗ | int8 | ✗ | None |
+| **Chroma 1** | 8.9B | ✓ | ✓ | ✓* | ✗ | ✗ | int8/fp8/nf4 | ✓ | T5-XXL |
+| **Auraflow** | 6.8B | ✓ | ✓ | ✓* | ✓ | ✗ | int8/fp8/nf4 | ✓ | UMT5-XXL |
+| **PixArt Sigma** | 0.6B-0.9B | ✗ | ✓ | ✓ | ✓ | ✗ | int8 | ✗ | T5-XXL |
+| **Sana** | 0.6B-4.8B | ✗ | ✓ | ✓ | ✗ | ✗ | int8 | ✓ | Gemma2-2B |
+| **Lumina2** | 2B | ✓ | ✓ | ✓ | ✗ | ✗ | int8 | ✓ | Gemma2 |
+| **Kwai Kolors** | 5B | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ChatGLM-6B |
+| **LTX Video** | 5B | ✓ | ✓ | ✓ | ✗ | ✓ I2V | int8/fp8 | ✓ | T5-XXL |
+| **LTX Video 2** | 19B | ✓ | ✓ | ✓* | ✗ | ✓ opt | int8/fp8 | ✓ | Gemma3 |
+| **Wan Video** | 1.3B-14B | ✓ | ✓ | ✓* | ✗ | ✗ | int8 | ✓ | UMT5 |
+| **HiDream** | 17B (8.5B MoE) | ✓ | ✓ | ✓* | ✓ | ✗ | int8/fp8/nf4 | ✓ | CLIP-L + T5-XXL + Llama |
+| **Cosmos2** | 2B-14B | ✗ | ✓ | ✓ | ✗ | ✗ | int8 | ✓ | T5-XXL |
+| **OmniGen** | 3.8B | ✓ | ✓ | ✓ | ✗ | ✗ | int8/fp8 | ✓ | T5-XXL |
+| **Qwen Image** | 20B | ✓ | ✓ | ✓* | ✗ | ✓ req (Edit) | int8/nf4 (req.) | ✓ | T5-XXL |
+| **SD 1.x/2.x (Legacy)** | 0.9B | ✓ | ✓ | ✓ | ✓ | ✗ | int8/nf4 | ✗ | CLIP-L |
+
+*✓ = Supported, ✗ = Not supported, * = Requires DeepSpeed for full-rank training, Ref Inputs marks existing reference/edit/I2V conditioning paths only*
 
 ### Advanced Training Techniques
 
@@ -125,6 +125,7 @@ For deployment details, see the [Enterprise Guide](/documentation/experimental/s
 ### Model-Specific Features
 
 - **Flux Kontext** - Edit conditioning and image-to-image training for Flux models
+- **Reference-input training** - Existing paired reference/edit/I2V paths for Flux Kontext, Flux.2, LTX Video 2, Qwen Edit, LongCat edit/I2V, Boogu edit, Hunyuan I2V, and Kandinsky I2I/I2V
 - **PixArt two-stage** - eDiff training pipeline support for PixArt Sigma
 - **Flow matching models** - Advanced scheduling with beta/uniform distributions
 - **HiDream MoE** - Mixture of Experts gate loss augmentation
@@ -200,6 +201,9 @@ pip install 'simpletuner[cuda]'
 # CUDA 13 / Blackwell users (NVIDIA B-series GPUs)
 pip install 'simpletuner[cuda13]' --extra-index-url https://download.pytorch.org/whl/cu130
 
+# CUDA 13 with TransformerEngine FP8 support
+pip install 'simpletuner[cuda13-transformerengine]' --extra-index-url https://download.pytorch.org/whl/cu130
+
 # ROCm users (AMD GPUs)
 pip install 'simpletuner[rocm]' --extra-index-url https://download.pytorch.org/whl/rocm7.1
 

docker-start.sh

@@ -4,7 +4,7 @@
 # This file can then later be sourced in a login shell
 echo "Exporting environment variables..."
 printenv |
-	grep -E '^RUNPOD_|^PATH=|^HF_HOME=|^HF_TOKEN=|^HUGGING_FACE_HUB_TOKEN=|^WANDB_API_KEY=|^WANDB_TOKEN=|^_=' |
+	grep -E '^RUNPOD_|^PATH=|^HF_HOME=|^HF_TOKEN=|^HUGGING_FACE_HUB_TOKEN=|^SIMPLETUNER_WORKSPACE=|^WANDB_API_KEY=|^WANDB_TOKEN=|^_=' |
 	sed 's/^\(.*\)=\(.*\)$/export \1="\2"/' >>/etc/rp_environment
 
 # Add it to Bash login script

documentation/DATALOADER.es.md

@@ -352,6 +352,20 @@ Genera versiones de baja calidad de las imágenes para entrenamiento de super-re
 }
 ```
 
+##### `sdr` / `logc3_sdr`
+Genera imágenes SDR/de referencia de condicionamiento para datasets de condicionamiento emparejados. El transform `rec709` predeterminado normaliza y recorta entradas Rec.709 SDR ya existentes, igual que la ruta de acondicionamiento de referencia HDR IC-LoRA de LTX-2:
+```json
+{
+  "type": "sdr",
+  "conditioning_type": "reference_strict",
+  "transform": "rec709",
+  "input_scale": 1.0,
+  "exposure": 0.0,
+  "captions": false
+}
+```
+Usa `transform: "srgb"` cuando los valores decodificados sean lineales y quieras un proxy SDR de pantalla. Usa `transform: "logc3"` (o el alias `logc3_sdr`) solo cuando quieras muestras codificadas en LogC3. `input_scale` se aplica antes de exposure y sirve cuando los valores decodificados necesitan normalización. Este generador actualmente opera sobre muestras de imagen que el backend de imágenes de SimpleTuner puede decodificar.
+
 ##### `jpeg_artifacts`
 Crea artefactos de compresión JPEG para entrenamiento de eliminación de artefactos:
 ```json
@@ -590,6 +604,13 @@ Por defecto, SimpleTuner escalará hacia arriba imágenes pequeñas para cumplir
 
 - Además de `prepend_instance_prompt`, reemplaza todos los captions del dataset con una sola frase o palabra trigger.
 
+### `timestep_sampling_offset`
+
+- Desplaza el muestreo de timesteps de flow-matching de este dataset hacia niveles de ruido más altos o más bajos. Se aplica al programa por defecto logit-normal (sigmoid).
+- Un valor **negativo** sesga el muestreo hacia timesteps de menor ruido, centrando el entrenamiento en el detalle fino (por ejemplo, primeros planos o datos con mucha textura). Un valor **positivo** sesga hacia timesteps de mayor ruido, centrándose en la estructura general (por ejemplo, cuerpo entero o datos centrados en la composición).
+- El valor se suma a la muestra normal previa al sigmoid; las magnitudes útiles suelen estar entre `-1.0` y `1.0`. Por defecto es `0.0` (sin sesgo, idéntico al comportamiento original).
+- Como cada lote (batch) proviene de un único dataset, agrupa las imágenes por granularidad semántica en datasets separados y define un `timestep_sampling_offset` para cada uno.
+
 ### `repeats`
 
 - Especifica cuántas veces se ven todas las muestras del dataset durante una época. Útil para dar más impacto a datasets pequeños o maximizar el uso de objetos de caché VAE.

documentation/DATALOADER.hi.md

@@ -352,6 +352,20 @@ Super‑resolution training के लिए images के low‑quality सं
 }
 ```
 
+##### `sdr` / `logc3_sdr`
+Paired conditioning datasets के लिए SDR/reference conditioning images बनाता है। Default `rec709` transform पहले से SDR Rec.709 inputs को normalize और clamp करता है, जो LTX-2 HDR IC-LoRA reference-conditioning path से मेल खाता है:
+```json
+{
+  "type": "sdr",
+  "conditioning_type": "reference_strict",
+  "transform": "rec709",
+  "input_scale": 1.0,
+  "exposure": 0.0,
+  "captions": false
+}
+```
+Decoded source values linear हों और display SDR proxy चाहिए तो `transform: "srgb"` उपयोग करें। LogC3-encoded samples जानबूझकर चाहिए तभी `transform: "logc3"` (या `logc3_sdr` alias) उपयोग करें। `input_scale` exposure से पहले apply होता है और decoded values को normalize करने की जरूरत होने पर उपयोगी है। यह generator अभी उन image samples पर काम करता है जिन्हें SimpleTuner image backend decode कर सकता है।
+
 ##### `jpeg_artifacts`
 Artifact removal training के लिए JPEG compression artifacts बनाता है:
 ```json
@@ -590,6 +604,13 @@ Images cropping से पहले resize नहीं होतीं **जब
 
 - `prepend_instance_prompt` के अतिरिक्त, पूरे dataset के सभी captions को एक ही phrase या trigger word से बदल देता है।
 
+### `timestep_sampling_offset`
+
+- इस dataset के flow-matching timestep sampling को अधिक या कम noise स्तरों की ओर स्थानांतरित करता है। यह डिफ़ॉल्ट logit-normal (sigmoid) schedule पर लागू होता है।
+- **ऋणात्मक** मान sampling को कम-noise timesteps की ओर झुकाता है, जिससे प्रशिक्षण बारीक विवरण (जैसे क्लोज़-अप या texture-प्रधान data) पर केंद्रित होता है। **धनात्मक** मान अधिक-noise timesteps की ओर झुकाता है, जिससे समग्र संरचना (जैसे फ़ुल-बॉडी या रचना-प्रधान data) पर ध्यान केंद्रित होता है।
+- यह मान sigmoid से पहले के normal sample में जोड़ा जाता है; उपयोगी मात्राएँ आमतौर पर `-1.0` से `1.0` के बीच होती हैं। डिफ़ॉल्ट `0.0` है (कोई bias नहीं, मूल व्यवहार के समान)।
+- चूँकि प्रत्येक batch एकल dataset से लिया जाता है, images को semantic granularity के अनुसार अलग-अलग datasets में समूहित करें और प्रत्येक पर `timestep_sampling_offset` सेट करें।
+
 ### `repeats`
 
 - यह बताता है कि epoch के दौरान dataset के सभी samples कितनी बार देखे जाते हैं। छोटे datasets का प्रभाव बढ़ाने या VAE cache objects का अधिकतम उपयोग करने के लिए उपयोगी।

documentation/DATALOADER.ja.md

@@ -352,6 +352,20 @@ Hugging Face の音声データセットでは、キャプション（プロン
 }
 ```
 
+##### `sdr` / `logc3_sdr`
+ペア条件データセット向けに SDR/参照条件画像を生成します。既定の `rec709` transform は、すでに Rec.709 SDR である入力を正規化してクリップし、LTX-2 HDR IC-LoRA の参照条件パスと一致します:
+```json
+{
+  "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 圧縮アーティファクトを作成します:
 ```json
@@ -590,6 +604,13 @@ Canny エッジ検出マップを生成します:
 
 - `prepend_instance_prompt` に加えて、データセット内のすべてのキャプションを単一のフレーズまたはトリガーワードで置き換えます。
 
+### `timestep_sampling_offset`
+
+- このデータセットのフローマッチングのタイムステップサンプリングを、より高いまたは低いノイズレベルへシフトします。デフォルトの logit-normal（sigmoid）スケジュールに適用されます。
+- **負の値**はサンプリングを低ノイズのタイムステップへ偏らせ、細部（クローズアップやテクスチャの多いデータなど）の学習に重点を置きます。**正の値**は高ノイズのタイムステップへ偏らせ、全体の構造（全身や構図中心のデータなど）に重点を置きます。
+- 値は sigmoid 適用前の正規サンプルに加算されます。有効な大きさは通常 `-1.0` ～ `1.0` 程度です。デフォルトは `0.0`（バイアスなし、既存の動作と同一）です。
+- 各バッチは単一のデータセットから取得されるため、画像を意味的な粒度でデータセットに分け、それぞれに `timestep_sampling_offset` を設定してください。
+
 ### `repeats`
 
 - エポック中にデータセット内のすべてのサンプルが表示される回数を指定します。小さなデータセットの影響を強めたり、VAE キャッシュオブジェクトの使用率を最大化したりするのに有用です。

documentation/DATALOADER.md

@@ -353,6 +353,20 @@ Generates low-quality versions of images for super-resolution training:
 }
 ```
 
+##### `sdr` / `logc3_sdr`
+Generates SDR/reference conditioning images for paired conditioning datasets. The default `rec709` transform normalizes and clamps already-SDR Rec.709 inputs, matching the LTX-2 HDR IC-LoRA reference-conditioning path:
+```json
+{
+  "type": "sdr",
+  "conditioning_type": "reference_strict",
+  "transform": "rec709",
+  "input_scale": 1.0,
+  "exposure": 0.0,
+  "captions": false
+}
+```
+Use `transform: "srgb"` when your decoded source values are linear and you want a display SDR proxy. Use `transform: "logc3"` (or the `logc3_sdr` alias) only when you intentionally want LogC3-encoded samples. `input_scale` is applied before exposure and is useful when decoded values need normalization. This generator currently operates on image samples that the SimpleTuner image backend can decode.
+
 ##### `jpeg_artifacts`
 Creates JPEG compression artifacts for artifact removal training:
 ```json
@@ -591,6 +605,13 @@ By default, SimpleTuner will upscale small images to meet the target resolution,
 
 - In addition to `prepend_instance_prompt`, replaces all captions in the dataset with a single phrase or trigger word.
 
+### `timestep_sampling_offset`
+
+- Shifts this dataset's flow-matching timestep sampling toward higher or lower noise levels. Applies to the default logit-normal (sigmoid) schedule.
+- A **negative** value biases sampling toward lower-noise timesteps, focusing training on fine detail (e.g. close-up or texture-heavy data). A **positive** value biases toward higher-noise timesteps, focusing on overall structure (e.g. full-body or composition-heavy data).
+- The value is added to the pre-sigmoid normal sample; useful magnitudes are typically around `-1.0` to `1.0`. Defaults to `0.0` (no bias, identical to stock behaviour).
+- Because each batch is drawn from a single dataset, group images by semantic granularity into separate datasets and set a per-dataset `timestep_sampling_offset` on each.
+
 ### `repeats`
 
 - Specifies the number of times all samples in the dataset are seen during an epoch. Useful for giving more impact to smaller datasets or maximizing the usage of VAE cache objects.