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 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.pyindex 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] = Nonesd_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[floareturn 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.pyindex 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] = Noneseed: Optional[int] = Nonesampling_method: Optional[str] = None+ scheduler: Optional[str] = Nonebatch_count: int = 1init_img: Optional[str] = Nonestrength: 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.pyindex 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_loadfrom 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] = Nonesampling_method: Optional[str] = Noneflow_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, ...]] = Noneserver: 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.pynew file mode 100644index 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