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 the VAE decode for DiT families, from the NVFP4 time budget pass (#10889)
Daniel Han2f51b4c1e2c0
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.pyindex 32b476e412d..0cf66a33dfe 100644--- a/studio/backend/core/inference/diffusion.py+++ b/studio/backend/core/inference/diffusion.py@@ -146,6 +146,7 @@ from .diffusion_speed import (restore_backend_flags,settle_compile_fallback,snapshot_backend_flags,+ vae_decode_compile_allowed,)from .diffusion_attention import (apply_attention_backend,@@ -1386,8 +1387,7 @@ def _planned_quant_scheme(base_repo: Optional[str],prequant_path: Optional[str],) -> Optional[str]:- """The scheme the load will resolve: without the base and the checkpoint probe, plan and load- pick different schemes and a second denoiser is fetched inline."""+ """The scheme the load will resolve, asked with the same base and hosted-checkpoint probe as the load."""return select_transformer_quant_scheme(target,requested,@@ -6361,6 +6361,7 @@ class DiffusionBackend:"mode": "max-autotune-no-cudagraphs"if effective_speed == SPEED_MAXelse "default",+ "vae_decode": vae_decode_compile_allowed(pipe, effective_speed),},logger = logger,)@@ -6770,7 +6771,6 @@ class DiffusionBackend:check_cancelled()if transformer is not None:if scheme == TQ_NVFP4:- # Only M = 1 is knowable here; other shapes tune on their first eager GEMM.from .diffusion_nvfp4_linear import nvfp4_prewarmnvfp4_prewarm(transformer, (1,), logger = logger)pipe = self._assemble_pipe(@@ -8019,6 +8019,7 @@ class DiffusionBackend:and state.offload_policy == OFFLOAD_NONE,"dynamic": compile_dynamic(getattr(state.pipe, "transformer", None), True),"mode": "default",+ "vae_decode": vae_decode_compile_allowed(state.pipe, SPEED_DEFAULT),},logger = logger,)@@ -9015,7 +9016,7 @@ class DiffusionBackend:def _transformer_quant_backend(state: Any) -> Optional[str]:- """The NVFP4 kernel path read from the MODULE TREE, not the load's intent. Never raises."""+ """Which NVFP4 kernel path the loaded denoiser runs, read from the MODULE TREE, or None. Never raises."""if getattr(state, "transformer_quant", None) != TQ_NVFP4:return Nonetry:diff --git a/studio/backend/core/inference/diffusion_auto_policy.py b/studio/backend/core/inference/diffusion_auto_policy.pyindex ac866914efe..9db1b41d13e 100644--- a/studio/backend/core/inference/diffusion_auto_policy.py+++ b/studio/backend/core/inference/diffusion_auto_policy.py@@ -48,7 +48,7 @@ _POLICY_STEADY_FACTOR: dict[str, float] = {def policy_steady_factor(family: Any, base_repo: Optional[str] = None) -> Optional[float]:- """None keeps the whole-model factor. Never raises: a sizing estimate must not sink a load."""+ """The NVFP4 POLICY steady factor for ``(family, base_repo)``, or None. Never raises."""from .diffusion_nvfp4_flag import nvfp4_diffusion_enabledif not nvfp4_diffusion_enabled():@@ -306,7 +306,7 @@ def _hf_cache_free_mib() -> Optional[int]:def _has_usable_prequant(fam: Any, scheme: str, prequant_path: Optional[str], base_repo: Optional[str]) -> bool:- """False on any failure: "cannot tell" is not "yes"."""+ """Whether a hosted or operator-supplied prequant checkpoint for ``scheme`` is usable; False on failure."""try:from .diffusion_prequant import usable_prequant_sourcereturn (diff --git a/studio/backend/core/inference/diffusion_compile_cache.py b/studio/backend/core/inference/diffusion_compile_cache.pyindex 16969082eba..9ea0eb5c797 100644--- a/studio/backend/core/inference/diffusion_compile_cache.py+++ b/studio/backend/core/inference/diffusion_compile_cache.py@@ -309,7 +309,12 @@ def model_fingerprint("dtype": str(dtype),"quant": str(quant) if quant is not None else "none","attention_backend": str(attention_backend) if attention_backend is not None else "default",- "compile_kwargs": {k: compile_kwargs[k] for k in sorted(compile_kwargs)},+ # A False vae_decode is what every load keyed before the flag existed, so it is left out of the key.+ "compile_kwargs": {+ k: compile_kwargs[k]+ for k in sorted(compile_kwargs)+ if not (k == "vae_decode" and not compile_kwargs[k])+ },"shape_bucket": shape_bucket,}diff --git a/studio/backend/core/inference/diffusion_cuda_graph.py b/studio/backend/core/inference/diffusion_cuda_graph.pyindex fd4b834fafe..6a0e673fb63 100644--- a/studio/backend/core/inference/diffusion_cuda_graph.py+++ b/studio/backend/core/inference/diffusion_cuda_graph.py@@ -197,7 +197,6 @@ def _drop_pool_if_unused() -> None:def _nvfp4_flashinfer_linears(module: Any) -> list:- """Lazy import, so a build without the backend does not lose CUDA graphs over it."""try:from .diffusion_nvfp4_linear import is_nvfp4_flashinfer_linearexcept Exception: # noqa: BLE001 - no backend module, no NVFP4 layers to find@@ -213,7 +212,7 @@ def _nvfp4_flashinfer_linears(module: Any) -> list:def _protect_keyed(module: Any) -> bool:- """Only when the lever is armed AND this module holds NVFP4 layers, so fp8 keeps its graph count."""+ """Whether the graph key needs the precision branch: lever armed AND the module holds NVFP4 layers."""try:from .diffusion_nvfp4_protect import module_controllerif not module_controller(module).armed:@@ -229,12 +228,11 @@ def protect_graph_key(controller: Any = None) -> tuple:def _unbaked_nvfp4_layers(layers: list) -> list:- """A scale still being learned would be frozen by capture. Fail closed: no answer is unbaked."""return [name for name, layer in layers if not getattr(layer, "activation_scales_baked", False)]def _prewarm_token_counts(live: list) -> tuple:- """Candidate GEMM row counts (M), read off the warm-up's shapes; generous but bounded."""+ """Candidate GEMM row counts (M) from the warm-up's shapes, smallest first; bounded."""counts = {1}for tensor in live:try:diff --git a/studio/backend/core/inference/diffusion_inference_info.py b/studio/backend/core/inference/diffusion_inference_info.pyindex ff78f344909..959793c6160 100644--- a/studio/backend/core/inference/diffusion_inference_info.py+++ b/studio/backend/core/inference/diffusion_inference_info.py@@ -24,7 +24,6 @@ def _round1(value: float) -> float:def _family_base_repos() -> dict[str, str]:- """Family name -> DEFAULT base repo; a variant load prices itself via ``estimate_dense_quant``."""return {fam.name.strip().lower(): fam.base_repo for fam in _FAMILIES}diff --git a/studio/backend/core/inference/diffusion_nvfp4_bias.py b/studio/backend/core/inference/diffusion_nvfp4_bias.pyindex 3b53607bbc2..52900b0fdef 100644--- a/studio/backend/core/inference/diffusion_nvfp4_bias.py+++ b/studio/backend/core/inference/diffusion_nvfp4_bias.py@@ -1,8 +1,7 @@# SPDX-License-Identifier: AGPL-3.0-only# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0-"""Eager bias add for the NVFP4 output, bit-identical to ``add_`` (compile defers to ``add_``). CUTLASS's-fused FP4 bias epilogue is WRONG here: it adds into the fp32 accumulator before the rounding."""+"""Eager bias add for the NVFP4 output, bit-identical to ``add_``; CUTLASS's fused epilogue rounds wrong."""from __future__ import annotations@@ -64,7 +63,7 @@ def _eligible(out: Any, bias: Any) -> bool:def fused_bias_add_(out: Any, bias: Any):- """The device guard is load-bearing: Triton takes its device from the CURRENT context."""+ """``out += bias``, bit-identical to ``add_``; the device guard matters (Triton uses the CURRENT device)."""import torchif torch.compiler.is_compiling() or not fast_bias_enabled() or not _eligible(out, bias):diff --git a/studio/backend/core/inference/diffusion_nvfp4_dispatch.py b/studio/backend/core/inference/diffusion_nvfp4_dispatch.pyindex 0221ad6fc59..bd4481e3671 100644--- a/studio/backend/core/inference/diffusion_nvfp4_dispatch.py+++ b/studio/backend/core/inference/diffusion_nvfp4_dispatch.py@@ -203,15 +203,14 @@ def _fast_quantize(def _drop_transposed(key: int, ref: Any) -> None:- """Lock-free: a collection can land on a thread already holding the lock."""+ """Weakref callback; lock-free because a collection can land on a thread already holding the lock."""entry = _TRANSPOSED.get(key)if entry is not None and entry[0] is ref:_TRANSPOSED.pop(key, None)def transposed(t: Any):- """A ``.T`` released with the weight. Over ``t.detach()``: ``t.T`` keeps ``t`` alive via ``_base``,- so the weakref would never fire."""+ """A kept ``.T`` released with the weight; views ``t.detach()`` since ``t.T`` would pin ``t`` via ``_base``."""key = id(t)stamp = (t.data_ptr(), tuple(t.shape))entry = _TRANSPOSED.get(key)@@ -241,7 +240,7 @@ def gemm_plan(*,force: bool = False,):- """None (use ``mm_fp4``) for a COLD key under capture, where ``choose_one`` may profile into the graph."""+ """``(runner, tactic, workspace)``, or None (use ``mm_fp4``), also for a COLD key under capture."""from .diffusion_nvfp4_ops import _device_index, _is_capturingdevice = xq.devicediff --git a/studio/backend/core/inference/diffusion_nvfp4_gate.py b/studio/backend/core/inference/diffusion_nvfp4_gate.pyindex 1497308bd23..afa85dfa5c2 100644--- a/studio/backend/core/inference/diffusion_nvfp4_gate.py+++ b/studio/backend/core/inference/diffusion_nvfp4_gate.py@@ -1,9 +1,7 @@# SPDX-License-Identifier: AGPL-3.0-only# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0-"""The checked-in record of which NVFP4 checkpoints passed the accuracy gate, per family, base and-policy. Verdicts are re-derived, never trusted as stored. Torch-free: the smoke-probe child reads it.-"""+"""Checked-in NVFP4 accuracy-gate verdicts per (family, base, policy); torch-free (the smoke probe reads it)."""from __future__ import annotations@@ -75,7 +73,7 @@ def nvfp4_gate_records(*,path: Any = None,) -> tuple:- """Without a base there are none: a sibling base's verdict must never be inherited."""+ """Gate records for ``(family, base_repo)``, optionally pinned to ``policy_id``; none without a base."""fam = str(family or "").strip().lower()base = _canonical(base_repo)if not fam or not base:@@ -100,7 +98,7 @@ def nvfp4_gate_record(*,path: Any = None,) -> Optional[dict]:- """The first record only; whether nvfp4 is allowed is ``_passing_record``'s question."""+ """The first gate record for ``(family, base_repo)``, or None (not whether nvfp4 is allowed)."""matched = nvfp4_gate_records(family, base_repo, policy_id, path = path)return matched[0] if matched else None@@ -111,7 +109,7 @@ def _passing_records(*,path: Any = None,) -> tuple:- """Every PASS at the resolved policy: one checkpoint's failure must not mask a later pass."""+ """Every PASS for this family and base at the resolved policy; a failure must not mask a later pass."""try:from .diffusion_nvfp4_policy import resolve_policypolicy = resolve_policy(family, base_repo)@@ -157,7 +155,7 @@ def nvfp4_gate_backends(*,path: Any = None,) -> tuple:- """Every backend a passing record was measured on: one policy can hold artifacts on either."""+ """Every NVFP4 backend a passing record was measured on, lowercased, deduplicated, in file order."""backends: list[str] = []for record in _passing_records(family, base_repo, path = path):backend = str(record.get("backend") or "").strip().lower()diff --git a/studio/backend/core/inference/diffusion_nvfp4_linear.py b/studio/backend/core/inference/diffusion_nvfp4_linear.pyindex 0fa5801233e..1ab353b2735 100644--- a/studio/backend/core/inference/diffusion_nvfp4_linear.py+++ b/studio/backend/core/inference/diffusion_nvfp4_linear.py@@ -3,9 +3,9 @@"""The FlashInfer NVFP4 Linear, and the conversion that puts a hosted checkpoint onto it.-Nothing requantizes: torchao's payload IS FlashInfer's, with ``per_tensor_scale == 1 / w_gsf``.-The activation scale must be BAKED: calibrating it live is not capture-safe and latched flux to-black frames, so a layer with no baked scale is NOT converted.+ONE artifact, two backends. Nothing here requantizes: torchao's payload IS FlashInfer's, byte for+byte. The activation global scale is BAKED, never calibrated (not capture-safe, and the cause of the+flux black-frame latch), so a layer without one is NOT converted."""from __future__ import annotations@@ -55,7 +55,7 @@ def nvfp4_linear_class():from .diffusion_nvfp4_bias import fused_bias_add_class NVFP4FlashInferLinear(nn.Module):- """Runs inside a captured CUDA graph: no host synchronize, no device-value branch."""+ """NVFP4-weight Linear; the forward must stay capture-safe (no host sync, no device-value branch)."""def __init__(self,@@ -107,7 +107,6 @@ def nvfp4_linear_class():)out = F.linear(flat, weight)else:- # Zero graph breaks under compile; without it a flashinfer launch can hit the wrong card.with _device_guard(flat):xq, x_sf = torch.ops.unsloth_nvfp4.quantize(flat, self.a_gsf)out = torch.ops.unsloth_nvfp4.mm(@@ -221,7 +220,7 @@ def convert_nvfp4_backend(*,logger: Any = None,) -> int:- """All or nothing: one missing baked scale leaves the whole tree on torchao."""+ """Move every NVFP4 Linear onto FlashInfer, returning how many; all or nothing on a missing baked scale."""if backend != BACKEND_FLASHINFER:return 0scales = _baked_activation_scales(metadata)@@ -280,7 +279,7 @@ def nvfp4_prewarm(*,logger: Any = None,) -> int:- """Must run before any capture, which would bake in ``mm_fp4``'s default tactic."""+ """Autotune converted layers at these token counts BEFORE any capture, with the precision lever suspended."""from .diffusion_nvfp4_flag import nvfp4_diffusion_enabledif not nvfp4_diffusion_enabled():@@ -334,7 +333,7 @@ def _prewarm_shapes(modules, shapes, *, logger, tuned_box) -> None:def _iter_linears(transformer: Any):- """Keyed on feature counts: a converted layer has no ``weight``."""+ """Every Linear-like leaf, by feature counts (a converted layer has no ``weight``)."""for name, module in transformer.named_modules():if not name:continuediff --git a/studio/backend/core/inference/diffusion_nvfp4_ops.py b/studio/backend/core/inference/diffusion_nvfp4_ops.pyindex a36d78bb98f..91fdd11008c 100644--- a/studio/backend/core/inference/diffusion_nvfp4_ops.py+++ b/studio/backend/core/inference/diffusion_nvfp4_ops.py@@ -1,10 +1,7 @@# SPDX-License-Identifier: AGPL-3.0-only# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0-"""FlashInfer NVFP4 kernels as ``torch.library`` custom ops (so ``fullgraph = True`` works), plus-the backend decision. Fake impls must match FlashInfer's allocation EXACTLY: a wrong meta shape is-a silently mis-sized buffer. torch and flashinfer import lazily for torch-free hosts.-"""+"""FlashInfer NVFP4 kernels as custom ops (for ``fullgraph``); fake impls must match its allocation EXACTLY."""from __future__ import annotations@@ -47,12 +44,12 @@ def _swizzled_sf_numel(cols: int,row_size: int = 128,) -> int:- """Copied, not imported: a fake impl must not touch the FlashInfer JIT machinery."""+ """Swizzled scale-factor element count; copied so fake impls never touch the FlashInfer JIT."""return ((rows + row_size - 1) // row_size * row_size) * ((cols + 3) // 4 * 4)def _device_guard(t: Any):- """EVERY flashinfer call needs this: it has no device guard, and a foreign device bricks the card."""+ """``torch.cuda.device`` for the tensor's device; EVERY flashinfer call needs one (a foreign device bricks the card)."""import torchreturn torch.cuda.device(t.device)@@ -76,7 +73,7 @@ def _is_capturing() -> bool:def _barrier(device: Any):- """Per-device 1-element buffer, UNCACHED under capture: an allocation made in a capture dies with the graph."""+ """Per-device 1-element bf16 barrier buffer, uncached while capturing (it would die with the graph)."""import torchindex = _device_index(device)@@ -118,11 +115,8 @@ def _quantize_impl(x: Any, global_sf: Any):def _mm_impl(xq: Any, wq: Any, x_sf: Any, w_sf: Any, alpha: Any, n: int, backend: str):- """NVFP4 GEMM on a row-major ``[N, K/2]`` weight (a ``.T`` input would be an alias Dynamo must track).-- A kernel MUST run between the activation quantiser and this GEMM: cutlass launches with PDL but its- ``griddepcontrol`` is compiled out, so ``torch.empty`` alone is NOT enough; a one-element fill is.- """+ """NVFP4 GEMM on a row-major ``[N, K/2]`` weight. A kernel (any, not ``torch.empty``) MUST run between+ the quantiser and this GEMM: cutlass launches with PDL but ``griddepcontrol`` is compiled out."""import flashinferimport torch@@ -274,7 +268,7 @@ _LUT_CACHE: dict = {}def e2m1_lut(device: Any):- """Memoised so it is never ALLOCATED under a graph capture (valid only while recording)."""+ """The signed e2m1 decode table on ``device``, memoised so it is never first allocated during capture."""import torchkey = (str(device.type), device.index)@@ -296,8 +290,7 @@ def dequantize_nvfp4_weight(*,dtype: Any = None,):- """Dense ``[N, K]`` weight, TRANSIENT (never cache it). Arithmetic in torchao's order, so it- matches the unprotected step bit for bit."""+ """The packed NVFP4 operand as a TRANSIENT dense ``[N, K]`` weight, in torchao's exact arithmetic order."""import torchif dtype is None:@@ -319,12 +312,13 @@ def dequantize_nvfp4_weight(def sf_matrix_shape(rows: int, cols: int) -> tuple[int, int]:+ """FlashInfer's 2D view of a swizzled scale buffer (leading dim is padded, not ``rows``)."""padded_cols = (cols + 3) // 4 * 4return (_swizzled_sf_numel(rows, cols, 128) // padded_cols, padded_cols)def nvfp4_preflight(device: Any = None, *, refresh: bool = False) -> dict:- """A tiny guarded quantise + GEMM, memoised per device: only a JIT build proves FlashInfer runs."""+ """A tiny GUARDED 128x256 quantise + GEMM on ``device``, memoised per device. Never raises."""from .diffusion_nvfp4_flag import nvfp4_diffusion_enabledif not nvfp4_diffusion_enabled():@@ -501,7 +495,7 @@ def nvfp4_backend_reason(device: Any = None) -> str:def select_nvfp4_backend(device: Any = None) -> str:- """An explicit ``flashinfer`` that fails import, capability or preflight falls back to torchao."""+ """``"torchao"`` or ``"flashinfer"`` for ``device``; a failing explicit ``flashinfer`` falls back to torchao."""backend, reason = _resolve_backend(device)if backend != BACKEND_FLASHINFER and nvfp4_backend_env() == BACKEND_FLASHINFER:key = (str(device), reason)diff --git a/studio/backend/core/inference/diffusion_nvfp4_policy.py b/studio/backend/core/inference/diffusion_nvfp4_policy.pyindex a661001d70f..ddb643a574b 100644--- a/studio/backend/core/inference/diffusion_nvfp4_policy.py+++ b/studio/backend/core/inference/diffusion_nvfp4_policy.py@@ -3,8 +3,8 @@"""Per-layer NVFP4 policies for the image DiTs: a named set of layers at 4 bits over an fp8 model.-FAILS CLOSED: layers match by exact dotted SUFFIX and every rule asserts a count, so a diffusers-rename raises at build time instead of shipping precisions nobody measured.+A policy puts a named set of layers at 4 bits over fp8: a memory lever, not a speed win, so nvfp4+sits BELOW fp8 in the image auto order. FAILS CLOSED: exact suffixes and asserted counts per rule."""from __future__ import annotations@@ -22,12 +22,12 @@ NVFP4_POLICY_KIND = "unsloth_nvfp4_layer_policy_v1"class PolicyMismatch(ValueError):- """The model is not the one this policy was written for. Raised, never warned."""+ """The model this policy was applied to is not the one it was written for."""@dataclass(frozen = True)class Rule:- """``expect`` is asserted at assignment time; ``prefix`` narrows the rule to one subtree."""+ """``suffix`` -> ``precision``; ``expect`` is an asserted count, ``prefix`` narrows to one subtree."""suffix: strprecision: str@@ -35,7 +35,7 @@ class Rule:prefix: str = ""def matches(self, fqn: str) -> bool:- """Exact dotted suffix: ``norm.linear`` selects neither ``norm1.linear`` nor ``norm_out``."""+ """Exact dotted-suffix match: ``norm.linear`` does not select ``norm1.linear``."""if self.prefix and not fqn.startswith(self.prefix):return Falsereturn fqn == self.suffix or fqn.endswith("." + self.suffix)@@ -43,9 +43,7 @@ class Rule:@dataclass(frozen = True)class Admit:- """A linear the shared filter rejects that this policy quantises anyway, at an exact ``shape``.- Dropping the floor instead would admit ``t_embedder.mlp.*``, which must stay bf16- (``TimestepEmbedder.forward`` reads ``mlp[0].weight.dtype``)."""+ """A filter-rejected linear this policy quantises anyway; ``shape`` is exact so ``t_embedder.mlp.*`` stays bf16."""suffix: strshape: tuple@@ -57,7 +55,7 @@ class Admit:@dataclass(frozen = True)class NVFP4Policy:- """Keyed on lowercased ``base_repos``: a sibling checkpoint is different, ungated weights."""+ """One measured per-layer precision assignment, keyed on lowercased ``base_repos`` (never a sibling's)."""policy_id: strversion: int@@ -201,15 +199,13 @@ def policy_by_id(policy_id: Any) -> Optional[NVFP4Policy]:def policy_expected_counts(policy: NVFP4Policy) -> dict:- """Zero entries dropped: a Counter never records a precision no layer took."""return {str(key): int(value) for key, value in dict(policy.expected_counts).items() if int(value)}def resolve_policy(family: Any, base_repo: Any = None) -> Optional[NVFP4Policy]:- """Keyed on the BASE: an unnamed base answers None even where the family has one policy, or a- second gated base would hand every anonymous load the first one's precisions."""+ """The policy for ``(family, base_repo)``, or None; an unnamed base is None even if the family has one."""fam = str(family or "").strip().lower()if not fam:return None@@ -232,6 +228,7 @@ def assign_precisions(min_features: Optional[int] = None,require_divisible: Optional[int] = None,) -> dict:+ """``{fqn: precision}`` for EVERY Linear, or raise ``PolicyMismatch``; rules apply in order, first claim wins."""import torchfrom .diffusion_transformer_quant import (@@ -305,7 +302,6 @@ def policy_metadata(activation_scales_baked: bool = False,gptq: bool = False,) -> dict:- """Sorted for byte-stable builds; the fqn list is recorded, not re-derived from a drifting rule."""counts = Counter(assignment.values())return {NVFP4_POLICY_KEY: {@@ -323,11 +319,12 @@ def policy_metadata(def declares_policy(metadata: Any) -> bool:- """Keyed on the KEY: an unreadable block must refuse, not read as "no policy"."""+ """True when ``metadata`` has the policy KEY; an unreadable block must refuse, not read as "no policy"."""return isinstance(metadata, dict) and metadata.get(NVFP4_POLICY_KEY) not in (None, "")def policy_metadata_error(metadata: Any) -> Optional[str]:+ """Why ``metadata``'s declared policy breaks the contract, or None. Torch-free."""if not declares_policy(metadata):return Noneblock = metadata.get(NVFP4_POLICY_KEY)@@ -373,7 +370,7 @@ _EXPECTED_WEIGHT_CLASS = {def _verify_weight_types(transformer: Any, assignment: Mapping) -> None:- """Raise unless every layer holds its precision's weight class: torchao skips layers silently."""+ """Raise unless every assigned layer holds its precision's weight class (torchao can skip silently)."""wrong: list = []for fqn, module in transformer.named_modules():precision = assignment.get(fqn)@@ -400,7 +397,7 @@ def quantize_with_policy(fast_accum: Optional[bool] = None,logger: Any = None,) -> dict:- """NVFP4 pass first, then fp8 over plain Parameters only. A raise leaves it partly quantised."""+ """Apply ``policy`` in place via two disjoint ``quantize_`` passes, NVFP4 first; discard on a raise."""import torchfrom torchao.quantization import quantize_diff --git a/studio/backend/core/inference/diffusion_nvfp4_protect.py b/studio/backend/core/inference/diffusion_nvfp4_protect.pyindex 74168051c7f..472a24053c0 100644--- a/studio/backend/core/inference/diffusion_nvfp4_protect.py+++ b/studio/backend/core/inference/diffusion_nvfp4_protect.py@@ -3,8 +3,8 @@"""Per-step precision for the NVFP4 backend: which denoising steps run W4A16 instead of W4A4.-The step counter wraps ``pipe.scheduler.step`` (called once per step, after the forward). Off by-default: the protected set must be MEASURED per model, a borrowed one can do worse than none.+A protected step dequantises to a transient bf16 weight; the counter wraps ``pipe.scheduler.step``.+The set must be MEASURED per model (a copied set did worse than none), so it is off unless named."""from __future__ import annotations@@ -31,7 +31,7 @@ def protect_steps_env() -> str:def parse_protect_steps(spec: Any, total_steps: int) -> tuple:- """Out-of-range indices are dropped; a non-integer token DOES raise, never silently nothing."""+ """``spec`` resolved against ``total_steps``, sorted; out-of-range drops, a non-integer token raises."""total = int(total_steps)if total <= 0:return ()@@ -67,7 +67,7 @@ def parse_protect_steps(spec: Any, total_steps: int) -> tuple:class NVFP4StepController:- """``protected`` is a plain bool, never a property: Dynamo would compile one variant per STEP."""+ """Current step and whether it is protected; ``protected`` is a plain bool (a property recompiles per STEP)."""def __init__(self, spec: Any = None) -> None:self.spec: str = ""@@ -91,7 +91,7 @@ class NVFP4StepController:return len(self._layers)def configure(self, spec: Any) -> "NVFP4StepController":- """``armed`` is a compile guard: configure before the first forward."""+ """Set the schedule before the first forward: ``armed`` is a compile guard."""raw = "" if spec is None else str(spec).strip().lower()self.spec = "" if raw in _OFF_TOKENS else rawself.armed = bool(self.spec)@@ -172,7 +172,7 @@ def protect_generation(controller: Optional[NVFP4StepController] = None,logger: Any = None,):- """A no-op when the lever is off; a pipeline with no scheduler to count protects NOTHING."""+ """Drive ``controller`` across one generation, then restore; no scheduler protects NOTHING."""ctls = [controller] if controller is not None else pipeline_controllers(pipe)ctl = ctls[0]if not ctl.armed:@@ -252,6 +252,7 @@ def protect_graph_key(*,controller: Optional[NVFP4StepController] = None,) -> tuple:+ """CUDA-graph key suffix for the branch in flight (a graph records ONE branch), or ``()`` when off."""ctl = controller if controller is not None else module_controller(module)if not ctl.armed:return ()diff --git a/studio/backend/core/inference/diffusion_prequant.py b/studio/backend/core/inference/diffusion_prequant.pyindex b00acc04427..d6862b562ba 100644--- a/studio/backend/core/inference/diffusion_prequant.py+++ b/studio/backend/core/inference/diffusion_prequant.py@@ -56,7 +56,7 @@ DEFAULT_PREQUANT_COMPONENT = "transformer"def prequant_format_for(metadata: Any) -> str:- """The on-disk format tag for ``metadata``. v2 and v3 are mutually exclusive (one tag slot)."""+ """The format tag to stamp for ``metadata``; v2 and v3 share one tag slot, so declaring both is refused."""from .diffusion_convrot import declares_rotationfrom .diffusion_nvfp4_policy import declares_policy@@ -744,7 +744,6 @@ def declares_nvfp4_checkpoint(model_path: Optional[str]) -> bool:return raw.rstrip("/\\").lower().endswith("-nvfp4")-# Bump on any payload-order or hash change, so two recipes are never compared under one name.FINGERPRINT_ALGO = "md5-packed-v1"# Payload attrs per torchao class NAME, hash order; unlisted reads "not covered", never "equal".@@ -767,7 +766,7 @@ _FINGERPRINT_PAYLOAD: dict = {def _packed_bytes(tensor: Any, torch: Any) -> bytes:- """Raw bytes of ``tensor``; a uint8 view reinterprets, so fp8 / fp4 / bf16 hash exactly."""+ """``tensor``'s raw bytes via ``view(torch.uint8)``, exact for dtypes numpy cannot represent."""t = tensor.detach().contiguous()if t.dim() == 0:t = t.reshape(1)@@ -777,7 +776,7 @@ def _packed_bytes(tensor: Any, torch: Any) -> bytes:def _hash_packed_payload(tensor: Any, digest: Any, torch: Any) -> bool:- """Hash slot names + bytes into ``digest``; False if uncovered or no slot present."""+ """Feed one weight's packed payload (with attribute names) into ``digest``; False when uncovered."""names = _FINGERPRINT_PAYLOAD.get(type(tensor).__name__)if names is None:return False@@ -798,7 +797,7 @@ def _hash_packed_payload(tensor: Any, digest: Any, torch: Any) -> bool:def packed_weight_fingerprint(state_dict: Any, *, select: Any = None) -> dict:- """md5 of every ``.weight``'s packed bytes by fqn; not the pickle, so re-saves match."""+ """md5 of every quantized weight's packed payload by fqn (``select`` narrows it); unknown ones go under ``skipped``."""import hashlibimport torch@@ -842,7 +841,7 @@ def _fingerprint_mode() -> str:def _fingerprint_sampled(fqn: str) -> bool:- """Stable 1-in-8 by md5 of the fqn; ``hash()`` is randomised per process by PYTHONHASHSEED."""+ """Stable 1-in-8 by md5 of the name (``hash()`` is randomised per process)."""import hashlibreturn hashlib.md5(fqn.encode("utf-8")).digest()[0] % FINGERPRINT_SAMPLE_RATE == 0@@ -853,7 +852,7 @@ def _verify_packed_fingerprint(*,logger: Any = None,) -> bool:- """Refuse on a fingerprint mismatch; no block, or one this build cannot compute, passes."""+ """Check the artifact's packed fingerprint: a mismatch drops to dense, a missing or uncomputable block passes."""block = (metadata or {}).get("fingerprint")expected = (block or {}).get("modules") if isinstance(block, dict) else Noneif not expected:@@ -1113,8 +1112,9 @@ def load_prequantized_transformer(lands under huggingface_hub's import-time constant, so a mid-session cache change re-downloadsinto a root Unsloth no longer reads.- ``component`` is checked (experts share every other key); ``prepare_model`` may reshape before- ``load_state_dict``; a recorded ``diffusion_convrot`` always gets its online half installed.+ ``component`` must match the checkpoint's (MoE experts share every other field); ``prepare_model``+ runs between ``from_config`` and ``load_state_dict``, the one window to reshape the skeleton. A+ declared activation rotation is installed unconditionally: a miss renders wrong pixels silently.Returns the placed transformer, or None on any problem (missing / mismatched / unreadablecheckpoint, unsupported meta-init, or a rotation this build cannot apply exactly) so the caller@@ -1454,8 +1454,7 @@ _FLOAT8_TENSOR_CLASS = "Float8Tensor"def _fp8_activation_floor_present(state_dict: Any, logger: Any) -> bool:- """True unless some fp8 tensor was quantised with no activation lower bound. Only the first- FLOAT8 tensor is read: an NVFP4Tensor also has ``act_quant_kwargs`` but no ``hp_value_lb``."""+ """True unless the first Float8Tensor has no activation lower bound (by class: NVFP4Tensor lacks one too)."""from .diffusion_transformer_quant import TQ_FP8try:@@ -1522,8 +1521,7 @@ def _validate_activation_rotation(ckpt_format: Any, meta: Any, scheme: str, loggdef _validate_policy(ckpt_format: Any, meta: Any, scheme: str, logger: Any) -> bool:- """Reject a policy this build cannot reproduce EXACTLY: the weights do not say which layer got- which precision."""+ """Reject a checkpoint whose per-layer nvfp4 policy this build cannot reproduce EXACTLY."""from .diffusion_nvfp4_policy import (NVFP4_POLICY_KEY,declares_policy,@@ -1626,7 +1624,7 @@ def _validate_checkpoint(fast_accum: Optional[bool] = None,component: Optional[str] = None,) -> bool:- """Reject a wrong format / scheme / base / filter / denoiser; absent fields predate them."""+ """Reject a wrong format / scheme / base / filter / denoiser; absent ``min_features`` / ``fast_accum`` pass."""if not isinstance(ckpt, dict) or ckpt.get("format") not in PREQUANT_FORMATS:_warn(logger, scheme, ValueError("unrecognised pre-quant checkpoint format"))return Falsediff --git a/studio/backend/core/inference/diffusion_quant_pad.py b/studio/backend/core/inference/diffusion_quant_pad.pyindex 2a6ae4aa31c..33f8718de46 100644--- a/studio/backend/core/inference/diffusion_quant_pad.py+++ b/studio/backend/core/inference/diffusion_quant_pad.py@@ -16,30 +16,10 @@ whole conditioning front end. This is the alternative: pad the flattened row cou``pad_to``, run the GEMM, slice the result back. The module becomes compilable with no change tothe quantization config, and the rows the caller asked for are returned BITWISE unchanged.-Two properties make the padding exact rather than approximately exact, and both are load-bearing:-- * The pad rows REPLICATE row 0 rather than being zeros. An all-zero row has amax 0, hence- scale 0, hence a division by zero in the activation quantizer. That NaN would stay confined- to a row that is then discarded, but replication costs the same and keeps the intermediate- finite -- and finite intermediates are what let the equality be checked at all.- * The activation scale is PER ROW (torchao quantizes the activations of- ``Int8DynamicActivationInt8WeightConfig`` with ``_int8_symm_per_token_...``), so each kept- row's scale is computed from that row alone and extra rows cannot perturb it. Replicating- row 0 happens to leave a per-TENSOR amax unchanged too, so the two properties overlap for- that particular granularity -- but a granularity calibrated on anything other than a plain- amax (a percentile, a mean, a running observer) would shift under duplicated rows and- silently change every output. ``wrap_small_m_linears`` therefore refuses to wrap a quantized- Linear whose activation granularity it cannot prove is per row, and RAISES rather than- quietly leaving it unwrapped: a half-padded transformer is the one outcome worse than either- end state, since it compiles on the modules that were wrapped and crashes on the rest.--Ordering invariant: wrapping REPARENTS the Linear, so it must happen AFTER a state dict is-loaded and BEFORE nothing in particular. The offline prequant builder-(``scripts/build_prequant_checkpoint.py``) drives ``quantize_`` directly and saves the state-dict, so it never sees a wrapper. As a second line of defence ``PadToMinM`` is state-dict-TRANSPARENT: it saves and loads its inner Linear's tensors under the wrapper's own prefix, so a-checkpoint written from a wrapped transformer still names ``context_embedder.weight`` rather-than ``context_embedder.inner.weight`` and stays loadable by an unwrapped tree.+Exact because pad rows REPLICATE row 0 (a zero row gives scale 0 and NaN) and the activation scale+is PER ROW; ``wrap_small_m_linears`` RAISES on a granularity it cannot prove per row, since a+half-padded transformer crashes. ``ZeroRowSafeLinear`` answers an EMPTY activation itself (nvfp4).+Wrapping reparents the Linear, so do it AFTER loading; ``PadToMinM`` is state-dict transparent."""from __future__ import annotations@@ -220,7 +200,7 @@ class PadToMinM(nn.Module):class ZeroRowSafeLinear(nn.Module):- """Answer an EMPTY activation here: torchao NVFP4's whole-input ``max()`` raises on it."""+ """Answer an EMPTY activation here: torchao NVFP4's global-scale ``max()`` raises on ``numel() == 0``."""def __init__(self, inner: nn.Linear) -> None:super().__init__()@@ -277,7 +257,7 @@ class ZeroRowSafeLinear(nn.Module):def wrap_zero_row_linears(model: nn.Module, fqns: Iterable[str]) -> tuple[str, ...]:- """Wrap each quantized Linear in ``fqns`` with ``ZeroRowSafeLinear`` (idempotent)."""+ """Wrap each Linear in ``fqns`` in a ``ZeroRowSafeLinear``; idempotent, and never stacks on ``PadToMinM``."""done: list[str] = []for fqn in sorted(set(fqns)):parent_name, _, leaf = fqn.rpartition(".")diff --git a/studio/backend/core/inference/diffusion_speed.py b/studio/backend/core/inference/diffusion_speed.pyindex 38dd2097301..39c1a2ee1f2 100644--- a/studio/backend/core/inference/diffusion_speed.py+++ b/studio/backend/core/inference/diffusion_speed.py@@ -22,9 +22,10 @@ this). On opt-in it applies the near-lossless speedups in the diffusers-recommenthe Q4 noise floor) plus TF32 matmul and fused QKV.``default`` is the cheap always-amortising compile; ``max`` pays the larger regional tax for the-bigger warm speedup. The compiled dequant is skipped under ``max`` (the regional compile subsumes-it; a separate compiled dequant would break that graph). ``supports_torch_compile`` + bf16/CUDA-(or fp16 on Turing+ NVIDIA) checks gate regional compile.+bigger warm speedup. The compiled dequant is skipped under ``max``, which subsumes it.++Knobs, safe unset: ``UNSLOTH_DIFFUSION_COMPILE_VAE=auto|0|1`` (DiT VAE decode compile; ``auto`` = ``max`` only),+and in their own modules ``UNSLOTH_NVFP4_FAST_BIAS``, ``_FAST_DISPATCH``, ``_ZERO_BUFFER`` and ``_BACKEND``.The flags this flips (TF32, cudnn.benchmark) are PROCESS-WIDE, so ``snapshot_backend_flags`` /``restore_backend_flags`` let the caller restore prior values at unload, keeping a later ``off``@@ -434,10 +435,14 @@ def apply_speed_optims(offload_active = offload_active,)- # A compiled U-Net family also compiles the VAE decode (4.98 to 4.25 s over 4 images, LPIPS unchanged). DiTs skip- # it. dynamic=True keeps it resolution-robust.- if applied["compiled"] and _denoiser_unet(pipe) is not None:- applied["compiled_vae_decode"] = _compile_vae_decode(pipe, logger)+ if applied["compiled"] and _vae_decode_compile_allowed(pipe, mode):+ # A U-Net keeps the decode recipe its whole-module compile was measured with.+ applied["compiled_vae_decode"] = _compile_vae_decode(+ pipe,+ logger,+ max_autotune = mode == SPEED_MAX and _denoiser_unet(pipe) is None,+ eager_when_tiled = _vae_eager_when_tiled(pipe),+ )if mode == SPEED_MAX:if on_cuda:@@ -513,13 +518,7 @@ def _denoiser_unet(pipe: Any) -> Any:def compiled_shapes_are_static(pipe: Any, speed_mode: Optional[str]) -> bool:- """Whether this load's compiled artifacts are per-(width, height, batch).-- ``max`` compiles regional DiT blocks with automatic dynamic (static until a dimension changes, then one- generalised graph; tracked by graph count, not shape) and U-Net whole-module is always static;- ``default`` DiT compiles dynamic=True (one artifact across shapes) EXCEPT a stream-merging DiT,- static there (see ``_STREAM_MERGING_BLOCKS``). The compile-cache layer keys on this to re-save its- bundle when a session hits an uncovered shape."""+ """Whether this load's compiled artifacts are per-(width, height, batch); the compile cache keys on it."""mode = normalize_speed_mode(speed_mode)if mode == SPEED_MAX:# An auto-dynamic DiT generalises a dimension once and then reuses that graph for unseen values, so a new@@ -559,7 +558,7 @@ _STREAM_MERGE_SOURCE = re.compile(@lru_cache(maxsize = None)def _class_merges_streams(cls: type, broad: bool = False) -> bool:- """``broad`` is an argument, not an env read in the body, so the memo cannot outlive it."""+ """Whether one repeated-block CLASS needs a static compile; ``broad`` is an argument so the memo keys on it."""if cls.__name__ in _STREAM_MERGING_BLOCKS:return Trueif not broad:@@ -876,7 +875,9 @@ def settle_compile_fallback(Adds ``compile_fallback_eager`` once, and drops ``compiled`` only when NO guarded DiT still runs compiled, so adual-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."""- fallback = compile_fallback_error(pipe)+ dit_error = compile_fallback_error(pipe)+ vae_error = getattr(getattr(pipe, "vae", None), "_unsloth_compile_decode_error", None)+ fallback = dit_error or vae_errorif not fallback:return Noneoptims = tuple(getattr(state, "speed_optims", None) or ())@@ -885,8 +886,10 @@ def settle_compile_fallback(updated.append("compile_fallback_eager")if logger is not None:logger.warning("diffusion.speed: regional compile fell back to eager: %s", fallback)- if "compiled" in updated and not compiled_dits_active(pipe):+ if dit_error and "compiled" in updated and not compiled_dits_active(pipe):updated.remove("compiled")+ if vae_error and "compiled_vae_decode" in updated:+ updated.remove("compiled_vae_decode")if tuple(updated) != optims:# The load states are frozen dataclasses; the status must still reflect what actually runs.object.__setattr__(state, "speed_optims", tuple(updated))@@ -925,16 +928,120 @@ def compile_fallback_error(pipe: Any) -> Optional[str]:return None-def _compile_vae_decode(pipe: Any, logger: Any) -> bool:- """torch.compile the VAE ``decode`` bound method in place (U-Net families; caller gates).- Instance-level assignment: the pipe owns it and the module object is untouched."""+COMPILE_VAE_ENV = "UNSLOTH_DIFFUSION_COMPILE_VAE"++_VAE_TRUE_TOKENS = ("1", "true", "yes", "on")+_VAE_FALSE_TOKENS = ("0", "false", "no", "off")++# Not a correctness list: these decode correctly compiled but measured SLOWER than eager.+_VAE_COMPILE_DENY: frozenset[str] = frozenset({"AutoencoderKLQwenImage", "AutoencoderKLWan"})++# ``auto`` compiles only measured VAEs: video DiTs also pass through apply_speed_optims.+_VAE_COMPILE_ALLOW: frozenset[str] = frozenset({"AutoencoderKL"})+++def vae_decode_compile_allowed(pipe: Any, speed_mode: str) -> bool:+ """Compile-cache key input; False for a U-Net so its existing bundles keep their key."""+ return _denoiser_unet(pipe) is None and _vae_decode_compile_allowed(pipe, speed_mode)+++def _vae_decode_compile_allowed(pipe: Any, speed_mode: str) -> bool:+ """U-Nets always; a DiT only on ``max`` (it costs a 60-70 s slower first render) or with the env forced on."""+ if _denoiser_unet(pipe) is not None:+ return True+ raw = os.environ.get(COMPILE_VAE_ENV, "").strip().lower()+ if raw in _VAE_FALSE_TOKENS:+ return False+ if raw in _VAE_TRUE_TOKENS:+ return True+ if speed_mode != SPEED_MAX:+ return False+ name = type(getattr(pipe, "vae", None)).__name__+ return name in _VAE_COMPILE_ALLOW and name not in _VAE_COMPILE_DENY+++def _vae_eager_when_tiled(pipe: Any) -> bool:+ """A DiT decode not forced on by the env runs eager while tiled; U-Nets keep their measured recipe."""+ if pipe is not None and _denoiser_unet(pipe) is not None:+ return False+ return os.environ.get(COMPILE_VAE_ENV, "").strip().lower() not in _VAE_TRUE_TOKENS+++def _guard_compiled_decode(+ vae: Any,+ compiled: Any,+ eager: Any,+ logger: Any,+ eager_when_tiled: bool = False,+) -> Any:+ """``compiled`` behind an eager fallback: torch.compile is lazy, so lowering fails on the first call; OOMs still raise.++ ``eager_when_tiled``: a tiled decode unrolls its tile loop into one graph (minutes of compile on low-VRAM loads),+ and tiling is only settled by the memory plan after the compile, so it is read per call."""+ had_own = "decode" in getattr(vae, "__dict__", {})+ failed: list = []++ def guarded(*args: Any, **kwargs: Any) -> Any:+ if eager_when_tiled and getattr(vae, "use_tiling", False):+ return eager(*args, **kwargs)+ if not failed:+ try:+ return compiled(*args, **kwargs)+ except Exception as exc: # noqa: BLE001 - reraised unless a compile-time failure+ if not is_compile_failure(exc):+ raise+ error = f"{type(exc).__name__}: {str(exc).splitlines()[0] if str(exc) else ''}"[+ :300+ ]+ failed.append(error)+ try:+ vae._unsloth_compile_decode_error = error+ vae._unsloth_compiled_decode = False+ if had_own:+ vae.decode = eager+ else:+ del vae.decode+ except Exception: # noqa: BLE001 - `failed` still routes this wrapper to eager+ pass+ if logger is not None:+ logger.warning(+ "diffusion.speed: torch.compile failed on the VAE decode (%s); decoding eager",+ error,+ )+ # The handled exception pins inductor's frames (and the traced fake tensors) through the retry.+ exc.__traceback__ = None+ return eager(*args, **kwargs)++ return guarded+++def _compile_vae_decode(+ pipe: Any,+ logger: Any,+ max_autotune: bool = False,+ eager_when_tiled: bool = False,+) -> bool:+ """torch.compile the VAE ``decode`` in place; no cudagraphs, whose capture would pin decode activations."""vae = getattr(pipe, "vae", None)decode = getattr(vae, "decode", None) if vae is not None else Noneif not callable(decode):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 Falsetry:import torch- vae.decode = torch.compile(decode, fullgraph = False, dynamic = True)++ kwargs: dict[str, Any] = {"fullgraph": False, "dynamic": True}+ if max_autotune:+ kwargs["mode"] = "max-autotune-no-cudagraphs"+ compiled = torch.compile(decode, **kwargs)+ vae.decode = _guard_compiled_decode(+ vae, compiled, decode, logger, eager_when_tiled = eager_when_tiled+ )+ vae._unsloth_compiled_decode = Truereturn Trueexcept Exception as exc: # noqa: BLE001 - optimisation only_warn(logger, "vae decode compile", exc)diff --git a/studio/backend/core/inference/diffusion_transformer_quant.py b/studio/backend/core/inference/diffusion_transformer_quant.pyindex 0cb840fff6b..0b7364bd47e 100644--- a/studio/backend/core/inference/diffusion_transformer_quant.py+++ b/studio/backend/core/inference/diffusion_transformer_quant.py@@ -213,7 +213,6 @@ _NVFP4_FAMILY_ZERO_ROW_NAME_TOKENS: dict[str, tuple[str, ...]] = {def zero_row_tokens_for_scheme(scheme: str, family: Optional[str] = None) -> tuple[str, ...]:- """Tokens needing the empty-activation guard; nvfp4 only (fp8 / mxfp8 reduce per row)."""if scheme != TQ_NVFP4:return ()return _NVFP4_FAMILY_ZERO_ROW_NAME_TOKENS.get(str(family or "").strip().lower(), ())@@ -226,7 +225,7 @@ def apply_zero_row_guard(*,logger: Any = None,) -> tuple[str, ...]:- """Wrap this family's zero-row-reachable quantized Linears after quantize; not best-effort."""+ """Guard zero-row-reachable quantized Linears; call AFTER quantization (else the first t2v render crashes)."""tokens = zero_row_tokens_for_scheme(scheme, family)if not tokens:return ()@@ -297,10 +296,8 @@ _FAMILY_SCHEME_DENY: dict[str, frozenset[str]] = {@dataclass(frozen = True)class _AutoPrefer:- """A family's own head of the ``auto`` order, tried AHEAD of the family-blind ``_AUTO_LADDER``.-- Dropped below ``floor`` and, unless ``consumer_ok``, on consumer GPUs. ``gated``: needs a- passing record for THIS base on this device's backend; ``backend``: needs that NVFP4 backend."""+ """A family's head of the ``auto`` order, ahead of ``_AUTO_LADDER``; off below ``floor`` or on consumer GPUs+ (unless ``consumer_ok``), and ``gated`` / ``backend`` need a passing record / backend for THIS device."""floor: tuple[int, int]schemes: tuple[str, ...]@@ -354,6 +351,7 @@ def _nvfp4_gate_passed(family, base_repo) -> bool:def _nvfp4_gate_backend_ok(family, base_repo, device: Any) -> bool:+ """Whether a passing gate record was measured on the backend this device selects; failure keeps the deny."""if not nvfp4_diffusion_enabled():return Falsetry:@@ -367,6 +365,7 @@ def _nvfp4_gate_backend_ok(family, base_repo, device: Any) -> bool:def _nvfp4_backend_is(device: Any, name: str) -> bool:+ """Whether ``select_nvfp4_backend`` picks ``name`` for ``device``; failure drops the head."""if not nvfp4_diffusion_enabled():return Falsetry:@@ -381,7 +380,7 @@ def _family_denied(scheme: str,base_repo: Optional[str] = None,) -> bool:- """nvfp4 is the one entry a gate record can lift, per BASE: a sibling base stays denied."""+ """Whether the deny table rules ``scheme`` out; a gate record lifts nvfp4 per BASE, not per family."""if scheme not in _FAMILY_SCHEME_DENY.get(str(family or "").strip().lower(), ()):return Falseif scheme == TQ_NVFP4 and _nvfp4_gate_passed(family, base_repo):@@ -400,7 +399,7 @@ def _family_train_denied(scheme: str,base_repo: Optional[str] = None,) -> bool:- """``_family_denied`` plus training-only additions: a superset, never a bypass."""+ """``_family_denied`` plus training-only denies (always a superset); nvfp4 is denied for every family."""if scheme == TQ_NVFP4:return Truekey = str(family or "").strip().lower()@@ -437,8 +436,7 @@ def family_denies_scheme(scheme: str,base_repo: Optional[str] = None,) -> bool:- """Whether the measured deny list rules ``scheme`` out for ``family``, regardless of hardware.- Public so the refusal message can tell a family deny from a missing kernel."""+ """Whether the deny list rules ``scheme`` out for ``family``, so a refusal can tell it from a missing kernel."""return _family_denied(family, scheme, base_repo)@@ -449,6 +447,7 @@ def explain_unusable_scheme(*,prequant_missing: bool = False,) -> str:+ """Why an EXPLICIT ``scheme`` got None: family deny, unusable torchao, or a GPU without the kernels."""if nvfp4_blocked(scheme):return nvfp4_disabled_message()if family_denies_scheme(family, scheme, base_repo):@@ -929,14 +928,9 @@ def select_transformer_quant_scheme(``auto`` walks the per-arch ladder and returns the first scheme passing a real quantise+matmulsmoke test, so an unavailable Blackwell fp4/mx kernel lands on fp8/int8 with no error. Anexplicit scheme is honored only if supported (else None), never swapped. ``family`` applies the- measured deny list (``_FAMILY_SCHEME_DENY``): schemes that produce black frames / out-of-bar- drift are skipped by ``auto`` and refused when explicit.-- ``base_repo`` keys the per-base nvfp4 deny lift. ``require_prequant`` schemes are offered by- AUTO only when ``has_prequant`` finds a hosted checkpoint; EXPLICIT opts into a build.-- ``unproven_ok`` is for the PRE-EVICTION route gate: a resident model can fail the smoke test for- want of VRAM, so it answers only "provably unusable here".+ measured deny list; ``base_repo`` keys its per-base nvfp4 lift. ``require_prequant``: schemes AUTO+ offers only with a hosted checkpoint (the gate measured that artifact, not an on-the-fly build).+ ``unproven_ok`` is for the PRE-EVICTION gate, where a resident model can fail the smoke test for VRAM."""requested = normalize_transformer_quant(requested)if requested is None or not dense_transformer_supported(target):@@ -1047,10 +1041,7 @@ def _auto_scheme_order(cap: tuple[int, int],base_repo: Optional[str] = None,) -> tuple[str, ...]:- """The schemes ``auto`` would try on this GPU for this family, best first, before the deny list- and the smoke probe have their say. Empty when no tier matches, head or not: a capability below- every tier has no dense quant path at all. Shared by ``select_transformer_quant_scheme`` and- ``auto_scheme_candidates`` so the two can never disagree."""+ """Schemes ``auto`` would try here, best first, before deny list and smoke probe; empty below every tier."""tier: tuple[str, ...] = ()for floor, schemes in _AUTO_LADDER:if cap >= floor:@@ -1691,11 +1682,7 @@ def quantize_transformer(offload: bool = False,act_int8: Optional[bool] = None,) -> Optional[str]:- """Quantise ``pipe.transformer``'s FLOP-heavy linears in place with the arch-chosen scheme.- Returns the scheme engaged, or None when disabled / unsupported / failed (caller loads GGUF).- Best-effort: never raises for an unsupported environment (failure leaves it dense).- ``fast_accum`` (fp8 only) overrides the per-GPU-class accumulate choice: None auto-detects,- True/False force it. ``base_repo`` (UPSTREAM id) selects the per-layer NVFP4 policy."""+ """Quantise ``pipe.transformer`` in place, returning the scheme or None (GGUF); ``base_repo`` picks the NVFP4 policy."""native = native_quant_scheme(target, mode, family = family, offload = offload)if native is not None:if act_int8 is None:diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.pyindex 9f7965f18e9..b60b9cfb079 100644--- a/studio/backend/core/inference/video.py+++ b/studio/backend/core/inference/video.py@@ -1433,7 +1433,7 @@ def _transformer_names(pipe: Any, fam: VideoFamily) -> tuple[str, ...]:def _video_transformer_quant_backend(state: Any) -> Optional[str]:- """Read from the module tree; both experts share one backend. Never raises."""+ """Which NVFP4 kernel path the loaded denoiser(s) run, or None. Never raises."""if getattr(state, "transformer_quant", None) != "nvfp4":return Nonetry:@@ -3077,7 +3077,7 @@ class VideoBackend:text_encoder_quant: Optional[str] = None,gpu_ordinal: Optional[int] = None,) -> Optional[str]:- """The plan's seed scheme; ``DENOISER_SEED_DECLINED`` if the load would offload."""+ """The pre-download auto denoiser scheme, None, or ``DENOISER_SEED_DECLINED`` if the plan would offload."""try:if kind != "pipeline" or getattr(fam, "modular_workflow", None):return None@@ -3270,7 +3270,7 @@ class VideoBackend:cancel_event: Optional[threading.Event] = None,local_files_only: bool = False,) -> None:- """Pre-fetch hosted denoiser checkpoint(s) under the load's cancel event; best effort."""+ """Pre-fetch the hosted denoiser checkpoint(s) under the load's cancel event; best effort except cancellation."""cancel = cancel_event if cancel_event is not None else self._cancel_eventfrom core.inference.diffusion_prequant import candidate_filenames_offrom utils.hf_xet_fallback import hf_hub_download_with_xet_fallback@@ -3311,7 +3311,7 @@ class VideoBackend:*,kind: str = "pipeline",) -> bool:- """True when hosted pre-quantized denoisers replace ALL dense DiT shards; never raises."""+ """True when hosted pre-quantized checkpoints replace ALL the family's dense DiT shards; offline, never raises."""try:scheme = normalize_transformer_quant(transformer_quant)# An unresolved "auto" must NOT drop dense shards; the backend settles it first.@@ -3334,7 +3334,7 @@ class VideoBackend:base: Optional[str],h3_task: Optional[str] = None,) -> list[Any]:- """Every ``PrequantSource`` a seeded load would open, or ``[]``; never raises."""+ """Every ``PrequantSource`` a seeded load would open, or ``[]``; registry only, never raises."""scheme = (transformer_quant or "").strip().lower()if scheme in ("", "auto", "off", "none"):return []@@ -3358,7 +3358,7 @@ class VideoBackend:base: Optional[str],h3_task: Optional[str] = None,) -> tuple[str, ...]:- """Repo id(s) a seeded denoiser is fetched from, for the in-flight delete guard."""+ """Hosted repo id(s) a seeded denoiser is fetched from, for the in-flight delete guard."""return tuple(dict.fromkeys(src.location@@ -3377,7 +3377,8 @@ class VideoBackend:api: Any,h3_task: Optional[str] = None,) -> tuple[Optional[str], list[tuple[str, int]]]:- """``(repo_id, [(rfilename, size)])`` for all hosted denoisers or ``(None, [])``."""+ """``(repo_id, [(rfilename, size)])`` for every hosted denoiser artifact, or ``(None, [])``, so preflight+ counts the checkpoint that replaces the dropped dense shards."""sources = VideoBackend._denoiser_prequant_source_list(fam, transformer_quant, base, h3_task)if not sources or any(getattr(src, "kind", None) != "repo" for src in sources):return None, []@@ -3518,8 +3519,7 @@ class VideoBackend:) -> list[tuple[str, int]]:"""The (rfilename, size) list a load actually needs from the base repo.- Single source of truth for the progress estimate AND the scoped pre-download,- so the two can never disagree. Excluded on purpose:+ Shared by the progress estimate and the scoped pre-download. Excluded on purpose:- root-level packaged checkpoints (ComfyUI-style singles; 170 GB of the LTX-2repo) -- the diffusers pipeline only reads per-component subfolders;- the duplicate ``text_encoder/diffusion_pytorch_model*`` shard set (the LTX-2@@ -3536,15 +3536,10 @@ class VideoBackend:- the dense weight shards of the denoiser partition this load opens, under``skip_transformer_weights``, supplied instead by a hosted PRE-QUANTIZEDdenoiser checkpoint (H3's transformer is 66.3 GB of its base repo).- ``transformer/config.json`` stays; ``skip_transformer_components`` names the covered ones.-- ``h3_task`` picks the H3 denoiser partition. The base repo ships two, and a load only ever- brings up one: ``transformer/`` for fl2va (which also covers text-only) and- ``transformer_ref/`` for ref2va. They are 66.28 GB each, so the scoped list carries exactly- one of them, never both. Substituting rather than listing both is what keeps the stage at- one denoiser: listing only ``transformer/`` staged the wrong 66.28 GB for a ref2va load and- left the right one to be fetched inline, outside the download manager's disk preflight and- cancellation."""+ ``transformer/config.json`` is kept for the same reason the pre-cast+ encoders keep theirs; ``skip_transformer_components`` names the covered denoisers.++ ``h3_task`` picks the ONE H3 partition staged (``transformer/`` or ``transformer_ref/``)."""from .diffusion_te_prequant import is_prequant_covered_weightfrom .video_minimax_h3 import H3_TASK_REFERENCES@@ -4599,10 +4594,7 @@ class VideoBackend:log: bool,denoiser_gb: Optional[float] = None,) -> tuple[Any, Any, bool]:- """``(plan, bf16_plan, quant_replanned)`` for a text-encoder budget of ``scale`` x- its bf16 size. Pure and cheap (``plan_diffusion_memory`` is arithmetic), so the- dense-encoder plan can be rebuilt below if the pre-cast injection does not land.- ``denoiser_gb`` replaces the bf16 DiT term for a SEEDED load (steady and peak)."""+ """``(plan, bf16_plan, quant_replanned)``; ``denoiser_gb`` prices a SEEDED DiT (peak == steady)."""text_encoder_gb = components[1] * scale if components is not None else 0.0# dtype_scale doubles bf16 terms when the fp16 promotion lands fp32 on an accelerator. A vae_force_fp32# family is the one component it must NOT touch: its table term is already recorded at fp32 and assemblydiff --git a/studio/backend/core/inference/video_denoiser_prequant.py b/studio/backend/core/inference/video_denoiser_prequant.pyindex 3084b2aad70..744d3b4f700 100644--- a/studio/backend/core/inference/video_denoiser_prequant.py+++ b/studio/backend/core/inference/video_denoiser_prequant.py@@ -1,7 +1,10 @@# SPDX-License-Identifier: AGPL-3.0-only# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0-"""Seed a conventional video pipeline with hosted pre-quantized denoisers, all-or-nothing."""+"""Seed a conventional video pipeline with hosted pre-quantized denoisers, all-or-nothing.++The MoE's second expert uses the ``task`` slot with NO filename fallback: it would load expert 1 as expert 2.+"""from __future__ import annotations@@ -11,7 +14,6 @@ MOE_SECOND_DENOISER = "transformer_2"def denoiser_components(fam: Any) -> tuple[str, ...]:- """Pipeline attribute name(s) of this family's denoiser(s), from the registry."""if getattr(fam, "is_moe", False):return ("transformer", MOE_SECOND_DENOISER)return ("transformer",)@@ -20,7 +22,7 @@ def denoiser_components(fam: Any) -> tuple[str, ...]:def denoiser_prequant_sources(fam: Any, scheme: Optional[str], base_repo: Optional[str]) -> Optional[dict[str, Any]]:- """``{component: PrequantSource}`` for EVERY denoiser, or None (never partial); never raises."""+ """``{component: PrequantSource}`` for EVERY denoiser, or None (never partial). Never raises."""wanted = (scheme or "").strip().lower()if wanted in ("", "auto", "off", "none"):return None@@ -64,7 +66,7 @@ def denoiser_prequant_pipe_kwargs(cache_dir: Optional[str] = None,logger: Any = None,) -> dict[str, Any]:- """Overrides for assembly, or ``{}`` (dense bf16 + runtime quant) unless all denoisers seed."""+ """Component overrides for pipeline assembly, or ``{}`` (not seeded whole: re-plan memory at bf16)."""try:import gcdiff --git a/studio/backend/tests/test_diffusion_backend.py b/studio/backend/tests/test_diffusion_backend.pyindex 07017bce540..68015365ad1 100644--- a/studio/backend/tests/test_diffusion_backend.py+++ b/studio/backend/tests/test_diffusion_backend.py@@ -1076,6 +1076,7 @@ def test_gguf_status_reports_selected_quant_instead_of_only_compute_dtype(fake_rassert status["dtype"] == "float32" # compute dtype is a separate concernassert status["gguf_variant"] == "Q8_0"+ assert status["gguf_filename"] == filenameassert backend.unload()["gguf_variant"] is Nonediff --git a/studio/backend/tests/test_diffusion_compile_cache.py b/studio/backend/tests/test_diffusion_compile_cache.pyindex 3f5c857f2b8..ae4a121ce1e 100644--- a/studio/backend/tests/test_diffusion_compile_cache.py+++ b/studio/backend/tests/test_diffusion_compile_cache.py@@ -91,6 +91,34 @@ def test_cache_key_sensitive_to_model_dims(field, value):assert cc.cache_key(efp, cc.model_fingerprint(**base)) != k0+def test_vae_decode_flag_changes_the_key():+ efp = cc.environment_fingerprint()+ base = dict(+ family = "flux.1",+ transformer = _transformer(),+ dtype = "bf16",+ quant = None,+ attention_backend = "x",+ compile_kwargs = {"fullgraph": True, "dynamic": True, "vae_decode": False},+ )+ k0 = cc.cache_key(efp, cc.model_fingerprint(**base))+ base["compile_kwargs"] = {"fullgraph": True, "dynamic": True, "vae_decode": True}+ assert cc.cache_key(efp, cc.model_fingerprint(**base)) != k0+++def test_a_load_whose_vae_decision_did_not_move_keeps_its_bundle_key():+ # Keys saved before the flag existed are {fullgraph, dynamic, ...}: an eager decode must still hit them after update.+ efp = cc.environment_fingerprint()+ base = dict(+ family = "flux.1", transformer = _transformer(), dtype = "bf16", quant = None, attention_backend = "x"+ )+ before = cc.model_fingerprint(**base, compile_kwargs = {"fullgraph": True, "dynamic": True})+ after = cc.model_fingerprint(+ **base, compile_kwargs = {"fullgraph": True, "dynamic": True, "vae_decode": False}+ )+ assert cc.cache_key(efp, after) == cc.cache_key(efp, before)++def test_repeated_blocks_change_key():efp = cc.environment_fingerprint()k1 = cc.cache_key(diff --git a/studio/backend/tests/test_diffusion_more_families.py b/studio/backend/tests/test_diffusion_more_families.pyindex c92bf2c9609..66a6700b490 100644--- a/studio/backend/tests/test_diffusion_more_families.py+++ b/studio/backend/tests/test_diffusion_more_families.py@@ -88,6 +88,7 @@ def test_flux1_krea_dev_generation_defaults():def test_flux_dev_and_krea_do_not_inherit_the_schnell_nvfp4_checkpoint():+ # The NVFP4 artifact is schnell-only: dev and Krea-dev inheriting it failed validation with no dense fallback.from core.inference.diffusion_families import family_prequant_repofam = detect_family("black-forest-labs/FLUX.1-schnell")diff --git a/studio/backend/tests/test_diffusion_nvfp4_backend.py b/studio/backend/tests/test_diffusion_nvfp4_backend.pyindex 67579e222f3..ee42011b471 100644--- a/studio/backend/tests/test_diffusion_nvfp4_backend.py+++ b/studio/backend/tests/test_diffusion_nvfp4_backend.py@@ -247,7 +247,7 @@ _STREAM_BANNED = ("set_stream", "set_device", "setDevice")def _banned_stream_calls(source: str) -> list[tuple[int, str]]:- """``set_stream`` silently sets the current DEVICE; ``set_device`` moves what the guard restores."""+ """``set_stream`` silently sets the current DEVICE too, and ``set_device`` moves what the guard restores."""found: list[tuple[int, str]] = []for node in ast.walk(ast.parse(source)):if isinstance(node, ast.Attribute) and node.attr in _STREAM_BANNED:@@ -360,6 +360,7 @@ def _fake_blackwell(monkeypatch):def test_an_allocation_failure_is_answered_but_not_cached(monkeypatch):+ """An OOM during AUTO planning means 'not now'; cached, it would drop nvfp4 for the process."""torch = _fake_blackwell(monkeypatch)calls: list = []@@ -379,6 +380,7 @@ def test_an_allocation_failure_is_answered_but_not_cached(monkeypatch):def test_a_host_property_failure_stays_cached(monkeypatch):+ """A JIT build that cannot run here never will, so the failure is cached."""_fake_blackwell(monkeypatch)calls: list = []diff --git a/studio/backend/tests/test_diffusion_nvfp4_dispatch.py b/studio/backend/tests/test_diffusion_nvfp4_dispatch.pyindex ff2197bbb19..ee184eac571 100644--- a/studio/backend/tests/test_diffusion_nvfp4_dispatch.py+++ b/studio/backend/tests/test_diffusion_nvfp4_dispatch.py@@ -1,6 +1,7 @@# SPDX-License-Identifier: AGPL-3.0-only# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0+"""Cached FlashInfer dispatch: allowlist, all-or-nothing private import, per-device bit-identity."""from __future__ import annotationsdiff --git a/studio/backend/tests/test_diffusion_nvfp4_gate.py b/studio/backend/tests/test_diffusion_nvfp4_gate.pyindex 01cd2fc5ae3..ec1cb7e7635 100644--- a/studio/backend/tests/test_diffusion_nvfp4_gate.py+++ b/studio/backend/tests/test_diffusion_nvfp4_gate.py@@ -120,6 +120,7 @@ def test_a_matching_record_reads_true_and_canonicalises_the_base(tmp_path):def test_the_backend_a_verdict_was_measured_on_is_readable(tmp_path):+ """The ladder keeps the deny unless the measured backend serves this device."""path = _gate_file(tmp_path, _record())assert nvfp4_gate_backend("z-image", ZIMAGE_BASE, path = path) == "flashinfer"assert nvfp4_gate_backend("Z-Image", ZIMAGE_BASE, path = path) == "flashinfer"diff --git a/studio/backend/tests/test_diffusion_nvfp4_linear.py b/studio/backend/tests/test_diffusion_nvfp4_linear.pyindex 49408e467af..bb0aa9f840c 100644--- a/studio/backend/tests/test_diffusion_nvfp4_linear.py+++ b/studio/backend/tests/test_diffusion_nvfp4_linear.py@@ -488,7 +488,7 @@ def test_a_whole_model_artifact_that_baked_nothing_says_the_flag_is_set():def test_an_fp32_layer_runs_and_answers_in_fp32():- """Wan2.2's fp32 time embedder feeds fp32, which ``fp4_quantize`` rejects."""+ """Wan2.2's fp32 time embedder feeds FP32 activations, which ``fp4_quantize`` rejects."""torch = _cuda_or_skip()import torch.nn as nnfrom torchao.prototype.mx_formats import NVFP4DynamicActivationNVFP4WeightConfigdiff --git a/studio/backend/tests/test_diffusion_nvfp4_protect.py b/studio/backend/tests/test_diffusion_nvfp4_protect.pyindex 3a0895f729b..fa571363a40 100644--- a/studio/backend/tests/test_diffusion_nvfp4_protect.py+++ b/studio/backend/tests/test_diffusion_nvfp4_protect.py@@ -585,7 +585,7 @@ def test_a_captured_block_gets_one_graph_per_branch(monkeypatch):def test_an_armed_controller_with_no_protect_capable_layer_refuses_and_says_so():- """A torchao load runs W4A4 at every step, so arming there would count steps nothing ran."""+ """Only ``NVFP4FlashInferLinear`` reads the controller, so a torchao load must not arm."""class _Logger:def __init__(self):diff --git a/studio/backend/tests/test_diffusion_nvfp4_protect_image.py b/studio/backend/tests/test_diffusion_nvfp4_protect_image.pyindex 64ae6e48b71..0fb645e61cf 100644--- a/studio/backend/tests/test_diffusion_nvfp4_protect_image.py+++ b/studio/backend/tests/test_diffusion_nvfp4_protect_image.py@@ -329,7 +329,6 @@ def _cuda_or_skip():def test_a_graphed_dit_captures_one_tuned_graph_per_branch_and_replays_both(monkeypatch):- """Two tuned captures, each replay bit-identical to its branch's un-graphed forward."""torch = _cuda_or_skip()import torch.nn as nnfrom torchao.prototype.mx_formats import NVFP4DynamicActivationNVFP4WeightConfigdiff --git a/studio/backend/tests/test_diffusion_nvfp4_speed.py b/studio/backend/tests/test_diffusion_nvfp4_speed.pyindex 3412035bd79..bd9ec695eb2 100644--- a/studio/backend/tests/test_diffusion_nvfp4_speed.py+++ b/studio/backend/tests/test_diffusion_nvfp4_speed.py@@ -1,8 +1,7 @@# SPDX-License-Identifier: AGPL-3.0-only# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0-"""NVFP4 flashinfer device guard and ordering barrier. Stubs ``torch`` and ``flashinfer``: neither the-launch device nor the call ORDER inside an opaque custom op is observable on one GPU."""+"""Kernel-side tests for the NVFP4 flashinfer path: the device guard and the ordering barrier."""from __future__ import annotationsdiff --git a/studio/backend/tests/test_diffusion_prequant.py b/studio/backend/tests/test_diffusion_prequant.pyindex b5153c3fc45..0ec6df5f425 100644--- a/studio/backend/tests/test_diffusion_prequant.py+++ b/studio/backend/tests/test_diffusion_prequant.py@@ -346,7 +346,7 @@ class _Bytes:class Float8Tensor:- """The class NAME is what the fingerprint and the activation-floor check key on."""+ """A quantized fp8 weight; the class NAME is what the fingerprint and activation-floor checks key on."""def __init__(self,@@ -2328,7 +2328,7 @@ def test_an_nvfp4_install_must_be_able_to_open_the_fp8_weights_too():def test_the_checkpoint_is_released_before_the_device_copy(monkeypatch, tmp_path):- """assign=True shares the checkpoint's tensors: unreference them before ``.to(device)``."""+ """The CPU checkpoint must be unreferenced by the time ``.to(device)`` allocates (unified memory peak)."""import weakrefseen: dict = {}diff --git a/studio/backend/tests/test_diffusion_speed.py b/studio/backend/tests/test_diffusion_speed.pyindex a1462105a4a..c15e5a9ed56 100644--- a/studio/backend/tests/test_diffusion_speed.py+++ b/studio/backend/tests/test_diffusion_speed.py@@ -87,8 +87,13 @@ def _stub_torch(monkeypatch):)# Said explicitly so the CUDA-graph arm refuses deterministically, whatever the host has.torch.cuda = types.SimpleNamespace(is_available = lambda: False)- # The VAE-decode compile wraps a bound method; identity wrap is enough for tests.- torch.compile = lambda fn, **kwargs: fn+ torch.compile_calls = []++ def _compile(fn, **kwargs):+ torch.compile_calls.append(kwargs)+ return fn++ torch.compile = _compilemonkeypatch.setitem(sys.modules, "torch", torch)return torch@@ -357,6 +362,14 @@ def test_restore_is_independent_per_flag(monkeypatch):# ── applier ───────────────────────────────────────────────────────────────────+class AutoencoderKL(types.SimpleNamespace):+ """The class NAME matters: ``auto`` keys the allow list off it."""+++class AutoencoderKLWan(types.SimpleNamespace):+ """A video VAE."""++class _Pipe:def __init__(self,@@ -364,8 +377,9 @@ class _Pipe:with_compile = False,with_fuse = False,with_second_dit = False,+ vae_cls = AutoencoderKL,) -> None:- self.vae = types.SimpleNamespace(mem_format = None, to = self._vae_to)+ self.vae = vae_cls(mem_format = None, to = self._vae_to, decode = lambda z: z)self.transformer = types.SimpleNamespace()if with_compile:self.transformer.compile_repeated_blocks = self._compile@@ -619,16 +633,157 @@ def test_unet_whole_compile_default_tier(monkeypatch):assert applied["compiled_vae_decode"] is True-def test_dit_default_tier_keeps_fuse_and_vae_decode_off(monkeypatch):- # The DiT default tier is unchanged: fused QKV measured exactly neutral so it stays max-only, and the VAE decode stays eager.- _stub_torch(monkeypatch)[email protected]("tier", [SPEED_DEFAULT, SPEED_MAX])+def test_a_unet_keeps_its_decode_recipe_and_bundle_key_on_every_tier(monkeypatch, tier):+ torch = _stub_torch(monkeypatch)+ monkeypatch.delenv(ds_mod.COMPILE_VAE_ENV, raising = False)+ pipe = _UNetPipe()+ applied = apply_speed_optims(pipe, _target(), is_gguf = False, family = _family(), speed_mode = tier)+ assert applied["compiled_vae_decode"] is True+ assert {"fullgraph": False, "dynamic": True} in torch.compile_calls+ assert not any(call.get("mode") for call in torch.compile_calls)+ assert ds_mod.vae_decode_compile_allowed(pipe, tier) is False+++def test_dit_default_tier_keeps_fuse_off_and_leaves_the_vae_decode_eager(monkeypatch):+ torch = _stub_torch(monkeypatch)+ monkeypatch.delenv(ds_mod.COMPILE_VAE_ENV, raising = False)pipe = _Pipe(with_compile = True, with_fuse = True)+ assert type(pipe.vae).__name__ in ds_mod._VAE_COMPILE_ALLOWapplied = apply_speed_optims(pipe, _target(), is_gguf = False, family = _family(), speed_mode = SPEED_DEFAULT)assert applied["compiled"] is Trueassert applied["fused_qkv"] is False and pipe.fused is Falseassert applied["compiled_vae_decode"] is False+ assert torch.compile_calls == []+ assert ds_mod.vae_decode_compile_allowed(pipe, SPEED_DEFAULT) is False+ assert ds_mod.vae_decode_compile_allowed(pipe, SPEED_MAX) is True+++def test_dit_default_tier_vae_decode_compile_forced_on_by_env(monkeypatch):+ torch = _stub_torch(monkeypatch)+ monkeypatch.setenv(ds_mod.COMPILE_VAE_ENV, "1")+ pipe = _Pipe(with_compile = True)+ applied = apply_speed_optims(+ pipe, _target(), is_gguf = False, family = _family(), speed_mode = SPEED_DEFAULT+ )+ assert applied["compiled"] is True and applied["compiled_vae_decode"] is True+ assert torch.compile_calls == [{"fullgraph": False, "dynamic": True}]+ assert ds_mod.vae_decode_compile_allowed(pipe, SPEED_DEFAULT) is True+++def test_dit_vae_decode_compile_opts_out_by_env(monkeypatch):+ torch = _stub_torch(monkeypatch)+ monkeypatch.setenv(ds_mod.COMPILE_VAE_ENV, "0")+ pipe = _Pipe(with_compile = True)+ applied = apply_speed_optims(+ pipe, _target(), is_gguf = False, family = _family(), speed_mode = SPEED_MAX+ )+ assert applied["compiled"] is True and applied["compiled_vae_decode"] is False+ assert torch.compile_calls == []+ assert ds_mod.vae_decode_compile_allowed(pipe, SPEED_MAX) is False+++def test_dit_vae_decode_compile_deny_set_and_force(monkeypatch):+ assert "AutoencoderKLQwenImage" in ds_mod._VAE_COMPILE_DENY+ _stub_torch(monkeypatch)+ monkeypatch.delenv(ds_mod.COMPILE_VAE_ENV, raising = False)+ pipe = _Pipe(with_compile = True)+ monkeypatch.setattr(+ ds_mod,+ "_VAE_COMPILE_DENY",+ frozenset({type(pipe.vae).__name__}),+ )+ applied = apply_speed_optims(+ pipe, _target(), is_gguf = False, family = _family(), speed_mode = SPEED_MAX+ )+ assert applied["compiled_vae_decode"] is False+ monkeypatch.setenv(ds_mod.COMPILE_VAE_ENV, "1")+ applied = apply_speed_optims(+ _Pipe(with_compile = True),+ _target(),+ is_gguf = False,+ family = _family(),+ speed_mode = SPEED_DEFAULT,+ )+ assert applied["compiled_vae_decode"] is True+++def test_video_vae_stays_eager_under_auto_and_compiles_once_per_pipe(monkeypatch):+ torch = _stub_torch(monkeypatch)+ monkeypatch.delenv(ds_mod.COMPILE_VAE_ENV, raising = False)+ pipe = _Pipe(with_compile = True, vae_cls = AutoencoderKLWan)+ applied = apply_speed_optims(+ pipe, _target(), is_gguf = False, family = _family(), speed_mode = SPEED_DEFAULT+ )+ assert applied["compiled"] is True and applied["compiled_vae_decode"] is False+ assert torch.compile_calls == []+ monkeypatch.setenv(ds_mod.COMPILE_VAE_ENV, "1")+ for _ in range(2):+ applied = apply_speed_optims(+ pipe, _target(), is_gguf = False, family = _family(), speed_mode = SPEED_DEFAULT+ )+ assert applied["compiled_vae_decode"] is True+ assert torch.compile_calls == [{"fullgraph": False, "dynamic": True}]+++def test_dit_vae_decode_compile_max_tier_autotunes(monkeypatch):+ torch = _stub_torch(monkeypatch)+ monkeypatch.delenv(ds_mod.COMPILE_VAE_ENV, raising = False)+ pipe = _Pipe(with_compile = True, with_fuse = True)+ applied = apply_speed_optims(+ pipe, _target(), is_gguf = False, family = _family(), speed_mode = SPEED_MAX+ )+ assert applied["compiled_vae_decode"] is True+ assert torch.compile_calls == [+ {"fullgraph": False, "dynamic": True, "mode": "max-autotune-no-cudagraphs"}+ ]+++def test_unet_vae_decode_compile_ignores_the_env(monkeypatch):+ _stub_torch(monkeypatch)+ monkeypatch.setenv(ds_mod.COMPILE_VAE_ENV, "0")+ pipe = _UNetPipe()+ applied = apply_speed_optims(+ pipe, _target(), is_gguf = False, family = _family(), speed_mode = SPEED_DEFAULT+ )+ assert applied["compiled_vae_decode"] is True+++def test_video_wan_vae_decode_is_denied_on_measurement(monkeypatch):+ # Denied, not just unlisted: stays off even if added to the allow set.+ torch = _stub_torch(monkeypatch)+ monkeypatch.delenv(ds_mod.COMPILE_VAE_ENV, raising = False)+ assert "AutoencoderKLWan" in ds_mod._VAE_COMPILE_DENY+ monkeypatch.setattr(+ ds_mod, "_VAE_COMPILE_ALLOW", ds_mod._VAE_COMPILE_ALLOW | {"AutoencoderKLWan"}+ )+ applied = apply_speed_optims(+ _Pipe(with_compile = True, vae_cls = AutoencoderKLWan),+ _target(),+ is_gguf = False,+ family = _family(),+ speed_mode = SPEED_DEFAULT,+ cuda_graph_default = False,+ )+ assert applied["compiled"] is True and applied["compiled_vae_decode"] is False+ assert torch.compile_calls == []+++def test_video_wan_vae_decode_stays_denied_on_max(monkeypatch):+ torch = _stub_torch(monkeypatch)+ monkeypatch.delenv(ds_mod.COMPILE_VAE_ENV, raising = False)+ applied = apply_speed_optims(+ _Pipe(with_compile = True, vae_cls = AutoencoderKLWan),+ _target(),+ is_gguf = False,+ family = _family(),+ speed_mode = SPEED_MAX,+ cuda_graph_default = False,+ )+ assert applied["compiled_vae_decode"] is False+ assert torch.compile_calls == []def test_unet_whole_compile_offload_drops_fullgraph(monkeypatch):@@ -1436,6 +1591,18 @@ def test_compiled_shapes_are_static_reports_the_stream_merging_downgrade(monkeypassert ds_mod.compiled_shapes_are_static(merging, SPEED_EAGER) is False+def test_the_loader_keys_the_compile_bundle_on_the_vae_decode_decision():+ from pathlib import Path++ src = (Path(__file__).resolve().parents[1] / "core" / "inference" / "diffusion.py").read_text(+ encoding = "utf-8"+ )+ assert src.count('"vae_decode": vae_decode_compile_allowed(') == 2+ assert '"vae_decode": vae_decode_compile_allowed(pipe, effective_speed)' in src+ assert '"vae_decode": vae_decode_compile_allowed(state.pipe, SPEED_DEFAULT)' in src+ assert ds_mod.vae_decode_compile_allowed is not None++def test_speed_max_keeps_automatic_dynamic_for_a_stream_merging_dit(monkeypatch):"""The static exception is the default tier's alone: max compiles every DiT with automatic dynamic."""_stub_torch(monkeypatch)@@ -1644,6 +1811,132 @@ def test_non_compile_errors_are_not_swallowed(monkeypatch, kind):assert ds_mod.compile_fallback_error(types.SimpleNamespace(transformer = dit)) is None+class _Vae:+ """A VAE whose ``decode`` is a class method, as on a diffusers AutoencoderKL."""++ def __init__(self) -> None:+ self.eager_calls = 0++ def decode(self, z):+ self.eager_calls += 1+ return z + 1+++def _stub_lazy_compile(monkeypatch, failure):+ """torch.compile that returns fine and fails only on the first call, like dynamo / inductor lowering."""+ torch = _stub_torch_compile_errors(monkeypatch)+ calls = {"compiled": 0}++ def _compile(fn, **kwargs):+ torch.compile_calls.append(kwargs)++ def compiled(*args, **kw):+ calls["compiled"] += 1+ raise failure()++ return compiled++ torch.compile = _compile+ return calls+++def test_vae_decode_compile_failure_at_first_decode_falls_back_to_eager(monkeypatch):+ calls = _stub_lazy_compile(+ monkeypatch, lambda: _BackendCompilerFailed("LoweringException: no lowering for aten.foo")+ )+ vae = _Vae()+ pipe = types.SimpleNamespace(vae = vae)+ assert ds_mod._compile_vae_decode(pipe, None, max_autotune = True) is True+ assert "decode" in vae.__dict__+ assert vae.decode(1) == 2+ assert vae.eager_calls == 1+ assert "decode" not in vae.__dict__+ assert vae.decode(5) == 6+ assert calls["compiled"] == 1+ assert "LoweringException" in vae._unsloth_compile_decode_error+++def test_vae_decode_fallback_is_settled_into_status_and_not_recompiled(monkeypatch):+ # Dual-DiT loads run apply_speed_optims twice: a fallen-back decode must not read as a live compile.+ calls = _stub_lazy_compile(monkeypatch, lambda: _BackendCompilerFailed("LoweringException"))+ vae = _Vae()+ pipe = types.SimpleNamespace(vae = vae)+ state = types.SimpleNamespace(speed_optims = ("compiled", "compiled_vae_decode"))+ assert ds_mod.settle_compile_fallback(state, pipe) is None+ assert ds_mod._compile_vae_decode(pipe, None) is True+ assert vae.decode(1) == 2+ assert vae._unsloth_compiled_decode is False+ assert "LoweringException" in ds_mod.settle_compile_fallback(state, pipe)+ assert state.speed_optims == ("compiled", "compile_fallback_eager")+ assert ds_mod._compile_vae_decode(pipe, None) is False+ assert "decode" not in vae.__dict__+ assert vae.decode(5) == 6+ assert calls["compiled"] == 1+++def test_vae_decode_compile_fallback_restores_an_instance_decode(monkeypatch):+ _stub_torch_compile_errors(monkeypatch)+ original = lambda z: z * 3 # noqa: E731 - an instance attribute, as on the SimpleNamespace fakes+ vae = types.SimpleNamespace(decode = original)++ def broken(z):+ raise _BackendCompilerFailed("CantSplit")++ vae.decode = ds_mod._guard_compiled_decode(vae, broken, original, None)+ assert vae.decode(2) == 6+ assert vae.decode is original++[email protected]("forced", [False, True])+def test_a_tiled_dit_decode_stays_eager_unless_the_compile_is_forced(monkeypatch, forced):+ # Tiled decode unrolls its tile loop into one graph: minutes of first-render compile for a low-VRAM load.+ if forced:+ monkeypatch.setenv(ds_mod.COMPILE_VAE_ENV, "1")+ else:+ monkeypatch.delenv(ds_mod.COMPILE_VAE_ENV, raising = False)+ calls = {"compiled": 0, "eager": 0}++ def compiled(z):+ calls["compiled"] += 1+ return z++ def eager(z):+ calls["eager"] += 1+ return z++ vae = types.SimpleNamespace(decode = eager, use_tiling = True)+ vae.decode = ds_mod._guard_compiled_decode(+ vae, compiled, eager, None, eager_when_tiled = ds_mod._vae_eager_when_tiled(None)+ )+ vae.decode(1)+ assert calls == ({"compiled": 1, "eager": 0} if forced else {"compiled": 0, "eager": 1})+ vae.use_tiling = False+ vae.decode(1)+ assert calls["compiled"] == (2 if forced else 1)++[email protected]("kind", ["runtime", "oom"])+def test_vae_decode_non_compile_errors_are_not_swallowed(monkeypatch, kind):+ def failure():+ if kind == "runtime":+ return RuntimeError("CUDA error: an illegal memory access was encountered")+ try:+ raise _OutOfMemory("CUDA out of memory")+ except _OutOfMemory as oom:+ try:+ raise _BackendCompilerFailed("autotune ran out") from oom+ except _BackendCompilerFailed as outer:+ return outer++ _stub_lazy_compile(monkeypatch, failure)+ vae = _Vae()+ assert ds_mod._compile_vae_decode(types.SimpleNamespace(vae = vae), None) is True+ with pytest.raises((RuntimeError, _BackendCompilerFailed)):+ vae.decode(1)+ assert vae.eager_calls == 0+ assert "decode" in vae.__dict__++class _TorchaoWeight:passdiff --git a/studio/backend/tests/test_diffusion_transformer_quant.py b/studio/backend/tests/test_diffusion_transformer_quant.pyindex 409e5e9f9fa..8645ebfec5b 100644--- a/studio/backend/tests/test_diffusion_transformer_quant.py+++ b/studio/backend/tests/test_diffusion_transformer_quant.py@@ -2305,7 +2305,7 @@ def test_a_gated_row_is_inert_without_a_record_and_leads_with_one(monkeypatch, tdef test_the_gated_head_stands_on_any_backend_a_passing_record_names(monkeypatch, tmp_path):- """One policy can hold records on both backends; neither device may lose nvfp4 to row order."""+ """One policy can hold artifacts gated on either backend; neither may lose nvfp4 to row order."""_stub_torch(monkeypatch, cc = (10, 0))_allow(monkeypatch, {TQ_NVFP4, TQ_FP8, TQ_MXFP8, TQ_INT8})_gate(diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.pyindex 246ec23806e..e076f904e3b 100644--- a/studio/backend/tests/test_video_backend.py+++ b/studio/backend/tests/test_video_backend.py@@ -9562,7 +9562,7 @@ def test_the_planned_scheme_is_what_the_load_seeds(fake_runtime, monkeypatch):def test_a_seed_the_plan_declined_is_not_re_taken_by_the_load(fake_runtime, monkeypatch):- """The load honours the plan's decline: re-deciding here would fetch the artifact inline."""+ """The load honours the plan's decline, or it would fetch the artifact inline."""import core.inference.video as video_modmonkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)@@ -9745,7 +9745,7 @@ def test_an_explicit_scheme_under_speed_off_stages_the_hosted_experts(monkeypatcdef test_the_video_status_response_carries_the_nvfp4_backend_label():- """'NVFP4' alone does not say which backend ran."""+ """The same backend field the image status exposes: 'NVFP4' alone does not say what ran."""from models.inference import VideoStatusResponseresp = VideoStatusResponse(@@ -9827,7 +9827,6 @@ def _a14b_plan(monkeypatch):def test_a_plan_that_still_offloads_at_artifact_size_stages_the_dense_experts(monkeypatch):- """A card the artifact-sized plan still offloads on cannot seed: stage the dense experts."""import core.inference.video as video_mod_a14b_plan(monkeypatch)@@ -9847,7 +9846,6 @@ def test_a_plan_that_still_offloads_at_artifact_size_stages_the_dense_experts(modef test_a_card_the_artifact_fits_on_still_stages_the_artifacts(monkeypatch):- """Where the artifact-sized plan stays resident the load seeds, so dense shards stay out."""import core.inference.video as video_mod_a14b_plan(monkeypatch)@@ -9870,7 +9868,6 @@ def test_a_card_the_artifact_fits_on_still_stages_the_artifacts(monkeypatch):def test_an_offloading_memory_mode_stages_the_dense_experts_on_any_card(monkeypatch):- """An explicit offload memory_mode stages the dense experts even on a roomy card."""import core.inference.video as video_mod_a14b_plan(monkeypatch)@@ -9892,7 +9889,7 @@ def test_an_offloading_memory_mode_stages_the_dense_experts_on_any_card(monkeypadef test_a_dense_encoder_fallback_that_forces_offload_also_drops_the_seed(fake_runtime, monkeypatch):- """A failed pre-cast encoder re-plans at bf16, which can offload: re-decide the seed there."""+ """A dense-encoder fallback re-plan that selects offload must re-take the seed decision."""import core.inference.diffusion_te_prequant as teimport core.inference.video as video_moddiff --git a/studio/backend/tests/test_video_prequant.py b/studio/backend/tests/test_video_prequant.pyindex c37b527b617..1a881e89a80 100644--- a/studio/backend/tests/test_video_prequant.py+++ b/studio/backend/tests/test_video_prequant.py@@ -1378,6 +1378,7 @@ def test_the_conventional_auto_scheme_needs_an_artifact_for_every_expert(monkeypdef test_auto_is_handed_the_probe_that_lets_it_reach_a_prequant_only_scheme(monkeypatch):+ """AUTO offers nvfp4 only where a hosted checkpoint provably covers THIS load."""assert _video_auto(monkeypatch, scheme = "nvfp4") == "nvfp4"probe = _video_auto.calls[-1]["has_prequant"]assert probe("nvfp4") is True@@ -1430,7 +1431,6 @@ def _a14b_auto(fam = None,allowed = None,):- """Real selector, preference table and coverage resolver for the shipped A14B family."""import typesimport core.inference.diffusion_nvfp4_ops as ops@@ -1502,7 +1502,7 @@ def test_the_a14b_auto_plan_falls_through_when_the_fp4_kernel_is_missing(monkeypdef _planned_denoiser_request(monkeypatch, fam, **load_kwargs):- """The scheme the planner hands ``_denoiser_prequant_verified`` (stubbed, as is the build)."""+ """The scheme the download planner hands ``_denoiser_prequant_verified``; only the Hub probe is stubbed."""from core.inference import video as vidbackend = vid.VideoBackend()@@ -1532,7 +1532,6 @@ def _planned_denoiser_request(monkeypatch, fam, **load_kwargs):def test_a_conventional_plan_drops_no_shard_the_load_will_not_seed(monkeypatch):- """Only the planned seed drops shards: a conventional load never forwards the raw request."""from core.inference.video_families import detect_video_familywan = detect_video_family("Wan-AI/Wan2.2-TI2V-5B-Diffusers")@@ -1552,7 +1551,7 @@ def test_a_conventional_plan_drops_no_shard_the_load_will_not_seed(monkeypatch):def test_a_seed_the_plan_declined_is_pinned_into_the_load(monkeypatch):- """The plan's decline travels as its own value: the load cannot re-decide on a roomier card."""+ """The plan runs with the PREVIOUS pipeline resident, so its decline travels as its own value, not None."""from core.inference import video as vidfrom core.inference.video_families import detect_video_family@@ -1590,7 +1589,6 @@ def test_a_seed_the_plan_declined_is_pinned_into_the_load(monkeypatch):def test_the_seeded_denoiser_repo_is_claimed_against_a_concurrent_delete(monkeypatch):- """The seeded denoiser's repo (neither repo_id nor base_repo) joins the in-flight claim."""from core.inference import video as vidfrom core.inference.video_families import detect_video_family@@ -1632,7 +1630,6 @@ def test_both_experts_of_an_moe_resolve_to_one_claimed_repo():def test_the_seeded_denoiser_artifact_is_fetched_under_the_load_cancel_event(monkeypatch):- """The seeded artifact is prefetched under the load's cancel event, not by the injection."""import threadingfrom core.inference import video as vid