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 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.pyindex 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_renderfrom .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 slotinstall_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.pynew file mode 100644index 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.pynew file mode 100644index 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}