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: 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.pyindex 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 thEngaged 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 Nonediff --git a/studio/backend/tests/test_diffusion_zimage_cfg_split.py b/studio/backend/tests/test_diffusion_zimage_cfg_split.pyindex 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 beforeassert 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