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 Images: one denoiser stream-out per prompt encode, and the Z-Image CFG negative encoded once (#15310)

Daniel Han709cdc33f1ac
diff --git a/studio/backend/core/inference/diffusion_memory.py b/studio/backend/core/inference/diffusion_memory.py
index 0bc68d08773..0a4e62491f1 100644
--- a/studio/backend/core/inference/diffusion_memory.py
+++ b/studio/backend/core/inference/diffusion_memory.py
@@ -5458,13 +5458,18 @@ def _is_text_encoder_module(pipe: Any, module: Any) -> bool:
return False
+# "0": pin the denoiser back after every text encoder instead of once per encode_prompt call.
+ENCODE_RELEASE_ONCE_ENV = "UNSLOTH_DIFFUSION_ENCODE_RELEASE_ONCE"
+
+
def install_encode_release(
pipe: Any,
plan: Any,
logger: Any = None,
) -> int:
"""While a text encoder runs, stream the whole-resident (or widened partial) denoiser back to the flat room (the
- partial placement's encode state); pin it back on return. Returns the number of encoders hooked."""
+ partial placement's encode state); pin it back on return, or once encode_prompt returns (one move per prompt with
+ several encoders). Returns the number of encoders hooked."""
estimates = getattr(plan, "estimates", None) or {}
encode_room = estimates.get("encode_resident_transformer_mib")
whole = getattr(plan, "resident_transformer_mib", None)
@@ -5495,13 +5500,21 @@ def install_encode_release(
# No empty_cache: the allocator frees cached segments and retries on OOM; flushing per prompt cost a sync.
pending.append(restore)
- def _after(module: Any, args: Any, output: Any) -> None:
+ # encode_prompt calls in flight: their encoders keep one release and the outermost return pins back
+ scope = [0]
+
+ def _restore_pending() -> None:
if not pending:
return
restore = pending.pop()
if restore is not None:
restore()
+ def _after(module: Any, args: Any, output: Any) -> None:
+ if scope[0] > 0:
+ return # the next encoder of this prompt reuses the room; encode_prompt's return pins back
+ _restore_pending()
+
before = disable(_before) if callable(disable) else _before
after = disable(_after) if callable(disable) else _after
hooked = 0
@@ -5515,6 +5528,29 @@ def install_encode_release(
)
module._unsloth_encode_release = handles
hooked += 1
+ encode = getattr(pipe, "encode_prompt", None)
+ if (
+ hooked > 1
+ and callable(encode)
+ and not _env_off(ENCODE_RELEASE_ONCE_ENV)
+ and not getattr(encode, "_unsloth_encode_release_scope", False)
+ ):
+
+ @functools.wraps(encode)
+ def encode_prompt(*args: Any, **kwargs: Any) -> Any:
+ scope[0] += 1
+ try:
+ return encode(*args, **kwargs)
+ finally:
+ scope[0] -= 1
+ if scope[0] == 0:
+ _restore_pending()
+
+ encode_prompt._unsloth_encode_release_scope = True
+ try:
+ pipe.encode_prompt = encode_prompt
+ except Exception: # noqa: BLE001 - a read-only attribute keeps the per-encoder pin-back
+ pass
if hooked and logger is not None:
logger.info(
"diffusion.memory: the prompt encode streams %d MiB of the resident transformer (%d MiB stay), "
diff --git a/studio/backend/core/inference/diffusion_prompt_cache.py b/studio/backend/core/inference/diffusion_prompt_cache.py
index 1a759d4bf6e..54704c33d63 100644
--- a/studio/backend/core/inference/diffusion_prompt_cache.py
+++ b/studio/backend/core/inference/diffusion_prompt_cache.py
@@ -24,9 +24,12 @@ _DEFAULT_BUDGET_MB = 256
_FALSE_TOKENS = ("0", "false", "no", "off")
_KEY_EXCLUDED_ARGS = frozenset({"device", "generator"})
-# Wan encodes prompt and negative separately; caching per text reuses the unchanged negative. "0" = pair key only.
+# Cache the per-text helper so an unchanged CFG negative is reused across prompts. "0" = pair key only.
_ENV_PER_TEXT = "UNSLOTH_DIFFUSION_PROMPT_CACHE_PER_TEXT"
-_PER_TEXT_METHODS = {"Wan": "_get_t5_prompt_embeds"}
+_PER_TEXT_METHODS = {
+ "Wan": "_get_t5_prompt_embeds",
+ "ZImage": "_encode_prompt",
+}
_TEXT_ENCODER_ATTRS = ("text_encoder", "text_encoder_2", "text_encoder_3", "text_encoder_4")
diff --git a/studio/backend/tests/test_diffusion_measured_placement.py b/studio/backend/tests/test_diffusion_measured_placement.py
index 6c77e93d17c..2a5027549cd 100644
--- a/studio/backend/tests/test_diffusion_measured_placement.py
+++ b/studio/backend/tests/test_diffusion_measured_placement.py
@@ -862,6 +862,76 @@ def test_encode_release_keeps_an_oversized_release_streamed(monkeypatch):
assert torch.equal(net(x.cuda()).cpu(), ref)
+def _two_encoder_pipe(monkeypatch):
+ """FLUX.1-shaped: encode_prompt runs a small and a large encoder back to back (CLIP, then T5)."""
+ torch, net, enc, pipe, x, ref, on_device = _encode_release_pipe(monkeypatch)
+ enc2 = type(enc)()
+ pipe.components["text_encoder_2"] = enc2
+ calls = {"release": 0, "restore": 0}
+ real = dm.release_resident_groups
+
+ def counted(*args, **kwargs):
+ restore = real(*args, **kwargs)
+ if restore is None:
+ return None
+ calls["release"] += 1
+
+ def counted_restore(*a, **k):
+ calls["restore"] += 1
+ return restore(*a, **k)
+
+ return counted_restore
+
+ monkeypatch.setattr(dm, "release_resident_groups", counted)
+
+ def encode_prompt(prompt, fail = False):
+ enc(torch.randn(2, 8, device = "cuda"))
+ enc2.fail = fail
+ return enc2(torch.randn(2, 8, device = "cuda"))
+
+ pipe.encode_prompt = encode_prompt
+ return torch, net, enc, enc2, pipe, x, ref, on_device, calls
+
+
+def test_encode_release_streams_the_denoiser_once_per_prompt_with_two_encoders(monkeypatch):
+ """Two encoders in one encode_prompt: the denoiser moves out and back once, not once per encoder."""
+ torch, net, enc, enc2, pipe, x, ref, on_device, calls = _two_encoder_pipe(monkeypatch)
+ block_mib = 4
+ assert dm.install_encode_release(pipe, _whole_plan(1024, 1024 - 2 * block_mib), None) == 2
+ for prompt in range(3):
+ pipe.encode_prompt(f"p{prompt}")
+ assert enc.seen[-1] == ["cuda"] * 4 + ["cpu"] * 2
+ assert enc2.seen[-1] == ["cuda"] * 4 + ["cpu"] * 2
+ assert on_device() == ["cuda"] * 6
+ assert torch.equal(net(x.cuda()).cpu(), ref)
+ assert calls == {"release": 3, "restore": 3}
+ # outside encode_prompt: pins back on its own return
+ enc2(torch.randn(2, 8, device = "cuda"))
+ assert on_device() == ["cuda"] * 6
+ assert calls == {"release": 4, "restore": 4}
+
+
+def test_encode_release_once_restores_after_a_failed_second_encoder(monkeypatch):
+ torch, net, enc, enc2, pipe, x, ref, on_device, calls = _two_encoder_pipe(monkeypatch)
+ assert dm.install_encode_release(pipe, _whole_plan(1024, 1024 - 8), None) == 2
+ with pytest.raises(RuntimeError):
+ pipe.encode_prompt("p", fail = True)
+ assert on_device() == ["cuda"] * 6
+ assert calls == {"release": 1, "restore": 1}
+ pipe.encode_prompt("p")
+ assert on_device() == ["cuda"] * 6
+ assert torch.equal(net(x.cuda()).cpu(), ref)
+
+
+def test_encode_release_once_kill_switch(monkeypatch):
+ torch, net, enc, enc2, pipe, x, ref, on_device, calls = _two_encoder_pipe(monkeypatch)
+ monkeypatch.setenv(dm.ENCODE_RELEASE_ONCE_ENV, "0")
+ assert dm.install_encode_release(pipe, _whole_plan(1024, 1024 - 8), None) == 2
+ pipe.encode_prompt("p")
+ assert on_device() == ["cuda"] * 6
+ assert calls == {"release": 2, "restore": 2} # once per encoder
+
+
def test_encode_release_only_for_the_whole_tier(monkeypatch):
torch, net, enc, pipe, x, ref, on_device = _encode_release_pipe(monkeypatch)
assert (
diff --git a/studio/backend/tests/test_diffusion_prompt_cache.py b/studio/backend/tests/test_diffusion_prompt_cache.py
index e31d54dba03..5b0e8453a95 100644
--- a/studio/backend/tests/test_diffusion_prompt_cache.py
+++ b/studio/backend/tests/test_diffusion_prompt_cache.py
@@ -546,8 +546,88 @@ def test_wan_per_text_cache_kill_switch(monkeypatch):
assert pipe.t5_calls == ["a cat", "blurry", "a dog", "blurry"]
-def test_per_text_cache_is_wan_only():
+def test_per_text_cache_only_for_known_pipelines():
pipe = _EncodePipe()
pipe._get_t5_prompt_embeds = lambda **kw: None
+ pipe._encode_prompt = lambda **kw: None
assert prompt_cache._per_text_method(pipe) is None
assert prompt_cache._per_text_method(WanStubPipeline()) == "_get_t5_prompt_embeds"
+ assert prompt_cache._per_text_method(ZImageStubPipeline()) == "_encode_prompt"
+
+
+class ZImageStubPipeline:
+ """diffusers ZImagePipeline's shape: encode_prompt encodes the prompt and, under CFG, the negative in ONE call,
+ each through _encode_prompt, which templates the caller's prompt list in place."""
+
+ def __init__(self):
+ self.calls = []
+ self._execution_device = torch.device("cpu")
+ self.text_encoder = torch.nn.Linear(2, 2)
+
+ def _encode_prompt(
+ self,
+ prompt,
+ device = None,
+ prompt_embeds = None,
+ max_sequence_length = 512,
+ ):
+ if prompt_embeds is not None:
+ return prompt_embeds
+ if isinstance(prompt, str):
+ prompt = [prompt]
+ self.calls.append(list(prompt))
+ out = [torch.full((len(p) + 1, 2), float(sum(map(ord, p)))) for p in prompt]
+ for i, p in enumerate(prompt):
+ prompt[i] = f"<user>{p}"
+ return out
+
+ def encode_prompt(
+ self,
+ prompt,
+ device = None,
+ do_classifier_free_guidance = True,
+ negative_prompt = None,
+ prompt_embeds = None,
+ negative_prompt_embeds = None,
+ max_sequence_length = 512,
+ ):
+ prompt = [prompt] if isinstance(prompt, str) else prompt
+ pos = self._encode_prompt(
+ prompt = prompt, device = device, max_sequence_length = max_sequence_length
+ )
+ neg = []
+ if do_classifier_free_guidance:
+ negative = [negative_prompt or "" for _ in prompt]
+ neg = self._encode_prompt(
+ prompt = negative, device = device, max_sequence_length = max_sequence_length
+ )
+ return pos, neg
+
+
+def _flat(x):
+ if isinstance(x, (list, tuple)):
+ return [t for v in x for t in _flat(v)]
+ return [x] if x is not None else []
+
+
+def test_cfg_negative_is_encoded_once_across_new_prompts():
+ """Under CFG only the new prompt is encoded; the unchanged negative is reused. Results match uncached."""
+ pipe = ZImageStubPipeline()
+ assert prompt_cache.install(pipe)
+ want = ZImageStubPipeline()
+ for text in ("a cat", "a dog", "a boat", "a dog"):
+ got = pipe.encode_prompt(text, negative_prompt = "blurry")
+ ref = want.encode_prompt(text, negative_prompt = "blurry")
+ a, b = _flat(got), _flat(ref)
+ assert len(a) == len(b) and all(torch.equal(x, y) for x, y in zip(a, b))
+ texts = [c[0] if isinstance(c, list) else c for c in pipe.calls]
+ assert texts == ["a cat", "blurry", "a dog", "a boat"]
+
+
+def test_cfg_negative_per_text_kill_switch(monkeypatch):
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_PROMPT_CACHE_PER_TEXT", "0")
+ pipe = ZImageStubPipeline()
+ assert prompt_cache.install(pipe)
+ for text in ("a cat", "a dog"):
+ pipe.encode_prompt(text, negative_prompt = "blurry")
+ assert [c[0] for c in pipe.calls] == ["a cat", "blurry", "a dog", "blurry"]