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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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 Noneif dynamic is not None:return Nonesources = 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 Falseif 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_unbackedtry: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 Truediff --git a/studio/backend/core/inference/diffusion_speed.py b/studio/backend/core/inference/diffusion_speed.pyindex 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. Returnsthe 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_errorif not fallback:return None@@ -1223,6 +1223,9 @@ def _vae_decode_compile_allowed(pipe: Any, speed_mode: str) -> bool:return Falseif _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 Falseraw = 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 Noneif 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 Trueif 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 torchdiff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.pyindex 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) > 0speed_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_speedif 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_DEFAULTif 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+ passtry: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.pynew file mode 100644index 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 patcheddiff --git a/studio/backend/core/inference/video_minimax_h3_vae.py b/studio/backend/core/inference/video_minimax_h3_vae.pyindex 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.pyindex 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 pytesttorch = 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)@staticmethoddef _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_sourcesdef 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.pyindex 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.pynew file mode 100644index 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 Falsediff --git a/studio/backend/tests/test_video_hv15_vae.py b/studio/backend/tests/test_video_hv15_vae.pynew file mode 100644index 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 // 4diff --git a/studio/backend/tests/test_video_minimax_h3_vae.py b/studio/backend/tests/test_video_minimax_h3_vae.pyindex 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]