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 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.pyindex 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:returnrestore = 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 _beforeafter = disable(_after) if callable(disable) else _afterhooked = 0@@ -5515,6 +5528,29 @@ def install_encode_release()module._unsloth_encode_release = handleshooked += 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+ passif 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.pyindex 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.pyindex 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.pyindex 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: Noneassert prompt_cache._per_text_method(pipe) is Noneassert 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"]