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
"""Stock vs fast Qwen-Image-2.1 forward, bit for bit; skipped without Qwen-Image 2.1 in diffusers."""
from __future__ import annotations
import importlib
import types
import pytest
from core.inference import diffusion_qwenimage21 as q
torch = pytest.importorskip("torch")
qmod = pytest.importorskip("diffusers.models.transformers.transformer_qwenimage21")
@pytest.fixture(autouse = True)
def _stock_after(monkeypatch):
monkeypatch.delenv(q.FAST_STEP_ENV, raising = False)
q.uninstall()
yield
q.uninstall()
def _model():
torch.manual_seed(0)
m = qmod.QwenImage21Transformer2DModel(
num_layers = 2,
attention_head_dim = 16,
num_attention_heads = 2,
context_in_dim = 24,
in_channels = 8,
out_channels = 8,
axes_dims_rope = (4, 6, 6),
).eval()
with torch.no_grad():
for p in m.parameters():
p.normal_(0, 0.2)
return m
def _inputs(
batch = 1,
text = 9,
cond = None,
target = (4, 6),
pad = 0,
seed = 7,
):
g = torch.Generator().manual_seed(seed)
th, tw = target
shapes = []
latents = []
if cond is None:
vlm = torch.zeros(text, dtype = torch.bool)
else:
ch, cw = cond
vlm = torch.cat(
[
torch.zeros(text // 2, dtype = torch.bool),
torch.ones(ch * cw // 4, dtype = torch.bool),
torch.zeros(text - text // 2, dtype = torch.bool),
]
)
shapes.append((1, ch, cw))
latents.append(torch.randn(batch, ch * cw, 8, generator = g))
shapes.append((1, th, tw))
img_mask = torch.cat([vlm, torch.ones(th * tw // 4, dtype = torch.bool)])[None].repeat(batch, 1)
mask = None
if pad:
mask = torch.ones(batch, vlm.numel(), dtype = torch.long)
mask[-1, -pad:] = 0
return {
"encoder_hidden_states": torch.randn(batch, vlm.numel(), 24, generator = g),
"encoder_hidden_states_mask": mask,
"img_shapes": [shapes] * batch,
"img_mask": img_mask,
"cond": torch.cat(latents, 1) if latents else None,
"latents": torch.randn(batch, th * tw, 8, generator = g),
}
def _render(
m,
inp,
steps = 4,
cache = True,
):
outs = []
kv = qmod.QwenImage21KVCache(len(m.transformer_blocks)) if cache else None
lat = inp["latents"]
with torch.inference_mode():
for i in range(steps):
hs = lat if inp["cond"] is None else torch.cat([inp["cond"], lat], 1)
out = m(
hidden_states = hs,
timestep = torch.full((hs.shape[0],), 1.0 - i / steps),
encoder_hidden_states = inp["encoder_hidden_states"],
encoder_hidden_states_mask = inp["encoder_hidden_states_mask"],
img_shapes = inp["img_shapes"],
img_mask = inp["img_mask"],
kv_cache = kv,
kv_cache_mode = None if not cache else ("extract" if i == 0 else "cached"),
return_dict = False,
)[0]
outs.append(out.clone())
lat = lat - 0.1 * out[:, -lat.shape[1] :]
return outs
CASES = [
{},
{"batch": 2, "pad": 3},
{"cond": (4, 4)},
{"batch": 2, "cond": (4, 8), "target": (6, 4), "pad": 2},
]
@pytest.mark.parametrize("case", CASES)
@pytest.mark.parametrize("cache", [True, False])
def test_fast_step_is_bit_identical_to_the_stock_forward(case, cache):
m = _model()
inp = _inputs(**case)
ref = _render(m, inp, cache = cache)
assert q.install()
assert getattr(type(m).forward, "__unsloth_q21_fast_step__", False)
first = _render(m, inp, cache = cache)
again = _render(m, _inputs(**case), cache = cache)
for a, b, c in zip(ref, first, again):
assert torch.equal(a, b)
assert torch.equal(a, c)
def test_layout_is_built_once_per_render_and_found_by_content():
m = _model()
assert q.install()
calls = {"n": 0}
real = q._build_layout
def counting(*a, **k):
calls["n"] += 1
return real(*a, **k)
q._build_layout = counting
try:
inp = _inputs()
_render(m, inp, steps = 5)
assert calls["n"] == 1
_render(m, _inputs(), steps = 5)
assert calls["n"] == 1
_render(m, _inputs(text = 11), steps = 3)
assert calls["n"] == 2
finally:
q._build_layout = real
def test_a_different_layout_of_the_same_length_is_not_reused():
m = _model()
a = _inputs(text = 8, cond = (4, 4))
b = _inputs(text = 8, cond = (4, 4))
vlm = b["img_mask"][0, :12].clone()
b["img_mask"][:, :12] = vlm.roll(3)
ref_b = _render(m, b)
assert q.install()
_render(m, a)
got_b = _render(m, b)
for x, y in zip(ref_b, got_b):
assert torch.equal(x, y)
def test_grad_and_kill_switch_take_the_stock_forward(monkeypatch):
m = _model()
assert q.install()
inp = _inputs()
seen = []
real = q._layout_for
monkeypatch.setattr(q, "_layout_for", lambda *a, **k: seen.append(1) or real(*a, **k))
kv = qmod.QwenImage21KVCache(len(m.transformer_blocks))
with torch.enable_grad():
m(
hidden_states = inp["latents"],
timestep = torch.ones(1),
encoder_hidden_states = inp["encoder_hidden_states"],
img_shapes = inp["img_shapes"],
img_mask = inp["img_mask"],
kv_cache = kv,
kv_cache_mode = "extract",
return_dict = False,
)
assert seen == []
monkeypatch.setenv(q.FAST_STEP_ENV, "0")
_render(m, inp, steps = 2)
assert seen == []
monkeypatch.delenv(q.FAST_STEP_ENV)
_render(m, inp, steps = 2)
assert seen
def test_stock_errors_are_kept():
m = _model()
assert q.install()
inp = _inputs()
with pytest.raises(ValueError, match = "kv_cache_mode"):
with torch.inference_mode():
m(
hidden_states = inp["latents"],
timestep = torch.ones(1),
encoder_hidden_states = inp["encoder_hidden_states"],
img_shapes = inp["img_shapes"],
img_mask = inp["img_mask"],
kv_cache_mode = "cached",
)
def test_install_is_idempotent_and_uninstall_restores_the_stock_forward():
cls = qmod.QwenImage21Transformer2DModel
stock = vars(cls)["forward"]
assert q.install() and q.install()
patched = vars(cls)["forward"]
assert patched is not stock
assert patched.__unsloth_stock_forward__ is stock
import inspect
assert inspect.signature(patched) == inspect.signature(stock)
q.uninstall()
assert vars(cls)["forward"] is stock
q.uninstall()
assert vars(cls)["forward"] is stock
def test_installed_diffusers_matches_the_fingerprints():
"""On failure: re-check the fast forward against the new stock function, then add its digest."""
assert q.why_unsupported(qmod) is None
def test_a_drifted_function_keeps_the_stock_forward(monkeypatch):
fake = types.SimpleNamespace(**vars(qmod))
def _qwenimage21_prefix_segments(image_ids, prefix_len):
return []
fake._qwenimage21_prefix_segments = _qwenimage21_prefix_segments
assert "prefix_segments differs" in q.why_unsupported(fake)
real_import = importlib.import_module
monkeypatch.setattr(
importlib,
"import_module",
lambda name, *a: fake if name == q._MODULE else real_import(name, *a),
)
cls = qmod.QwenImage21Transformer2DModel
stock = vars(cls)["forward"]
assert q.install() is False
assert vars(cls)["forward"] is stock
def test_kill_switch_blocks_install(monkeypatch):
monkeypatch.setenv(q.FAST_STEP_ENV, "off")
assert q.install() is False
assert not getattr(
vars(qmod.QwenImage21Transformer2DModel)["forward"], "__unsloth_q21_fast_step__", False
)
@pytest.mark.skipif(not torch.cuda.is_available(), reason = "needs CUDA for the sync check")
def test_cached_steps_do_not_sync_the_host():
m = _model().to("cuda")
inp = {
k: (v.to("cuda") if torch.is_tensor(v) else v) for k, v in _inputs(batch = 2, pad = 2).items()
}
assert q.install()
kv = qmod.QwenImage21KVCache(len(m.transformer_blocks))
with torch.inference_mode():
for i in range(4):
if i >= 2:
torch.cuda.set_sync_debug_mode("error")
try:
m(
hidden_states = inp["latents"],
timestep = torch.full((2,), 0.5, device = "cuda"),
encoder_hidden_states = inp["encoder_hidden_states"],
encoder_hidden_states_mask = inp["encoder_hidden_states_mask"],
img_shapes = inp["img_shapes"],
img_mask = inp["img_mask"],
kv_cache = kv,
kv_cache_mode = "extract" if i == 0 else "cached",
return_dict = False,
)
finally:
torch.cuda.set_sync_debug_mode("default")
def test_digest_ignores_docstrings_comments_and_blank_lines_only():
import linecache
src = "def f(x):\n '''doc'''\n # note\n y = x + 1 # why\n\n return y\n"
other = "def f(x):\n y = x + 1\n return y\n"
changed = "def f(x):\n y = x + 2\n return y\n"
digests = []
for i, text in enumerate((src, other, changed)):
name = f"<q21-digest-{i}>"
linecache.cache[name] = (len(text), None, text.splitlines(True), name)
scope: dict = {}
exec(compile(text, name, "exec"), scope)
digests.append(q._digest(scope["f"]))
assert digests[0] == digests[1] != digests[2]
def test_install_for_pipe_only_touches_qwen_image_21_and_never_raises(monkeypatch):
calls = []
monkeypatch.setattr(q, "install", lambda logger = None: calls.append(1) or True)
assert q.install_for_pipe(types.SimpleNamespace(transformer = object())) is False
assert q.install_for_pipe(types.SimpleNamespace()) is False
assert calls == []
pipe = types.SimpleNamespace(
transformer = qmod.QwenImage21Transformer2DModel.__new__(qmod.QwenImage21Transformer2DModel)
)
assert q.install_for_pipe(pipe) is True and calls == [1]
monkeypatch.setattr(
q, "install", lambda logger = None: (_ for _ in ()).throw(RuntimeError("boom"))
)
assert q.install_for_pipe(pipe) is False
def test_a_mask_rewritten_in_place_between_renders_gets_its_new_layout():
m = _model()
inp = _inputs(text = 8, cond = (4, 4), pad = 2)
assert q.install()
_render(m, inp)
inp["img_mask"][:, :12] = inp["img_mask"][:, :12].roll(3, dims = 1).clone()
got = _render(m, inp)
q.uninstall()
ref = _render(m, inp)
for a, b in zip(ref, got):
assert torch.equal(a, b)
def test_a_cached_layout_does_not_alias_the_callers_mask():
m = _model()
inp = _inputs(text = 8, cond = (4, 4), pad = 2)
assert q.install()
_render(m, dict(inp, encoder_hidden_states_mask = None))
original = inp["img_mask"].clone()
inp["img_mask"][:, :12] = inp["img_mask"][:, :12].roll(3, dims = 1).clone()
fresh = dict(inp, img_mask = original)
got = _render(m, fresh)
q.uninstall()
ref = _render(m, fresh)
for a, b in zip(ref, got):
assert torch.equal(a, b)
@pytest.mark.parametrize("prefill, decode", [(False, True), (True, False), (True, True)])
def test_an_autocast_change_between_steps_matches_the_stock_forward(prefill, decode):
m = _model()
inp = _inputs(pad = 2)
def render():
outs = []
kv = qmod.QwenImage21KVCache(len(m.transformer_blocks))
lat = inp["latents"]
with torch.inference_mode():
for i in range(3):
with torch.autocast(
"cpu", dtype = torch.bfloat16, enabled = prefill if i == 0 else decode
):
out = m(
hidden_states = lat,
timestep = torch.full((1,), 1.0 - i / 3),
encoder_hidden_states = inp["encoder_hidden_states"],
encoder_hidden_states_mask = inp["encoder_hidden_states_mask"],
img_shapes = inp["img_shapes"],
img_mask = inp["img_mask"],
kv_cache = kv,
kv_cache_mode = "extract" if i == 0 else "cached",
return_dict = False,
)[0]
outs.append(out.float().clone())
lat = lat - 0.1 * out.float()[:, -lat.shape[1] :]
return outs
ref = render()
assert q.install()
got = render()
for a, b in zip(ref, got):
assert torch.equal(a, b)
def test_an_unknown_build_token_metadata_keeps_the_stock_forward():
"""Both known sources (0.41.0, main d42ebf9c) are accepted; any other edit still falls back."""
assert q._FINGERPRINTS["build_token_metadata"] == frozenset(
{"51818c1674e0d406", "9282e4c4803957f8"}
)
fake = types.SimpleNamespace(**vars(qmod))
class QwenImage21Transformer2DModel(qmod.QwenImage21Transformer2DModel):
forward = qmod.QwenImage21Transformer2DModel.forward
def build_token_metadata(self, image_pad_mask, img_shapes):
return None, None
fake.QwenImage21Transformer2DModel = QwenImage21Transformer2DModel
assert "build_token_metadata differs" in q.why_unsupported(fake)