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: build each Qwen-Image-Edit variant on its own transformer config (2509 / original Edit no longer get 2511's zero_cond_t) (#12815)

Daniel Han4b00d49577ab
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 1649e3afe7f..820f0d0a573 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -69,6 +69,8 @@ from .diffusion_families import (
resolve_base_repo,
resolve_local_gguf_child,
supported_family_names,
+ transformer_config_overrides_for,
+ transformer_variant_differs_from_base,
)
from .diffusion_compat import (
assert_flux2_pick_compatible,
@@ -2586,6 +2588,14 @@ class DiffusionBackend:
speed = kwargs.get("speed_mode")
if speed is not None and str(speed).strip().lower() == SPEED_OFF:
return False
+ if transformer_variant_differs_from_base(
+ fam,
+ kwargs.get("base_repo"),
+ kwargs.get("gguf_filename"),
+ kwargs.get("repo_id"),
+ kwargs.get("display_repo_id"),
+ ):
+ return False
try:
# A definite-offload policy skips the dense build, so widening wastes a multi-GB pull with no GGUF
# fallback.
@@ -4364,7 +4374,13 @@ class DiffusionBackend:
(
lambda companions, transformer_files: self._dense_quant_prefetch_needed(
fam,
- {**load_kwargs, "base_repo": base, "hf_token": hf_token},
+ {
+ **load_kwargs,
+ "repo_id": repo_id,
+ "gguf_filename": gguf_filename,
+ "base_repo": base,
+ "hf_token": hf_token,
+ },
companion_files = companions,
transformer_files = transformer_files,
)
@@ -5715,6 +5731,25 @@ class DiffusionBackend:
# repo's transformer/ shards, since the fallback would pull them HERE, inside the load lock, after
# eviction, where unload cannot preempt it and progress already reported 100%.
dense_fallback_allowed = bool(_transformer_prefetched)
+ # 2509 / original Edit GGUFs resolve to the 2511 base, whose transformer/ is another model.
+ if (
+ kind == "gguf"
+ and normalize_transformer_quant(transformer_quant) is not None
+ and transformer_variant_differs_from_base(
+ fam, base, gguf_filename, repo_id, display_repo_id
+ )
+ ):
+ dense_declined = True
+ if transformer_quant_decline is None:
+ transformer_quant_decline = (
+ f"{base} has a different transformer than this GGUF, so only the GGUF "
+ "itself can run it"
+ )
+ # Baking adapters needs the dense build; staying on auto lets the load fail loudly below.
+ if transformer_quant_pinned is None and not _has_active_lora(loras):
+ transformer_quant = "off"
+ else:
+ transformer_quant_decline_status = RESOLVED_UNSUPPORTED
# Set when an offloading GGUF pick loads the pre-quantised checkpoint instead (diffusion_gguf_route).
gguf_offload_placement: Optional[Any] = None
gguf_offload_scheme: Optional[str] = None
@@ -6663,6 +6698,10 @@ class DiffusionBackend:
# it, so without the flag this branch reaches the Hub on a load nobody asked for. The
# pipeline assembly below was already guarded; this call was not.
"local_files_only": local_files_only,
+ # config is the family base's (2511); 2509 / original Edit lack its zero_cond_t
+ **transformer_config_overrides_for(
+ fam, gguf_filename, repo_id, display_repo_id, base
+ ),
}
# Before the prefix shim below, which wraps whatever entry it finds and
# finds nothing for a class that is not registered yet.
@@ -7230,7 +7269,9 @@ class DiffusionBackend:
self._raise_if_load_cancelled(_load_token)
# Before from_pipe copies the scheduler.
apply_comfy_flow_shift(
- pipe, comfy_flow_shift_for(fam, gguf_filename, repo_id, base), logger
+ pipe,
+ comfy_flow_shift_for(fam, gguf_filename, repo_id, display_repo_id, base),
+ logger,
)
# Before the speed optims, so the fused batched tile decode does not replace it.
try:
diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.py
index eaa890ff5ff..ca494d715dd 100644
--- a/studio/backend/core/inference/diffusion_families.py
+++ b/studio/backend/core/inference/diffusion_families.py
@@ -121,6 +121,10 @@ class DiffusionFamily:
comfy_flow_shift: Optional[float] = None
# (lowercased id substring, shift) for checkpoints whose template differs; first match wins.
comfy_flow_shift_variants: tuple[tuple[str, float], ...] = field(default_factory = tuple)
+ # (lowercased id substring, ((key, value), ...)) overriding ``base_repo``'s transformer config; first match wins.
+ transformer_config_variants: tuple[tuple[str, tuple[tuple[str, Any], ...]], ...] = field(
+ default_factory = tuple
+ )
# Activation-guard cost of one condition pixel relative to one output pixel.
condition_pixel_weight: float = 1.0
# Extra lowercased substrings (besides ``name``) that map a repo id here.
@@ -352,8 +356,17 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
name = "qwen-image-edit",
filter_reduction_configs_archs = _REDUCTION_RACE_ARCHS,
comfy_flow_shift = 3.1, # ComfyUI ModelSamplingAuraFlow 3.1 (Qwen-Image-Edit 2511 template)
- # The 2509 template samples at ModelSamplingAuraFlow 3.
- comfy_flow_shift_variants = (("qwen-image-edit-2509", 3.0),),
+ comfy_flow_shift_variants = (
+ ("qwen-image-edit-2511", 3.1),
+ ("qwen-image-edit-2509", 3.0),
+ ("qwen-image-edit", 3.0),
+ ),
+ # Only the 2511 config sets zero_cond_t; on 2509 / original Edit it renders oversaturated, off-identity images.
+ transformer_config_variants = (
+ ("qwen-image-edit-2511", ()),
+ ("qwen-image-edit-2509", (("zero_cond_t", False),)),
+ ("qwen-image-edit", (("zero_cond_t", False),)),
+ ),
pipeline_class = "QwenImageEditPlusPipeline",
transformer_class = "QwenImageTransformer2DModel",
base_repo = "Qwen/Qwen-Image-Edit-2511",
@@ -1284,15 +1297,33 @@ _GENERATION_DEFAULTS: tuple[tuple[str, int, float], ...] = (
_GENERATION_DEFAULT_FALLBACK = (9, 0.0)
-def comfy_flow_shift_for(fam: Any, *identifiers: Optional[str]) -> Optional[float]:
- """ComfyUI's static shift for the loaded checkpoint: the first family variant whose key is in
- an identifier (repo id, GGUF file, base repo), else the family default."""
+def _first_variant(rows: Any, identifiers: tuple[Optional[str], ...]) -> Optional[tuple]:
+ """First ``(key, ...)`` row whose key is in an identifier; ``_`` reads as ``-`` (ComfyUI file names)."""
for identifier in identifiers:
- needle = (identifier or "").lower()
- for key, shift in getattr(fam, "comfy_flow_shift_variants", ()) or ():
- if key in needle:
- return shift
- return getattr(fam, "comfy_flow_shift", None)
+ needle = (identifier or "").lower().replace("_", "-")
+ for row in rows or ():
+ if row[0] in needle:
+ return row
+ return None
+
+
+def comfy_flow_shift_for(fam: Any, *identifiers: Optional[str]) -> Optional[float]:
+ row = _first_variant(getattr(fam, "comfy_flow_shift_variants", ()), identifiers)
+ return row[1] if row else getattr(fam, "comfy_flow_shift", None)
+
+
+def transformer_config_overrides_for(fam: Any, *identifiers: Optional[str]) -> dict[str, Any]:
+ row = _first_variant(getattr(fam, "transformer_config_variants", ()), identifiers)
+ return dict(row[1]) if row else {}
+
+
+def transformer_variant_differs_from_base(
+ fam: Any, base: Optional[str], *identifiers: Optional[str]
+) -> bool:
+ """Checkpoint and ``base`` name different variants; a base naming none (a local dir) is unknown."""
+ rows = getattr(fam, "transformer_config_variants", ())
+ base_row = _first_variant(rows, (base,))
+ return base_row is not None and _first_variant(rows, identifiers) not in (None, base_row)
def default_generation_params(*identifiers: Optional[str]) -> tuple[int, float]:
diff --git a/studio/backend/tests/test_diffusion_backend.py b/studio/backend/tests/test_diffusion_backend.py
index 034c180c24f..62f55d0a481 100644
--- a/studio/backend/tests/test_diffusion_backend.py
+++ b/studio/backend/tests/test_diffusion_backend.py
@@ -2090,6 +2090,129 @@ def test_edit_family_uses_own_pipeline_and_requires_image(fake_runtime, tmp_path
backend.generate(prompt = "make it night", steps = 8)
+ "gguf_filename, expected",
+ [
+ ("qwen-image-edit-2509-Q6_K.gguf", {"zero_cond_t": False}),
+ ("qwen_image_edit_2509_Q4_K_M.gguf", {"zero_cond_t": False}),
+ ("qwen-image-edit-Q4_K_M.gguf", {"zero_cond_t": False}),
+ ("qwen-image-edit-2511-Q4_K_M.gguf", {}),
+ ("model.gguf", {}),
+ ],
+)
+def test_qwen_edit_gguf_builds_on_its_variant_config(
+ fake_runtime, tmp_path, gguf_filename, expected
+):
+ """2509 / original Edit override the 2511 companion's zero_cond_t; 2511 and unnamed files do not."""
+ (tmp_path / gguf_filename).write_bytes(b"x")
+ backend = DiffusionBackend()
+ _load_into(
+ backend,
+ tmp_path,
+ gguf_filename = gguf_filename,
+ base_repo = "Qwen/Qwen-Image-Edit-2511",
+ family_override = "qwen-image-edit",
+ )
+ assert _FakeTransformer.last["config"].endswith("/Qwen-Image-Edit-2511")
+ assert {k: v for k, v in _FakeTransformer.last.items() if k == "zero_cond_t"} == expected
+
+
+def test_non_qwen_edit_gguf_gets_no_config_override(fake_runtime, tmp_path):
+ (tmp_path / "qwen-image-2512-Q4_K_M.gguf").write_bytes(b"x")
+ backend = DiffusionBackend()
+ _load_into(
+ backend, tmp_path, gguf_filename = "qwen-image-2512-Q4_K_M.gguf", family_override = "qwen-image"
+ )
+ assert "zero_cond_t" not in _FakeTransformer.last
+
+
+def test_qwen_edit_display_repo_id_names_the_variant(fake_runtime, tmp_path):
+ (tmp_path / "model.gguf").write_bytes(b"x")
+ _load_into(
+ DiffusionBackend(),
+ tmp_path,
+ gguf_filename = "model.gguf",
+ display_repo_id = "unsloth/Qwen-Image-Edit-2509-GGUF",
+ base_repo = "Qwen/Qwen-Image-Edit-2511",
+ family_override = "qwen-image-edit",
+ )
+ assert _FakeTransformer.last.get("zero_cond_t") is False
+
+
+def _qwen_edit_dense_route(backend, monkeypatch):
+ from core.inference import diffusion as dmod
+
+ _force_cuda_target(backend, monkeypatch)
+ monkeypatch.setattr(dmod, "dense_transformer_supported", lambda target: True)
+ monkeypatch.setattr(
+ dmod, "select_transformer_quant_scheme", lambda target, mode, family = None, **_kw: "fp8"
+ )
+ attempted = []
+
+ def fake_dense_load(self, *a, **k):
+ attempted.append(k.get("base") if "base" in k else a[2])
+ return None, None
+
+ monkeypatch.setattr(DiffusionBackend, "_load_dense_quant_pipeline", fake_dense_load)
+ return attempted
+
+
+ "gguf_filename, takes_dense",
+ [("qwen-image-edit-2509-Q6_K.gguf", False), ("qwen-image-edit-2511-Q4_K_M.gguf", True)],
+)
+def test_qwen_edit_variant_gguf_never_runs_the_2511_dense_transformer(
+ fake_runtime, tmp_path, monkeypatch, allow_precision_fallback, gguf_filename, takes_dense
+):
+ backend = DiffusionBackend()
+ attempted = _qwen_edit_dense_route(backend, monkeypatch)
+ (tmp_path / gguf_filename).write_bytes(b"x")
+ _load_into(
+ backend,
+ tmp_path,
+ gguf_filename = gguf_filename,
+ base_repo = "Qwen/Qwen-Image-Edit-2511",
+ family_override = "qwen-image-edit",
+ transformer_quant = "fp8",
+ )
+ assert bool(attempted) is takes_dense
+ assert _FakeTransformer.last["path"].endswith(gguf_filename)
+
+
+def test_qwen_edit_variant_gguf_refuses_a_pinned_quant(fake_runtime, tmp_path, monkeypatch):
+ backend = DiffusionBackend()
+ attempted = _qwen_edit_dense_route(backend, monkeypatch)
+ (tmp_path / "qwen-image-edit-2509-Q6_K.gguf").write_bytes(b"x")
+ with pytest.raises(RuntimeError, match = "different transformer"):
+ _load_into(
+ backend,
+ tmp_path,
+ gguf_filename = "qwen-image-edit-2509-Q6_K.gguf",
+ base_repo = "Qwen/Qwen-Image-Edit-2511",
+ family_override = "qwen-image-edit",
+ transformer_quant = "fp8",
+ )
+ assert attempted == []
+
+
+def test_qwen_edit_variant_gguf_with_baked_loras_fails_instead_of_silent_drop(
+ fake_runtime, tmp_path, monkeypatch
+):
+ backend = DiffusionBackend()
+ attempted = _qwen_edit_dense_route(backend, monkeypatch)
+ (tmp_path / "qwen-image-edit-2509-Q6_K.gguf").write_bytes(b"x")
+ with pytest.raises(RuntimeError, match = "LoRA adapters could not be applied"):
+ _load_into(
+ backend,
+ tmp_path,
+ gguf_filename = "qwen-image-edit-2509-Q6_K.gguf",
+ base_repo = "Qwen/Qwen-Image-Edit-2511",
+ family_override = "qwen-image-edit",
+ loras = [("adapter", 1.0)],
+ )
+ assert attempted == []
+
+
def test_load_pipeline_kind_uses_from_pretrained(fake_runtime):
"""A full-pipeline (no single-file) load on an unsloth/* repo builds the pipe with
pipeline_cls.from_pretrained(repo_id) -- NO single-file transformer build, NO GGUF
diff --git a/studio/backend/tests/test_diffusion_prequant.py b/studio/backend/tests/test_diffusion_prequant.py
index b13e9508fcb..10f362605a0 100644
--- a/studio/backend/tests/test_diffusion_prequant.py
+++ b/studio/backend/tests/test_diffusion_prequant.py
@@ -2857,7 +2857,7 @@ def test_the_download_plan_probes_with_the_user_token():
from core.inference.diffusion import DiffusionBackend
src = inspect.getsource(DiffusionBackend.download_plan)
- assert '{**load_kwargs, "base_repo": base, "hf_token": hf_token}' in src
+ assert '"base_repo": base,' in src and '"hf_token": hf_token,' in src
def test_a_full_fingerprint_pass_is_remembered_per_unchanged_file(monkeypatch, tmp_path):
diff --git a/studio/backend/tests/test_diffusion_qwen_edit_variants.py b/studio/backend/tests/test_diffusion_qwen_edit_variants.py
new file mode 100644
index 00000000000..638ef4dcdab
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_qwen_edit_variants.py
@@ -0,0 +1,181 @@
+# 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-Edit variants: only 2511 sets zero_cond_t; 2509 and the original sample at shift 3."""
+
+from __future__ import annotations
+
+import pytest
+
+from core.inference.diffusion_families import (
+ comfy_flow_shift_for,
+ detect_family,
+ detect_family_for_pick,
+ transformer_config_overrides_for,
+ transformer_variant_differs_from_base,
+)
+
+_OFF = {"zero_cond_t": False}
+
+
+ "identifiers, expected",
+ [
+ (
+ (
+ "qwen-image-edit-2509-Q6_K.gguf",
+ "unsloth/Qwen-Image-Edit-2509-GGUF",
+ "Qwen/Qwen-Image-Edit-2511",
+ ),
+ _OFF,
+ ),
+ ((None, "unsloth/Qwen-Image-Edit-2509-GGUF", "Qwen/Qwen-Image-Edit-2511"), _OFF),
+ ((None, "/models/local", "Qwen/Qwen-Image-Edit-2509"), _OFF),
+ (("qwen_image_edit_2509_Q4_K_M.gguf", "/models/unet", "Qwen/Qwen-Image-Edit-2511"), _OFF),
+ (
+ (
+ "qwen-image-edit-Q4_K_M.gguf",
+ "unsloth/Qwen-Image-Edit-GGUF",
+ "Qwen/Qwen-Image-Edit-2511",
+ ),
+ _OFF,
+ ),
+ ((None, "QuantStack/Qwen-Image-Edit-GGUF", "Qwen/Qwen-Image-Edit"), _OFF),
+ (
+ (
+ "qwen-image-edit-2511-Q4_K_M.gguf",
+ "unsloth/Qwen-Image-Edit-2511-GGUF",
+ "Qwen/Qwen-Image-Edit-2511",
+ ),
+ {},
+ ),
+ (("qwen_image_edit_2511_bf16.gguf", "/models/unet", "Qwen/Qwen-Image-Edit-2511"), {}),
+ (("model.gguf", "/models/unet", "Qwen/Qwen-Image-Edit-2511"), {}),
+ ],
+)
+def test_qwen_edit_transformer_config_per_variant(identifiers, expected):
+ fam = detect_family("qwen-image-edit")
+ assert fam.base_repo == "Qwen/Qwen-Image-Edit-2511"
+ assert transformer_config_overrides_for(fam, *identifiers) == expected
+
+
+def test_variant_lookup_returns_a_fresh_dict():
+ fam = detect_family("qwen-image-edit")
+ first = transformer_config_overrides_for(fam, "qwen-image-edit-2509-Q6_K.gguf")
+ first["zero_cond_t"] = True
+ assert transformer_config_overrides_for(fam, "qwen-image-edit-2509-Q6_K.gguf") == _OFF
+
+
+ "repo_id, gguf_filename",
+ [
+ ("unsloth/Qwen-Image-2512-GGUF", "qwen-image-2512-Q4_K_M.gguf"),
+ ("unsloth/Qwen-Image-GGUF", "qwen-image-Q4_K_M.gguf"),
+ ("unsloth/FLUX.1-Kontext-dev-GGUF", "flux1-kontext-dev-Q4_K_M.gguf"),
+ ("unsloth/Z-Image-Turbo-GGUF", "z-image-turbo-Q4_K_M.gguf"),
+ ],
+)
+def test_other_families_get_no_config_override(repo_id, gguf_filename):
+ fam = detect_family_for_pick(repo_id, gguf_filename)
+ assert fam is not None and fam.name != "qwen-image-edit"
+ assert transformer_config_overrides_for(fam, gguf_filename, repo_id, fam.base_repo) == {}
+
+
+def test_qwen_edit_flow_shift_per_variant():
+ # Comfy-Org image_qwen_image_edit{,_2509} templates: ModelSamplingAuraFlow 3; _2511: 3.1.
+ fam = detect_family("qwen-image-edit")
+ base = fam.base_repo
+ assert (
+ comfy_flow_shift_for(
+ fam, "qwen-image-edit-Q4_K_M.gguf", "unsloth/Qwen-Image-Edit-GGUF", base
+ )
+ == 3.0
+ )
+ assert comfy_flow_shift_for(fam, None, "Qwen/Qwen-Image-Edit", None) == 3.0
+ assert (
+ comfy_flow_shift_for(
+ fam, "qwen-image-edit-2509-Q6_K.gguf", "unsloth/Qwen-Image-Edit-2509-GGUF", base
+ )
+ == 3.0
+ )
+ assert (
+ comfy_flow_shift_for(
+ fam, "qwen-image-edit-2511-Q4_K_M.gguf", "unsloth/Qwen-Image-Edit-2511-GGUF", base
+ )
+ == 3.1
+ )
+ assert comfy_flow_shift_for(fam, None, "unsloth/Qwen-Image-Edit-2511", None) == 3.1
+ assert comfy_flow_shift_for(fam, "model.gguf", "/models/unet", base) == 3.1
+ assert comfy_flow_shift_for(fam, None, None, None) == 3.1
+
+
+ "gguf_filename, shift",
+ [
+ ("qwen_image_edit_2509_Q4_K_M.gguf", 3.0),
+ ("Qwen_Image_Edit-Q4_0.gguf", 3.0),
+ ("qwen_image_edit_2511_Q4_K_M.gguf", 3.1),
+ ],
+)
+def test_comfy_style_names_pick_their_shift(gguf_filename, shift):
+ fam = detect_family("qwen-image-edit")
+ assert comfy_flow_shift_for(fam, gguf_filename, "/models/unet", fam.base_repo) == shift
+
+
+ "base, gguf_filename, differs",
+ [
+ ("Qwen/Qwen-Image-Edit-2511", "qwen-image-edit-2509-Q6_K.gguf", True),
+ ("Qwen/Qwen-Image-Edit-2511", "qwen_image_edit_Q4_K_M.gguf", True),
+ ("Qwen/Qwen-Image-Edit-2511", "qwen-image-edit-2511-Q4_K_M.gguf", False),
+ ("Qwen/Qwen-Image-Edit-2511", "model.gguf", False),
+ ("Qwen/Qwen-Image-Edit-2509", "qwen-image-edit-2509-Q6_K.gguf", False),
+ ("/models/qwen-edit-pipeline", "qwen-image-edit-2509-Q6_K.gguf", False),
+ ],
+)
+def test_variant_differs_from_base(base, gguf_filename, differs):
+ fam = detect_family("qwen-image-edit")
+ assert (
+ transformer_variant_differs_from_base(fam, base, gguf_filename, "/models/unet") is differs
+ )
+
+
+def test_other_families_never_differ_from_base():
+ fam = detect_family("qwen-image")
+ assert not transformer_variant_differs_from_base(
+ fam, fam.base_repo, "qwen-image-edit-2509-Q6_K.gguf"
+ )
+
+
+ "gguf_filename, stages_transformer",
+ [("qwen-image-edit-2509-Q4_K_M.gguf", False), ("qwen-image-edit-2511-Q4_K_M.gguf", True)],
+)
+def test_download_plan_skips_the_2511_transformer_for_a_variant(
+ monkeypatch, gguf_filename, stages_transformer
+):
+ import core.inference.diffusion as dmod
+
+ monkeypatch.setattr(dmod, "_resolve_base_repo", lambda *a, **k: "Qwen/Qwen-Image-Edit-2511")
+ monkeypatch.setattr(dmod, "_assert_base_repo_accessible", lambda *a, **k: None)
+ monkeypatch.setattr(
+ dmod.DiffusionBackend, "_te_prequant_plan_files", staticmethod(lambda *a, **k: {})
+ )
+ monkeypatch.setattr(
+ dmod.DiffusionBackend, "_dense_quant_prefetch_decision", lambda self, *a, **k: True
+ )
+ asked = []
+
+ def estimate(
+ *a,
+ include_transformer = False,
+ **k,
+ ):
+ asked.append(include_transformer((), ("transformer/x.safetensors",)))
+ return 0, []
+
+ monkeypatch.setattr(dmod.DiffusionBackend, "_estimate_download_bytes", staticmethod(estimate))
+ dmod.DiffusionBackend().download_plan(
+ "unsloth/Qwen-Image-Edit-GGUF", gguf_filename = gguf_filename, transformer_quant = "fp8"
+ )
+ assert asked == [stages_transformer]