Skip to content

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

Studio: faster first start for image loads (VAE kernel prebuild, early quant probe, one FLUX.1 single-block graph) (#12666)

Daniel Hanec806236d760
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 640405d3b5d..ea5bc5e4862 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -7407,6 +7407,11 @@ class DiffusionBackend:
self._raise_if_load_cancelled(_load_token)
self._state = state
state_committed = True
+ try:
+ from . import diffusion_vae_prebuild
+ diffusion_vae_prebuild.maybe_kick(pipe, compile_ctx, logger)
+ except Exception: # noqa: BLE001 - a prebuild, never a failed load
+ pass
except BaseException as exc:
_clear_exception_frames(exc)
raise
@@ -10114,6 +10119,9 @@ class DiffusionBackend:
# Restore the process-wide backend flags this load flipped so the next `off` load is bit-identical. All
# idempotent.
restore_backend_flags(state.backend_flags_before)
+ prebuild = sys.modules.get(f"{__package__}.diffusion_vae_prebuild")
+ if prebuild is not None:
+ prebuild.cancel_all()
compile_cache.restore(state.compile_cache_ctx, logger = logger)
# Before clear_gpu_cache(), or the graph pool stays reserved for the life of the process.
cuda_graph.uninstall_all(state.cuda_graphs)
diff --git a/studio/backend/core/inference/diffusion_block_restride.py b/studio/backend/core/inference/diffusion_block_restride.py
new file mode 100644
index 00000000000..556e40886ec
--- /dev/null
+++ b/studio/backend/core/inference/diffusion_block_restride.py
@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Give FLUX.1's first single block the slice layout of blocks 1..37 so all 38 share one compiled graph.
+
+Block 0 gets two separate tensors; the rest get two slices of one ``[B, text + image, D]`` buffer. Dynamo guards on
+strides, so block 0 otherwise compiles a second graph ("stride mismatch at index 0"). The block concatenates its
+inputs first, so copying them into one buffer is value-identical. ``UNSLOTH_DIFFUSION_BLOCK_RESTRIDE=0`` disables it.
+"""
+
+from __future__ import annotations
+
+import inspect
+import os
+from typing import Any
+
+_ENV = "UNSLOTH_DIFFUSION_BLOCK_RESTRIDE"
+_FALSE = ("0", "false", "no", "off")
+_TARGETS = {
+ "FluxTransformer2DModel": ("single_transformer_blocks", "FluxSingleTransformerBlock"),
+}
+_MARK = "_unsloth_block_restride"
+
+
+def enabled() -> bool:
+ return (os.environ.get(_ENV) or "").strip().lower() not in _FALSE
+
+
+def _takes_both_streams(block: Any) -> bool:
+ try:
+ params = inspect.signature(type(block).forward).parameters
+ except (TypeError, ValueError):
+ return False
+ return "hidden_states" in params and "encoder_hidden_states" in params
+
+
+def _restrided(hidden: Any, encoder: Any) -> Any:
+ """``(hidden, encoder)`` as slices of one buffer, or None when the pair is not the shape this targets."""
+ import torch
+
+ if not (isinstance(hidden, torch.Tensor) and isinstance(encoder, torch.Tensor)):
+ return None
+ if hidden.dim() != 3 or encoder.dim() != 3:
+ return None
+ if hidden.shape[0] != encoder.shape[0] or hidden.shape[2] != encoder.shape[2]:
+ return None
+ if hidden.dtype != encoder.dtype or hidden.device != encoder.device:
+ return None
+ if hidden.requires_grad or encoder.requires_grad:
+ return None
+ batch, text, dim = encoder.shape
+ image = hidden.shape[1]
+ if hidden.stride() == ((text + image) * dim, dim, 1) and encoder.stride() == hidden.stride():
+ return None
+ buf = torch.empty((batch, text + image, dim), dtype = hidden.dtype, device = hidden.device)
+ buf[:, :text].copy_(encoder)
+ buf[:, text:].copy_(hidden)
+ return buf[:, text:], buf[:, :text]
+
+
+def install(transformer: Any, logger: Any = None) -> bool:
+ """Wrap the first single block's compiled call. Idempotent; True when installed. Never raises."""
+ if not enabled():
+ return False
+ try:
+ target = _TARGETS.get(type(transformer).__name__)
+ if target is None:
+ return False
+ attr, block_cls = target
+ blocks = getattr(transformer, attr, None)
+ if blocks is None or len(blocks) < 2:
+ return False
+ first = blocks[0]
+ if type(first).__name__ != block_cls or not _takes_both_streams(first):
+ return False
+ compiled = getattr(first, "_compiled_call_impl", None)
+ if compiled is None:
+ return False
+ if getattr(compiled, _MARK, False):
+ return True
+
+ def restride(*args: Any, **kwargs: Any) -> Any:
+ if not args and "hidden_states" in kwargs and "encoder_hidden_states" in kwargs:
+ pair = _restrided(kwargs["hidden_states"], kwargs["encoder_hidden_states"])
+ if pair is not None:
+ kwargs = dict(kwargs)
+ kwargs["hidden_states"], kwargs["encoder_hidden_states"] = pair
+ return compiled(*args, **kwargs)
+
+ setattr(restride, _MARK, True)
+ # Keep the guard's identity visible: guard_compiled_blocks skips modules already wrapped.
+ guard = getattr(compiled, "_unsloth_compile_guard", None)
+ if guard is not None:
+ restride._unsloth_compile_guard = guard # type: ignore[attr-defined]
+ first._compiled_call_impl = restride
+ if logger is not None:
+ logger.info(
+ "diffusion.block_restride: %s[0] gets the slice layout of blocks 1..%d (one compiled graph)",
+ attr,
+ len(blocks) - 1,
+ )
+ return True
+ except Exception as exc: # noqa: BLE001 - optimisation only
+ if logger is not None:
+ logger.warning("diffusion.block_restride: skipped (%s: %s)", type(exc).__name__, exc)
+ return False
diff --git a/studio/backend/core/inference/diffusion_probe_cache.py b/studio/backend/core/inference/diffusion_probe_cache.py
index 83323e2e58d..4dac266e73a 100644
--- a/studio/backend/core/inference/diffusion_probe_cache.py
+++ b/studio/backend/core/inference/diffusion_probe_cache.py
@@ -52,6 +52,15 @@ def _cache_file() -> Optional[Path]:
return None
+def has_file() -> bool:
+ """A verdict file exists (stdlib only, no key check): a later start that will most likely read its table."""
+ path = _cache_file() if enabled() else None
+ try:
+ return path is not None and path.is_file() and path.stat().st_size > 0
+ except OSError:
+ return False
+
+
def _source_digest() -> str:
global _SOURCE_DIGEST
if _SOURCE_DIGEST is None:
diff --git a/studio/backend/core/inference/diffusion_speed.py b/studio/backend/core/inference/diffusion_speed.py
index 32f7490124f..4ccb7883bd0 100644
--- a/studio/backend/core/inference/diffusion_speed.py
+++ b/studio/backend/core/inference/diffusion_speed.py
@@ -1034,6 +1034,12 @@ def _compile_repeated_blocks(
# 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)
+ # After the guard (it wraps the guarded call): FLUX.1's first single block otherwise compiles a second graph.
+ try:
+ from . import diffusion_block_restride
+ diffusion_block_restride.install(transformer, logger)
+ except Exception as exc: # noqa: BLE001 - optimisation only
+ _warn(logger, "block restride", exc)
# Inductor turns the prefix KV cache's clone into a view of the full K/V buffer, which pins it for the render.
try:
from .diffusion_prefix_kv import install_prefix_kv_compaction
diff --git a/studio/backend/core/inference/diffusion_vae_prebuild.py b/studio/backend/core/inference/diffusion_vae_prebuild.py
new file mode 100644
index 00000000000..c8b0d5a4735
--- /dev/null
+++ b/studio/backend/core/inference/diffusion_vae_prebuild.py
@@ -0,0 +1,201 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Build the fused VAE's Triton kernels in a child process while a first start compiles its denoiser.
+
+The first decode with an empty Triton cache JIT-compiles every fused VAE kernel (~3 s of render 1 on an RTX PRO 6000).
+On a load with no compile bundle, a spawned child rebuilds the VAE from its config without weights, installs the same
+fused passes and decodes zeros at a small latent (same divisibility classes), filling the shared Triton cache. The
+parent never waits; kernels the child has not finished are compiled by the parent as before.
+``UNSLOTH_DIFFUSION_VAE_PREBUILD=0`` disables it.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from typing import Any, Optional
+
+_ENV = "UNSLOTH_DIFFUSION_VAE_PREBUILD"
+_FALSE = ("0", "false", "no", "off")
+# Multiple of 16 at every decoder stage, well under 1 GiB.
+_LATENT_SIDE = 64
+# Free VRAM needed after the load before a second CUDA context opens.
+_MIN_FREE_BYTES = 6 * 1024**3
+_CHILD_TIMEOUT_S = 180.0
+_LIVE: set = set()
+_LIVE_LOCK = threading.Lock()
+
+
+def enabled() -> bool:
+ return (os.environ.get(_ENV) or "").strip().lower() not in _FALSE
+
+
+def _jsonable(value: Any) -> Any:
+ if isinstance(value, (list, tuple)):
+ return [_jsonable(v) for v in value]
+ if isinstance(value, dict):
+ return {str(k): _jsonable(v) for k, v in value.items()}
+ if value is None or isinstance(value, (bool, int, float, str)):
+ return value
+ return str(value)
+
+
+def plan(pipe: Any) -> Optional[dict]:
+ """What the child needs to rebuild ``pipe.vae``'s fused decode, or None when there is nothing to prebuild."""
+ import torch
+
+ vae = getattr(pipe, "vae", None)
+ if vae is None or not getattr(vae, "_unsloth_vae_fused_installed", 0):
+ return None
+ config = getattr(vae, "config", None)
+ if config is None:
+ return None
+ try:
+ decoder = getattr(vae, "decoder", None) or vae
+ weight = next(p for p in decoder.parameters() if p.is_floating_point())
+ except StopIteration:
+ return None
+ if weight.device.type != "cuda":
+ return None
+ cfg = _jsonable(dict(config))
+ z_dim = cfg.get("z_dim")
+ if isinstance(z_dim, int):
+ shape = [1, z_dim, 1, _LATENT_SIDE, _LATENT_SIDE]
+ elif isinstance(cfg.get("latent_channels"), int):
+ shape = [1, cfg["latent_channels"], _LATENT_SIDE, _LATENT_SIDE]
+ else:
+ return None
+ return {
+ "module": type(vae).__module__,
+ "name": type(vae).__name__,
+ "config": cfg,
+ "dtype": str(weight.dtype).replace("torch.", ""),
+ "device": int(
+ weight.device.index if weight.device.index is not None else torch.cuda.current_device()
+ ),
+ "shape": shape,
+ }
+
+
+def maybe_kick(
+ pipe: Any,
+ compile_ctx: Any,
+ logger: Any = None,
+) -> bool:
+ """Spawn the prebuild child for a first-start load (no compile-bundle hit). Never blocks, never raises."""
+ if not enabled():
+ return False
+ try:
+ import torch
+
+ if getattr(torch.version, "hip", None) or not torch.cuda.is_available():
+ return False
+ if compile_ctx is None or getattr(compile_ctx, "hit", False):
+ return False # a restart's Triton cache already holds the kernels
+ job = plan(pipe)
+ if job is None:
+ return False
+ free, _total = torch.cuda.mem_get_info(job["device"])
+ if free < _MIN_FREE_BYTES:
+ return False
+ return _spawn(job, logger)
+ except Exception as exc: # noqa: BLE001 - a prebuild, never a failed load
+ if logger is not None:
+ logger.info("diffusion.vae_prebuild: skipped (%s: %s)", type(exc).__name__, exc)
+ return False
+
+
+def _spawn(job: dict, logger: Any) -> bool:
+ import multiprocessing as mp
+
+ from utils.native_path_leases import (
+ native_path_secret_removed_for_child_start,
+ run_without_native_path_secret,
+ )
+ from utils.process_lifetime import adopt_pid, is_process_shutting_down
+
+ # A quit during the load: the sweep may already have run, so a child started now would outlive the server.
+ if is_process_shutting_down():
+ return False
+ ctx = mp.get_context("spawn")
+ with native_path_secret_removed_for_child_start():
+ proc = ctx.Process(
+ target = run_without_native_path_secret,
+ args = (__name__, "_child_entry", {}, job),
+ daemon = True,
+ )
+ proc.start()
+ with _LIVE_LOCK:
+ _LIVE.add(proc)
+ try:
+ adopt_pid(proc.pid)
+ except Exception: # noqa: BLE001
+ pass
+ # Recheck once the pid is recorded: the latch can be set between the gate above and the adoption.
+ if is_process_shutting_down():
+ _stop(proc)
+ return False
+
+ def reap() -> None:
+ proc.join(_CHILD_TIMEOUT_S)
+ _stop(proc)
+ if logger is not None:
+ logger.info("diffusion.vae_prebuild: child exited (%s)", proc.exitcode)
+
+ threading.Thread(target = reap, name = "unsloth-vae-prebuild-reaper", daemon = True).start()
+ if logger is not None:
+ logger.info(
+ "diffusion.vae_prebuild: building %s's fused kernels in a child (pid %s)",
+ job["name"],
+ proc.pid,
+ )
+ return True
+
+
+def _stop(proc: Any) -> None:
+ with _LIVE_LOCK:
+ _LIVE.discard(proc)
+ if proc.is_alive():
+ proc.kill()
+ proc.join(5.0)
+ try:
+ from utils.process_lifetime import forget_pid
+ if not proc.is_alive():
+ forget_pid(proc.pid)
+ except Exception: # noqa: BLE001
+ pass
+
+
+def cancel_all() -> int:
+ """Kill every live prebuild child (unload: its CUDA context and VAE must not shadow the next load). Never raises."""
+ with _LIVE_LOCK:
+ procs = list(_LIVE)
+ for proc in procs:
+ try:
+ _stop(proc)
+ except Exception: # noqa: BLE001
+ pass
+ return len(procs)
+
+
+def _child_entry(job: dict) -> None:
+ """Child side: same VAE class and config, no weights, the same fused passes, one decode of zeros."""
+ import diffusers
+ import torch
+
+ from core.inference import diffusion_vae_fused
+
+ # Only diffusers' own exported VAE classes: the job names a class, it never picks a module to import.
+ cls = getattr(diffusers, job["name"], None)
+ if cls is None or getattr(cls, "__module__", None) != job["module"]:
+ return
+ torch.cuda.set_device(job["device"])
+ dtype = getattr(torch, job["dtype"])
+ vae = cls.from_config(job["config"]).to(device = f"cuda:{job['device']}", dtype = dtype).eval()
+ if not diffusion_vae_fused.install(vae, None):
+ return
+ with torch.inference_mode():
+ z = torch.zeros(job["shape"], device = f"cuda:{job['device']}", dtype = dtype)
+ vae.decode(z)
+ torch.cuda.synchronize()
diff --git a/studio/backend/tests/test_diffusion_block_restride.py b/studio/backend/tests/test_diffusion_block_restride.py
new file mode 100644
index 00000000000..a7b16960ee5
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_block_restride.py
@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""FLUX.1's first single block gets the slice layout of the other 37, so the regional compile traces ONE graph."""
+
+from __future__ import annotations
+
+import pytest
+
+torch = pytest.importorskip("torch")
+
+import torch._dynamo # noqa: E402
+
+from core.inference import diffusion_block_restride as restride # noqa: E402
+
+
+class FluxSingleTransformerBlock(torch.nn.Module):
+ """Same call contract as diffusers': concatenates text + image itself, returns two slices of one tensor."""
+
+ def __init__(self, dim: int = 8):
+ super().__init__()
+ self.proj = torch.nn.Linear(dim, dim)
+
+ def forward(
+ self,
+ hidden_states,
+ encoder_hidden_states,
+ temb = None,
+ image_rotary_emb = None,
+ joint_attention_kwargs = None,
+ ):
+ text = encoder_hidden_states.shape[1]
+ x = torch.cat([encoder_hidden_states, hidden_states], dim = 1)
+ x = x + self.proj(x)
+ return x[:, :text], x[:, text:]
+
+
+class FluxTransformer2DModel(torch.nn.Module):
+ def __init__(
+ self,
+ n: int = 4,
+ dim: int = 8,
+ ):
+ super().__init__()
+ self.single_transformer_blocks = torch.nn.ModuleList(
+ FluxSingleTransformerBlock(dim) for _ in range(n)
+ )
+
+ def forward(self, hidden_states, encoder_hidden_states):
+ for block in self.single_transformer_blocks:
+ encoder_hidden_states, hidden_states = block(
+ hidden_states = hidden_states,
+ encoder_hidden_states = encoder_hidden_states,
+ temb = None,
+ image_rotary_emb = None,
+ joint_attention_kwargs = None,
+ )
+ return hidden_states
+
+
+def _inputs(
+ batch = 1,
+ text = 3,
+ image = 5,
+ dim = 8,
+):
+ g = torch.Generator().manual_seed(0)
+ return torch.randn(batch, image, dim, generator = g), torch.randn(batch, text, dim, generator = g)
+
+
+def _frames_compiled(model, hidden, encoder) -> int:
+ """Dynamo frames compiled for one forward of a regional-compiled model (eager backend: dynamo only)."""
+ torch._dynamo.reset()
+ graphs = []
+
+ def backend(gm, example_inputs):
+ graphs.append(gm)
+ return gm.forward
+
+ for block in model.single_transformer_blocks:
+ block.compile(backend = backend, fullgraph = True, dynamic = None)
+ restride.install(model)
+ with torch.no_grad():
+ model(hidden, encoder)
+ torch._dynamo.reset()
+ return len(graphs)
+
+
+def test_restrided_pair_is_the_later_blocks_layout_with_the_same_values():
+ hidden, encoder = _inputs(batch = 2)
+ pair = restride._restrided(hidden, encoder)
+ assert pair is not None
+ h2, e2 = pair
+ assert torch.equal(h2, hidden) and torch.equal(e2, encoder)
+ # What diffusers' single block returns: two slices of one [B, text + image, D] tensor.
+ later_e, later_h = FluxSingleTransformerBlock()(hidden, encoder)
+ assert h2.stride() == later_h.stride() and e2.stride() == later_e.stride()
+ assert h2.untyped_storage().data_ptr() == e2.untyped_storage().data_ptr()
+
+
+def test_already_slice_layout_and_mismatched_pairs_pass_through():
+ hidden, encoder = _inputs()
+ e, h = FluxSingleTransformerBlock()(hidden, encoder)
+ assert restride._restrided(h, e) is None
+ assert restride._restrided(hidden, encoder[..., :4]) is None
+ assert restride._restrided(hidden, encoder.double()) is None
+ assert restride._restrided(hidden, None) is None
+
+
+def test_first_single_block_compiles_one_graph_instead_of_two(monkeypatch):
+ model = FluxTransformer2DModel()
+ hidden, encoder = _inputs()
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_BLOCK_RESTRIDE", "0")
+ assert _frames_compiled(model, hidden, encoder) == 2
+ model = FluxTransformer2DModel()
+ monkeypatch.delenv("UNSLOTH_DIFFUSION_BLOCK_RESTRIDE")
+ assert _frames_compiled(model, hidden, encoder) == 1
+
+
+def test_outputs_identical_with_and_without_restride(monkeypatch):
+ torch.manual_seed(0)
+ model = FluxTransformer2DModel()
+ hidden, encoder = _inputs(batch = 2)
+ with torch.no_grad():
+ ref = model(hidden, encoder)
+ assert restride.install(model) is False # nothing compiled: nothing to wrap
+ for block in model.single_transformer_blocks:
+ block.compile(backend = "eager", fullgraph = True)
+ assert restride.install(model) is True
+ assert restride.install(model) is True # idempotent
+ with torch.no_grad():
+ out = model(hidden, encoder)
+ assert torch.equal(ref, out)
+ torch._dynamo.reset()
+
+
+def test_other_transformers_and_kill_switch_are_left_alone(monkeypatch):
+ class Other(FluxTransformer2DModel):
+ pass
+
+ model = Other()
+ for block in model.single_transformer_blocks:
+ block.compile(backend = "eager")
+ assert restride.install(model) is False
+ model = FluxTransformer2DModel()
+ for block in model.single_transformer_blocks:
+ block.compile(backend = "eager")
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_BLOCK_RESTRIDE", "0")
+ before = model.single_transformer_blocks[0]._compiled_call_impl
+ assert restride.install(model) is False
+ assert model.single_transformer_blocks[0]._compiled_call_impl is before
+
+
+def test_positional_calls_pass_through_unchanged():
+ model = FluxTransformer2DModel()
+ seen = []
+ block = model.single_transformer_blocks[0]
+ block._compiled_call_impl = lambda *a, **k: seen.append((a, k)) or (a[1], a[0])
+ assert restride.install(model) is True
+ hidden, encoder = _inputs()
+ block(hidden, encoder)
+ assert seen[0][0][0] is hidden and seen[0][0][1] is encoder
diff --git a/studio/backend/tests/test_diffusion_vae_prebuild.py b/studio/backend/tests/test_diffusion_vae_prebuild.py
new file mode 100644
index 00000000000..2ed33b81d13
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_vae_prebuild.py
@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""First-start fused-VAE Triton prebuild in a child process (``diffusion_vae_prebuild``)."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import textwrap
+import types
+from pathlib import Path
+
+import pytest
+
+torch = pytest.importorskip("torch")
+
+from core.inference import diffusion_vae_prebuild as prebuild # noqa: E402
+
+BACKEND = Path(__file__).resolve().parents[1]
+
+
+class _Param:
+ def __init__(self, dtype, device):
+ self.dtype = dtype
+ self.device = device
+
+ def is_floating_point(self):
+ return True
+
+
+class _Decoder:
+ def __init__(self, param):
+ self._p = param
+
+ def parameters(self):
+ yield self._p
+
+
+def _vae(
+ config,
+ *,
+ fused = 5,
+ device = types.SimpleNamespace(type = "cuda", index = 1),
+):
+ vae = types.SimpleNamespace(config = config, decoder = _Decoder(_Param(torch.bfloat16, device)))
+ vae._unsloth_vae_fused_installed = fused
+ return vae
+
+
+def test_plan_describes_the_class_config_dtype_and_a_small_latent():
+ job = prebuild.plan(
+ types.SimpleNamespace(vae = _vae({"latent_channels": 16, "block_out_channels": (128, 256)}))
+ )
+ assert job["name"] == "SimpleNamespace" and job["dtype"] == "bfloat16" and job["device"] == 1
+ assert job["shape"] == [1, 16, prebuild._LATENT_SIDE, prebuild._LATENT_SIDE]
+ assert job["config"]["block_out_channels"] == [128, 256] # JSON-safe for the spawn
+ video = prebuild.plan(types.SimpleNamespace(vae = _vae({"z_dim": 16})))
+ assert video["shape"] == [1, 16, 1, prebuild._LATENT_SIDE, prebuild._LATENT_SIDE]
+
+
+def test_nothing_to_prebuild_without_fused_passes_on_a_cuda_vae():
+ assert prebuild.plan(types.SimpleNamespace(vae = None)) is None
+ assert prebuild.plan(types.SimpleNamespace(vae = _vae({"latent_channels": 4}, fused = 0))) is None
+ cpu = types.SimpleNamespace(type = "cpu", index = None)
+ assert (
+ prebuild.plan(types.SimpleNamespace(vae = _vae({"latent_channels": 4}, device = cpu))) is None
+ )
+ assert prebuild.plan(types.SimpleNamespace(vae = _vae({"something_else": 1}))) is None
+
+
+def test_restart_and_kill_switch_never_spawn(monkeypatch):
+ spawned = []
+ monkeypatch.setattr(prebuild, "_spawn", lambda job, logger: spawned.append(job) or True)
+ monkeypatch.setattr(prebuild, "plan", lambda pipe: {"device": 0})
+ monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
+ monkeypatch.setattr(torch.cuda, "mem_get_info", lambda device: (64 * 1024**3, 96 * 1024**3))
+ pipe = types.SimpleNamespace()
+ assert (
+ prebuild.maybe_kick(pipe, types.SimpleNamespace(hit = True)) is False
+ ) # restart: cache already warm
+ assert prebuild.maybe_kick(pipe, None) is False # no compile bundle at all
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_VAE_PREBUILD", "0")
+ assert prebuild.maybe_kick(pipe, types.SimpleNamespace(hit = False)) is False
+ monkeypatch.delenv("UNSLOTH_DIFFUSION_VAE_PREBUILD")
+ monkeypatch.setattr(torch.cuda, "mem_get_info", lambda device: (2 * 1024**3, 24 * 1024**3))
+ assert (
+ prebuild.maybe_kick(pipe, types.SimpleNamespace(hit = False)) is False
+ ) # too little VRAM for a 2nd context
+ monkeypatch.setattr(torch.cuda, "mem_get_info", lambda device: (64 * 1024**3, 96 * 1024**3))
+ assert prebuild.maybe_kick(pipe, types.SimpleNamespace(hit = False)) is True
+ assert spawned == [{"device": 0}]
+
+
+def test_a_quit_during_the_load_never_starts_the_child(monkeypatch):
+ import multiprocessing as mp
+
+ from utils import process_lifetime
+
+ started = []
+ monkeypatch.setattr(mp, "get_context", lambda method: started.append(method))
+ monkeypatch.setattr(process_lifetime, "is_process_shutting_down", lambda: True)
+ assert prebuild._spawn({"name": "AutoencoderKL"}, None) is False
+ assert started == []
+
+
+def test_unload_kills_a_child_that_is_still_building():
+ class _Proc:
+ pid = None
+ alive = True
+
+ def is_alive(self):
+ return self.alive
+
+ def kill(self):
+ self.alive = False
+
+ def join(self, timeout = None):
+ pass
+
+ proc = _Proc()
+ prebuild._LIVE.add(proc)
+ assert prebuild.cancel_all() == 1
+ assert proc.alive is False and proc not in prebuild._LIVE
+ assert prebuild.cancel_all() == 0
+
+
+_SCRIPT = textwrap.dedent(
+ r"""
+ import os, sys, json
+ sys.path.insert(0, os.environ["BACKEND"])
+ import torch
+ from diffusers import AutoencoderKL
+ from core.inference import diffusion_vae_fused, diffusion_vae_prebuild as prebuild
+
+ cfg = dict(block_out_channels = [32, 64], down_block_types = ["DownEncoderBlock2D"] * 2,
+ up_block_types = ["UpDecoderBlock2D"] * 2, latent_channels = 4, norm_num_groups = 32,
+ layers_per_block = 1)
+ vae = AutoencoderKL.from_config(cfg).cuda().to(torch.bfloat16).eval()
+ if not diffusion_vae_fused.install(vae, None):
+ print("RESULT", json.dumps({"skip": "fused VAE does not install here"}))
+ raise SystemExit
+ cache = os.environ["TRITON_CACHE_DIR"]
+ count = lambda: sum(len(f) for _, _, f in os.walk(cache))
+ mode = sys.argv[1]
+ if mode == "child":
+ prebuild._child_entry(prebuild.plan(type("P", (), {"vae": vae})()))
+ print("RESULT", json.dumps({"files": count()}))
+ else:
+ before = count()
+ with torch.inference_mode():
+ vae.decode(torch.zeros(1, 4, 128, 128, device = "cuda", dtype = torch.bfloat16))
+ torch.cuda.synchronize()
+ print("RESULT", json.dumps({"before": before, "after": count()}))
+ """
+)
+
+
+def _run(tmp_path: Path, mode: str) -> dict:
+ import json
+
+ env = dict(
+ os.environ,
+ BACKEND = str(BACKEND),
+ TRITON_CACHE_DIR = str(tmp_path / "triton"),
+ PYTHONPATH = str(BACKEND),
+ )
+ r = subprocess.run(
+ [sys.executable, "-c", _SCRIPT, mode],
+ cwd = str(BACKEND),
+ env = env,
+ capture_output = True,
+ text = True,
+ timeout = 900,
+ )
+ line = [ln for ln in r.stdout.splitlines() if ln.startswith("RESULT ")]
+ assert line, r.stdout[-3000:] + r.stderr[-3000:]
+ return json.loads(line[-1][len("RESULT ") :])
+
+
+ not torch.cuda.is_available(),
+ reason = "the child JIT-compiles real Triton kernels, which needs a CUDA GPU",
+)
+def test_child_fills_the_triton_cache_the_full_size_decode_then_reads(tmp_path):
+ child = _run(tmp_path, "child")
+ if "skip" in child:
+ pytest.skip(
+ child["skip"]
+ ) # e.g. Triton absent / fused passes refuse this GPU: nothing to prebuild
+ assert child["files"] > 0
+ parent = _run(tmp_path, "parent")
+ # A full-resolution decode in a fresh process compiles nothing new: every kernel came from the child's 64x64 decode.
+ assert parent["after"] == parent["before"], parent
diff --git a/studio/backend/tests/test_early_quant_probe.py b/studio/backend/tests/test_early_quant_probe.py
new file mode 100644
index 00000000000..8fdf245578e
--- /dev/null
+++ b/studio/backend/tests/test_early_quant_probe.py
@@ -0,0 +1,101 @@
+# 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 quant smoke probe's child starts during the torch warm (after dynamo is imported), not after diffusers."""
+
+from __future__ import annotations
+
+import threading
+
+import pytest
+
+
+def warm(monkeypatch):
+ from utils import torch_warmup
+
+ monkeypatch.delenv(torch_warmup.EARLY_PROBE_ENV_VAR, raising = False)
+ # _warm() publishes into the module-level status; keep that out of later tests.
+ monkeypatch.setattr(
+ torch_warmup, "_status", {"started": False, "finished": False, "stages": {}}
+ )
+ return torch_warmup
+
+
+def test_probe_is_kicked_right_after_the_dynamo_import_stage(warm, monkeypatch):
+ order: list[str] = []
+ stages = tuple(
+ (name, (lambda n = name: order.append(n)))
+ for name in ("hardware", "inference_backend", "transformers", "datasets")
+ )
+ monkeypatch.setattr(warm, "_STAGES", stages)
+ monkeypatch.setattr(warm, "_kick_early_quant_probe", lambda: order.append("probe"))
+ monkeypatch.setattr(warm, "_detection_epoch", lambda: None)
+ warm._warm(epoch = None)
+ assert order == ["hardware", "inference_backend", "probe", "transformers", "datasets"]
+
+
+def test_kick_runs_the_existing_prewarm_on_a_daemon_thread_only_for_diffusers_installs(
+ warm, monkeypatch
+):
+ calls: list[str] = []
+ ran = threading.Event()
+
+ def prewarm() -> None:
+ calls.append(threading.current_thread().name)
+ ran.set()
+
+ monkeypatch.setattr(warm, "_prewarm_quant_probe", prewarm)
+ monkeypatch.setattr(warm, "_a_local_model_would_load_through_diffusers", lambda: True)
+ from core.inference import diffusion_probe_cache
+
+ monkeypatch.setattr(diffusion_probe_cache, "has_file", lambda: False)
+ thread = warm._kick_early_quant_probe()
+ assert thread is not None and thread.daemon
+ thread.join(10)
+ assert calls == ["early-quant-probe"]
+
+ calls.clear()
+ monkeypatch.setattr(warm, "_a_local_model_would_load_through_diffusers", lambda: False)
+ warm._kick_early_quant_probe().join(10)
+ assert calls == [] # chat-only / training-only installs pay nothing
+
+ def broken() -> bool:
+ raise RuntimeError("index unreadable")
+
+ monkeypatch.setattr(warm, "_a_local_model_would_load_through_diffusers", broken)
+ warm._kick_early_quant_probe().join(10)
+ assert calls == []
+
+
+def test_a_later_start_with_a_persisted_table_does_not_import_the_probe_during_the_warm(
+ warm, monkeypatch
+):
+ from core.inference import diffusion_probe_cache
+
+ monkeypatch.setattr(warm, "_a_local_model_would_load_through_diffusers", lambda: True)
+ monkeypatch.setattr(
+ warm, "_prewarm_quant_probe", lambda: pytest.fail("probe ran although its table is on disk")
+ )
+ monkeypatch.setattr(diffusion_probe_cache, "has_file", lambda: True)
+ warm._kick_early_quant_probe().join(10)
+
+
+def test_probe_cache_file_check(tmp_path, monkeypatch):
+ from core.inference import diffusion_probe_cache
+
+ path = tmp_path / "diffusion_quant_probe.json"
+ monkeypatch.setattr(diffusion_probe_cache, "_cache_file", lambda: path)
+ assert not diffusion_probe_cache.has_file()
+ path.write_text("{}")
+ assert diffusion_probe_cache.has_file()
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_PROBE_CACHE", "0")
+ assert not diffusion_probe_cache.has_file()
+
+
+def test_kill_switch_keeps_the_old_timing(warm, monkeypatch):
+ monkeypatch.setenv(warm.EARLY_PROBE_ENV_VAR, "0")
+ monkeypatch.setattr(
+ warm, "_prewarm_quant_probe", lambda: pytest.fail("probe ran under the kill switch")
+ )
+ assert warm._kick_early_quant_probe() is None
diff --git a/studio/backend/tests/test_orchestrator_unload_cancel.py b/studio/backend/tests/test_orchestrator_unload_cancel.py
index 8b89035b37d..93be3a26433 100644
--- a/studio/backend/tests/test_orchestrator_unload_cancel.py
+++ b/studio/backend/tests/test_orchestrator_unload_cancel.py
@@ -3869,6 +3869,7 @@ def test_every_long_lived_spawner_consults_the_shutdown_latch():
guarded = {
"core/export/orchestrator.py",
"core/inference/audio_cpp_server.py",
+ "core/inference/diffusion_vae_prebuild.py",
"core/inference/engine_install.py",
"core/inference/lemonade_server.py",
"core/inference/llama_cpp.py",
diff --git a/studio/backend/utils/torch_warmup.py b/studio/backend/utils/torch_warmup.py
index 6c7c8994739..7bfae614159 100644
--- a/studio/backend/utils/torch_warmup.py
+++ b/studio/backend/utils/torch_warmup.py
@@ -420,6 +420,9 @@ def _warm(epoch: Optional[int] = None) -> None:
return
# Only the real stage takes the epoch; a patched _STAGES entry is called bare.
_run_stage(name, partial(fn, epoch) if fn is _warm_hardware else fn)
+ if name == "inference_backend":
+ # dynamo is imported by now, so the probe's imports cannot race its first import (#10350).
+ _kick_early_quant_probe()
if epoch is not None and _detection_epoch() != epoch:
# Later stages reach get_device(), republishing DEVICE after teardown.
logger.info("torch warm stopped after %s: its lifespan ended", name)
@@ -600,6 +603,33 @@ def _is_native_video_pick(pick) -> bool:
return False
+EARLY_PROBE_ENV_VAR = "UNSLOTH_DIFFUSION_PROBE_EARLY"
+
+
+def _early_quant_probe() -> None:
+ try:
+ from core.inference.diffusion_probe_cache import has_file # noqa: PLC0415 - stdlib only
+ if has_file():
+ # A later start reads the persisted table; importing the probe module here would only slow the warm.
+ return
+ if not _a_local_model_would_load_through_diffusers():
+ return
+ except Exception as exc: # noqa: BLE001 -- a gate that cannot answer means skip, not crash
+ logger.debug("early quant smoke probe skipped: %r", exc)
+ return
+ _prewarm_quant_probe()
+
+
+def _kick_early_quant_probe() -> Optional[threading.Thread]:
+ """Start the quant smoke probe's child during the warm instead of after the diffusers import (a load posted right
+ after the warm waited ~3 s for it). ``UNSLOTH_DIFFUSION_PROBE_EARLY=0`` keeps the old timing."""
+ if os.environ.get(EARLY_PROBE_ENV_VAR, "").strip().lower() in ("0", "false", "no", "off"):
+ return None
+ thread = threading.Thread(target = _early_quant_probe, name = "early-quant-probe", daemon = True)
+ thread.start()
+ return thread
+
+
def _prewarm_quant_probe() -> None:
"""Run the 4-5 s quant smoke probe here instead of at the first image load; never fatal."""
try: