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: 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.py
index 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_key
return _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, None
if 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.py
index 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 offlo
Under 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 two
calls (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.py
index 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 bg
model = _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