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: compile VAEs by repeated block, one H3 graph per first render, vectorise the HunyuanVideo-1.5 VAE mask (#12061)

Daniel Han0771bdc387d3
diff --git a/studio/backend/core/inference/diffusion_dynamic_text.py b/studio/backend/core/inference/diffusion_dynamic_text.py
index eab28441571..cffb13c63dd 100644
--- a/studio/backend/core/inference/diffusion_dynamic_text.py
+++ b/studio/backend/core/inference/diffusion_dynamic_text.py
@@ -48,6 +48,11 @@ _FAMILY_SOURCES: dict[str, tuple[str, ...]] = {
"MiniMaxH3Transformer3DModel": _MINIMAX_H3_SOURCES,
}
+# Unbacked: a backed symbol specialises size 1, and H3's temb has 1 row on step 1, 2 after (a second compile).
+_FAMILY_UNBACKED: dict[str, tuple[str, ...]] = {
+ "MiniMaxH3Transformer3DModel": ("L['temb']",),
+}
+
def _compiler_config() -> Any:
try:
@@ -69,17 +74,44 @@ def supported() -> bool:
return _compiler_config() is not None
+def unbacked_supported() -> bool:
+ cfg = _compiler_config()
+ if cfg is None:
+ return False
+ try:
+ from torch._dynamo.variables import builder # noqa: PLC0415
+ getattr(cfg, "unbacked_sources")
+ except Exception: # noqa: BLE001 - knob absent on this build
+ return False
+ return callable(getattr(builder, "is_unbacked_source", None))
+
+
+def unbacked_sources_for(transformer: Any) -> tuple[str, ...]:
+ if not unbacked_supported():
+ return ()
+ return _FAMILY_UNBACKED.get(type(transformer).__name__, ())
+
+
def sources_for(transformer: Any) -> tuple[str, ...]:
- return _FAMILY_SOURCES.get(type(transformer).__name__, ())
+ # A source is dynamic OR unbacked; without the unbacked knob it stays on the dynamic list.
+ unbacked = set(unbacked_sources_for(transformer))
+ return tuple(
+ s for s in _FAMILY_SOURCES.get(type(transformer).__name__, ()) if s not in unbacked
+ )
def fingerprint(transformer: Any, dynamic: Any) -> Optional[str]:
+ if dynamic is True:
+ # dynamic=True already makes every dim dynamic; only the unbacked sources are armed (see install).
+ unbacked = unbacked_sources_for(transformer)
+ return "unbacked:" + ",".join(unbacked) if unbacked else None
if dynamic is not None:
return None
sources = sources_for(transformer)
if not sources or not supported():
return None
- return ",".join(sources)
+ unbacked = unbacked_sources_for(transformer)
+ return ",".join(sources) + (";unbacked:" + ",".join(unbacked) if unbacked else "")
def _merge(current: str, extra: tuple[str, ...]) -> str:
@@ -90,23 +122,38 @@ def _merge(current: str, extra: tuple[str, ...]) -> str:
return ",".join(parts)
-def install(transformer: Any, logger: Any = None) -> bool:
+def install(
+ transformer: Any,
+ logger: Any = None,
+ *,
+ dynamic: Any = None,
+) -> bool:
+ """Arm sources for a ``dynamic`` compile: None arms dynamic + unbacked, True only unbacked, False nothing."""
+ if dynamic is False:
+ return False
if getattr(transformer, "_unsloth_dynamic_text", None) is not None:
return True
- sources = sources_for(transformer)
+ unbacked = unbacked_sources_for(transformer)
+ sources = sources_for(transformer) if dynamic is None else ()
cfg = _compiler_config()
- if not sources or cfg is None:
+ if not (sources or unbacked) or cfg is None:
return False
- saved: list[Optional[str]] = []
+ saved: list[tuple[Optional[str], Optional[str]]] = []
def _enter(module: Any, args: Any) -> None:
prev = cfg.dynamic_sources
- saved.append(prev)
+ prev_unbacked = cfg.unbacked_sources if unbacked else None
+ saved.append((prev, prev_unbacked))
cfg.dynamic_sources = _merge(prev, sources)
+ if unbacked:
+ cfg.unbacked_sources = _merge(prev_unbacked, unbacked)
def _exit(module: Any, args: Any, output: Any) -> None:
if saved:
- cfg.dynamic_sources = saved.pop()
+ prev, prev_unbacked = saved.pop()
+ cfg.dynamic_sources = prev
+ if unbacked:
+ cfg.unbacked_sources = prev_unbacked
try:
pre = transformer.register_forward_pre_hook(_enter)
@@ -118,8 +165,10 @@ def install(transformer: Any, logger: Any = None) -> bool:
transformer._unsloth_dynamic_text = (pre, post)
if logger is not None:
logger.info(
- "diffusion.dynamic_text: prompt-length dims of %s compile dynamic from the first forward",
+ "diffusion.dynamic_text: %s of %s compile %s from the first forward",
+ "prompt-length dims" if sources else ",".join(unbacked),
type(transformer).__name__,
+ "dynamic" if sources else "unbacked",
)
return True
diff --git a/studio/backend/core/inference/diffusion_speed.py b/studio/backend/core/inference/diffusion_speed.py
index da8a6b81123..0f8bc246950 100644
--- a/studio/backend/core/inference/diffusion_speed.py
+++ b/studio/backend/core/inference/diffusion_speed.py
@@ -912,12 +912,12 @@ def _compile_repeated_blocks(
except Exception as exc: # noqa: BLE001 - optimisation only
_warn(logger, "compile_repeated_blocks", exc)
continue
- if dit_kwargs["dynamic"] is None:
- try:
- from . import diffusion_dynamic_text
- diffusion_dynamic_text.install(transformer, logger)
- except Exception as exc: # noqa: BLE001 - optimisation only
- _warn(logger, "dynamic text dims", exc)
+ # dynamic=True (dense H3) still needs the unbacked temb, else step 1 compiles a second graph.
+ try:
+ from . import diffusion_dynamic_text
+ diffusion_dynamic_text.install(transformer, logger, dynamic = dit_kwargs["dynamic"])
+ except Exception as exc: # noqa: BLE001 - optimisation only
+ _warn(logger, "dynamic text dims", exc)
# compile_repeated_blocks is lazy: inductor only runs on the first forward, inside generate(), where a lowering
# bug would fail the render. Guard every compiled block so such a failure drops this DiT to eager instead.
guard_compiled_blocks(transformer, logger)
@@ -1123,7 +1123,7 @@ def settle_compile_fallback(
dual-DiT load whose second expert still compiles keeps the LoRA gate and the compile-cache shape registry. Returns
the recorded failure, or None when nothing fell back."""
dit_error = compile_fallback_error(pipe)
- vae_error = getattr(getattr(pipe, "vae", None), "_unsloth_compile_decode_error", None)
+ vae_error = _vae_compile_error(getattr(pipe, "vae", None))
fallback = dit_error or vae_error
if not fallback:
return None
@@ -1223,6 +1223,9 @@ def _vae_decode_compile_allowed(pipe: Any, speed_mode: str) -> bool:
return False
if _denoiser_unet(pipe) is not None:
return True
+ # H3's fused decoder never calls the blocks, so compiling them would be reported but never run.
+ if getattr(getattr(pipe, "vae", None), "_unsloth_decode_blocks_bypassed", False):
+ return False
raw = os.environ.get(COMPILE_VAE_ENV, "").strip().lower()
if raw in _VAE_FALSE_TOKENS:
return False
@@ -1352,12 +1355,17 @@ def _compile_vae_decode(
decode = getattr(owner, "decode", None) if vae is not None else None
if not callable(decode):
return False
+ # A regional block guard does not clear _unsloth_compiled_decode when it falls back, so the error is read first.
+ if _vae_compile_error(vae):
+ return False
# A dual-DiT family calls apply_speed_optims twice over the same pipe.
if getattr(vae, "_unsloth_compiled_decode", False):
return True
if getattr(vae, "_unsloth_compile_decode_error", None):
return False
_install_inductor_backports(logger)
+ if _vae_declares_repeated_blocks(vae):
+ return _compile_vae_regionally(vae, logger, max_autotune = max_autotune)
try:
import torch
@@ -1376,6 +1384,44 @@ def _compile_vae_decode(
return False
+def _vae_declares_repeated_blocks(vae: Any) -> bool:
+ try:
+ return bool(getattr(vae, "_repeated_blocks", None)) and callable(
+ getattr(vae, "compile_repeated_blocks", None)
+ )
+ except Exception: # noqa: BLE001
+ return False
+
+
+def _compile_vae_regionally(
+ vae: Any,
+ logger: Any,
+ max_autotune: bool = False,
+) -> bool:
+ """Compile the VAE's repeated block, not ``decode``: a tiled decode unrolls its Python tile loop into one graph
+ (RecursionError static, CantSplit dynamic on MiniMax-H3); a block sees one fixed-shape tile."""
+ try:
+ kwargs: dict[str, Any] = {"fullgraph": False, "dynamic": False}
+ if max_autotune:
+ kwargs["mode"] = "max-autotune-no-cudagraphs"
+ vae.compile_repeated_blocks(**kwargs)
+ guard_compiled_blocks(vae, logger)
+ vae._unsloth_compiled_decode = True
+ return True
+ except Exception as exc: # noqa: BLE001 - optimisation only
+ _warn(logger, "vae regional compile", exc)
+ return False
+
+
+def _vae_compile_error(vae: Any) -> Optional[str]:
+ """The decode-compile failure a VAE fell back from: the whole-decode wrapper's, or a regional block guard's."""
+ error = getattr(vae, "_unsloth_compile_decode_error", None)
+ if error:
+ return error
+ guard = getattr(vae, "_unsloth_compile_guard", None)
+ return getattr(guard, "error", None) if guard is not None else None
+
+
def _enable_cudnn_benchmark(logger: Any) -> bool:
try:
import torch
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index ed3bdc24ddc..152d6b6ba99 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -5438,6 +5438,11 @@ class VideoBackend:
# Sets a flag the pipelines read when they first build their frequency tables, so it need only happen before
# generation, not before placement.
force_float32_rope(pipe, target, logger = logger)
+ # HunyuanVideo-1.5 VAE only: same mask values, so bit-identical, but held off on SPEED_OFF like the trim above.
+ hv15_mask_engaged = False
+ if effective_speed != SPEED_OFF:
+ from .video_hv15_vae import install_vectorised_causal_mask
+ hv15_mask_engaged = install_vectorised_causal_mask(pipe, logger = logger) > 0
speed_optims: tuple = ()
for view in views:
# Both helpers act on ``view.transformer``; call once per view (engaged values match, so record the first).
@@ -5488,6 +5493,8 @@ class VideoBackend:
speed_optims = tuple(k for k, v in applied.items() if v)
if attention_trim_engaged:
speed_optims += ("hunyuan_attn_trim",)
+ if hv15_mask_engaged:
+ speed_optims += ("hv15_vae_vector_mask",)
with self._generate_lock:
# A cancelled/superseded load must not place weights on a GPU the arbiter may have reassigned; recheck
# before placement.
@@ -6121,12 +6128,10 @@ class VideoBackend:
effective_speed = resolve_speed_mode(speed_mode, is_gguf = False, dense_default = SPEED_DEFAULT)
h3_vae_speed = effective_speed
if effective_speed == SPEED_MAX:
- # SPEED_MAX compiles static until a dimension changes. H3's packed sequence length carries the caption's
- # token rows, so a static graph recompiles on new prompts: measured 0.957-1.000 s/step static against
- # 1.000-1.040 dynamic, and two recompiles paid for it.
+ # max-autotune: 2.41 vs 2.45 s/step but 110 vs 48 s first render (~45 renders to break even).
logger.info(
"video.speed_mode: MiniMax-H3 runs the 'default' regional profile under max "
- "(a static graph retraces on the caption's contribution to the packed length)"
+ "(max-autotune's first-render cost is not repaid by its 2% faster step)"
)
effective_speed = SPEED_DEFAULT
if device != "cpu":
@@ -6258,6 +6263,13 @@ class VideoBackend:
# denoises with would keep native attention and stay uncompiled while the resolved record below still reported
# the requested profile -- and the pin above is what removes the eager downgrade that used to hide it.
speed_view = _denoiser_view(pipe, denoiser_component)
+ try:
+ from .video_minimax_h3_vae import reserve_h3_fast_decoder
+ reserve_h3_fast_decoder(
+ getattr(pipe, "vae", None), speed_mode = h3_vae_speed, workflow = workflow
+ )
+ except Exception: # noqa: BLE001 -- optimisation only, never fail a load
+ pass
try:
attention_engaged = apply_attention_backend(
speed_view,
diff --git a/studio/backend/core/inference/video_hv15_vae.py b/studio/backend/core/inference/video_hv15_vae.py
new file mode 100644
index 00000000000..63877806c36
--- /dev/null
+++ b/studio/backend/core/inference/video_hv15_vae.py
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""HunyuanVideo-1.5 VAE: build the causal attention mask with one masked_fill instead of a Python loop.
+
+The stock per-row loop unrolls under compile into a graph inductor cannot schedule (RecursionError in
+``reorder_for_peak_memory``). Same values, bit-identical decode.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+_ATTN_BLOCK = "HunyuanVideo15AttnBlock"
+_VAE_CLASS = "AutoencoderKLHunyuanVideo15"
+# The stock body this replaces; a diffusers release that rewrites it keeps its own version.
+_STOCK_NEEDLES = ("for i in range(seq_len)", "mask[i, : (i_frame + 1) * n_hw] = 0")
+
+
+# One implementation for both installers: the fused VAE path (CUDA + Triton) patches the same method with it.
+from .diffusion_vae_fused import _hv_causal_mask as causal_attention_mask # noqa: E402
+
+
+def _stock_loop(cls: type) -> bool:
+ fn = cls.__dict__.get("prepare_causal_attention_mask")
+ fn = getattr(fn, "__func__", fn)
+ try:
+ src = inspect.getsource(fn)
+ except (OSError, TypeError):
+ return False
+ return all(n in src for n in _STOCK_NEEDLES)
+
+
+def install_vectorised_causal_mask(pipe: Any, logger: Any = None) -> int:
+ """Patch each HV1.5 VAE attention block instance of ``pipe``; returns the count patched. Never raises."""
+ vae = getattr(pipe, "vae", None)
+ if vae is None or type(vae).__name__ != _VAE_CLASS:
+ return 0
+ patched = 0
+ try:
+ for module in vae.modules():
+ cls = type(module)
+ if cls.__name__ != _ATTN_BLOCK or not _stock_loop(cls):
+ continue
+ # A plain function on the instance is not bound, so ``self.prepare_causal_attention_mask(...)`` calls it
+ # with the staticmethod's own arguments.
+ module.prepare_causal_attention_mask = causal_attention_mask
+ patched += 1
+ except Exception as exc: # noqa: BLE001 - optimisation only
+ if logger is not None:
+ logger.warning("video.hv15_vae_mask: install failed, keeping the stock mask: %s", exc)
+ return 0
+ if patched and logger is not None:
+ logger.info(
+ "video.hv15_vae_mask: vectorised causal mask on %d VAE attention block(s)", patched
+ )
+ return patched
diff --git a/studio/backend/core/inference/video_minimax_h3_vae.py b/studio/backend/core/inference/video_minimax_h3_vae.py
index 6ca74dfd5b8..3f71a561250 100644
--- a/studio/backend/core/inference/video_minimax_h3_vae.py
+++ b/studio/backend/core/inference/video_minimax_h3_vae.py
@@ -1259,6 +1259,27 @@ def cuda_fast_path_available(vae: Any = None) -> bool:
return _triton_version_ok() and _kernels() is not None and _triton_jit_toolchain_ok()
+def reserve_h3_fast_decoder(
+ vae: Any,
+ *,
+ speed_mode: Optional[str],
+ workflow: Optional[str] = None,
+) -> bool:
+ """Mark ``vae`` before apply_speed_optims when the fused decoder will engage, so its block compile is skipped."""
+ try:
+ engages = (
+ vae is not None
+ and LEVER_FUSED_DECODER in plan_h3_vae_levers(speed_mode, workflow = workflow)
+ and _decoder_fusable(getattr(vae, "decoder", None))
+ and cuda_fast_path_available(vae)
+ )
+ if engages:
+ vae._unsloth_decode_blocks_bypassed = True
+ return bool(engages)
+ except Exception: # noqa: BLE001 - optimisation only
+ return False
+
+
def apply_h3_vae_speedups(
vae: Any,
*,
diff --git a/studio/backend/tests/test_diffusion_dynamic_text.py b/studio/backend/tests/test_diffusion_dynamic_text.py
index f965d169268..79e6bbd94a8 100644
--- a/studio/backend/tests/test_diffusion_dynamic_text.py
+++ b/studio/backend/tests/test_diffusion_dynamic_text.py
@@ -3,6 +3,8 @@
from __future__ import annotations
+import types
+
import pytest
torch = pytest.importorskip("torch")
@@ -215,10 +217,10 @@ def test_torch_that_reads_the_allowlist_once_is_not_armed(monkeypatch):
class MiniMaxH3Transformer3DModel(torch.nn.Module):
- def __init__(self):
+ def __init__(self, dynamic = None):
super().__init__()
self.seen = None
- self.block = torch.compile(self._block, backend = "eager", dynamic = None)
+ self.block = torch.compile(self._block, backend = "eager", dynamic = dynamic)
@staticmethod
def _block(hidden_states, temb, adaln_indices, rotary_emb):
@@ -227,6 +229,7 @@ class MiniMaxH3Transformer3DModel(torch.nn.Module):
def forward(self, seq_len, n_timesteps):
self.seen = _cfg().dynamic_sources
+ self.seen_unbacked = getattr(_cfg(), "unbacked_sources", "")
hidden_states = torch.randn(1, seq_len, 8)
temb = torch.randn(n_timesteps, 8)
adaln_indices = torch.arange(seq_len) % n_timesteps
@@ -244,10 +247,16 @@ def test_minimax_h3_packed_length_is_armed():
"L['adaln_indices']",
"L['rotary_emb'][0]",
"L['rotary_emb'][1]",
- "L['temb']",
):
assert name in seen
+ # temb is unbacked where torch has the knob, else dynamic: never both, never neither
+ unbacked = [s for s in (m.seen_unbacked or "").split(",") if s]
+ assert ("L['temb']" in seen) != ("L['temb']" in unbacked)
+ assert ("L['temb']" in unbacked) == dt.unbacked_supported()
dt.uninstall(m)
+ assert _cfg().dynamic_sources == "" or "L['temb']" not in _cfg().dynamic_sources
+ if dt.unbacked_supported():
+ assert "L['temb']" not in _cfg().unbacked_sources
def test_minimax_h3_new_caption_and_i2v_reuse_the_first_graphs():
@@ -270,3 +279,143 @@ def test_minimax_h3_new_caption_and_i2v_reuse_the_first_graphs():
assert graphs_per_render(False)[2:] != [0, 0, 0]
assert graphs_per_render(True)[2:] == [0, 0, 0]
+
+
+ not dt.unbacked_supported(), reason = "torch lacks compiler.config.unbacked_sources"
+)
+def test_minimax_h3_first_render_compiles_the_block_once():
+ """temb has 1 row on the first step and 2 after it: a backed symbol specialises the 1 and compiles twice."""
+ from torch._dynamo.utils import counters
+
+ torch._dynamo.reset()
+ counters.clear()
+ m = MiniMaxH3Transformer3DModel()
+ assert dt.install(m)
+ try:
+ for render in ((100, 1), (100, 2), (104, 1), (130, 3)):
+ m(*render)
+ assert counters["stats"]["unique_graphs"] == 1
+ finally:
+ dt.uninstall(m)
+ torch._dynamo.reset()
+
+
+def test_unbacked_list_is_restored_after_forward():
+ if not dt.unbacked_supported():
+ pytest.skip("torch lacks compiler.config.unbacked_sources")
+ cfg = _cfg()
+ before = cfg.unbacked_sources
+ try:
+ cfg.unbacked_sources = "L['user_thing']"
+ m = MiniMaxH3Transformer3DModel()
+ dt.install(m)
+ m(12, 1)
+ assert m.seen_unbacked.split(",") == ["L['user_thing']", "L['temb']"]
+ assert cfg.unbacked_sources == "L['user_thing']"
+ dt.uninstall(m)
+ finally:
+ cfg.unbacked_sources = before
+
+
+def test_fingerprint_keys_on_the_unbacked_list(monkeypatch):
+ m = MiniMaxH3Transformer3DModel()
+ fp = dt.fingerprint(m, None)
+ assert fp
+ assert ("unbacked:L['temb']" in fp) == dt.unbacked_supported()
+ monkeypatch.setattr(dt, "unbacked_supported", lambda: False)
+ fp_old = dt.fingerprint(m, None)
+ assert "unbacked" not in fp_old and "L['temb']" in fp_old
+
+
+def test_dense_h3_dynamic_true_arms_only_the_unbacked_temb():
+ """A dense (non-torchao) H3 compiles with dynamic=True: every dim is already dynamic, only temb must go unbacked."""
+ m = MiniMaxH3Transformer3DModel(dynamic = True)
+ before = _cfg().dynamic_sources
+ installed = dt.install(m, dynamic = True)
+ assert installed is dt.unbacked_supported()
+ try:
+ m(12, 2)
+ assert m.seen == before # the prompt-length list is left alone under dynamic=True
+ if dt.unbacked_supported():
+ assert "L['temb']" in m.seen_unbacked.split(",")
+ assert "L['temb']" not in (_cfg().unbacked_sources or "").split(",")
+ finally:
+ dt.uninstall(m)
+
+
+def test_static_compile_and_unarmed_families_are_not_hooked():
+ m = MiniMaxH3Transformer3DModel()
+ assert dt.install(m, dynamic = False) is False
+ assert not m._forward_pre_hooks
+ other = QwenImage21Transformer2DModel()
+ assert dt.install(other, dynamic = True) is False
+ assert not other._forward_pre_hooks
+
+
+def test_fingerprint_for_dynamic_true_keys_only_on_unbacked():
+ h3 = MiniMaxH3Transformer3DModel()
+ want = "unbacked:L['temb']" if dt.unbacked_supported() else None
+ assert dt.fingerprint(h3, True) == want
+ assert dt.fingerprint(h3, False) is None
+ assert dt.fingerprint(QwenImage21Transformer2DModel(), True) is None
+ assert dt.fingerprint(OtherTransformer(), True) is None
+
+
+ not dt.unbacked_supported(), reason = "torch lacks compiler.config.unbacked_sources"
+)
+def test_dense_h3_first_render_compiles_the_block_once():
+ """dynamic=True still specialises a backed size of 1, so without the unbacked temb the first render compiles
+ twice (temb 1 row, then 2)."""
+ from torch._dynamo.utils import counters
+
+ def graphs(install):
+ torch._dynamo.reset()
+ counters.clear()
+ m = MiniMaxH3Transformer3DModel(dynamic = True)
+ if install:
+ assert dt.install(m, dynamic = True)
+ try:
+ for render in ((100, 1), (100, 2), (104, 1), (130, 3)):
+ m(*render)
+ return counters["stats"]["unique_graphs"]
+ finally:
+ dt.uninstall(m)
+ torch._dynamo.reset()
+
+ assert graphs(False) == 2
+ assert graphs(True) == 1
+
+
+def test_regional_compile_of_a_dense_h3_arms_the_unbacked_temb(monkeypatch):
+ """Studio's own regional compile: a dense H3 resolves to dynamic=True and must still arm temb."""
+ from core.inference import diffusion_speed as ds
+
+ monkeypatch.setattr(ds, "_install_inductor_backports", lambda logger: False)
+ # _compile_repeated_blocks sets these process-wide; monkeypatch restores them after the test.
+ import torch._dynamo.config as dynamo_cfg
+ import torch._inductor.config as inductor_cfg
+
+ for cfg, name in (
+ (dynamo_cfg, "recompile_limit"),
+ (dynamo_cfg, "cache_size_limit"),
+ (inductor_cfg, "emulate_precision_casts"),
+ ):
+ if hasattr(cfg, name):
+ monkeypatch.setattr(cfg, name, getattr(cfg, name))
+ seen = {}
+
+ class MiniMaxH3Transformer3DModel(torch.nn.Module): # noqa: N801 - the family key is the class name
+ _repeated_blocks = ["MiniMaxH3TransformerBlock"]
+
+ def compile_repeated_blocks(self, **kwargs):
+ seen.update(kwargs)
+
+ m = MiniMaxH3Transformer3DModel()
+ try:
+ assert ds._compile_repeated_blocks(types.SimpleNamespace(transformer = m), None) is True
+ assert seen["dynamic"] is True
+ assert (getattr(m, "_unsloth_dynamic_text", None) is not None) is dt.unbacked_supported()
+ finally:
+ dt.uninstall(m)
diff --git a/studio/backend/tests/test_diffusion_speed.py b/studio/backend/tests/test_diffusion_speed.py
index 42889de8a47..9c94c416eda 100644
--- a/studio/backend/tests/test_diffusion_speed.py
+++ b/studio/backend/tests/test_diffusion_speed.py
@@ -2225,18 +2225,21 @@ def test_automatic_dynamic_compile_arms_the_prompt_length_allowlist(monkeypatch)
armed = []
monkeypatch.setattr(
- diffusion_dynamic_text, "install", lambda t, logger = None: armed.append(t) or True
+ diffusion_dynamic_text,
+ "install",
+ lambda t, logger = None, *, dynamic = None: armed.append((t, dynamic)) or True,
)
_stub_torch(monkeypatch)
pipe = _Pipe(with_compile = True, with_fuse = True)
apply_speed_optims(pipe, _target(), is_gguf = False, family = _family(), speed_mode = SPEED_MAX)
- assert armed == [pipe.transformer]
+ assert armed == [(pipe.transformer, None)]
+ # default compiles dynamic=True; install() gets that value and arms only unbacked sources (dense MiniMax-H3's temb)
armed.clear()
_stub_torch(monkeypatch)
pipe = _Pipe(with_compile = True)
apply_speed_optims(pipe, _target(), is_gguf = False, family = _family(), speed_mode = SPEED_DEFAULT)
- assert armed == []
+ assert armed == [(pipe.transformer, True)]
@pytest.mark.usefixtures("no_divisibility_proof")
diff --git a/studio/backend/tests/test_diffusion_vae_regional_compile.py b/studio/backend/tests/test_diffusion_vae_regional_compile.py
new file mode 100644
index 00000000000..84d8ffb6393
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_vae_regional_compile.py
@@ -0,0 +1,200 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""A VAE declaring ``_repeated_blocks`` (MiniMax-H3) compiles its repeated block, never the tiled ``decode``."""
+
+from __future__ import annotations
+
+import types
+
+import pytest
+
+torch = pytest.importorskip("torch")
+
+from core.inference import diffusion_speed as ds_mod # noqa: E402
+
+
+class _Blk(torch.nn.Module):
+ def forward(self, x):
+ return x + 1
+
+
+class _RegionalVae(torch.nn.Module):
+ """Mirrors diffusers ModelMixin.compile_repeated_blocks, with a stand-in compiled callable per block."""
+
+ _repeated_blocks = ["_Blk"]
+
+ def __init__(self, compiled_factory = None):
+ super().__init__()
+ self.blocks = torch.nn.ModuleList([_Blk(), _Blk()])
+ self.compile_kwargs = None
+ self.compiled_factory = compiled_factory
+ self.use_tiling = True
+
+ def compile_repeated_blocks(self, **kwargs):
+ self.compile_kwargs = kwargs
+ for m in self.modules():
+ if type(m).__name__ in self._repeated_blocks:
+ m._compiled_call_impl = (
+ self.compiled_factory(m) if self.compiled_factory else m._call_impl
+ )
+
+ def decode(self, z):
+ for b in self.blocks:
+ z = b(z)
+ return z
+
+
+def _inductor_error(msg):
+ try:
+ from torch._inductor.exc import InductorError # noqa: PLC0415
+ except ImportError: # torch < 2.7 raises BackendCompilerFailed instead
+ from torch._dynamo.exc import BackendCompilerFailed # noqa: PLC0415
+ return BackendCompilerFailed("inductor", RuntimeError(msg))
+ try:
+ return InductorError(RuntimeError(msg), None)
+ except TypeError: # constructor signature varies by torch version
+ return InductorError(msg)
+
+
+def test_regional_vae_compiles_blocks_static_and_keeps_decode():
+ vae = _RegionalVae()
+ pipe = types.SimpleNamespace(vae = vae)
+ assert ds_mod._compile_vae_decode(pipe, None) is True
+ assert vae.compile_kwargs == {"fullgraph": False, "dynamic": False}
+ # the tiled decode itself is never wrapped: the tile loop stays in Python
+ assert "decode" not in vae.__dict__
+ assert vae.decode(torch.zeros(1)).item() == 2
+ assert vae._unsloth_compiled_decode is True
+ # idempotent across the dual-DiT second call
+ vae.compile_kwargs = None
+ assert ds_mod._compile_vae_decode(pipe, None) is True
+ assert vae.compile_kwargs is None
+
+
+def test_regional_vae_max_tier_autotunes_without_cudagraphs():
+ vae = _RegionalVae()
+ assert ds_mod._compile_vae_decode(types.SimpleNamespace(vae = vae), None, max_autotune = True)
+ assert vae.compile_kwargs["mode"] == "max-autotune-no-cudagraphs"
+ assert vae.compile_kwargs["dynamic"] is False
+
+
+def test_regional_vae_tiling_does_not_force_eager():
+ # eager_when_tiled exists because a WHOLE-decode compile unrolls the tile loop; a block compile does not.
+ calls = {"compiled": 0}
+
+ def factory(m):
+ def compiled(*a, **k):
+ calls["compiled"] += 1
+ return m._call_impl(*a, **k)
+
+ return compiled
+
+ vae = _RegionalVae(factory)
+ assert ds_mod._compile_vae_decode(types.SimpleNamespace(vae = vae), None, eager_when_tiled = True)
+ vae.decode(torch.zeros(1))
+ assert calls["compiled"] == 2
+
+
+def test_regional_vae_compile_failure_falls_back_and_settles_status():
+ def factory(m):
+ def compiled(*a, **k):
+ raise _inductor_error("RecursionError: maximum recursion depth exceeded")
+
+ return compiled
+
+ vae = _RegionalVae(factory)
+ pipe = types.SimpleNamespace(vae = vae)
+ assert ds_mod._compile_vae_decode(pipe, None) is True
+ assert vae.decode(torch.zeros(1)).item() == 2 # eager answer, same value
+ state = types.SimpleNamespace(speed_optims = ("compiled", "compiled_vae_decode"))
+ reason = ds_mod.settle_compile_fallback(state, pipe)
+ assert "RecursionError" in reason or "BackendCompilerFailed" in reason # torch < 2.7 wraps it
+ assert "compiled_vae_decode" not in state.speed_optims
+ assert "compile_fallback_eager" in state.speed_optims
+ # a later apply_speed_optims pass does not retry the broken lowering
+ assert ds_mod._compile_vae_decode(pipe, None) is False
+ assert all(b._compiled_call_impl is None for b in vae.blocks)
+
+
+def test_vae_without_repeated_blocks_keeps_the_whole_decode_path(monkeypatch):
+ seen = {}
+
+ def fake_compile(fn, **kwargs):
+ seen.update(kwargs)
+ return fn
+
+ monkeypatch.setattr(torch, "compile", fake_compile)
+
+ class _PlainVae:
+ def decode(self, z):
+ return z
+
+ vae = _PlainVae()
+ assert ds_mod._compile_vae_decode(types.SimpleNamespace(vae = vae), None) is True
+ assert seen == {"fullgraph": False, "dynamic": True}
+ assert "decode" in vae.__dict__
+
+
+def test_empty_repeated_blocks_is_not_regional():
+ class _Empty(_RegionalVae):
+ _repeated_blocks = []
+
+ assert ds_mod._vae_declares_repeated_blocks(_Empty()) is False
+ assert ds_mod._vae_declares_repeated_blocks(_RegionalVae()) is True
+ assert ds_mod._vae_declares_repeated_blocks(None) is False
+
+
+ not torch.cuda.is_available() or not ds_mod.torch_compile_runtime_available(),
+ reason = "needs a GPU and a working inductor (Windows ROCm has no Triton)",
+)
+def test_tiny_minimax_h3_vae_decode_compiles_once_per_tile_shape():
+ """Real diffusers H3 VAE, tiny config: the tiled decode used to be one unrolled graph; now one block graph."""
+ diffusers = pytest.importorskip("diffusers")
+ cls = getattr(diffusers, "AutoencoderKLMiniMaxH3", None)
+ if cls is None:
+ pytest.skip("diffusers without MiniMax-H3")
+ from torch._dynamo.utils import counters
+
+ torch.manual_seed(0)
+ vae = (
+ cls(
+ block_out_channels = (8, 8, 8, 8, 8, 8),
+ decoder_num_layers = 2,
+ decoder_num_attention_heads = 2,
+ decoder_attention_head_dim = 16,
+ norm_num_groups = 4,
+ )
+ .cuda()
+ .eval()
+ )
+ # 2 x 2 tiles, 2 temporal chunks
+ z = torch.randn(1, 24, 7, 24, 24, device = "cuda")
+ with torch.no_grad():
+ ref = vae.decode(z, return_dict = False)[0]
+ torch._dynamo.reset()
+ counters.clear()
+ assert ds_mod._compile_vae_decode(types.SimpleNamespace(vae = vae), None) is True
+ with torch.no_grad():
+ out = vae.decode(z, return_dict = False)[0]
+ out2 = vae.decode(z, return_dict = False)[0]
+ assert ds_mod._vae_compile_error(vae) is None
+ assert counters["stats"]["unique_graphs"] == 1
+ assert out.shape == ref.shape
+ torch.testing.assert_close(out, ref, atol = 2e-3, rtol = 2e-3)
+ torch.testing.assert_close(out2, out)
+ torch._dynamo.reset()
+
+
+def test_a_vae_whose_blocks_the_fast_decoder_bypasses_is_not_compiled_even_when_forced(monkeypatch):
+ # MiniMax-H3's fused decoder reads block weights and never calls the blocks: compiling them would report
+ # compiled_vae_decode for a compile that never runs.
+ monkeypatch.setenv(ds_mod.COMPILE_VAE_ENV, "1")
+ vae = _RegionalVae()
+ pipe = types.SimpleNamespace(vae = vae)
+ assert ds_mod._vae_decode_compile_allowed(pipe, ds_mod.SPEED_DEFAULT) is True
+ vae._unsloth_decode_blocks_bypassed = True
+ for tier in (ds_mod.SPEED_DEFAULT, ds_mod.SPEED_MAX):
+ assert ds_mod._vae_decode_compile_allowed(pipe, tier) is False
+ assert ds_mod.vae_decode_compile_allowed(pipe, tier) is False
diff --git a/studio/backend/tests/test_video_hv15_vae.py b/studio/backend/tests/test_video_hv15_vae.py
new file mode 100644
index 00000000000..8d431febe47
--- /dev/null
+++ b/studio/backend/tests/test_video_hv15_vae.py
@@ -0,0 +1,158 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+import types
+
+import pytest
+
+torch = pytest.importorskip("torch")
+
+from core.inference import video_hv15_vae as hv # noqa: E402
+
+
+def _stock(
+ n_frame,
+ n_hw,
+ dtype,
+ device,
+ batch_size = None,
+):
+ seq_len = n_frame * n_hw
+ mask = torch.full((seq_len, seq_len), float("-inf"), dtype = dtype, device = device)
+ for i in range(seq_len):
+ i_frame = i // n_hw
+ mask[i, : (i_frame + 1) * n_hw] = 0
+ if batch_size is not None:
+ mask = mask.unsqueeze(0).expand(batch_size, -1, -1)
+ return mask
+
+
+class HunyuanVideo15AttnBlock(torch.nn.Module):
+ prepare_causal_attention_mask = staticmethod(_stock)
+
+ def forward(self, n_frame, n_hw):
+ return self.prepare_causal_attention_mask(n_frame, n_hw, torch.float32, "cpu", batch_size = 1)
+
+
+class AutoencoderKLHunyuanVideo15(torch.nn.Module):
+ def __init__(self):
+ super().__init__()
+ self.mid = HunyuanVideo15AttnBlock()
+
+
[email protected]("dtype", [torch.float32, torch.bfloat16, torch.float16])
[email protected]("n_frame,n_hw", [(1, 4), (3, 5), (7, 16), (2, 1)])
+def test_vectorised_mask_equals_the_stock_loop(dtype, n_frame, n_hw):
+ for batch in (None, 2):
+ want = _stock(n_frame, n_hw, dtype, "cpu", batch)
+ got = hv.causal_attention_mask(n_frame, n_hw, dtype, "cpu", batch)
+ assert got.dtype == want.dtype and got.shape == want.shape and got.stride() == want.stride()
+ assert torch.equal(got, want)
+
+
+def test_install_patches_instances_only():
+ vae = AutoencoderKLHunyuanVideo15()
+ assert hv.install_vectorised_causal_mask(types.SimpleNamespace(vae = vae)) == 1
+ assert vae.mid.prepare_causal_attention_mask is hv.causal_attention_mask
+ assert torch.equal(vae.mid(3, 4), _stock(3, 4, torch.float32, "cpu", 1))
+ # the class, and so every other pipe, keeps diffusers' own mask
+ assert HunyuanVideo15AttnBlock.__dict__["prepare_causal_attention_mask"].__func__ is _stock
+ assert HunyuanVideo15AttnBlock().prepare_causal_attention_mask is _stock
+
+
+def test_other_vaes_and_missing_vae_are_left_alone():
+ class AutoencoderKLWan(torch.nn.Module):
+ def __init__(self):
+ super().__init__()
+ self.mid = HunyuanVideo15AttnBlock()
+
+ wan = AutoencoderKLWan()
+ assert hv.install_vectorised_causal_mask(types.SimpleNamespace(vae = wan)) == 0
+ assert "prepare_causal_attention_mask" not in wan.mid.__dict__
+ assert hv.install_vectorised_causal_mask(types.SimpleNamespace()) == 0
+
+
+def test_a_rewritten_upstream_mask_is_not_replaced():
+ class HunyuanVideo15AttnBlock(torch.nn.Module): # noqa: N801 - mirrors the diffusers name
+ @staticmethod
+ def prepare_causal_attention_mask(
+ n_frame,
+ n_hw,
+ dtype,
+ device,
+ batch_size = None,
+ ):
+ return torch.zeros(1)
+
+ class AutoencoderKLHunyuanVideo15(torch.nn.Module): # noqa: N801
+ def __init__(self):
+ super().__init__()
+ self.mid = HunyuanVideo15AttnBlock()
+
+ vae = AutoencoderKLHunyuanVideo15()
+ assert hv.install_vectorised_causal_mask(types.SimpleNamespace(vae = vae)) == 0
+
+
+def test_real_diffusers_block_is_recognised_when_installed():
+ mod = pytest.importorskip("diffusers.models.autoencoders.autoencoder_kl_hunyuanvideo15")
+ cls = getattr(mod, "HunyuanVideo15AttnBlock", None)
+ if cls is None:
+ pytest.skip("diffusers without HunyuanVideo-1.5")
+ if not hv._stock_loop(cls):
+ pytest.skip("this diffusers already rewrote the mask")
+ for n_frame, n_hw in ((2, 3), (5, 8)):
+ assert torch.equal(
+ hv.causal_attention_mask(n_frame, n_hw, torch.bfloat16, "cpu", 1),
+ cls.prepare_causal_attention_mask(n_frame, n_hw, torch.bfloat16, "cpu", batch_size = 1),
+ )
+
+
+def test_mask_allocates_nothing_quadratic_besides_the_output():
+ """The stock loop allocates only the seq_len x seq_len mask; so must this (no seq_len x seq_len bool predicate)."""
+ from torch.utils._python_dispatch import TorchDispatchMode
+ from torch.utils._pytree import tree_leaves
+
+ class _Allocs(TorchDispatchMode):
+ def __init__(self):
+ super().__init__()
+ self.storages = []
+
+ def __torch_dispatch__(
+ self,
+ func,
+ types,
+ args = (),
+ kwargs = None,
+ ):
+ out = func(*args, **(kwargs or {}))
+ for t in tree_leaves(out):
+ if isinstance(t, torch.Tensor):
+ self.storages.append(
+ (t.untyped_storage().data_ptr(), t.untyped_storage().nbytes())
+ )
+ return out
+
+ n_frame, n_hw = 6, 32
+ seq_len = n_frame * n_hw
+ rec = _Allocs()
+ with rec:
+ mask = hv.causal_attention_mask(n_frame, n_hw, torch.bfloat16, "cpu", 2)
+ own = mask.untyped_storage().data_ptr()
+ assert [nb for ptr, nb in rec.storages if ptr != own and nb >= seq_len * seq_len] == []
+ assert torch.equal(mask, _stock(n_frame, n_hw, torch.bfloat16, "cpu", 2))
+
+
[email protected](not torch.cuda.is_available(), reason = "needs CUDA")
+def test_mask_peak_cuda_memory_is_the_output_alone():
+ n_frame, n_hw = 6, 256
+ seq_len = n_frame * n_hw
+ torch.cuda.synchronize()
+ torch.cuda.reset_peak_memory_stats()
+ base = torch.cuda.memory_allocated()
+ mask = hv.causal_attention_mask(n_frame, n_hw, torch.float32, "cuda", 1)
+ torch.cuda.synchronize()
+ extra = torch.cuda.max_memory_allocated() - base - mask.untyped_storage().nbytes()
+ # A seq_len x seq_len bool would be 2.36 MB here; the frame-level predicate is n_frame ** 2 bytes.
+ assert extra < seq_len * seq_len // 4
diff --git a/studio/backend/tests/test_video_minimax_h3_vae.py b/studio/backend/tests/test_video_minimax_h3_vae.py
index 5e4fb344e8e..dc45a7094c7 100644
--- a/studio/backend/tests/test_video_minimax_h3_vae.py
+++ b/studio/backend/tests/test_video_minimax_h3_vae.py
@@ -1214,3 +1214,64 @@ def test_int8_decoder_rotated_path_stays_close(monkeypatch):
ref = vae.decoder(z)
got = fast.decoder(z)
assert (got - ref).norm() / ref.norm() < 0.05
+
+
+def test_the_fused_decoder_reservation_turns_off_the_forced_vae_block_compile(monkeypatch):
+ # UNSLOTH_DIFFUSION_COMPILE_VAE=1 used to compile the decoder blocks the fused decoder never calls, and report it
+ from core.inference import diffusion_speed as ds_mod
+
+ monkeypatch.setenv(ds_mod.COMPILE_VAE_ENV, "1")
+ monkeypatch.delenv(H.H3_VAE_FAST_ENV, raising = False)
+ monkeypatch.setattr(H, "cuda_fast_path_available", lambda vae = None: True)
+ vae = _tiny_vae()
+ pipe = types.SimpleNamespace(vae = vae)
+ assert H.reserve_h3_fast_decoder(vae, speed_mode = "default", workflow = "t2va") is True
+ assert ds_mod._vae_decode_compile_allowed(pipe, "default") is False
+ # the reservation predicts exactly what apply_h3_vae_speedups then engages
+ assert H.LEVER_FUSED_DECODER in H.apply_h3_vae_speedups(
+ vae, speed_mode = "default", workflow = "t2va"
+ )
+
+
[email protected]("case", ["off", "fast_disabled", "no_fast_path"])
+def test_no_fused_decoder_keeps_the_forced_vae_block_compile(monkeypatch, case):
+ from core.inference import diffusion_speed as ds_mod
+
+ monkeypatch.setenv(ds_mod.COMPILE_VAE_ENV, "1")
+ monkeypatch.delenv(H.H3_VAE_FAST_ENV, raising = False)
+ monkeypatch.setattr(H, "cuda_fast_path_available", lambda vae = None: case != "no_fast_path")
+ if case == "fast_disabled":
+ monkeypatch.setenv(H.H3_VAE_FAST_ENV, "0")
+ vae = _tiny_vae()
+ speed = "off" if case == "off" else "default"
+ assert H.reserve_h3_fast_decoder(vae, speed_mode = speed, workflow = "t2va") is False
+ assert ds_mod._vae_decode_compile_allowed(types.SimpleNamespace(vae = vae), "default") is True
+
+
+def test_the_h3_load_reserves_the_fused_decoder_before_the_speed_optims():
+ import ast
+ import pathlib
+
+ tree = ast.parse((pathlib.Path(H.__file__).parent / "video.py").read_text(encoding = "utf-8"))
+ load = next(
+ n
+ for n in ast.walk(tree)
+ if isinstance(n, ast.FunctionDef) and n.name == "_load_h3_modular_pipeline"
+ )
+
+ def calls(name):
+ return [
+ c
+ for c in ast.walk(load)
+ if isinstance(c, ast.Call)
+ and (getattr(c.func, "id", None) == name or getattr(c.func, "attr", None) == name)
+ ]
+
+ (reserve,) = calls("reserve_h3_fast_decoder")
+ (apply_vae,) = calls("apply_h3_vae_speedups")
+ assert reserve.lineno < calls("apply_speed_optims")[0].lineno
+ assert {k.arg for k in reserve.keywords} == {"speed_mode", "workflow"}
+ # the same tier and workflow as the call that engages the fused decoder
+ for kw in ("speed_mode", "workflow"):
+ got = {k.arg: ast.dump(k.value) for k in reserve.keywords}[kw]
+ assert got == {k.arg: ast.dump(k.value) for k in apply_vae.keywords}[kw]