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 sd.cpp: send the simple scheduler so flow families get the diffusers sigma grid (#17360)

Daniel Han49e0073bf072
diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.py
index 0243387449b..f0222b974b3 100644
--- a/studio/backend/core/inference/diffusion_families.py
+++ b/studio/backend/core/inference/diffusion_families.py
@@ -242,6 +242,12 @@ class DiffusionFamily:
# sd-cli defaults.
sd_cpp_sampling_method: Optional[str] = None
sd_cpp_flow_shift: Optional[float] = None
+ # sd-cli --scheduler; "simple" matches the diffusers grid (sd.cpp's default ends at sigma ~0.003). None = sd.cpp's.
+ sd_cpp_scheduler: Optional[str] = None
+ # (id substring, shift) overriding sd_cpp_flow_shift under sd_cpp_scheduler; first match wins, None = sd.cpp's.
+ sd_cpp_flow_shift_variants: tuple[tuple[str, Optional[float]], ...] = field(
+ default_factory = tuple
+ )
# Literal an sd.cpp build carries once it can run this family; matched against binary bytes
# since old runnable builds are never upgraded and release tags cannot answer it.
sd_cpp_arch_marker: Optional[str] = None
@@ -535,6 +541,13 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
controlnet_model_class = "FluxControlNetModel",
sd_cpp_vae = ("black-forest-labs/FLUX.1-schnell", "ae.safetensors"),
sd_cpp_text_encoders = _FLUX1_SD_CPP_TEXT_ENCODERS,
+ # schnell mu 0; dev rows (sd.cpp's mu 1.15) stop a dev GGUF matching a schnell id later in the list.
+ sd_cpp_scheduler = "simple",
+ sd_cpp_flow_shift_variants = tuple(
+ (f"{prefix}-{model}", shift)
+ for model, shift in (("schnell", 0.0), ("krea-dev", None), ("dev", None))
+ for prefix in ("flux.1", "flux1", "flux-1", "flux")
+ ),
),
# Must precede a generic flux match.
DiffusionFamily(
@@ -827,6 +840,7 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
# Native: FLUX.1's VAE + CLIP-L / T5-XXL, the source as a reference image (sd.cpp docs/kontext.md).
sd_cpp_vae = ("black-forest-labs/FLUX.1-schnell", "ae.safetensors"),
sd_cpp_text_encoders = _FLUX1_SD_CPP_TEXT_ENCODERS,
+ sd_cpp_scheduler = "simple",
),
DiffusionFamily(
# Specific aliases first so detect_family prefers this over qwen-image.
@@ -903,6 +917,7 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
),
sd_cpp_sampling_method = "euler",
sd_cpp_flow_shift = 3.0,
+ sd_cpp_scheduler = "simple",
),
DiffusionFamily(
# Listed before qwen-image so the name outranks it.
@@ -948,6 +963,7 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
),
sd_cpp_sampling_method = "euler",
sd_cpp_flow_shift = 1.0,
+ sd_cpp_scheduler = "simple",
# Layered support landed upstream in master-744 (556f04b); an older reused build has no such literal.
sd_cpp_arch_marker = "qwen_image_layers",
),
@@ -1016,6 +1032,7 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
# Qwen-Image's supported sd.cpp invocation (docs/qwen_image.md).
sd_cpp_sampling_method = "euler",
sd_cpp_flow_shift = 3.0,
+ sd_cpp_scheduler = "simple",
),
DiffusionFamily(
# Different architecture from qwen-image, so its own family.
@@ -1213,6 +1230,7 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
# (hidden_states[-2]) nor sd.cpp (out_layers {35}) reads, so the conditioning is the same. Same BF16 file
# klein 4B reads, so one download serves both.
sd_cpp_text_encoders = (("unsloth/Qwen3-4B-GGUF", "Qwen3-4B-BF16.gguf", "llm"),),
+ sd_cpp_scheduler = "simple",
),
DiffusionFamily(
name = "krea-2",
@@ -1245,6 +1263,7 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
sd_cpp_vae = ("unsloth/Krea-2-Turbo", "vae/diffusion_pytorch_model.safetensors"),
sd_cpp_text_encoders = _FLUX3_SD_CPP_TEXT_ENCODERS,
sd_cpp_sampling_method = "euler",
+ sd_cpp_scheduler = "simple",
sd_cpp_arch_marker = _KREA2_SD_CPP_ARCH_MARKER,
),
# HunyuanImage 2.1: 17B dual-stream DiT. HiDream-I1 repos lack text_encoder_4 (Llama-3.1-8B), loaded from the open unsloth mirror; one family for Full/Dev/Fast
@@ -1452,6 +1471,7 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
sd_cpp_tokenizer = ("unsloth/MOSS-Image-SFT-FP8", "tokenizer/tokenizer.json"),
# sd.cpp master-975 model_version_to_str name; its default flow shift is already 5.
sd_cpp_arch_marker = "MOSS-Image",
+ sd_cpp_scheduler = "simple",
),
# SDXL is the one U-Net family: the denoiser is ``pipe.unet`` and a single-file ``.safetensors`` is the WHOLE
# pipeline. img2img / inpaint / ControlNet are the standard SDXL pipelines. No GGUF path.
@@ -2266,6 +2286,11 @@ def comfy_flow_shift_for(fam: Any, *identifiers: Optional[str]) -> Optional[floa
return row[1] if row else getattr(fam, "comfy_flow_shift", None)
+def sd_cpp_flow_shift_for(fam: Any, *identifiers: Optional[str]) -> Optional[float]:
+ row = _first_variant(getattr(fam, "sd_cpp_flow_shift_variants", ()), identifiers)
+ return row[1] if row else getattr(fam, "sd_cpp_flow_shift", None)
+
+
# FLUX.3 single files and GGUFs can take the other variant's transformer config from the companion
# repo, so the family sets flow_map; a base file on the distilled config fails on meta tensors, and
# the reverse drops its weights.
diff --git a/studio/backend/core/inference/sd_cpp_args.py b/studio/backend/core/inference/sd_cpp_args.py
index 2df626dcdf5..6a2628ebc93 100644
--- a/studio/backend/core/inference/sd_cpp_args.py
+++ b/studio/backend/core/inference/sd_cpp_args.py
@@ -84,6 +84,7 @@ class SdCppGenParams:
guidance: Optional[float] = None
seed: Optional[int] = None
sampling_method: Optional[str] = None
+ scheduler: Optional[str] = None
batch_count: int = 1
init_img: Optional[str] = None
strength: Optional[float] = None
@@ -912,6 +913,8 @@ def build_sd_cpp_command(
cmd += ["--guidance", _fmt_float(params.guidance)]
if params.sampling_method:
cmd += ["--sampling-method", str(params.sampling_method)]
+ if params.scheduler:
+ cmd += ["--scheduler", str(params.scheduler)]
if params.seed is not None:
cmd += ["--seed", str(int(params.seed))]
if params.batch_count and params.batch_count != 1:
@@ -1151,6 +1154,7 @@ def build_img_gen_request(
seed: Optional[int] = None,
batch_count: int = 1,
sample_method: Optional[str] = None,
+ scheduler: Optional[str] = None,
flow_shift: Optional[float] = None,
cfg_scale: Optional[float] = None,
distilled_guidance: Optional[float] = None,
@@ -1177,6 +1181,8 @@ def build_img_gen_request(
sample_params["sample_steps"] = int(steps)
if sample_method:
sample_params["sample_method"] = str(sample_method)
+ if scheduler:
+ sample_params["scheduler"] = str(scheduler)
if flow_shift is not None:
sample_params["flow_shift"] = float(flow_shift)
if custom_sigmas:
@@ -1229,6 +1235,15 @@ H3_SERVER_REFS_ENV = "UNSLOTH_H3_SERVER_REFS"
_SD_CLI_FRAME_EXTS = (".jpg", ".jpeg", ".png", ".bmp", ".webp")
+# "0" = no family --scheduler / flow-shift variants (sd.cpp default schedule).
+FAMILY_SCHEDULER_ENV = "UNSLOTH_SD_CPP_FAMILY_SCHEDULER"
+
+
+def family_scheduler_enabled() -> bool:
+ value = os.environ.get(FAMILY_SCHEDULER_ENV, "").strip().lower()
+ return value not in ("0", "false", "no", "off")
+
+
def h3_server_refs_enabled() -> bool:
value = os.environ.get(H3_SERVER_REFS_ENV, "").strip().lower()
return value not in ("0", "false", "no", "off")
diff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.py
index f1477ec8a80..838a9755e5e 100644
--- a/studio/backend/core/inference/sd_cpp_backend.py
+++ b/studio/backend/core/inference/sd_cpp_backend.py
@@ -52,6 +52,7 @@ from core.inference.sd_cpp_multigpu import split_for_load
from core.inference.diffusion_families import (
krea2_raw_checkpoint,
krea2_sd_cpp_flow_shift,
+ sd_cpp_flow_shift_for,
MOSS_IMAGE_FAMILY_NAME,
DIFFUSION_CANCELLED_MSG,
DIFFUSION_NOT_LOADED_MSG,
@@ -2906,6 +2907,7 @@ class _SdState:
threads: Optional[int] = None
sampling_method: Optional[str] = None
flow_shift: Optional[float] = None
+ scheduler: Optional[str] = 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
@@ -3123,8 +3125,15 @@ def _request_extra_sample_args(state: Any) -> Optional[str]:
)
+def _request_scheduler(state: Any) -> Optional[str]:
+ """The family's ``--scheduler``; None under custom sigmas (they replace the schedule) or the kill switch."""
+ if getattr(state, "sample_sigmas", None) or not sd_cpp_args_mod.family_scheduler_enabled():
+ return None
+ return getattr(state, "scheduler", None)
+
+
def _request_flow_shift(state: Any, width: int, height: int) -> Optional[float]:
- """The family's fixed ``--flow-shift``, except Krea 2 Raw, whose mu follows the output size."""
+ """The family's ``--flow-shift``; Krea 2 Raw follows output size, variants apply under the family scheduler."""
if getattr(state.family, "name", None) == "krea-2" and krea2_raw_checkpoint(
state.gguf_filename,
getattr(state, "display_repo_id", None),
@@ -3132,6 +3141,14 @@ def _request_flow_shift(state: Any, width: int, height: int) -> Optional[float]:
state.base_repo,
):
return krea2_sd_cpp_flow_shift(width, height)
+ if _request_scheduler(state) and getattr(state.family, "sd_cpp_flow_shift_variants", ()):
+ # Not base_repo: an unnamed dev GGUF can fall back to the family's schnell base.
+ return sd_cpp_flow_shift_for(
+ state.family,
+ getattr(state, "gguf_filename", None),
+ getattr(state, "repo_id", None),
+ getattr(state, "display_repo_id", None),
+ )
return state.flow_shift
@@ -4110,6 +4127,7 @@ class SdCppDiffusionBackend:
threads = _default_threads(),
sampling_method = fam.sd_cpp_sampling_method,
flow_shift = fam.sd_cpp_flow_shift,
+ scheduler = fam.sd_cpp_scheduler,
sample_sigmas = sample_sigmas,
server = server,
mode = mode,
@@ -5077,6 +5095,7 @@ class SdCppDiffusionBackend:
seed = chunk_seed,
batch_count = count,
sample_method = state.sampling_method,
+ scheduler = _request_scheduler(state),
flow_shift = _request_flow_shift(state, int(width), int(height)),
custom_sigmas = (
sd_cpp_sample_sigmas(state.sample_sigmas, int(steps))
@@ -5503,6 +5522,7 @@ class SdCppDiffusionBackend:
guidance = flux_guidance,
seed = seed_i,
sampling_method = state.sampling_method,
+ scheduler = _request_scheduler(state),
batch_count = 1,
lora_dir = lora_dir,
lora_apply_mode = "auto" if lora_dir else None,
diff --git a/studio/backend/tests/test_sd_cpp_family_scheduler.py b/studio/backend/tests/test_sd_cpp_family_scheduler.py
new file mode 100644
index 00000000000..53467dfec25
--- /dev/null
+++ b/studio/backend/tests/test_sd_cpp_family_scheduler.py
@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Family sd.cpp --scheduler: the diffusers / baseline sigma grid on both transports, with its kill switch."""
+
+from __future__ import annotations
+
+import pytest
+
+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 (
+ FAMILY_SCHEDULER_ENV,
+ SdCppModelFiles,
+ build_sd_cpp_command,
+)
+from core.inference.sd_cpp_backend import SdCppDiffusionBackend
+
+from .test_sd_cpp_backend import _FakeEngine, _FakeServer
+
+CASES = [
+ ("unsloth/Z-Image-Turbo-GGUF", "z-image-turbo-Q4_K_M.gguf", "simple", None),
+ ("unsloth/MOSS-Image-SFT-GGUF", "MOSS-Image-SFT-Q8_0.gguf", "simple", None),
+ ("vantagewithai/Krea-2-Turbo-GGUF", "krea2_turbo-Q4_K_M.gguf", "simple", None),
+ ("unsloth/FLUX.1-schnell-GGUF", "flux1-schnell-Q2_K.gguf", "simple", 0.0),
+ ("unsloth/FLUX.1-dev-GGUF", "flux1-dev-Q4_K_M.gguf", "simple", None),
+ ("unsloth/Qwen-Image-GGUF", "qwen-image-Q4_K_M.gguf", "simple", 3.0),
+ # Qwen-Image-2.1 keeps sd.cpp's resolution-dependent official schedule.
+ ("unsloth/Qwen-Image-2.1-GGUF", "qwen-image-2.1-Q4_K_M.gguf", None, None),
+]
+FILES = SdCppModelFiles(diffusion_model = "/m/dit.gguf", vae = "/m/vae.safetensors", llm = "/m/te.gguf")
+
+
+def _state(
+ repo,
+ gguf,
+ *,
+ mode = "oneshot",
+ server = None,
+ grid = None,
+):
+ fam = detect_family_for_pick(repo, gguf, 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,
+ scheduler = fam.sd_cpp_scheduler,
+ sample_sigmas = grid,
+ mode = mode,
+ server = server,
+ gguf_filename = gguf,
+ )
+
+
+def _oneshot_argv(repo, gguf, **kw):
+ engine = _FakeEngine()
+ b = SdCppDiffusionBackend(engine = engine)
+ b._state = _state(repo, gguf, **kw)
+ b.generate(prompt = "p", steps = 8, guidance = 1.0, seed = 3)
+ files, params, out, extra = engine.calls[-1]
+ return build_sd_cpp_command(
+ "sd-cli", files, params, output_path = out, extra_args = list(extra.get("extra_args") or [])
+ )
+
+
+def _server_sample_params(repo, gguf):
+ server = _FakeServer("sd-server")
+ b = SdCppDiffusionBackend(engine = _FakeEngine())
+ b._state = _state(repo, gguf, mode = "server", server = server)
+ b.generate(prompt = "p", steps = 8, guidance = 1.0, seed = 3)
+ return server.payloads[-1]["sample_params"]
+
+
+def _flag(argv, name):
+ return argv[argv.index(name) + 1] if name in argv else None
+
+
[email protected]("repo,gguf,scheduler,shift", CASES)
+def test_oneshot_argv_carries_the_family_scheduler(repo, gguf, scheduler, shift):
+ argv = _oneshot_argv(repo, gguf)
+ assert _flag(argv, "--scheduler") == scheduler
+ got = _flag(argv, "--flow-shift")
+ assert (float(got) if got is not None else None) == shift
+
+
[email protected]("repo,gguf,scheduler,shift", CASES)
+def test_server_body_carries_the_family_scheduler(repo, gguf, scheduler, shift):
+ sp = _server_sample_params(repo, gguf)
+ assert sp.get("scheduler") == scheduler
+ assert sp.get("flow_shift") == shift
+
+
[email protected]("repo,gguf,scheduler,shift", CASES)
+def test_kill_switch_restores_sd_cpp_defaults(monkeypatch, repo, gguf, scheduler, shift):
+ monkeypatch.setenv(FAMILY_SCHEDULER_ENV, "0")
+ argv = _oneshot_argv(repo, gguf)
+ assert "--scheduler" not in argv
+ fam = detect_family_for_pick(repo, gguf, None)
+ got = _flag(argv, "--flow-shift")
+ assert (float(got) if got is not None else None) == fam.sd_cpp_flow_shift
+ assert "scheduler" not in _server_sample_params(repo, gguf)
+
+
+ "repo,scheduler",
+ [
+ ("black-forest-labs/FLUX.1-Kontext-dev", "simple"),
+ ("Qwen/Qwen-Image-Edit-2511", "simple"),
+ ("Qwen/Qwen-Image-Layered", "simple"),
+ ("black-forest-labs/FLUX.2-klein-4B", None),
+ ("black-forest-labs/FLUX.2-dev", None),
+ ("black-forest-labs/flux-3-image-klein", None),
+ ],
+)
+def test_edit_and_untouched_families(repo, scheduler):
+ assert detect_family_for_pick(repo, None, None).sd_cpp_scheduler == scheduler
+
+
+def test_a_shipped_grid_sends_no_scheduler():
+ argv = _oneshot_argv("unsloth/Z-Image-Turbo-GGUF", "z-image-turbo-Q4_K_M.gguf", grid = (1.0, 0.5))
+ assert "--scheduler" not in argv and "--sigmas" in argv
+
+
+def test_a_dev_gguf_never_takes_the_schnell_shift_from_its_base():
+ state = _state("someone/FLUX.1-dev-gguf", "model-Q4_K_M.gguf")
+ assert state.base_repo.lower().endswith("schnell")
+ assert bk._request_flow_shift(state, 1024, 1024) is None