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 guided steps run at the guidance-off batch so turning CFG on recompiles nothing (#14541)

Daniel Hanb6980ac370ee
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 20728730021..cade476a53d 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -109,6 +109,12 @@ from .diffusion_device import (
resolve_selected_cuda_ordinals,
)
from .diffusion_cfg_batch import cfg_batch_status, end_cfg_batch_render, install_cfg_batch
+from .diffusion_zimage_cfg_split import (
+ install_zimage_cfg_split,
+ uninstall_zimage_cfg_split,
+ zimage_cfg_split_status,
+)
+from .diffusion_zimage_cfg_split import render as zimage_cfg_split_render
from .diffusion_multigpu import (
AUTOMATIC_ORDINALS,
end_cfg_render,
@@ -9896,6 +9902,8 @@ class DiffusionBackend:
install_cfg_parallel(pipe, offload_policy = effective_policy, logger = logger)
# both branches through one offloaded forward; declines when CFG-parallel took the slot
install_cfg_batch(pipe, offload_policy = effective_policy, logger = logger)
+ # Z-Image guided steps at the guidance-off batch: turning CFG on compiles and records nothing new
+ install_zimage_cfg_split(pipe, offload_policy = effective_policy, logger = logger)
te_releaser = te_release.maybe_install(pipe, plan, logger = logger)
state = _LoadState(
pipe = pipe,
@@ -12874,6 +12882,7 @@ class DiffusionBackend:
),
protect_ctx,
denoise_phase(pipe, _enter_denoise_phase),
+ zimage_cfg_split_render(pipe, len(chunk)),
decode_phase(pipe, _enter_decode_phase),
_completed_step_poller(_pump),
):
@@ -13245,6 +13254,7 @@ class DiffusionBackend:
prebuild.cancel_all()
compile_cache.restore(state.compile_cache_ctx, logger = logger)
uninstall_cfg_parallel(state.pipe)
+ uninstall_zimage_cfg_split(state.pipe)
# Before clear_gpu_cache(), or the graph pool stays reserved for the life of the process.
cuda_graph.uninstall_all(state.cuda_graphs)
uninstall_static_step_skip(state.pipe)
@@ -13366,6 +13376,7 @@ class DiffusionBackend:
"transformer_cache_stats": static_skip_stats(state.pipe),
"multi_gpu": multigpu_placement_status(state.pipe),
"cfg_batch": cfg_batch_status(state.pipe),
+ "zimage_cfg_split": zimage_cfg_split_status(state.pipe),
"resolved": resolved,
"generation_defaults": _generation_defaults_for(
state.repo_id,
diff --git a/studio/backend/core/inference/diffusion_zimage_cfg_split.py b/studio/backend/core/inference/diffusion_zimage_cfg_split.py
new file mode 100644
index 00000000000..400805f36c2
--- /dev/null
+++ b/studio/backend/core/inference/diffusion_zimage_cfg_split.py
@@ -0,0 +1,217 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Z-Image guidance branches as two calls at the guidance-off batch, so turning CFG on compiles and records nothing.
+
+``ZImagePipeline`` (and its img2img / inpaint variants) batches a guided step into ONE transformer call of twice the
+samples: the latents repeated, the prompt embeddings followed by the negative ones. A session that rendered guidance 0
+first (Turbo's default) compiled the repeated block at one sample with no attention mask; the doubled call is a new
+batch (dynamo specialises size 1) and, whenever the two captions pad to different 32-token buckets, a mask that was None
+before, so the first guided render recompiled the block three times (one graph per block kind: noise refiner, context
+refiner, main layers) and recorded a new whole-step CUDA graph. Later guided prompts kept recompiling as their caption
+lengths moved between "same bucket as the negative" (no mask) and "other bucket" (mask).
+
+Here a guided call of ``2 * B`` samples runs as the conditional ``B`` then the unconditional ``B`` through the module's
+normal call (every forward layer, hook and graph sees an ordinary guidance-off call), and the two output lists are
+joined in the pipeline's order. Same math: the batched call masks the padding, the split one has none to mask. Not
+bit-exact: a single sample with no mask can pick other attention / GEMM tiles than the masked pair.
+
+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``.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import threading
+from typing import Any, Optional
+
+ZIMAGE_CFG_SPLIT_ENV = "UNSLOTH_DIFFUSION_ZIMAGE_CFG_SPLIT"
+_TRANSFORMER_CLASS = "ZImageTransformer2DModel"
+_STREAMED_POLICIES = ("group", "streaming", "sequential")
+# Instance attributes: armed at load, images per guidance-off call during a render, per-load counters.
+_ARMED_ATTR = "_unsloth_zimage_cfg_split"
+_SAMPLES_ATTR = "_unsloth_zimage_cfg_samples"
+_STATS_ATTR = "_unsloth_zimage_cfg_split_stats"
+# Keyword arguments a split call may carry (anything else, e.g. siglip / controlnet / noise masks, runs batched).
+_PLAIN_KWARGS = frozenset({"return_dict", "joint_attention_kwargs", "patch_size", "f_patch_size"})
+
+_LOCK = threading.Lock()
+_PATCHED: dict = {}
+
+
+def zimage_cfg_split_disabled() -> bool:
+ return (os.environ.get(ZIMAGE_CFG_SPLIT_ENV) or "").strip().lower() in (
+ "0",
+ "off",
+ "false",
+ "no",
+ )
+
+
+def _is_zimage(module: Any) -> bool:
+ return type(module).__name__ == _TRANSFORMER_CLASS
+
+
+def _declined_now(module: Any) -> Optional[str]:
+ slots = getattr(module, "__dict__", {})
+ 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"
+ if getattr(module, "training", False):
+ return "training"
+ return None
+
+
+def _halves(samples: int, args: tuple, kwargs: dict) -> Optional[tuple]:
+ """``(cond_args, uncond_args, kwargs)`` when this is a guided call of ``2 * samples`` plain samples, else None."""
+ if samples < 1 or len(args) != 3 or not set(kwargs) <= _PLAIN_KWARGS:
+ return None
+ x, t, cap = args
+ n = 2 * samples
+ if not isinstance(x, list) or not isinstance(cap, list) or len(x) != n or len(cap) != n:
+ return None
+ # Omni inputs are lists of lists per sample; this splits plain tensors only.
+ if not all(hasattr(v, "shape") for v in x) or not all(hasattr(v, "shape") for v in cap):
+ return None
+ shape = getattr(t, "shape", None)
+ if shape is None or len(shape) != 1 or shape[0] != n:
+ return None
+ return (
+ (x[:samples], t[:samples], cap[:samples]),
+ (x[samples:], t[samples:], cap[samples:]),
+ kwargs,
+ )
+
+
+def _join(a: Any, b: Any) -> Any:
+ if isinstance(a, tuple) and isinstance(b, tuple) and len(a) == len(b) and a:
+ return (list(a[0]) + list(b[0]),) + tuple(a[1:])
+ sample_a, sample_b = getattr(a, "sample", None), getattr(b, "sample", None)
+ if isinstance(sample_a, list) and isinstance(sample_b, list):
+ return type(a)(sample = sample_a + sample_b)
+ raise TypeError(f"unexpected Z-Image output {type(a).__name__}")
+
+
+def _make_call(orig_call: Any) -> Any:
+ def __call__(self, *args, **kwargs):
+ slots = getattr(self, "__dict__", {})
+ samples = slots.get(_SAMPLES_ATTR)
+ if not samples or not slots.get(_ARMED_ATTR):
+ return orig_call(self, *args, **kwargs)
+ parts = _halves(int(samples), args, kwargs)
+ stats = slots.get(_STATS_ATTR)
+ if parts is None:
+ return orig_call(self, *args, **kwargs)
+ if _declined_now(self) is not None:
+ if stats is not None:
+ stats["batched"] += 1
+ return orig_call(self, *args, **kwargs)
+ cond, uncond, kw = parts
+ out_cond = orig_call(self, *cond, **kw)
+ out_uncond = orig_call(self, *uncond, **kw)
+ if stats is not None:
+ stats["split"] += 1
+ return _join(out_cond, out_uncond)
+
+ __call__.__unsloth_zimage_cfg_split__ = True
+ return __call__
+
+
+def _patch_class(cls: Any) -> bool:
+ with _LOCK:
+ if cls in _PATCHED:
+ return True
+ own = cls.__dict__.get("__call__")
+ if getattr(own, "__unsloth_zimage_cfg_split__", False):
+ return True
+ # (the class's own __call__ or None when inherited, the patched one)
+ patched = _make_call(cls.__call__)
+ cls.__call__ = patched
+ _PATCHED[cls] = (own, patched)
+ return True
+
+
+def uninstall_zimage_cfg_split(pipe: Any = None) -> None:
+ """Disarm ``pipe.transformer`` and restore the class ``__call__`` (model unload). Idempotent."""
+ denoiser = getattr(pipe, "transformer", None) if pipe is not None else None
+ slots = getattr(denoiser, "__dict__", None)
+ if isinstance(slots, dict):
+ for name in (_ARMED_ATTR, _SAMPLES_ATTR, _STATS_ATTR):
+ slots.pop(name, None)
+ with _LOCK:
+ for cls, (own, patched) in list(_PATCHED.items()):
+ if cls.__dict__.get("__call__") is patched:
+ if own is None:
+ delattr(cls, "__call__")
+ else:
+ cls.__call__ = own
+ _PATCHED.pop(cls, None)
+
+
+def install_zimage_cfg_split(
+ pipe: Any,
+ *,
+ offload_policy: str,
+ logger: Any = None,
+) -> Optional[str]:
+ """Arm the split on ``pipe.transformer``; the decline reason, or None when armed. Never fails a load."""
+ try:
+ denoiser = getattr(pipe, "transformer", None)
+ if denoiser is None or not _is_zimage(denoiser):
+ return "not a Z-Image denoiser"
+ if zimage_cfg_split_disabled():
+ reason = f"{ZIMAGE_CFG_SPLIT_ENV}=0"
+ elif offload_policy in _STREAMED_POLICIES:
+ reason = (
+ f"denoiser is streamed ({offload_policy}): two calls would upload it twice per step"
+ )
+ else:
+ reason = None
+ if reason is None:
+ _patch_class(type(denoiser))
+ denoiser.__dict__[_ARMED_ATTR] = True
+ denoiser.__dict__[_STATS_ATTR] = {"split": 0, "batched": 0}
+ else:
+ denoiser.__dict__.pop(_ARMED_ATTR, None)
+ if logger is not None:
+ logger.info(
+ "diffusion.zimage_cfg_split: %s",
+ "armed (guided steps run as two calls at the guidance-off batch)"
+ if reason is None
+ else f"not armed ({reason})",
+ )
+ return reason
+ except Exception as exc: # noqa: BLE001 - an optional lever
+ if logger is not None:
+ logger.info("diffusion.zimage_cfg_split: not armed (%s: %s)", type(exc).__name__, exc)
+ return f"{type(exc).__name__}: {exc}"
+
+
+def zimage_cfg_split_status(pipe: Any) -> Optional[dict]:
+ denoiser = getattr(pipe, "transformer", None)
+ if denoiser is None or not _is_zimage(denoiser):
+ return None
+ slots = getattr(denoiser, "__dict__", {})
+ return {"armed": bool(slots.get(_ARMED_ATTR)), **dict(slots.get(_STATS_ATTR) or {})}
+
+
+def render(pipe: Any, samples: int):
+ """For one pipeline call whose guidance-off transformer call carries ``samples`` images."""
+ denoiser = getattr(pipe, "transformer", None)
+ armed = denoiser is not None and bool(getattr(denoiser, "__dict__", {}).get(_ARMED_ATTR))
+ if not armed:
+ yield
+ return
+ denoiser.__dict__[_SAMPLES_ATTR] = int(samples)
+ try:
+ yield
+ finally:
+ denoiser.__dict__.pop(_SAMPLES_ATTR, None)
diff --git a/studio/backend/tests/test_diffusion_zimage_cfg_split.py b/studio/backend/tests/test_diffusion_zimage_cfg_split.py
new file mode 100644
index 00000000000..e06d4b97d28
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_zimage_cfg_split.py
@@ -0,0 +1,198 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Tests for ``diffusion_zimage_cfg_split.py``: a guided Z-Image call after guidance-off ones compiles nothing new."""
+
+from __future__ import annotations
+
+import types
+
+import pytest
+
+from core.inference import diffusion_zimage_cfg_split as zs
+
+torch = pytest.importorskip("torch")
+zmod = pytest.importorskip("diffusers.models.transformers.transformer_z_image")
+
+_CONFIG = dict(
+ all_patch_size = (2,),
+ all_f_patch_size = (1,),
+ in_channels = 16,
+ dim = 32,
+ n_layers = 2,
+ n_refiner_layers = 1,
+ n_heads = 2,
+ n_kv_heads = 2,
+ norm_eps = 1e-5,
+ qk_norm = True,
+ cap_feat_dim = 16,
+ rope_theta = 256.0,
+ t_scale = 1000.0,
+ axes_dims = [8, 4, 4],
+ axes_lens = [512, 64, 64],
+)
+
+
[email protected](autouse = True)
+def _clean(monkeypatch):
+ monkeypatch.delenv(zs.ZIMAGE_CFG_SPLIT_ENV, raising = False)
+ yield
+ zs.uninstall_zimage_cfg_split()
+
+
+def _model():
+ torch.manual_seed(0)
+ return zmod.ZImageTransformer2DModel(**_CONFIG).eval()
+
+
+def _latent(seed):
+ g = torch.Generator().manual_seed(seed)
+ return torch.randn(16, 1, 8, 8, generator = g)
+
+
+def _caption(n, seed):
+ g = torch.Generator().manual_seed(1000 + seed)
+ return torch.randn(n, 16, generator = g)
+
+
+def _guided_args(latent, t, cond_len, neg_len, seed):
+ # What ZImagePipeline passes on a guided step: the latent repeated, the prompt then the negative embeddings.
+ return (
+ [latent, latent.clone()],
+ t.repeat(2),
+ [_caption(cond_len, seed), _caption(neg_len, seed + 1)],
+ )
+
+
+def _compile_blocks(model):
+ """Studio's regional compile: every repeated block's forward through one dynamic dynamo code object."""
+ for block in (*model.noise_refiner, *model.context_refiner, *model.layers):
+ block.forward = torch.compile(block.forward, backend = "eager", dynamic = True)
+
+
+def _graphs():
+ from torch._dynamo.utils import counters
+ return counters["stats"]["unique_graphs"]
+
+
+def _run(model, *args):
+ with torch.no_grad():
+ return model(*args, return_dict = False)[0]
+
+
+def test_guided_call_after_guidance_off_compiles_nothing_new():
+ torch._dynamo.reset()
+ model = _model()
+ pipe = types.SimpleNamespace(transformer = model)
+ assert zs.install_zimage_cfg_split(pipe, offload_policy = "none") is None
+ _compile_blocks(model)
+ t = torch.tensor([0.4])
+ with zs.render(pipe, 1):
+ # Guidance-off renders at two prompt lengths (two 32-token caption buckets).
+ _run(model, [_latent(0)], t, [_caption(9, 0)])
+ _run(model, [_latent(1)], t, [_caption(45, 1)])
+ warm = _graphs()
+ assert warm > 0
+ # CFG turned on: captions in different buckets (a mask when batched), then in the same bucket (no mask).
+ _run(model, *_guided_args(_latent(2), t, 45, 9, 2))
+ _run(model, *_guided_args(_latent(3), t, 7, 9, 3))
+ _run(model, *_guided_args(_latent(4), t, 70, 9, 4))
+ assert _graphs() == warm
+ assert zs.zimage_cfg_split_status(pipe) == {"armed": True, "split": 3, "batched": 0}
+
+
+def test_batched_guided_call_recompiles_without_the_split(monkeypatch):
+ """The defect the split removes: the doubled batch (and its attention mask) are new graphs."""
+ torch._dynamo.reset()
+ monkeypatch.setenv(zs.ZIMAGE_CFG_SPLIT_ENV, "0")
+ model = _model()
+ pipe = types.SimpleNamespace(transformer = model)
+ assert zs.install_zimage_cfg_split(pipe, offload_policy = "none") is not None
+ _compile_blocks(model)
+ t = torch.tensor([0.4])
+ with zs.render(pipe, 1):
+ _run(model, [_latent(0)], t, [_caption(9, 0)])
+ _run(model, [_latent(1)], t, [_caption(45, 1)])
+ warm = _graphs()
+ _run(model, *_guided_args(_latent(2), t, 45, 9, 2))
+ assert _graphs() > warm
+
+
+def test_split_output_is_each_branch_alone_and_matches_the_batched_call():
+ model = _model()
+ pipe = types.SimpleNamespace(transformer = model)
+ t = torch.tensor([0.4])
+ x, tt, cap = _guided_args(_latent(5), t, 45, 9, 5)
+ batched = _run(model, x, tt, cap)
+ alone = _run(model, x[:1], tt[:1], cap[:1]) + _run(model, x[1:], tt[1:], cap[1:])
+ zs.install_zimage_cfg_split(pipe, offload_policy = "none")
+ with zs.render(pipe, 1):
+ split = _run(model, x, tt, cap)
+ # return_dict=True (img2img / inpaint) joins the output dataclass the same way
+ with torch.no_grad():
+ split_dc = model(x, tt, cap).sample
+ assert len(split) == 2
+ for s, a, b, d in zip(split, alone, batched, split_dc):
+ assert torch.equal(s, a)
+ assert torch.equal(d, a)
+ torch.testing.assert_close(s, b, atol = 1e-5, rtol = 1e-4)
+
+
+def test_guidance_off_and_unarmed_calls_are_untouched():
+ model = _model()
+ pipe = types.SimpleNamespace(transformer = model)
+ zs.install_zimage_cfg_split(pipe, offload_policy = "none")
+ t = torch.tensor([0.4, 0.4])
+ x, cap = [_latent(6), _latent(7)], [_caption(9, 6), _caption(12, 7)]
+ with zs.render(pipe, 2):
+ # Two images per call with guidance off: one batched call, as before.
+ _run(model, x, t, cap)
+ # Outside a render, nothing splits.
+ _run(model, *_guided_args(_latent(8), torch.tensor([0.4]), 45, 9, 8))
+ assert zs.zimage_cfg_split_status(pipe)["split"] == 0
+
+
[email protected]("policy", ["group", "streaming", "sequential"])
+def test_streamed_denoiser_is_not_armed(policy):
+ pipe = types.SimpleNamespace(transformer = _model())
+ assert "streamed" in zs.install_zimage_cfg_split(pipe, offload_policy = policy)
+ assert zs.zimage_cfg_split_status(pipe)["armed"] is False
+
+
+def test_step_cache_and_step_skip_keep_the_batched_call():
+ model = _model()
+ pipe = types.SimpleNamespace(transformer = model)
+ zs.install_zimage_cfg_split(pipe, offload_policy = "none")
+ args = _guided_args(_latent(9), torch.tensor([0.4]), 45, 9, 9)
+ model._unsloth_step_cache = object()
+ with zs.render(pipe, 1):
+ _run(model, *args)
+ del model._unsloth_step_cache
+
+ class _Skip:
+ _unsloth_outer_forward = True
+
+ def __call__(self, *a, **k):
+ return type(model).forward(model, *a, **k)
+
+ model.__dict__["forward"] = _Skip()
+ with zs.render(pipe, 1):
+ _run(model, *args)
+ assert zs.zimage_cfg_split_status(pipe) == {"armed": True, "split": 0, "batched": 2}
+
+
+def test_not_zimage_and_uninstall_restores_the_class():
+ assert (
+ zs.install_zimage_cfg_split(
+ types.SimpleNamespace(transformer = torch.nn.Linear(2, 2)), offload_policy = "none"
+ )
+ == "not a Z-Image denoiser"
+ )
+ cls = zmod.ZImageTransformer2DModel
+ before = cls.__dict__.get("__call__")
+ pipe = types.SimpleNamespace(transformer = _model())
+ zs.install_zimage_cfg_split(pipe, offload_policy = "none")
+ assert getattr(cls.__dict__.get("__call__"), "__unsloth_zimage_cfg_split__", False)
+ zs.uninstall_zimage_cfg_split(pipe)
+ assert cls.__dict__.get("__call__") is before
+ assert zs.zimage_cfg_split_status(pipe) == {"armed": False}