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: Z-Image CFG split under static step skip and CFG-parallel (#14551)

Daniel Han6e63ceb60d86
diff --git a/studio/backend/core/inference/diffusion_zimage_cfg_split.py b/studio/backend/core/inference/diffusion_zimage_cfg_split.py
index 400805f36c2..029cd3a7fd1 100644
--- a/studio/backend/core/inference/diffusion_zimage_cfg_split.py
+++ b/studio/backend/core/inference/diffusion_zimage_cfg_split.py
@@ -18,8 +18,8 @@ bit-exact: a single sample with no mask can pick other attention / GEMM tiles th
Engaged per render (``render``: Studio knows the images per call, so ``2 * B`` samples is a guided call, ``B`` is not),
only on a resident denoiser: a block-streamed one would upload its weights twice per step, which costs more than the
-recompile. Declined per call under a step cache / static step skip (they key cond and uncond on the one batched call)
-and a CFG-parallel router. Kill switch: ``UNSLOTH_DIFFUSION_ZIMAGE_CFG_SPLIT=0``.
+recompile. Declined per call under a step cache and a static step skip that cannot key a step's two calls apart.
+Kill switch: ``UNSLOTH_DIFFUSION_ZIMAGE_CFG_SPLIT=0``.
"""
from __future__ import annotations
@@ -56,14 +56,25 @@ def _is_zimage(module: Any) -> bool:
return type(module).__name__ == _TRANSFORMER_CLASS
+def _skip_keys_calls_apart(skip: Any) -> bool:
+ """Whether a static step skip keys cond / uncond apart: without a step signal one shared counter advances twice."""
+ if not hasattr(skip, "plan"):
+ return False
+ if not skip.plan:
+ return True
+ return getattr(skip, "context", None) is None and bool(getattr(skip, "step_signal", False))
+
+
def _declined_now(module: Any) -> Optional[str]:
slots = getattr(module, "__dict__", {})
+ # FBCache keeps one residual per cache_context; two calls in one context would compare cond against uncond.
if getattr(module, "_unsloth_step_cache", None):
return "step cache"
- if getattr(slots.get("forward"), "_unsloth_outer_forward", False):
- return "static step skip"
- if getattr(module, "_unsloth_cfg_router", None) is not None:
- return "cfg parallel"
+ # A CFG-parallel router installed after the skip takes the forward slot.
+ for skip in (slots.get("_unsloth_static_skip"), slots.get("forward")):
+ if getattr(skip, "_unsloth_outer_forward", False) and not _skip_keys_calls_apart(skip):
+ return "static step skip without a per-step call order"
+ # No CFG-router decline: it pairs by first-tensor identity (a fresh timestep per call), so never pairs Z-Image.
if getattr(module, "training", False):
return "training"
return None
diff --git a/studio/backend/tests/test_diffusion_zimage_cfg_split.py b/studio/backend/tests/test_diffusion_zimage_cfg_split.py
index e06d4b97d28..7d03d727fe7 100644
--- a/studio/backend/tests/test_diffusion_zimage_cfg_split.py
+++ b/studio/backend/tests/test_diffusion_zimage_cfg_split.py
@@ -196,3 +196,129 @@ def test_not_zimage_and_uninstall_restores_the_class():
zs.uninstall_zimage_cfg_split(pipe)
assert cls.__dict__.get("__call__") is before
assert zs.zimage_cfg_split_status(pipe) == {"armed": False}
+
+
+def _denoise(
+ pipe,
+ model,
+ guided,
+ steps,
+ seed,
+ skip = None,
+ cond_len = 45,
+ neg_len = 9,
+):
+ """A Z-Image denoise loop as ZImagePipeline runs it: one transformer call per step (2 samples when guided), the
+ step-end callback after it. Returns the per-step noise predictions."""
+ from core.inference import diffusion_step_skip as ss
+
+ if skip is not None:
+ ss.reset_static_step_skip(pipe, steps, step_signal = True)
+ latent = _latent(seed)
+ cond, neg = _caption(cond_len, seed), _caption(neg_len, seed + 1)
+ preds = []
+ with zs.render(pipe, 1):
+ for i in range(steps):
+ t = torch.tensor([1.0 - i / steps])
+ if guided:
+ out = _run(model, [latent, latent.clone()], t.repeat(2), [cond, neg])
+ pred = out[0] + 2.0 * (out[0] - out[1])
+ else:
+ pred = _run(model, [latent], t, [cond])[0]
+ preds.append(pred)
+ latent = latent - pred / steps
+ if skip is not None:
+ ss.mark_step_end(pipe)
+ return preds
+
+
+def _static_pipe(compile_blocks):
+ from core.inference import diffusion_step_skip as ss
+
+ model = _model()
+ pipe = types.SimpleNamespace(transformer = model)
+ zs.install_zimage_cfg_split(pipe, offload_policy = "none")
+ if compile_blocks:
+ _compile_blocks(model)
+ settings = {"mode": "taylor1", "head": 0.2, "tail": 0.1, "every": 2, "min_steps": 12}
+ assert ss.install_static_step_skip(pipe, settings = settings) == "static"
+ return pipe, model, ss._find(pipe)
+
+
+def test_static_step_skip_splits_and_turning_cfg_on_compiles_nothing_new():
+ torch._dynamo.reset()
+ pipe, model, skip = _static_pipe(compile_blocks = True)
+ _denoise(pipe, model, False, 12, 0, skip)
+ warm = _graphs()
+ assert warm > 0
+ _denoise(pipe, model, True, 12, 1, skip)
+ assert _graphs() == warm
+ assert zs.zimage_cfg_split_status(pipe) == {"armed": True, "split": 12, "batched": 0}
+ assert skip.stats["skipped"] > 0
+
+
+def test_static_step_skip_split_matches_the_batched_schedule(monkeypatch):
+ """Same steps skipped, same predictions: the split only keys cond as ``#0`` and uncond as ``#1``."""
+ pipe, model, skip = _static_pipe(compile_blocks = False)
+ split = _denoise(pipe, model, True, 12, 2, skip)
+ split_stats = dict(skip.stats)
+ assert zs.zimage_cfg_split_status(pipe)["split"] == 12
+ zs.uninstall_zimage_cfg_split(pipe)
+ from core.inference import diffusion_step_skip as ss
+
+ ss.uninstall_static_step_skip(pipe)
+ monkeypatch.setenv(zs.ZIMAGE_CFG_SPLIT_ENV, "0")
+ pipe_b, model_b, skip_b = _static_pipe(compile_blocks = False)
+ batched = _denoise(pipe_b, model_b, True, 12, 2, skip_b)
+ assert split_stats["skipped"] == 2 * skip_b.stats["skipped"] > 0
+ assert split_stats["computed"] == 2 * skip_b.stats["computed"]
+ for s, b in zip(split, batched):
+ torch.testing.assert_close(s, b, atol = 1e-4, rtol = 1e-4)
+
+
+def test_static_step_skip_without_a_step_signal_keeps_the_batched_call():
+ from core.inference import diffusion_step_skip as ss
+
+ pipe, model, skip = _static_pipe(compile_blocks = False)
+ ss.reset_static_step_skip(pipe, 12, step_signal = False)
+ with zs.render(pipe, 1):
+ _run(model, *_guided_args(_latent(3), torch.tensor([0.4]), 45, 9, 3))
+ assert zs.zimage_cfg_split_status(pipe) == {"armed": True, "split": 0, "batched": 1}
+ from core.inference.diffusion_multigpu import CfgParallelRouter
+
+ model.__dict__["forward"] = CfgParallelRouter(model, primary = "cpu", secondary = "cpu")
+ with zs.render(pipe, 1):
+ _run(model, *_guided_args(_latent(3), torch.tensor([0.4]), 45, 9, 3))
+ assert zs.zimage_cfg_split_status(pipe) == {"armed": True, "split": 0, "batched": 2}
+ ss.reset_static_step_skip(pipe, 12, step_signal = True)
+ with zs.render(pipe, 1):
+ _run(model, *_guided_args(_latent(3), torch.tensor([0.4]), 45, 9, 3))
+ assert zs.zimage_cfg_split_status(pipe) == {"armed": True, "split": 1, "batched": 2}
+
+
+def test_cfg_parallel_router_splits_and_keeps_both_branches_on_the_primary():
+ from core.inference.diffusion_multigpu import CfgParallelRouter
+
+ torch._dynamo.reset()
+ model = _model()
+ pipe = types.SimpleNamespace(transformer = model)
+ zs.install_zimage_cfg_split(pipe, offload_policy = "none")
+ t = torch.tensor([0.4])
+ x, tt, cap = _guided_args(_latent(4), t, 45, 9, 4)
+ with zs.render(pipe, 1):
+ plain = _run(model, x, tt, cap)
+ _compile_blocks(model)
+ router = CfgParallelRouter(model, primary = "cpu", secondary = "cpu")
+ model.__dict__["forward"] = router
+ model._unsloth_cfg_router = router
+ with zs.render(pipe, 1):
+ _run(model, [_latent(0)], t, [_caption(9, 0)])
+ _run(model, [_latent(1)], t, [_caption(45, 1)])
+ warm = _graphs()
+ routed = _run(model, x, tt, cap)
+ _denoise(pipe, model, True, 3, 5)
+ assert _graphs() == warm
+ assert router.replica is None and router.stats["replica_calls"] == 0
+ for a, b in zip(routed, plain):
+ assert torch.equal(a, b)
+ assert zs.zimage_cfg_split_status(pipe)["batched"] == 0