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
"""Auto static step skip: the per-model policy, its kill switch, joint (video, audio) outputs, and the image loader."""
from __future__ import annotations
import contextlib
import types
import pytest
import torch
from core.inference import diffusion_cache as dcache
from core.inference import diffusion_step_skip as ss
from core.inference.diffusion_families import default_generation_params
from .test_diffusion_backend import _load_into, fake_runtime # noqa: F401 - fixture
def test_min_steps_raises_the_floor_but_never_lowers_it():
assert ss.static_schedule(14, min_steps = 20) == ()
assert ss.static_schedule(20, min_steps = 20) == ss.static_schedule(20)
assert ss.static_schedule(11, min_steps = 4) == ()
assert ss.static_schedule(14, min_steps = 4) == ss.static_schedule(14)
@pytest.fixture
def table(monkeypatch):
monkeypatch.setattr(
dcache,
"AUTO_STATIC_SKIP",
{
"black-forest-labs/flux.1-krea-dev": {"default": 2, "max": 3},
"black-forest-labs/flux.1-dev": {"max": 2},
},
)
monkeypatch.delenv(dcache.ENV_AUTO_STEP_SKIP, raising = False)
KREA = "black-forest-labs/FLUX.1-Krea-dev"
DEV = "black-forest-labs/FLUX.1-dev"
@pytest.mark.parametrize(
"ids, tier, steps, want",
[
((KREA,), "default", 28, None),
((KREA,), "max", 28, {"every": 3, "min_steps": 20}),
((KREA,), "eager", 28, None),
((KREA,), "off", 28, None),
((KREA,), None, 28, None),
((KREA,), "default", 12, None), # a short default schedule is never measured
((DEV,), "default", 28, None),
((DEV,), "max", 28, {"every": 2, "min_steps": 20}),
# The unsloth mirror and a local path with the upstream as its base both resolve to the upstream row.
(("unsloth/FLUX.1-Krea-dev",), "max", 28, {"every": 3, "min_steps": 20}),
(("/models/my-krea", KREA), "max", 28, {"every": 3, "min_steps": 20}),
(("unsloth/FLUX.1-Krea-dev",), "default", 28, None),
(("black-forest-labs/FLUX.1-schnell",), "max", 28, None),
((None,), "max", 28, None),
(KREA, "max", 28, {"every": 3, "min_steps": 20}), # a bare string
],
)
def test_plan_follows_the_tier_and_the_default_steps(table, ids, tier, steps, want):
assert dcache.auto_static_skip_plan(ids, tier, steps) == want
@pytest.mark.parametrize("value", ["0", "false", "off", "NO"])
def test_kill_switch_turns_auto_static_off(table, monkeypatch, value):
monkeypatch.setenv(dcache.ENV_AUTO_STEP_SKIP, value)
assert dcache.auto_static_skip_plan((KREA,), "default", 28) is None
assert dcache.resolve_auto_step_cache("max", 28, static_plan = None) == dcache.TC_FBCACHE
assert dcache.resolve_auto_step_cache("default", 28, static_plan = None) is None
def test_static_plan_wins_over_fbcache_on_max(table):
plan = dcache.auto_static_skip_plan((DEV,), "max", 28)
assert dcache.resolve_auto_step_cache("max", 28, static_plan = plan) == dcache.TC_STATIC
def test_auto_settings_use_the_plan_unless_the_env_pins_every():
plan = {"every": 3, "min_steps": 20}
knobs = ss.auto_static_settings(plan, env = {})
assert (knobs["every"], knobs["min_steps"], knobs["auto"]) == (3, 20, True)
assert knobs["mode"] == ss.DEFAULT_MODE
assert ss.auto_static_settings(plan, env = {ss.ENV_EVERY: "2"})["every"] == 2
MEASURED = {
"Qwen/Qwen-Image-2.1": ("default", "max"),
"Qwen/Qwen-Image": ("default", "max"),
"black-forest-labs/FLUX.1-Krea-dev": ("default", "max"),
"black-forest-labs/FLUX.2-klein-base-4B": ("default", "max"),
"Wan-AI/Wan2.2-TI2V-5B-Diffusers": ("default", "max"),
"black-forest-labs/FLUX.1-dev": ("max",),
"hunyuanvideo-community/HunyuanImage-2.1-Diffusers": ("max",),
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v": ("max",),
"MiniMaxAI/MiniMax-H3": ("max",),
}
def test_shipped_table_lists_only_measured_models():
assert set(dcache.AUTO_STATIC_SKIP) == {k.lower() for k in MEASURED}
for repo, tiers in MEASURED.items():
entry = {k: v for k, v in dcache.AUTO_STATIC_SKIP[repo.lower()].items() if k != "steps"}
assert set(entry) == set(tiers)
assert all(int(v) >= 2 for v in entry.values())
assert entry.get("default", 99) <= entry["max"] or "default" not in entry
@pytest.mark.parametrize("repo", sorted(MEASURED))
def test_every_measured_model_reaches_the_auto_floor_at_its_default_steps(repo):
from core.inference.video_families import default_video_generation_params
steps, _ = default_generation_params(repo)
if repo.startswith(("Wan-AI", "hunyuanvideo-community/HunyuanVideo")):
steps, _ = default_video_generation_params(repo)
if repo == "MiniMaxAI/MiniMax-H3":
steps = 30 # family default; no generation-defaults row
assert steps >= dcache.AUTO_STATIC_MIN_STEPS
assert dcache.auto_static_skip_plan((repo,), "max", steps) is not None
@pytest.mark.parametrize(
"repo",
[
"black-forest-labs/FLUX.1-schnell",
"black-forest-labs/FLUX.2-klein-4B",
"black-forest-labs/FLUX.2-klein-base-9B",
"Tongyi-MAI/Z-Image-Turbo",
"Tongyi-MAI/Z-Image",
"Qwen/Qwen-Image-2512",
"Qwen/Qwen-Image-Edit-2511",
"unsloth/Krea-2-Turbo",
],
)
def test_unmeasured_or_distilled_siblings_never_auto_skip(repo):
steps, _ = default_generation_params(repo)
for tier in ("default", "max"):
assert dcache.auto_static_skip_plan((repo,), tier, max(steps, 50)) is None
class _JointDiT:
"""MiniMax-H3's shape: one call per step returning (video velocity, audio velocity) of different sizes."""
def __init__(self):
self.calls = 0
def forward(
self,
hidden_states = None,
audio_hidden_states = None,
timestep = None,
return_dict = True,
):
self.calls += 1
t = float(timestep.reshape(-1).max())
return torch.full((1, 6, 2), t), torch.full((1, 3), 2 * t)
def _run_joint(pipe, steps):
outs = []
for i in range(steps):
t = torch.tensor([0.0, 1.0 - i / steps]) # conditioning rows at 0, noisy rows at t
outs.append(pipe.transformer.forward(hidden_states = None, timestep = t, return_dict = False))
return outs
@pytest.mark.parametrize("mode", ["reuse", "taylor1"])
def test_joint_video_audio_outputs_are_skipped_stream_by_stream(mode):
dit = _JointDiT()
pipe = types.SimpleNamespace(transformer = dit)
knobs = {**ss.static_skip_settings({}), "mode": mode}
assert ss.install_static_step_skip(pipe, settings = knobs) == dcache.TC_STATIC
ss.reset_static_step_skip(pipe, 30)
outs = _run_joint(pipe, 30)
plan = ss.static_schedule(30)
assert dit.calls == sum(plan)
assert ss.static_skip_stats(pipe)["stats"]["skipped"] == 30 - sum(plan)
for i, (video, audio) in enumerate(outs):
assert type(outs[i]) is tuple and video.shape == (1, 6, 2) and audio.shape == (1, 3)
t = 1.0 - i / 30
if plan[i] or mode == "taylor1":
# Linear extrapolation in t is exact for these linear-in-t outputs.
assert torch.allclose(video, torch.full_like(video, t), atol = 1e-5)
assert torch.allclose(audio, torch.full_like(audio, 2 * t), atol = 1e-5)
else:
prev = max(j for j in range(i) if plan[j])
assert torch.allclose(video, torch.full_like(video, 1.0 - prev / 30))
def test_a_non_tensor_member_still_declines():
class _KV(_JointDiT):
def forward(self, **kw):
self.calls += 1
return torch.zeros(1, 2), {"kv": 1}
dit = _KV()
pipe = types.SimpleNamespace(transformer = dit)
ss.install_static_step_skip(pipe, settings = ss.static_skip_settings({}))
ss.reset_static_step_skip(pipe, 25)
for i in range(25):
dit.forward(timestep = torch.tensor([1.0 - i / 25]))
assert dit.calls == 25
def _probe_plan(entry):
"""The real plan function over a one-row table, whatever ids the loader passes (a tmp-path GGUF here)."""
def plan(
ids,
tier,
steps,
env = None,
):
saved = dict(dcache.AUTO_STATIC_SKIP)
dcache.AUTO_STATIC_SKIP.clear()
dcache.AUTO_STATIC_SKIP["probe/model"] = entry
try:
return dcache.auto_static_skip_plan(("probe/model",), tier, steps, env)
finally:
dcache.AUTO_STATIC_SKIP.clear()
dcache.AUTO_STATIC_SKIP.update(saved)
return plan
@pytest.mark.parametrize(
"speed, killed, want_static",
[
("default", False, False),
("max", False, True),
("eager", False, False),
("max", True, False),
],
)
def test_auto_load_installs_static_for_a_listed_model(
fake_runtime, tmp_path, monkeypatch, speed, killed, want_static
):
from core.inference import diffusion as dmod
monkeypatch.setattr(dmod, "auto_static_skip_plan", _probe_plan({"default": 3, "max": 3}))
monkeypatch.setattr(dmod, "default_generation_params", lambda *a, **k: (28, 3.5))
if killed:
monkeypatch.setenv(dcache.ENV_AUTO_STEP_SKIP, "0")
else:
monkeypatch.delenv(dcache.ENV_AUTO_STEP_SKIP, raising = False)
installs, fb = [], []
monkeypatch.setattr(
dmod,
"install_static_step_skip",
lambda pipe, settings = None, logger = None: installs.append(settings) or dcache.TC_STATIC,
)
monkeypatch.setattr(
dmod, "apply_step_cache", lambda pipe, mode = None, **k: fb.append(mode) or None
)
(tmp_path / "model.gguf").write_bytes(b"weights")
backend = dmod.DiffusionBackend()
status = _load_into(backend, tmp_path, speed_mode = speed, transformer_cache = None)
entry = status["resolved"]["transformer_cache"]
if want_static:
assert len(installs) == 1 and installs[0]["every"] == 3 and installs[0]["min_steps"] == 20
assert installs[0]["auto"] is True
assert status["transformer_cache"] == "static" and entry["value"] == "static"
assert entry["requested"] is None and "UNSLOTH_DIFFUSION_AUTO_STEP_SKIP" in entry["reason"]
assert fb == []
assert backend._state.cache_auto is False
else:
assert installs == []
assert status["transformer_cache"] in (None, dcache.TC_FBCACHE)
backend.unload()
def test_explicit_requests_ignore_the_table(fake_runtime, tmp_path, monkeypatch):
from core.inference import diffusion as dmod
monkeypatch.setattr(dmod, "auto_static_skip_plan", _probe_plan({"default": 3, "max": 3}))
monkeypatch.setattr(
dmod,
"install_static_step_skip",
lambda *a, **k: pytest.fail("explicit off installed static"),
)
(tmp_path / "model.gguf").write_bytes(b"weights")
backend = dmod.DiffusionBackend()
status = _load_into(backend, tmp_path, speed_mode = "default", transformer_cache = "off")
assert status["transformer_cache"] is None
backend.unload()
def test_auto_static_declined_falls_back_to_the_previous_auto(fake_runtime, tmp_path, monkeypatch):
from core.inference import diffusion as dmod
monkeypatch.setattr(dmod, "auto_static_skip_plan", _probe_plan({"default": 2, "max": 2}))
monkeypatch.setattr(dmod, "default_generation_params", lambda *a, **k: (28, 3.5))
monkeypatch.delenv(dcache.ENV_AUTO_STEP_SKIP, raising = False)
monkeypatch.setattr(dmod, "install_static_step_skip", lambda *a, **k: None)
modes = []
monkeypatch.setattr(
dmod, "apply_step_cache", lambda pipe, mode = None, **k: modes.append(mode) or None
)
(tmp_path / "model.gguf").write_bytes(b"weights")
backend = dmod.DiffusionBackend()
_load_into(backend, tmp_path, speed_mode = "max", transformer_cache = None)
assert modes == [dcache.TC_FBCACHE]
backend.unload()
@pytest.mark.parametrize("auto", [True, False])
def test_auto_skip_runs_on_txt2img_only_explicit_everywhere(
fake_runtime, tmp_path, monkeypatch, auto
):
from core.inference import diffusion as dmod
from .test_diffusion_backend import _loaded_backend, _tiny_png_b64
(tmp_path / "model.gguf").write_bytes(b"x")
backend = _loaded_backend(tmp_path)
pipe = backend._state.pipe
pipe.transformer = types.SimpleNamespace(forward = lambda *a, **k: None, __dict__ = {})
layer = types.SimpleNamespace(auto = auto)
monkeypatch.setattr(dmod, "static_skip_is_auto", lambda p: layer.auto)
armed = []
monkeypatch.setattr(
dmod,
"reset_static_step_skip",
lambda p, steps, **k: armed.append((steps, bool(k.get("compute_all")))) or True,
)
monkeypatch.setattr(dmod, "effective_request_strength", lambda *a, **k: None)
object.__setattr__(backend._state, "transformer_cache", dcache.TC_STATIC)
backend.generate(prompt = "a car", steps = 28, seed = 1)
assert armed[0] == (28, False)
armed.clear()
backend.generate(prompt = "a car", steps = 28, seed = 1, init_image = _tiny_png_b64(), strength = 1.0)
# img2img: an AUTO layer computes every step; an explicit one keeps its schedule.
assert armed[0] == (28, auto)
backend.unload()
def test_deferred_default_tier_never_auto_skips(fake_runtime, tmp_path, monkeypatch):
from core.inference import diffusion as dmod
from .test_diffusion_backend import DiffusionBackend
monkeypatch.setattr(dmod, "auto_static_skip_plan", _probe_plan({"default": 2, "max": 3}))
monkeypatch.setattr(dmod, "default_generation_params", lambda *a, **k: (28, 3.5))
monkeypatch.delenv(dcache.ENV_AUTO_STEP_SKIP, raising = False)
monkeypatch.setattr(dmod, "compile_eligible", lambda *a, **k: True)
monkeypatch.setattr(
dmod,
"apply_speed_optims",
lambda pipe, target, **k: {"compiled": k.get("speed_mode") == "default"},
)
monkeypatch.setattr(dmod.compile_cache, "begin", lambda **k: None)
installs = []
monkeypatch.setattr(
dmod,
"install_static_step_skip",
lambda pipe, settings = None, logger = None: installs.append(settings) or dcache.TC_STATIC,
)
monkeypatch.setattr(dmod, "reset_static_step_skip", lambda *a, **k: True)
(tmp_path / "model.safetensors").write_bytes(b"weights")
backend = DiffusionBackend()
status = _load_into(
backend, tmp_path, gguf_filename = "model.safetensors", family_override = "qwen-image"
)
assert status["speed_mode"] == "off" and status["transformer_cache"] is None
backend.generate(prompt = "one")
backend.generate(prompt = "two")
assert installs == [] and backend.status()["transformer_cache"] is None
backend.generate(prompt = "three")
st = backend.status()
assert st["speed_mode"] == "default"
assert installs == []
assert st["transformer_cache"] is None
assert st["resolved"]["transformer_cache"]["value"] != "static"
backend.unload()
def test_a_bypassed_render_reports_zero_skips_not_the_previous_render():
dit = _JointDiT()
pipe = types.SimpleNamespace(transformer = dit)
ss.install_static_step_skip(pipe, settings = ss.static_skip_settings({}))
ss.reset_static_step_skip(pipe, 30)
_run_joint(pipe, 30)
assert ss.static_skip_stats(pipe)["stats"]["skipped"] > 0
ss.reset_static_step_skip(pipe, 30, compute_all = True)
calls = dit.calls
_run_joint(pipe, 30)
described = ss.static_skip_stats(pipe)
assert dit.calls - calls == 30
assert described["stats"] == {"calls": 30, "computed": 30, "skipped": 0}
assert described["planned_skips"] == 0
class _H3DiT:
"""(video, audio) outputs linear in each stream's own timestep, read from the H3 row layout."""
def __init__(self):
self.calls = 0
def forward(
self,
hidden_states = None,
timestep = None,
timestep_indices = None,
token_tags = None,
**kw,
):
self.calls += 1
rows = timestep.index_select(0, timestep_indices)
video_t = rows[token_tags == 0].min()
audio_t = rows[token_tags == 2].min()
return torch.full((1, 4, 2), float(video_t)), torch.full((1, 3), float(audio_t))
def _shifted(sigma, shift):
return shift * sigma / (1 + (shift - 1) * sigma)
def test_h3_audio_extrapolates_on_its_own_schedule():
# MiniMax-H3 defaults: video shift 12, audio shift 3.
steps = 30
dit = _H3DiT()
pipe = types.SimpleNamespace(transformer = dit)
ss.install_static_step_skip(pipe, settings = {**ss.static_skip_settings({}), "mode": "taylor1"})
ss.reset_static_step_skip(pipe, steps)
tags = torch.tensor([0, 0, 0, 1, 2, 2, 2])
plan = ss.static_schedule(steps)
for i in range(steps):
sigma = 1.0 - i / steps
vt, at = _shifted(sigma, 12.0), _shifted(sigma, 3.0)
per_row = torch.tensor([1.0, vt, vt, vt, 1.0, at, at])
unique, inverse = torch.unique(per_row, sorted = True, return_inverse = True)
video, audio = pipe.transformer.forward(
hidden_states = None, timestep = unique, timestep_indices = inverse, token_tags = tags
)
if not plan[i]:
prev = [j for j in range(i) if plan[j]][-2:]
s0, s1 = (1.0 - j / steps for j in prev)
want_a = _shifted(s1, 3.0) + (_shifted(s1, 3.0) - _shifted(s0, 3.0)) * (
at - _shifted(s1, 3.0)
) / (_shifted(s1, 3.0) - _shifted(s0, 3.0))
assert torch.allclose(audio, torch.full_like(audio, want_a), atol = 1e-5), (
i,
float(audio[0, 0]),
at,
)
assert torch.allclose(video, torch.full_like(video, vt), atol = 1e-5)
assert dit.calls == sum(plan)
def test_a_failed_deferred_profile_takes_the_auto_skip_back_off(
fake_runtime, tmp_path, monkeypatch
):
from core.inference import diffusion as dmod
from .test_diffusion_backend import DiffusionBackend
monkeypatch.setattr(dmod, "auto_static_skip_plan", _probe_plan({"default": 2, "max": 3}))
monkeypatch.setattr(dmod, "default_generation_params", lambda *a, **k: (28, 3.5))
monkeypatch.delenv(dcache.ENV_AUTO_STEP_SKIP, raising = False)
monkeypatch.setattr(dmod, "compile_eligible", lambda *a, **k: True)
def boom(*a, **k):
raise RuntimeError("compile unavailable")
monkeypatch.setattr(dmod.compile_cache, "begin", boom)
monkeypatch.setattr(
dmod,
"install_static_step_skip",
lambda pipe, settings = None, logger = None: dcache.TC_STATIC,
)
removed = []
monkeypatch.setattr(dmod, "uninstall_static_step_skip", lambda pipe: removed.append(pipe))
(tmp_path / "model.safetensors").write_bytes(b"weights")
backend = DiffusionBackend()
_load_into(backend, tmp_path, gguf_filename = "model.safetensors", family_override = "qwen-image")
for p in ("one", "two", "three"):
backend.generate(prompt = p)
st = backend.status()
assert st["speed_mode"] == "off"
assert st["transformer_cache"] is None and removed == []
assert st["resolved"]["transformer_cache"]["value"] != "static"
backend.unload()
# Step counts the table rows were measured at; the auto skip never runs below them.
MEASURED_STEPS = {
"Qwen/Qwen-Image-2.1": 25,
"Qwen/Qwen-Image": 20,
"black-forest-labs/FLUX.1-Krea-dev": 28,
"black-forest-labs/FLUX.2-klein-base-4B": 50,
"Wan-AI/Wan2.2-TI2V-5B-Diffusers": 50,
"black-forest-labs/FLUX.1-dev": 28,
"hunyuanvideo-community/HunyuanImage-2.1-Diffusers": 50,
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v": 50,
"MiniMaxAI/MiniMax-H3": 30,
}
@pytest.mark.parametrize("repo", sorted(MEASURED_STEPS))
def test_auto_skip_never_runs_below_the_measured_step_count(repo):
plan = dcache.auto_static_skip_plan((repo,), "max", 50, env = {})
assert plan["min_steps"] == max(dcache.AUTO_STATIC_MIN_STEPS, MEASURED_STEPS[repo])
below = ss.static_schedule(
plan["min_steps"] - 1, every = plan["every"], min_steps = plan["min_steps"]
)
assert below == ()
assert not all(
ss.static_schedule(plan["min_steps"], every = plan["every"], min_steps = plan["min_steps"])
)
@pytest.mark.parametrize(
"requested, effective, want",
[
("off", "default", "off"),
("eager", "default", "eager"),
(None, "default", "default"),
("max", "max", "max"),
],
)
def test_an_explicit_lossless_tier_never_auto_skips(requested, effective, want):
tier = dcache.skip_tier(requested, effective)
assert tier == want
plan = dcache.auto_static_skip_plan(("Qwen/Qwen-Image",), tier, 20, env = {})
assert (plan is None) == (want != "max")
@pytest.mark.parametrize("raw, want", [("1", 3), ("abc", 3), ("", 3), ("4", 4)])
def test_only_a_valid_every_override_beats_the_measured_interval(raw, want):
out = ss.auto_static_settings({"every": 3, "min_steps": 20}, env = {ss.ENV_EVERY: raw})
assert out["every"] == want