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: MOSS-Image GGUF path follows the per-checkpoint negative-branch skip (#16255)

Daniel Han84e32b7bc6d4
diff --git a/studio/backend/core/inference/sd_cpp_args.py b/studio/backend/core/inference/sd_cpp_args.py
index 35030b17212..c5f96efdeec 100644
--- a/studio/backend/core/inference/sd_cpp_args.py
+++ b/studio/backend/core/inference/sd_cpp_args.py
@@ -7,6 +7,7 @@ tests need no GPU, binary, or model files"""
from __future__ import annotations
import functools
+import os
from collections.abc import Sequence
from dataclasses import dataclass, field
from typing import Optional
@@ -417,6 +418,36 @@ METAL_MMAP_MIN_BUILD = 907
_INSTALL_RECORD = ".unsloth-sd-cpp-install.json"
+# MOSS-Image negative-branch skip, matching diffusion_moss_image.reference_uncond_skip: SFT skips nothing; Base skips
+# block 22 while sigma-percent is in 0 .. 0.5 (shift 5: steps 0-12 of 25). Builds without these --extra-sample-args keys
+# ignore them and keep sd.cpp's default (block 22 every step); UNSLOTH_MOSS_REFERENCE_SKIP=0 sends nothing.
+MOSS_REFERENCE_SKIP_ENV = "UNSLOTH_MOSS_REFERENCE_SKIP"
+MOSS_BASE_UNCOND_SKIP_END = 0.5
+
+
+def moss_is_base_checkpoint(*identities: Optional[str]) -> bool:
+ """True when any repo id / folder / filename spells MOSS-Image-Base (separators folded); else the SFT default."""
+ for identity in identities:
+ folded = "".join(c for c in str(identity or "").lower() if c.isalnum())
+ if "mossimagebase" in folded:
+ return True
+ return False
+
+
+def moss_uncond_skip_sample_args(*identities: Optional[str]) -> Optional[str]:
+ """sd.cpp ``extra_sample_args`` for a MOSS-Image checkpoint, or None for the binary's every-step default."""
+ if (os.environ.get(MOSS_REFERENCE_SKIP_ENV) or "").strip().lower() in (
+ "0",
+ "off",
+ "false",
+ "no",
+ ):
+ return None
+ if moss_is_base_checkpoint(*identities):
+ return f"moss_uncond_skip_start=0,moss_uncond_skip_end={MOSS_BASE_UNCOND_SKIP_END:g}"
+ return "moss_uncond_skip=false"
+
+
def sd_cpp_build_number(tag: Optional[str]) -> Optional[int]:
"""``N`` of a ``master-N-<sha>[-u<sha>]`` release tag, else None."""
import re
@@ -1021,6 +1052,7 @@ def build_img_gen_request(
qwen_image_layers: Optional[int] = None,
custom_sigmas: Optional[list[float]] = None,
hires: Optional[dict] = None,
+ extra_sample_args: Optional[str] = None,
) -> dict:
"""Guidance is split: FLUX distilled values go to distilled_guidance, real CFG scales to txt_cfg."""
if not str(prompt).strip():
@@ -1044,6 +1076,8 @@ def build_img_gen_request(
sample_params["custom_sigmas"] = [float(s) for s in custom_sigmas]
if guidance:
sample_params["guidance"] = guidance
+ if extra_sample_args:
+ sample_params["extra_sample_args"] = str(extra_sample_args)
req: dict = {
"prompt": prompt,
diff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.py
index 9cc7f868491..a1b316c0930 100644
--- a/studio/backend/core/inference/sd_cpp_backend.py
+++ b/studio/backend/core/inference/sd_cpp_backend.py
@@ -45,6 +45,7 @@ from core.inference.diffusion_device import (
from core.inference.diffusion_families import (
krea2_raw_checkpoint,
krea2_sd_cpp_flow_shift,
+ MOSS_IMAGE_FAMILY_NAME,
DIFFUSION_CANCELLED_MSG,
DIFFUSION_NOT_LOADED_MSG,
DiffusionFamily,
@@ -2927,6 +2928,18 @@ def _estimate_eta(total_steps: int, step: int, first_step_at: float, now: float)
return max(0.0, (total_steps - step) * per_step)
+def _request_extra_sample_args(state: Any) -> Optional[str]:
+ """Per-checkpoint ``extra_sample_args``: only MOSS-Image sends any (its negative-branch skip window)."""
+ if getattr(getattr(state, "family", None), "name", None) != MOSS_IMAGE_FAMILY_NAME:
+ return None
+ return sd_cpp_args_mod.moss_uncond_skip_sample_args(
+ getattr(state, "repo_id", None),
+ getattr(state, "display_repo_id", None),
+ getattr(state, "base_repo", None),
+ getattr(state, "gguf_filename", 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."""
if getattr(state.family, "name", None) == "krea-2" and krea2_raw_checkpoint(
@@ -4841,6 +4854,7 @@ class SdCppDiffusionBackend:
],
qwen_image_layers = layers,
hires = hires_payload,
+ extra_sample_args = _request_extra_sample_args(state),
)
try:
blobs = state.server.img_gen(
@@ -5150,6 +5164,9 @@ class SdCppDiffusionBackend:
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)]
+ extra_sample_args = _request_extra_sample_args(state)
+ if extra_sample_args:
+ extra_args += ["--extra-sample-args", extra_sample_args]
images = []
seeds: list[int] = []
diff --git a/studio/backend/tests/test_diffusion_more_families.py b/studio/backend/tests/test_diffusion_more_families.py
index 82b85a52cf4..231ce39992a 100644
--- a/studio/backend/tests/test_diffusion_more_families.py
+++ b/studio/backend/tests/test_diffusion_more_families.py
@@ -769,7 +769,7 @@ def test_the_pinned_prebuilt_is_one_that_can_load_qwen_image_21():
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
- assert module.DEFAULT_TAG == "master-982-0518b34-ud331c66", (
+ assert module.DEFAULT_TAG == "master-982-0518b34-uaba3a1c", (
"the pinned prebuilt must be one built from a tree carrying Qwen-Image-2.1, FLUX.3 and MOSS-Image; "
f"{module.DEFAULT_TAG} is not"
)
diff --git a/studio/backend/tests/test_sd_cpp_args.py b/studio/backend/tests/test_sd_cpp_args.py
index 5bff66dd158..0266d00f1db 100644
--- a/studio/backend/tests/test_sd_cpp_args.py
+++ b/studio/backend/tests/test_sd_cpp_args.py
@@ -1058,9 +1058,10 @@ def _all_builders(binary, extra_args = None):
@pytest.mark.parametrize(
"tag, expected",
[
- ("master-982-0518b34-ud331c66", True), # the pinned bundle
- ("master-968-8cd731e-ubdb47d1", True), # the previous pin
- ("master-951-f89d9b1-uafac7a7", True), # the pin before it
+ ("master-982-0518b34-uaba3a1c", True), # the pinned bundle
+ ("master-982-0518b34-ud331c66", True), # the previous pin
+ ("master-968-8cd731e-ubdb47d1", True), # the pin before it
+ ("master-951-f89d9b1-uafac7a7", True), # an older pin
("master-907-500ef5f", True), # the build that merged #2037
("master-906-abcdef0", False), # --mmap there hands Metal an unaddressable CPU buffer
("master-813-bfbef5b-u6321a69", False),
diff --git a/studio/backend/tests/test_sd_cpp_install_verify.py b/studio/backend/tests/test_sd_cpp_install_verify.py
index 6d53a8f8079..49a161e7a02 100644
--- a/studio/backend/tests/test_sd_cpp_install_verify.py
+++ b/studio/backend/tests/test_sd_cpp_install_verify.py
@@ -98,7 +98,7 @@ def _managed_root(tmp_path, monkeypatch) -> Path:
def _working_vulkan_install(root: Path) -> Path:
"""What the affected host had: the mirror's Vulkan build in its versioned subdirectory."""
- sub = root / "sd-master-982-0518b34-ud331c66-bin-win-vulkan-x64"
+ sub = root / "sd-master-982-0518b34-uaba3a1c-bin-win-vulkan-x64"
sub.mkdir()
for name in (_CLI, _SERVER):
(sub / name).write_bytes(_starting_binary())
@@ -311,14 +311,14 @@ def test_the_refusal_record_survives_a_fallback_from_another_release(
monkeypatch,
{"rocm": _bundle(_refused_binary()), "vulkan": _bundle(_starting_binary(), "vk/")},
)
- monkeypatch.setattr(sdmod, "_pinned_tag", lambda: "master-982-0518b34-ud331c66")
+ monkeypatch.setattr(sdmod, "_pinned_tag", lambda: "master-982-0518b34-uaba3a1c")
monkeypatch.setattr(backend, "_managed_tree_in_use", lambda: False)
monkeypatch.setattr(backend, "is_managed_binary", lambda _b: True)
server = backend.ensure_sd_server_binary(accelerator = "rocm")
assert server is not None
- assert sdmod.read_install_record(root).get("tag") != "master-982-0518b34-ud331c66"
+ assert sdmod.read_install_record(root).get("tag") != "master-982-0518b34-uaba3a1c"
assert backend.accelerator_runtime_failed("rocm") is True
assert backend.preferred_accelerator("rocm") == "vulkan"
diff --git a/studio/backend/tests/test_sd_cpp_moss_uncond_skip.py b/studio/backend/tests/test_sd_cpp_moss_uncond_skip.py
new file mode 100644
index 00000000000..73a0077f07e
--- /dev/null
+++ b/studio/backend/tests/test_sd_cpp_moss_uncond_skip.py
@@ -0,0 +1,144 @@
+# 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) MOSS-Image negative-branch skip per checkpoint, on both transports: SFT sends
+moss_uncond_skip=false, Base the sigma-percent window 0 .. 0.5, the kill switch and every other family nothing."""
+
+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 (
+ MOSS_REFERENCE_SKIP_ENV,
+ SdCppModelFiles,
+ build_img_gen_request,
+ moss_is_base_checkpoint,
+ moss_uncond_skip_sample_args,
+)
+from core.inference.sd_cpp_backend import SdCppDiffusionBackend
+
+from .test_sd_cpp_backend import _FakeEngine, _FakeServer
+
+SFT_ARGS = "moss_uncond_skip=false"
+BASE_ARGS = "moss_uncond_skip_start=0,moss_uncond_skip_end=0.5"
+FILES = SdCppModelFiles(
+ diffusion_model = "/m/model.gguf",
+ vae = "/m/vae/diffusion_pytorch_model.safetensors",
+ llm = "/m/Qwen3.5-9B-Q8_0.gguf",
+ tokenizer = "/m/tokenizer/tokenizer.json",
+)
+
+
[email protected](autouse = True)
+def _no_kill_switch(monkeypatch):
+ monkeypatch.delenv(MOSS_REFERENCE_SKIP_ENV, raising = False)
+
+
+def _state(
+ repo,
+ gguf,
+ *,
+ mode = "oneshot",
+ server = None,
+ base_repo = None,
+):
+ fam = detect_family_for_pick(repo, gguf, None)
+ return bk._SdState(
+ repo_id = repo,
+ base_repo = base_repo or fam.base_repo,
+ family = fam,
+ device = "cpu",
+ files = FILES,
+ sampling_method = fam.sd_cpp_sampling_method,
+ flow_shift = fam.sd_cpp_flow_shift,
+ mode = mode,
+ server = server,
+ gguf_filename = gguf,
+ )
+
+
+def _server_sample_params(repo, gguf, **kw):
+ server = _FakeServer("sd-server")
+ b = SdCppDiffusionBackend(engine = _FakeEngine())
+ b._state = _state(repo, gguf, mode = "server", server = server, **kw)
+ b.generate(prompt = "p", steps = 25, guidance = 4.0, seed = 3)
+ return server.payloads[-1].get("sample_params") or {}
+
+
+def _oneshot_extra_args(repo, gguf, **kw):
+ engine = _FakeEngine()
+ b = SdCppDiffusionBackend(engine = engine)
+ b._state = _state(repo, gguf, **kw)
+ b.generate(prompt = "p", steps = 25, guidance = 4.0, seed = 3)
+ return list(engine.calls[-1][3].get("extra_args") or [])
+
+
+_SFT = ("unsloth/MOSS-Image-SFT-GGUF", "MOSS-Image-SFT-Q4_K_M.gguf")
+_BASE = ("unsloth/MOSS-Image-Base-GGUF", "MOSS-Image-Base-Q4_K_M.gguf")
+
+
+ "identities, base",
+ [
+ (("unsloth/MOSS-Image-Base-GGUF",), True),
+ (("OpenMOSS-Team/MOSS-Image-Base",), True),
+ (("me/my-moss", "moss_image_base-q8_0.gguf"), True),
+ (("unsloth/MOSS-Image-SFT-GGUF", "MOSS-Image-SFT-Q4_K_M.gguf"), False),
+ ((None, ""), False),
+ ],
+)
+def test_base_is_spelled_by_any_identity(identities, base):
+ assert moss_is_base_checkpoint(*identities) is base
+
+
+def test_policy_strings_and_kill_switch(monkeypatch):
+ assert moss_uncond_skip_sample_args(*_SFT) == SFT_ARGS
+ assert moss_uncond_skip_sample_args(*_BASE) == BASE_ARGS
+ for off in ("0", "off", "false", "No"):
+ monkeypatch.setenv(MOSS_REFERENCE_SKIP_ENV, off)
+ assert moss_uncond_skip_sample_args(*_SFT) is None
+ assert moss_uncond_skip_sample_args(*_BASE) is None
+
+
+def test_request_builder_only_adds_the_key_when_given():
+ assert "extra_sample_args" not in build_img_gen_request(prompt = "p", steps = 25).get(
+ "sample_params", {}
+ )
+ req = build_img_gen_request(prompt = "p", steps = 25, extra_sample_args = BASE_ARGS)
+ assert req["sample_params"]["extra_sample_args"] == BASE_ARGS
+
+
[email protected]("pick, expected", [(_SFT, SFT_ARGS), (_BASE, BASE_ARGS)])
+def test_server_body_carries_the_checkpoint_window(pick, expected):
+ assert _server_sample_params(*pick)["extra_sample_args"] == expected
+
+
[email protected]("pick, expected", [(_SFT, SFT_ARGS), (_BASE, BASE_ARGS)])
+def test_oneshot_argv_carries_the_checkpoint_window(pick, expected):
+ extra = _oneshot_extra_args(*pick)
+ i = extra.index("--extra-sample-args")
+ assert extra[i + 1] == expected
+ assert extra.count("--extra-sample-args") == 1
+
+
+def test_a_base_gguf_resolved_to_the_sft_base_repo_still_windows():
+ # The Base pick is recognised from its repo / filename even when base_repo resolved to the family's SFT base.
+ assert (
+ _server_sample_params(*_BASE, base_repo = "OpenMOSS-Team/MOSS-Image-SFT")["extra_sample_args"]
+ == BASE_ARGS
+ )
+
+
+def test_kill_switch_sends_nothing_on_both_transports(monkeypatch):
+ monkeypatch.setenv(MOSS_REFERENCE_SKIP_ENV, "0")
+ for pick in (_SFT, _BASE):
+ assert "extra_sample_args" not in _server_sample_params(*pick)
+ assert "--extra-sample-args" not in _oneshot_extra_args(*pick)
+
+
+def test_other_families_send_nothing():
+ pick = ("unsloth/Z-Image-Turbo-GGUF", "z-image-turbo-Q4_K_M.gguf")
+ assert "extra_sample_args" not in _server_sample_params(*pick)
+ assert "--extra-sample-args" not in _oneshot_extra_args(*pick)
diff --git a/studio/backend/tests/test_sd_cpp_vulkan_cpu_torch.py b/studio/backend/tests/test_sd_cpp_vulkan_cpu_torch.py
index ac200bcb42e..0d898ecb975 100644
--- a/studio/backend/tests/test_sd_cpp_vulkan_cpu_torch.py
+++ b/studio/backend/tests/test_sd_cpp_vulkan_cpu_torch.py
@@ -350,13 +350,13 @@ def test_selection_installs_the_vulkan_build(monkeypatch):
_PINNED_RELEASE_ASSETS = [
- "sd-master-982-0518b34-ud331c66-bin-Linux-Ubuntu-22.04-x86_64-cuda12.zip",
- "sd-master-982-0518b34-ud331c66-bin-Linux-Ubuntu-22.04-x86_64-vulkan.zip",
- "sd-master-982-0518b34-ud331c66-bin-Linux-Ubuntu-22.04-x86_64.zip",
- "sd-master-982-0518b34-ud331c66-bin-Linux-Ubuntu-24.04-aarch64.zip",
- "sd-master-982-0518b34-ud331c66-bin-win-cpu-x64.zip",
- "sd-master-982-0518b34-ud331c66-bin-win-cuda12-x64.zip",
- "sd-master-982-0518b34-ud331c66-bin-win-vulkan-x64.zip",
+ "sd-master-982-0518b34-uaba3a1c-bin-Linux-Ubuntu-22.04-x86_64-cuda12.zip",
+ "sd-master-982-0518b34-uaba3a1c-bin-Linux-Ubuntu-22.04-x86_64-vulkan.zip",
+ "sd-master-982-0518b34-uaba3a1c-bin-Linux-Ubuntu-22.04-x86_64.zip",
+ "sd-master-982-0518b34-uaba3a1c-bin-Linux-Ubuntu-24.04-aarch64.zip",
+ "sd-master-982-0518b34-uaba3a1c-bin-win-cpu-x64.zip",
+ "sd-master-982-0518b34-uaba3a1c-bin-win-cuda12-x64.zip",
+ "sd-master-982-0518b34-uaba3a1c-bin-win-vulkan-x64.zip",
]
@@ -366,9 +366,9 @@ _PINNED_RELEASE_ASSETS = [
(
"Linux",
"x86_64",
- "sd-master-982-0518b34-ud331c66-bin-Linux-Ubuntu-22.04-x86_64-vulkan.zip",
+ "sd-master-982-0518b34-uaba3a1c-bin-Linux-Ubuntu-22.04-x86_64-vulkan.zip",
),
- ("Windows", "AMD64", "sd-master-982-0518b34-ud331c66-bin-win-vulkan-x64.zip"),
+ ("Windows", "AMD64", "sd-master-982-0518b34-uaba3a1c-bin-win-vulkan-x64.zip"),
("Linux", "aarch64", None),
],
)
diff --git a/studio/install_sd_cpp_prebuilt.py b/studio/install_sd_cpp_prebuilt.py
index 5e3b821dcc5..9dfbf906a23 100644
--- a/studio/install_sd_cpp_prebuilt.py
+++ b/studio/install_sd_cpp_prebuilt.py
@@ -37,10 +37,11 @@ DEFAULT_REPO = "unslothai/stable-diffusion.cpp"
UPSTREAM_FALLBACK_REPO = "leejet/stable-diffusion.cpp"
# Pinned for reproducibility; UNSLOTH_SD_CPP_TAG overrides (empty tracks latest) and a missing tag falls back to latest. The -u<id> suffix is the mirror's patch set: an unpatched build aborts on the default --cfg-scale and on --vae-on-cpu, and quantizes MiniMax-H3's 1-D norms into an output uncorrelated with its own bf16 reference (leejet/stable-diffusion.cpp#1861, #1862, #1863).
# The base must carry every family's sd_cpp_arch_marker / sd_cpp_edit_marker: hosts the mirror does
-# not build (ROCm) install it from upstream. master-968, the previous base, predates MOSS-Image (master-975,
-# split-QKV GGUF loading in the same release); master-951 before it predated FLUX.3 Image Klein (master-968), and
-# master-813 Qwen-Image-2.1 (master-883) and its reference-alpha fix (master-896). CUDA bundles carry no CUDA runtime.
-DEFAULT_TAG = "master-982-0518b34-ud331c66"
+# not build (ROCm) install it from upstream. -ud331c66, the previous pin on this base, ignores the MOSS-Image
+# moss_uncond_skip* sample args; master-968 predates MOSS-Image (master-975, split-QKV GGUF loading in the same
+# release); master-951 before it predated FLUX.3 Image Klein (master-968), and master-813 Qwen-Image-2.1 (master-883)
+# and its reference-alpha fix (master-896). CUDA bundles carry no CUDA runtime.
+DEFAULT_TAG = "master-982-0518b34-uaba3a1c"
REPO = DEFAULT_REPO