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: default Qwen-Image-2.1 int8 to the hosted ConvRot file, with shared rotations (#12874)

Daniel Hane7b2e9627fbb
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 9be35e8001c..172258b3dc1 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -1998,6 +1998,11 @@ def _uninstall_fused_dit_patches() -> None:
uninstall_flux2_rope()
except Exception: # noqa: BLE001 - teardown is best effort
pass
+ try:
+ from .diffusion_qwenimage21_fused import uninstall as uninstall_q21_fused
+ uninstall_q21_fused()
+ except Exception: # noqa: BLE001 - teardown is best effort
+ pass
try:
from .diffusion_rocm_fused import uninstall as uninstall_rocm_fused
uninstall_rocm_fused()
diff --git a/studio/backend/core/inference/diffusion_int8_fused.py b/studio/backend/core/inference/diffusion_int8_fused.py
index 05379d9b441..aa18f95d337 100644
--- a/studio/backend/core/inference/diffusion_int8_fused.py
+++ b/studio/backend/core/inference/diffusion_int8_fused.py
@@ -1222,7 +1222,11 @@ def _is_zimage_ff(module: Any) -> bool:
def _swiglu_layout_allowed(module: Any) -> bool:
- return _SWIGLU_ALL_LAYOUTS or _is_zimage_ff(module)
+ if _SWIGLU_ALL_LAYOUTS or _is_zimage_ff(module):
+ return True
+ # rotated down projection: the SwiGLU kernel never runs
+ from .diffusion_qwenimage21_fused import rotated_ff
+ return rotated_ff(module)
def _get(module: Any, dotted: str) -> Any:
@@ -1252,20 +1256,31 @@ def int8_linear(module: Any, x: Any) -> Any:
on B200). 0.18 skips it for symmetric activations, as this does; the values are the same (``y - 0 == y``).
Anything else (LoRA wrappers, legacy tensors, small M, CPU, a Linear running diffusion_int8_gemm's fused GEMM) is
``module(x)``."""
- import torch
from torch import nn
from .diffusion_convrot import is_rotated_linear
- rotated = is_rotated_linear(module)
# an instance-level forward is an offload hook (accelerate / diffusers) or another wrapper: only it may run
if (
_LINEAR_OFF
- or not (type(module) is nn.Linear or rotated)
+ or not (type(module) is nn.Linear or is_rotated_linear(module))
or _I8_GEMM_MARK in module.__dict__
or "forward" in module.__dict__
):
return module(x)
+ return int8_linear_core(module, x)
+
+
+def int8_linear_core(module: Any, x: Any) -> Any:
+ """``int8_linear`` minus its wrapper checks, for a forward installed on ``module``: fallbacks run the class
+ forward, never ``module(x)`` (would recurse)."""
+ import torch
+
+ from .diffusion_convrot import is_rotated_linear
+
+ rotated = is_rotated_linear(module)
+ if _LINEAR_OFF:
+ return _stock_call(module, x)
weight = module.weight
lead = x.shape[:-1]
x2d = x.reshape(-1, x.shape[-1])
@@ -1277,7 +1292,7 @@ def int8_linear(module: Any, x: Any) -> Any:
or getattr(weight, "act_pre_scale", None) is not None
or weight.device != x.device
):
- return module(x)
+ return _stock_call(module, x)
if rotated:
x2d = _rotate(x2d, module.convrot_groupsize)
xq, xs = _fast_act_quant(x2d, weight)
@@ -1287,6 +1302,12 @@ def int8_linear(module: Any, x: Any) -> Any:
return y.reshape(*lead, y.shape[-1])
+def _stock_call(module: Any, x: Any) -> Any:
+ if "forward" in module.__dict__:
+ return type(module).forward(module, x)
+ return module(x)
+
+
def _rotate(x2d: Any, group: int) -> Any:
"""``ConvRotLinear.forward``'s input rotation, same ops and dtype."""
from .diffusion_convrot import build_convrot_hadamard, rotate_convrot_activation
diff --git a/studio/backend/core/inference/diffusion_qwenimage21_fused.py b/studio/backend/core/inference/diffusion_qwenimage21_fused.py
new file mode 100644
index 00000000000..45d457ad80e
--- /dev/null
+++ b/studio/backend/core/inference/diffusion_qwenimage21_fused.py
@@ -0,0 +1,269 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Qwen-Image-2.1 ConvRot int8: one rotation + one act quant per shared input (QKV, SwiGLU gate/value) in the compile.
+
+Rotation is on the shared input axis and int8 scales are per row, so fused outputs equal the separate rotated ones bit
+for bit. Only where ``diffusion_int8_gemm`` leaves rotated Linears on the stock path (e.g. sm90, sm100), resident only.
+Kill switch: ``UNSLOTH_DIFFUSION_Q21_CONVROT_FUSED=0``.
+"""
+
+from __future__ import annotations
+
+import functools
+import os
+import threading
+import types
+from typing import Any, Optional
+
+Q21_CONVROT_FUSED_ENV = "UNSLOTH_DIFFUSION_Q21_CONVROT_FUSED"
+_PREPARE = "_qwenimage21_prepare_qkv"
+_QKV_ATTR = "_unsloth_q21_fused_qkv"
+_OUT_MARK = "_unsloth_q21_out_prev"
+_NO_PREV = object()
+
+_LOCK = threading.Lock()
+_STATE: dict = {}
+
+
+def q21_convrot_fused_disabled() -> bool:
+ return (os.environ.get(Q21_CONVROT_FUSED_ENV) or "").strip().lower() in (
+ "0",
+ "off",
+ "false",
+ "no",
+ )
+
+
+def arch_ok(device: Any = None) -> bool:
+ """True where ``diffusion_int8_gemm`` has neither its fused GEMM nor ``rotq_i8`` for this arch."""
+ try:
+ import torch
+
+ if not torch.cuda.is_available() or getattr(torch.version, "hip", None):
+ return False
+ dev = torch.device(device) if device is not None else None
+ if dev is None or dev.type != "cuda":
+ index = torch.cuda.current_device()
+ else:
+ index = dev.index if dev.index is not None else torch.cuda.current_device()
+ from .diffusion_int8_gemm import _gates, int8_gemm_mode
+
+ if int8_gemm_mode() == "off":
+ return True
+ gemm, rotq = _gates(torch.cuda.get_device_capability(index))
+ return not (gemm or rotq)
+ except Exception: # noqa: BLE001
+ return False
+
+
+def _rotated_group(linears: list) -> int:
+ """The shared ConvRot group of ``linears``, else 0 (plain or mixed)."""
+ from .diffusion_zimage_fused import _rotation_group
+
+ group = _rotation_group(linears)
+ return group if isinstance(group, int) and group > 0 else 0
+
+
+def _plain(lin: Any) -> bool:
+ from .diffusion_int8_fused import _I8_GEMM_MARK, _plain_int8_weight
+ d = getattr(lin, "__dict__", {})
+ return "forward" not in d and _I8_GEMM_MARK not in d and _plain_int8_weight(lin.weight)
+
+
+def rotated_ff(module: Any) -> bool:
+ """A Qwen-Image-2.1 SwiGLU with rotated gate/value and down projections, on a covered arch."""
+ if type(module).__name__ != "QwenImage21SwiGLUFeedForward" or q21_convrot_fused_disabled():
+ return False
+ try:
+ parts = [module.gate_layer, module.proj]
+ if not _rotated_group(parts) or not _rotated_group([module.out]):
+ return False
+ return arch_ok(module.gate_layer.weight.device)
+ except Exception: # noqa: BLE001
+ return False
+
+
+def _qkv_intact(attn: Any) -> Any:
+ rec = attn.__dict__.get(_QKV_ATTR)
+ if rec is None:
+ return None
+ lin, q, k, v = rec
+ if attn.to_q is not q or attn.to_k is not k or attn.to_v is not v:
+ return None
+ return lin
+
+
+def _make_prepare(stock: Any, mod: Any) -> Any:
+ import torch
+
+ from .diffusion_int8_fused import int8_linear
+
+ def _qwenimage21_prepare_qkv(
+ attn, hidden_states, rotary_emb, layer_cache, kv_cache_mode, cache_write_slice
+ ):
+ fused = _qkv_intact(attn) if torch.compiler.is_compiling() else None
+ if fused is None:
+ return stock(
+ attn, hidden_states, rotary_emb, layer_cache, kv_cache_mode, cache_write_slice
+ )
+ # stock body below the projections, op for op (fingerprinted at install)
+ query, key, value = int8_linear(fused, hidden_states).chunk(3, dim = -1)
+
+ query = query.unflatten(-1, (attn.heads, -1))
+ key = key.unflatten(-1, (attn.heads, -1))
+ value = value.unflatten(-1, (attn.heads, -1))
+
+ query = attn.norm_q(query).to(value.dtype)
+ key = attn.norm_k(key).to(value.dtype)
+
+ if rotary_emb is not None:
+ # read per call: diffusion_qwenimage21_rope may have replaced it
+ query = mod.apply_rotary_emb_qwen(query, rotary_emb, use_real = False)
+ key = mod.apply_rotary_emb_qwen(key, rotary_emb, use_real = False)
+
+ if layer_cache is not None:
+ if kv_cache_mode == "extract" and cache_write_slice is not None:
+ layer_cache.store(
+ key[:, cache_write_slice].clone(),
+ value[:, cache_write_slice].clone(),
+ )
+ elif kv_cache_mode == "cached":
+ cached_k, cached_v = layer_cache.get()
+ key = torch.cat([cached_k, key], dim = 1)
+ value = torch.cat([cached_v, value], dim = 1)
+
+ seq_len_q = query.shape[1]
+ return query, key, value, seq_len_q
+
+ functools.update_wrapper(
+ _qwenimage21_prepare_qkv, stock, assigned = ("__name__", "__doc__"), updated = ()
+ )
+ _qwenimage21_prepare_qkv.__unsloth_q21_fused__ = True
+ return _qwenimage21_prepare_qkv
+
+
+def _out_forward(self: Any, x: Any) -> Any:
+ """``to_out[0]`` under compile: own rotation + the probed act quant kernel."""
+ import torch
+
+ if not torch.compiler.is_compiling():
+ return type(self).forward(self, x)
+ from .diffusion_int8_fused import int8_linear_core
+
+ return int8_linear_core(self, x)
+
+
+def _patch_prepare(logger: Any = None) -> bool:
+ try:
+ from diffusers.models.transformers import transformer_qwenimage21 as mod
+ except Exception: # noqa: BLE001 - diffusers without Qwen-Image 2.1
+ return False
+ with _LOCK:
+ current = getattr(mod, _PREPARE, None)
+ if getattr(current, "__unsloth_q21_fused__", False):
+ return True
+ from .diffusion_qwenimage21_rope import _FINGERPRINTS, _digest
+
+ digest = _digest(current)
+ if digest not in _FINGERPRINTS[_PREPARE]:
+ if logger is not None:
+ logger.info(
+ "diffusion.q21_convrot_fused: stock QKV kept: %s differs (%s)", _PREPARE, digest
+ )
+ return False
+ _STATE["stock"] = (mod, current)
+ setattr(mod, _PREPARE, _make_prepare(current, mod))
+ return True
+
+
+def install(
+ transformer: Any,
+ logger: Any = None,
+ offload_active: bool = False,
+) -> dict:
+ """Before the first compile; deferred to the first forward when the weights are not on the GPU yet."""
+ result = {"fused_qkv": 0, "out": 0}
+ if q21_convrot_fused_disabled():
+ uninstall(transformer)
+ return result
+ if offload_active or type(transformer).__name__ != "QwenImage21Transformer2DModel":
+ return result
+ from .diffusion_int8_fused import resident_cuda_device, run_on_first_call
+
+ if resident_cuda_device(transformer) is not None:
+ return install_modules(transformer, logger)
+ run_on_first_call(transformer, "q21_convrot_fused", lambda t: install_modules(t, logger))
+ return {"fused_qkv": None, "out": None}
+
+
+def install_modules(root: Any, logger: Any = None) -> dict:
+ result = {"fused_qkv": 0, "out": 0}
+ if q21_convrot_fused_disabled():
+ return result
+ from .diffusion_int8_fused import resident_cuda_device
+
+ dev = resident_cuda_device(root)
+ if dev is None or not arch_ok(dev):
+ return result
+ from .diffusion_zimage_fused import _fuse_linears, _share_storage
+
+ todo = []
+ for _name, module in root.named_modules():
+ if type(module).__name__ != "QwenImage21Attention":
+ continue
+ parts = [getattr(module, n, None) for n in ("to_q", "to_k", "to_v")]
+ if any(p is None for p in parts) or not _rotated_group(parts):
+ continue
+ todo.append((module, parts))
+ if not todo or not _patch_prepare(logger):
+ return result
+ with _LOCK:
+ for module, parts in todo:
+ if _QKV_ATTR not in module.__dict__ and all(_plain(p) for p in parts):
+ fused = _fuse_linears(parts)
+ if fused is not None and _share_storage(fused, parts):
+ module.__dict__[_QKV_ATTR] = (fused, *parts)
+ if _QKV_ATTR in module.__dict__:
+ result["fused_qkv"] += 1
+ out = module.to_out[0]
+ if _OUT_MARK in out.__dict__:
+ result["out"] += 1
+ elif _rotated_group([out]) and _plain(out):
+ out.__dict__[_OUT_MARK] = True
+ out.forward = types.MethodType(_out_forward, out)
+ result["out"] += 1
+ if logger is not None:
+ logger.info(
+ "diffusion.q21_convrot_fused: one ConvRot rotation + act quant for QKV on %d attention module(s), "
+ "probed act quant on %d output projection(s)",
+ result["fused_qkv"],
+ result["out"],
+ )
+ return result
+
+
+def uninstall(transformer: Any = None) -> None:
+ """Restore the stock QKV helper; drop the fused Linears and to_out forwards."""
+ if transformer is not None:
+ from .diffusion_int8_fused import cancel_first_call
+ cancel_first_call(transformer, "q21_convrot_fused")
+ with _LOCK:
+ stock = _STATE.pop("stock", None)
+ if stock is not None:
+ mod, fn = stock
+ if getattr(getattr(mod, _PREPARE, None), "__unsloth_q21_fused__", False):
+ setattr(mod, _PREPARE, fn)
+ if transformer is not None:
+ for module in transformer.modules():
+ module.__dict__.pop(_QKV_ATTR, None)
+ if module.__dict__.pop(_OUT_MARK, None) is not None:
+ fwd = module.__dict__.get("forward")
+ if getattr(fwd, "__func__", None) is _out_forward:
+ module.__dict__.pop("forward", None)
+
+
+def is_installed(module: Any) -> bool:
+ return _QKV_ATTR in getattr(module, "__dict__", {}) or _OUT_MARK in getattr(
+ module, "__dict__", {}
+ )
diff --git a/studio/backend/core/inference/diffusion_speed.py b/studio/backend/core/inference/diffusion_speed.py
index 1f0e25fa407..31795fe672e 100644
--- a/studio/backend/core/inference/diffusion_speed.py
+++ b/studio/backend/core/inference/diffusion_speed.py
@@ -1152,6 +1152,19 @@ def _compile_repeated_blocks(
install_zimage_fused(transformer, logger, offload_active = offload_active)
except Exception as exc: # noqa: BLE001 - optimisation only
_warn(logger, "z-image fused attention", exc)
+ if type(transformer).__name__ == "QwenImage21Transformer2DModel":
+ # after the int8 GEMM swap, whose leftovers it reads
+ try:
+ from .diffusion_qwenimage21_fused import install as install_q21_fused
+ install_q21_fused(
+ transformer,
+ logger,
+ offload_active = offload_active
+ if denoiser_offloaded is None
+ else bool(denoiser_offloaded),
+ )
+ except Exception as exc: # noqa: BLE001 - optimisation only
+ _warn(logger, "qwen-image-2.1 convrot sharing", exc)
try:
transformer.compile_repeated_blocks(**dit_kwargs)
engaged = True
diff --git a/studio/backend/core/inference/diffusion_transformer_quant.py b/studio/backend/core/inference/diffusion_transformer_quant.py
index 394371eda4c..dc65f949271 100644
--- a/studio/backend/core/inference/diffusion_transformer_quant.py
+++ b/studio/backend/core/inference/diffusion_transformer_quant.py
@@ -250,7 +250,7 @@ _INT8_FAMILY_CONVROT_REPO: dict[str, str] = {
}
# Families whose int8 runs ConvRot unless the env turns it off; the rest stay opt-in (``=1``).
-_INT8_FAMILY_CONVROT_DEFAULT_ON: frozenset[str] = frozenset({"z-image"})
+_INT8_FAMILY_CONVROT_DEFAULT_ON: frozenset[str] = frozenset({"qwen-image-2.1", "z-image"})
INT8_CONVROT_ENV = "UNSLOTH_DIFFUSION_INT8_CONVROT"
diff --git a/studio/backend/tests/test_diffusion_int8_runtime_convrot.py b/studio/backend/tests/test_diffusion_int8_runtime_convrot.py
index 84afa1c224d..0fcb4f3cbb5 100644
--- a/studio/backend/tests/test_diffusion_int8_runtime_convrot.py
+++ b/studio/backend/tests/test_diffusion_int8_runtime_convrot.py
@@ -130,8 +130,8 @@ def test_int8_artifact_names_the_rotated_build_first_and_keeps_the_plain_one():
)
-def test_without_the_opt_in_int8_is_plain_everywhere(monkeypatch):
- monkeypatch.delenv(tq.INT8_CONVROT_ENV)
+def test_with_the_kill_switch_int8_is_plain_everywhere(monkeypatch):
+ monkeypatch.setenv(tq.INT8_CONVROT_ENV, "0")
from core.inference.diffusion_families import detect_family
from core.inference.diffusion_prequant import resolve_prequant_source
@@ -151,8 +151,8 @@ def test_without_the_opt_in_int8_is_plain_everywhere(monkeypatch):
assert not tq.int8_convrot_enabled()
-def test_quantize_transformer_without_the_opt_in_rotates_nothing(monkeypatch):
- monkeypatch.delenv(tq.INT8_CONVROT_ENV)
+def test_quantize_transformer_with_the_kill_switch_rotates_nothing(monkeypatch):
+ monkeypatch.setenv(tq.INT8_CONVROT_ENV, "0")
seen = []
_stub_torchao(monkeypatch, seen)
monkeypatch.setattr(
@@ -442,11 +442,12 @@ def test_zimage_convrot_is_default_on_and_the_env_is_its_kill_switch(monkeypatch
monkeypatch.delenv(tq.INT8_CONVROT_ENV)
assert tq.int8_convrot_enabled("z-image") and tq.int8_convrot_enabled(" Z-Image ")
# every other family keeps the opt-in it had
- for family in (None, "qwen-image-2.1", "qwen-image", "flux.1", "minimax-h3"):
+ for family in (None, "qwen-image", "flux.1", "minimax-h3"):
assert not tq.int8_convrot_enabled(family)
for off in ("0", "off", "false", "no", " OFF "):
monkeypatch.setenv(tq.INT8_CONVROT_ENV, off)
assert not tq.int8_convrot_enabled("z-image")
+ assert not tq.int8_convrot_enabled("qwen-image-2.1")
monkeypatch.setenv(tq.INT8_CONVROT_ENV, "1")
assert tq.int8_convrot_enabled("qwen-image-2.1") and tq.int8_convrot_enabled("z-image")
@@ -521,3 +522,112 @@ def test_zimage_rotated_artifact_is_only_named_in_its_own_repo(monkeypatch):
)
names = candidate_filenames_of(resolve_prequant_source(fam, "int8"))
assert "Z-Image-Turbo-INT8-ConvRot.safetensors" not in names
+
+
+def test_qwen_image_21_convrot_is_default_on_and_the_env_is_its_kill_switch(monkeypatch):
+ monkeypatch.delenv(tq.INT8_CONVROT_ENV)
+ assert tq.int8_convrot_enabled("qwen-image-2.1") and tq.int8_convrot_enabled(" Qwen-Image-2.1 ")
+ for off in ("0", "off", "false", "no"):
+ monkeypatch.setenv(tq.INT8_CONVROT_ENV, off)
+ assert not tq.int8_convrot_enabled("qwen-image-2.1")
+
+
[email protected]("env, rotated_first", [(None, True), ("0", False), ("1", True)])
+def test_qwen_image_21_int8_resolves_the_rotated_artifact_first_unless_killed(
+ monkeypatch, env, rotated_first
+):
+ from core.inference.diffusion_families import detect_family
+ from core.inference.diffusion_prequant import (
+ candidate_filenames_of,
+ comfy_prequant_filename,
+ is_comfy_prequant_filename,
+ resolve_prequant_source,
+ )
+
+ if env is None:
+ monkeypatch.delenv(tq.INT8_CONVROT_ENV)
+ else:
+ monkeypatch.setenv(tq.INT8_CONVROT_ENV, env)
+ for repo in ("Qwen/Qwen-Image-2.1", "unsloth/Qwen-Image-2.1"):
+ fam = detect_family(repo)
+ assert fam is not None and fam.name == "qwen-image-2.1"
+ src = resolve_prequant_source(fam, "int8")
+ # -ComfyUI twins ride ahead of each artifact; compare Studio's own names
+ everything = candidate_filenames_of(src)
+ names = tuple(n for n in everything if not is_comfy_prequant_filename(n))
+ assert everything[0] == comfy_prequant_filename(names[0])
+ assert src.location == "unsloth/Qwen-Image-2.1-FP8"
+ assert "Qwen-Image-2.1-INT8.safetensors" in names
+ assert (names[0] == "Qwen-Image-2.1-INT8-ConvRot.safetensors") is rotated_first
+ assert ("Qwen-Image-2.1-INT8-ConvRot.safetensors" in names) is rotated_first
+ assert "Qwen-Image-2.1-INT8-ConvRot.safetensors" not in candidate_filenames_of(
+ resolve_prequant_source(fam, "fp8")
+ )
+
+
+def test_qwen_image_21_runtime_int8_rotates_by_default(monkeypatch):
+ monkeypatch.delenv(tq.INT8_CONVROT_ENV)
+ seen = []
+ _stub_torchao(monkeypatch, seen)
+ monkeypatch.setattr(
+ tq, "select_transformer_quant_scheme", lambda target, mode, family = None, **_: tq.TQ_INT8
+ )
+ pipe = types.SimpleNamespace(transformer = _Tiny())
+ assert (
+ tq.quantize_transformer(pipe, object(), mode = "int8", family = "qwen-image-2.1") == tq.TQ_INT8
+ )
+ assert len(seen) == 1 and set(seen[0]) == _ROTATED
+
+
+def test_qwen_image_21_offline_default_still_loads_the_cached_plain_artifact(monkeypatch, tmp_path):
+ from huggingface_hub.errors import LocalEntryNotFoundError
+
+ from core.inference import diffusion_prequant as pq
+ from core.inference.diffusion_families import detect_family
+
+ monkeypatch.delenv(tq.INT8_CONVROT_ENV)
+ plain = tmp_path / "Qwen-Image-2.1-INT8.safetensors"
+ plain.write_bytes(b"weights")
+ monkeypatch.setattr(pq, "restricted_prequant_load_supported", lambda *a, **k: True)
+ monkeypatch.setattr(
+ "huggingface_hub.try_to_load_from_cache",
+ lambda repo_id, filename, cache_dir = None, **k: str(tmp_path / filename)
+ if (tmp_path / filename).is_file()
+ else None,
+ )
+ asked = []
+
+ def _dl(
+ repo_id,
+ filename,
+ token = None,
+ cache_dir = None,
+ local_files_only = False,
+ ):
+ asked.append(filename)
+ raise LocalEntryNotFoundError("connection error")
+
+ monkeypatch.setattr("huggingface_hub.hf_hub_download", _dl)
+ source = pq.resolve_prequant_source(detect_family("Qwen/Qwen-Image-2.1"), "int8")
+ assert pq._resolve_checkpoint_path(source, None, None) == str(plain)
+ assert asked == ["Qwen-Image-2.1-INT8-ConvRot-ComfyUI.safetensors"]
+
+
+def test_qwen_image_21_rotated_set_is_exactly_the_int8_quantized_set(monkeypatch):
+ # an int8-quantized but unrotated Linear would be a silent accuracy hole
+ monkeypatch.delenv(tq.INT8_CONVROT_ENV)
+ diffusers = pytest.importorskip("diffusers")
+ cls = getattr(diffusers, "QwenImage21Transformer2DModel", None)
+ if cls is None:
+ pytest.skip(
+ reason = "installed diffusers has no QwenImage21Transformer2DModel to build the skeleton from"
+ )
+ from accelerate import init_empty_weights
+
+ with init_empty_weights():
+ model = cls()
+ filt = _filter("qwen-image-2.1")
+ quantized = {n for n, m in model.named_modules() if isinstance(m, nn.Linear) and filt(m, n)}
+ group, suffixes = tq.convrot_spec_for_scheme(tq.TQ_INT8, "qwen-image-2.1")
+ rotated = set(tq.convrot_fqns(model, filt, group, suffixes))
+ assert quantized and rotated == quantized
diff --git a/studio/backend/tests/test_diffusion_prequant.py b/studio/backend/tests/test_diffusion_prequant.py
index 62121b990e4..03ee3143342 100644
--- a/studio/backend/tests/test_diffusion_prequant.py
+++ b/studio/backend/tests/test_diffusion_prequant.py
@@ -2923,7 +2923,20 @@ def _own_names(names):
{"UNSLOTH_DIFFUSION_INT8_CONVROT": "1"},
"Qwen-Image-2.1-INT8-ConvRot.safetensors",
),
- ("Qwen/Qwen-Image-2.1", "qwen-image-2.1", "int8", {}, "Qwen-Image-2.1-INT8.safetensors"),
+ (
+ "Qwen/Qwen-Image-2.1",
+ "qwen-image-2.1",
+ "int8",
+ {},
+ "Qwen-Image-2.1-INT8-ConvRot.safetensors",
+ ),
+ (
+ "Qwen/Qwen-Image-2.1",
+ "qwen-image-2.1",
+ "int8",
+ {"UNSLOTH_DIFFUSION_INT8_CONVROT": "0"},
+ "Qwen-Image-2.1-INT8.safetensors",
+ ),
("Qwen/Qwen-Image-2.1", "qwen-image-2.1", "fp8", {}, "Qwen-Image-2.1-FP8.safetensors"),
("black-forest-labs/FLUX.2-klein-4B", None, "fp8", {}, "FLUX.2-klein-4B-FP8.safetensors"),
],
diff --git a/studio/backend/tests/test_diffusion_qwenimage21_fused.py b/studio/backend/tests/test_diffusion_qwenimage21_fused.py
new file mode 100644
index 00000000000..9469ae7e32c
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_qwenimage21_fused.py
@@ -0,0 +1,215 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""``diffusion_qwenimage21_fused``; exactness tests need CUDA sm90 / sm100."""
+
+from __future__ import annotations
+
+import pytest
+
+from core.inference import diffusion_int8_fused as i8f
+from core.inference import diffusion_qwenimage21_fused as qf
+
+torch = pytest.importorskip("torch")
+qmod = pytest.importorskip("diffusers.models.transformers.transformer_qwenimage21")
+
+DIM, HEADS, HEAD_DIM, GROUP = 256, 2, 128, 64
+
+
+def _ready() -> bool:
+ if not torch.cuda.is_available() or getattr(torch.version, "hip", None):
+ return False
+ try:
+ from torchao.quantization import Int8DynamicActivationInt8WeightConfig
+ Int8DynamicActivationInt8WeightConfig(version = 2, set_inductor_config = False)
+ except Exception: # noqa: BLE001
+ return False
+ return qf.arch_ok()
+
+
+needs_cuda = pytest.mark.skipif(
+ not _ready(),
+ reason = "needs CUDA (not ROCm), torchao Int8Tensor, and an arch the int8 GEMM swap leaves stock",
+)
+
+
[email protected](autouse = True)
+def _restore(monkeypatch):
+ monkeypatch.delenv(qf.Q21_CONVROT_FUSED_ENV, raising = False)
+ yield
+ qf.uninstall()
+
+
+def test_stock_prepare_qkv_fingerprint_matches_installed_diffusers():
+ from core.inference.diffusion_qwenimage21_rope import _FINGERPRINTS, _digest
+ assert _digest(getattr(qmod, qf._PREPARE)) in _FINGERPRINTS[qf._PREPARE]
+
+
+def test_kill_switch_offload_and_wrong_model_are_noops(monkeypatch):
+ class Other(torch.nn.Module):
+ pass
+
+ assert qf.install(Other()) == {"fused_qkv": 0, "out": 0}
+ blk_model = type("QwenImage21Transformer2DModel", (torch.nn.Module,), {})()
+ assert qf.install(blk_model, offload_active = True) == {"fused_qkv": 0, "out": 0}
+ monkeypatch.setenv(qf.Q21_CONVROT_FUSED_ENV, "0")
+ assert qf.install(blk_model) == {"fused_qkv": 0, "out": 0}
+ assert not getattr(getattr(qmod, qf._PREPARE), "__unsloth_q21_fused__", False)
+
+
+def _block(rotate: bool = True):
+ torch.manual_seed(0)
+ blk = qmod.QwenImage21TransformerBlock(DIM, HEADS, HEAD_DIM).cuda().to(torch.bfloat16).eval()
+ for p in blk.parameters():
+ p.data.normal_(0, 0.05)
+ names = [n for n, m in blk.named_modules() if isinstance(m, torch.nn.Linear)]
+ if rotate:
+ from core.inference.diffusion_convrot import rotate_linears_, warm_rotation_cache
+ rotate_linears_(blk, names, GROUP)
+ warm_rotation_cache(blk, "cuda", torch.bfloat16)
+ from torchao.quantization import Int8DynamicActivationInt8WeightConfig, quantize_
+
+ quantize_(
+ blk,
+ Int8DynamicActivationInt8WeightConfig(version = 2, set_inductor_config = False),
+ filter_fn = lambda m, fqn: isinstance(m, torch.nn.Linear),
+ )
+ return blk
+
+
+def _x(seq = 96, scale = 1.0):
+ g = torch.Generator(device = "cpu").manual_seed(1)
+ x = torch.randn(1, seq, DIM, generator = g) * scale
+ x[..., :3] *= 40
+ return x.cuda().to(torch.bfloat16)
+
+
+def _engage(blk):
+ with torch.inference_mode(False), torch.no_grad():
+ assert i8f.install(blk) == 1
+ res = qf.install_modules(blk)
+ assert res == {"fused_qkv": 1, "out": 1}
+ return res
+
+
+@needs_cuda
+def test_shared_projections_equal_the_separate_rotated_ones():
+ blk = _block()
+ x = _x()
+ attn, ff = blk.attn, blk.img_mlp
+ with torch.no_grad():
+ ref_q, ref_k, ref_v = attn.to_q(x), attn.to_k(x), attn.to_v(x)
+ ref_out = attn.to_out[0](x)
+ ref_ff = type(ff).forward(ff, x)
+ _engage(blk)
+ fused = qf._qkv_intact(attn)
+ from core.inference.diffusion_convrot import is_rotated_linear
+
+ assert is_rotated_linear(fused) and fused.out_features == 3 * DIM
+ q, k, v = i8f.int8_linear(fused, x).chunk(3, dim = -1)
+ out = i8f.int8_linear_core(attn.to_out[0], x)
+ y_ff = ff(x)
+ assert torch.equal(q, ref_q) and torch.equal(k, ref_k) and torch.equal(v, ref_v)
+ assert torch.equal(out, ref_out)
+ assert torch.equal(y_ff, ref_ff)
+ assert attn.to_q.weight.qdata.data_ptr() == fused.weight.qdata.data_ptr()
+
+
+def mod_params(x):
+ g = torch.Generator(device = "cpu").manual_seed(2)
+ return (torch.randn(1, 4 * DIM, generator = g) * 0.1).cuda().to(torch.bfloat16)
+
+
+def _rope(seq):
+ g = torch.Generator(device = "cpu").manual_seed(3)
+ ang = torch.rand(seq, HEAD_DIM // 2, generator = g) * 6.28
+ return torch.polar(torch.ones_like(ang), ang).to(torch.complex64).cuda()
+
+
+@needs_cuda
+def test_compiled_block_stays_within_the_compile_floor(monkeypatch):
+ # Inductor's own act quant is not eager-exact: bar = the stock compile's distance from eager
+ traced = []
+ real_linear = i8f.int8_linear
+
+ def counting(module, x):
+ traced.append(
+ module.out_features
+ ) # runs at trace time: proves the compiled graph took the fused QKV
+ return real_linear(module, x)
+
+ monkeypatch.setattr(i8f, "int8_linear", counting)
+ blk = _block()
+ x = _x()
+ rope = _rope(x.shape[1])
+ with torch.no_grad(), torch._inductor.config.patch(emulate_precision_casts = True):
+ eager = blk(x, mod_params(x), rotary_emb = rope)
+ torch._dynamo.reset()
+ ref = torch.compile(blk)(x, mod_params(x), rotary_emb = rope)
+ _engage(blk)
+ assert getattr(getattr(qmod, qf._PREPARE), "__unsloth_q21_fused__", False)
+ torch._dynamo.reset()
+ out = torch.compile(blk)(x, mod_params(x), rotary_emb = rope)
+ again = blk(x, mod_params(x), rotary_emb = rope)
+ assert torch.equal(again, eager)
+ assert 3 * DIM in traced
+ floor = (ref != eager).sum().item()
+ assert (out != eager).sum().item() <= 1.1 * floor + 16
+ assert (out.float() - eager.float()).abs().max().item() <= 2 * (
+ ref.float() - eager.float()
+ ).abs().max().item() + 1e-6
+
+
+@needs_cuda
+def test_plain_int8_block_is_left_alone():
+ blk = _block(rotate = False)
+ assert not qf.rotated_ff(blk.img_mlp)
+ assert qf.install_modules(blk) == {"fused_qkv": 0, "out": 0}
+ assert not qf.is_installed(blk.attn) and "forward" not in blk.attn.to_out[0].__dict__
+
+
+@needs_cuda
+def test_arch_covered_by_the_int8_gemm_swap_is_left_alone(monkeypatch):
+ blk = _block()
+ monkeypatch.setattr(qf, "arch_ok", lambda device = None: False)
+ assert not qf.rotated_ff(blk.img_mlp)
+ assert qf.install_modules(blk) == {"fused_qkv": 0, "out": 0}
+
+
+@needs_cuda
+def test_replaced_projection_falls_back_and_uninstall_restores(monkeypatch):
+ blk = _block()
+ _engage(blk)
+ attn = blk.attn
+ assert qf._qkv_intact(attn) is not None
+ original = attn.to_k
+ attn.to_k = torch.nn.Identity() # a LoRA wrapper / later swap
+ assert qf._qkv_intact(attn) is None
+ attn.to_k = original
+ qf.uninstall(blk)
+ assert not getattr(getattr(qmod, qf._PREPARE), "__unsloth_q21_fused__", False)
+ assert not qf.is_installed(attn) and "forward" not in attn.to_out[0].__dict__
+ i8f.uninstall(blk)
+
+
+@needs_cuda
+def test_deferred_install_is_cancelled_by_uninstall():
+ blk = _block()
+ model = type("QwenImage21Transformer2DModel", (torch.nn.Module,), {})()
+ model.blk = blk.cpu()
+ assert qf.install(model) == {"fused_qkv": None, "out": None}
+ assert "q21_convrot_fused" in model.__dict__["_unsloth_first_call_hooks"]
+ qf.uninstall(model)
+ assert "q21_convrot_fused" not in model.__dict__["_unsloth_first_call_hooks"]
+
+
+def test_model_unload_restores_the_process_global_patch(monkeypatch):
+ from core.inference import diffusion as d
+
+ sentinel = getattr(qmod, qf._PREPARE)
+ fake = lambda *a, **k: None # noqa: E731
+ fake.__unsloth_q21_fused__ = True
+ qf._STATE["stock"] = (qmod, sentinel)
+ monkeypatch.setattr(qmod, qf._PREPARE, fake)
+ d._uninstall_fused_dit_patches()
+ assert getattr(qmod, qf._PREPARE) is sentinel