Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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 shapecheck. 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 callextra_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] += stepsexcept BaseException:diff --git a/studio/backend/core/inference/diffusion_auto_policy.py b/studio/backend/core/inference/diffusion_auto_policy.pyindex 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 thediff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.pyindex 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 = 4condition_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[DiffusionFamatched family cannot run (``...-layered``) is still refused, so the index only adds modelswhose 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 Noneif 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 isdiff --git a/studio/backend/core/inference/diffusion_memory.py b/studio/backend/core/inference/diffusion_memory.pyindex 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 * hpixel_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.pyindex 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.pyindex 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.pyindex 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]:passtry: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 Nonefamilies = (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.pyindex 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 Noneassert 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 Nonedef 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.pynew file mode 100644index 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") == 8192diff --git a/studio/frontend/src/features/images/image-generation-defaults.ts b/studio/frontend/src/features/images/image-generation-defaults.tsindex 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.tsindex 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.tsxindex 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.tsindex 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);+ }+});