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: per-model automatic step skip at each model's measured step count (1.44 to 1.81x, MiniMax-H3 on max) (#12652)

Daniel Han341f5baec6cc
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 8185dc78c83..927aa3ba291 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -215,7 +215,9 @@ from .diffusion_cache import (
TC_AUTO,
TC_STATIC,
apply_step_cache,
+ auto_static_skip_plan,
auto_step_cache_allowed,
+ skip_tier,
cache_breaks_graph,
effective_denoise_steps,
effective_request_strength,
@@ -225,9 +227,11 @@ from .diffusion_cache import (
step_cache_supported,
)
from .diffusion_step_skip import (
+ auto_static_settings,
install_static_step_skip,
mark_step_end,
reset_static_step_skip,
+ static_skip_is_auto,
static_skip_stats,
static_skip_view,
uninstall_static_step_skip,
@@ -1055,6 +1059,8 @@ class _LoadState:
eager_patched: bool = False
# Deferred speed auto: the load stays eager, generate() engages `default` at the 3rd generation
speed_deferred: bool = False
+ # Auto static skip plan for that deferred `default` tier, installed when it engages.
+ deferred_static_plan: Optional[dict] = None
# Successful generations on this load; drives the deferred engagement above.
generation_count: int = 0
# Pre-warmed torch.compile cache context when a compiled tier ran, else None.
@@ -6916,15 +6922,33 @@ class DiffusionBackend:
gguf_filename
)
default_steps: Optional[int] = None
+ static_plan: Optional[dict] = None
if cache_auto:
default_steps, _ = default_generation_params(
gguf_filename, repo_id, base, fam.name
)
- cache_request = resolve_auto_step_cache(effective_speed, default_steps)
+ static_plan = auto_static_skip_plan(
+ (repo_id, base), skip_tier(speed_mode, effective_speed), default_steps
+ )
+ cache_request = resolve_auto_step_cache(
+ effective_speed, default_steps, static_plan = static_plan
+ )
+ cache_engaged = None
if cache_request == TC_STATIC:
- # Explicit only: auto never resolves to static.
- cache_engaged = install_static_step_skip(pipe, logger = logger)
- else:
+ cache_engaged = (
+ install_static_step_skip(
+ pipe,
+ settings = auto_static_settings(static_plan, logger = logger),
+ logger = logger,
+ )
+ if static_plan
+ else install_static_step_skip(pipe, logger = logger)
+ )
+ if cache_engaged is None and static_plan:
+ # Declined (second denoiser, no forward): auto falls back to what it picked before.
+ static_plan = None
+ cache_request = resolve_auto_step_cache(effective_speed, default_steps)
+ if cache_request != TC_STATIC:
cache_engaged = apply_step_cache(
pipe,
mode = cache_request,
@@ -6936,15 +6960,37 @@ class DiffusionBackend:
length_changes_ok = not cache_auto,
logger = logger,
)
+ # Speed unset on a dense load: `default` engages on the 3rd image, and the skip with it.
+ deferred_static_plan = (
+ auto_static_skip_plan((repo_id, base), SPEED_DEFAULT, default_steps)
+ if cache_auto and speed_deferred and cache_engaged is None
+ else None
+ )
cache_graph_break = cache_breaks_graph(cache_engaged)
self._raise_if_load_cancelled(_load_token)
# Arm only where FBCache can engage: a live toggle drops fullgraph and retries every generation.
- cache_may_toggle = cache_auto_live and (
- cache_engaged is not None
- or (cache_request is None and step_cache_supported(pipe, logger = logger))
+ cache_may_toggle = (
+ cache_auto_live
+ and cache_engaged != TC_STATIC
+ and (
+ cache_engaged is not None
+ or (cache_request is None and step_cache_supported(pipe, logger = logger))
+ )
)
if cache_auto:
- if not cache_auto_live:
+ if cache_engaged == TC_STATIC:
+ cache_reason = (
+ f"auto: static step skip (every {static_plan['every']}) for this model "
+ f"at {static_plan['min_steps']}+ steps; set "
+ "UNSLOTH_DIFFUSION_AUTO_STEP_SKIP=0 to turn it off"
+ )
+ elif deferred_static_plan:
+ cache_reason = (
+ f"auto: static step skip (every {deferred_static_plan['every']}) engages "
+ "with the compiled profile on the 3rd image; set "
+ "UNSLOTH_DIFFUSION_AUTO_STEP_SKIP=0 to turn it off"
+ )
+ elif not cache_auto_live:
# Only name the max tier where it would help: SDXL / LTX-2 never cache on any tier.
cache_reason = (
"auto: step caching engages on the max speed tier only"
@@ -7387,6 +7433,7 @@ class DiffusionBackend:
cache_threshold = transformer_cache_threshold,
eager_patched = eager_patched,
speed_deferred = speed_deferred,
+ deferred_static_plan = deferred_static_plan,
compile_cache_ctx = compile_ctx,
bg_compile = load_bg_compile,
hf_token = hf_token,
@@ -9044,6 +9091,42 @@ class DiffusionBackend:
pass
def _engage_deferred_speed(self, state: _LoadState) -> None:
+ """The deferred `default` profile plus its auto static skip; a failed profile takes the skip back off."""
+ object.__setattr__(state, "speed_deferred", False)
+ plan = state.deferred_static_plan
+ object.__setattr__(state, "deferred_static_plan", None)
+ tc = (state.resolved or {}).get("transformer_cache")
+ tc_before = dict(tc) if isinstance(tc, dict) else None
+ installed = False
+ # Before compile, as at load: the skip is an outer forward on the transformer.
+ if plan and state.transformer_cache is None:
+ installed = (
+ install_static_step_skip(
+ state.pipe, settings = auto_static_settings(plan, logger = logger), logger = logger
+ )
+ == TC_STATIC
+ )
+ if installed:
+ object.__setattr__(state, "transformer_cache", TC_STATIC)
+ if isinstance(tc, dict):
+ tc["value"] = TC_STATIC
+ tc["reason"] = (
+ f"auto: static step skip (every {plan['every']}) for this model at "
+ f"{plan['min_steps']}+ steps, engaged with the compiled profile; set "
+ "UNSLOTH_DIFFUSION_AUTO_STEP_SKIP=0 to turn it off"
+ )
+ try:
+ self._engage_deferred_profile(state)
+ except BaseException:
+ if installed:
+ uninstall_static_step_skip(state.pipe)
+ object.__setattr__(state, "transformer_cache", None)
+ if isinstance(tc, dict) and tc_before is not None:
+ tc.clear()
+ tc.update(tc_before)
+ raise
+
+ def _engage_deferred_profile(self, state: _LoadState) -> None:
"""Engage the deferred `default` speed profile at the start of the 3rd generation this
session. The load left the pipe fully eager (bit-identical reference); by the 3rd image
repeated use is established, so pay the one-time compile now: eager patches + attention
@@ -9766,9 +9849,14 @@ class DiffusionBackend:
state.cuda_graphs, cache_breaks_graph(state.transformer_cache)
)
if static_skip:
+ # Auto skip was measured on txt2img only; explicit "static" applies to every workflow.
+ auto_only_txt2img = workflow != "txt2img" and static_skip_is_auto(
+ state.pipe
+ )
reset_static_step_skip(
state.pipe,
denoise_steps,
+ compute_all = auto_only_txt2img,
step_signal = "callback_on_step_end" in chunk_kwargs,
keep_stats = static_chunks_run > 0,
owner = current_account_id(),
diff --git a/studio/backend/core/inference/diffusion_cache.py b/studio/backend/core/inference/diffusion_cache.py
index d86d33e22b9..e7797fa59ed 100644
--- a/studio/backend/core/inference/diffusion_cache.py
+++ b/studio/backend/core/inference/diffusion_cache.py
@@ -24,7 +24,7 @@ from typing import Any, Optional
TC_OFF = "off"
TC_AUTO = "auto"
TC_FBCACHE = "fbcache"
-# Fixed-schedule step skip (diffusion_step_skip.py); explicit opt-in only, auto never picks it.
+# Fixed-schedule step skip (diffusion_step_skip.py); explicit, or auto for the measured families below.
TC_STATIC = "static"
TC_MODES = (TC_FBCACHE, TC_STATIC)
@@ -44,12 +44,104 @@ AUTO_STEP_CACHE_TIER = "max"
_REDUCTION_FILTER_OPTION = "test_configs.force_filter_reduction_configs"
+_TIER_DEFAULT = "default"
+_TIER_MAX = "max"
+
+# Per-model interval on each tier ("default" also covers max), measured vs the no-skip render (PR #12652): default
+# needs mean LPIPS <= 0.05, max <= 0.10. "steps" = the step count it was measured at: fewer steps compute every step.
+# Keyed by the UPSTREAM repo id so distilled / unmeasured siblings never match.
+AUTO_STATIC_SKIP: dict = {
+ "qwen/qwen-image-2.1": {"default": 3, "max": 3, "steps": 25},
+ "qwen/qwen-image": {"default": 2, "max": 3, "steps": 20},
+ "black-forest-labs/flux.1-krea-dev": {"default": 2, "max": 3, "steps": 28},
+ "black-forest-labs/flux.2-klein-base-4b": {"default": 2, "max": 3, "steps": 50},
+ "wan-ai/wan2.2-ti2v-5b-diffusers": {"default": 2, "max": 3, "steps": 50},
+ # every 2 is 0.29 LPIPS on a dense-texture prompt, so max only.
+ "black-forest-labs/flux.1-dev": {"max": 3, "steps": 28},
+ "hunyuanvideo-community/hunyuanimage-2.1-diffusers": {"max": 2, "steps": 50},
+ "hunyuanvideo-community/hunyuanvideo-1.5-diffusers-480p_t2v": {"max": 2, "steps": 50},
+ "minimaxai/minimax-h3": {"max": 2, "steps": 30},
+}
+
+# Load gate on the model's default steps (keeps distilled siblings out); explicit "static" keeps STATIC_MIN_STEPS (12).
+AUTO_STATIC_MIN_STEPS = 20
+
+# Kill switch: auto never picks static (explicit requests still honoured).
+ENV_AUTO_STEP_SKIP = "UNSLOTH_DIFFUSION_AUTO_STEP_SKIP"
+
+
+def auto_step_skip_disabled(env: Optional[dict] = None) -> bool:
+ import os
+ raw = (
+ str((os.environ if env is None else env).get(ENV_AUTO_STEP_SKIP, "") or "").strip().lower()
+ )
+ return raw in ("0", "false", "off", "no", "none")
+
+
+def auto_static_skip_entry(*identifiers: Optional[str]) -> Optional[dict]:
+ """The AUTO_STATIC_SKIP row for the first identifier (repo id, then resolved base) naming a listed checkpoint."""
+ from .diffusion_families import canonical_base
+
+ for identifier in identifiers:
+ if not identifier:
+ continue
+ entry = AUTO_STATIC_SKIP.get(canonical_base(str(identifier)).strip().lower())
+ if entry is not None:
+ return entry
+ return None
+
+
+def skip_tier(requested: Optional[str], effective: Optional[str]) -> Optional[str]:
+ """The tier the skip policy reads: an explicit off / eager stays lossless even when quant forces a compile."""
+ asked = str(requested or "").strip().lower()
+ return asked if asked in ("off", "eager") else effective
+
+
+def auto_static_skip_plan(
+ identifiers: Any,
+ speed_mode: Optional[str],
+ default_steps: Optional[int],
+ env: Optional[dict] = None,
+) -> Optional[dict]:
+ """Settings for an auto static skip (``{"every": n, "min_steps": m}``), or None when auto must not pick it.
+
+ ``speed_mode`` is the tier the user ASKED for (an eager downgrade forced by offload does not change what the
+ skip costs in quality); off / eager are the lossless tiers and never skip."""
+ if auto_step_skip_disabled(env):
+ return None
+ if isinstance(identifiers, str) or identifiers is None:
+ identifiers = (identifiers,)
+ entry = auto_static_skip_entry(*identifiers)
+ if not entry or speed_mode not in (_TIER_DEFAULT, _TIER_MAX):
+ return None
+ every = entry.get(_TIER_DEFAULT) if speed_mode == _TIER_DEFAULT else entry.get(_TIER_MAX)
+ try:
+ steps_ok = default_steps is not None and int(default_steps) >= AUTO_STATIC_MIN_STEPS
+ except (TypeError, ValueError):
+ steps_ok = False
+ if not every or not steps_ok:
+ return None
+ return {
+ "every": int(every),
+ "min_steps": max(AUTO_STATIC_MIN_STEPS, int(entry.get("steps") or 0)),
+ }
+
+
def auto_step_cache_allowed(speed_mode: Optional[str]) -> bool:
"""Takes the EFFECTIVE speed tier."""
return speed_mode == AUTO_STEP_CACHE_TIER
-def resolve_auto_step_cache(speed_mode: Optional[str], default_steps: int) -> Optional[str]:
+def resolve_auto_step_cache(
+ speed_mode: Optional[str],
+ default_steps: int,
+ *,
+ static_plan: Optional[dict] = None,
+) -> Optional[str]:
+ """``static_plan`` (from auto_static_skip_plan) wins: a family measured for the fixed schedule takes it on every
+ tier the plan allows, FBCache stays the max-tier fallback for the rest."""
+ if static_plan:
+ return TC_STATIC
if auto_step_cache_allowed(speed_mode) and int(default_steps) >= FBCACHE_MIN_STEPS:
return TC_FBCACHE
return None
diff --git a/studio/backend/core/inference/diffusion_step_skip.py b/studio/backend/core/inference/diffusion_step_skip.py
index d3d58ea4a7a..37e688054ce 100644
--- a/studio/backend/core/inference/diffusion_step_skip.py
+++ b/studio/backend/core/inference/diffusion_step_skip.py
@@ -55,14 +55,17 @@ def static_schedule(
head: float = DEFAULT_HEAD,
tail: float = DEFAULT_TAIL,
every: int = DEFAULT_EVERY,
+ min_steps: int = STATIC_MIN_STEPS,
) -> tuple:
- """Per step, compute (True) or skip (False); empty (compute all) below ``STATIC_MIN_STEPS``."""
+ """Per step, compute (True) or skip (False); empty (compute all) below ``min_steps`` (never below
+ ``STATIC_MIN_STEPS``)."""
try:
n = int(steps) # type: ignore[arg-type]
every = int(every)
+ floor = max(STATIC_MIN_STEPS, int(min_steps))
except (TypeError, ValueError):
return ()
- if n < STATIC_MIN_STEPS or every < 2:
+ if n < floor or every < 2:
return ()
first = max(MIN_HEAD_STEPS, round(n * float(head)))
last = max(1, round(n * float(tail)))
@@ -109,6 +112,29 @@ def static_skip_settings(env: Optional[dict] = None, logger: Any = None) -> dict
return out
+def _every_override_valid(env: dict) -> bool:
+ try:
+ return int(env.get(ENV_EVERY)) >= 2
+ except (TypeError, ValueError):
+ return False
+
+
+def auto_static_settings(
+ plan: dict,
+ env: Optional[dict] = None,
+ logger: Any = None,
+) -> dict:
+ """Knobs for an AUTO static skip: the family's measured ``every`` and ``min_steps`` over the defaults; an
+ explicit ``UNSLOTH_STATIC_SKIP_*`` value still wins (benchmarking)."""
+ env = os.environ if env is None else env
+ out = static_skip_settings(env, logger)
+ if out["every"] == DEFAULT_EVERY and plan.get("every") and not _every_override_valid(env):
+ out["every"] = int(plan["every"])
+ out["min_steps"] = int(plan.get("min_steps") or STATIC_MIN_STEPS)
+ out["auto"] = True
+ return out
+
+
def _call_signature(args: tuple, kwargs: dict) -> tuple:
"""Reuse key: latent shape, prefix-KV mode (an ``extract`` call returns a longer sequence), container."""
hidden = kwargs.get("hidden_states", args[0] if args else None)
@@ -141,6 +167,9 @@ def _split_output(out: Any) -> tuple:
return out[0], lambda v: (v,)
if len(out) == 1 and type(out[0]) is list and _same_shape_tensors(out[0]):
return _torch().stack(out[0]), lambda v: (list(v.unbind(0)),)
+ # Joint (video, audio) predictions (MiniMax-H3), per stream; a non-tensor member (klein KV cache) declines.
+ if len(out) >= 2 and all(_is_tensor(v) for v in out):
+ return _Joint(out), lambda v: tuple(v.parts)
return None, None
keys = getattr(out, "keys", None)
if callable(keys) and callable(getattr(out, "to_tuple", None)):
@@ -162,6 +191,25 @@ def _split_output(out: Any) -> tuple:
return None, None
+class _Joint:
+ """Several predictions from one call, stored and extrapolated stream by stream."""
+
+ __slots__ = ("parts",)
+
+ def __init__(self, parts: Any) -> None:
+ self.parts = tuple(parts)
+
+ @property
+ def shape(self) -> tuple:
+ return tuple(tuple(p.shape) for p in self.parts)
+
+ def detach(self) -> "_Joint":
+ return _Joint(p.detach() for p in self.parts)
+
+ def clone(self) -> "_Joint":
+ return _Joint(p.clone() for p in self.parts)
+
+
_TIMESTEP_NAMES = ("timestep", "timesteps", "t")
@@ -204,13 +252,50 @@ def _timestep_of(
return None
+# MiniMax-H3 token_tags of the (video, audio) output streams; each stream steps its own shifted schedule.
+_JOINT_STREAM_TAGS = (0, 2)
+
+
+def _stream_timesteps(kwargs: dict) -> Optional[tuple]:
+ """Per-stream target timestep: min over the stream's rows (conditioning rows sit at or above it); no host sync."""
+ torch = _torch()
+ ts, idx, tags = kwargs.get("timestep"), kwargs.get("timestep_indices"), kwargs.get("token_tags")
+ if not (_is_tensor(ts) and _is_tensor(idx) and _is_tensor(tags)):
+ return None
+ try:
+ rows = ts.detach().reshape(-1).float().index_select(0, idx.detach().reshape(-1).long())
+ tags = tags.detach().reshape(-1).to(rows.device)
+ inf = torch.full_like(rows, float("inf"))
+ return tuple(
+ torch.where(tags == tag, rows, inf).amin().reshape(1).clone()
+ for tag in _JOINT_STREAM_TAGS
+ )
+ except Exception: # noqa: BLE001 - shared timestep instead
+ return None
+
+
+def _pick_t(t: Any, i: int, n: int) -> Any:
+ if isinstance(t, tuple):
+ return t[i] if len(t) == n else _torch().stack(t).amax().reshape(1)
+ return t
+
+
def _extrapolate(v0: Any, t0: Any, v1: Any, t1: Any, t: Any) -> Any:
+ if isinstance(v1, _Joint):
+ n = len(v1.parts)
+ return _Joint(
+ _extrapolate(a, _pick_t(t0, i, n), b, _pick_t(t1, i, n), _pick_t(t, i, n))
+ for i, (a, b) in enumerate(zip(v0.parts, v1.parts))
+ )
+ t0, t1, t = (_pick_t(x, 0, 0) for x in (t0, t1, t))
torch = _torch()
device = v1.device
t0, t1, t = t0.to(device), t1.to(device), t.to(device)
step = t1 - t0
safe = torch.where(step != 0, step, torch.ones_like(step))
ratio = torch.where(step != 0, (t - t1) / safe, torch.zeros_like(step))
+ # A stream with no rows in the call reads inf: reuse instead of a NaN.
+ ratio = torch.where(torch.isfinite(ratio), ratio, torch.zeros_like(ratio))
ratio = ratio.reshape([1] * v1.ndim) if v1.ndim else ratio.reshape(())
v1f = v1.float()
return (v1f + (v1f - v0.float()) * ratio).to(v1.dtype)
@@ -237,6 +322,8 @@ class StaticStepSkip:
head: float = DEFAULT_HEAD,
tail: float = DEFAULT_TAIL,
every: int = DEFAULT_EVERY,
+ min_steps: int = STATIC_MIN_STEPS,
+ auto: bool = False,
logger: Any = None,
) -> None:
# First, so nothing update_wrapper copies over can shadow the state set below.
@@ -256,6 +343,8 @@ class StaticStepSkip:
self.inner = inner
self.mode = mode if mode in SKIP_MODES else DEFAULT_MODE
self.head, self.tail, self.every = float(head), float(tail), int(every)
+ self.min_steps = int(min_steps)
+ self.auto = bool(auto)
self.logger = logger
self.armed = True
self.context: Any = None
@@ -275,12 +364,20 @@ class StaticStepSkip:
step_signal: bool = False,
keep_stats: bool = False,
owner: Optional[str] = None,
+ compute_all: bool = False,
) -> "StaticStepSkip":
"""Start a forward of ``steps`` denoise steps (None: compute all); ``keep_stats`` sums across chunks.
- ``owner`` (arming only) rebinds the counters; a new owner never inherits the previous one's."""
+ ``owner`` (arming only) rebinds the counters; a new owner never inherits the previous one's.
+ ``compute_all``: count this generation but skip nothing (an auto skip on an unmeasured workflow)."""
self.plan = (
- static_schedule(steps, head = self.head, tail = self.tail, every = self.every)
- if self.armed
+ static_schedule(
+ steps,
+ head = self.head,
+ tail = self.tail,
+ every = self.every,
+ min_steps = self.min_steps,
+ )
+ if self.armed and not compute_all
else ()
)
skips = [i for i, compute in enumerate(self.plan) if not compute]
@@ -316,6 +413,8 @@ class StaticStepSkip:
"head": self.head,
"tail": self.tail,
"every": self.every,
+ "min_steps": self.min_steps,
+ "auto": self.auto,
"armed": bool(self.armed),
"planned_skips": self.planned_skips,
"stats": dict(self.stats if self.stats["calls"] else self.last_stats),
@@ -381,9 +480,10 @@ class StaticStepSkip:
)
return
# Cloned: the pipeline may keep or modify the tensor it was handed.
- stored = _Stored(
- sig, _timestep_of(args, kwargs, self._t_slot), value.detach().clone(), rebuild
+ t = (_stream_timesteps(kwargs) if isinstance(value, _Joint) else None) or _timestep_of(
+ args, kwargs, self._t_slot
)
+ stored = _Stored(sig, t, value.detach().clone(), rebuild)
keep = 2 if self.mode == MODE_TAYLOR1 else 1
history = self.history.setdefault(key, [])
history.append(stored)
@@ -394,7 +494,9 @@ class StaticStepSkip:
value = None
if self.mode == MODE_TAYLOR1 and len(history) >= 2:
prev = history[-2]
- t = _timestep_of(args, kwargs, self._t_slot)
+ t = (
+ _stream_timesteps(kwargs) if isinstance(last.value, _Joint) else None
+ ) or _timestep_of(args, kwargs, self._t_slot)
# Only same-shape outputs combine: a prefix-KV step 0 is longer than every later step.
if (
prev.sig == last.sig
@@ -466,6 +568,8 @@ def install_static_step_skip(
existing.head = float(knobs.get("head", existing.head))
existing.tail = float(knobs.get("tail", existing.tail))
existing.every = int(knobs.get("every", existing.every))
+ existing.min_steps = int(knobs.get("min_steps", STATIC_MIN_STEPS))
+ existing.auto = bool(knobs.get("auto", False))
existing.reset(None)
return TC_STATIC
try:
@@ -477,6 +581,8 @@ def install_static_step_skip(
head = knobs.get("head", DEFAULT_HEAD),
tail = knobs.get("tail", DEFAULT_TAIL),
every = knobs.get("every", DEFAULT_EVERY),
+ min_steps = knobs.get("min_steps", STATIC_MIN_STEPS),
+ auto = knobs.get("auto", False),
logger = logger,
)
prior_ctx = slots.get("cache_context")
@@ -493,11 +599,13 @@ def install_static_step_skip(
return None
if logger is not None:
logger.info(
- "diffusion.step_skip: static engaged (mode=%s head=%s tail=%s every=%s)",
+ "diffusion.step_skip: static engaged (mode=%s head=%s tail=%s every=%s min_steps=%s%s)",
skip.mode,
skip.head,
skip.tail,
skip.every,
+ skip.min_steps,
+ ", auto" if skip.auto else "",
)
return TC_STATIC
@@ -509,11 +617,18 @@ def reset_static_step_skip(
step_signal: bool = False,
keep_stats: bool = False,
owner: Optional[str] = None,
+ compute_all: bool = False,
) -> bool:
skip = _find(pipe)
if skip is None:
return False
- skip.reset(steps, step_signal = step_signal, keep_stats = keep_stats, owner = owner)
+ skip.reset(
+ steps,
+ step_signal = step_signal,
+ keep_stats = keep_stats,
+ owner = owner,
+ compute_all = compute_all,
+ )
return True
@@ -523,6 +638,12 @@ def mark_step_end(pipe: Any) -> None:
skip.step_end()
+def static_skip_is_auto(pipe: Any) -> bool:
+ """Whether the installed layer came from the auto policy (measured per workflow) rather than an explicit ask."""
+ skip = _find(pipe)
+ return bool(skip is not None and skip.auto)
+
+
def static_skip_stats(pipe: Any) -> Optional[dict]:
skip = _find(pipe)
return skip.describe() if skip is not None else None
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index f3cefcef01d..a10b49ed831 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -61,7 +61,10 @@ from .diffusion_cache import (
TC_AUTO,
TC_STATIC,
apply_step_cache,
+ auto_static_skip_entry,
+ auto_static_skip_plan,
auto_step_cache_allowed,
+ skip_tier,
cache_breaks_graph,
maybe_toggle_step_cache,
normalize_transformer_cache,
@@ -69,9 +72,11 @@ from .diffusion_cache import (
step_cache_supported,
)
from .diffusion_step_skip import (
+ auto_static_settings,
install_static_step_skip,
mark_step_end,
reset_static_step_skip,
+ static_skip_is_auto,
static_skip_stats,
static_skip_view,
uninstall_static_step_skip,
@@ -2256,6 +2261,16 @@ def _denoiser_view(pipe: Any, component: str) -> Any:
return pipe if component == "transformer" else _NamedDiTView(pipe, component)
+def _skip_pipe(state: Any, pipe: Any = None) -> Any:
+ """What the static step skip helpers read ``transformer`` from: the pipe, or for MiniMax-H3 a view onto the
+ partition this load denoises with (a reference load's DiT is ``transformer_ref``)."""
+ pipe = getattr(state, "pipe", None) if pipe is None else pipe
+ fam = getattr(state, "family", None)
+ if pipe is None or not getattr(fam, "modular_workflow", None):
+ return pipe
+ return _denoiser_view(pipe, h3_denoiser_component(getattr(state, "h3_task", None)))
+
+
def _is_static_cache_request(value: Optional[str]) -> bool:
try:
return normalize_transformer_cache(value) == TC_STATIC
@@ -6313,12 +6328,28 @@ class VideoBackend:
# GGUF and torchao-quantised DiTs need the higher threshold to trigger over quant noise
cache_quant_active = kind == "gguf" or transformer_quant_engaged is not None
default_cache_steps: Optional[int] = None
+ static_plan: Optional[dict] = None
if cache_auto:
- default_cache_steps, _ = default_video_generation_params(gguf_filename, repo_id, base)
- cache_request = resolve_auto_step_cache(effective_speed, default_cache_steps)
+ default_cache_steps, _ = default_video_generation_params(
+ gguf_filename, repo_id, base, fallback = (fam.default_steps, fam.default_guidance)
+ )
+ static_plan = auto_static_skip_plan(
+ (repo_id, base), skip_tier(speed_mode, effective_speed), default_cache_steps
+ )
+ cache_request = resolve_auto_step_cache(
+ effective_speed, default_cache_steps, static_plan = static_plan
+ )
cache_engaged = None
static_decline: Optional[str] = None
- if cache_request == TC_STATIC:
+ if cache_request == TC_STATIC and static_plan:
+ # Auto: only where it was measured, which never lists a two-expert or joint audio-video family.
+ cache_engaged = install_static_step_skip(
+ pipe, settings = auto_static_settings(static_plan, logger = logger), logger = logger
+ )
+ if cache_engaged is None:
+ static_plan = None
+ cache_request = resolve_auto_step_cache(effective_speed, default_cache_steps)
+ if cache_request == TC_STATIC and not static_plan:
# One denoiser only: a dual-expert MoE hands part of the trajectory to transformer_2, unseen by the history.
if len(views) > 1 or getattr(pipe, "transformer_2", None) is not None:
static_decline = (
@@ -6339,7 +6370,7 @@ class VideoBackend:
static_decline = (
"static step skip is unavailable for this pipeline; it runs uncached"
)
- else:
+ elif cache_request != TC_STATIC:
for view in views:
engaged = apply_step_cache(
view,
@@ -6353,12 +6384,21 @@ class VideoBackend:
cache_engaged = engaged
cache_graph_break = cache_breaks_graph(cache_engaged)
# Arm only where FBCache can engage: a live toggle drops fullgraph and retries every generation.
- cache_may_toggle = cache_auto_live and (
- cache_engaged is not None
- or (cache_request is None and step_cache_supported(pipe, logger = logger))
+ cache_may_toggle = (
+ cache_auto_live
+ and cache_engaged != TC_STATIC
+ and (
+ cache_engaged is not None
+ or (cache_request is None and step_cache_supported(pipe, logger = logger))
+ )
)
if cache_auto:
- if not cache_auto_live:
+ if cache_engaged == TC_STATIC:
+ cache_reason = (
+ f"auto: static step skip (every {static_plan['every']}) for this model at "
+ f"{static_plan['min_steps']}+ steps; set UNSLOTH_DIFFUSION_AUTO_STEP_SKIP=0 to turn it off"
+ )
+ elif not cache_auto_live:
# Only name the max tier where it would help: SDXL / LTX-2 never cache on any tier.
cache_reason = (
"auto: step caching engages on the max speed tier only"
@@ -7534,6 +7574,53 @@ class VideoBackend:
except Exception as exc: # noqa: BLE001 -- optimisation only, never fail a load
logger.warning("video.h3_audio_vae: keeping the stock audio VAE: %s", exc)
+ # Static skip is the only step cache here (the modular loop opens no cache_context for FBCache). One call per
+ # step (guidance-distilled), so the per-call counter is the step index.
+ h3_cache_engaged: Optional[str] = None
+ h3_cache_reason = "not supported by this modular workflow"
+ try:
+ h3_cache_request = normalize_transformer_cache(transformer_cache)
+ except ValueError:
+ h3_cache_request = str(
+ transformer_cache
+ ) # the routes refuse it first; a direct call runs uncached
+ h3_cache_auto = transformer_cache is None or h3_cache_request == TC_AUTO
+ h3_static_plan = (
+ auto_static_skip_plan((repo_id, base), h3_vae_speed, fam.default_steps)
+ if h3_cache_auto
+ else None
+ )
+ if h3_static_plan or h3_cache_request == TC_STATIC:
+ h3_cache_engaged = install_static_step_skip(
+ _denoiser_view(pipe, denoiser_component),
+ settings = (
+ auto_static_settings(h3_static_plan, logger = logger) if h3_static_plan else None
+ ),
+ logger = logger,
+ )
+ if h3_cache_engaged is None:
+ h3_cache_reason = (
+ "static step skip is unavailable for this pipeline; it runs uncached"
+ )
+ elif h3_static_plan:
+ h3_cache_reason = (
+ f"auto: static step skip (every {h3_static_plan['every']}) for this model at "
+ f"{h3_static_plan['min_steps']}+ steps; set UNSLOTH_DIFFUSION_AUTO_STEP_SKIP=0 to turn it off"
+ )
+ else:
+ h3_cache_reason = "requested"
+ elif h3_cache_auto:
+ h3_cache_reason = (
+ "auto: static step skip engages on the max speed tier only"
+ if auto_static_skip_entry(repo_id, base)
+ else "auto: not enabled for this model"
+ )
+ elif h3_cache_request is not None:
+ h3_cache_reason = (
+ "only static step skip is supported by this modular workflow; running uncached"
+ )
+ else:
+ h3_cache_reason = "requested"
if offload_policy != "none" and (te_streamed or denoiser_streamed):
# Only the VAEs rotate now, evicting each other every render. Installed last: the levers above replace weights.
from .video_minimax_h3_residency import install_pinned_swap
@@ -7583,11 +7670,15 @@ class VideoBackend:
(
transformer_cache,
"off",
- "static step skip is not supported by this modular workflow",
+ h3_cache_reason,
RESOLVED_UNSUPPORTED,
)
- if _is_static_cache_request(transformer_cache)
- else (None, "off", "not supported by this modular workflow")
+ if h3_cache_engaged is None and h3_cache_request not in (None, TC_AUTO)
+ else (
+ None if h3_cache_auto else transformer_cache,
+ h3_cache_engaged or "off",
+ h3_cache_reason,
+ )
),
"cuda_graph": (
None,
@@ -7663,6 +7754,7 @@ class VideoBackend:
# a dense fallback recorded as int8 would under-state the floor by 39 GB and let a doomed generation
# start.
text_encoder_quant = text_encoder_quant_engaged,
+ transformer_cache = h3_cache_engaged,
denoiser_pinned = denoiser_pinned,
denoiser_streamed = bool(denoiser_streamed),
# A slab-arena pin released the pageable source, so the pinned copy is the only one.
@@ -7960,7 +8052,7 @@ class VideoBackend:
state = self._state
if state is None or state.transformer_cache != TC_STATIC:
return None, None
- return static_skip_view(state.pipe)
+ return static_skip_view(_skip_pipe(state))
def _run_generate(
self,
@@ -8637,7 +8729,7 @@ class VideoBackend:
def _on_step(p, step_index, timestep, callback_kwargs):
if static_skip:
- mark_step_end(pipe)
+ mark_step_end(_skip_pipe(state, pipe))
# diffusers calls this at the END of a loop iteration, after scheduler.step, so
# the step's latent update is already submitted when the marker goes down.
if cancel.is_set():
@@ -8705,9 +8797,16 @@ class VideoBackend:
+ f" {FBCACHE_MIN_STEPS}"
)
if static_skip:
+ # Auto skip was measured on text-to-video only.
+ conditioned = bool(first_pil is not None or last_pil is not None or references)
+ auto_unmeasured = conditioned and static_skip_is_auto(_skip_pipe(state, pipe))
# Without a step callback (HunyuanVideo-1.5) steps count per CFG branch from cache_context names.
reset_static_step_skip(
- pipe, steps, step_signal = has_step_callback, owner = current_account_id()
+ _skip_pipe(state, pipe),
+ steps,
+ step_signal = has_step_callback,
+ owner = current_account_id(),
+ compute_all = auto_unmeasured,
)
elif state.transformer_cache:
self._reset_step_cache(pipe)
@@ -8738,8 +8837,10 @@ class VideoBackend:
# whether this render finished, was cancelled or failed.
settle_compile_fallback(state, pipe, logger)
if static_skip:
- logger.debug("video.step_skip: %s", static_skip_stats(pipe))
- reset_static_step_skip(pipe, None)
+ logger.debug(
+ "video.step_skip: %s", static_skip_stats(_skip_pipe(state, pipe))
+ )
+ reset_static_step_skip(_skip_pipe(state, pipe), None)
if fam.modular_workflow:
from .video_minimax_h3_vae import settle_h3_vae_fallback
settle_h3_vae_fallback(state, pipe)
@@ -9501,7 +9602,7 @@ class VideoBackend:
diffusion_cuda_graph.uninstall_all(
getattr(getattr(state, "pipe", None), "_unsloth_cuda_graphs", ()) or ()
)
- uninstall_static_step_skip(getattr(state, "pipe", None))
+ uninstall_static_step_skip(_skip_pipe(state))
try:
from .diffusion_nvfp4_linear import reset_nvfp4_state
reset_nvfp4_state()
@@ -9637,7 +9738,9 @@ class VideoBackend:
**_sd_cpp_cudnn_status(state),
"transformer_cache": state.transformer_cache,
"transformer_cache_stats": (
- static_skip_stats(state.pipe) if state.transformer_cache == TC_STATIC else None
+ static_skip_stats(_skip_pipe(state))
+ if state.transformer_cache == TC_STATIC
+ else None
),
"transformer_quant": state.transformer_quant,
**_nvfp4_backend_fields(_video_transformer_quant_backend(state), owner = self),
diff --git a/studio/backend/tests/test_diffusion_step_skip_defaults.py b/studio/backend/tests/test_diffusion_step_skip_defaults.py
new file mode 100644
index 00000000000..bd07b62849c
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_step_skip_defaults.py
@@ -0,0 +1,546 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Auto static step skip: the per-model policy, its kill switch, joint (video, audio) outputs, and the image loader."""
+
+from __future__ import annotations
+
+import contextlib
+import types
+
+import pytest
+import torch
+
+from core.inference import diffusion_cache as dcache
+from core.inference import diffusion_step_skip as ss
+from core.inference.diffusion_families import default_generation_params
+
+from .test_diffusion_backend import _load_into, fake_runtime # noqa: F401 - fixture
+
+
+# --------------------------------------------------------------------------------------------- schedule / policy
+def test_min_steps_raises_the_floor_but_never_lowers_it():
+ assert ss.static_schedule(14, min_steps = 20) == ()
+ assert ss.static_schedule(20, min_steps = 20) == ss.static_schedule(20)
+ # Below STATIC_MIN_STEPS stays off whatever is asked.
+ assert ss.static_schedule(11, min_steps = 4) == ()
+ assert ss.static_schedule(14, min_steps = 4) == ss.static_schedule(14)
+
+
+def table(monkeypatch):
+ monkeypatch.setattr(
+ dcache,
+ "AUTO_STATIC_SKIP",
+ {
+ "black-forest-labs/flux.1-krea-dev": {"default": 2, "max": 3},
+ "black-forest-labs/flux.1-dev": {"max": 2},
+ },
+ )
+ monkeypatch.delenv(dcache.ENV_AUTO_STEP_SKIP, raising = False)
+
+
+KREA = "black-forest-labs/FLUX.1-Krea-dev"
+DEV = "black-forest-labs/FLUX.1-dev"
+
+
+ "ids, tier, steps, want",
+ [
+ ((KREA,), "default", 28, {"every": 2, "min_steps": 20}),
+ ((KREA,), "max", 28, {"every": 3, "min_steps": 20}),
+ ((KREA,), "eager", 28, None),
+ ((KREA,), "off", 28, None),
+ ((KREA,), None, 28, None),
+ ((KREA,), "default", 12, None), # a short default schedule is never measured
+ ((DEV,), "default", 28, None), # max-only row
+ ((DEV,), "max", 28, {"every": 2, "min_steps": 20}),
+ # The unsloth mirror and a local path with the upstream as its base both resolve to the upstream row.
+ (("unsloth/FLUX.1-Krea-dev",), "default", 28, {"every": 2, "min_steps": 20}),
+ (("/models/my-krea", KREA), "default", 28, {"every": 2, "min_steps": 20}),
+ (("black-forest-labs/FLUX.1-schnell",), "max", 28, None),
+ ((None,), "max", 28, None),
+ (KREA, "default", 28, {"every": 2, "min_steps": 20}), # a bare string
+ ],
+)
+def test_plan_follows_the_tier_and_the_default_steps(table, ids, tier, steps, want):
+ assert dcache.auto_static_skip_plan(ids, tier, steps) == want
+
+
[email protected]("value", ["0", "false", "off", "NO"])
+def test_kill_switch_turns_auto_static_off(table, monkeypatch, value):
+ monkeypatch.setenv(dcache.ENV_AUTO_STEP_SKIP, value)
+ assert dcache.auto_static_skip_plan((KREA,), "default", 28) is None
+ # Auto falls back to what it did before: FBCache on max at 20+ steps, nothing on default.
+ assert dcache.resolve_auto_step_cache("max", 28, static_plan = None) == dcache.TC_FBCACHE
+ assert dcache.resolve_auto_step_cache("default", 28, static_plan = None) is None
+
+
+def test_static_plan_wins_over_fbcache_on_max(table):
+ plan = dcache.auto_static_skip_plan((DEV,), "max", 28)
+ assert dcache.resolve_auto_step_cache("max", 28, static_plan = plan) == dcache.TC_STATIC
+
+
+def test_auto_settings_use_the_plan_unless_the_env_pins_every():
+ plan = {"every": 3, "min_steps": 20}
+ knobs = ss.auto_static_settings(plan, env = {})
+ assert (knobs["every"], knobs["min_steps"], knobs["auto"]) == (3, 20, True)
+ assert knobs["mode"] == ss.DEFAULT_MODE
+ assert ss.auto_static_settings(plan, env = {ss.ENV_EVERY: "2"})["every"] == 2
+
+
+# The shipped table: only the checkpoints that were measured, each at its default steps.
+MEASURED = {
+ "Qwen/Qwen-Image-2.1": ("default", "max"),
+ "Qwen/Qwen-Image": ("default", "max"),
+ "black-forest-labs/FLUX.1-Krea-dev": ("default", "max"),
+ "black-forest-labs/FLUX.2-klein-base-4B": ("default", "max"),
+ "Wan-AI/Wan2.2-TI2V-5B-Diffusers": ("default", "max"),
+ "black-forest-labs/FLUX.1-dev": ("max",),
+ "hunyuanvideo-community/HunyuanImage-2.1-Diffusers": ("max",),
+ "hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v": ("max",),
+ "MiniMaxAI/MiniMax-H3": ("max",),
+}
+
+
+def test_shipped_table_lists_only_measured_models():
+ assert set(dcache.AUTO_STATIC_SKIP) == {k.lower() for k in MEASURED}
+ for repo, tiers in MEASURED.items():
+ entry = {k: v for k, v in dcache.AUTO_STATIC_SKIP[repo.lower()].items() if k != "steps"}
+ assert set(entry) == set(tiers)
+ assert all(int(v) >= 2 for v in entry.values())
+ # The default tier never skips more than the max tier.
+ assert entry.get("default", 99) <= entry["max"] or "default" not in entry
+
+
[email protected]("repo", sorted(MEASURED))
+def test_every_measured_model_reaches_the_auto_floor_at_its_default_steps(repo):
+ from core.inference.video_families import default_video_generation_params
+
+ steps, _ = default_generation_params(repo)
+ if repo.startswith(("Wan-AI", "hunyuanvideo-community/HunyuanVideo")):
+ steps, _ = default_video_generation_params(repo)
+ if repo == "MiniMaxAI/MiniMax-H3":
+ steps = 30 # the family default; no generation-defaults row
+ assert steps >= dcache.AUTO_STATIC_MIN_STEPS
+ assert dcache.auto_static_skip_plan((repo,), "max", steps) is not None
+
+
+ "repo",
+ [
+ "black-forest-labs/FLUX.1-schnell",
+ "black-forest-labs/FLUX.2-klein-4B",
+ "black-forest-labs/FLUX.2-klein-base-9B",
+ "Tongyi-MAI/Z-Image-Turbo",
+ "Tongyi-MAI/Z-Image",
+ "Qwen/Qwen-Image-2512",
+ "Qwen/Qwen-Image-Edit-2511",
+ "unsloth/Krea-2-Turbo",
+ ],
+)
+def test_unmeasured_or_distilled_siblings_never_auto_skip(repo):
+ steps, _ = default_generation_params(repo)
+ for tier in ("default", "max"):
+ assert dcache.auto_static_skip_plan((repo,), tier, max(steps, 50)) is None
+
+
+# --------------------------------------------------------------------------------------------- joint outputs (H3)
+class _JointDiT:
+ """MiniMax-H3's shape: one call per step returning (video velocity, audio velocity) of different sizes."""
+
+ def __init__(self):
+ self.calls = 0
+
+ def forward(
+ self,
+ hidden_states = None,
+ audio_hidden_states = None,
+ timestep = None,
+ return_dict = True,
+ ):
+ self.calls += 1
+ t = float(timestep.reshape(-1).max())
+ return torch.full((1, 6, 2), t), torch.full((1, 3), 2 * t)
+
+
+def _run_joint(pipe, steps):
+ outs = []
+ for i in range(steps):
+ t = torch.tensor([0.0, 1.0 - i / steps]) # conditioning rows at 0, noisy rows at t
+ outs.append(pipe.transformer.forward(hidden_states = None, timestep = t, return_dict = False))
+ return outs
+
+
[email protected]("mode", ["reuse", "taylor1"])
+def test_joint_video_audio_outputs_are_skipped_stream_by_stream(mode):
+ dit = _JointDiT()
+ pipe = types.SimpleNamespace(transformer = dit)
+ knobs = {**ss.static_skip_settings({}), "mode": mode}
+ assert ss.install_static_step_skip(pipe, settings = knobs) == dcache.TC_STATIC
+ ss.reset_static_step_skip(pipe, 30)
+ outs = _run_joint(pipe, 30)
+ plan = ss.static_schedule(30)
+ assert dit.calls == sum(plan)
+ assert ss.static_skip_stats(pipe)["stats"]["skipped"] == 30 - sum(plan)
+ for i, (video, audio) in enumerate(outs):
+ assert type(outs[i]) is tuple and video.shape == (1, 6, 2) and audio.shape == (1, 3)
+ t = 1.0 - i / 30
+ if plan[i] or mode == "taylor1":
+ # Computed, or extrapolated linearly in t, which is exact for these linear-in-t outputs.
+ assert torch.allclose(video, torch.full_like(video, t), atol = 1e-5)
+ assert torch.allclose(audio, torch.full_like(audio, 2 * t), atol = 1e-5)
+ else:
+ prev = max(j for j in range(i) if plan[j])
+ assert torch.allclose(video, torch.full_like(video, 1.0 - prev / 30))
+
+
+def test_a_non_tensor_member_still_declines():
+ class _KV(_JointDiT):
+ def forward(self, **kw):
+ self.calls += 1
+ return torch.zeros(1, 2), {"kv": 1}
+
+ dit = _KV()
+ pipe = types.SimpleNamespace(transformer = dit)
+ ss.install_static_step_skip(pipe, settings = ss.static_skip_settings({}))
+ ss.reset_static_step_skip(pipe, 25)
+ for i in range(25):
+ dit.forward(timestep = torch.tensor([1.0 - i / 25]))
+ assert dit.calls == 25
+
+
+# --------------------------------------------------------------------------------------------- image loader
+def _probe_plan(entry):
+ """The real plan function over a one-row table, whatever ids the loader passes (a tmp-path GGUF here)."""
+
+ def plan(
+ ids,
+ tier,
+ steps,
+ env = None,
+ ):
+ saved = dict(dcache.AUTO_STATIC_SKIP)
+ dcache.AUTO_STATIC_SKIP.clear()
+ dcache.AUTO_STATIC_SKIP["probe/model"] = entry
+ try:
+ return dcache.auto_static_skip_plan(("probe/model",), tier, steps, env)
+ finally:
+ dcache.AUTO_STATIC_SKIP.clear()
+ dcache.AUTO_STATIC_SKIP.update(saved)
+
+ return plan
+
+
+ "speed, killed, want_static",
+ [
+ ("default", False, True),
+ ("max", False, True),
+ ("eager", False, False),
+ ("default", True, False),
+ ],
+)
+def test_auto_load_installs_static_for_a_listed_model(
+ fake_runtime, tmp_path, monkeypatch, speed, killed, want_static
+):
+ from core.inference import diffusion as dmod
+
+ monkeypatch.setattr(dmod, "auto_static_skip_plan", _probe_plan({"default": 3, "max": 3}))
+ monkeypatch.setattr(dmod, "default_generation_params", lambda *a, **k: (28, 3.5))
+ if killed:
+ monkeypatch.setenv(dcache.ENV_AUTO_STEP_SKIP, "0")
+ else:
+ monkeypatch.delenv(dcache.ENV_AUTO_STEP_SKIP, raising = False)
+ installs, fb = [], []
+ monkeypatch.setattr(
+ dmod,
+ "install_static_step_skip",
+ lambda pipe, settings = None, logger = None: installs.append(settings) or dcache.TC_STATIC,
+ )
+ monkeypatch.setattr(
+ dmod, "apply_step_cache", lambda pipe, mode = None, **k: fb.append(mode) or None
+ )
+ (tmp_path / "model.gguf").write_bytes(b"weights")
+ backend = dmod.DiffusionBackend()
+ status = _load_into(backend, tmp_path, speed_mode = speed, transformer_cache = None)
+ entry = status["resolved"]["transformer_cache"]
+ if want_static:
+ assert len(installs) == 1 and installs[0]["every"] == 3 and installs[0]["min_steps"] == 20
+ assert installs[0]["auto"] is True
+ assert status["transformer_cache"] == "static" and entry["value"] == "static"
+ assert entry["requested"] is None and "UNSLOTH_DIFFUSION_AUTO_STEP_SKIP" in entry["reason"]
+ assert fb == []
+ # The generate-time FBCache toggle is never armed over an engaged static skip.
+ assert backend._state.cache_auto is False
+ else:
+ assert installs == []
+ assert status["transformer_cache"] in (None, dcache.TC_FBCACHE)
+ backend.unload()
+
+
+def test_explicit_requests_ignore_the_table(fake_runtime, tmp_path, monkeypatch):
+ from core.inference import diffusion as dmod
+
+ monkeypatch.setattr(dmod, "auto_static_skip_plan", _probe_plan({"default": 3, "max": 3}))
+ monkeypatch.setattr(
+ dmod,
+ "install_static_step_skip",
+ lambda *a, **k: pytest.fail("explicit off installed static"),
+ )
+ (tmp_path / "model.gguf").write_bytes(b"weights")
+ backend = dmod.DiffusionBackend()
+ status = _load_into(backend, tmp_path, speed_mode = "default", transformer_cache = "off")
+ assert status["transformer_cache"] is None
+ backend.unload()
+
+
+def test_auto_static_declined_falls_back_to_the_previous_auto(fake_runtime, tmp_path, monkeypatch):
+ from core.inference import diffusion as dmod
+
+ monkeypatch.setattr(dmod, "auto_static_skip_plan", _probe_plan({"default": 2, "max": 2}))
+ monkeypatch.setattr(dmod, "default_generation_params", lambda *a, **k: (28, 3.5))
+ monkeypatch.delenv(dcache.ENV_AUTO_STEP_SKIP, raising = False)
+ monkeypatch.setattr(dmod, "install_static_step_skip", lambda *a, **k: None)
+ modes = []
+ monkeypatch.setattr(
+ dmod, "apply_step_cache", lambda pipe, mode = None, **k: modes.append(mode) or None
+ )
+ (tmp_path / "model.gguf").write_bytes(b"weights")
+ backend = dmod.DiffusionBackend()
+ _load_into(backend, tmp_path, speed_mode = "max", transformer_cache = None)
+ assert modes == [dcache.TC_FBCACHE]
+ backend.unload()
+
+
+# --------------------------------------------------------------------------------------------- generate scope
[email protected]("auto", [True, False])
+def test_auto_skip_runs_on_txt2img_only_explicit_everywhere(
+ fake_runtime, tmp_path, monkeypatch, auto
+):
+ from core.inference import diffusion as dmod
+
+ from .test_diffusion_backend import _loaded_backend, _tiny_png_b64
+
+ (tmp_path / "model.gguf").write_bytes(b"x")
+ backend = _loaded_backend(tmp_path)
+ pipe = backend._state.pipe
+ pipe.transformer = types.SimpleNamespace(forward = lambda *a, **k: None, __dict__ = {})
+ layer = types.SimpleNamespace(auto = auto)
+ monkeypatch.setattr(dmod, "static_skip_is_auto", lambda p: layer.auto)
+ armed = []
+ monkeypatch.setattr(
+ dmod,
+ "reset_static_step_skip",
+ lambda p, steps, **k: armed.append((steps, bool(k.get("compute_all")))) or True,
+ )
+ monkeypatch.setattr(dmod, "effective_request_strength", lambda *a, **k: None)
+ object.__setattr__(backend._state, "transformer_cache", dcache.TC_STATIC)
+ backend.generate(prompt = "a car", steps = 28, seed = 1)
+ assert armed[0] == (28, False)
+ armed.clear()
+ backend.generate(prompt = "a car", steps = 28, seed = 1, init_image = _tiny_png_b64(), strength = 1.0)
+ # img2img: an AUTO layer computes every step; an explicit one keeps its schedule.
+ assert armed[0] == (28, auto)
+ backend.unload()
+
+
+def test_deferred_default_tier_installs_the_auto_skip_on_the_third_image(
+ fake_runtime, tmp_path, monkeypatch
+):
+ # Speed unset (the UI default): a dense load stays eager, then the 3rd image engages `default`, and with it the
+ # model's default-tier skip. The first two renders stay full-step.
+ from core.inference import diffusion as dmod
+
+ from .test_diffusion_backend import DiffusionBackend
+
+ monkeypatch.setattr(dmod, "auto_static_skip_plan", _probe_plan({"default": 2, "max": 3}))
+ monkeypatch.setattr(dmod, "default_generation_params", lambda *a, **k: (28, 3.5))
+ monkeypatch.delenv(dcache.ENV_AUTO_STEP_SKIP, raising = False)
+ monkeypatch.setattr(dmod, "compile_eligible", lambda *a, **k: True)
+ monkeypatch.setattr(
+ dmod,
+ "apply_speed_optims",
+ lambda pipe, target, **k: {"compiled": k.get("speed_mode") == "default"},
+ )
+ monkeypatch.setattr(dmod.compile_cache, "begin", lambda **k: None)
+ installs = []
+ monkeypatch.setattr(
+ dmod,
+ "install_static_step_skip",
+ lambda pipe, settings = None, logger = None: installs.append(settings) or dcache.TC_STATIC,
+ )
+ monkeypatch.setattr(dmod, "reset_static_step_skip", lambda *a, **k: True)
+ (tmp_path / "model.safetensors").write_bytes(b"weights")
+ backend = DiffusionBackend()
+ status = _load_into(
+ backend, tmp_path, gguf_filename = "model.safetensors", family_override = "qwen-image"
+ )
+ assert status["speed_mode"] == "off" and status["transformer_cache"] is None
+ backend.generate(prompt = "one")
+ backend.generate(prompt = "two")
+ assert installs == [] and backend.status()["transformer_cache"] is None
+ backend.generate(prompt = "three")
+ st = backend.status()
+ assert st["speed_mode"] == "default"
+ assert len(installs) == 1 and installs[0]["every"] == 2 and installs[0]["auto"] is True
+ assert st["transformer_cache"] == "static"
+ assert st["resolved"]["transformer_cache"]["value"] == "static"
+ backend.unload()
+
+
+def test_a_bypassed_render_reports_zero_skips_not_the_previous_render():
+ dit = _JointDiT()
+ pipe = types.SimpleNamespace(transformer = dit)
+ ss.install_static_step_skip(pipe, settings = ss.static_skip_settings({}))
+ ss.reset_static_step_skip(pipe, 30)
+ _run_joint(pipe, 30)
+ assert ss.static_skip_stats(pipe)["stats"]["skipped"] > 0
+ ss.reset_static_step_skip(pipe, 30, compute_all = True)
+ calls = dit.calls
+ _run_joint(pipe, 30)
+ described = ss.static_skip_stats(pipe)
+ assert dit.calls - calls == 30
+ assert described["stats"] == {"calls": 30, "computed": 30, "skipped": 0}
+ assert described["planned_skips"] == 0
+
+
+class _H3DiT:
+ """(video, audio) outputs linear in each stream's own timestep, read from the H3 row layout."""
+
+ def __init__(self):
+ self.calls = 0
+
+ def forward(
+ self,
+ hidden_states = None,
+ timestep = None,
+ timestep_indices = None,
+ token_tags = None,
+ **kw,
+ ):
+ self.calls += 1
+ rows = timestep.index_select(0, timestep_indices)
+ video_t = rows[token_tags == 0].min()
+ audio_t = rows[token_tags == 2].min()
+ return torch.full((1, 4, 2), float(video_t)), torch.full((1, 3), float(audio_t))
+
+
+def _shifted(sigma, shift):
+ return shift * sigma / (1 + (shift - 1) * sigma)
+
+
+def test_h3_audio_extrapolates_on_its_own_schedule():
+ # Video shift 12, audio shift 3 (MiniMax-H3 defaults); a video reference row at 1.0 and a text row.
+ steps = 30
+ dit = _H3DiT()
+ pipe = types.SimpleNamespace(transformer = dit)
+ ss.install_static_step_skip(pipe, settings = {**ss.static_skip_settings({}), "mode": "taylor1"})
+ ss.reset_static_step_skip(pipe, steps)
+ tags = torch.tensor([0, 0, 0, 1, 2, 2, 2])
+ plan = ss.static_schedule(steps)
+ for i in range(steps):
+ sigma = 1.0 - i / steps
+ vt, at = _shifted(sigma, 12.0), _shifted(sigma, 3.0)
+ per_row = torch.tensor([1.0, vt, vt, vt, 1.0, at, at])
+ unique, inverse = torch.unique(per_row, sorted = True, return_inverse = True)
+ video, audio = pipe.transformer.forward(
+ hidden_states = None, timestep = unique, timestep_indices = inverse, token_tags = tags
+ )
+ if not plan[i]:
+ prev = [j for j in range(i) if plan[j]][-2:]
+ s0, s1 = (1.0 - j / steps for j in prev)
+ want_a = _shifted(s1, 3.0) + (_shifted(s1, 3.0) - _shifted(s0, 3.0)) * (
+ at - _shifted(s1, 3.0)
+ ) / (_shifted(s1, 3.0) - _shifted(s0, 3.0))
+ assert torch.allclose(audio, torch.full_like(audio, want_a), atol = 1e-5), (
+ i,
+ float(audio[0, 0]),
+ at,
+ )
+ assert torch.allclose(video, torch.full_like(video, vt), atol = 1e-5)
+ assert dit.calls == sum(plan)
+
+
+def test_a_failed_deferred_profile_takes_the_auto_skip_back_off(
+ fake_runtime, tmp_path, monkeypatch
+):
+ from core.inference import diffusion as dmod
+
+ from .test_diffusion_backend import DiffusionBackend
+
+ monkeypatch.setattr(dmod, "auto_static_skip_plan", _probe_plan({"default": 2, "max": 3}))
+ monkeypatch.setattr(dmod, "default_generation_params", lambda *a, **k: (28, 3.5))
+ monkeypatch.delenv(dcache.ENV_AUTO_STEP_SKIP, raising = False)
+ monkeypatch.setattr(dmod, "compile_eligible", lambda *a, **k: True)
+
+ def boom(*a, **k):
+ raise RuntimeError("compile unavailable")
+
+ monkeypatch.setattr(dmod.compile_cache, "begin", boom)
+ monkeypatch.setattr(
+ dmod,
+ "install_static_step_skip",
+ lambda pipe, settings = None, logger = None: dcache.TC_STATIC,
+ )
+ removed = []
+ monkeypatch.setattr(dmod, "uninstall_static_step_skip", lambda pipe: removed.append(pipe))
+ (tmp_path / "model.safetensors").write_bytes(b"weights")
+ backend = DiffusionBackend()
+ _load_into(backend, tmp_path, gguf_filename = "model.safetensors", family_override = "qwen-image")
+ for p in ("one", "two", "three"):
+ backend.generate(prompt = p)
+ st = backend.status()
+ assert st["speed_mode"] == "off"
+ assert st["transformer_cache"] is None and removed
+ assert st["resolved"]["transformer_cache"]["value"] != "static"
+ backend.unload()
+
+
+# Step counts the table rows were measured at (PR description); the auto skip never runs below them.
+MEASURED_STEPS = {
+ "Qwen/Qwen-Image-2.1": 25,
+ "Qwen/Qwen-Image": 20,
+ "black-forest-labs/FLUX.1-Krea-dev": 28,
+ "black-forest-labs/FLUX.2-klein-base-4B": 50,
+ "Wan-AI/Wan2.2-TI2V-5B-Diffusers": 50,
+ "black-forest-labs/FLUX.1-dev": 28,
+ "hunyuanvideo-community/HunyuanImage-2.1-Diffusers": 50,
+ "hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v": 50,
+ "MiniMaxAI/MiniMax-H3": 30,
+}
+
+
[email protected]("repo", sorted(MEASURED_STEPS))
+def test_auto_skip_never_runs_below_the_measured_step_count(repo):
+ plan = dcache.auto_static_skip_plan((repo,), "max", 50, env = {})
+ assert plan["min_steps"] == max(dcache.AUTO_STATIC_MIN_STEPS, MEASURED_STEPS[repo])
+ below = ss.static_schedule(
+ plan["min_steps"] - 1, every = plan["every"], min_steps = plan["min_steps"]
+ )
+ assert below == ()
+ assert not all(
+ ss.static_schedule(plan["min_steps"], every = plan["every"], min_steps = plan["min_steps"])
+ )
+
+
+ "requested, effective, want",
+ [
+ ("off", "default", "off"),
+ ("eager", "default", "eager"),
+ (None, "default", "default"),
+ ("max", "max", "max"),
+ ],
+)
+def test_an_explicit_lossless_tier_never_auto_skips(requested, effective, want):
+ tier = dcache.skip_tier(requested, effective)
+ assert tier == want
+ plan = dcache.auto_static_skip_plan(("Qwen/Qwen-Image",), tier, 20, env = {})
+ assert (plan is None) == (want in ("off", "eager"))
+
+
[email protected]("raw, want", [("1", 3), ("abc", 3), ("", 3), ("4", 4)])
+def test_only_a_valid_every_override_beats_the_measured_interval(raw, want):
+ out = ss.auto_static_settings({"every": 3, "min_steps": 20}, env = {ss.ENV_EVERY: raw})
+ assert out["every"] == want
diff --git a/studio/backend/tests/test_video_static_skip.py b/studio/backend/tests/test_video_static_skip.py
index a66587d732e..7ad3013b5e9 100644
--- a/studio/backend/tests/test_video_static_skip.py
+++ b/studio/backend/tests/test_video_static_skip.py
@@ -214,15 +214,68 @@ def test_fbcache_load_still_reports_an_active_cache(loop_runtime, monkeypatch):
@pytest.mark.parametrize("request_cache", [None, "auto"])
-def test_auto_never_installs_static(loop_runtime, monkeypatch, request_cache):
+def test_auto_installs_the_measured_static_skip_on_wan_5b(loop_runtime, monkeypatch, request_cache):
+ monkeypatch.delenv(dcache.ENV_AUTO_STEP_SKIP, raising = False)
+ seen = _record_speed(monkeypatch)
+ backend = VideoBackend()
+ status = backend.load_pipeline(
+ WAN_5B, model_kind = "pipeline", speed_mode = "default", transformer_cache = request_cache
+ )
+ assert status["transformer_cache"] == "static"
+ entry = status["resolved"]["transformer_cache"]
+ assert entry["value"] == "static" and entry["requested"] is None
+ assert "UNSLOTH_DIFFUSION_AUTO_STEP_SKIP" in entry["reason"]
+ layer = loop_runtime["pipe"].transformer.__dict__["forward"]
+ # Measured at 50 steps, so a shorter render computes every step.
+ assert (layer.every, layer.auto, layer.min_steps) == (2, True, 50)
+ # Kept graph decisions, and the generate-time FBCache toggle is never armed over it.
+ assert [kw["cache_active"] for kw in seen] == [False]
+ assert backend._state.cache_auto is False
+ backend.generate(prompt = "a sloth", steps = STEPS)
+ assert loop_runtime["pipe"].transformer.computed == 2 * (STEPS - SKIPPED_PER_BRANCH)
+ backend.unload()
+
+
+def test_auto_skip_leaves_a_keyframe_clip_unskipped(loop_runtime, monkeypatch):
+ monkeypatch.delenv(dcache.ENV_AUTO_STEP_SKIP, raising = False)
+ backend = VideoBackend()
+ backend.load_pipeline(WAN_5B, model_kind = "pipeline", speed_mode = "default")
+ real = VideoBackend._resolve_keyframes
+
+ def with_first_frame(*args, **kwargs):
+ first, last, width, height, conditioning = real(*args, **kwargs)
+ return object(), last, width, height, conditioning
+
+ monkeypatch.setattr(VideoBackend, "_resolve_keyframes", staticmethod(with_first_frame))
+ armed = []
import core.inference.video as video_mod
+ real_reset = video_mod.reset_static_step_skip
+ monkeypatch.setattr(
+ video_mod,
+ "reset_static_step_skip",
+ lambda p, steps, **k: armed.append((steps, k.get("compute_all")))
+ or real_reset(p, steps, **k),
+ )
+ try:
+ backend.generate(prompt = "a sloth", steps = STEPS)
+ except Exception: # noqa: BLE001 - the fake pipe may not take an image; the arming is what is under test
+ pass
+ assert armed and armed[0] == (STEPS, True)
+ backend.unload()
+
+
[email protected]("request_cache", [None, "auto"])
+def test_auto_kill_switch_restores_the_previous_auto(loop_runtime, monkeypatch, request_cache):
+ import core.inference.video as video_mod
+
+ monkeypatch.setenv(dcache.ENV_AUTO_STEP_SKIP, "0")
monkeypatch.setattr(
video_mod, "install_static_step_skip", lambda *a, **k: pytest.fail("auto picked static")
)
backend = VideoBackend()
status = backend.load_pipeline(WAN_5B, model_kind = "pipeline", transformer_cache = request_cache)
- # Auto resolves per speed tier (FBCache on max, else uncached); never to static.
+ # Auto resolves per speed tier (FBCache on max, else uncached), exactly as before.
assert status["transformer_cache"] in (None, "fbcache")
backend.unload()
@@ -423,26 +476,145 @@ def _load_h3(backend, transformer_cache):
)
-def test_modular_workflow_reports_a_static_ask_as_unsupported(fake_runtime):
+class _H3DiT:
+ """MiniMax-H3's denoiser: one call per step (guidance-distilled), returning (video velocity, audio velocity)."""
+
+ def __init__(self) -> None:
+ self.computed = 0
+
+ def __call__(self, *args, **kwargs):
+ # nn.Module.__call__ reads the INSTANCE forward, which is where the skip layer sits.
+ return self.forward(*args, **kwargs)
+
+ def forward(
+ self,
+ hidden_states = None,
+ audio_hidden_states = None,
+ timestep = None,
+ return_dict = True,
+ ):
+ self.computed += 1
+ return _Tensorish(self.computed), _Tensorish(-self.computed)
+
+
+class _H3LoopPipe:
+ """The modular denoise loop: transformer, then components.scheduler.step, once per step; no step callback."""
+
+ def __init__(self, inner) -> None:
+ object.__setattr__(self, "_inner", inner)
+ object.__setattr__(self, "transformer", _H3DiT())
+ object.__setattr__(self, "outputs", [])
+
+ def __getattr__(self, name):
+ return getattr(object.__getattribute__(self, "_inner"), name)
+
+ def __setattr__(self, name, value):
+ setattr(object.__getattribute__(self, "_inner"), name, value)
+
+ def __call__(
+ self,
+ *,
+ num_inference_steps = None,
+ num_frames = None,
+ **kwargs,
+ ):
+ for _ in range(int(num_inference_steps or 1)):
+ self.outputs.append(self.transformer(timestep = None, return_dict = False))
+ self.scheduler.step(object(), 0, object())
+ return {"videos": [[object() for _ in range(int(num_frames or 1))]], "audio": None}
+
+
+def h3_runtime(fake_runtime, monkeypatch):
+ from .test_video_backend import _FakeModularPipe
+
+ class _Loader:
+ @classmethod
+ def from_pretrained(cls, path, **kwargs):
+ _FakeModularPipeline.instance = _H3LoopPipe(_FakeModularPipe())
+ return _FakeModularPipeline.instance
+
+ monkeypatch.setattr(_FakeModularPipeline, "from_pretrained", _Loader.from_pretrained)
+ monkeypatch.setattr(
+ sys.modules["torch"], "is_tensor", lambda obj: isinstance(obj, _Tensorish), raising = False
+ )
+ monkeypatch.delenv(dcache.ENV_AUTO_STEP_SKIP, raising = False)
+ return _FakeModularPipeline
+
+
+def _h3_fwd_calls(pipe):
+ return pipe.transformer.computed
+
+
+def test_modular_workflow_engages_an_explicit_static_skip(h3_runtime, monkeypatch):
+ monkeypatch.setattr(dcache, "AUTO_STATIC_SKIP", {})
backend = VideoBackend()
status = _load_h3(backend, "static")
entry = status["resolved"]["transformer_cache"]
+ assert status["transformer_cache"] == "static"
+ assert entry["requested"] == "static" and entry["value"] == "static"
+ assert entry["status"] == "applied" and entry["reason"] == "requested"
+ pipe = h3_runtime.instance
+ assert isinstance(pipe.transformer.__dict__["forward"], ss.StaticStepSkip)
+ backend.generate(prompt = "a sloth", steps = 30, num_frames = 124, width = 960, height = 544)
+ plan = ss.static_schedule(30)
+ # One call per step, the per-call counter is the step index: exactly the planned skips are skipped.
+ assert _h3_fwd_calls(pipe) == sum(plan)
+ stats = backend.status()["transformer_cache_stats"]["stats"]
+ assert stats == {"calls": 30, "computed": sum(plan), "skipped": 30 - sum(plan)}
+ # Every skipped step still hands the loop a (video, audio) pair.
+ assert all(type(o) is tuple and len(o) == 2 for o in pipe.outputs)
+ backend.unload()
+ assert "forward" not in pipe.transformer.__dict__
+
+
+def test_modular_workflow_auto_follows_the_table_and_the_kill_switch(h3_runtime, monkeypatch):
+ monkeypatch.setattr(
+ dcache, "AUTO_STATIC_SKIP", {"minimaxai/minimax-h3": {"default": 2, "max": 2}}
+ )
+ backend = VideoBackend()
+ status = _load_h3(backend, None)
+ entry = status["resolved"]["transformer_cache"]
+ assert status["transformer_cache"] == "static"
+ assert entry["requested"] is None and entry["value"] == "static"
+ assert "UNSLOTH_DIFFUSION_AUTO_STEP_SKIP" in entry["reason"]
+ layer = h3_runtime.instance.transformer.__dict__["forward"]
+ assert layer.auto is True and layer.min_steps == dcache.AUTO_STATIC_MIN_STEPS
+ # A 16-step clip is under the auto floor: every step computes.
+ backend.generate(prompt = "a sloth", steps = 16, num_frames = 124, width = 960, height = 544)
+ assert _h3_fwd_calls(h3_runtime.instance) == 16
+ backend.unload()
+
+ monkeypatch.setenv(dcache.ENV_AUTO_STEP_SKIP, "0")
+ backend = VideoBackend()
+ status = _load_h3(backend, None)
assert status["transformer_cache"] is None
- assert entry["requested"] == "static" and entry["value"] == "off"
- assert entry["status"] == "unsupported" and "modular" in entry["reason"]
+ assert "forward" not in h3_runtime.instance.transformer.__dict__
backend.unload()
[email protected]("request_cache", [None, "off", "fbcache", "bogus"])
-def test_modular_workflow_keeps_its_record_for_every_other_ask(fake_runtime, request_cache):
[email protected]("request_cache", ["fbcache", "bogus"])
+def test_modular_workflow_reports_other_caches_as_unsupported(h3_runtime, request_cache):
backend = VideoBackend()
status = _load_h3(backend, request_cache)
entry = status["resolved"]["transformer_cache"]
- assert entry["requested"] is None and entry["value"] == "off"
- assert entry["reason"] == "not supported by this modular workflow"
+ assert status["transformer_cache"] is None
+ assert entry["requested"] == request_cache and entry["value"] == "off"
+ assert entry["status"] == "unsupported" and "static" in entry["reason"]
backend.unload()
+def test_modular_workflow_off_and_unlisted_auto_run_uncached(h3_runtime, monkeypatch):
+ monkeypatch.setattr(dcache, "AUTO_STATIC_SKIP", {})
+ for ask in ("off", None):
+ backend = VideoBackend()
+ status = _load_h3(backend, ask)
+ assert status["transformer_cache"] is None
+ assert status["resolved"]["transformer_cache"]["value"] == "off"
+ assert "forward" not in h3_runtime.instance.transformer.__dict__
+ backend.unload()
+
+
def test_video_api_accepts_static_and_reports_its_stats():
from pydantic import ValidationError
diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsx
index 111f150591d..de0eeb5304b 100644
--- a/studio/frontend/src/features/images/images-page.tsx
+++ b/studio/frontend/src/features/images/images-page.tsx
@@ -4672,7 +4672,7 @@ export function ImagesPage({
)}
<AdvancedSelect
label="Step cache"
- hint="First-Block-Cache reuses the transformer tail across steps for many-step models (~1.4x, small quality cost). Auto turns it on only on the Max speed tier at 20+ steps, re-checked per image. Static skip extrapolates every other middle step on a fixed schedule (12+ steps) and keeps the CUDA graph; never picked by Auto."
+ hint="Static skip extrapolates middle steps on a fixed schedule (12+ steps) and keeps the compile and CUDA graph. Auto uses it for text-to-image, at or above the step count it was measured at, on the models where it stayed close to the full render: Qwen-Image, Qwen-Image-2.1, FLUX.1 Krea dev, FLUX.2 klein base 4B on every speed tier but Off/Eager, and FLUX.1 dev and HunyuanImage 2.1 on Max only. First-Block-Cache reuses the transformer tail across steps (~1.4x, larger quality cost); Auto turns it on for other many-step models on Max only. UNSLOTH_DIFFUSION_AUTO_STEP_SKIP=0 stops Auto from picking Static skip."
badge={<ResolvedBadge status={status} controlKey="transformer_cache" />}
value={transformerCache}
onValueChange={(v) => setTransformerCache(v as typeof transformerCache)}
diff --git a/studio/frontend/src/features/video/video-page.tsx b/studio/frontend/src/features/video/video-page.tsx
index 74f5263ecbb..de9e81a8a44 100644
--- a/studio/frontend/src/features/video/video-page.tsx
+++ b/studio/frontend/src/features/video/video-page.tsx
@@ -3618,7 +3618,7 @@ function VideoGenerator({
)}
<AdvancedSelect
label="Step cache"
- hint="First-Block-Cache reuses the transformer tail across steps for many-step models (small quality cost). Auto turns it on only on the Max speed tier at 20+ steps, re-checked per clip. Static skip extrapolates every other middle step on a fixed schedule (12+ steps) and keeps the compile and CUDA graph; Wan2.2 A14B, LTX-2 and MiniMax-H3 run uncached. Never picked by Auto."
+ hint="Static skip extrapolates middle steps on a fixed schedule (12+ steps) and keeps the compile and CUDA graph; Wan2.2 A14B and LTX-2 run uncached. Auto uses it for text-to-video (no keyframes or references), at or above the step count it was measured at, on Wan2.2 TI2V 5B on every speed tier but Off/Eager, and on HunyuanVideo 1.5 and MiniMax-H3 on Max only. First-Block-Cache reuses the transformer tail across steps (larger quality cost); Auto turns it on for other many-step models on Max only. UNSLOTH_DIFFUSION_AUTO_STEP_SKIP=0 stops Auto from picking Static skip."
badge={<ResolvedBadge status={status} controlKey="transformer_cache" />}
value={transformerCache}
onValueChange={(v) => setTransformerCache(v as typeof transformerCache)}