Merge pull request #2433 from bghira/bugfix/flux2-not-allowing-adding-cond-datasets

clarification and fixes for flux2 and other i2i model validation setup

Author: bghira

documentation/OPTIONS.es.md

@@ -646,6 +646,79 @@ Muchas configuraciones se establecen a través del [dataloader config](DATALOADE
 - **Qué**: Desactiva el cálculo de pérdida de evaluación durante la validación.
 - **Por qué**: Cuando se configura un dataset de eval, la pérdida se calcula automáticamente. Si la evaluación CLIP también está habilitada, ambas se ejecutarán. Este flag te permite desactivar selectivamente la pérdida de eval manteniendo la evaluación CLIP habilitada.
 
+### `--validation_using_datasets`
+
+- **Qué**: Usa imágenes de datasets de entrenamiento para validación en lugar de generación pura de texto a imagen.
+- **Por qué**: Habilita el modo de validación imagen-a-imagen (img2img) donde el modelo des-ruido parcialmente imágenes de entrenamiento en lugar de generar desde ruido puro. Útil para:
+  - Probar modelos de edición/inpainting que requieren imágenes de entrada
+  - Evaluar qué tan bien el modelo preserva la estructura de imagen
+  - Modelos que soportan flujos duales texto-a-imagen E imagen-a-imagen (ej., Flux2, LTXVideo2)
+- **Notas**:
+  - Requiere que el modelo tenga un pipeline `IMG2IMG` registrado
+  - Puede combinarse con `--eval_dataset_id` para obtener imágenes de un dataset específico
+  - La fuerza de des-ruido se controla con los ajustes normales de timestep de validación
+
+### `--eval_dataset_id`
+
+- **Qué**: ID de dataset específico a usar para obtener imágenes de evaluación/validación.
+- **Por qué**: Al usar `--validation_using_datasets` o validación basada en conditioning, controla qué dataset provee las imágenes de entrada:
+  - Sin esta opción, las imágenes se seleccionan aleatoriamente de todos los datasets de entrenamiento
+  - Con esta opción, solo se usa el dataset especificado para entradas de validación
+- **Notas**:
+  - El ID de dataset debe coincidir con un dataset configurado en tu config de dataloader
+  - Útil para mantener evaluación consistente usando un dataset de eval dedicado
+  - Para modelos de conditioning, los datos de conditioning del dataset (si existen) también se usarán
+
+---
+
+## Entendiendo Modos de Conditioning y Validación
+
+SimpleTuner soporta tres paradigmas principales para modelos que usan entradas de conditioning (imágenes de referencia, señales de control, etc.):
+
+### 1. Modelos que REQUIEREN Conditioning
+
+Algunos modelos no pueden funcionar sin entradas de conditioning:
+
+- **Flux Kontext**: Siempre necesita imágenes de referencia para entrenamiento estilo edición
+- **Entrenamiento ControlNet**: Requiere imágenes de señal de control
+
+Para estos modelos, un dataset de conditioning es obligatorio. La WebUI mostrará opciones de conditioning como requeridas, y el entrenamiento fallará sin ellas.
+
+### 2. Modelos que SOPORTAN Conditioning Opcional
+
+Algunos modelos pueden operar en modos texto-a-imagen E imagen-a-imagen:
+
+- **Flux2**: Soporta entrenamiento dual T2I/I2I con imágenes de referencia opcionales
+- **LTXVideo2**: Soporta T2V e I2V (imagen-a-video) con conditioning de primer frame opcional
+- **LongCat-Video**: Soporta conditioning de frames opcional
+
+Para estos modelos, PUEDES agregar datasets de conditioning pero no es obligatorio. La WebUI mostrará opciones de conditioning como opcionales.
+
+### 3. Modos de Validación
+
+| Modo | Flag | Comportamiento |
+|------|------|----------------|
+| **Texto-a-Imagen** | (por defecto) | Genera solo desde prompts de texto |
+| **Basado en Dataset** | `--validation_using_datasets` | Des-ruido parcial de imágenes de datasets (img2img) |
+| **Basado en Conditioning** | (auto cuando se configura conditioning) | Usa entradas de conditioning durante validación |
+
+**Combinando modos**: Cuando un modelo soporta conditioning Y `--validation_using_datasets` está habilitado:
+- El sistema de validación obtiene imágenes de datasets
+- Si esos datasets tienen datos de conditioning, se usan automáticamente
+- Usa `--eval_dataset_id` para controlar qué dataset provee entradas
+
+### Tipos de Datos de Conditioning
+
+Diferentes modelos esperan diferentes datos de conditioning:
+
+| Tipo | Modelos | Configuración de Dataset |
+|------|---------|-------------------------|
+| `conditioning` | ControlNet, Control | `type: conditioning` en config de dataset |
+| `image` | Flux Kontext | `type: image` (dataset de imagen estándar) |
+| `latents` | Flux, Flux2 | Conditioning se codifica con VAE automáticamente |
+
+---
+
 ### `--caption_strategy`
 
 - **Qué**: Estrategia para derivar captions de imagen. **Opciones**: `textfile`, `filename`, `parquet`, `instanceprompt`

documentation/OPTIONS.hi.md

@@ -644,6 +644,79 @@ Alternative attention mechanisms समर्थित हैं, जिनक
 - **What**: validation के दौरान evaluation loss गणना disable करें।
 - **Why**: जब eval dataset कॉन्फ़िगर हो, loss स्वतः गणना होता है। यदि CLIP evaluation सक्षम है, तो दोनों चलेंगे। यह flag eval loss को disable करने देता है जबकि CLIP evaluation चालू रहता है।
 
+### `--validation_using_datasets`
+
+- **What**: pure text-to-image generation के बजाय training datasets से images validation के लिए use करें।
+- **Why**: image-to-image (img2img) validation mode enable करता है जहाँ model pure noise से generate करने के बजाय training images को partially denoise करता है। उपयोगी है:
+  - Edit/inpainting models test करने के लिए जिन्हें input images चाहिए
+  - Model image structure को कितना preserve करता है evaluate करने के लिए
+  - Dual text-to-image AND image-to-image workflows support करने वाले models के लिए (जैसे, Flux2, LTXVideo2)
+- **Notes**:
+  - Model में `IMG2IMG` pipeline registered होना चाहिए
+  - `--eval_dataset_id` के साथ combine कर सकते हैं specific dataset से images लेने के लिए
+  - Denoising strength normal validation timestep settings से control होती है
+
+### `--eval_dataset_id`
+
+- **What**: Evaluation/validation image sourcing के लिए specific dataset ID।
+- **Why**: `--validation_using_datasets` या conditioning-based validation use करते समय, यह control करता है कौन सा dataset input images provide करे:
+  - इस option के बिना, images सभी training datasets से randomly select होती हैं
+  - इस option के साथ, केवल specified dataset validation inputs के लिए use होता है
+- **Notes**:
+  - Dataset ID आपके dataloader config में configured dataset से match होना चाहिए
+  - Dedicated eval dataset use करके consistent evaluation maintain करने के लिए useful
+  - Conditioning models के लिए, dataset का conditioning data (यदि हो) भी use होगा
+
+---
+
+## Conditioning और Validation Modes को समझना
+
+SimpleTuner conditioning inputs (reference images, control signals, आदि) use करने वाले models के लिए तीन मुख्य paradigms support करता है:
+
+### 1. Models जो Conditioning REQUIRE करते हैं
+
+कुछ models conditioning inputs के बिना function नहीं कर सकते:
+
+- **Flux Kontext**: Edit-style training के लिए हमेशा reference images चाहिए
+- **ControlNet training**: Control signal images require करता है
+
+इन models के लिए, conditioning dataset mandatory है। WebUI conditioning options को required दिखाएगी, और training इनके बिना fail होगी।
+
+### 2. Models जो Optional Conditioning SUPPORT करते हैं
+
+कुछ models text-to-image AND image-to-image दोनों modes में operate कर सकते हैं:
+
+- **Flux2**: Optional reference images के साथ dual T2I/I2I training support करता है
+- **LTXVideo2**: Optional first-frame conditioning के साथ T2V और I2V (image-to-video) दोनों support करता है
+- **LongCat-Video**: Optional frame conditioning support करता है
+
+इन models के लिए, आप conditioning datasets ADD कर सकते हैं पर जरूरी नहीं। WebUI conditioning options को optional दिखाएगी।
+
+### 3. Validation Modes
+
+| Mode | Flag | Behavior |
+|------|------|----------|
+| **Text-to-Image** | (default) | केवल text prompts से generate |
+| **Dataset-based** | `--validation_using_datasets` | Datasets से images partially denoise (img2img) |
+| **Conditioning-based** | (auto जब conditioning configured हो) | Validation के दौरान conditioning inputs use |
+
+**Modes combine करना**: जब model conditioning support करता है AND `--validation_using_datasets` enabled है:
+- Validation system datasets से images लेता है
+- यदि उन datasets में conditioning data है, तो automatically use होता है
+- `--eval_dataset_id` use करें control करने के लिए कौन सा dataset inputs provide करे
+
+### Conditioning Data Types
+
+Different models different conditioning data expect करते हैं:
+
+| Type | Models | Dataset Setting |
+|------|--------|-----------------|
+| `conditioning` | ControlNet, Control | Dataset config में `type: conditioning` |
+| `image` | Flux Kontext | `type: image` (standard image dataset) |
+| `latents` | Flux, Flux2 | Conditioning automatically VAE-encoded होता है |
+
+---
+
 ### `--caption_strategy`
 
 - **What**: image captions derive करने की रणनीति। **Choices**: `textfile`, `filename`, `parquet`, `instanceprompt`

documentation/OPTIONS.ja.md

@@ -646,6 +646,79 @@ Accelerate の既定値を使いたい項目は省略してください（例: 
 - **内容**: 検証中の評価損失計算を無効化します。
 - **理由**: 評価用データセットを設定すると損失は自動計算されます。CLIP 評価も有効な場合は両方実行されます。このフラグで CLIP を残したまま評価損失だけ無効化できます。
 
+### `--validation_using_datasets`
+
+- **内容**: 純粋なテキストから画像生成の代わりに、学習データセットから画像を検証に使用します。
+- **理由**: 画像から画像 (img2img) 検証モードを有効化し、モデルが純粋なノイズから生成するのではなく学習画像を部分的にデノイズします。以下の場合に便利です：
+  - 入力画像が必要な編集/インペインティングモデルのテスト
+  - モデルが画像構造をどの程度保持するかの評価
+  - テキストから画像と画像から画像の両方のワークフローをサポートするモデル（例：Flux2、LTXVideo2）
+- **注意**:
+  - モデルに `IMG2IMG` パイプラインが登録されている必要があります
+  - `--eval_dataset_id` と組み合わせて特定のデータセットから画像を取得できます
+  - デノイズ強度は通常の検証タイムステップ設定で制御されます
+
+### `--eval_dataset_id`
+
+- **内容**: 評価/検証画像ソーシング用の特定のデータセットID。
+- **理由**: `--validation_using_datasets` またはコンディショニングベースの検証を使用する場合、どのデータセットが入力画像を提供するかを制御します：
+  - このオプションなしでは、すべての学習データセットからランダムに画像が選択されます
+  - このオプションありでは、指定されたデータセットのみが検証入力に使用されます
+- **注意**:
+  - データセットIDはデータローダー設定の設定済みデータセットと一致する必要があります
+  - 専用の評価データセットを使用して一貫した評価を維持するのに便利です
+  - コンディショニングモデルの場合、データセットのコンディショニングデータ（存在する場合）も使用されます
+
+---
+
+## コンディショニングと検証モードの理解
+
+SimpleTunerは、コンディショニング入力（参照画像、制御信号など）を使用するモデル向けに3つの主要なパラダイムをサポートしています：
+
+### 1. コンディショニングを必要とするモデル
+
+一部のモデルはコンディショニング入力なしでは機能しません：
+
+- **Flux Kontext**: 編集スタイルの学習には常に参照画像が必要
+- **ControlNet学習**: 制御信号画像が必要
+
+これらのモデルではコンディショニングデータセットが必須です。WebUIはコンディショニングオプションを必須として表示し、なければ学習は失敗します。
+
+### 2. オプションのコンディショニングをサポートするモデル
+
+一部のモデルはテキストから画像と画像から画像の両方のモードで動作できます：
+
+- **Flux2**: オプションの参照画像でデュアルT2I/I2I学習をサポート
+- **LTXVideo2**: オプションの最初のフレームコンディショニングでT2VとI2V（画像から動画）の両方をサポート
+- **LongCat-Video**: オプションのフレームコンディショニングをサポート
+
+これらのモデルでは、コンディショニングデータセットを追加できますが必須ではありません。WebUIはコンディショニングオプションをオプションとして表示します。
+
+### 3. 検証モード
+
+| モード | フラグ | 動作 |
+|--------|--------|------|
+| **テキストから画像** | (デフォルト) | テキストプロンプトのみから生成 |
+| **データセットベース** | `--validation_using_datasets` | データセットから画像を部分的にデノイズ (img2img) |
+| **コンディショニングベース** | (コンディショニング設定時に自動) | 検証中にコンディショニング入力を使用 |
+
+**モードの組み合わせ**: モデルがコンディショニングをサポートし、かつ `--validation_using_datasets` が有効な場合：
+- 検証システムはデータセットから画像を取得します
+- それらのデータセットにコンディショニングデータがあれば、自動的に使用されます
+- `--eval_dataset_id` を使用してどのデータセットが入力を提供するかを制御できます
+
+### コンディショニングデータタイプ
+
+異なるモデルは異なるコンディショニングデータを期待します：
+
+| タイプ | モデル | データセット設定 |
+|--------|--------|-----------------|
+| `conditioning` | ControlNet, Control | データセット設定で `type: conditioning` |
+| `image` | Flux Kontext | `type: image` (標準画像データセット) |
+| `latents` | Flux, Flux2 | コンディショニングは自動的にVAEエンコードされます |
+
+---
+
 ### `--caption_strategy`
 
 - **内容**: 画像キャプションを導出する戦略。**選択肢**: `textfile`, `filename`, `parquet`, `instanceprompt`

documentation/OPTIONS.md

@@ -644,6 +644,79 @@ A lot of settings are instead set through the [dataloader config](DATALOADER.md)
 - **What**: Disable evaluation loss calculation during validation.
 - **Why**: When an eval dataset is configured, loss will automatically be calculated. If CLIP evaluation is also enabled, they will both run. This flag will allow you to selectively disable eval loss while keeping CLIP evaluation enabled.
 
+### `--validation_using_datasets`
+
+- **What**: Use images from training datasets for validation instead of pure text-to-image generation.
+- **Why**: Enables image-to-image (img2img) validation mode where the model partially denoises training images rather than generating from pure noise. This is useful for:
+  - Testing edit/inpainting models that require input images
+  - Evaluating how well the model preserves image structure
+  - Models that support dual text-to-image AND image-to-image workflows (e.g., Flux2, LTXVideo2)
+- **Notes**:
+  - Requires the model to have an `IMG2IMG` pipeline registered (most dual-mode models use the same pipeline for both)
+  - Can be combined with `--eval_dataset_id` to source images from a specific dataset
+  - The denoising strength is controlled by the normal validation timestep settings
+
+### `--eval_dataset_id`
+
+- **What**: Specific dataset ID to use for evaluation/validation image sourcing.
+- **Why**: When using `--validation_using_datasets` or conditioning-based validation, this controls which dataset provides the input images:
+  - Without this option, images are randomly selected from all training datasets
+  - With this option, only the specified dataset is used for validation inputs
+- **Notes**:
+  - The dataset ID must match a configured dataset in your dataloader config
+  - Useful for keeping evaluation consistent by using a dedicated eval dataset
+  - For conditioning models, the dataset's conditioning data (if any) will also be used
+
+---
+
+## Understanding Conditioning and Validation Modes
+
+SimpleTuner supports three main paradigms for models that use conditioning inputs (reference images, control signals, etc.):
+
+### 1. Models that REQUIRE Conditioning
+
+Some models cannot function without conditioning inputs:
+
+- **Flux Kontext**: Always needs reference images for edit-style training
+- **ControlNet training**: Requires control signal images
+
+For these models, a conditioning dataset is mandatory. The WebUI will show conditioning options as required, and training will fail without them.
+
+### 2. Models that SUPPORT Optional Conditioning
+
+Some models can operate in both text-to-image AND image-to-image modes:
+
+- **Flux2**: Supports dual T2I/I2I training with optional reference images
+- **LTXVideo2**: Supports both T2V and I2V (image-to-video) with optional first-frame conditioning
+- **LongCat-Video**: Supports optional frame conditioning
+
+For these models, you CAN add conditioning datasets but don't have to. The WebUI will show conditioning options as optional.
+
+### 3. Validation Modes
+
+| Mode | Flag | Behavior |
+|------|------|----------|
+| **Text-to-Image** | (default) | Generate from text prompts only |
+| **Dataset-based** | `--validation_using_datasets` | Partially denoise images from datasets (img2img) |
+| **Conditioning-based** | (auto when conditioning configured) | Use conditioning inputs during validation |
+
+**Combining modes**: When a model supports conditioning AND `--validation_using_datasets` is enabled:
+- The validation system sources images from datasets
+- If those datasets have conditioning data, it's used automatically
+- Use `--eval_dataset_id` to control which dataset provides inputs
+
+### Conditioning Data Types
+
+Different models expect different conditioning data:
+
+| Type | Models | Dataset Setting |
+|------|--------|-----------------|
+| `conditioning` | ControlNet, Control | `type: conditioning` in dataset config |
+| `image` | Flux Kontext | `type: image` (standard image dataset) |
+| `latents` | Flux, Flux2 | Conditioning is VAE-encoded automatically |
+
+---
+
 ### `--caption_strategy`
 
 - **What**: Strategy for deriving image captions. **Choices**: `textfile`, `filename`, `parquet`, `instanceprompt`