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 negative-branch layer skip follows the reference workflows per checkpoint (#16127)

Daniel Hanb1e0b0072790
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index c3d255691eb..cd289d15160 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -9301,6 +9301,7 @@ class DiffusionBackend:
local_files_only = local_files_only,
text_encoder = pipe_kwargs.get("text_encoder"),
transformer = pipe_kwargs.get("transformer"),
+ checkpoint = base,
)
finally:
self._stop_load_prefetch()
@@ -11597,6 +11598,7 @@ class DiffusionBackend:
text_encoder = moss_te,
check_cancelled = check_cancelled,
local_files_only = local_files_only,
+ checkpoint = base,
)
check_cancelled()
pipe.to(device)
diff --git a/studio/backend/core/inference/diffusion_moss_image.py b/studio/backend/core/inference/diffusion_moss_image.py
index 46e796870f4..0e5909c0e47 100644
--- a/studio/backend/core/inference/diffusion_moss_image.py
+++ b/studio/backend/core/inference/diffusion_moss_image.py
@@ -36,6 +36,10 @@ QK_ROPE_ATTR = "_unsloth_moss_qk_rope"
# Kill switch for the per-render text-refiner cache (``refine_text``): 0 refines on every step like the reference.
TEXT_CACHE_ENV = "UNSLOTH_MOSS_TEXT_CACHE"
DEFAULT_UNCOND_SKIP_LAYERS = (22,)
+# SFT skips nothing; Base skips block 22 for the first half of the sigma schedule. Env 0 = block 22 every step.
+REFERENCE_SKIP_ENV = "UNSLOTH_MOSS_REFERENCE_SKIP"
+BASE_UNCOND_SKIP_END = 0.5
+_UNSET = object()
def _env_off(name: str) -> bool:
@@ -590,6 +594,30 @@ class MOSSImageScheduler(FlowMatchEulerDiscreteScheduler):
from diffusers import DiffusionPipeline # noqa: E402
+def is_base_checkpoint(identity: Optional[str]) -> bool:
+ folded = "".join(c for c in str(identity or "").lower() if c.isalnum())
+ return "mossimagebase" in folded
+
+
+def reference_uncond_skip(identity: Optional[str]) -> tuple[tuple[int, ...], float]:
+ """``(uncond_skip_layers, uncond_skip_end)`` for a checkpoint."""
+ if _env_off(REFERENCE_SKIP_ENV):
+ return DEFAULT_UNCOND_SKIP_LAYERS, 1.0
+ if is_base_checkpoint(identity):
+ return DEFAULT_UNCOND_SKIP_LAYERS, BASE_UNCOND_SKIP_END
+ return (), 1.0
+
+
+def percent_to_sigma(percent: float, shift: float) -> float:
+ """As ComfyUI ``ModelSamplingDiscreteFlow.percent_to_sigma`` (multiplier 1)."""
+ if percent <= 0.0:
+ return 1.0
+ if percent >= 1.0:
+ return 0.0
+ t = 1.0 - percent
+ return shift * t / (1 + (shift - 1) * t)
+
+
def _offloaded(module: Any) -> bool:
"""Accelerate / diffusers offload hooks move weights per call: the pre-refined text path calls a submodule outside
the forward, so an offloaded transformer keeps the reference per-step refine."""
@@ -735,7 +763,9 @@ class MOSSImagePipeline(DiffusionPipeline):
max_sequence_length = 4096,
output_type = "pil",
return_dict = True,
- uncond_skip_layers = DEFAULT_UNCOND_SKIP_LAYERS,
+ uncond_skip_layers = _UNSET,
+ uncond_skip_start = 0.0,
+ uncond_skip_end = None,
slg_layers = None,
slg_scale = 0.0,
slg_start = 0.0,
@@ -744,12 +774,25 @@ class MOSSImagePipeline(DiffusionPipeline):
callback_on_step_end: Optional[Callable] = None,
callback_on_step_end_tensor_inputs = ("latents",),
):
- """Generate images. ``uncond_skip_layers`` (default block 22) skips those zero-based blocks in the negative
- branch only (two forwards per step); None / () disables it. ``slg_layers`` with ``slg_scale > 0`` adds a third,
- skipped positive forward and the fp32 correction ``slg_scale * (cond - cond_skip)``. Both are active where
+ """Generate images. ``uncond_skip_layers`` skips those zero-based blocks in the negative branch only (two
+ forwards per step); None / () disables it. Unset: block 22, or ``reference_uncond_skip`` of the loader's
+ checkpoint. ``uncond_skip_start`` / ``uncond_skip_end`` bound it in sigma-percent. ``slg_layers`` with ``slg_scale > 0`` adds a third, skipped positive forward and the
+ fp32 correction ``slg_scale * (cond - cond_skip)``. Both are also gated by
``slg_start <= step_index / num_steps < slg_stop``."""
self._interrupt = False
depth = len(self.transformer.layers)
+ if uncond_skip_layers is _UNSET:
+ identity = getattr(self, "_unsloth_checkpoint", None)
+ if identity is None:
+ uncond_skip_layers, policy_end = DEFAULT_UNCOND_SKIP_LAYERS, 1.0
+ else:
+ uncond_skip_layers, policy_end = reference_uncond_skip(identity)
+ if uncond_skip_end is None:
+ uncond_skip_end = policy_end
+ if uncond_skip_end is None:
+ uncond_skip_end = 1.0
+ if not 0 <= uncond_skip_start <= uncond_skip_end <= 1:
+ raise ValueError("Require 0 <= uncond_skip_start <= uncond_skip_end <= 1.")
uncond_skip = _validate_skip_layers(uncond_skip_layers, depth, "uncond_skip_layers")
slg = _validate_skip_layers(slg_layers, depth, "slg_layers")
# Tuples, not frozensets: a CUDA graph keys plain values, not objects.
@@ -827,10 +870,21 @@ class MOSSImagePipeline(DiffusionPipeline):
self.scheduler.set_timesteps(num_inference_steps, device = device)
timesteps = self.scheduler.timesteps
num_steps = len(timesteps)
+ uncond_window = None
+ if uncond_skip_kw and (uncond_skip_start > 0 or uncond_skip_end < 1):
+ shift = float(getattr(self.scheduler.config, "shift", 5.0))
+ high = percent_to_sigma(uncond_skip_start, shift)
+ low = percent_to_sigma(uncond_skip_end, shift)
+ uncond_window = [
+ low <= sigma <= high for sigma in self.scheduler.sigmas[:num_steps].tolist()
+ ]
for step_index, timestep in enumerate(self.progress_bar(timesteps)):
if self._interrupt:
continue
skip_active = slg_start <= step_index / num_steps < slg_stop
+ uncond_skip_active = skip_active and (
+ uncond_window is None or uncond_window[step_index]
+ )
# CFG combines fp32 predictions, even when the DiT runs in bf16.
# return_dict=False: a CUDA-graph replay hands back a tuple, never a dataclass.
prediction = self.transformer(latents, timestep, **cond_kw, return_dict = False)[
@@ -839,7 +893,7 @@ class MOSSImagePipeline(DiffusionPipeline):
conditional = prediction
if do_cfg:
skip_kwargs = (
- {"skip_layers": uncond_skip_kw} if uncond_skip_kw and skip_active else {}
+ {"skip_layers": uncond_skip_kw} if uncond_skip_kw and uncond_skip_active else {}
)
uncond = self.transformer(
latents, timestep, **uncond_kw, **skip_kwargs, return_dict = False
@@ -1035,12 +1089,14 @@ def load_moss_image_pipeline(
local_files_only: bool = False,
check_cancelled: Optional[Callable[[], None]] = None,
vae_dtype: Any = None,
+ checkpoint: Optional[str] = None,
) -> MOSSImagePipeline:
"""A ready ``MOSSImagePipeline`` for ``repo_id`` (a repo id or a local diffusers folder), on CPU.
Loads safetensors and JSON only, per subfolder; the repo's ``pipeline_moss_image.py`` is never imported.
``transformer`` / ``text_encoder`` let a quantised or pre-cast build hand in a component. The VAE decodes in fp32
- unless ``vae_dtype`` says otherwise (the reference and ComfyUI's MOSS launcher both decode in fp32)."""
+ unless ``vae_dtype`` says otherwise (the reference and ComfyUI's MOSS launcher both decode in fp32). ``checkpoint``
+ (else ``repo_id``) picks SFT or Base skip defaults."""
check_cancelled = check_cancelled or (lambda: None)
check_cancelled()
assert_transformers_supported()
@@ -1075,13 +1131,15 @@ def load_moss_image_pipeline(
check_cancelled()
scheduler = MOSSImageScheduler.from_pretrained(repo_id, subfolder = "scheduler", **common)
logger.info("diffusion.moss_image: assembled pipeline from %s per component", repo_id)
- return MOSSImagePipeline(
+ pipe = MOSSImagePipeline(
transformer = transformer,
scheduler = scheduler,
text_encoder = text_encoder,
tokenizer = tokenizer,
vae = vae,
)
+ pipe._unsloth_checkpoint = str(checkpoint or repo_id)
+ return pipe
def in_tree_class(name: str) -> Optional[type]:
diff --git a/studio/backend/tests/test_diffusion_moss_image.py b/studio/backend/tests/test_diffusion_moss_image.py
index f6498549120..d13181df0b4 100644
--- a/studio/backend/tests/test_diffusion_moss_image.py
+++ b/studio/backend/tests/test_diffusion_moss_image.py
@@ -594,3 +594,132 @@ def test_step_callback_latents_are_bchw(pipelines):
callback_on_step_end = on_step,
)
assert shapes == [(1, 128, 2, 3)] * 2
+
+
+ "identity, expected",
+ [
+ ("OpenMOSS-Team/MOSS-Image-SFT", ((), 1.0)),
+ ("unsloth/MOSS-Image-SFT-FP8", ((), 1.0)),
+ ("/models/my-moss-folder", ((), 1.0)),
+ (None, ((), 1.0)),
+ ("OpenMOSS-Team/MOSS-Image-Base", ((22,), 0.5)),
+ ("unsloth/MOSS-Image-Base-FP8", ((22,), 0.5)),
+ ("/hub/models--OpenMOSS-Team--MOSS-Image-Base/snapshots/abc", ((22,), 0.5)),
+ ("moss_image_base", ((22,), 0.5)),
+ ],
+)
+def test_reference_uncond_skip_per_checkpoint(moss, monkeypatch, identity, expected):
+ monkeypatch.delenv(moss.REFERENCE_SKIP_ENV, raising = False)
+ assert moss.reference_uncond_skip(identity) == expected
+
+
+ "identity", ["OpenMOSS-Team/MOSS-Image-SFT", "OpenMOSS-Team/MOSS-Image-Base"]
+)
+def test_reference_skip_kill_switch_restores_block_22_always(moss, monkeypatch, identity):
+ monkeypatch.setenv(moss.REFERENCE_SKIP_ENV, "0")
+ assert moss.reference_uncond_skip(identity) == ((22,), 1.0)
+
+
+def test_percent_to_sigma_is_the_discrete_flow_formula(moss):
+ assert moss.percent_to_sigma(0.0, 5.0) == 1.0
+ assert moss.percent_to_sigma(1.0, 5.0) == 0.0
+ assert moss.percent_to_sigma(0.5, 5.0) == pytest.approx(2.5 / 3.0)
+ assert moss.percent_to_sigma(0.5, 1.0) == pytest.approx(0.5)
+
+
+def _uncond_skips(
+ moss,
+ transformer,
+ monkeypatch,
+ steps,
+ checkpoint,
+ schedule = "sgm_uniform",
+ **kwargs,
+):
+ """Negative-branch ``skip_layers`` per step."""
+ import torch
+
+ pipe = moss.MOSSImagePipeline(transformer, moss.MOSSImageScheduler(sigma_schedule = schedule))
+ pipe.set_progress_bar_config(disable = True)
+ if checkpoint is not None:
+ pipe._unsloth_checkpoint = checkpoint
+ calls = []
+
+ def spy(latents, *args, **kw):
+ calls.append(kw.get("skip_layers"))
+ return (torch.zeros_like(latents),)
+
+ monkeypatch.setattr(transformer, "forward", spy)
+ _, embeds, _ = _inputs(lengths = (9,), seed = 3)
+ _, negative, _ = _inputs(lengths = (4,), seed = 4)
+ pipe(
+ prompt_embeds = embeds,
+ negative_prompt_embeds = negative,
+ height = 32,
+ width = 32,
+ num_inference_steps = steps,
+ output_type = "latent",
+ generator = torch.Generator("cpu").manual_seed(0),
+ **kwargs,
+ )
+ monkeypatch.undo()
+ assert calls[0::2] == [None] * steps
+ return calls[1::2]
+
+
[email protected]("schedule", ["sgm_uniform", "training_grid"])
+def test_base_skips_block_22_for_the_first_half_of_sigma(
+ moss, transformers_pair, monkeypatch, schedule
+):
+ _, ours = transformers_pair
+ monkeypatch.delenv(moss.REFERENCE_SKIP_ENV, raising = False)
+ skips = _uncond_skips(moss, ours, monkeypatch, 25, "OpenMOSS-Team/MOSS-Image-Base", schedule)
+ assert skips == [(22,)] * 13 + [None] * 12
+
+
+def test_sft_skips_nothing_and_unknown_pipe_keeps_the_official_default(
+ moss, transformers_pair, monkeypatch
+):
+ _, ours = transformers_pair
+ monkeypatch.delenv(moss.REFERENCE_SKIP_ENV, raising = False)
+ assert _uncond_skips(moss, ours, monkeypatch, 4, "OpenMOSS-Team/MOSS-Image-SFT") == [None] * 4
+ assert _uncond_skips(moss, ours, monkeypatch, 4, None) == [(22,)] * 4
+
+
+ "checkpoint", ["OpenMOSS-Team/MOSS-Image-SFT", "OpenMOSS-Team/MOSS-Image-Base"]
+)
+def test_kill_switch_skips_block_22_every_step(moss, transformers_pair, monkeypatch, checkpoint):
+ _, ours = transformers_pair
+ monkeypatch.setenv(moss.REFERENCE_SKIP_ENV, "0")
+ skips = _uncond_skips(moss, ours, monkeypatch, 6, checkpoint)
+ assert skips == [(22,)] * 6
+
+
+def test_explicit_uncond_skip_arguments_win_over_the_checkpoint(
+ moss, transformers_pair, monkeypatch
+):
+ _, ours = transformers_pair
+ monkeypatch.delenv(moss.REFERENCE_SKIP_ENV, raising = False)
+ sft = "OpenMOSS-Team/MOSS-Image-SFT"
+ assert _uncond_skips(moss, ours, monkeypatch, 4, sft, uncond_skip_layers = [22]) == [(22,)] * 4
+ base = "OpenMOSS-Team/MOSS-Image-Base"
+ assert _uncond_skips(moss, ours, monkeypatch, 4, base, uncond_skip_end = 1.0) == [(22,)] * 4
+ with pytest.raises(ValueError):
+ _uncond_skips(moss, ours, monkeypatch, 2, base, uncond_skip_start = 0.6, uncond_skip_end = 0.5)
+
+
+def test_loader_records_the_checkpoint_and_diffusion_passes_the_base_repo(moss):
+ import inspect
+
+ assert "checkpoint" in inspect.signature(moss.load_moss_image_pipeline).parameters
+ assert "pipe._unsloth_checkpoint = str(checkpoint or repo_id)" in inspect.getsource(
+ moss.load_moss_image_pipeline
+ )
+ source = (_BACKEND / "core" / "inference" / "diffusion.py").read_text(encoding = "utf-8")
+ calls = source.split("load_moss_image_pipeline(")[1:]
+ calls = [c for c in calls if "dtype" in c.split(")")[0] or "dtype," in c[:200]]
+ assert len(calls) == 2
+ assert all("checkpoint = base," in c[:900] for c in calls)
diff --git a/studio/backend/tests/test_diffusion_moss_image_quant.py b/studio/backend/tests/test_diffusion_moss_image_quant.py
index 0badaf212f4..6b93b45ff27 100644
--- a/studio/backend/tests/test_diffusion_moss_image_quant.py
+++ b/studio/backend/tests/test_diffusion_moss_image_quant.py
@@ -303,7 +303,11 @@ def test_a_handed_in_encoder_gets_the_vision_drop_and_offload_guard(monkeypatch)
monkeypatch.setattr(
diffusers.AutoencoderKLFlux2, "from_pretrained", classmethod(lambda cls, *a, **k: "vae")
)
- monkeypatch.setattr(moss, "MOSSImagePipeline", lambda **kw: kw)
+
+ class Parts(dict):
+ """Components; accepts loader-set attributes."""
+
+ monkeypatch.setattr(moss, "MOSSImagePipeline", lambda **kw: Parts(kw))
encoder = Encoder()
parts = moss.load_moss_image_pipeline(
"OpenMOSS-Team/MOSS-Image-SFT",
@@ -314,6 +318,7 @@ def test_a_handed_in_encoder_gets_the_vision_drop_and_offload_guard(monkeypatch)
)
assert parts["text_encoder"] is encoder and encoder.visual is None
assert getattr(encoder.layer, "_unsloth_conv_guard", False)
+ assert parts._unsloth_checkpoint == "OpenMOSS-Team/MOSS-Image-SFT"
def test_tokenizer_class_comes_from_its_config(tmp_path, offline_empty):