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: Qwen-Image-Layered on the diffusers engine, GGUF included (#12775)

Daniel Han7c16bcc7c99f
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 6ee3f151860..1649e3afe7f 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -721,9 +721,25 @@ def _compile_shape_dims(
if init_pil is None or not _is_source_sized(workflow, family):
return int(width), int(height)
iw, ih = init_pil.size
+ if getattr(family, "layer_count", 0):
+ return _layered_canvas(family, (iw, ih))
return int(iw), int(ih)
+def _layered_canvas(family: Any, size: tuple[int, int]) -> tuple[int, int]:
+ """The (width, height) QwenImageLayeredPipeline decomposes at: the ``layer_resolution`` square's area at the input's
+ aspect ratio, each side rounded to 32 (``calculate_dimensions`` in the pipeline). The input image's own size only
+ sets the ratio."""
+ import math
+
+ iw, ih = size
+ area = float(getattr(family, "layer_resolution", 640)) ** 2
+ ratio = float(iw) / float(max(1, ih))
+ width = math.sqrt(area * ratio)
+ height = width / ratio
+ return max(32, int(round(width / 32)) * 32), max(32, int(round(height / 32)) * 32)
+
+
# Official non-unsloth pipeline bases: safetensors-only, no remote code, exact lowercased match
_TRUSTED_NON_GGUF_REPOS = frozenset(
{
@@ -753,6 +769,7 @@ _TRUSTED_NON_GGUF_REPOS = frozenset(
"qwen/qwen-image",
"qwen/qwen-image-2512",
"qwen/qwen-image-edit-2511",
+ "qwen/qwen-image-layered",
# Qwen-Image-2.1: the family's own base_repo, and a family whose base is not listed here is
# not a family at all. Detection resolves it, the version gate passes once the pinned main
# build is in, and then validate_load_request refuses it as a non-unsloth repo before the
@@ -1403,6 +1420,49 @@ def _restore_gguf_trimmed_dims(model: Any, state_dict: Any) -> Any:
return state_dict
+def _dequantize_gguf_outside_linears(
+ model: Any,
+ dtype: Any,
+ logger: Any = None,
+) -> int:
+ """Dequantise GGUF-packed params outside GGUFLinear (only those dequantise per forward; numpy has no bf16, so BF16
+ stays raw bytes too). Qwen-Image-Layered's BF16 addition_t_embedding otherwise fails the first step with 3072 vs
+ 6144. A few KB, kept dense at ``dtype``. Returns the count."""
+ try:
+ import torch
+ from diffusers.quantizers.gguf.utils import (
+ GGUFLinear,
+ GGUFParameter,
+ dequantize_gguf_tensor,
+ )
+ except Exception: # noqa: BLE001 - no GGUF support, nothing packed to fix
+ return 0
+ named_modules = getattr(model, "named_modules", None)
+ if not callable(named_modules):
+ return 0
+ fixed: list = []
+ for module_name, module in named_modules():
+ if isinstance(module, GGUFLinear):
+ continue
+ for name, param in list(module.named_parameters(recurse = False)):
+ if not isinstance(param, GGUFParameter):
+ continue
+ dense = dequantize_gguf_tensor(param).to(dtype)
+ setattr(
+ module,
+ name,
+ torch.nn.Parameter(dense.as_subclass(torch.Tensor), requires_grad = False),
+ )
+ fixed.append(f"{module_name}.{name}" if module_name else name)
+ if fixed and logger is not None:
+ logger.info(
+ "diffusion.gguf: dequantised %d non-linear parameter(s): %s",
+ len(fixed),
+ ", ".join(fixed[:8]),
+ )
+ return len(fixed)
+
+
def _install_gguf_dim_restore(logger: Any) -> None:
"""Wrap diffusers' meta loader so a GGUF's trimmed dimensions are restored before its shape
check. Patched here rather than in the mapping fn because a GGUF whose tensor names already
@@ -6620,6 +6680,8 @@ class DiffusionBackend:
transformer = transformer_cls.from_single_file(
single_file_path, **sf_kwargs
)
+ if kind == "gguf":
+ _dequantize_gguf_outside_linears(transformer, dtype, logger)
self._raise_if_load_cancelled(_load_token)
if fam.name == KREA2_FAMILY_NAME:
@@ -9544,7 +9606,10 @@ class DiffusionBackend:
"support masks (mask_image)."
)
workflow = "edit"
- init_pil = decode_b64_image(init_image, mode = "RGB")
+ # RGB for the instruction editors; the layered VAE reads the alpha as a fourth channel.
+ init_pil = decode_b64_image(
+ init_image, mode = getattr(fam, "condition_image_mode", "RGB") or "RGB"
+ )
elif requested_workflow == "edit":
if not getattr(fam, "unified_edit", False):
raise ValueError(
@@ -9730,6 +9795,12 @@ class DiffusionBackend:
)
else:
kwargs["guidance_schedule"] = None
+ layer_count = int(getattr(fam, "layer_count", 0) or 0)
+ if layer_count:
+ if "layers" in call_params:
+ kwargs["layers"] = layer_count
+ if "resolution" in call_params:
+ kwargs["resolution"] = int(getattr(fam, "layer_resolution", 640))
if state.family.name == LUMINA2_FAMILY_NAME and "cfg_trunc_ratio" in call_params:
# Lumina 2's card recipe truncates the CFG double-forward to the first quarter
# (cfg_trunc_ratio=0.25); the 1.0 default oversaturates.
@@ -9784,8 +9855,9 @@ class DiffusionBackend:
kwargs["control_mode"] = cn_mode
# Per-forward chunks: the whole job list in ONE forward by default, bounded by an explicit batch_size
- # cap; the OOM backoff below halves a failed chunk.
- chunks = chunk_jobs(jobs, batch_size)
+ # cap; the OOM backoff below halves a failed chunk. Layered: one input per forward (the pipeline's
+ # per-prompt layer stride is only right for one).
+ chunks = [[job] for job in jobs] if layer_count else chunk_jobs(jobs, batch_size)
try:
# The dimensions the forward runs at, not the sliders: img2img / inpaint / upscale / edit take
@@ -9796,22 +9868,26 @@ class DiffusionBackend:
)
guard_batch = _activation_guard_batch(chunks)
guard_target = self._state_device_target(state)
+ guard_condition_pixels = (
+ int(
+ (1 + len(ref_extra))
+ * ref_resolution
+ * ref_resolution
+ * getattr(fam, "condition_pixel_weight", 1.0)
+ )
+ if ref_resolution is not None
+ else 0
+ )
+ if layer_count:
+ # layers + 1 extra canvas-sized frames beside the output-sized one.
+ guard_condition_pixels += (layer_count + 1) * guard_width * guard_height
# past what the measured placement reserved: stream resident groups again for this call
extra_mib = measured_request_extra_mib(
state.pipe,
width = guard_width,
height = guard_height,
batch_size = guard_batch,
- condition_pixels = (
- int(
- (1 + len(ref_extra))
- * ref_resolution
- * ref_resolution
- * getattr(fam, "condition_pixel_weight", 1.0)
- )
- if ref_resolution is not None
- else 0
- ),
+ condition_pixels = guard_condition_pixels,
)
if extra_mib > 0:
restore_resident = release_resident_groups(state.pipe, extra_mib, logger)
@@ -9831,16 +9907,7 @@ class DiffusionBackend:
# resolution" is actionable there; the rest size from the upload alone and get the upload-side
# remedy.
source_driven = source_sized and workflow != "img2img",
- condition_pixels = (
- int(
- (1 + len(ref_extra))
- * ref_resolution
- * ref_resolution
- * getattr(fam, "condition_pixel_weight", 1.0)
- )
- if ref_resolution is not None
- else 0
- ),
+ condition_pixels = guard_condition_pixels,
vae_tile_side = vae_tile_side(getattr(pipe, "vae", None)),
vae_sliced = vae_can_slice(getattr(pipe, "vae", None)),
quadratic_attention = _quadratic_attention(
@@ -10147,8 +10214,14 @@ class DiffusionBackend:
settle_compile_fallback(state, state.pipe, logger)
if cancel.is_set():
raise RuntimeError(DIFFUSION_CANCELLED_MSG)
- images.extend(out)
- per_image_seeds.extend(s for _, s in chunk)
+ if layer_count:
+ # One list of layers per input; each layer is an output image with its input's seed.
+ for (_, s), layers_out in zip(chunk, out):
+ images.extend(layers_out)
+ per_image_seeds.extend(s for _ in layers_out)
+ else:
+ images.extend(out)
+ per_image_seeds.extend(s for _, s in chunk)
chunk_shapes.append(len(chunk))
steps_done[0] += steps
except BaseException:
diff --git a/studio/backend/core/inference/diffusion_auto_policy.py b/studio/backend/core/inference/diffusion_auto_policy.py
index eb2053eb7fa..4de4407e550 100644
--- a/studio/backend/core/inference/diffusion_auto_policy.py
+++ b/studio/backend/core/inference/diffusion_auto_policy.py
@@ -71,6 +71,8 @@ _FAMILY_BF16_GB: dict[str, tuple[float, float, float]] = {
"flux.2-dev": (64.5, 48.0, 0.4),
"qwen-image": (40.9, 16.6, 0.3),
"qwen-image-edit": (40.9, 16.6, 0.3),
+ # Same DiT and Qwen2.5-VL 7B encoder; the RGBA VAE is 0.25 GB.
+ "qwen-image-layered": (40.9, 16.6, 0.3),
# A different architecture, not a refreshed Qwen-Image: 32 single-stream blocks against 60
# dual-stream ones, so the DiT is 14.2 GB rather than 40.9, while the Qwen3-VL 8B encoder is
# LARGER than Qwen-Image's Qwen2.5-VL 7B. Ships bf16, so resident equals on-disk. Read off the
diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.py
index 533e670958c..415cfed2db5 100644
--- a/studio/backend/core/inference/diffusion_families.py
+++ b/studio/backend/core/inference/diffusion_families.py
@@ -105,6 +105,10 @@ class DiffusionFamily:
# True when the text-to-image pipeline also follows edit instructions over ``image`` (Qwen-Image-2.1), at the
# requested size. Never inferred from ``reference``: a reference family is not necessarily trained to edit.
unified_edit: bool = False
+ # Qwen-Image-Layered: RGBA layers per input (each an output image); 0 = not layered.
+ layer_count: int = 0
+ # The pipeline's ``resolution`` area bucket (640 or 1024).
+ layer_resolution: int = 640
# Condition images per call, INCLUDING the init image; overflow is refused, never sliced.
max_condition_images: int = 4
condition_image_mode: str = "RGB"
@@ -378,6 +382,26 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
sd_cpp_sampling_method = "euler",
sd_cpp_flow_shift = 3.0,
),
+ DiffusionFamily(
+ # qwen-image's DiT plus use_additional_t_cond / use_layer3d_rope (read from the base config for a GGUF) and an
+ # RGBA VAE. Listed before qwen-image so the name outranks it.
+ name = "qwen-image-layered",
+ filter_reduction_configs_archs = _REDUCTION_RACE_ARCHS,
+ # ComfyUI's Image to Layers template: ModelSamplingAuraFlow 1, 2 layers, the input scaled to 640.
+ comfy_flow_shift = 1.0,
+ layer_count = 2,
+ layer_resolution = 640,
+ pipeline_class = "QwenImageLayeredPipeline",
+ transformer_class = "QwenImageTransformer2DModel",
+ base_repo = "Qwen/Qwen-Image-Layered",
+ cfg_kwarg = "true_cfg_scale",
+ aliases = ("qwen_image_layered", "qwenimagelayered"),
+ edit = True,
+ max_condition_images = 1,
+ condition_image_mode = "RGBA",
+ # same DiT as qwen-image
+ fp16_incompatible = True,
+ ),
DiffusionFamily(
name = "qwen-image",
filter_reduction_configs_archs = _REDUCTION_RACE_ARCHS,
@@ -723,8 +747,8 @@ def excluded_model_reason(repo_id: str) -> Optional[str]:
return None
-# Editing / inpaint checkpoints share an arch keyword but need a different pipeline + input image. "layered" rejects
-# Qwen-Image-Layered, whose transformer expects an extra input.
+# Editing / inpaint checkpoints share an arch keyword but need a different pipeline + input image. "layered" rejects a
+# layered checkpoint of any family without a layered entry of its own; Qwen-Image-Layered has one, so it matches that.
_EDIT_KEYWORDS = ("edit", "kontext", "inpaint", "layered")
@@ -839,16 +863,28 @@ def detect_family_by_pipeline_index(path: Optional[str]) -> Optional[DiffusionFa
matched family cannot run (``...-layered``) is still refused, so the index only adds models
whose name said nothing, never overrides a name that said no."""
fam = detect_family_by_pipeline_class(pipeline_class_from_index(path))
- if fam is None:
+ if fam is None or _index_family_ruled_out(fam, path):
return None
+ return fam
+
+
+def _index_family_ruled_out(fam: DiffusionFamily, path: Optional[str]) -> bool:
+ """True when the directory's NAME carries a variant keyword the index's family cannot run."""
basename = re.split(r"[/\\]+", str(path).lower())[-1]
matched_tokens = (fam.name, *fam.aliases)
- if any(
+ return any(
_token_in_needle(kw, basename) and not any(kw in tok for tok in matched_tokens)
for kw in _EDIT_KEYWORDS
- ):
- return None
- return fam
+ )
+
+
+def pipeline_index_contradicts_name(path: Optional[str]) -> bool:
+ """True when a local pipeline's ``model_index.json`` declares a family its directory name rules out (a
+ ``qwen-image-layered`` folder holding a plain ``QwenImagePipeline``). The name-based fallback must not answer
+ for such a directory: the name would pick the variant's family and the loader would then build that pipeline
+ over a checkpoint saved as another. The listing and the loader both refuse it."""
+ fam = detect_family_by_pipeline_class(pipeline_class_from_index(path))
+ return fam is not None and _index_family_ruled_out(fam, path)
def detect_family_for_pick(
@@ -874,6 +910,8 @@ def detect_family_for_pick(
# directory. Remote picks are unaffected: with no local index this is None and the name-based paths below run
# as before.
fam = detect_family_by_pipeline_index(repo_id)
+ if fam is None and pipeline_index_contradicts_name(repo_id):
+ return None
if fam is None:
fam = detect_family(repo_id, override)
if fam is None and gguf_filename and not override:
@@ -1201,6 +1239,10 @@ _GENERATION_DEFAULTS: tuple[tuple[str, int, float], ...] = (
("qwen-image-21", 25, 1.0),
("qwen_image_21", 25, 1.0),
("qwenimage21", 25, 1.0),
+ # ComfyUI's Image to Layers template: 20 steps, cfg 2.5.
+ ("qwen-image-layered", 20, 2.5),
+ ("qwen_image_layered", 20, 2.5),
+ ("qwenimagelayered", 20, 2.5),
# 2509 template: 20 / 4; the generic key is the 2511 recipe (the family base).
("qwen-image-edit-2509", 20, 4.0),
("qwen-image-edit", 40, 4.0),
@@ -1350,6 +1392,8 @@ _PIPELINE_MIN_DIFFUSERS: dict[str, str] = {
"Flux2KleinPipeline": "0.37.0",
"ZImageInpaintPipeline": "0.37.0",
"LTX2Pipeline": "0.37.0",
+ # Absent from the 0.36.0 wheel's diffusers/__init__.py, exported by 0.37.0's.
+ "QwenImageLayeredPipeline": "0.37.0",
"Flux2KleinInpaintPipeline": "0.38.0",
"Ideogram4Pipeline": "0.39.0",
# Qwen-Image-2.1 merged upstream on 2026-09-18, four weeks after 0.40.0 was cut, so 0.41.0 is
diff --git a/studio/backend/core/inference/diffusion_memory.py b/studio/backend/core/inference/diffusion_memory.py
index 19503fe20d3..c0f15af8689 100644
--- a/studio/backend/core/inference/diffusion_memory.py
+++ b/studio/backend/core/inference/diffusion_memory.py
@@ -1003,6 +1003,11 @@ def estimate_safetensors_dense_mib(
return storage_mib
+# qwen-image-layered's layer_count / layer_resolution (pinned equal by a test; no families import here).
+_QWEN_LAYERED_LAYERS = 2
+_QWEN_LAYERED_CANVAS = 640
+
+
def estimate_image_runtime_mib(
*,
width: Optional[int],
@@ -1018,6 +1023,10 @@ def estimate_image_runtime_mib(
h = max(64, int(height or DEFAULT_IMAGE_HEIGHT))
batch = max(1, int(batch_size or 1))
cond = max(0, int(condition_pixels or 0))
+ if width is None and height is None and "qwen-image-layered" in (family or "").lower():
+ # Planning call: reserve what the generation guard charges a decomposition, not one 1024x1024 frame.
+ w = h = _QWEN_LAYERED_CANVAS
+ cond = (_QWEN_LAYERED_LAYERS + 1) * w * h
pixel_scale = ((w * h + cond) * batch) / float(DEFAULT_IMAGE_WIDTH * DEFAULT_IMAGE_HEIGHT)
return max(1024, int(8192 * max(0.25, pixel_scale) * _family_activation_multiplier(family)))
diff --git a/studio/backend/core/inference/diffusion_precision.py b/studio/backend/core/inference/diffusion_precision.py
index 61686b20a57..2d0d60cf9b3 100644
--- a/studio/backend/core/inference/diffusion_precision.py
+++ b/studio/backend/core/inference/diffusion_precision.py
@@ -59,6 +59,7 @@ _TEXT_ENCODER_ATTRS = ("text_encoder", "text_encoder_2", "text_encoder_3")
_TE_INT8_SKIP: dict[str, tuple[int, int]] = {
"qwen-image": (6, 6),
"qwen-image-edit": (6, 6),
+ "qwen-image-layered": (6, 6),
"flux.2-dev": (3, 0),
}
diff --git a/studio/backend/core/inference/diffusion_transformer_quant.py b/studio/backend/core/inference/diffusion_transformer_quant.py
index d81687d816f..394371eda4c 100644
--- a/studio/backend/core/inference/diffusion_transformer_quant.py
+++ b/studio/backend/core/inference/diffusion_transformer_quant.py
@@ -135,6 +135,7 @@ _LTX2_INT8_EXCLUDES = ("audio", "av_cross_attn", "adaln")
_INT8_FAMILY_EXCLUDE_NAME_TOKENS: dict[str, tuple[str, ...]] = {
"qwen-image": _QWENIMAGE_INT8_EXCLUDES,
"qwen-image-edit": _QWENIMAGE_INT8_EXCLUDES, # same DiT class + unpadded text stream
+ "qwen-image-layered": _QWENIMAGE_INT8_EXCLUDES, # same DiT class + unpadded text stream
# 2.1 is a 32-block SINGLE-stream DiT: no add_* projections, no txt_mlp, so the 20B MMDiT's
# exclusion list does not apply and this one was measured rather than inherited. ``txt_in`` is
# here as a QUALITY lever, not the small-M crash guard it is on qwen-image: all four policy arms
@@ -435,6 +436,7 @@ _AUTO_LADDER: tuple[tuple[tuple[int, int], tuple[str, ...]], ...] = (
_FAMILY_SCHEME_DENY: dict[str, frozenset[str]] = {
"qwen-image": frozenset({TQ_MXFP8, TQ_NVFP4}),
"qwen-image-edit": frozenset({TQ_MXFP8, TQ_NVFP4}), # same DiT
+ "qwen-image-layered": frozenset({TQ_MXFP8, TQ_NVFP4}), # same DiT
}
diff --git a/studio/backend/hub/services/models/catalog_classification.py b/studio/backend/hub/services/models/catalog_classification.py
index f012fca3863..5706eaa467f 100644
--- a/studio/backend/hub/services/models/catalog_classification.py
+++ b/studio/backend/hub/services/models/catalog_classification.py
@@ -528,8 +528,14 @@ def _local_model_task(model) -> Optional[str]:
pass
try:
from core.inference.diffusion_engine_router import family_buildable_here
- from core.inference.diffusion_families import detect_family, detect_family_by_pipeline_index
+ from core.inference.diffusion_families import (
+ detect_family,
+ detect_family_by_pipeline_index,
+ pipeline_index_contradicts_name,
+ )
+ if pipeline_index_contradicts_name(path):
+ return None
families = (
detect_family_by_pipeline_index(path),
*(detect_family(needle) for needle in _local_family_needles(model)),
diff --git a/studio/backend/tests/test_diffusion_backend.py b/studio/backend/tests/test_diffusion_backend.py
index 7cad898a5dc..034c180c24f 100644
--- a/studio/backend/tests/test_diffusion_backend.py
+++ b/studio/backend/tests/test_diffusion_backend.py
@@ -140,8 +140,9 @@ def test_detect_family_matches_reject_and_alias_by_segment():
# Supported edit families still resolve (edit / kontext are whole tokens).
assert detect_family("unsloth/Qwen-Image-Edit-2511-GGUF").name == "qwen-image-edit"
assert detect_family("unsloth/FLUX.1-Kontext-dev-GGUF").name == "flux.1-kontext"
+ assert detect_family("unsloth/Qwen-Image-Layered-GGUF").name == "qwen-image-layered"
# Unsupported variants sharing only a base arch keyword still reject.
- assert detect_family("unsloth/Qwen-Image-Layered-GGUF") is None
+ assert detect_family("unsloth/FLUX.1-dev-Layered-GGUF") is None
assert detect_family("unsloth/Qwen-Image-2512-Inpaint") is None
@@ -153,7 +154,10 @@ def test_detect_family_edit_keyword_scoped_to_basename():
assert detect_family_for_pick("/models/edit", "Z-Image-Turbo-Q4.gguf").name == "z-image"
assert detect_family_for_pick("/models/inpaint", "qwen-image-2512-Q4.gguf").name == "qwen-image"
# A genuinely unsupported variant keyword in the FILENAME still rejects.
- assert detect_family_for_pick("/models/misc", "Qwen-Image-Layered-Q4.gguf") is None
+ assert detect_family_for_pick("/models/misc", "Z-Image-Turbo-Layered-Q4.gguf") is None
+ assert detect_family_for_pick("/models/misc", "Qwen-Image-Layered-Q4.gguf").name == (
+ "qwen-image-layered"
+ )
def test_detect_family_override():
@@ -2363,10 +2367,15 @@ def test_resolve_base_repo_maps_a_mirrored_card_tag_back_to_the_vendor_id(monkey
)
-def test_detect_family_rejects_layered():
- # Qwen-Image-Layered needs a dedicated pipeline (additional_t_cond), so reject at load, not at the first step.
- assert detect_family("unsloth/Qwen-Image-Layered-GGUF") is None
- assert detect_family("unsloth/qwen_image_layered") is None
+def test_detect_family_routes_layered_to_its_own_pipeline():
+ # Qwen-Image-Layered needs a dedicated pipeline (additional_t_cond), so it resolves to its own family rather than
+ # to qwen-image; a layered variant of a family without one is still rejected at load.
+ assert (
+ detect_family("unsloth/Qwen-Image-Layered-GGUF").pipeline_class
+ == "QwenImageLayeredPipeline"
+ )
+ assert detect_family("unsloth/qwen_image_layered").name == "qwen-image-layered"
+ assert detect_family("unsloth/FLUX.1-Layered") is None
def test_failed_load_rolls_back_eager_patches(fake_runtime, tmp_path, monkeypatch):
diff --git a/studio/backend/tests/test_diffusion_qwen_layered.py b/studio/backend/tests/test_diffusion_qwen_layered.py
new file mode 100644
index 00000000000..017c140e55c
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_qwen_layered.py
@@ -0,0 +1,321 @@
+# 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-Layered on the diffusers engine: detection of the GGUF and full repos, the GGUF
+transformer's config source, the decomposition call (layers, resolution bucket, true CFG, RGBA
+input) and the flattening of the returned RGBA layers into output images, against the real
+generate() with a pipeline double whose signature matches QwenImageLayeredPipeline's."""
+
+from __future__ import annotations
+
+import base64
+import io
+import types
+
+import pytest
+from PIL import Image
+
+from core.inference.diffusion import (
+ DiffusionBackend,
+ _compile_shape_dims,
+ _family_workflows,
+ _is_trusted_diffusion_repo,
+)
+from core.inference.diffusion_families import (
+ comfy_flow_shift_for,
+ default_generation_params,
+ detect_family,
+ detect_family_for_pick,
+)
+
+from .test_diffusion_backend import ( # noqa: F401
+ _FakePipe,
+ _FakeTransformer,
+ _load_into,
+ fake_runtime,
+)
+
+_LAYER_COLOURS = ((200, 10, 10, 255), (10, 200, 10, 0), (10, 10, 200, 128), (9, 9, 9, 9))
+
+
+class _FakeLayeredPipe(_FakePipe):
+ """QwenImageLayeredPipeline's call signature: no width / height, ``layers`` and ``resolution``,
+ and one LIST of RGBA layers per input in ``images``."""
+
+ calls: list = []
+
+ def __call__(
+ self,
+ image = None,
+ prompt = None,
+ negative_prompt = None,
+ true_cfg_scale = 4.0,
+ layers = 4,
+ num_inference_steps = 50,
+ sigmas = None,
+ guidance_scale = None,
+ num_images_per_prompt = 1,
+ generator = None,
+ latents = None,
+ output_type = "pil",
+ return_dict = True,
+ attention_kwargs = None,
+ callback_on_step_end = None,
+ callback_on_step_end_tensor_inputs = ("latents",),
+ max_sequence_length = 512,
+ resolution = 640,
+ cfg_normalize = False,
+ use_en_prompt = False,
+ ):
+ self.last_kwargs = {
+ "image": image,
+ "prompt": prompt,
+ "negative_prompt": negative_prompt,
+ "true_cfg_scale": true_cfg_scale,
+ "layers": layers,
+ "num_inference_steps": num_inference_steps,
+ "num_images_per_prompt": num_images_per_prompt,
+ "generator": generator,
+ "resolution": resolution,
+ }
+ _FakeLayeredPipe.calls.append(self.last_kwargs)
+ per_input = [
+ [Image.new("RGBA", (32, 32), _LAYER_COLOURS[i % 4]) for i in range(layers)]
+ for _ in range(num_images_per_prompt)
+ ]
+ return types.SimpleNamespace(images = per_input)
+
+
+class _FakeLayeredPipeline:
+ @classmethod
+ def from_pretrained(cls, base, **kwargs):
+ _FakeLayeredPipeline.base = base
+ return _FakeLayeredPipe()
+
+
+def _png(size = (96, 64), color = (120, 30, 30, 77)) -> str:
+ buf = io.BytesIO()
+ Image.new("RGBA", size, color).save(buf, format = "PNG")
+ return base64.b64encode(buf.getvalue()).decode()
+
+
+def layered(fake_runtime, tmp_path):
+ import diffusers
+
+ diffusers.QwenImageLayeredPipeline = _FakeLayeredPipeline
+ diffusers.QwenImageTransformer2DModel = _FakeTransformer
+ _FakeLayeredPipe.calls = []
+ (tmp_path / "qwen-image-layered-UD-Q4_K_XL.gguf").write_bytes(b"x")
+ backend = DiffusionBackend()
+ _load_into(
+ backend,
+ tmp_path,
+ gguf_filename = "qwen-image-layered-UD-Q4_K_XL.gguf",
+ base_repo = "Qwen/Qwen-Image-Layered",
+ family_override = None,
+ )
+ return backend
+
+
+ "repo_id",
+ [
+ "unsloth/Qwen-Image-Layered-GGUF",
+ "Qwen/Qwen-Image-Layered",
+ "unsloth/qwen_image_layered",
+ "/models/qwen-image-layered-UD-Q4_K_XL.gguf",
+ ],
+)
+def test_layered_ids_resolve_to_their_own_family(repo_id):
+ fam = detect_family(repo_id)
+ assert fam is not None and fam.name == "qwen-image-layered"
+ assert fam.pipeline_class == "QwenImageLayeredPipeline"
+ assert fam.transformer_class == "QwenImageTransformer2DModel"
+ assert fam.base_repo == "Qwen/Qwen-Image-Layered"
+
+
+def test_layered_filename_in_a_neutral_folder_resolves():
+ fam = detect_family_for_pick("/models/misc", "qwen-image-layered-BF16.gguf")
+ assert fam is not None and fam.name == "qwen-image-layered"
+
+
+def test_neighbouring_families_keep_their_detection():
+ assert detect_family("unsloth/Qwen-Image-GGUF").name == "qwen-image"
+ assert detect_family("unsloth/Qwen-Image-2512-GGUF").name == "qwen-image"
+ assert detect_family("unsloth/Qwen-Image-Edit-2511-GGUF").name == "qwen-image-edit"
+ assert detect_family("unsloth/Qwen-Image-2.1-GGUF").name == "qwen-image-2.1"
+ # A layered or inpaint variant of a family with no entry of its own is still refused.
+ assert detect_family("unsloth/FLUX.1-dev-Layered-GGUF") is None
+ assert detect_family("unsloth/Qwen-Image-2512-Inpaint") is None
+ assert detect_family_for_pick("/models/misc", "z-image-layered-Q4.gguf") is None
+
+
+def test_layered_family_contract():
+ fam = detect_family("unsloth/Qwen-Image-Layered-GGUF")
+ # Image in, layers out: no text-to-image tab.
+ assert fam.edit is True and _family_workflows(fam) == ["edit"]
+ assert fam.condition_image_mode == "RGBA"
+ assert fam.cfg_kwarg == "true_cfg_scale"
+ # ComfyUI's Image to Layers template: 20 steps, cfg 2.5, ModelSamplingAuraFlow 1, 2 layers at 640.
+ assert (fam.layer_count, fam.layer_resolution) == (2, 640)
+ assert comfy_flow_shift_for(fam, "unsloth/Qwen-Image-Layered-GGUF") == 1.0
+ for name in (
+ "unsloth/Qwen-Image-Layered-GGUF",
+ "Qwen/Qwen-Image-Layered",
+ "local/qwen_image_layered",
+ "local/qwenimagelayered-q4",
+ ):
+ assert default_generation_params(name) == (20, 2.5)
+ # Families without a layered pipeline stay at 0.
+ assert detect_family("unsloth/Qwen-Image-Edit-2511-GGUF").layer_count == 0
+ # The full repo is an allowed non-GGUF base (and the GGUF's base_model tag).
+ assert _is_trusted_diffusion_repo("Qwen/Qwen-Image-Layered")
+
+
+def test_gguf_transformer_reads_the_layered_config(layered):
+ assert layered._state.family.name == "qwen-image-layered"
+ # The GGUF supplies weights only; the layered transformer config (additional t cond, layer3d RoPE) comes from the
+ # base, and so do the RGBA VAE and the pipeline.
+ assert _FakeTransformer.last["config"] == "Qwen/Qwen-Image-Layered"
+ assert _FakeTransformer.last["subfolder"] == "transformer"
+ assert _FakeTransformer.last["path"].endswith("qwen-image-layered-UD-Q4_K_XL.gguf")
+ assert _FakeLayeredPipeline.base == "Qwen/Qwen-Image-Layered"
+ assert layered.status()["workflows"] == ["edit"]
+
+
+def test_decomposition_call_and_layer_outputs(layered):
+ out = layered.generate(
+ prompt = "a cup on a table",
+ steps = 20,
+ guidance = 2.5,
+ seed = 7,
+ init_image = _png(color = (120, 30, 30, 77)),
+ )
+ call = layered._state.pipe.last_kwargs
+ assert call["layers"] == 2 and call["resolution"] == 640
+ assert call["true_cfg_scale"] == 2.5 and call["num_inference_steps"] == 20
+ # True CFG needs a negative present; Studio sends the empty one, as ComfyUI encodes.
+ assert call["negative_prompt"] == ""
+ # The input keeps its alpha: the layered VAE encodes 4 channels.
+ assert call["image"].mode == "RGBA" and call["image"].getpixel((0, 0)) == (120, 30, 30, 77)
+ # Each RGBA layer is its own output image, with the decomposition's seed.
+ assert [im.mode for im in out["images"]] == ["RGBA", "RGBA"]
+ assert [im.getpixel((0, 0)) for im in out["images"]] == list(_LAYER_COLOURS[:2])
+ assert out["seeds"] == [7, 7] and out["seed"] == 7
+ assert out["workflow"] == "edit"
+
+
+def test_seed_batch_runs_one_decomposition_per_forward(layered):
+ out = layered.generate(
+ prompt = "a cup on a table",
+ steps = 4,
+ guidance = 2.5,
+ seeds = [3, 9],
+ init_image = _png(),
+ )
+ # The pipeline's per-prompt grouping is only right for one input, so each seed is its own call.
+ assert [c["num_images_per_prompt"] for c in _FakeLayeredPipe.calls] == [1, 1]
+ assert len(out["images"]) == 4
+ assert out["seeds"] == [3, 3, 9, 9]
+
+
+def test_layered_needs_an_input_image(layered):
+ with pytest.raises(ValueError, match = "input image"):
+ layered.generate(prompt = "no image", steps = 4, guidance = 2.5, seed = 1)
+
+
+ "size,expected",
+ [((96, 64), (768, 512)), ((1000, 500), (896, 448)), ((640, 640), (640, 640))],
+)
+def test_registered_shape_is_the_decomposition_canvas(size, expected):
+ fam = detect_family("unsloth/Qwen-Image-Layered-GGUF")
+ src = Image.new("RGBA", size)
+ # 640 x 640 area at the input's aspect ratio on the 32 px grid, as the pipeline sizes it.
+ assert _compile_shape_dims("edit", src, 1024, 1024, fam) == expected
+ # Other edit-only families still size from the source.
+ kontext = detect_family("black-forest-labs/FLUX.1-Kontext-dev")
+ assert _compile_shape_dims("edit", src, 1024, 1024, kontext) == size
+
+
+def _saved(root, class_name):
+ import json
+
+ root.mkdir(parents = True)
+ (root / "model_index.json").write_text(json.dumps({"_class_name": class_name}))
+ return str(root)
+
+
+def test_saved_layered_pipeline_resolves_and_a_contradicting_one_is_refused(tmp_path):
+ # A real saved Qwen-Image-Layered declares its own class: the index and the name agree.
+ real = _saved(tmp_path / "qwen-image-layered", "QwenImageLayeredPipeline")
+ assert detect_family_for_pick(real).name == "qwen-image-layered"
+ # An opaque folder name: the index alone answers.
+ opaque = _saved(tmp_path / "0f3d1a2b4c5d", "QwenImageLayeredPipeline")
+ assert detect_family_for_pick(opaque).name == "qwen-image-layered"
+ # A layered NAME over a plain QwenImagePipeline: the name must not route it to the layered pipeline.
+ wrong = _saved(tmp_path / "x" / "qwen-image-layered", "QwenImagePipeline")
+ assert detect_family_for_pick(wrong) is None
+
+
+def test_gguf_packed_embedding_is_dequantised_and_linears_are_left_packed():
+ torch = pytest.importorskip("torch")
+ gguf = pytest.importorskip("gguf")
+ utils = pytest.importorskip("diffusers.quantizers.gguf.utils")
+ from core.inference.diffusion import _dequantize_gguf_outside_linears
+
+ # nn.Embedding(2, 8) stored BF16, as the public Qwen-Image-Layered GGUFs store addition_t_embedding: GGUF keeps
+ # BF16 as raw bytes, (2, 16) uint8 for a (2, 8) table.
+ table = torch.arange(16, dtype = torch.float32).reshape(2, 8).to(torch.bfloat16)
+ raw = table.view(torch.uint8)
+ model = torch.nn.Module()
+ model.embed = torch.nn.Embedding(2, 8)
+ model.embed.weight = utils.GGUFParameter(raw, quant_type = gguf.GGMLQuantizationType.BF16)
+ linear = utils.GGUFLinear(8, 8, bias = False, compute_dtype = torch.bfloat16)
+ linear.weight = utils.GGUFParameter(
+ torch.zeros(8, 16, dtype = torch.uint8), quant_type = gguf.GGMLQuantizationType.BF16
+ )
+ model.proj = linear
+ # Before: the embedding lookup returns raw bytes, twice as wide as the model dimension.
+ assert model.embed(torch.tensor([1])).shape[-1] == 16
+
+ assert _dequantize_gguf_outside_linears(model, torch.bfloat16) == 1
+ assert type(model.embed.weight) is torch.nn.Parameter
+ assert model.embed.weight.dtype == torch.bfloat16 and tuple(model.embed.weight.shape) == (2, 8)
+ assert torch.equal(model.embed(torch.tensor([1]))[0], table[1])
+ # The quantizer's own linears dequantise per forward and stay packed.
+ assert isinstance(model.proj.weight, utils.GGUFParameter)
+ # Nothing packed left: a second pass is a no-op.
+ assert _dequantize_gguf_outside_linears(model, torch.bfloat16) == 0
+
+
+def test_load_planning_reserves_what_the_decomposition_guard_charges():
+ # The guard charges layers + 1 extra canvas frames; a load planned for one 1024x1024 frame then refused every
+ # default render on a card that had to offload to fit (no calibrated placement to release groups from).
+ from core.inference import diffusion_memory as dm
+
+ fam = detect_family("unsloth/Qwen-Image-Layered-GGUF")
+ assert (dm._QWEN_LAYERED_LAYERS, dm._QWEN_LAYERED_CANVAS) == (
+ fam.layer_count,
+ fam.layer_resolution,
+ )
+ hint = "qwen-image-layered qwen-image-layered-Q4_K_M.gguf unsloth/Qwen-Image-Layered-GGUF"
+ side = fam.layer_resolution
+ extra = (fam.layer_count + 1) * side * side
+ planned = dm.estimate_image_runtime_mib(width = None, height = None, family = hint)
+ assert planned == dm.estimate_image_runtime_mib(
+ width = side, height = side, family = hint, condition_pixels = extra
+ )
+ # Free memory that covers only the planned headroom (an offloaded load): the default render still runs.
+ verdict = dm.image_activation_verdict(
+ device_memory = dm.DeviceMemory("cuda", "cuda", "discrete_vram", 10000, 24576),
+ width = side,
+ height = side,
+ family = hint,
+ source_driven = True,
+ condition_pixels = extra,
+ )
+ assert verdict.action == dm.ACTIVATION_RUN
+ # Other families' planning is untouched.
+ assert dm.estimate_image_runtime_mib(width = None, height = None, family = "qwen-image") == 8192
diff --git a/studio/frontend/src/features/images/image-generation-defaults.ts b/studio/frontend/src/features/images/image-generation-defaults.ts
index fc8829ffec2..75d8819311f 100644
--- a/studio/frontend/src/features/images/image-generation-defaults.ts
+++ b/studio/frontend/src/features/images/image-generation-defaults.ts
@@ -29,6 +29,10 @@ const MODEL_DEFAULTS: Array<{
{ match: "qwen-image-21", steps: 25, guidance: 1 },
{ match: "qwen_image_21", steps: 25, guidance: 1 },
{ match: "qwenimage21", steps: 25, guidance: 1 },
+ // ComfyUI Image to Layers template, before the generic key.
+ { match: "qwen-image-layered", steps: 20, guidance: 2.5 },
+ { match: "qwen_image_layered", steps: 20, guidance: 2.5 },
+ { match: "qwenimagelayered", steps: 20, guidance: 2.5 },
{ match: "qwen-image-edit-2509", steps: 20, guidance: 4 },
{ match: "qwen-image-edit", steps: 40, guidance: 4 },
{ match: "qwen-image-2512", steps: 50, guidance: 4 },
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/family-override.ts b/studio/frontend/src/features/model-picker/components/model-selector/family-override.ts
index fb08d0e3411..007624e06b5 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/family-override.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/family-override.ts
@@ -13,6 +13,7 @@ const LABELS: Readonly<Record<string, string>> = {
"qwen-image": "Qwen Image",
"qwen-image-2.1": "Qwen Image 2.1",
"qwen-image-edit": "Qwen Image Edit",
+ "qwen-image-layered": "Qwen Image Layered",
"z-image": "Z-Image",
"krea-2": "Krea 2",
"lumina-2": "Lumina 2",
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx b/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx
index a9baaba9d5f..45eea6db18b 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx
+++ b/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx
@@ -2685,8 +2685,14 @@ function mediaPageForTask(
// task itself must stay, since FLUX.2-klein carries it too.
const IMAGE_EDIT_KEYWORDS = ["edit", "kontext", "inpaint", "layered"] as const;
// Editing families the backend now SUPPORTS: not hidden despite the edit keyword. Mirrors the
-// backend's qwen-image-edit family.
-const SUPPORTED_EDIT_KEYWORDS = ["qwen-image-edit", "kontext"] as const;
+// backend's qwen-image-edit, flux.1-kontext and qwen-image-layered families.
+const SUPPORTED_EDIT_KEYWORDS = [
+ "qwen-image-edit",
+ "kontext",
+ "qwen-image-layered",
+ "qwen_image_layered",
+ "qwenimagelayered",
+] as const;
// Match a keyword as a whole path/name segment, not a raw substring, so "edit" does not hide
// ".../edited/...". Keywords are [a-z-] literals, so no escaping. Mirrors _token_in_needle.
function idHasSegment(id: string, keyword: string): boolean {
diff --git a/studio/frontend/tests/image-generation-defaults.test.ts b/studio/frontend/tests/image-generation-defaults.test.ts
index 2bf0db66152..529f46a8371 100644
--- a/studio/frontend/tests/image-generation-defaults.test.ts
+++ b/studio/frontend/tests/image-generation-defaults.test.ts
@@ -178,3 +178,13 @@ test("defaults follow ComfyUI's official templates for the same model", () => {
assert.deepEqual(defaultsFor(id), want, id);
}
});
+
+test("every Qwen-Image-Layered spelling the backend accepts gets its 20 / 2.5 recipe", () => {
+ for (const id of [
+ "unsloth/Qwen-Image-Layered-GGUF",
+ "local/qwen_image_layered",
+ "local/qwenimagelayered-q4",
+ ]) {
+ assert.deepEqual(defaultsFor(id), { steps: 20, guidance: 2.5 }, id);
+ }
+});