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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Per-block U-Net compile (SDXL) and the background compile that a render pauses between blocks instead of waiting
for the whole compile. CPU only: ``Module.compile`` is lazy, and the "compiled" block calls below are stand-ins
that take time like a block graph's first compile."""
from __future__ import annotations
import logging
import threading
import time
from types import SimpleNamespace
import pytest
torch = pytest.importorskip("torch")
from core.inference import diffusion_bg_compile as bg # noqa: E402
from core.inference import diffusion_speed as ds # noqa: E402
from core.inference.diffusion_autoopt import targets # noqa: E402
LOG = logging.getLogger("test_unet_block_compile")
@pytest.mark.parametrize(
"raw, on",
[
(None, True),
("", True),
("1", True),
("0", False),
("off", False),
("False", False),
("no", False),
],
)
def test_unet_regional_switch(monkeypatch, raw, on):
if raw is None:
monkeypatch.delenv(targets.UNET_REGIONAL_ENV, raising = False)
else:
monkeypatch.setenv(targets.UNET_REGIONAL_ENV, raw)
assert targets.unet_regional_enabled() is on
unet = _tiny_unet()
assert ds.unet_compiles_regionally(unet) is on
assert ds.unet_compiles_regionally(unet, max_autotune = True) is False
assert ds.unet_compiles_regionally(None) is False
# nothing to compile per block (not a torch module, or no repeated block): the whole-module compile
assert ds.unet_compiles_regionally(object()) is False
assert ds.unet_compiles_regionally(torch.nn.Linear(2, 2)) is False
@pytest.mark.parametrize(
"raw, eager_s, want",
[
(None, None, 0.0),
(None, 2.8, 2.8),
(None, 99.0, 30.0),
(None, -1.0, 0.0),
(None, float("nan"), 0.0),
("5", 2.8, 5.0),
("0", 2.8, 0.0),
("junk", 2.8, 2.8),
],
)
def test_slice_seconds(monkeypatch, raw, eager_s, want):
if raw is None:
monkeypatch.delenv(bg.SLICE_ENV, raising = False)
else:
monkeypatch.setenv(bg.SLICE_ENV, raw)
assert bg.slice_seconds(eager_s) == pytest.approx(want)
def _tiny_unet():
diffusers = pytest.importorskip("diffusers")
return diffusers.UNet2DConditionModel(
sample_size = 8,
in_channels = 4,
out_channels = 4,
layers_per_block = 1,
block_out_channels = (8, 16),
down_block_types = ("DownBlock2D", "CrossAttnDownBlock2D"),
up_block_types = ("CrossAttnUpBlock2D", "UpBlock2D"),
cross_attention_dim = 8,
attention_head_dim = 2,
norm_num_groups = 4,
).eval()
def _compiled_blocks(unet):
return [
m
for m in unet.modules()
if m is not unet and getattr(m, "_compiled_call_impl", None) is not None
]
@pytest.fixture
def _restore_dynamo_limits():
import torch._dynamo
cfg = torch._dynamo.config
saved = {a: getattr(cfg, a) for a in ("recompile_limit", "cache_size_limit") if hasattr(cfg, a)}
yield
for a, v in saved.items():
setattr(cfg, a, v)
def test_unet_compiles_its_repeated_blocks_not_the_whole_module(
monkeypatch, _restore_dynamo_limits
):
monkeypatch.delenv(targets.UNET_REGIONAL_ENV, raising = False)
unet = _tiny_unet()
pipe = SimpleNamespace(unet = unet)
assert ds._compile_repeated_blocks(pipe, LOG) is True
assert getattr(unet, "_compiled_call_impl", None) is None
names = {type(m).__name__ for m in _compiled_blocks(unet)}
assert names == set(targets.UNET_REGIONAL_BLOCKS)
# every compiled block sits behind the compile guard (fallback to eager, background-compile gating)
assert all(
getattr(m._compiled_call_impl, "_unsloth_compile_guard", None)
for m in _compiled_blocks(unet)
)
assert unet._unsloth_bg_yield is True
assert unet._unsloth_regional_compile_kwargs == {"fullgraph": True, "dynamic": False}
# the guard is found like a DiT's, so a compile failure is reported
assert unet in ds._guarded_dits(pipe)
assert ds.compile_fallback_error(pipe) is None
unet._unsloth_compile_guard.error = "InductorError: boom"
assert ds.compile_fallback_error(pipe) == "InductorError: boom"
def test_unet_kill_switch_keeps_the_whole_module_compile(monkeypatch, _restore_dynamo_limits):
monkeypatch.setenv(targets.UNET_REGIONAL_ENV, "0")
unet = _tiny_unet()
assert ds._compile_repeated_blocks(SimpleNamespace(unet = unet), LOG) is True
assert getattr(unet, "_compiled_call_impl", None) is not None
assert _compiled_blocks(unet) == [] # no block compiled on its own
assert not getattr(unet, "_unsloth_bg_yield", False)
def test_max_autotune_keeps_the_whole_module_compile(monkeypatch, _restore_dynamo_limits):
monkeypatch.delenv(targets.UNET_REGIONAL_ENV, raising = False)
unet = _tiny_unet()
assert ds._compile_repeated_blocks(SimpleNamespace(unet = unet), LOG, max_autotune = True) is True
assert getattr(unet, "_compiled_call_impl", None) is not None
def test_compile_cache_key_names_the_block_graphs(monkeypatch):
from core.inference.diffusion_autoopt import plan
unet = _tiny_unet()
pipe = SimpleNamespace(unet = unet, vae = None)
kw = dict(speed_mode = "default", fullgraph = True, offload_below_hooks = False, deferred = True)
monkeypatch.delenv(targets.UNET_REGIONAL_ENV, raising = False)
assert plan.compile_cache_kwargs(pipe, **kw)["unet_graph"] == "blocks"
monkeypatch.setenv(targets.UNET_REGIONAL_ENV, "0")
assert "unet_graph" not in plan.compile_cache_kwargs(pipe, **kw)
# a DiT pipe's key is unchanged
monkeypatch.delenv(targets.UNET_REGIONAL_ENV, raising = False)
assert "unet_graph" not in plan.compile_cache_kwargs(SimpleNamespace(vae = None), **kw)
class _Blocks(torch.nn.Module):
"""A denoiser of N guarded blocks whose first compiled call takes ``compile_s`` (a block graph compile)."""
def __init__(
self,
n: int = 6,
compile_s: float = 0.15,
yields: bool = True,
) -> None:
super().__init__()
self.blocks = torch.nn.ModuleList(torch.nn.Linear(4, 4) for _ in range(n))
self.compiled_calls = 0
self.compiled_blocks: set = set()
for i, blk in enumerate(self.blocks):
blk._compiled_call_impl = self._fake_compiled(i, blk, compile_s)
ds.guard_compiled_blocks(self, LOG)
if yields:
self._unsloth_bg_yield = True
def _fake_compiled(self, index, blk, compile_s):
def compiled(*args, **kwargs):
if index not in self.compiled_blocks:
time.sleep(compile_s)
self.compiled_blocks.add(index)
self.compiled_calls += 1
return blk.forward(*args, **kwargs)
return compiled
def forward(self, x):
for blk in self.blocks:
x = blk(x)
return x
def _armed(net):
job = bg.arm(net, logger = LOG)
assert job is not None
with torch.no_grad(), bg.force_eager():
net(torch.randn(2, 4)) # records the sample; the guard routes the blocks eager
assert net.compiled_calls == 0 and len(job.samples) == 1
return job
def _wait_for(pred, timeout = 10.0):
t0 = time.time()
while not pred():
if time.time() - t0 > timeout:
raise AssertionError("timed out")
time.sleep(0.01)
def test_a_render_pauses_the_compile_between_blocks_and_it_resumes(monkeypatch):
monkeypatch.setenv(bg.IDLE_ENV, "0")
monkeypatch.delenv(bg.YIELD_ENV, raising = False)
net = _Blocks(n = 6, compile_s = 0.15)
job = _armed(net)
assert job.yields()
assert job.kick() and job.compiling()
_wait_for(lambda: len(net.compiled_blocks) >= 1)
waited, paused = job.pause(budget_s = 0.0)
assert paused
assert waited < 0.15 + 0.5 # at most the block graph in flight
done_at_pause = len(net.compiled_blocks)
assert done_at_pause < 6
time.sleep(0.5) # parked: no progress while the render runs
assert len(net.compiled_blocks) == done_at_pause
assert job.compiling()
# the render runs eager beside the parked compile
with torch.no_grad(), bg.force_eager():
calls = net.compiled_calls
net(torch.randn(2, 4))
assert net.compiled_calls == calls
job.resume()
_wait_for(lambda: job.state == "done")
assert len(net.compiled_blocks) == 6
assert job.pauses == 1 and job.paused_s >= 0.4
assert job.describe()["pauses"] == 1
def test_a_compile_that_ends_inside_the_slice_is_not_paused(monkeypatch):
monkeypatch.setenv(bg.IDLE_ENV, "0")
monkeypatch.delenv(bg.YIELD_ENV, raising = False)
net = _Blocks(n = 4, compile_s = 0.3)
job = _armed(net)
job.kick()
_wait_for(lambda: job.graph_s is not None) # one block graph timed
assert job.graph_s == pytest.approx(0.3, abs = 0.15)
waited, paused = job.pause(budget_s = 5.0)
assert not paused and job.state == "done"
assert waited < 5.0
job.resume() # harmless without a pause held
def test_the_pause_is_asked_one_block_graph_before_the_slice_ends(monkeypatch):
monkeypatch.setenv(bg.IDLE_ENV, "0")
monkeypatch.delenv(bg.YIELD_ENV, raising = False)
net = _Blocks(n = 12, compile_s = 0.4)
job = _armed(net)
job.kick()
_wait_for(lambda: job.graph_s is not None)
waited, paused = job.pause(budget_s = 1.0)
assert paused
# asked at ~0.6 s, the graph in flight ends by ~1.0 s (+ its own jitter); never slice + a whole graph
assert 0.5 <= waited < 1.0 + 0.3
job.resume()
_wait_for(lambda: job.state == "done")
def test_back_to_back_renders_cannot_starve_the_compile(monkeypatch):
monkeypatch.setenv(bg.IDLE_ENV, "0")
monkeypatch.delenv(bg.YIELD_ENV, raising = False)
net = _Blocks(n = 5, compile_s = 0.3)
job = _armed(net)
job.kick()
renders = 0
while job.compiling() and renders < 50:
_, paused = job.pause(budget_s = 0.0) # every render asks at once
if paused:
job.resume()
renders += 1
_wait_for(lambda: job.state == "done")
# each resume owes one block graph before the next park: at most one render per graph (+ the first)
assert renders <= 5 + 1
assert len(net.compiled_blocks) == 5
def test_nested_pause_runs_no_second_slice(monkeypatch):
monkeypatch.setenv(bg.IDLE_ENV, "0")
monkeypatch.delenv(bg.YIELD_ENV, raising = False)
net = _Blocks(n = 6, compile_s = 0.2)
job = _armed(net)
job.kick()
_, paused = job.pause(budget_s = 0.0)
assert paused
t0 = time.time()
_, paused2 = job.pause(budget_s = 5.0) # a hires pass inside the paused render
assert paused2 and time.time() - t0 < 1.0
job.resume()
time.sleep(0.4)
assert job.compiling() # still held by the outer render
job.resume()
_wait_for(lambda: job.state == "done")
def test_close_ends_a_parked_compile(monkeypatch):
monkeypatch.setenv(bg.IDLE_ENV, "0")
monkeypatch.delenv(bg.YIELD_ENV, raising = False)
net = _Blocks(n = 6, compile_s = 0.15)
job = _armed(net)
job.kick()
_, paused = job.pause(budget_s = 0.0)
assert paused
thread = job._thread
job.close(timeout = 5.0)
assert not thread.is_alive()
assert job.state == "failed" and "closed" in (job.error or "")
@pytest.mark.parametrize("env, flag", [("0", True), (None, False)])
def test_without_yield_a_pause_waits_for_the_whole_compile(monkeypatch, env, flag):
monkeypatch.setenv(bg.IDLE_ENV, "0")
if env is None:
monkeypatch.delenv(bg.YIELD_ENV, raising = False)
else:
monkeypatch.setenv(bg.YIELD_ENV, env)
net = _Blocks(n = 4, compile_s = 0.1, yields = flag)
job = _armed(net)
assert not job.yields()
job.kick()
_wait_for(lambda: len(net.compiled_blocks) >= 1)
_, paused = job.pause(budget_s = 0.0)
# no yield point is armed: the thread never parks, the pause returns when the compile ends
assert job.state == "done" and len(net.compiled_blocks) == 4
job.resume()
def test_yield_point_is_a_no_op_off_the_compile_thread():
bg.yield_point() # no active compile on this thread
class _FakeBg:
def __init__(
self,
yields: bool,
compiling: bool = True,
) -> None:
self._yields, self._compiling = yields, compiling
self.calls: list = []
def compiling(self):
return self._compiling
def yields(self):
return self._yields
def pause(
self,
cancel = None,
budget_s = 0.0,
):
self.calls.append(("pause", budget_s))
return 0.1, True
def wait(self, cancel = None):
self.calls.append(("wait",))
return 0.2
def _state(loras = ()):
pipe = SimpleNamespace(_unsloth_loras = loras, _unsloth_eager_render_s = 2.5)
return SimpleNamespace(pipe = pipe, speed_optims = ())
def test_render_pauses_a_yielding_compile_for_one_slice(monkeypatch):
from core.inference import diffusion as d
monkeypatch.delenv(bg.SLICE_ENV, raising = False)
fake = _FakeBg(yields = True)
assert d._wait_or_pause_bg_compile(fake, _state(), None, threading.Event()) is fake
assert fake.calls == [("pause", 2.5)]
@pytest.mark.parametrize(
"yields, loras, attached",
[(False, None, ()), (True, [("some/lora", 1.0)], ()), (True, None, (("a", "p", 1.0),))],
)
def test_render_waits_for_the_whole_compile_otherwise(yields, loras, attached):
from core.inference import diffusion as d
fake = _FakeBg(yields = yields)
assert d._wait_or_pause_bg_compile(fake, _state(attached), loras, threading.Event()) is None
assert fake.calls == [("wait",)]
def test_no_compile_in_flight_neither_waits_nor_pauses():
from core.inference import diffusion as d
fake = _FakeBg(yields = True, compiling = False)
assert d._wait_or_pause_bg_compile(fake, _state(), None, threading.Event()) is None
assert d._wait_or_pause_bg_compile(None, _state(), None, threading.Event()) is None
assert fake.calls == []
def test_note_eager_render_keeps_the_fastest_eager_render():
from core.inference import diffusion as d
state = SimpleNamespace(pipe = SimpleNamespace(), speed_optims = ())
d._note_eager_render(state, False, 4.1)
d._note_eager_render(state, False, 2.8)
d._note_eager_render(state, True, 10.1)
assert state.pipe._unsloth_eager_render_s == pytest.approx(2.8)
compiled = SimpleNamespace(pipe = state.pipe, speed_optims = ("compiled",))
d._note_eager_render(compiled, False, 1.0) # a compiled render is not an eager one
assert state.pipe._unsloth_eager_render_s == pytest.approx(2.8)
d._note_eager_render(compiled, True, 2.0) # eager beside a pending compile
assert state.pipe._unsloth_eager_render_s == pytest.approx(2.0)
@pytest.fixture
def _fake_pool(monkeypatch):
from torch._inductor import async_compile
calls: list = []
monkeypatch.setattr(
async_compile.AsyncCompile, "warm_pool", classmethod(lambda cls: calls.append("warm"))
)
monkeypatch.setattr(
async_compile.AsyncCompile, "wakeup", classmethod(lambda cls: calls.append("wakeup"))
)
monkeypatch.setattr(bg, "_POOL_WARMED", False)
monkeypatch.delenv(bg.WARM_POOL_ENV, raising = False)
monkeypatch.delenv("UNSLOTH_DIFFUSION_BG_COMPILE", raising = False)
return calls
def test_warm_compile_pool_starts_the_workers_once(_fake_pool):
assert bg.warm_compile_pool(LOG) is True
assert bg.warm_compile_pool(LOG) is False
assert _fake_pool == ["warm", "wakeup"]
@pytest.mark.parametrize(
"env", ["UNSLOTH_DIFFUSION_BG_COMPILE_WARM_POOL", "UNSLOTH_DIFFUSION_BG_COMPILE"]
)
def test_warm_compile_pool_switches(monkeypatch, _fake_pool, env):
monkeypatch.setenv(env, "0")
assert bg.warm_compile_pool(LOG) is False
assert _fake_pool == []