Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: random flip opt-in, plus checkpoint retention, caption dropout, LoRA dropout and timestep shift on the image Train tab (#13210)

Daniel Handaf65abe7587
diff --git a/studio/backend/core/training/diffusion_train_common.py b/studio/backend/core/training/diffusion_train_common.py
index 3072b282d64..38041f2a2b0 100644
--- a/studio/backend/core/training/diffusion_train_common.py
+++ b/studio/backend/core/training/diffusion_train_common.py
@@ -1012,7 +1012,8 @@ class DiffusionLoraConfig:
lr_scheduler: str = "constant"
lr_warmup_steps: int = 0
center_crop: bool = False
- random_flip: bool = True
+ # Off by default: flipping mirrors text, logos and one-sided features in half the samples.
+ random_flip: bool = False
caption_column: str = "text"
adapter_name: str = "default"
hf_token: Optional[str] = None
@@ -1579,8 +1580,7 @@ def h3_train_unsupported_reason(cfg: Any) -> Optional[str]:
return None
-# These have a DEFAULT the H3 loop disagrees with, so they are normalised rather than refused (which would 422 every
-# untouched request): one centre cover-crop, nothing flipped, a plain unweighted MSE, and exactly one cached tuple.
+# Normalised, not refused: several are request defaults, refusing would 422 every untouched request.
_H3_FIXED_RECIPE: dict[str, Any] = {
"center_crop": True,
"random_flip": False,
diff --git a/studio/backend/models/training.py b/studio/backend/models/training.py
index 0d04315f019..87d36344a05 100644
--- a/studio/backend/models/training.py
+++ b/studio/backend/models/training.py
@@ -974,7 +974,10 @@ class DiffusionTrainingStartRequest(BaseModel):
] = Field("constant")
lr_warmup_steps: int = Field(0, ge = 0)
center_crop: bool = Field(False)
- random_flip: bool = Field(True)
+ # Opt-in: mirroring teaches text, logos and one-sided features in both orientations.
+ random_flip: bool = Field(
+ False, description = "Randomly mirror training images left-right (augmentation)"
+ )
caption_column: str = Field("text")
hf_token: Optional[str] = Field(None)
cache_latents: bool = Field(
diff --git a/studio/backend/tests/test_diffusion_checkpoint_resume.py b/studio/backend/tests/test_diffusion_checkpoint_resume.py
index 08f40eea689..05978bb9abf 100644
--- a/studio/backend/tests/test_diffusion_checkpoint_resume.py
+++ b/studio/backend/tests/test_diffusion_checkpoint_resume.py
@@ -1996,7 +1996,7 @@ def test_the_identity_covers_the_input_stream(run_dir):
("cache_latents", False, "latent caching"),
("cache_variants", 8, "cached crop variants"),
("center_crop", True, "centre cropping"),
- ("random_flip", False, "random flipping"),
+ ("random_flip", True, "random flipping"),
):
changed_cfg = dataclasses.replace(base.cfg, **{field: value})
reason = dc.identity_for_config(base.cfg).mismatch_reason(
@@ -2009,8 +2009,9 @@ def test_the_identity_covers_the_input_stream(run_dir):
assert older is not None
assert older.mismatch_reason(dc.identity_for_config(changed_cfg)) is None, field
# False is a VALUE, not an unknown: the flags are recorded as on/off for exactly that.
- flipped = dataclasses.replace(base.cfg, random_flip = False)
- assert dc.identity_for_config(flipped).random_flip == "off"
+ assert dc.identity_for_config(base.cfg).random_flip == "off"
+ flipped = dataclasses.replace(base.cfg, random_flip = True)
+ assert dc.identity_for_config(flipped).random_flip == "on"
def test_the_identity_covers_the_update_shape_and_the_resolution(run_dir):
diff --git a/studio/backend/tests/test_diffusion_h3_trainer.py b/studio/backend/tests/test_diffusion_h3_trainer.py
index 8bd5019e015..e322ea6b2f9 100644
--- a/studio/backend/tests/test_diffusion_h3_trainer.py
+++ b/studio/backend/tests/test_diffusion_h3_trainer.py
@@ -1128,9 +1128,9 @@ def test_the_h3_preflight_runs_before_the_start_route_evicts_anything():
def test_the_augmentation_knobs_record_what_h3_actually_does():
- """Every frame goes through the same centre cover-crop and nothing is flipped, but the
- schema defaults say the opposite (center_crop=False, random_flip=True), so an untouched
- request described augmentation that never happened. Normalised rather than refused: a
+ """Every frame goes through the same centre cover-crop and nothing is flipped, but a request
+ can say otherwise (center_crop defaults to False, random_flip can be turned on), so the run
+ record described augmentation that never happened. Normalised rather than refused: a
refusal would 422 every default request."""
from dataclasses import replace as _replace
diff --git a/studio/backend/tests/test_diffusion_train_perf.py b/studio/backend/tests/test_diffusion_train_perf.py
index 27bb065178d..ff72ff64ec0 100644
--- a/studio/backend/tests/test_diffusion_train_perf.py
+++ b/studio/backend/tests/test_diffusion_train_perf.py
@@ -57,6 +57,23 @@ def _cfg(**kw) -> DiffusionLoraConfig:
# ── _plan_cache_variants (pure, seed-deterministic) ───────────────────────────
+def test_random_flip_is_opt_in():
+ assert DiffusionLoraConfig.random_flip is False
+ req = DiffusionTrainingStartRequest(base_model = _SDXL, data_dir = "d", output_dir = "o")
+ assert req.random_flip is False
+ cfg = DiffusionLoraConfig(
+ **req.model_dump(include = {"base_model", "data_dir", "output_dir", "random_flip"})
+ )
+ plan = _plan_cache_variants(5, 4, cfg.center_crop, cfg.random_flip, cfg.seed)
+ assert not any(flip for variants in plan for (_, _, flip) in variants)
+ assert (
+ DiffusionTrainingStartRequest(
+ base_model = _SDXL, data_dir = "d", output_dir = "o", random_flip = True
+ ).random_flip
+ is True
+ )
+
+
def test_plan_cache_variants_deterministic_and_deduped():
# Same seed gives a byte-identical plan (its own rng stream, so it is fully reproducible).
p1 = _plan_cache_variants(3, 4, center_crop = False, random_flip = True, seed = 123)
diff --git a/studio/frontend/src/features/images/api.ts b/studio/frontend/src/features/images/api.ts
index c5a0c40da55..be24d45cdfa 100644
--- a/studio/frontend/src/features/images/api.ts
+++ b/studio/frontend/src/features/images/api.ts
@@ -609,6 +609,12 @@ export interface DiffusionTrainingStartRequest {
seed?: number;
mixed_precision?: "bf16" | "fp16" | "no";
gradient_checkpointing?: boolean;
+ random_flip?: boolean;
+ // Chance of training a sample on the empty prompt (DiT families; MiniMax-H3 refuses it). 0 when omitted.
+ cfg_dropout?: number;
+ lora_dropout?: number;
+ // Not sdxl. "auto" = family inference schedule; omitted = family default.
+ flow_shift?: number | "auto";
lr_scheduler?: string;
lr_warmup_steps?: number;
// DiT-family quantised base precision (nf4 QLoRA by default). Ignored for sdxl, which uses mixed_precision.
diff --git a/studio/frontend/src/features/images/train/diffusion-train-panel.tsx b/studio/frontend/src/features/images/train/diffusion-train-panel.tsx
index d9d65d544b3..2e503704d67 100644
--- a/studio/frontend/src/features/images/train/diffusion-train-panel.tsx
+++ b/studio/frontend/src/features/images/train/diffusion-train-panel.tsx
@@ -426,6 +426,10 @@ export function DiffusionTrainPanel({
// sdxl trains the U-Net in mixed precision, so it uses mixed_precision instead of base_precision.
// Everything else is a DiT family.
const isDiT = familyName !== "sdxl";
+ const isH3 = familyName === "minimax-h3";
+ const supportsCfgDropout = isDiT && !isH3;
+ // H3 shifts its video and audio schedules separately and applies a number to video only: no shared control.
+ const supportsFlowShift = isDiT && !isH3;
// An EMPTY precision_modes list on a DiT family means this host cannot train it at all (the reason rides in
// vram_note); only an ABSENT field means an older backend. SDXL reports [] too but is not precision-gated,
// hence the isDiT scope.
@@ -498,12 +502,21 @@ export function DiffusionTrainPanel({
// Periodic resume points. 0 (off) keeps the default: only a stop-and-save writes one, so nothing
// is spent on disk unless asked.
const [saveSteps, setSaveSteps] = useState(0);
+ // 0 keeps every checkpoint; backend default 2.
+ const [saveTotalLimit, setSaveTotalLimit] = useState(2);
// LR schedule. Warmup applies only to non-constant schedules. Seeded from the family, which is
// where the flow-matching DiTs' short ramp comes from.
const [lrScheduler, setLrScheduler] = useState<LrScheduler>("constant");
const [lrWarmupSteps, setLrWarmupSteps] = useState(0);
// Gradient checkpointing trades ~20-30% step time for a large activation-VRAM saving.
const [gradCheckpoint, setGradCheckpoint] = useState(true);
+ const [randomFlip, setRandomFlip] = useState(false);
+ // Only the DiT loops read it, and MiniMax-H3 refuses it: it has no unconditional branch to train.
+ const [cfgDropout, setCfgDropout] = useState(0);
+ const [loraDropout, setLoraDropout] = useState(0);
+ // "default" sends nothing, so each family keeps its own default.
+ const [flowShiftMode, setFlowShiftMode] = useState<"default" | "custom">("default");
+ const [flowShift, setFlowShift] = useState(3);
// sdxl (U-Net) trains in a mixed-precision autocast; the DiT families quantise the frozen base
// weights and ignore this.
const [precision, setPrecision] = useState<"bf16" | "fp16" | "no">("bf16");
@@ -1147,6 +1160,15 @@ export function DiffusionTrainPanel({
if (gradAccum < 1) return toast.error("Gradient accumulation must be at least 1.");
if (learningRate <= 0) return toast.error("Learning rate must be greater than 0.");
if (lrWarmupSteps < 0) return toast.error("Warmup steps cannot be negative.");
+ if (supportsCfgDropout && !(cfgDropout >= 0 && cfgDropout <= 1)) {
+ return toast.error("Caption dropout must be between 0 and 1.");
+ }
+ if (!(loraDropout >= 0 && loraDropout < 1)) {
+ return toast.error("LoRA dropout must be at least 0 and below 1.");
+ }
+ if (supportsFlowShift && flowShiftMode === "custom" && !(flowShift > 0)) {
+ return toast.error("Timestep shift must be greater than 0.");
+ }
setStarting(true);
// A previous run's confirmed stop must not leak into this run: the read-time clamp would re-arm a
// permanently disabled "Stopping..." button.
@@ -1173,12 +1195,17 @@ export function DiffusionTrainPanel({
gradient_accumulation_steps: gradAccum,
seed,
gradient_checkpointing: gradCheckpoint,
+ random_flip: randomFlip,
lr_scheduler: lrScheduler,
lr_warmup_steps: lrScheduler === "constant" ? 0 : lrWarmupSteps,
lora_rank: rank,
// Zero rather than the field's value when the family has none: the field is only hidden, not
// reset, so a value typed for one family would otherwise still be sent and refused.
save_steps: supportsCheckpoints ? Math.max(0, Math.floor(saveSteps)) : 0,
+ save_total_limit: supportsCheckpoints ? Math.max(0, Math.floor(saveTotalLimit)) : undefined,
+ cfg_dropout: supportsCfgDropout ? cfgDropout : undefined,
+ lora_dropout: loraDropout,
+ flow_shift: supportsFlowShift && flowShiftMode === "custom" ? flowShift : undefined,
mixed_precision: precision,
// DiT families quantise the base weights; sdxl uses mixed_precision above and ignores this. Only
// send compile where supported.
@@ -1211,7 +1238,15 @@ export function DiffusionTrainPanel({
gradAccum,
seed,
saveSteps,
+ saveTotalLimit,
gradCheckpoint,
+ randomFlip,
+ cfgDropout,
+ supportsCfgDropout,
+ loraDropout,
+ flowShiftMode,
+ flowShift,
+ supportsFlowShift,
lrScheduler,
lrWarmupSteps,
rank,
@@ -1313,6 +1348,8 @@ export function DiffusionTrainPanel({
});
}, [status, effectiveBase, customBase, family, instancePrompt, onDeploy, deployBaseFor]);
+ // For fields no family seeds: editing one must not stop a family switch from reseeding rank / LR / resolution.
+ const keepFamilyDefaults = () => {};
const numberField = (
label: string,
value: number,
@@ -1437,6 +1474,13 @@ export function DiffusionTrainPanel({
min: 0,
hint: "Saves a resume point every this many steps, so a crash or a shutdown can be picked up where it left off. 0 turns it off; stopping and saving always leaves one either way.",
})}
+ {supportsCheckpoints &&
+ saveSteps > 0 &&
+ numberField("Keep checkpoints", saveTotalLimit, setSaveTotalLimit, 2, {
+ min: 0,
+ markDirty: keepFamilyDefaults,
+ hint: "How many of those checkpoints stay on disk; older ones are deleted as new ones are saved. Raise it to compare earlier steps. 0 keeps every one.",
+ })}
</div>
<div className="grid grid-cols-1 items-start gap-x-6 gap-y-5 @min-[324px]:grid-cols-2 @min-[498px]:grid-cols-3">
@@ -1500,6 +1544,66 @@ export function DiffusionTrainPanel({
</Select>
</div>
+ {!isH3 && (
+ <div className={fieldClass}>
+ <FieldLabel hint="Mirrors images left-right at random for extra variety. Leave off for text, logos or subjects with one-sided features (a side parting, a scar); try on for styles and symmetric subjects.">
+ Random flip
+ </FieldLabel>
+ <Select
+ value={randomFlip ? "on" : "off"}
+ onValueChange={(v) => setRandomFlip(v === "on")}
+ >
+ <SelectTrigger className={selectClass} aria-label="Random flip">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ <SelectItem value="off">Off</SelectItem>
+ <SelectItem value="on">On (mirror images)</SelectItem>
+ </SelectContent>
+ </Select>
+ </div>
+ )}
+ {supportsCfgDropout &&
+ numberField("Caption dropout", cfgDropout, setCfgDropout, 0, {
+ min: 0,
+ markDirty: keepFamilyDefaults,
+ step: 0.05,
+ hint: "The chance each image trains with an empty prompt instead of its caption. 0.05 to 0.1 can help a LoRA respond to guidance (CFG) without overfitting to the exact caption; 0 turns it off.",
+ })}
+ {numberField("LoRA dropout", loraDropout, setLoraDropout, 0, {
+ min: 0,
+ markDirty: keepFamilyDefaults,
+ step: 0.05,
+ hint: "Randomly drops part of the LoRA's input each step, a light guard against memorising a small dataset. 0 (off) is the usual choice; try 0.05 to 0.1 if results copy the training images too closely.",
+ })}
+ {supportsFlowShift && (
+ <div className={fieldClass}>
+ <FieldLabel hint="Which noise levels training spends its steps on. Default follows the model's own schedule (Qwen-Image and LTX-2 match the one they generate with). Custom sets the shift directly: higher favours composition and layout, lower fine detail.">
+ Timestep shift
+ </FieldLabel>
+ <Select
+ value={flowShiftMode}
+ onValueChange={(v) => setFlowShiftMode(v as "default" | "custom")}
+ >
+ <SelectTrigger className={selectClass} aria-label="Timestep shift">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ <SelectItem value="default">Default</SelectItem>
+ <SelectItem value="custom">Custom</SelectItem>
+ </SelectContent>
+ </Select>
+ </div>
+ )}
+ {supportsFlowShift &&
+ flowShiftMode === "custom" &&
+ numberField("Shift value", flowShift, setFlowShift, 3, {
+ min: 0.1,
+ step: 0.5,
+ markDirty: keepFamilyDefaults,
+ hint: "1 is no shift; around 3 suits most image models.",
+ })}
+
{isDiT ? (
<div className={fieldClass}>
<FieldLabel hint="How the frozen base is quantised while the LoRA trains. Auto picks the best fit for your GPU; nf4 uses the least VRAM.">