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: split guided Z-Image on the background-compile recording render (#15057)
Daniel Hanc785486f61df
diff --git a/studio/backend/core/inference/diffusion_bg_compile.py b/studio/backend/core/inference/diffusion_bg_compile.pyindex d1309ca6e42..7b2aeb010db 100644--- a/studio/backend/core/inference/diffusion_bg_compile.py+++ b/studio/backend/core/inference/diffusion_bg_compile.py@@ -76,6 +76,22 @@ def force_eager(on: bool = True):_FORCE_EAGER.reset(token)+def recording(module: Any) -> bool:+ """True when a call into ``module`` now records inputs for its pending background compile; callers that reshape+ compiled calls (Z-Image CFG split) must reshape this one too, or the compile builds a graph nothing runs."""+ if not eager_forced() or _NO_RECORD.get():+ return False+ for hook in tuple((getattr(module, "_forward_pre_hooks", None) or {}).values()):+ owner = getattr(hook, "__self__", None)+ if (+ isinstance(owner, BackgroundCompile)+ and owner.module is module+ and owner.wants_samples()+ ):+ return True+ return False++def _cuda_graph_helpers() -> tuple[Callable, Callable, Callable]:from .diffusion_cuda_graph import _flatten, _rebuild, graph_keyreturn _flatten, _rebuild, graph_key@@ -208,6 +224,13 @@ class BackgroundCompile:self.error = f"record: {type(exc).__name__}: {exc}"return None+ def wants_samples(self) -> bool:+ return (+ self.state == "recording"+ and len(self.samples) < self.max_samples+ and self._handle is not None+ )+def _remove_hook(self) -> None:handle, self._handle = self._handle, Noneif handle is not None:diff --git a/studio/backend/core/inference/diffusion_zimage_cfg_split.py b/studio/backend/core/inference/diffusion_zimage_cfg_split.pyindex 63008833fc9..3a58a80a4f1 100644--- a/studio/backend/core/inference/diffusion_zimage_cfg_split.py+++ b/studio/backend/core/inference/diffusion_zimage_cfg_split.py@@ -22,8 +22,9 @@ recompile. Group offload counts as resident (checked per call) while every offloUnder a CFG-parallel router the halves go to ``run_pair`` (identity pairing never matches fresh tensors). Kill switch: ``UNSLOTH_DIFFUSION_ZIMAGE_CFG_SPLIT=0``.Studio arms it ``compiled_only``: a render splits only while the denoiser runs compiled code or replays CUDA graphs,-checked per render since a deferred compile can engage after the load. An eager denoiser has no graph to keep, and-there the two serial calls cost more than one batched guided call (B200, eager, random weights: ~2x at 256px,+checked per render since a deferred compile can engage after the load. The eager render that records inputs for a+pending background compile splits too, so the compile builds the guidance-off batch graph the compiled renders run.+Any other eager denoiser has no graph to keep, and there the two serial calls cost more than one batched guided call (B200, eager, random weights: ~2x at 256px,~1.3-1.5x at 512px, parity at 1024px). An eager guided call that runs out of memory batched retries as the twocalls (half the activations) for the rest of that render. An active CFG-parallel router keeps the split eager too:its replica runs the guidance-off half concurrently, and it cannot pair one batched call. Graphs are read from the@@ -252,11 +253,20 @@ def _routed_now(slots: dict) -> bool:)+def _records_for_compile(denoiser: Any) -> bool:+ try:+ from .diffusion_bg_compile import recording+ return recording(denoiser)+ except Exception: # noqa: BLE001 - unknown: nothing records+ return False++def _eager_now(pipe: Any, denoiser: Any, slots: dict) -> bool:- """compiled_only with nothing compiled or graphed and no active router: the render stays batched (split on OOM)."""+ """compiled_only, nothing compiled/graphed/recording and no active router: stays batched (split on OOM)."""return (bool(slots.get(_COMPILED_ONLY_ATTR))and not _graphs_engaged(pipe, denoiser)+ and not _records_for_compile(denoiser)and not _routed_now(slots))diff --git a/studio/backend/tests/test_diffusion_zimage_cfg_split.py b/studio/backend/tests/test_diffusion_zimage_cfg_split.pyindex 6f746934166..945ded67631 100644--- a/studio/backend/tests/test_diffusion_zimage_cfg_split.py+++ b/studio/backend/tests/test_diffusion_zimage_cfg_split.py@@ -689,7 +689,7 @@ def test_compiled_only_ignores_a_poisoned_graph_handle():def test_compiled_only_honours_the_background_compile_eager_gate():- """A render recording for a pending background compile bypasses compiled calls and graphs: it runs batched."""+ """Eager-forced with nothing recording (compile already running): the guided call runs batched."""from core.inference import diffusion_bg_compile as bgmodel = _model()@@ -700,11 +700,65 @@ def test_compiled_only_honours_the_background_compile_eager_gate():with bg.force_eager(), zs.render(pipe, 1):_run(model, *args)assert zs.zimage_cfg_split_status(pipe)["split"] == 0+ rec = bg.BackgroundCompile(model)+ assert rec.install()+ rec.state = "compiling"+ with bg.force_eager():+ assert zs.guided_runs_at_guidance_off_batch(pipe) is False+ with zs.render(pipe, 1):+ _run(model, *args)+ assert zs.zimage_cfg_split_status(pipe)["split"] == 0 and rec.samples == []with zs.render(pipe, 1):_run(model, *args)assert zs.zimage_cfg_split_status(pipe)["split"] == 1+def test_background_compile_recording_render_splits_and_records_the_compiled_shape():+ """The recording render splits, so the compiled render after the background replay compiles nothing new."""+ from core.inference import diffusion_bg_compile as bg+ from core.inference.diffusion_cuda_graph import _rebuild++ torch._dynamo.reset()+ model = _model()+ pipe = types.SimpleNamespace(transformer = model)+ assert zs.install_zimage_cfg_split(pipe, offload_policy = "none", compiled_only = True) is None+ rec = bg.BackgroundCompile(model)+ assert rec.install()+ args = _guided_args(_latent(17), torch.tensor([0.4]), 9, 12, 17)+ with torch.no_grad():+ batched = model(*args, return_dict = False)[0]+ alone = (+ model(*[a[:1] for a in args], return_dict = False)[0]+ + model(*[a[1:] for a in args], return_dict = False)[0]+ )+ with bg.force_eager():+ priced_off = zs.guided_runs_at_guidance_off_batch(pipe)+ with zs.render(pipe, 1):+ recorded = [_run(model, *args) for _ in range(3)]+ shapes = sorted(tuple(c[0].shape) for _, c, *_ in rec.samples)+ stats = dict(zs.zimage_cfg_split_status(pipe))+ # What kick() runs: regional compile, then the recorded inputs.+ _compile_blocks(model)+ with torch.no_grad():+ for spec, clones, *_ in rec.samples:+ a, k = _rebuild(spec, clones)+ model(*a, **k)+ warm = _graphs()+ assert warm > 0+ with zs.render(pipe, 1):+ _run(model, *args)+ assert _graphs() - warm == 0+ assert zs.zimage_cfg_split_status(pipe)["split"] == 4+ assert stats == {"armed": True, "split": 3, "batched": 0}+ assert shapes == [(16, 1, 8, 8)] * 2+ assert priced_off is True+ for out in recorded:+ for s, a, b in zip(out, alone, batched):+ assert torch.equal(s, a)+ torch.testing.assert_close(s, b, atol = 1e-5, rtol = 1e-4)+ assert bg.recording(model) is False++def test_eager_render_behind_an_active_router_is_priced_and_run_split():"""Eager compiled_only behind an active router: priced guidance-off and keeps splitting if the router gives up."""from core.inference import diffusion_bg_compile as bg