Merge pull request #2668 from bghira/main

bghira · web-flow · commit fbddde0b880b · 2026-04-02T13:56:41.000-06:00
merge
diff --git a/documentation/OPTIONS.es.md b/documentation/OPTIONS.es.md
@@ -450,6 +450,8 @@ Esto es útil para herramientas de monitoreo que reciben webhooks de múltiples
   - Visible en visualizadores de modelos externos (ComfyUI, herramientas de info de modelos)
   - Acepta una cadena o un array de cadenas (unidas con saltos de línea)
   - Soporta marcadores `{env:VAR_NAME}` para sustitución de variables de entorno
+  - Soporta `{current_step}`, `{current_epoch}` y `{timestamp}` cuando se escribe el metadata
+  - `{timestamp}` usa un valor UTC en formato ISO 8601
   - Cada checkpoint usa el valor de configuración actual en el momento del guardado
 
 **Ejemplo (cadena)**:
@@ -476,6 +478,9 @@ Esto es útil para herramientas de monitoreo que reciben webhooks de múltiples
 
 - **Qué**: Ruta a tu configuración de dataset de SimpleTuner.
 - **Por qué**: Se pueden combinar múltiples datasets en distintos medios de almacenamiento en una sola sesión de entrenamiento.
+- **Notas**:
+  - Los valores de texto cargados desde `config.json` y `config.toml` soportan `{env:VAR_NAME}`
+  - Los valores de texto dentro del `multidatabackend.json` referenciado también soportan `{env:VAR_NAME}`
 - **Ejemplo**: Consulta [multidatabackend.json.example](/multidatabackend.json.example) para un ejemplo de configuración y [este documento](DATALOADER.md) para más información sobre la configuración del data loader.
 
 ### `--override_dataset_config`
diff --git a/documentation/OPTIONS.hi.md b/documentation/OPTIONS.hi.md
@@ -450,6 +450,8 @@ Alternative attention mechanisms समर्थित हैं, जिनक
   - बाहरी model viewers (ComfyUI, model info tools) में दिखाई देता है
   - string या strings की array (newlines से जुड़ी) स्वीकार करता है
   - environment variable substitution के लिए `{env:VAR_NAME}` placeholders support करता है
+  - metadata लिखते समय `{current_step}`, `{current_epoch}`, और `{timestamp}` support करता है
+  - `{timestamp}` UTC ISO 8601 value का उपयोग करता है
   - प्रत्येक checkpoint save के समय current config value उपयोग करता है
 
 **Example (string)**:
@@ -476,6 +478,9 @@ Alternative attention mechanisms समर्थित हैं, जिनक
 
 - **What**: आपके SimpleTuner dataset कॉन्फ़िगरेशन का path.
 - **Why**: अलग‑अलग storage माध्यमों पर कई datasets को एक training session में जोड़ा जा सकता है।
+- **Notes**:
+  - `config.json` और `config.toml` से load की गई string values `{env:VAR_NAME}` support करती हैं
+  - referenced `multidatabackend.json` के अंदर की string values भी `{env:VAR_NAME}` support करती हैं
 - **Example**: उदाहरण कॉन्फ़िगरेशन के लिए [multidatabackend.json.example](/multidatabackend.json.example) देखें, और data loader कॉन्फ़िगर करने के लिए [यह दस्तावेज़](DATALOADER.md) देखें।
 
 ### `--override_dataset_config`
diff --git a/documentation/OPTIONS.ja.md b/documentation/OPTIONS.ja.md
@@ -451,6 +451,8 @@ Accelerate の既定値を使いたい項目は省略してください（例: 
   - 外部モデルビューア（ComfyUI、モデル情報ツール）で表示可能
   - 文字列または文字列配列（改行で結合）を受け付けます
   - 環境変数置換用の `{env:VAR_NAME}` プレースホルダをサポート
+  - メタデータ書き込み時に `{current_step}`、`{current_epoch}`、`{timestamp}` をサポート
+  - `{timestamp}` は UTC の ISO 8601 値です
   - 各チェックポイントは保存時の現在の設定値を使用
 
 **例（文字列）**:
@@ -477,6 +479,9 @@ Accelerate の既定値を使いたい項目は省略してください（例: 
 
 - **内容**: SimpleTuner データセット設定へのパス。
 - **理由**: 複数のストレージ媒体にあるデータセットを 1 つの学習セッションにまとめられます。
+- **注記**:
+  - `config.json` と `config.toml` から読み込まれる文字列値は `{env:VAR_NAME}` をサポート
+  - 参照先の `multidatabackend.json` 内の文字列値も `{env:VAR_NAME}` をサポート
 - **例**: 設定例は [multidatabackend.json.example](/multidatabackend.json.example) を参照し、データローダ設定の詳細は [このドキュメント](DATALOADER.md) を参照してください。
 
 ### `--override_dataset_config`
diff --git a/documentation/OPTIONS.md b/documentation/OPTIONS.md
@@ -450,6 +450,8 @@ This is useful for monitoring tools receiving webhooks from multiple training ru
   - Visible in external model viewers (ComfyUI, model info tools)
   - Accepts a string or array of strings (joined with newlines)
   - Supports `{env:VAR_NAME}` placeholders for environment variable substitution
+  - Supports `{current_step}`, `{current_epoch}`, and `{timestamp}` placeholders when metadata is written
+  - `{timestamp}` uses a UTC ISO 8601 value
   - Each checkpoint uses the current config value at save time
 
 **Example (string)**:
@@ -476,6 +478,9 @@ This is useful for monitoring tools receiving webhooks from multiple training ru
 
 - **What**: Path to your SimpleTuner dataset configuration.
 - **Why**: Multiple datasets on different storage medium may be combined into a single training session.
+- **Notes**:
+  - String values loaded from `config.json` and `config.toml` support `{env:VAR_NAME}`
+  - String values inside the referenced `multidatabackend.json` also support `{env:VAR_NAME}`
 - **Example**: See [multidatabackend.json.example](/multidatabackend.json.example) for an example configuration, and [this document](DATALOADER.md) for more information on configuring the data loader.
 
 ### `--override_dataset_config`
diff --git a/documentation/OPTIONS.pt-BR.md b/documentation/OPTIONS.pt-BR.md
@@ -449,6 +449,8 @@ Isso e util para ferramentas de monitoramento que recebem webhooks de varios tre
   - Visivel em visualizadores de modelo externos (ComfyUI, ferramentas de info de modelo)
   - Aceita uma string ou array de strings (unidas com quebras de linha)
   - Suporta placeholders `{env:VAR_NAME}` para substituicao de variaveis de ambiente
+  - Suporta `{current_step}`, `{current_epoch}` e `{timestamp}` quando o metadata e gravado
+  - `{timestamp}` usa um valor UTC em formato ISO 8601
   - Cada checkpoint usa o valor de configuracao atual no momento do salvamento
 
 **Exemplo (string)**:
@@ -475,6 +477,9 @@ Isso e util para ferramentas de monitoramento que recebem webhooks de varios tre
 
 - **O que**: Caminho para sua configuracao de dataset do SimpleTuner.
 - **Por que**: Multiplos datasets em midias diferentes podem ser combinados em uma unica sessao de treinamento.
+- **Notas**:
+  - Valores de string carregados de `config.json` e `config.toml` suportam `{env:VAR_NAME}`
+  - Valores de string dentro do `multidatabackend.json` referenciado tambem suportam `{env:VAR_NAME}`
 - **Exemplo**: Veja [multidatabackend.json.example](/multidatabackend.json.example) para um exemplo de configuracao e [este documento](DATALOADER.md) para mais informacoes sobre o data loader.
 
 ### `--override_dataset_config`
diff --git a/documentation/OPTIONS.zh.md b/documentation/OPTIONS.zh.md
@@ -453,6 +453,8 @@ TRAINING_DYNAMO_BACKEND=inductor
   - 在外部模型查看器（ComfyUI、模型信息工具）中可见
   - 接受字符串或字符串数组（用换行符连接）
   - 支持 `{env:VAR_NAME}` 占位符用于环境变量替换
+  - 在写入元数据时支持 `{current_step}`、`{current_epoch}` 和 `{timestamp}`
+  - `{timestamp}` 使用 UTC ISO 8601 值
   - 每个检查点使用保存时的当前配置值
 
 **示例（字符串）**：
@@ -479,6 +481,9 @@ TRAINING_DYNAMO_BACKEND=inductor
 
 - **内容**：SimpleTuner 数据集配置路径。
 - **原因**：可将不同存储介质上的多个数据集组合到同一训练会话中。
+- **说明**：
+  - 从 `config.json` 和 `config.toml` 读取的字符串值支持 `{env:VAR_NAME}`
+  - 被引用的 `multidatabackend.json` 内部字符串值也支持 `{env:VAR_NAME}`
 - **示例**：配置示例见 [multidatabackend.json.example](/multidatabackend.json.example)，更多信息见 [此文档](DATALOADER.md)。
 
 ### `--override_dataset_config`
diff --git a/documentation/quickstart/FLUX2.es.md b/documentation/quickstart/FLUX2.es.md
@@ -25,6 +25,8 @@ Para seleccionar una variante, configura `model_flavour` en tu configuración:
 }
 ```
 
+> **Importante**: Para `klein-4b` y `klein-9b`, deja `pretrained_text_encoder_model_name_or_path` sin definir a menos que realmente quieras reemplazar el codificador Qwen3 incluido. Si configuras ese campo, anulas el valor predeterminado de Klein y puedes provocar la descarga de otro codificador de texto.
+
 ## Resumen del modelo
 
 FLUX.2-dev introduce cambios arquitectónicos significativos respecto a FLUX.1:
diff --git a/documentation/quickstart/FLUX2.hi.md b/documentation/quickstart/FLUX2.hi.md
@@ -25,6 +25,8 @@ FLUX.2 तीन वेरिएंट में आता है:
 }
 ```
 
+> **महत्वपूर्ण**: `klein-4b` और `klein-9b` के लिए `pretrained_text_encoder_model_name_or_path` को unset छोड़ें, जब तक कि आप bundled Qwen3 text encoder को जानबूझकर बदलना न चाहते हों। इस field को सेट करने पर Klein का default override हो जाता है और किसी दूसरे text encoder का download शुरू हो सकता है।
+
 ## मॉडल ओवरव्यू
 
 FLUX.2-dev, FLUX.1 से बड़े आर्किटेक्चरल बदलाव लाता है:
diff --git a/documentation/quickstart/FLUX2.ja.md b/documentation/quickstart/FLUX2.ja.md
@@ -25,6 +25,8 @@ FLUX.2は3つのバリアントがあります:
 }
 ```
 
+> **重要**: `klein-4b` と `klein-9b` では、同梱のQwen3テキストエンコーダーを意図的に置き換えたい場合を除き、`pretrained_text_encoder_model_name_or_path` は設定しないでください。この項目を設定するとKleinのデフォルトを上書きし、別のテキストエンコーダーのダウンロードが発生することがあります。
+
 ## モデル概要
 
 FLUX.2-devはFLUX.1から大幅なアーキテクチャ変更を導入しています:
diff --git a/documentation/quickstart/FLUX2.md b/documentation/quickstart/FLUX2.md
@@ -25,6 +25,8 @@ To select a variant, set `model_flavour` in your config:
 }
 ```
 
+> **Important**: For `klein-4b` and `klein-9b`, leave `pretrained_text_encoder_model_name_or_path` unset unless you intentionally want to replace the bundled Qwen3 text encoder. Setting that field overrides the Klein default and can trigger downloads of a different text encoder.
+
 ## Model Overview
 
 FLUX.2-dev introduces significant architectural changes from FLUX.1:
diff --git a/documentation/quickstart/FLUX2.pt-BR.md b/documentation/quickstart/FLUX2.pt-BR.md
@@ -25,6 +25,8 @@ Para selecionar uma variante, defina `model_flavour` na sua configuração:
 }
 ```
 
+> **Importante**: Para `klein-4b` e `klein-9b`, deixe `pretrained_text_encoder_model_name_or_path` sem definir, a menos que você realmente queira substituir o encoder Qwen3 incluído. Ao definir esse campo, você sobrescreve o padrão do Klein e pode disparar o download de outro encoder de texto.
+
 ## Visão geral do modelo
 
 O FLUX.2-dev introduz mudanças arquiteturais significativas em relação ao FLUX.1:
diff --git a/documentation/quickstart/FLUX2.zh.md b/documentation/quickstart/FLUX2.zh.md
@@ -25,6 +25,8 @@ FLUX.2 有三个变体：
 }
 ```
 
+> **重要**：对于 `klein-4b` 和 `klein-9b`，除非你明确想替换内置的 Qwen3 文本编码器，否则不要设置 `pretrained_text_encoder_model_name_or_path`。设置这个字段会覆盖 Klein 的默认行为，并可能触发下载其他文本编码器。
+
 ## 模型概述
 
 FLUX.2-dev 相比 FLUX.1 引入了重大架构变化：
diff --git a/simpletuner/__init__.py b/simpletuner/__init__.py
@@ -123,4 +123,4 @@ def _suppress_swigvarlink(message, *args, **kwargs):
 warnings.warn = _suppress_swigvarlink
 
 
-__version__ = "4.1.2"
+__version__ = "4.1.3"
diff --git a/simpletuner/helpers/configuration/cli_utils.py b/simpletuner/helpers/configuration/cli_utils.py
@@ -5,6 +5,8 @@
 from collections.abc import Iterable, Mapping
 from typing import Callable, Optional
 
+from simpletuner.helpers.configuration.template_vars import resolve_value_placeholders
+
 TransformFunc = Optional[Callable[[str, object], object]]
 
 
@@ -198,7 +200,8 @@ def mapping_to_cli_args(
             if field is not None and getattr(field, "arg_name", "NOT_NONE") is None:
                 continue
 
-        value = transform(key, raw_value) if transform else raw_value
+        resolved_value = resolve_value_placeholders(raw_value)
+        value = transform(key, resolved_value) if transform else resolved_value
 
         canonical_key = key.lstrip("-") if isinstance(key, str) else key
         handler = _LEGACY_ARG_HANDLERS.get(canonical_key)
diff --git a/simpletuner/helpers/configuration/cmd_args.py b/simpletuner/helpers/configuration/cmd_args.py
@@ -17,6 +17,7 @@
 from accelerate.utils import ProjectConfiguration
 
 from simpletuner.helpers.configuration.cli_utils import mapping_to_cli_args, normalize_lr_scheduler_value
+from simpletuner.helpers.configuration.template_vars import render_modelspec_comment
 from simpletuner.helpers.logging import get_logger
 from simpletuner.helpers.training.attention_backend import (
     AttentionBackendMode,
@@ -212,35 +213,7 @@ def _parse_json_like_option(raw_value, option_name: str):
 
 def _process_modelspec_comment(value) -> str | None:
     """Process modelspec_comment: handle array, JSON string, env placeholders."""
-    if value is None:
-        return None
-
-    # If it's a string that looks like JSON array, parse it first
-    if isinstance(value, str):
-        stripped = value.strip()
-        if stripped.startswith("[") and stripped.endswith("]"):
-            try:
-                parsed = json.loads(stripped)
-                if isinstance(parsed, list):
-                    value = parsed
-            except (json.JSONDecodeError, ValueError):
-                pass  # Not valid JSON, treat as regular string
-
-    if isinstance(value, list):
-        value = "\n".join(str(item) for item in value)
-    elif not isinstance(value, str):
-        value = str(value)
-
-    value = value.strip()
-    if not value:
-        return None
-
-    def replace_env(match):
-        var_name = match.group(1)
-        return os.environ.get(var_name, "")
-
-    value = re.sub(r"\{env:([^}]+)\}", replace_env, value)
-    return value or None
+    return render_modelspec_comment(value)
 
 
 def _contains_ast_markers(candidate: str) -> bool:
diff --git a/simpletuner/helpers/configuration/env_file.py b/simpletuner/helpers/configuration/env_file.py
@@ -88,6 +88,7 @@
 import os
 import subprocess
 
+from simpletuner.helpers.configuration.template_vars import resolve_string_placeholders
 from simpletuner.helpers.training.multi_process import should_log
 
 logger = logging.getLogger("SimpleTuner")
@@ -199,6 +200,8 @@ def load_env_config():
             value = value[1:-1]
         if value is not None and value.startswith('"') and value.endswith('"'):
             value = value[1:-1]
+        if isinstance(value, str):
+            value = resolve_string_placeholders(value)
         try:
             float(value)
             is_numeric = True
diff --git a/simpletuner/helpers/configuration/template_vars.py b/simpletuner/helpers/configuration/template_vars.py
@@ -0,0 +1,82 @@
+import json
+import os
+import re
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from typing import Any
+
+from simpletuner.helpers.training.state_tracker import StateTracker
+
+_PLACEHOLDER_PATTERN = re.compile(r"\{([^{}]+)\}")
+
+
+def resolve_string_placeholders(value: str, *, variables: Mapping[str, object] | None = None) -> str:
+    """Resolve supported placeholders in a string value."""
+
+    if not isinstance(value, str):
+        return value
+
+    def _replace(match: re.Match[str]) -> str:
+        token = match.group(1)
+        if token.startswith("env:"):
+            return os.environ.get(token[4:], "")
+        if variables is not None and token in variables:
+            resolved = variables[token]
+            return "" if resolved is None else str(resolved)
+        return match.group(0)
+
+    return _PLACEHOLDER_PATTERN.sub(_replace, value)
+
+
+def resolve_value_placeholders(value: Any, *, variables: Mapping[str, object] | None = None) -> Any:
+    """Recursively resolve placeholders in strings nested inside lists and dicts."""
+
+    if isinstance(value, str):
+        return resolve_string_placeholders(value, variables=variables)
+    if isinstance(value, list):
+        return [resolve_value_placeholders(item, variables=variables) for item in value]
+    if isinstance(value, tuple):
+        return tuple(resolve_value_placeholders(item, variables=variables) for item in value)
+    if isinstance(value, dict):
+        return {key: resolve_value_placeholders(item, variables=variables) for key, item in value.items()}
+    return value
+
+
+def render_modelspec_comment(value: Any, *, variables: Mapping[str, object] | None = None) -> str | None:
+    """Normalize and render a modelspec comment value."""
+
+    if value is None:
+        return None
+
+    if isinstance(value, str):
+        stripped = value.strip()
+        if stripped.startswith("[") and stripped.endswith("]"):
+            try:
+                parsed = json.loads(stripped)
+                if isinstance(parsed, list):
+                    value = parsed
+            except (json.JSONDecodeError, ValueError):
+                pass
+
+    if isinstance(value, list):
+        value = "\n".join(str(item) for item in value)
+    elif not isinstance(value, str):
+        value = str(value)
+
+    value = value.strip()
+    if not value:
+        return None
+
+    value = resolve_string_placeholders(value, variables=variables)
+    return value or None
+
+
+def build_modelspec_template_values(now: datetime | None = None) -> dict[str, str]:
+    """Build dynamic template values for modelspec metadata expansion."""
+
+    timestamp = now or datetime.now(tz=timezone.utc)
+    return {
+        "current_step": str(StateTracker.get_global_step()),
+        "current_epoch": str(StateTracker.get_epoch()),
+        "timestamp": timestamp.isoformat(),
+    }
diff --git a/simpletuner/helpers/data_backend/factory.py b/simpletuner/helpers/data_backend/factory.py
@@ -76,6 +76,7 @@ def _coerce_bucket_keys(indices: Dict[Any, Iterable]) -> Dict[Any, list]:
 from simpletuner.helpers.caching.image_embed import ImageEmbedCache
 from simpletuner.helpers.caching.text_embeds import TextEmbeddingCache
 from simpletuner.helpers.caching.vae import VAECache
+from simpletuner.helpers.configuration.template_vars import resolve_value_placeholders
 from simpletuner.helpers.data_backend.aws import S3DataBackend
 from simpletuner.helpers.data_backend.base import BaseDataBackend
 from simpletuner.helpers.data_backend.bucket_report import BucketReport
@@ -1071,17 +1072,6 @@ def fill_variables_in_config_paths(args: dict, config: list[dict]) -> dict:
     if not output_dir:
         output_dir = os.path.join(os.getcwd(), ".simpletuner_output")
 
-    def _fill(value, mapping):
-        if isinstance(value, str):
-            for var_name, var_value in mapping.items():
-                value = value.replace(var_name, str(var_value))
-            return value
-        if isinstance(value, dict):
-            return {key: _fill(val, mapping) for key, val in value.items()}
-        if isinstance(value, list):
-            return [_fill(item, mapping) for item in value]
-        return value
-
     filled_config: list[dict] = []
     for backend in config:
         dataset_id = ""
@@ -1090,11 +1080,11 @@ def _fill(value, mapping):
         except Exception:
             dataset_id = ""
         mapping = {
-            "{model_family}": model_family,
-            "{output_dir}": output_dir,
-            "{id}": dataset_id,
+            "model_family": model_family,
+            "output_dir": output_dir,
+            "id": dataset_id,
         }
-        filled_config.append(_fill(backend, mapping))
+        filled_config.append(resolve_value_placeholders(backend, variables=mapping))
 
     return filled_config
 
diff --git a/simpletuner/helpers/models/common.py b/simpletuner/helpers/models/common.py
diff --git a/simpletuner/helpers/training/save_hooks.py b/simpletuner/helpers/training/save_hooks.py
diff --git a/simpletuner/helpers/training/trainer.py b/simpletuner/helpers/training/trainer.py
diff --git a/simpletuner/simpletuner_sdk/server/services/field_registry/sections/publishing.py b/simpletuner/simpletuner_sdk/server/services/field_registry/sections/publishing.py
diff --git a/tests/test_config_templates.py b/tests/test_config_templates.py
diff --git a/tests/test_lora_metadata.py b/tests/test_lora_metadata.py
diff --git a/tests/test_sdxl_single_file_loading.py b/tests/test_sdxl_single_file_loading.py

Original file line number	Diff line number	Diff line change
@@ -25,6 +25,8 @@ Para seleccionar una variante, configura `model_flavour` en tu configuración:
`25`	`25`	`}`
`26`	`26`	```
`27`	`27`
	`28`	+> Importante: Para `klein-4b` y `klein-9b`, deja `pretrained_text_encoder_model_name_or_path` sin definir a menos que realmente quieras reemplazar el codificador Qwen3 incluido. Si configuras ese campo, anulas el valor predeterminado de Klein y puedes provocar la descarga de otro codificador de texto.
	`29`	`+`
`28`	`30`	`## Resumen del modelo`
`29`	`31`
`30`	`32`	`FLUX.2-dev introduce cambios arquitectónicos significativos respecto a FLUX.1:`
Original file line number	Diff line number	Diff line change
`@@ -25,6 +25,8 @@ FLUX.2 तीन वेरिएंट में आता है:`
`25`	`25`	`}`
`26`	`26`	```
`27`	`27`
	`28`	+> महत्वपूर्ण: `klein-4b` और `klein-9b` के लिए `pretrained_text_encoder_model_name_or_path` को unset छोड़ें, जब तक कि आप bundled Qwen3 text encoder को जानबूझकर बदलना न चाहते हों। इस field को सेट करने पर Klein का default override हो जाता है और किसी दूसरे text encoder का download शुरू हो सकता है।
	`29`	`+`
`28`	`30`	`## मॉडल ओवरव्यू`
`29`	`31`
`30`	`32`	`FLUX.2-dev, FLUX.1 से बड़े आर्किटेक्चरल बदलाव लाता है:`
Original file line number	Diff line number	Diff line change
`@@ -25,6 +25,8 @@ FLUX.2は3つのバリアントがあります:`
`25`	`25`	`}`
`26`	`26`	```
`27`	`27`
	`28`	+> 重要: `klein-4b` と `klein-9b` では、同梱のQwen3テキストエンコーダーを意図的に置き換えたい場合を除き、`pretrained_text_encoder_model_name_or_path` は設定しないでください。この項目を設定するとKleinのデフォルトを上書きし、別のテキストエンコーダーのダウンロードが発生することがあります。
	`29`	`+`
`28`	`30`	`## モデル概要`
`29`	`31`
`30`	`32`	`FLUX.2-devはFLUX.1から大幅なアーキテクチャ変更を導入しています:`
Original file line number	Diff line number	Diff line change
@@ -25,6 +25,8 @@ To select a variant, set `model_flavour` in your config:
`25`	`25`	`}`
`26`	`26`	```
`27`	`27`
	`28`	+> Important: For `klein-4b` and `klein-9b`, leave `pretrained_text_encoder_model_name_or_path` unset unless you intentionally want to replace the bundled Qwen3 text encoder. Setting that field overrides the Klein default and can trigger downloads of a different text encoder.
	`29`	`+`
`28`	`30`	`## Model Overview`
`29`	`31`
`30`	`32`	`FLUX.2-dev introduces significant architectural changes from FLUX.1:`