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.

Route Qwen-Image-2.1 GGUFs to the sd.cpp engine (#11507)

Daniel Han7efdd45b03f4
diff --git a/studio/backend/core/inference/diffusion_engine_router.py b/studio/backend/core/inference/diffusion_engine_router.py
index 0fa66d04c8c..059f44e1169 100644
--- a/studio/backend/core/inference/diffusion_engine_router.py
+++ b/studio/backend/core/inference/diffusion_engine_router.py
@@ -39,6 +39,7 @@ from core.inference.sd_cpp_backend import (
ensure_sd_server_binary,
note_unlaunchable_accelerator_build,
preferred_accelerator,
+ sd_cpp_binary_runs_family,
usable_or_recorded_failure,
)
from core.inference.sd_cpp_engine import (
@@ -239,6 +240,7 @@ def select_and_activate_engine(
binary = None
server_binary = None
+ incapable_build = False
if policy_eligible and fam_ok:
# Once, so server and CLI cannot disagree.
selected_card = _selected_card(gpu_ordinal)
@@ -292,6 +294,27 @@ def select_and_activate_engine(
note_unlaunchable_accelerator_build(
unlaunchable_cli or unlaunchable_server, card = selected_card
)
+ # Runnable is not the same as capable. A build installed before this family's architecture
+ # existed upstream is reused untouched -- nothing upgrades a runnable build of the right
+ # accelerator -- and sd-cli only discovers it cannot read the model deep inside the load,
+ # which for the server means a failed load and for the one-shot path a backend that
+ # reported ready and dies on the first generation. Diffusers can run it, so drop the
+ # incapable binary here and let the fallback below say why.
+ for name, candidate in (("sd-server", server_binary), ("sd-cli", binary)):
+ if candidate and not sd_cpp_binary_runs_family(candidate, fam):
+ incapable_build = True
+ logger.warning(
+ "%s at %s predates %s support; using diffusers. Reinstall the native engine "
+ "(delete the managed stable-diffusion.cpp install, or point SD_CLI_PATH at a "
+ "build from after upstream added it) to use it here",
+ name,
+ candidate,
+ fam.name,
+ )
+ if name == "sd-server":
+ server_binary = None
+ else:
+ binary = None
native_available = bool(binary or server_binary) and policy_eligible and fam_ok
choice = select_diffusion_engine(
@@ -305,6 +328,8 @@ def select_and_activate_engine(
reason = f"GPU backend '{backend}' uses diffusers"
elif not fam_ok:
reason = f"family '{fam.name}' has no native sd.cpp asset mapping"
+ elif incapable_build:
+ reason = f"the installed sd.cpp build predates '{fam.name}' support"
elif not (binary or server_binary):
reason = "native sd.cpp binary unavailable"
else:
@@ -312,7 +337,9 @@ def select_and_activate_engine(
return _activate(ENGINE_DIFFUSERS, reason)
-def native_binary_installed(*, gpu_ordinal: Optional[int] = None) -> bool:
+def native_binary_installed(
+ *, gpu_ordinal: Optional[int] = None, fam: Optional[DiffusionFamily] = None
+) -> bool:
"""Whether a RUNNABLE sd.cpp binary is already on disk, installing nothing to find out.
Separated from the prediction because the two answers differ where it matters: prediction
@@ -320,6 +347,10 @@ def native_binary_installed(*, gpu_ordinal: Optional[int] = None) -> bool:
must know whether selection could still fall back to diffusers needs the unassumed answer.
Filters exactly as selection does, card included, or the plan stages the wrong engine's files.
+ Given ``fam``, that includes selection's architecture gate: a build that cannot run this family
+ is not a native route for it, and a prediction that says otherwise stages sd-cli's companion
+ VAE and text encoder for a load that goes to diffusers. Without ``fam`` the question is the
+ older one, "is there a binary at all".
"""
selected_card = _selected_card(gpu_ordinal)
install_accelerator = preferred_accelerator(
@@ -330,13 +361,19 @@ def native_binary_installed(*, gpu_ordinal: Optional[int] = None) -> bool:
install_accelerator,
selected_card,
)
- if server_binary and _server_binary_runnable(server_binary):
+ if (
+ server_binary
+ and _server_binary_runnable(server_binary)
+ and (fam is None or sd_cpp_binary_runs_family(server_binary, fam))
+ ):
return True
binary = usable_or_recorded_failure(
ensure_sd_cpp_binary(allow_install = False, accelerator = install_accelerator),
install_accelerator,
selected_card,
)
+ if fam is not None and binary and not sd_cpp_binary_runs_family(binary, fam):
+ return False
return bool(binary and SdCppEngine(binary = binary).version() is not None)
@@ -375,7 +412,14 @@ def predict_engine(
if not (policy_eligible and family_sd_cpp_supported(fam)):
return ENGINE_DIFFUSERS
- native_available = native_binary_installed(gpu_ordinal = gpu_ordinal) or _install_allowed()
+ # A permitted install counts as available only where selection would actually perform one.
+ # ``ensure_*_binary`` keeps a runnable build of the right accelerator untouched, so a resident
+ # build that cannot run this family is never upgraded away, and predicting native for it would
+ # stage sd-cli's companions for a load the router sends to diffusers. With nothing resident the
+ # install happens and lands on the pinned prebuilt, which is current by definition.
+ native_available = native_binary_installed(gpu_ordinal = gpu_ordinal, fam = fam) or (
+ _install_allowed() and not native_binary_installed(gpu_ordinal = gpu_ordinal)
+ )
return select_diffusion_engine(
backend, native_available = native_available, prefer_native = prefer_native
)
diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.py
index 69e4bda6267..feaf33715f3 100644
--- a/studio/backend/core/inference/diffusion_families.py
+++ b/studio/backend/core/inference/diffusion_families.py
@@ -139,6 +139,17 @@ class DiffusionFamily:
# sd-cli defaults.
sd_cpp_sampling_method: Optional[str] = None
sd_cpp_flow_shift: Optional[float] = None
+ # A literal this family's ARCHITECTURE puts in an sd.cpp build that can run it. Set it for a
+ # family whose support landed upstream after builds were already in the wild: the asset mapping
+ # above says what to hand sd-cli, not whether the sd-cli on this disk understands the model, and
+ # a binary installed before the support existed is reused as-is (nothing upgrades a runnable
+ # build of the right accelerator). Without a gate that is a load that reports ready and dies on
+ # the first generation, where falling back to diffusers is both possible and correct.
+ #
+ # Matched against the binary's BYTES rather than the install record's tag: every mirror release
+ # carries the upstream base in its tag name whatever tree was built, so the tag cannot answer
+ # this, and a custom SD_CLI_PATH build has no record at all.
+ sd_cpp_arch_marker: Optional[str] = None
# True when Unsloth can TRAIN a LoRA on this family; the training-start path refuses a non-trainable family up
# front.
trainable: bool = False
@@ -375,6 +386,48 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
# capability ships dark.
reference = True,
aliases = ("qwen_image_21", "qwenimage21", "qwen-image-21"),
+ # Built by us from Qwen/Qwen-Image-2.1 itself: the same 238 tensors under upstream's own
+ # names, cast fp32 -> bf16 and written as one file, because sd-cli takes --vae as a single
+ # file rather than a diffusers subfolder. That is 0.63 GiB against upstream's 1.26 GiB of
+ # fp32, and a fixed-seed 1024 render through it is PIXEL-identical to one made with the
+ # fp32 original. No third-party repack is in the chain; the file is nonetheless
+ # value-identical to Comfy-Org's bf16 repack, all 238 tensors, so either works.
+ #
+ # It lives beside the pre-cast text encoder in the FP8 repo rather than in a companion repo
+ # of its own, and NOT in the GGUF repo: sd_cpp_companion_only_repo_ids() is companions
+ # minus loadable, and the GGUF repo appears in no family field, so pointing here at it
+ # would classify the repo that holds every denoiser as fetch-only and hide it from the
+ # catalog. The FP8 repo is in prequant_repos, so it is subtracted and stays loadable.
+ # FP8 and INT8 picks do not use this file at all; they take the VAE from the base repo
+ # through diffusers, as every prequant family does.
+ #
+ # 2.1 has its own VAE class, so the qwen-image or Wan 2.2 file decodes to noise here
+ # rather than failing.
+ sd_cpp_vae = ("unsloth/Qwen-Image-2.1-FP8", "vae/qwen_image_2.1_vae_bf16.safetensors"),
+ # Qwen3-VL 8B, not Qwen2.5-VL, and supplied through --llm rather than --qwen2vl: the
+ # qwen2vl flag carries Qwen2-VL's vision preprocessing, which this encoder does not want.
+ # Q4_K_M keeps the CPU RAM win the no-GPU route exists for (bf16 is 16.4 GB, this is 4.7).
+ # Text to image only, which is all this family exposes (edit is False, and there are no
+ # img2img / inpaint pipelines). Upstream's docs/qwen_image_2.1.md requires a separate
+ # mmproj through --llm_vision before a GGUF encoder can do image editing; turning editing
+ # on here without adding it would load an encoder that logs "vision disabled" and carry on.
+ sd_cpp_text_encoders = (
+ (
+ "unsloth/Qwen3-VL-8B-Instruct-GGUF",
+ "Qwen3-VL-8B-Instruct-Q4_K_M.gguf",
+ "llm",
+ ),
+ ),
+ sd_cpp_sampling_method = "euler",
+ # No flow shift on purpose. Qwen-Image pins 3.0, but upstream sd.cpp selects a
+ # resolution-dependent schedule for qwen_image_2_1 itself, and passing a fixed shift
+ # overrides that silently: the render still succeeds and is simply worse off-square.
+ #
+ # Support landed upstream on 2026-09-20, long after builds shipped, so the gate matters
+ # here more than anywhere: measured across six builds on this host, only the pinned
+ # release (both sd-cli and sd-server, CPU and CUDA) carries this literal, and the five
+ # older ones, including the previous pin, do not.
+ sd_cpp_arch_marker = "qwen_image_2_1",
),
DiffusionFamily(
name = "z-image",
@@ -1465,7 +1518,11 @@ def family_gguf_loadable(fam: DiffusionFamily) -> bool:
def family_sd_cpp_supported(fam: DiffusionFamily) -> bool:
"""True when the family has the single-file VAE + text-encoder mapping sd.cpp needs; without it
- the no-GPU route falls back to diffusers."""
+ the no-GPU route falls back to diffusers.
+
+ Says nothing about the sd.cpp build on this disk. A family that also declares
+ ``sd_cpp_arch_marker`` needs ``sd_cpp_binary_runs_family`` on top of this before the native
+ route is really available."""
return bool(fam.sd_cpp_vae and fam.sd_cpp_text_encoders)
diff --git a/studio/backend/core/inference/sd_cpp_args.py b/studio/backend/core/inference/sd_cpp_args.py
index 678c3cf2fed..22c63857e48 100644
--- a/studio/backend/core/inference/sd_cpp_args.py
+++ b/studio/backend/core/inference/sd_cpp_args.py
@@ -31,6 +31,10 @@ _TE_FLAGS_BY_FAMILY: dict[str, tuple[str, ...]] = {
"flux.2-klein": ("--llm",),
"flux.2-dev": ("--llm",),
"qwen-image": ("--qwen2vl",),
+ # 2.1 conditions on Qwen3-VL, which sd-cli takes through --llm. --qwen2vl is an alias of --llm
+ # that also turns on Qwen2-VL's vision path, so it is the wrong door even though both names
+ # reach the same field.
+ "qwen-image-2.1": ("--llm",),
"flux.1": ("--clip_l", "--t5xxl"),
}
diff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.py
index 5fd5e57740b..e43418a884a 100644
--- a/studio/backend/core/inference/sd_cpp_backend.py
+++ b/studio/backend/core/inference/sd_cpp_backend.py
@@ -1570,6 +1570,66 @@ def _superseded_legacy_server(binary: Optional[str], accelerator: str) -> bool:
return False
+_ARCH_MARKER_CACHE: dict[tuple[str, int, int, str], bool] = {}
+
+
+def binary_carries_marker(binary: Optional[str], marker: Optional[str]) -> bool:
+ """Whether the sd.cpp executable at ``binary`` contains the literal ``marker``.
+
+ An architecture upstream has not implemented leaves no trace in the build, so this answers
+ "can this particular sd-cli/sd-server run that model" for a build whose version string cannot:
+ our mirror releases all name the same upstream base in their tag whatever tree was built, and a
+ binary reached through SD_CLI_PATH has no install record to consult at all.
+
+ No marker means no claim, so an unmarked family is True and nothing changes for it. An
+ unreadable binary is True as well: refusing a load because a stat failed would take the native
+ route away on a host where it works, and the old behaviour (attempt, fail, surface the error)
+ is no worse than what this replaces.
+
+ Scanned in chunks with an overlap, since the literal can straddle a boundary, and memoised on
+ (path, size, mtime) so a reinstall is noticed while repeated loads read 100+ MB once.
+ """
+ if not marker:
+ return True
+ if not binary:
+ return False
+ try:
+ st = os.stat(binary)
+ key = (str(binary), int(st.st_size), int(st.st_mtime_ns), marker)
+ except OSError:
+ return True
+ hit = _ARCH_MARKER_CACHE.get(key)
+ if hit is not None:
+ return hit
+ needle = marker.encode()
+ chunk = 8 << 20
+ found = False
+ try:
+ with open(binary, "rb") as fh:
+ tail = b""
+ while True:
+ block = fh.read(chunk)
+ if not block:
+ break
+ if needle in tail + block:
+ found = True
+ break
+ tail = block[-(len(needle) - 1) :] if len(needle) > 1 else b""
+ except OSError:
+ return True
+ _ARCH_MARKER_CACHE[key] = found
+ return found
+
+
+def sd_cpp_binary_runs_family(binary: Optional[str], fam: Any) -> bool:
+ """Whether the sd.cpp build at ``binary`` implements ``fam``'s architecture.
+
+ The companion to ``family_sd_cpp_supported``, which only says whether the family has assets to
+ hand sd-cli. This is the half that looks at the disk.
+ """
+ return binary_carries_marker(binary, getattr(fam, "sd_cpp_arch_marker", None))
+
+
def _installed_accelerator_of(binary: Optional[str]) -> Optional[str]:
"""The accelerator class recorded for the managed install ``binary`` belongs to.
diff --git a/studio/backend/tests/test_diffusion_engine_router.py b/studio/backend/tests/test_diffusion_engine_router.py
index 9eb2f05726a..4fe743bfbf3 100644
--- a/studio/backend/tests/test_diffusion_engine_router.py
+++ b/studio/backend/tests/test_diffusion_engine_router.py
@@ -403,3 +403,58 @@ def test_predict_engine_returns_diffusers_for_a_family_without_native_assets(mon
_set_binary(monkeypatch, "/usr/bin/sd-cli")
_set_runnable(monkeypatch)
assert r.predict_engine(detect_family("sdxl"), model_kind = "gguf") == ENGINE_DIFFUSERS
+
+
+# ── the architecture gate: a runnable build is not always a CAPABLE one ───────
+
+
+def _write_binary(tmp_path, name, *, marker: bool):
+ """A stand-in sd.cpp executable, with or without the 2.1 architecture literal in it."""
+ path = tmp_path / name
+ body = b"ELF-ish padding " * 64
+ if marker:
+ body += b"qwen_image_2_1.hpp"
+ path.write_bytes(body + b" trailing")
+ return str(path)
+
+
+def test_a_build_that_predates_the_family_does_not_get_the_native_route(monkeypatch, tmp_path):
+ # The real regression: nothing upgrades a runnable sd.cpp build of the right accelerator, so a
+ # host that installed one before upstream added Qwen-Image-2.1 keeps it, and without this gate
+ # the router hands it a model it cannot read -- a load that reports ready and dies on the first
+ # generation. Diffusers can run it, so the fallback is the right answer and the reason says so.
+ _set_device(monkeypatch, "cpu")
+ _set_runnable(monkeypatch)
+ _set_binary(monkeypatch, _write_binary(tmp_path, "sd-cli-old", marker = False))
+ assert _select("qwen-image-2.1") == ENGINE_DIFFUSERS
+ assert "predates" in (r._fallback_reason or "")
+
+ _set_binary(monkeypatch, _write_binary(tmp_path, "sd-cli-new", marker = True))
+ assert _select("qwen-image-2.1") == ENGINE_SD_CPP
+
+
+def test_the_gate_only_speaks_for_families_that_declare_a_marker(monkeypatch, tmp_path):
+ # z-image has been in sd.cpp for as long as the native route has existed and declares no
+ # marker, so the same old binary that is refused above must still serve it. A gate that read
+ # "no marker found" as "cannot run" would take the native engine away from every family.
+ _set_device(monkeypatch, "cpu")
+ _set_runnable(monkeypatch)
+ _set_binary(monkeypatch, _write_binary(tmp_path, "sd-cli-old2", marker = False))
+ assert _select("z-image") == ENGINE_SD_CPP
+
+
+def test_the_prediction_agrees_with_the_selection_about_an_incapable_build(monkeypatch, tmp_path):
+ # The download plan is built from the prediction. Installs are ALLOWED here and there is a
+ # resident binary, which is exactly the case where a permitted install changes nothing: the
+ # ensure helpers keep a runnable build of the right accelerator. Predicting native would stage
+ # sd-cli's companion VAE and text encoder for a load that goes to diffusers.
+ _set_device(monkeypatch, "cpu")
+ _set_runnable(monkeypatch)
+ _set_binary(monkeypatch, _write_binary(tmp_path, "sd-cli-old3", marker = False))
+ fam = detect_family("qwen-image-2.1")
+ assert r.predict_engine(fam, model_kind = "gguf") == ENGINE_DIFFUSERS
+ # ... and a fresh host with nothing installed still predicts native, since the install lands on
+ # the pinned prebuilt, which does carry the architecture.
+ _set_binary(monkeypatch, None)
+ monkeypatch.setattr(r, "ensure_sd_server_binary", lambda **_: None)
+ assert r.predict_engine(fam, model_kind = "gguf") == ENGINE_SD_CPP
diff --git a/studio/backend/tests/test_diffusion_more_families.py b/studio/backend/tests/test_diffusion_more_families.py
index f8d556fa321..a0ba70fd8bd 100644
--- a/studio/backend/tests/test_diffusion_more_families.py
+++ b/studio/backend/tests/test_diffusion_more_families.py
@@ -14,8 +14,11 @@ from core.inference.diffusion_families import (
default_generation_params,
detect_family,
excluded_model_reason,
+ family_sd_cpp_supported,
+ sd_cpp_companion_only_repo_ids,
sd_cpp_text_encoders_for,
)
+from core.inference.sd_cpp_args import text_encoder_flags_for_family
from core.inference.diffusion_lora import _CURATED, list_loras
@@ -665,6 +668,70 @@ def test_every_image_family_base_repo_is_loadable():
), f"these families declare a base repo that validate_load_request refuses: {unreachable}"
+def test_qwen_image_21_gguf_reaches_sd_cpp_with_its_own_vae_and_a_qwen3vl_encoder():
+ """The no-GPU route for unsloth/Qwen-Image-2.1-GGUF.
+
+ Every assertion here is a way the route was observed to fail quietly rather than loudly:
+ a family without both sd.cpp assets silently falls back to diffusers, the qwen-image VAE
+ decodes 2.1 latents to noise instead of erroring, and a fixed flow shift overrides the
+ resolution-dependent schedule upstream picks for this architecture.
+ """
+ fam = detect_family("unsloth/Qwen-Image-2.1-GGUF")
+ assert fam is not None and fam.name == "qwen-image-2.1"
+ assert family_sd_cpp_supported(fam)
+
+ assert fam.sd_cpp_vae == (
+ "unsloth/Qwen-Image-2.1-FP8",
+ "vae/qwen_image_2.1_vae_bf16.safetensors",
+ )
+ # Not the qwen-image VAE: a different class for a different latent space, which decodes to
+ # noise rather than raising if it is ever substituted here.
+ assert "2.1" in fam.sd_cpp_vae[1]
+
+ encoders = sd_cpp_text_encoders_for(fam, "unsloth/Qwen-Image-2.1-GGUF", None)
+ assert len(encoders) == 1
+ repo, filename, kind = encoders[0]
+ assert repo == "unsloth/Qwen3-VL-8B-Instruct-GGUF"
+ assert filename == "Qwen3-VL-8B-Instruct-Q4_K_M.gguf"
+ assert kind == "llm"
+ assert text_encoder_flags_for_family(fam.name) == ("--llm",)
+
+ assert fam.sd_cpp_sampling_method == "euler"
+ assert fam.sd_cpp_flow_shift is None
+
+ # The encoder repo is fetch-only and must not be offered as a loadable model. The VAE repo is
+ # the base itself, so it must NOT be classified that way.
+ companions = sd_cpp_companion_only_repo_ids()
+ assert "unsloth/qwen3-vl-8b-instruct-gguf" in companions
+ # The VAE ships inside a repo that is itself loadable, so it must NOT be classified fetch-only.
+ # Putting it in the GGUF repo instead WOULD be: that repo appears in no family field, so
+ # companions-minus-loadable would mark the home of every denoiser as a companion and hide it.
+ assert "unsloth/qwen-image-2.1-fp8" not in companions
+ assert "qwen/qwen-image-2.1" not in companions
+
+
+def test_the_pinned_prebuilt_is_one_that_can_load_qwen_image_21():
+ """The route is only real if the binary the installer pins understands the architecture.
+
+ The tag STRING cannot answer this: every mirror build resolves to the same master-813 base, so
+ the August build and the current one are indistinguishable by name. What is asserted here is the
+ pin itself, against the release verified to render this family (26.9s at 1024 on one B200,
+ Q4_K_M denoiser, bf16 VAE, Q4_K_M Qwen3-VL encoder). Bump both together or not at all.
+ """
+ import importlib.util
+ from pathlib import Path
+
+ script = Path(__file__).resolve().parents[2] / "install_sd_cpp_prebuilt.py"
+ spec = importlib.util.spec_from_file_location("install_sd_cpp_prebuilt_pin", script)
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+
+ assert module.DEFAULT_TAG == "master-813-bfbef5b-u1d02858", (
+ "the pinned prebuilt must be one built from a tree carrying Qwen-Image-2.1; "
+ f"{module.DEFAULT_TAG} is not"
+ )
+
+
def test_a_minimum_that_has_not_shipped_does_not_prescribe_an_impossible_upgrade():
"""``pip install -U 'diffusers>=0.41.0'`` has no candidate while 0.41.0 is unreleased, so the
refusal has to name the pinned main build Studio actually installs for this class."""
diff --git a/studio/backend/tests/test_sd_cpp_args.py b/studio/backend/tests/test_sd_cpp_args.py
index 406c32274e8..8d102b684bd 100644
--- a/studio/backend/tests/test_sd_cpp_args.py
+++ b/studio/backend/tests/test_sd_cpp_args.py
@@ -50,6 +50,9 @@ def test_te_flags_by_family():
assert text_encoder_flags_for_family("qwen-image") == ("--qwen2vl",)
assert text_encoder_flags_for_family("flux.1") == ("--clip_l", "--t5xxl")
assert text_encoder_flags_for_family("flux.2-klein") == ("--llm",)
+ # Not --qwen2vl, even though the family name starts with the same three words: 2.1 conditions
+ # on Qwen3-VL and the qwen2vl door additionally enables Qwen2-VL's vision preprocessing.
+ assert text_encoder_flags_for_family("qwen-image-2.1") == ("--llm",)
assert text_encoder_flags_for_family("unknown") == ()
diff --git a/studio/backend/tests/test_sd_cpp_backend.py b/studio/backend/tests/test_sd_cpp_backend.py
index 953720eacd9..0f485745692 100644
--- a/studio/backend/tests/test_sd_cpp_backend.py
+++ b/studio/backend/tests/test_sd_cpp_backend.py
@@ -2426,3 +2426,44 @@ def test_generation_in_flight_never_builds_a_backend(monkeypatch):
lambda *a, **k: pytest.fail("liveness constructed a native diffusion backend"),
)
assert bk.generation_in_flight() is False
+
+
+# ── the architecture marker scan ─────────────────────────────────────────────
+
+
+def test_the_marker_is_found_even_when_it_straddles_a_read_boundary(tmp_path):
+ # The scan reads in 8 MiB blocks, and a literal landing across the seam is exactly the case a
+ # naive loop misses: it would report a current build as incapable and quietly send every load
+ # of the family to diffusers. Placed so the first block ends mid-literal.
+ marker = "qwen_image_2_1"
+ chunk = 8 << 20
+ path = tmp_path / "sd-cli"
+ body = bytearray(b"\0" * (chunk + len(marker) * 2))
+ body[chunk - len(marker) // 2 : chunk - len(marker) // 2 + len(marker)] = marker.encode()
+ path.write_bytes(bytes(body))
+ assert bk.binary_carries_marker(str(path), marker) is True
+ assert bk.binary_carries_marker(str(path), "wan_2_2_no_such_arch") is False
+
+
+def test_an_unreadable_binary_and_an_unmarked_family_both_leave_the_route_alone(tmp_path):
+ # Two "no claim" cases that must not become a refusal. A family with no marker asks nothing of
+ # the build, and a path that cannot be stat-ed or opened is not evidence about its contents:
+ # refusing there would take the native engine away on a host where it works.
+ present = tmp_path / "sd-cli"
+ present.write_bytes(b"nothing interesting")
+ assert bk.binary_carries_marker(str(present), None) is True
+ assert bk.binary_carries_marker(str(tmp_path / "missing"), "qwen_image_2_1") is True
+ assert bk.binary_carries_marker(None, "qwen_image_2_1") is False
+ assert bk.sd_cpp_binary_runs_family(str(present), detect_family("z-image")) is True
+ assert bk.sd_cpp_binary_runs_family(str(present), detect_family("qwen-image-2.1")) is False
+
+
+def test_the_scan_is_redone_when_the_binary_on_that_path_changes(tmp_path):
+ # An upgrade writes a new build to the SAME path, so a result memoised on the path alone would
+ # keep reporting the old answer for the life of the process and the upgrade would never take
+ # effect. Keyed on size and mtime as well.
+ path = tmp_path / "sd-cli"
+ path.write_bytes(b"an old build")
+ assert bk.binary_carries_marker(str(path), "qwen_image_2_1") is False
+ path.write_bytes(b"a new build with qwen_image_2_1 in it")
+ assert bk.binary_carries_marker(str(path), "qwen_image_2_1") is True
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
index 1336ffa06f6..77e0abe3b46 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
@@ -195,6 +195,7 @@ export const IMAGE_CATALOG: CatalogGroup[] = [
prequantRepo: "unsloth/Qwen-Image-2.1-FP8",
prequantSizeGb: { fp8: 7.12, int8: 7.26 },
}),
+ gguf("unsloth/Qwen-Image-2.1-GGUF"),
],
},
{
diff --git a/studio/install_sd_cpp_prebuilt.py b/studio/install_sd_cpp_prebuilt.py
index 782fd0df5fa..ff9c8c13b99 100644
--- a/studio/install_sd_cpp_prebuilt.py
+++ b/studio/install_sd_cpp_prebuilt.py
@@ -39,7 +39,11 @@ else:
DEFAULT_REPO = "unslothai/stable-diffusion.cpp"
UPSTREAM_FALLBACK_REPO = "leejet/stable-diffusion.cpp"
# Pinned for reproducibility; UNSLOTH_SD_CPP_TAG overrides (empty tracks latest) and a missing tag falls back to latest. The -u<id> suffix is the mirror's patch set: an unpatched build aborts on the default --cfg-scale and on --vae-on-cpu, and quantizes MiniMax-H3's 1-D norms into an output uncorrelated with its own bf16 reference (leejet/stable-diffusion.cpp#1861, #1862, #1863).
-DEFAULT_TAG = "master-813-bfbef5b-u13b9d92"
+# The Qwen-Image-2.1 line: the tag STRING still resolves to the master-813 base, because that is the
+# newest upstream release our ancestry names, but this build is the mirror's current tree and carries
+# the architecture (upstream 137f7409bb, 2026-09-20). The u13b9d92 build this replaces is from
+# 2026-08-09 and cannot load it at all, so the native route for that family is only real from here.
+DEFAULT_TAG = "master-813-bfbef5b-u1d02858"
REPO = DEFAULT_REPO