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: support Qwen-Image-2.1-Turbo with its 8-step sampling schedule (#13159)

oobaboogaa2915dede449
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index d0f6866f3d2..bd164746d5e 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -53,6 +53,7 @@ from .diffusion_content import (
)
from .diffusion_gguf_pipeline import load_whole_pipeline_gguf, whole_pipeline_gguf_resident_mib
from .diffusion_families import (
+ named_variant_base,
DIFFUSION_CANCELLED_MSG,
DIFFUSION_NOT_LOADED_MSG,
IDEOGRAM4_FAMILY_NAME,
@@ -70,6 +71,7 @@ from .diffusion_families import (
cache_holds_files,
comfy_flow_shift_for,
default_generation_params,
+ generation_params_with_grid,
detect_family_for_pick,
excluded_model_reason,
prefer_ungated_mirror,
@@ -270,7 +272,13 @@ from .diffusion_precision import (
)
from .diffusion_te_prequant import supplied_component_pipe_kwargs, te_prequant_pipe_kwargs
from .diffusion_fast_load import start_load_prefetch, stop_prefetch, te_precast_components
-from .diffusion_flow_shift import apply_comfy_flow_shift
+from .diffusion_flow_shift import (
+ SAMPLE_SIGMAS_KEY,
+ apply_comfy_flow_shift,
+ install_sample_sigmas,
+ pipe_sample_sigmas,
+ sample_sigmas_for_steps,
+)
from .diffusion_single_file_converters import (
CONVERTERS as _ORIGINAL_LAYOUT_CONVERTERS,
load_original_layout_transformer,
@@ -836,6 +844,7 @@ _TRUSTED_NON_GGUF_REPOS = frozenset(
# build is in, and then validate_load_request refuses it as a non-unsloth repo before the
# pipeline is ever built.
"qwen/qwen-image-2.1",
+ "qwen/qwen-image-2.1-turbo",
# Krea 2: assembled per-component. Turbo = inference; Raw = the LoRA training base.
"krea/krea-2-turbo",
"krea/krea-2-raw",
@@ -1127,7 +1136,9 @@ def _with_supplied_components(load: Callable[..., dict]) -> Callable[..., dict]:
vae_file = vae_file,
)
hf_token = (kwargs.get("hf_token") or "").strip() or None
- base = _resolve_base_repo(repo_id, kwargs.get("base_repo"), fam, hf_token)
+ base = _resolve_base_repo(
+ repo_id, kwargs.get("base_repo"), fam, hf_token, kwargs.get("gguf_filename")
+ )
overrides = self._plan_component_overrides(
fam,
repo_id,
@@ -1565,14 +1576,33 @@ def _restore_gguf_trimmed_dims(model: Any, state_dict: Any) -> Any:
return state_dict
+def _model_index_sample_sigmas(base: str, base_local_dir: Optional[str]) -> Any:
+ """``sample_sigmas`` from the model_index.json the pipeline was just built from, never from the network."""
+ from .diffusion_comfy_components import read_model_index
+
+ try:
+ index = read_model_index(
+ base,
+ base_local_dir = base_local_dir,
+ local_files_only = True,
+ cache_dir = hub_cache_dir(),
+ )
+ except Exception: # noqa: BLE001 - an uncached or unreadable index carries no grid
+ return None
+ return index.get(SAMPLE_SIGMAS_KEY) if isinstance(index, dict) else None
+
+
def _generation_defaults_for(
- repo_id: Optional[str], gguf_filename: Optional[str], base_repo: Optional[str]
+ repo_id: Optional[str],
+ gguf_filename: Optional[str],
+ base_repo: Optional[str],
+ grid: Optional[tuple[float, ...]] = None,
) -> Optional[dict[str, float]]:
"""The (steps, guidance) the OpenAI route renders this load with, header variant before base (FLUX.1's base is
schnell), so the Images form can match it."""
try:
- steps, guidance = default_generation_params(
- gguf_filename, content_variant_hint(repo_id, gguf_filename), repo_id, base_repo
+ steps, guidance = generation_params_with_grid(
+ grid, gguf_filename, content_variant_hint(repo_id, gguf_filename), repo_id, base_repo
)
except Exception: # noqa: BLE001 - status must not fail on a recipe lookup
return None
@@ -3356,7 +3386,7 @@ class DiffusionBackend:
if kind == "pipeline":
base = repo_id # the full pipeline IS the repo
else:
- base = _resolve_base_repo(repo_id, base_repo, fam, hf_token)
+ base = _resolve_base_repo(repo_id, base_repo, fam, hf_token, gguf_filename)
# Probe the repo the load will FETCH from: refusing the upstream id would reject the gated picks the ungated
# mirror rescues, and the swap is pure, so it decides the same here as on the load thread. Only the raise
# matters; _run_load recomputes the excused snapshot.
@@ -3527,7 +3557,11 @@ class DiffusionBackend:
base = kwargs["repo_id"]
else:
base = _resolve_base_repo(
- kwargs["repo_id"], kwargs.get("base_repo"), fam, kwargs.get("hf_token")
+ kwargs["repo_id"],
+ kwargs.get("base_repo"),
+ fam,
+ kwargs.get("hf_token"),
+ kwargs.get("gguf_filename"),
)
kwargs["base_repo"] = base
# Claimed before a byte moves, so the cache-delete guard sees a Hub component repo.
@@ -4667,7 +4701,7 @@ class DiffusionBackend:
# plan no work.
return {"entries": [], "total_bytes": 0, "required_bytes": 0, "checkpoint_bytes": 0}
else:
- base = _resolve_base_repo(repo_id, base_repo, fam, hf_token)
+ base = _resolve_base_repo(repo_id, base_repo, fam, hf_token, gguf_filename)
# Reported, not raised. The images page falls back to /images/load on ANY plan failure, so a 400 here would
# start the very download this is meant to prevent; carried in the envelope instead, the picker can refuse at
# SELECTION time. Metadata only, and None whenever nothing is known to be wrong. The speech verdict belongs
@@ -5849,7 +5883,9 @@ class DiffusionBackend:
)
# A full pipeline is its own base; single-file kinds resolve the companion base repo.
base = (
- repo_id if kind == "pipeline" else _resolve_base_repo(repo_id, base_repo, fam, hf_token)
+ repo_id
+ if kind == "pipeline"
+ else _resolve_base_repo(repo_id, base_repo, fam, hf_token, gguf_filename)
)
# ``base`` stays the UPSTREAM id every report and table lookup keys on; ``fetch_base`` is the only id handed
# to something that downloads. One decision per load, so nothing stages one repo and assembles from the other.
@@ -7830,19 +7866,22 @@ 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,
- content_variant_hint(repo_id, gguf_filename),
- repo_id,
- display_repo_id,
- base,
- ),
- logger,
- )
+ # A shipped grid was tuned on the shipped scheduler: no ComfyUI shift.
+ raw_grid = _model_index_sample_sigmas(fetch_base, _base_local_dir)
+ if install_sample_sigmas(pipe, raw_grid, logger) is None:
+ # Before from_pipe copies the scheduler.
+ apply_comfy_flow_shift(
+ pipe,
+ comfy_flow_shift_for(
+ fam,
+ gguf_filename,
+ content_variant_hint(repo_id, gguf_filename),
+ repo_id,
+ display_repo_id,
+ base,
+ ),
+ logger,
+ )
# Before the speed optims, so the fused batched tile decode does not replace it.
try:
install_wide_vae_tiles(getattr(pipe, "vae", None), logger)
@@ -10516,6 +10555,10 @@ class DiffusionBackend:
# Most pipelines use "guidance_scale"; Qwen-Image uses "true_cfg_scale".
state.family.cfg_kwarg: guidance,
}
+ # Explicit: the pinned pipeline never reads the grid, and a newer one overrides num_inference_steps.
+ sample_sigmas = pipe_sample_sigmas(state.pipe)
+ if sample_sigmas is not None and "sigmas" in call_params:
+ kwargs["sigmas"] = sample_sigmas_for_steps(sample_sigmas, steps)
if state.family.name == IDEOGRAM4_FAMILY_NAME:
# Ideogram 4 drives CFG via EITHER a constant guidance_scale OR a per-step guidance_schedule,
# never both. At the advertised defaults drop the constant so the recommended 48-step taper
@@ -11391,7 +11434,7 @@ class DiffusionBackend:
"transformer_cache_stats": static_skip_stats(state.pipe),
"resolved": resolved,
"generation_defaults": _generation_defaults_for(
- state.repo_id, state.gguf_filename, state.base_repo
+ state.repo_id, state.gguf_filename, state.base_repo, pipe_sample_sigmas(state.pipe)
),
# Workflows the loaded family supports, so the UI can gate its tabs.
"workflows": _family_workflows(state.family),
@@ -11475,7 +11518,11 @@ def _family_workflows(fam: DiffusionFamily) -> list[str]:
def _resolve_base_repo(
- repo_id: str, base_repo: Optional[str], fam: DiffusionFamily, hf_token: Optional[str]
+ repo_id: str,
+ base_repo: Optional[str],
+ fam: DiffusionFamily,
+ hf_token: Optional[str],
+ gguf_filename: Optional[str] = None,
) -> str:
"""The companion diffusers repo: caller's base, else the GGUF repo's own ``base_model`` tag,
else the family fallback. Shared by both load paths so a direct ``load_pipeline`` call
@@ -11492,6 +11539,9 @@ def _resolve_base_repo(
# this becomes status()["base_repo"] and a trained adapter's default base_model, both of which must stay
# the vendor id. An EXPLICIT base_repo is verbatim.
base = canonical_base(tag)
+ elif tag is None:
+ # No card tag: only a curated variant the name spells out.
+ base = named_variant_base(fam, repo_id, gguf_filename) or ""
# Returns the UPSTREAM id; the swap happens at the fetch sites only.
resolved = resolve_base_repo(fam, base)
_remember_companion_base(repo_id, resolved)
diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.py
index c8e4e1f3291..5de535c5d8c 100644
--- a/studio/backend/core/inference/diffusion_families.py
+++ b/studio/backend/core/inference/diffusion_families.py
@@ -160,10 +160,10 @@ class DiffusionFamily:
# covers variants whose weights differ. Resolution prefers an exact variant match, then falls back to
# ``prequant_repos``.
prequant_variant_repos: tuple[tuple[str, str, str], ...] = field(default_factory = tuple)
- # Bases (lowercased) with NO hosted checkpoint, which must not inherit ``prequant_repos``: the family fallback
- # names an artifact baked from different weights, and planning acts on it before the load's base_model_id check
- # can refuse it. Only for a base whose weights genuinely differ from the default.
+ # Lowercased bases with different weights: never inherit ``prequant_repos``; their variant rows still win.
prequant_excluded_bases: tuple[str, ...] = field(default_factory = tuple)
+ # Variant bases a repo id or GGUF name can select when no card ``base_model`` tag resolves one.
+ named_variant_bases: tuple[str, ...] = field(default_factory = tuple)
# Preferred checkpoint FILENAME for a scheme, as (scheme, filename), overriding the ``<Model>-<SCHEME>.pt`` name
# ``prequant_repo_filename`` derives. The derived name stays on as the fallback, so a repo hosting BOTH an old and
# a new artifact serves the new one to a build that asks for it by name and the old one to every build that does
@@ -526,6 +526,14 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
("fp8", "unsloth/Qwen-Image-2.1-FP8"),
("nvfp4", "unsloth/Qwen-Image-2.1-NVFP4"),
),
+ # Turbo's own checkpoints (a different distill); derived names (2.1's plus -Turbo) resolve them.
+ prequant_variant_repos = (
+ ("qwen/qwen-image-2.1-turbo", "int8", "unsloth/Qwen-Image-2.1-Turbo-FP8"),
+ ("qwen/qwen-image-2.1-turbo", "fp8", "unsloth/Qwen-Image-2.1-Turbo-FP8"),
+ ),
+ # 2.1's artifacts are baked from 2.1's denoiser: for nvfp4 Turbo quantizes its own weights.
+ prequant_excluded_bases = ("qwen/qwen-image-2.1-turbo",),
+ named_variant_bases = ("Qwen/Qwen-Image-2.1-Turbo",),
# The artifacts are safetensors, not the historical torch.save pickle, so the family has to
# NAME them: every derived fallback ends in .pt, and without these rows the loader would ask
# the Hub for a file that is not there and silently fall back to the dense bf16 download.
@@ -1080,6 +1088,27 @@ def upstream_is_gated(repo_id: Optional[str]) -> bool:
return (repo_id or "").strip().lower() in _GATED_UPSTREAMS
+def named_variant_base(fam: "DiffusionFamily", *names: Optional[str]) -> Optional[str]:
+ """The longest ``fam.named_variant_bases`` entry ``names`` spell (separators folded), or None. The last, most
+ specific name decides first; one spelling the plain base stops the search (a 2.1 file in a Turbo repo stays 2.1)."""
+
+ def fold(text: Optional[str]) -> str:
+ return "".join(c for c in (text or "").lower() if c.isalnum())
+
+ variants = [
+ (b, fold(b.rsplit("/", 1)[-1])) for b in getattr(fam, "named_variant_bases", ()) or ()
+ ]
+ plain = fold((getattr(fam, "base_repo", "") or "").rsplit("/", 1)[-1])
+ for name in reversed([n for n in names if n]):
+ identity = fold(name)
+ hits = [b for b, key in variants if key and key in identity]
+ if hits:
+ return max(hits, key = len)
+ if plain and plain in identity:
+ return None
+ return None
+
+
def canonical_base(repo_id: Optional[str]) -> str:
"""A mirror id mapped back to the upstream it copies, else ``repo_id`` unchanged. Base-keyed
tables hold UPSTREAM ids, so every lookup normalises here: a mirror reaching
@@ -1330,7 +1359,11 @@ _GENERATION_DEFAULTS: tuple[tuple[str, int, float], ...] = (
("flux.2-klein-base", 20, 5.0),
("flux.2-klein", 4, 1.0),
("flux.2-dev", 20, 4.0), # full (non-distilled)
- # Before the generic qwen-image key (also the two below).
+ # Before the generic qwen-image key, Turbo before 2.1; qwenimage21 has no separator to fold, hence its own row.
+ ("qwen-image-2.1-turbo", 8, 1.0),
+ ("qwen-image-21-turbo", 8, 1.0),
+ ("qwenimage21-turbo", 8, 1.0),
+ ("qwenimage21turbo", 8, 1.0),
("qwen-image-2.1", 25, 1.0),
("qwen-image-21", 25, 1.0),
("qwen_image_21", 25, 1.0),
@@ -1414,15 +1447,30 @@ def transformer_variant_differs_from_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]:
- """Default ``(steps, guidance)`` for a loaded model. The first identifier naming a known model
- wins (repo id, then resolved base repo), so a local-path load still resolves via its base
- repo. Keys matched as substrings, most specific first."""
+def named_generation_params(*identifiers: Optional[str]) -> Optional[tuple[int, float]]:
+ """``(steps, guidance)`` of the first identifier naming a known model (a local path resolves via its base), or None."""
for identifier in identifiers:
needle = (identifier or "").lower()
for key, steps, guidance in _GENERATION_DEFAULTS:
if name_key_in(key, needle):
return steps, guidance
+ return None
+
+
+def default_generation_params(*identifiers: Optional[str]) -> tuple[int, float]:
+ """:func:`named_generation_params`, else the generic fallback."""
+ return named_generation_params(*identifiers) or _GENERATION_DEFAULT_FALLBACK
+
+
+def generation_params_with_grid(
+ grid: Optional[tuple[float, ...]], *identifiers: Optional[str]
+) -> tuple[int, float]:
+ """:func:`default_generation_params`, but an unnamed load with a shipped grid runs the grid's own step count."""
+ named = named_generation_params(*identifiers)
+ if named is not None:
+ return named
+ if grid:
+ return len(grid), _GENERATION_DEFAULT_FALLBACK[1]
return _GENERATION_DEFAULT_FALLBACK
@@ -1442,16 +1490,26 @@ def family_prequant_repo(
return None
# Both tables are keyed on lowercased upstream ids.
base = canonical_base(base_repo).lower()
+ named = named_variant_base(fam, base_repo) if base else None
+ if named and named.lower() != base:
+ # A local copy naming a variant: its row if the loader's tail compare accepts it, else none (never 2.1's).
+ if (
+ base.replace("\\", "/").rstrip("/").rsplit("/", 1)[-1]
+ != named.lower().rsplit("/", 1)[-1]
+ ):
+ return None
+ base = named.lower()
if base:
# getattr, because the video loader calls this with a VideoFamily, which has no such field. A plain attribute
# read raises AttributeError, resolve_prequant_source swallows it in its bare except and hands back None, and
# every video family silently loses its hosted prequant checkpoint to the dense path whenever a base_repo is
# passed.
- if base in (getattr(fam, "prequant_excluded_bases", ()) or ()):
- return None
+ # A variant row beats the exclusion: an excluded base may host its own checkpoints for some schemes.
for entry_base, entry_scheme, repo_id in fam.prequant_variant_repos:
if entry_base == base and entry_scheme == scheme:
return repo_id
+ if base in (getattr(fam, "prequant_excluded_bases", ()) or ()):
+ return None
for entry_scheme, repo_id in fam.prequant_repos:
if entry_scheme == scheme:
return repo_id
diff --git a/studio/backend/core/inference/diffusion_flow_shift.py b/studio/backend/core/inference/diffusion_flow_shift.py
index b0a4648270d..952ab6d67da 100644
--- a/studio/backend/core/inference/diffusion_flow_shift.py
+++ b/studio/backend/core/inference/diffusion_flow_shift.py
@@ -2,7 +2,8 @@
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Rebuild the loaded scheduler at ComfyUI's static sigma shift (shipped schedulers differ, e.g.
-Qwen-Image dynamic ~2.0 + terminal stretch vs 3.1). No torch/diffusers imports."""
+Qwen-Image dynamic ~2.0 + terminal stretch vs 3.1), unless the checkpoint ships its own sampling
+grid. No torch/diffusers imports."""
from __future__ import annotations
@@ -68,3 +69,82 @@ def apply_comfy_flow_shift(
if logger is not None:
logger.info("scheduler flow shift set to %s (ComfyUI default)", shift)
return True
+
+
+# A pipeline config's fixed sampling grid, terminal sigma excluded (QwenImage21Pipeline, huggingface/diffusers#14950).
+SAMPLE_SIGMAS_KEY = "sample_sigmas"
+
+
+def valid_sample_sigmas(raw: Any) -> Optional[tuple[float, ...]]:
+ """``raw`` as a grid the scheduler can take: finite, in (0, 1], strictly decreasing. None otherwise."""
+ if not isinstance(raw, (list, tuple)) or not raw:
+ return None
+ try:
+ grid = tuple(float(s) for s in raw)
+ except (TypeError, ValueError):
+ return None
+ if not all(math.isfinite(s) and 0.0 < s <= 1.0 for s in grid):
+ return None
+ if any(b >= a for a, b in zip(grid, grid[1:])):
+ return None
+ return grid
+
+
+# Not pipe.config: on the pinned diffusers an extra key fails DiffusionPipeline.components (group offload, from_pipe).
+SAMPLE_SIGMAS_ATTR = "_unsloth_sample_sigmas"
+
+
+def pipe_sample_sigmas(pipe: Any) -> Optional[tuple[float, ...]]:
+ """The grid the loaded pipeline carries (its own config on diffusers with #14950, else installed), or None."""
+ config = getattr(pipe, "config", None)
+ try:
+ raw = config.get(SAMPLE_SIGMAS_KEY) if config is not None else None
+ except Exception: # noqa: BLE001 - an exotic config carries no grid
+ raw = None
+ return valid_sample_sigmas(raw if raw is not None else getattr(pipe, SAMPLE_SIGMAS_ATTR, None))
+
+
+def install_sample_sigmas(
+ pipe: Any,
+ raw: Any,
+ logger: Any = None,
+) -> Optional[tuple[float, ...]]:
+ """Carry model_index.json ``sample_sigmas`` (dropped by the pinned diffusers) on ``pipe``; None without a grid."""
+ grid = pipe_sample_sigmas(pipe)
+ if grid is not None or raw is None:
+ return grid
+ grid = valid_sample_sigmas(raw)
+ if grid is None:
+ if logger is not None:
+ logger.warning("sample_sigmas ignored: not a decreasing grid in (0, 1]: %r", raw)
+ return None
+ setattr(pipe, SAMPLE_SIGMAS_ATTR, grid)
+ if logger is not None:
+ logger.info(
+ "checkpoint sampling grid installed: %d steps, shipped scheduler kept", len(grid)
+ )
+ return grid
+
+
+def sd_cpp_sample_sigmas(grid: tuple[float, ...], steps: int) -> list[float]:
+ """sd.cpp samples custom sigmas verbatim (no shift, steps = len - 1), so it needs the terminal 0 itself."""
+ return [*sample_sigmas_for_steps(grid, steps), 0.0]
+
+
+def sample_sigmas_for_steps(grid: tuple[float, ...], steps: int) -> list[float]:
+ """The grid at its own length, else resampled along it (Studio's own: the card evaluates only the 8-step grid)."""
+ steps = max(1, int(steps))
+ if steps == len(grid):
+ return list(grid)
+ if len(grid) == 1:
+ # No curve to follow: the pipeline's own linear spacing from the grid's start.
+ return [grid[0] * (1.0 - i / steps) for i in range(steps)]
+ if steps == 1:
+ return [grid[0]]
+ last = len(grid) - 1
+ out = []
+ for i in range(steps):
+ pos = i * last / (steps - 1)
+ lo = min(int(pos), last - 1)
+ out.append(grid[lo] + (grid[lo + 1] - grid[lo]) * (pos - lo))
+ return out
diff --git a/studio/backend/core/inference/diffusion_prequant.py b/studio/backend/core/inference/diffusion_prequant.py
index 5d7037b0acf..179dab8188a 100644
--- a/studio/backend/core/inference/diffusion_prequant.py
+++ b/studio/backend/core/inference/diffusion_prequant.py
@@ -1010,11 +1010,17 @@ def resolve_prequant_source(
# Family-declared name first when there is one, then the derived chain, which puts the
# safetensors spelling ahead of the pickle. Order-preserving dedup so a family that declares
# exactly what the chain would derive does not make the downloader ask twice for it.
- declared = (preferred,) if preferred else ()
+ # Declared names are the default repo's files; a variant repo gets its own spelling of each.
+ variant_repo = _is_variant_prequant_repo(fam, repo_id)
+ if variant_repo and preferred:
+ declared = (prequant_repo_filename(repo_id, scheme, ".safetensors"),)
+ else:
+ declared = (preferred,) if preferred else ()
# rotated artifact (hosted) first, only in its own repo; the plain chain stays behind it (offline, older caches)
from .diffusion_transformer_quant import (
convrot_prequant_filename,
convrot_prequant_repo,
+ convrot_prequant_variant_repo,
int8_convrot_enabled,
)
@@ -1022,6 +1028,13 @@ def resolve_prequant_source(
rotated = convrot_prequant_filename(scheme, fam_name)
rotated_repo = convrot_prequant_repo(scheme, fam_name)
if (
+ variant_repo
+ and convrot_prequant_variant_repo(scheme, fam_name, repo_id)
+ and int8_convrot_enabled(fam_name)
+ ):
+ # A variant repo listed as hosting its own rotated build, named like its derived chain.
+ declared = (prequant_repo_filename(repo_id, scheme, "-ConvRot.safetensors"),) + declared
+ elif (
rotated
and rotated_repo
and str(repo_id).strip().lower() == rotated_repo.lower()
@@ -1044,6 +1057,23 @@ def resolve_prequant_source(
return None
+def _is_variant_prequant_repo(fam: Any, repo_id: Optional[str]) -> bool:
+ """Whether ``repo_id`` is one of ``fam``'s per-base variant repos and not one of its default repos."""
+ key = str(repo_id or "").strip().lower()
+ if not key:
+ return False
+ try:
+ defaults = {str(r).strip().lower() for _s, r in getattr(fam, "prequant_repos", ()) or ()}
+ variants = {
+ str(e[2]).strip().lower()
+ for e in getattr(fam, "prequant_variant_repos", ()) or ()
+ if len(e) == 3
+ }
+ except Exception: # noqa: BLE001 - a malformed table keeps the declared names, today's behaviour
+ return False
+ return key in variants and key not in defaults
+
+
def _comfy_prequant_family(fam: Any) -> bool:
"""Whether ``fam``'s hosted artifacts may resolve to a ComfyUI-format twin: the image families, whose
denoiser loads through ``load_prequantized_transformer`` as one whole module."""
diff --git a/studio/backend/core/inference/diffusion_te_prequant.py b/studio/backend/core/inference/diffusion_te_prequant.py
index d3522455839..2bb81d7a337 100644
--- a/studio/backend/core/inference/diffusion_te_prequant.py
+++ b/studio/backend/core/inference/diffusion_te_prequant.py
@@ -193,6 +193,13 @@ _TE_EQUIVALENT_BASES: tuple[frozenset[str], ...] = (
"hunyuanvideo-community/hunyuanimage-2.1-diffusers",
}
),
+ # Qwen3-VL-8B: one file vs four shards, but all 750 tensors byte-identical (compared 2026-10-09).
+ frozenset(
+ {
+ "qwen/qwen-image-2.1",
+ "qwen/qwen-image-2.1-turbo",
+ }
+ ),
# Qwen3-4B: identical sha256 across the Krea-2 pair (compared 2026-08-25)
frozenset(
{
diff --git a/studio/backend/core/inference/diffusion_transformer_quant.py b/studio/backend/core/inference/diffusion_transformer_quant.py
index dc65f949271..ed4c1d731a0 100644
--- a/studio/backend/core/inference/diffusion_transformer_quant.py
+++ b/studio/backend/core/inference/diffusion_transformer_quant.py
@@ -249,6 +249,11 @@ _INT8_FAMILY_CONVROT_REPO: dict[str, str] = {
"z-image": "unsloth/Z-Image-Turbo-FP8",
}
+# Variant repos that also host a rotated build (``<Model>-INT8-ConvRot.safetensors``), listed for the same reason.
+_INT8_FAMILY_CONVROT_VARIANT_REPOS: dict[str, tuple[str, ...]] = {
+ "qwen-image-2.1": ("unsloth/Qwen-Image-2.1-Turbo-FP8",),
+}
+
# Families whose int8 runs ConvRot unless the env turns it off; the rest stay opt-in (``=1``).
_INT8_FAMILY_CONVROT_DEFAULT_ON: frozenset[str] = frozenset({"qwen-image-2.1", "z-image"})
@@ -288,6 +293,17 @@ def convrot_prequant_repo(scheme: str, family: Optional[str] = None) -> Optional
return _INT8_FAMILY_CONVROT_REPO.get(str(family or "").strip().lower())
+def convrot_prequant_variant_repo(
+ scheme: str, family: Optional[str], repo_id: Optional[str]
+) -> bool:
+ """Whether ``repo_id`` is a variant repo that hosts the family's rotated int8 build under its own name."""
+ if scheme != TQ_INT8 or not repo_id:
+ return False
+ key = str(repo_id).strip().lower()
+ repos = _INT8_FAMILY_CONVROT_VARIANT_REPOS.get(str(family or "").strip().lower(), ())
+ return any(key == r.lower() for r in repos)
+
+
def convrot_fqns(
transformer: Any, filter_fn: Any, group: int, suffixes: tuple[str, ...]
) -> tuple[str, ...]:
diff --git a/studio/backend/core/inference/sd_cpp_args.py b/studio/backend/core/inference/sd_cpp_args.py
index 9f226a873ae..4734552bfbb 100644
--- a/studio/backend/core/inference/sd_cpp_args.py
+++ b/studio/backend/core/inference/sd_cpp_args.py
@@ -615,6 +615,7 @@ def build_img_gen_request(
lora: Optional[list[dict]] = None,
ref_images: Optional[list[str]] = None,
qwen_image_layers: Optional[int] = None,
+ custom_sigmas: Optional[list[float]] = None,
) -> dict:
"""Build the ``POST /sdcpp/v1/img_gen`` JSON body for one text-to-image request.
@@ -638,6 +639,9 @@ def build_img_gen_request(
sample_params["sample_method"] = str(sample_method)
if flow_shift is not None:
sample_params["flow_shift"] = float(flow_shift)
+ if custom_sigmas:
+ # Same key the server's sample_params parser reads for sd-cli's --sigmas.
+ sample_params["custom_sigmas"] = [float(s) for s in custom_sigmas]
if guidance:
sample_params["guidance"] = guidance
diff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.py
index 8dce6805d9f..b553d9174ee 100644
--- a/studio/backend/core/inference/sd_cpp_backend.py
+++ b/studio/backend/core/inference/sd_cpp_backend.py
@@ -50,12 +50,19 @@ from core.inference.diffusion_families import (
legacy_source_repo,
prefer_cached_legacy_source,
prefer_ungated_mirror,
+ canonical_base,
+ named_variant_base,
resolve_base_repo,
resolve_local_gguf_child,
sd_cpp_text_encoders_for,
supported_family_names,
_family_override_resolved,
)
+from core.inference.diffusion_flow_shift import (
+ SAMPLE_SIGMAS_KEY,
+ sd_cpp_sample_sigmas,
+ valid_sample_sigmas,
+)
from core.inference.diffusion_memory import (
OFFLOAD_GROUP,
OFFLOAD_MODEL,
@@ -189,6 +196,64 @@ def _tree_reader(
_MAX_SERVER_BATCH = 8
+# Families whose bases ship a model_index.json ``sample_sigmas`` grid; every other load skips the card and index reads.
+_SAMPLE_SIGMAS_FAMILIES = frozenset({"qwen-image-2.1"})
+
+
+def _base_sample_sigmas(
+ repo_id: str,
+ base: str,
+ hf_token: Optional[str],
+ *,
+ family: str,
+ explicit_base: bool,
+ local_files_only: bool,
+ named_base: Optional[str] = None,
+) -> tuple[Optional[tuple[float, ...]], str]:
+ """(the base's model_index.json grid or None, that base). Without an explicit base the card's ``base_model``
+ names it, as on the diffusers route, so a community Turbo GGUF does not read 2.1's index."""
+ if family not in _SAMPLE_SIGMAS_FAMILIES:
+ return None, base
+ try:
+ from core.inference.diffusion import (
+ _hf_base_model,
+ _is_trusted_diffusion_repo,
+ hub_cache_dir,
+ )
+ from core.inference.diffusion_comfy_components import read_model_index
+
+ if not explicit_base and not local_files_only:
+ tag = _hf_base_model(repo_id, hf_token)
+ # Same trust bar as the diffusers resolver: the tag is repo-author metadata.
+ if tag and _is_trusted_diffusion_repo(tag):
+ base = canonical_base(tag)
+ elif tag is None and named_base:
+ base = named_base
+ elif not explicit_base and named_base:
+ # Cache-only (e.g. the OpenAI route's auto-switch) reads no card: the pick's own name decides.
+ base = named_base
+ # Cache-only reads try both roots, as the plan's locality check and _fetch_assets do.
+ roots = (hub_cache_dir(), None) if local_files_only else (hub_cache_dir(),)
+ for i, root in enumerate(roots):
+ try:
+ index = read_model_index(
+ base, hf_token = hf_token, local_files_only = local_files_only, cache_dir = root
+ )
+ break
+ except Exception: # noqa: BLE001
+ if i == len(roots) - 1:
+ raise
+ except Exception as exc: # noqa: BLE001 - no grid is the pre-grid behaviour
+ logger.debug("sd_cpp.sample_sigmas_unavailable: %s", exc)
+ return None, base
+ grid = valid_sample_sigmas(index.get(SAMPLE_SIGMAS_KEY) if isinstance(index, dict) else None)
+ if grid is not None:
+ logger.info(
+ "sd_cpp: %s ships a %d-step sampling grid; passing it as custom sigmas", base, len(grid)
+ )
+ return grid, base
+
+
def _default_threads() -> int:
"""Physical-core thread count for the sd.cpp CPU backend. ``threads = None`` lets sd.cpp pick
its own default, which is the logical-core count (all hyperthreads). For the compute-bound
@@ -2147,6 +2212,8 @@ class _SdState:
threads: Optional[int] = None
sampling_method: Optional[str] = None
flow_shift: Optional[float] = None
+ # The base's shipped ``sample_sigmas`` grid, sent as custom sigmas; None keeps sd.cpp's own schedule.
+ sample_sigmas: Optional[tuple[float, ...]] = None
server: Optional[SdCppServer] = None
mode: str = "server"
# Token kept so LoRA adapters selected at generate time can be fetched from the Hub.
@@ -2765,6 +2832,7 @@ class SdCppDiffusionBackend:
local_files_only = local_files_only,
gguf_filename = gguf_filename,
base = base,
+ explicit_base = bool((base_repo or "").strip()),
fam = fam,
family_override = family_override,
hf_token = hf_token,
@@ -2788,6 +2856,7 @@ class SdCppDiffusionBackend:
display_repo_id: Optional[str] = None,
gguf_filename: str,
base: str,
+ explicit_base: bool = False,
fam: DiffusionFamily,
family_override: Optional[str] = None,
hf_token: Optional[str],
@@ -2915,6 +2984,22 @@ class SdCppDiffusionBackend:
local_files_only = local_files_only,
vision_optional = not getattr(fam, "edit", False),
)
+ sample_sigmas, grid_base = _base_sample_sigmas(
+ repo_id,
+ base,
+ hf_token,
+ family = fam.name,
+ explicit_base = explicit_base,
+ local_files_only = local_files_only,
+ named_base = named_variant_base(fam, repo_id, gguf_filename),
+ )
+ if grid_base != base:
+ # The card can name a base begin_load did not know; link it so the delete guard keeps its index.
+ try:
+ from hub.utils.companion_assets import record_companion_link
+ record_companion_link(repo_id, grid_base)
+ except Exception as exc: # noqa: BLE001 -- bookkeeping never fails a load
+ logger.debug("sd_cpp.companion_link_record_failed: %s", exc)
files = SdCppModelFiles(
diffusion_model = paths["diffusion_model"],
@@ -3130,7 +3215,8 @@ class SdCppDiffusionBackend:
state = _SdState(
repo_id = repo_id,
display_repo_id = display_repo_id,
- base_repo = base,
+ # The card's base when it shipped the grid, as the diffusers route reports it.
+ base_repo = grid_base if sample_sigmas else base,
family = fam,
device = device,
files = files,
@@ -3142,6 +3228,7 @@ class SdCppDiffusionBackend:
threads = _default_threads(),
sampling_method = fam.sd_cpp_sampling_method,
flow_shift = fam.sd_cpp_flow_shift,
+ sample_sigmas = sample_sigmas,
server = server,
mode = mode,
hf_token = hf_token,
@@ -3286,6 +3373,18 @@ class SdCppDiffusionBackend:
into = merged.setdefault(fetch_repo[repo], [])
into.extend(n for n in names if n not in into)
by_repo = merged
+ # A named variant's load reads its model_index.json for the grid; planned so locality cannot skip it.
+ if base_repo:
+ explicit = resolve_base_repo(fam, base_repo)
+ variants = {b.lower() for b in getattr(fam, "named_variant_bases", ()) or ()}
+ # As given: that is the cache entry the load reads.
+ grid_base = explicit if explicit.lower() in variants else None
+ else:
+ grid_base = named_variant_base(fam, repo_id, gguf_filename)
+ if fam.name in _SAMPLE_SIGMAS_FAMILIES and grid_base:
+ names = by_repo.setdefault(grid_base, [])
+ if "model_index.json" not in names:
+ names.append("model_index.json")
fetch_repo_id = fetch_repo.get(repo_id, repo_id)
# AFTER the swap: preflighting the upstream id would refuse the very picks the ungated mirror exists to rescue
self._preflight_companion_repos(by_repo, fetch_repo_id, hf_token)
@@ -4044,6 +4143,11 @@ class SdCppDiffusionBackend:
batch_count = count,
sample_method = state.sampling_method,
flow_shift = state.flow_shift,
+ custom_sigmas = (
+ sd_cpp_sample_sigmas(state.sample_sigmas, int(steps))
+ if state.sample_sigmas
+ else None
+ ),
cfg_scale = cfg_scale,
distilled_guidance = flux_guidance,
lora = lora_payload,
@@ -4191,6 +4295,9 @@ class SdCppDiffusionBackend:
extra_args += ["--vae-format", state.vae_format]
if state.flow_shift is not None:
extra_args += ["--flow-shift", repr(float(state.flow_shift))]
+ if state.sample_sigmas:
+ sigmas = sd_cpp_sample_sigmas(state.sample_sigmas, int(steps))
+ extra_args += ["--sigmas", ",".join(repr(float(x)) for x in sigmas)]
images = []
seeds: list[int] = []
diff --git a/studio/backend/hub/tests/test_companion_assets.py b/studio/backend/hub/tests/test_companion_assets.py
index 638159d5116..2554b1007f0 100644
--- a/studio/backend/hub/tests/test_companion_assets.py
+++ b/studio/backend/hub/tests/test_companion_assets.py
@@ -722,6 +722,21 @@ def test_a_variant_named_by_an_alias_spelling_still_pins_its_base(monkeypatch):
assert asyncio.run(companion_cleanup.orphan_companions_response())["companions"] == []
+def test_a_turbo_gguf_pins_the_turbo_index_without_a_recorded_link(monkeypatch):
+ """A native Turbo load reads Qwen/Qwen-Image-2.1-Turbo's model_index.json for its sampling grid,
+ so that cached index has a dependent while the GGUF is installed, link or no link."""
+ turbo = "Qwen/Qwen-Image-2.1-Turbo"
+ _install(
+ monkeypatch,
+ _repo(
+ "someone/Qwen-Image-2.1-Turbo-GGUF", [("qwen_image_2.1_turbo_Q4_K_M.gguf", 2_000_000)]
+ ),
+ _repo(turbo, [("model_index.json", 460)]),
+ )
+ assert companion_cleanup.companion_dependents(turbo) == ["someone/Qwen-Image-2.1-Turbo-GGUF"]
+ assert asyncio.run(companion_cleanup.orphan_companions_response())["companions"] == []
+
+
def test_every_cached_gguf_in_one_repo_pins_its_own_base(monkeypatch):
"""One generic repo can hold checkpoints of two families in separate subdirectories, and the
loader selects either by file name. Probing only the first left the other's base orphaned."""
diff --git a/studio/backend/hub/utils/companion_assets.py b/studio/backend/hub/utils/companion_assets.py
index 9ce206a09db..ebdc4bcea22 100644
--- a/studio/backend/hub/utils/companion_assets.py
+++ b/studio/backend/hub/utils/companion_assets.py
@@ -291,6 +291,8 @@ def _curated_base_ids() -> set[str]:
try:
from core.inference.diffusion_families import _FAMILIES
ids |= {fam.base_repo for fam in _FAMILIES if getattr(fam, "base_repo", None)}
+ # Named variants (Qwen-Image-2.1-Turbo) are bases too: a Turbo pick's grid comes from that repo's index.
+ ids |= {b for fam in _FAMILIES for b in (getattr(fam, "named_variant_bases", ()) or ())}
except Exception as exc: # noqa: BLE001 -- no table means no extra candidates, as before
logger.debug("Companion base table unavailable: %s", exc)
ids |= _mirror_pair_ids()
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 2d1277fd6ba..73447d78f26 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -47977,14 +47977,19 @@ async def _generate_openai_images(
# Same order as the load (FLUX.1's base is schnell).
from core.inference.diffusion_content import content_variant_hint
- steps, guidance = default_generation_params(
- status.get("gguf_filename"),
- await asyncio.to_thread(
- content_variant_hint, status.get("repo_id"), status.get("gguf_filename")
- ),
- status.get("repo_id"),
- status.get("base_repo"),
- )
+ # Resolved by the diffusers status (a shipped grid's step count included).
+ defaults = status.get("generation_defaults")
+ if isinstance(defaults, dict) and defaults.get("steps"):
+ steps, guidance = int(defaults["steps"]), float(defaults["guidance"])
+ else:
+ steps, guidance = default_generation_params(
+ status.get("gguf_filename"),
+ await asyncio.to_thread(
+ content_variant_hint, status.get("repo_id"), status.get("gguf_filename")
+ ),
+ status.get("repo_id"),
+ status.get("base_repo"),
+ )
reset_media_generation_progress("image")
try:
with account_access.media_generation("diffusion"):
diff --git a/studio/backend/tests/test_diffusion_backend.py b/studio/backend/tests/test_diffusion_backend.py
index 5ac75e2c072..529dd86ea76 100644
--- a/studio/backend/tests/test_diffusion_backend.py
+++ b/studio/backend/tests/test_diffusion_backend.py
@@ -280,7 +280,7 @@ def test_no_mirror_is_a_companion_only_repo():
# Vendor bases the catalog offers before their unsloth mirror exists on the Hub. A mirror row for a
# repo that is not there would 404 every fetch it redirects, so the table cannot lead the upload;
# this names the gap instead of letting the check below go red on every PR until it closes.
-_MIRRORS_NOT_YET_PUBLISHED: frozenset[str] = frozenset()
+_MIRRORS_NOT_YET_PUBLISHED: frozenset[str] = frozenset({"qwen/qwen-image-2.1-turbo"})
def test_every_third_party_bf16_pipeline_the_catalog_offers_is_mirrored():
@@ -2854,6 +2854,85 @@ def test_generate_other_family_never_passes_cfg_trunc_ratio(fake_runtime, tmp_pa
assert call["cfg_trunc_ratio"] is None
+_TURBO_GRID = [1.0, 0.978453, 0.95418, 0.926626, 0.89508, 0.845148, 0.704534, 0.414568]
+
+
+class _FakeFlowScheduler:
+ def __init__(self, **config):
+ self.config = dict(config)
+
+ @classmethod
+ def from_config(cls, config, **overrides):
+ return cls(**{**config, **overrides})
+
+
+class _FakeGridPipe(_FakePipe):
+ """A QwenImage21Pipeline on the pinned diffusers: takes ``sigmas``, but its config never holds ``sample_sigmas``
+ (an extra key there breaks DiffusionPipeline.components, so group offload fails and the load dies)."""
+
+ def __init__(self) -> None:
+ super().__init__()
+ self.config = {}
+ self.scheduler = _FakeFlowScheduler(
+ shift = 1.0, use_dynamic_shifting = False, shift_terminal = None
+ )
+
+ def __call__(
+ self,
+ *,
+ prompt = None,
+ sigmas = None,
+ callback_on_step_end = None,
+ **kwargs,
+ ):
+ self.last_kwargs = {"prompt": prompt, "sigmas": sigmas, **kwargs}
+ return types.SimpleNamespace(images = [_FakeImage()])
+
+
+class _FakeGridPipeline:
+ @classmethod
+ def from_pretrained(cls, base, **kwargs):
+ return _FakeGridPipe()
+
+
+def _load_grid_pipeline(backend, tmp_path, monkeypatch, **manifest):
+ import diffusers
+
+ monkeypatch.setattr(diffusers, "Lumina2Pipeline", _FakeGridPipeline, raising = False)
+ # Stand in for a family whose ComfyUI template sets a static shift.
+ monkeypatch.setattr("core.inference.diffusion.comfy_flow_shift_for", lambda *a, **k: 3.0)
+ _write_pipeline(tmp_path, "Lumina2Pipeline", **manifest)
+ backend.load_pipeline(str(tmp_path), family_override = "lumina-2")
+ return backend._state.pipe
+
+
+def test_checkpoint_sample_sigmas_drive_the_schedule(fake_runtime, tmp_path, monkeypatch):
+ # The pinned diffusers drops Turbo's model_index.json grid; the backend carries it and passes it to every render.
+ backend = DiffusionBackend()
+ pipe = _load_grid_pipeline(backend, tmp_path, monkeypatch, sample_sigmas = _TURBO_GRID)
+ assert "sample_sigmas" not in pipe.config
+ assert pipe.scheduler.config["shift"] == 1.0 # not rebuilt at the static shift
+
+ backend.generate(prompt = "a sloth", steps = 8, guidance = 1.0)
+ assert pipe.last_kwargs["sigmas"] == _TURBO_GRID
+ # Another step count follows the same curve: same endpoints, still decreasing.
+ backend.generate(prompt = "a sloth", steps = 4, guidance = 1.0)
+ four = pipe.last_kwargs["sigmas"]
+ assert len(four) == 4 and four[0] == _TURBO_GRID[0] and four[-1] == _TURBO_GRID[-1]
+ assert all(b < a for a, b in zip(four, four[1:]))
+
+
+def test_checkpoint_without_sample_sigmas_keeps_the_static_shift(
+ fake_runtime, tmp_path, monkeypatch
+):
+ # Qwen/Qwen-Image-2.1 and every other checkpoint: no grid, so the ComfyUI shift and the linear ramp stay as on main.
+ backend = DiffusionBackend()
+ pipe = _load_grid_pipeline(backend, tmp_path, monkeypatch)
+ assert pipe.scheduler.config["shift"] == 3.0
+ backend.generate(prompt = "a sloth", steps = 8, guidance = 1.0)
+ assert pipe.last_kwargs["sigmas"] is None
+
+
def test_begin_load_rejects_concurrent(monkeypatch):
backend = DiffusionBackend()
# The worker resolves the base + downloads, both over the network; stub them so this is offline.
diff --git a/studio/backend/tests/test_diffusion_flow_shift.py b/studio/backend/tests/test_diffusion_flow_shift.py
index dc5c6992a26..222d58af102 100644
--- a/studio/backend/tests/test_diffusion_flow_shift.py
+++ b/studio/backend/tests/test_diffusion_flow_shift.py
@@ -8,7 +8,13 @@ from __future__ import annotations
import types
from core.inference.diffusion_families import comfy_flow_shift_for, detect_family
-from core.inference.diffusion_flow_shift import apply_comfy_flow_shift, flow_shift_overrides
+from core.inference.diffusion_flow_shift import (
+ apply_comfy_flow_shift,
+ flow_shift_overrides,
+ install_sample_sigmas,
+ pipe_sample_sigmas,
+ sample_sigmas_for_steps,
+)
from core.inference.video_families import detect_video_family
@@ -87,3 +93,28 @@ def test_qwen_image_edit_2509_keeps_its_template_shift():
assert comfy_flow_shift_for(fam, None, "Qwen/Qwen-Image-Edit-2511", None) == 3.1
assert comfy_flow_shift_for(fam, None, "unsloth/Qwen-Image-Edit-2511-GGUF", None) == 3.1
assert comfy_flow_shift_for(detect_family("Qwen/Qwen-Image"), "Qwen/Qwen-Image") == 3.1
+
+
+def test_sample_sigmas_follow_the_checkpoint_grid():
+ grid = (1.0, 0.978453, 0.95418, 0.926626, 0.89508, 0.845148, 0.704534, 0.414568)
+ assert sample_sigmas_for_steps(grid, 8) == list(grid)
+ for steps in (2, 4, 6, 12, 16):
+ out = sample_sigmas_for_steps(grid, steps)
+ assert len(out) == steps and out[0] == grid[0] and abs(out[-1] - grid[-1]) < 1e-12
+ assert all(b < a for a, b in zip(out, out[1:]))
+ assert sample_sigmas_for_steps(grid, 1) == [1.0]
+
+ def _pipe(config = None):
+ return types.SimpleNamespace(config = _Config(config or {}))
+
+ pipe = _pipe()
+ assert install_sample_sigmas(pipe, list(grid)) == grid
+ assert pipe_sample_sigmas(pipe) == grid and pipe.config == {}
+ assert install_sample_sigmas(_pipe(), None) is None
+ # A malformed grid is refused rather than handed to the scheduler, and the pipe stays untouched.
+ for bad in ([0.5, 0.8], [1.5, 0.5], [1.0, "x"], [], 0.5):
+ pipe = _pipe()
+ assert install_sample_sigmas(pipe, bad) is None
+ assert pipe_sample_sigmas(pipe) is None
+ # A pipeline that already carries one (diffusers with #14950) keeps it without reading the file.
+ assert install_sample_sigmas(_pipe({"sample_sigmas": [1.0, 0.5]}), None) == (1.0, 0.5)
diff --git a/studio/backend/tests/test_diffusion_more_families.py b/studio/backend/tests/test_diffusion_more_families.py
index b5b3e5bc76e..c79fe714134 100644
--- a/studio/backend/tests/test_diffusion_more_families.py
+++ b/studio/backend/tests/test_diffusion_more_families.py
@@ -682,6 +682,98 @@ def test_qwen_image_21_is_reachable_end_to_end_not_just_detectable():
)
+def test_qwen_image_21_turbo_loads_as_its_own_checkpoint_of_the_family():
+ """The official 8-step distill is trusted, gets its card's defaults, loads its own hosted denoisers (never 2.1's),
+ and shares 2.1's text encoder."""
+ from core.inference.diffusion_families import (
+ default_generation_params,
+ detect_family,
+ family_prequant_repo,
+ )
+ from core.inference.diffusion_te_prequant import te_base_equivalent
+
+ turbo = "Qwen/Qwen-Image-2.1-Turbo"
+ fam = detect_family(turbo)
+ assert fam is not None and fam.name == "qwen-image-2.1"
+ assert _is_trusted_diffusion_repo(turbo)
+ # The card's recipe, for the repo, its GGUFs and a renamed local copy alike; the base keeps its own.
+ for identifier in (
+ turbo,
+ "qwen_image_2.1_turbo_Q4_K_M.gguf",
+ "/models/qwen-image-21-turbo",
+ "/models/qwen_image_21_turbo",
+ "/models/qwen-image-21_turbo",
+ "/models/qwenimage21-turbo",
+ "/models/qwenimage21_turbo",
+ "/models/qwenimage21turbo",
+ "qwenimage21turbo-Q4_K_M.gguf",
+ ):
+ assert default_generation_params(identifier) == (8, 1.0), identifier
+ for identifier in ("Qwen/Qwen-Image-2.1", "/models/qwen_image_21", "/models/qwenimage21"):
+ assert default_generation_params(identifier) == (25, 1.0), identifier
+ # Turbo's own int8 / fp8 denoisers, never 2.1's; nvfp4 (not hosted for Turbo) quantizes at load.
+ for scheme in ("int8", "fp8"):
+ assert (
+ family_prequant_repo(fam, scheme, base_repo = turbo) == "unsloth/Qwen-Image-2.1-Turbo-FP8"
+ )
+ assert (
+ family_prequant_repo(fam, scheme, base_repo = "Qwen/Qwen-Image-2.1")
+ == "unsloth/Qwen-Image-2.1-FP8"
+ )
+ assert family_prequant_repo(fam, "nvfp4", base_repo = turbo) is None
+ # Its Qwen3-VL encoder is byte-identical to 2.1's, so the hosted int8 ConvRot encoder serves both.
+ assert te_base_equivalent("Qwen/Qwen-Image-2.1", turbo)
+ assert not te_base_equivalent("Qwen/Qwen-Image", turbo)
+
+
+def test_qwen_image_21_turbo_resolves_its_own_artifact_names(monkeypatch):
+ """Turbo's repo is asked for Turbo's files, in the same order 2.1's repo is asked for 2.1's, and declares only
+ files it hosts. 2.1's chain is unchanged."""
+ from core.inference.diffusion_families import detect_family
+ from core.inference.diffusion_prequant import resolve_prequant_source
+
+ monkeypatch.delenv("UNSLOTH_DIFFUSION_INT8_CONVROT", raising = False)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_PREQUANT_COMFY", "0")
+ fam = detect_family("Qwen/Qwen-Image-2.1")
+ expected = {
+ ("Qwen/Qwen-Image-2.1", "int8"): (
+ "unsloth/Qwen-Image-2.1-FP8",
+ ("Qwen-Image-2.1-INT8-ConvRot.safetensors", "Qwen-Image-2.1-INT8.safetensors"),
+ ),
+ ("Qwen/Qwen-Image-2.1", "fp8"): (
+ "unsloth/Qwen-Image-2.1-FP8",
+ ("Qwen-Image-2.1-FP8.safetensors",),
+ ),
+ ("Qwen/Qwen-Image-2.1-Turbo", "int8"): (
+ "unsloth/Qwen-Image-2.1-Turbo-FP8",
+ (
+ "Qwen-Image-2.1-Turbo-INT8-ConvRot.safetensors",
+ "Qwen-Image-2.1-Turbo-INT8.safetensors",
+ ),
+ ),
+ ("Qwen/Qwen-Image-2.1-Turbo", "fp8"): (
+ "unsloth/Qwen-Image-2.1-Turbo-FP8",
+ ("Qwen-Image-2.1-Turbo-FP8.safetensors",),
+ ),
+ }
+ for (base, scheme), (repo, declared) in expected.items():
+ source = resolve_prequant_source(fam, scheme, base_repo = base)
+ assert source.location == repo, (base, scheme)
+ assert source.declared_filenames == declared, (base, scheme)
+ assert source.filename == declared[0], (base, scheme)
+ names = [
+ n
+ for n in (source.filename, *source.fallback_filenames)
+ if not n.startswith("transformer_")
+ ]
+ assert all(("-Turbo-" in n) == ("Turbo" in base) for n in names), names
+ # The ConvRot kill switch drops the rotated name for both repos alike.
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_INT8_CONVROT", "0")
+ for base in ("Qwen/Qwen-Image-2.1", "Qwen/Qwen-Image-2.1-Turbo"):
+ source = resolve_prequant_source(fam, "int8", base_repo = base)
+ assert not any("ConvRot" in n for n in (source.filename, *source.fallback_filenames))
+
+
def test_every_image_family_base_repo_is_loadable():
"""The general form of the above, so the next family cannot ship inert the same way."""
from core.inference.diffusion_families import _FAMILIES
@@ -854,3 +946,78 @@ def test_qwen_image_21_takes_reference_images_but_is_not_an_edit_only_family():
edit = detect_family("Qwen/Qwen-Image-Edit-2511")
assert edit is not None and edit.name == "qwen-image-edit" and edit.edit is True
assert edit.pipeline_class != fam.pipeline_class
+
+
+ "name, card, expected",
+ [
+ ("qwen_image_2.1_turbo-Q4_K_M.gguf", None, "Qwen/Qwen-Image-2.1-Turbo"),
+ ("qwen-image-2.1-Q4_K_M.gguf", None, "Qwen/Qwen-Image-2.1"),
+ # A card tag decides when there is one, even an untrusted one that falls back to the default.
+ ("qwen_image_2.1_turbo-Q4_K_M.gguf", "someone/else", "Qwen/Qwen-Image-2.1"),
+ ],
+)
+def test_a_local_turbo_gguf_resolves_the_turbo_base_by_name(
+ monkeypatch, tmp_path, name, card, expected
+):
+ from core.inference import diffusion as dmod
+ from core.inference.diffusion_families import detect_family_for_pick
+
+ monkeypatch.setattr(dmod, "_hf_base_model", lambda repo_id, token: card)
+ monkeypatch.setattr(dmod, "_remember_companion_base", lambda repo_id, base: None)
+ fam = detect_family_for_pick(str(tmp_path), name, "qwen-image-2.1")
+ assert dmod._resolve_base_repo(str(tmp_path), None, fam, None, name) == expected
+
+
+ "repo, gguf, expected",
+ [
+ (
+ "someone/Qwen-Image-2.1-GGUF",
+ "qwen-image-2.1-turbo-Q4_K_M.gguf",
+ "Qwen/Qwen-Image-2.1-Turbo",
+ ),
+ ("someone/Qwen-Image-2.1-Turbo-GGUF", "model-Q4_K_M.gguf", "Qwen/Qwen-Image-2.1-Turbo"),
+ # The selected file decides: a plain 2.1 file in a Turbo-named repo or folder keeps 2.1.
+ ("someone/Qwen-Image-2.1-Turbo-GGUF", "qwen_image_2.1_Q4_K_M.gguf", None),
+ ("/models/qwen-image-2.1-turbo", "qwenimage21-Q8_0.gguf", None),
+ ("someone/Qwen-Image-2.1-GGUF", "qwen-image-2.1-Q4_K_M.gguf", None),
+ ],
+)
+def test_the_selected_file_decides_the_named_variant(repo, gguf, expected):
+ from core.inference.diffusion_families import named_variant_base
+ assert named_variant_base(detect_family("Qwen/Qwen-Image-2.1"), repo, gguf) == expected
+
+
+ "base, expected",
+ [
+ ("Qwen/Qwen-Image-2.1-Turbo", "unsloth/Qwen-Image-2.1-Turbo-FP8"),
+ # A local Turbo pipeline: the Turbo artifact when the loader's tail compare accepts it, else none at all.
+ ("/models/Qwen-Image-2.1-Turbo", "unsloth/Qwen-Image-2.1-Turbo-FP8"),
+ ("/models/qwen_image_21_turbo", None),
+ ("/models/Qwen-Image-2.1", "unsloth/Qwen-Image-2.1-FP8"),
+ ("Qwen/Qwen-Image-2.1", "unsloth/Qwen-Image-2.1-FP8"),
+ ],
+)
+def test_a_local_turbo_pipeline_never_plans_the_2_1_artifact(base, expected):
+ from core.inference.diffusion_families import family_prequant_repo
+ fam = detect_family("Qwen/Qwen-Image-2.1")
+ for scheme in ("int8", "fp8"):
+ assert family_prequant_repo(fam, scheme, base_repo = base) == expected, (base, scheme)
+
+
+def test_an_opaque_local_load_with_a_shipped_grid_runs_its_step_count():
+ from core.inference.diffusion import _generation_defaults_for
+ from core.inference.diffusion_families import generation_params_with_grid
+
+ grid = (1.0, 0.978453, 0.95418, 0.926626, 0.89508, 0.845148, 0.704534, 0.414568)
+ # No name matches: the grid's own count, not the fallback's 9 (which would resample it).
+ assert generation_params_with_grid(grid, "/models/opaque", "/models/opaque") == (8, 0.0)
+ assert _generation_defaults_for("/models/opaque", None, "/models/opaque", grid) == {
+ "steps": 8,
+ "guidance": 0.0,
+ }
+ # A name still decides first, and no grid keeps the fallback.
+ assert generation_params_with_grid(grid, "Qwen/Qwen-Image-2.1-Turbo") == (8, 1.0)
+ assert generation_params_with_grid(None, "/models/opaque") == (9, 0.0)
diff --git a/studio/backend/tests/test_openai_images_generations_route.py b/studio/backend/tests/test_openai_images_generations_route.py
index ca06524b347..5eef2a4dab1 100644
--- a/studio/backend/tests/test_openai_images_generations_route.py
+++ b/studio/backend/tests/test_openai_images_generations_route.py
@@ -119,7 +119,10 @@ class _FakeBackend:
# (repo_id, base_repo) pairs generate() reports as loaded, one per call: models a
# replacement landing between the route's status() read and its lock (#9448).
replaced_by = None,
+ # What a diffusers status() reports as its resolved recipe, when set.
+ generation_defaults = None,
) -> None:
+ self._generation_defaults = generation_defaults
self._loaded = loaded
self._repo_id = repo_id
self._base_repo = base_repo
@@ -146,6 +149,8 @@ class _FakeBackend:
"dtype": "float32",
"cpu_offload": False,
}
+ if self._generation_defaults is not None:
+ out["generation_defaults"] = self._generation_defaults
if isinstance(self._workflows, dict):
out["workflows"] = self._workflows.get(self._repo_id, [])
elif self._workflows is not None:
@@ -306,6 +311,19 @@ def test_local_load_uses_base_repo_for_defaults(monkeypatch):
assert backend.calls[0]["steps"] == 20 and backend.calls[0]["guidance"] == 3.5
+def test_the_status_recipe_wins_over_the_name_lookup(monkeypatch):
+ # An opaque local Turbo pipeline: no name matches, but the status resolved the shipped grid's 8 steps.
+ backend = _FakeBackend(
+ repo_id = "/models/opaque", generation_defaults = {"steps": 8, "guidance": 0.0}
+ )
+ monkeypatch.setattr(diffusion_module, "get_diffusion_backend", lambda: backend)
+ cli, store, _save = _make_client(backend)
+ monkeypatch.setattr(gallery_module, "save", _save)
+ resp = cli.post("/v1/images/generations", json = {"prompt": "p", "size": "256x256"})
+ assert resp.status_code == 200
+ assert backend.calls[0]["steps"] == 8 and backend.calls[0]["guidance"] == 0.0
+
+
def test_pipeline_runtime_error_is_sanitized_500(monkeypatch):
# A RuntimeError raised inside the pipeline while the model stays loaded (e.g. CUDA OOM) is a sanitized 500, not a 503 echoing the raw text.
oom = RuntimeError("CUDA out of memory. Tried to allocate 20.00 GiB (GPU 0; 47.5 GiB total)")
diff --git a/studio/backend/tests/test_sd_cpp_sample_sigmas.py b/studio/backend/tests/test_sd_cpp_sample_sigmas.py
new file mode 100644
index 00000000000..320ab4d81fa
--- /dev/null
+++ b/studio/backend/tests/test_sd_cpp_sample_sigmas.py
@@ -0,0 +1,333 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Native (sd.cpp) route for a checkpoint whose base ships a sampling grid (Qwen-Image-2.1-Turbo's
+model_index.json ``sample_sigmas``): the grid plus sd.cpp's terminal 0 goes out as custom sigmas on
+both the sd-server body and the one-shot sd-cli argv, resampled for other step counts, and a load
+without a grid sends exactly what it sent before."""
+
+from __future__ import annotations
+
+import pytest
+
+from core.inference import diffusion as diffusion_mod
+from core.inference import diffusion_comfy_components as comfy_components
+from core.inference import sd_cpp_backend as bk
+from core.inference.diffusion_families import detect_family_for_pick
+from core.inference.sd_cpp_args import SdCppModelFiles
+from core.inference.sd_cpp_backend import SdCppDiffusionBackend
+
+from .test_sd_cpp_backend import _FakeEngine, _FakeServer
+
+TURBO_GRID = (1.0, 0.978453, 0.95418, 0.926626, 0.89508, 0.845148, 0.704534, 0.414568)
+REPO = "Abiray/Qwen-Image-2.1-Turbo-GGUF"
+GGUF = "qwen_image_2.1_turbo_Q4_K_M.gguf"
+FAM = detect_family_for_pick(REPO, GGUF, None)
+FILES = SdCppModelFiles(
+ diffusion_model = f"/m/{GGUF}",
+ vae = "/m/qwen_image_2.1_vae_bf16.safetensors",
+ llm = "/m/Qwen3-VL-8B-Instruct-UD-Q4_K_XL.gguf",
+)
+
+
+def _state(
+ *,
+ grid,
+ mode = "oneshot",
+ server = None,
+):
+ return bk._SdState(
+ repo_id = REPO,
+ base_repo = FAM.base_repo,
+ family = FAM,
+ device = "cpu",
+ files = FILES,
+ sampling_method = FAM.sd_cpp_sampling_method,
+ flow_shift = FAM.sd_cpp_flow_shift,
+ sample_sigmas = grid,
+ mode = mode,
+ server = server,
+ )
+
+
+def _server_body(grid, steps):
+ server = _FakeServer("sd-server")
+ b = SdCppDiffusionBackend(engine = _FakeEngine())
+ b._state = _state(grid = grid, mode = "server", server = server)
+ b.generate(prompt = "p", steps = steps, guidance = 1.0, seed = 3)
+ return server.payloads[-1]
+
+
+def _oneshot_extra_args(grid, steps):
+ engine = _FakeEngine()
+ b = SdCppDiffusionBackend(engine = engine)
+ b._state = _state(grid = grid)
+ b.generate(prompt = "p", steps = steps, guidance = 1.0, seed = 3)
+ return list(engine.calls[-1][3].get("extra_args") or [])
+
+
+def test_family_is_qwen_image_21_without_a_flow_shift():
+ assert FAM is not None and FAM.base_repo == "Qwen/Qwen-Image-2.1"
+ # Custom sigmas replace sd.cpp's schedule outright, so there is no shift for them to fight.
+ assert FAM.sd_cpp_flow_shift is None
+
+
+def test_server_body_carries_the_grid_and_terminal_zero():
+ body = _server_body(TURBO_GRID, 8)
+ assert body["sample_params"]["custom_sigmas"] == [*TURBO_GRID, 0.0]
+ assert body["sample_params"]["sample_steps"] == 8
+
+
+def test_server_body_without_a_grid_is_unchanged():
+ with_none = _server_body(None, 8)
+ assert "custom_sigmas" not in with_none["sample_params"]
+ with_grid = _server_body(TURBO_GRID, 8)
+ with_grid["sample_params"].pop("custom_sigmas")
+ assert with_grid == with_none
+
+
+def test_oneshot_argv_carries_the_grid_and_terminal_zero():
+ extra = _oneshot_extra_args(TURBO_GRID, 8)
+ sigmas = [float(x) for x in extra[extra.index("--sigmas") + 1].split(",")]
+ assert sigmas == [*TURBO_GRID, 0.0]
+
+
+def test_oneshot_argv_without_a_grid_is_unchanged():
+ assert "--sigmas" not in _oneshot_extra_args(None, 8)
+ with_grid = _oneshot_extra_args(TURBO_GRID, 8)
+ i = with_grid.index("--sigmas")
+ assert with_grid[:i] + with_grid[i + 2 :] == _oneshot_extra_args(None, 8)
+
+
[email protected]("steps", [4, 12])
+def test_other_step_counts_resample_along_the_grid(steps):
+ sigmas = _server_body(TURBO_GRID, steps)["sample_params"]["custom_sigmas"]
+ # sd.cpp takes the step count from len(sigmas) - 1, so it must match the request.
+ assert len(sigmas) == steps + 1
+ assert sigmas[0] == 1.0 and sigmas[-2] == pytest.approx(TURBO_GRID[-1]) and sigmas[-1] == 0.0
+ assert all(a > b for a, b in zip(sigmas, sigmas[1:]))
+
+
+def _patch_hub(monkeypatch, *, card_base, indexes):
+ calls = {"card": 0, "index": []}
+
+ def _card(repo_id, token):
+ calls["card"] += 1
+ return card_base
+
+ def _index(base, **kw):
+ calls["index"].append((base, kw.get("local_files_only")))
+ if base not in indexes:
+ raise FileNotFoundError(base)
+ return indexes[base]
+
+ monkeypatch.setattr(diffusion_mod, "_hf_base_model", _card)
+ monkeypatch.setattr(comfy_components, "read_model_index", _index)
+ return calls
+
+
+INDEXES = {
+ "Qwen/Qwen-Image-2.1-Turbo": {"sample_sigmas": list(TURBO_GRID)},
+ "Qwen/Qwen-Image-2.1": {"_class_name": "QwenImage21Pipeline"},
+}
+
+
+def test_community_gguf_finds_the_grid_through_its_card_base(monkeypatch):
+ _patch_hub(monkeypatch, card_base = "Qwen/Qwen-Image-2.1-Turbo", indexes = INDEXES)
+ grid, base = bk._base_sample_sigmas(
+ REPO, FAM.base_repo, None, family = FAM.name, explicit_base = False, local_files_only = False
+ )
+ assert grid == TURBO_GRID
+ # Reported as the load's base, so the Images form resets to Turbo's 8 steps, not 2.1's 25.
+ assert base == "Qwen/Qwen-Image-2.1-Turbo"
+
+
+def test_base_without_a_grid_and_untrusted_tags_give_none(monkeypatch):
+ _patch_hub(monkeypatch, card_base = "Qwen/Qwen-Image-2.1", indexes = INDEXES)
+ assert (
+ bk._base_sample_sigmas(
+ REPO, FAM.base_repo, None, family = FAM.name, explicit_base = False, local_files_only = False
+ )[0]
+ is None
+ )
+ # An untrusted card tag is dropped, as on the diffusers route.
+ calls = _patch_hub(
+ monkeypatch,
+ card_base = "someone/evil",
+ indexes = {**INDEXES, "someone/evil": {"sample_sigmas": list(TURBO_GRID)}},
+ )
+ assert (
+ bk._base_sample_sigmas(
+ REPO, FAM.base_repo, None, family = FAM.name, explicit_base = False, local_files_only = False
+ )[0]
+ is None
+ )
+ assert calls["index"] == [("Qwen/Qwen-Image-2.1", False)]
+
+
+def test_explicit_base_and_cache_only_loads_skip_the_card(monkeypatch):
+ calls = _patch_hub(monkeypatch, card_base = "Qwen/Qwen-Image-2.1-Turbo", indexes = INDEXES)
+ assert (
+ bk._base_sample_sigmas(
+ REPO,
+ "Qwen/Qwen-Image-2.1-Turbo",
+ None,
+ family = FAM.name,
+ explicit_base = True,
+ local_files_only = False,
+ )[0]
+ == TURBO_GRID
+ )
+ assert (
+ bk._base_sample_sigmas(
+ REPO, FAM.base_repo, None, family = FAM.name, explicit_base = False, local_files_only = True
+ )[0]
+ is None
+ )
+ assert calls["card"] == 0
+ assert calls["index"][-1] == ("Qwen/Qwen-Image-2.1", True)
+
+
[email protected]("raw", [[1.0, 1.2], [0.5, 0.9], "x", [float("nan")]])
+def test_invalid_or_unreadable_grids_give_none(monkeypatch, raw):
+ _patch_hub(monkeypatch, card_base = None, indexes = {"Qwen/Qwen-Image-2.1": {"sample_sigmas": raw}})
+ assert (
+ bk._base_sample_sigmas(
+ REPO, FAM.base_repo, None, family = FAM.name, explicit_base = False, local_files_only = False
+ )[0]
+ is None
+ )
+ _patch_hub(monkeypatch, card_base = None, indexes = {})
+ assert (
+ bk._base_sample_sigmas(
+ REPO, FAM.base_repo, None, family = FAM.name, explicit_base = False, local_files_only = False
+ )[0]
+ is None
+ )
+
+
+def test_other_families_never_read_the_card_or_index(monkeypatch):
+ calls = _patch_hub(monkeypatch, card_base = "Qwen/Qwen-Image-2.1-Turbo", indexes = INDEXES)
+ assert (
+ bk._base_sample_sigmas(
+ REPO, FAM.base_repo, None, family = "flux", explicit_base = False, local_files_only = False
+ )[0]
+ is None
+ )
+ assert calls["card"] == 0 and calls["index"] == []
+
+
+def test_a_cache_only_reload_follows_the_picks_own_name(monkeypatch):
+ calls = _patch_hub(monkeypatch, card_base = "Qwen/Qwen-Image-2.1-Turbo", indexes = INDEXES)
+ kw = dict(family = FAM.name, explicit_base = False, local_files_only = True)
+ # The OpenAI route's auto-switch reloads cache-only with no base: a Turbo-named pick keeps its grid and base.
+ grid, base = bk._base_sample_sigmas(
+ REPO, FAM.base_repo, None, named_base = "Qwen/Qwen-Image-2.1-Turbo", **kw
+ )
+ assert grid == TURBO_GRID and base == "Qwen/Qwen-Image-2.1-Turbo"
+ # A plain 2.1 file from the same repo gets 2.1's schedule, whatever an earlier Turbo load resolved.
+ assert bk._base_sample_sigmas(REPO, FAM.base_repo, None, **kw) == (None, FAM.base_repo)
+ assert calls["card"] == 0
+
+
+def test_a_local_turbo_gguf_without_a_card_takes_the_named_grid(monkeypatch):
+ calls = _patch_hub(monkeypatch, card_base = None, indexes = INDEXES)
+ grid, base = bk._base_sample_sigmas(
+ REPO,
+ FAM.base_repo,
+ None,
+ family = FAM.name,
+ explicit_base = False,
+ local_files_only = False,
+ named_base = "Qwen/Qwen-Image-2.1-Turbo",
+ )
+ assert grid == TURBO_GRID and base == "Qwen/Qwen-Image-2.1-Turbo"
+ assert calls["index"][-1][0] == "Qwen/Qwen-Image-2.1-Turbo"
+
+
+ "gguf, base_repo, staged",
+ [
+ (GGUF, None, True),
+ ("qwen_image_2.1_Q4_K_M.gguf", None, False),
+ (GGUF, "Qwen/Qwen-Image-2.1", False),
+ ("model-Q4_K_M.gguf", "Qwen/Qwen-Image-2.1-Turbo", True),
+ ("model-Q4_K_M.gguf", "qwen/qwen-image-2.1-turbo", True),
+ ],
+)
+def test_the_native_plan_stages_a_named_variants_index(monkeypatch, gguf, base_repo, staged):
+ # Locality approves a cache-only load from this plan, so the index the load reads for its grid is in it.
+ from core.inference.diffusion import DiffusionBackend
+
+ repo = "someone/Qwen-Image-2.1-GGUF"
+ b = SdCppDiffusionBackend(engine = _FakeEngine())
+ monkeypatch.setattr(b, "_asset_specs", lambda *a, **k: [(repo, gguf, "diffusion_model")])
+ monkeypatch.setattr(b, "_flux2_inner_dim", lambda *a, **k: None)
+ monkeypatch.setattr(bk, "_assert_pick_is_not_speech", lambda *a, **k: None)
+ monkeypatch.setattr(bk, "_fetch_repo_map", lambda specs, token: {repo: repo})
+ monkeypatch.setattr(b, "_preflight_companion_repos", lambda *a, **k: None)
+ monkeypatch.setattr(b, "_plan_file_sizes", lambda by_repo, token: {})
+ monkeypatch.setattr(
+ DiffusionBackend, "_hub_file_is_loadable", staticmethod(lambda *a, **k: False)
+ )
+ plan = b.download_plan(repo, gguf_filename = gguf, base_repo = base_repo, model_kind = "gguf")
+ index = [e for e in plan["entries"] if e["repo_id"].lower() == "qwen/qwen-image-2.1-turbo"]
+ assert (
+ (index == [{**index[0], "files": ["model_index.json"], "checkpoint": False}])
+ if staged
+ else index == []
+ )
+
+
+def test_a_card_resolved_grid_base_is_linked_to_the_pick(monkeypatch):
+ # begin_load linked only the family default; the base the card named holds the index a cache-only reload needs.
+ from hub.utils import companion_assets
+
+ from .test_sd_cpp_backend import _shared_setup_1
+
+ links = []
+ monkeypatch.setattr(
+ companion_assets, "record_companion_link", lambda c, b: links.append((c, b))
+ )
+ monkeypatch.setattr(
+ bk, "_base_sample_sigmas", lambda *a, **k: (TURBO_GRID, "Qwen/Qwen-Image-2.1-Turbo")
+ )
+ monkeypatch.setattr(bk, "find_sd_server_binary", lambda: None)
+ b = SdCppDiffusionBackend()
+ _shared_setup_1(b, _FakeEngine(), monkeypatch)
+ b._load_token = 1
+ b._run_load(
+ repo_id = "someone/community-gguf",
+ gguf_filename = "model-Q4_K_M.gguf",
+ base = FAM.base_repo,
+ fam = FAM,
+ hf_token = None,
+ _load_token = 1,
+ )
+ assert b._state is not None and b._state.sample_sigmas == TURBO_GRID
+ assert ("someone/community-gguf", "Qwen/Qwen-Image-2.1-Turbo") in links
+
+
+def test_a_cache_only_grid_read_falls_back_to_the_default_cache_root(monkeypatch):
+ # The plan's locality check and _fetch_assets accept a copy in either root; the grid read must too.
+ roots = []
+
+ def _index(base, **kw):
+ roots.append(kw.get("cache_dir"))
+ if kw.get("cache_dir") is not None:
+ raise FileNotFoundError(base)
+ return {"sample_sigmas": list(TURBO_GRID)}
+
+ monkeypatch.setattr(comfy_components, "read_model_index", _index)
+ monkeypatch.setattr(diffusion_mod, "hub_cache_dir", lambda: "/live")
+ grid, base = bk._base_sample_sigmas(
+ REPO,
+ FAM.base_repo,
+ None,
+ family = FAM.name,
+ explicit_base = False,
+ local_files_only = True,
+ named_base = "Qwen/Qwen-Image-2.1-Turbo",
+ )
+ assert grid == TURBO_GRID and base == "Qwen/Qwen-Image-2.1-Turbo"
+ assert roots == ["/live", None]
diff --git a/studio/frontend/src/features/images/image-generation-defaults.ts b/studio/frontend/src/features/images/image-generation-defaults.ts
index 810c9061670..836ccc43239 100644
--- a/studio/frontend/src/features/images/image-generation-defaults.ts
+++ b/studio/frontend/src/features/images/image-generation-defaults.ts
@@ -24,7 +24,11 @@ const MODEL_DEFAULTS: Array<{
{ match: "flux.2-klein-base", steps: 20, guidance: 5 },
{ match: "flux.2-klein", steps: 4, guidance: 1 },
{ match: "flux.2-dev", steps: 20, guidance: 4 },
- // Qwen-Image-2.1 and its aliases, before the generic key.
+ // Qwen-Image-2.1 and its aliases, before the generic key, Turbo before 2.1.
+ { match: "qwen-image-2.1-turbo", steps: 8, guidance: 1 },
+ { match: "qwen-image-21-turbo", steps: 8, guidance: 1 },
+ { match: "qwenimage21-turbo", steps: 8, guidance: 1 },
+ { match: "qwenimage21turbo", steps: 8, guidance: 1 },
{ match: "qwen-image-2.1", steps: 25, guidance: 1 },
{ match: "qwen-image-21", steps: 25, guidance: 1 },
{ match: "qwen_image_21", steps: 25, guidance: 1 },
@@ -53,8 +57,13 @@ export function defaultsFor(repoId: string): {
steps: number;
guidance: number;
} {
+ // Mirrors the backend's name_key_in, so both tables resolve one spelling alike.
+ const fold = (text: string) => text.replace(/[-_.\s]+/g, "-");
const id = repoId.toLowerCase();
- const matched = MODEL_DEFAULTS.find((entry) => id.includes(entry.match));
+ const folded = fold(id);
+ const matched = MODEL_DEFAULTS.find(
+ (entry) => id.includes(entry.match) || folded.includes(fold(entry.match)),
+ );
return matched
? { steps: matched.steps, guidance: matched.guidance }
: DEFAULT_GEN;
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts
index 2019b2ccc1f..0c814f251fe 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts
@@ -125,6 +125,11 @@ assert.ok(qwen21);
assert.equal(qwen21.canonicalId, "unsloth/Qwen-Image-2.1");
assert.equal(groupForRepoId("unsloth/Qwen-Image-2.1-FP8", IMAGE_CATALOG), qwen21);
assert.equal(groupForRepoId("unsloth/Qwen-Image-2.1-INT8", IMAGE_CATALOG), qwen21);
+// Turbo is its own group, prequant repo included: its checkpoints are baked from a different denoiser.
+const qwen21Turbo = groupForRepoId("Qwen/Qwen-Image-2.1-Turbo", IMAGE_CATALOG);
+assert.ok(qwen21Turbo);
+assert.equal(qwen21Turbo.canonicalId, "Qwen/Qwen-Image-2.1-Turbo");
+assert.equal(groupForRepoId("unsloth/Qwen-Image-2.1-Turbo-FP8", IMAGE_CATALOG), qwen21Turbo);
assert.notEqual(groupForRepoId("Qwen/Qwen-Image", IMAGE_CATALOG), qwen21);
assert.equal(
groupForRepoId("Qwen/Qwen-Image", IMAGE_CATALOG)?.canonicalId,
@@ -1181,6 +1186,8 @@ const PREQUANT_ROWS = [
["Qwen/Qwen-Image-2512", "unsloth/Qwen-Image-2512-FP8"],
["black-forest-labs/FLUX.1-schnell", "unsloth/FLUX.1-schnell-FP8"],
["krea/Krea-2-Turbo", "unsloth/Krea-2-Turbo-FP8"],
+ ["Qwen/Qwen-Image-2.1", "unsloth/Qwen-Image-2.1-FP8"],
+ ["Qwen/Qwen-Image-2.1-Turbo", "unsloth/Qwen-Image-2.1-Turbo-FP8"],
] as const;
for (const [id, repo] of PREQUANT_ROWS) {
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
index b6f3811f0a1..59cec446352 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
@@ -253,6 +253,22 @@ export const IMAGE_CATALOG: CatalogGroup[] = [
gguf("unsloth/Qwen-Image-2.1-GGUF"),
],
},
+ {
+ // A different denoiser with its own FP8/INT8 checkpoints; no unsloth mirror, so the vendor pipeline is the row.
+ canonicalId: "Qwen/Qwen-Image-2.1-Turbo",
+ displayName: "Qwen-Image 2.1 Turbo",
+ description: "Text-to-image and image editing in 8 steps",
+ scope: "image",
+ // Same reason as 2.1's alias: the int8 half of the prequant repo has no artifact row.
+ aliases: ["unsloth/Qwen-Image-2.1-Turbo-FP8"],
+ artifacts: [
+ bf16Pipeline("Qwen/Qwen-Image-2.1-Turbo", 33, {
+ totalParams: 7115124736,
+ prequantRepo: "unsloth/Qwen-Image-2.1-Turbo-FP8",
+ prequantSizeGb: { fp8: 7.12, int8: 7.26 },
+ }),
+ ],
+ },
{
canonicalId: "unsloth/Qwen-Image-2512",
displayName: "Qwen-Image 2512",
diff --git a/studio/frontend/tests/image-generation-defaults.test.ts b/studio/frontend/tests/image-generation-defaults.test.ts
index 0bb5a44cab1..73924ff0031 100644
--- a/studio/frontend/tests/image-generation-defaults.test.ts
+++ b/studio/frontend/tests/image-generation-defaults.test.ts
@@ -191,6 +191,25 @@ test("every Qwen-Image-Layered spelling the backend accepts gets its 20 / 2.5 re
}
});
+test("every Qwen-Image-2.1 spelling gets Turbo's 8 / 1 recipe when it names Turbo, and the base keeps 25", () => {
+ for (const id of [
+ "Qwen/Qwen-Image-2.1-Turbo",
+ "/models/qwen-image-21-turbo",
+ "/models/qwen_image_21_turbo",
+ "/models/qwen-image-21_turbo",
+ "/models/qwenimage21-turbo",
+ "/models/qwenimage21_turbo",
+ "/models/qwenimage21turbo",
+ "/models/qwenimage21turbo-Q4_K_M.gguf",
+ "/models/qwen_image_2.1_turbo_Q4_K_M.gguf",
+ ]) {
+ assert.deepEqual(defaultsFor(id), { steps: 8, guidance: 1 }, id);
+ }
+ for (const id of ["Qwen/Qwen-Image-2.1", "/models/qwen_image_21", "/models/qwenimage21", "/models/qwen_image_2.1.gguf"]) {
+ assert.deepEqual(defaultsFor(id), { steps: 25, guidance: 1 }, id);
+ }
+});
+
test("a community single file picked by path takes its family recipe once loaded (#11391)", () => {
const pick = defaultsFor(defaultsKeyFor("/models/checkpoints/RealVisXL_V4.0.safetensors", null));
const resident = residentDefaultsKey(