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 diffusion: show whether group offload keeps the transformer on the GPU or streams it every step (#16610)

oobaboogae36352f2b8b8
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 172fb796204..40caed79a4a 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -211,6 +211,8 @@ from .diffusion_memory import (
plan_diffusion_memory,
plan_fits_total_capacity,
denoisers_pinned_resident,
+ denoiser_offload,
+ agreed_placement,
install_encode_release,
plan_keeps_transformer_resident,
prequant_seed_device,
@@ -14442,6 +14444,7 @@ class DiffusionBackend:
)
whole_tier = None
whole_release: list = []
+ chunk_placements: list = []
def _release_whole_denoiser() -> None:
while whole_release:
@@ -14517,6 +14520,8 @@ class DiffusionBackend:
protect_ctx = protect_generation(pipe, denoise_steps, logger = logger)
# Per chunk: a later chunk encodes again after an earlier one decoded.
gen.phase = "encode"
+ # appended only if the chunk succeeds: an OOM attempt is split and retried
+ chunk_placement: list = []
def _enter_denoise_phase(gen = gen) -> None:
if gen.phase == "encode":
@@ -14548,6 +14553,10 @@ class DiffusionBackend:
"""The decoder was entered: a HOST position, possibly far ahead of the GPU. Mark the
boundary in the stream and let the poller flip once the GPU reaches it; with no event
to wait on (CPU) there is no queue to be ahead of, so flip now."""
+ # every step ran (deferred returns settled), the pin still holds, no VAE OOM unpin yet
+ chunk_placement.append(
+ denoiser_offload(state.pipe, state.offload_policy)
+ )
if peak_probe is not None:
peak_probe.mark_decode()
_release_whole_denoiser()
@@ -14656,6 +14665,11 @@ class DiffusionBackend:
images.extend(out)
per_image_seeds.extend(s for _, s in chunk)
chunk_shapes.append(len(chunk))
+ # a pipeline that never enters the decoder is read once it returns
+ chunk_placements.extend(
+ chunk_placement[:1]
+ or [denoiser_offload(state.pipe, state.offload_policy)]
+ )
steps_done[0] += progress_steps
except BaseException:
if previewer is not None:
@@ -14757,6 +14771,7 @@ class DiffusionBackend:
"text_encoder_quant": state.text_encoder_quant,
"memory_mode": state.memory_mode,
"offload_policy": state.offload_policy,
+ "denoiser_offload": agreed_placement(chunk_placements),
# Read after the deferred speed / step-cache toggles, so this is what ran.
"speed_mode": state.speed_mode,
"attention_backend": state.attention_backend,
@@ -15080,6 +15095,7 @@ class DiffusionBackend:
"gguf_variant": None,
"cpu_offload": False,
"offload_policy": None,
+ "denoiser_offload": None,
"vae_tiling": False,
"memory_mode": None,
"speed_mode": None,
@@ -15137,6 +15153,7 @@ class DiffusionBackend:
),
"cpu_offload": state.cpu_offload,
"offload_policy": state.offload_policy,
+ "denoiser_offload": denoiser_offload(state.pipe, state.offload_policy),
"vae_tiling": state.vae_tiling,
"memory_mode": state.memory_mode,
"speed_mode": state.speed_mode,
diff --git a/studio/backend/core/inference/diffusion_detailer.py b/studio/backend/core/inference/diffusion_detailer.py
index b5fc09a3dbf..923d5ea4da8 100644
--- a/studio/backend/core/inference/diffusion_detailer.py
+++ b/studio/backend/core/inference/diffusion_detailer.py
@@ -643,6 +643,7 @@ def detail_result(
if not images:
return
renders = list(images)
+ placement = result.get("denoiser_offload")
stop_event = threading.Event()
with _active_lock:
_active[stop_event] = account
@@ -668,6 +669,7 @@ def detail_result(
stopped = stop_event.is_set()
if finished and stopped:
result["images"] = renders
+ result["denoiser_offload"] = placement
result["detailer"] = [
record
if record and record.get("error")
@@ -690,9 +692,12 @@ def _detail_images(
generate_kwargs: dict,
) -> None:
from core.inference.diffusion_families import DIFFUSION_CANCELLED_MSG
+ from core.inference.diffusion_memory import agreed_placement
seeds = result.get("seeds") or []
records: list[Optional[dict]] = [None] * len(images)
+ # crop inpaints skip the per-request whole tier, so a kept crop can stream where the base ran resident
+ placements = [result.get("denoiser_offload")]
try:
found, info = detect(images, settings, stop = stop_event.is_set)
except Exception as exc: # noqa: BLE001 -- the render stands; the recipe says why it was not detailed
@@ -716,6 +721,7 @@ def _detail_images(
continue
inherited: dict = {}
+ crop_placements: list = []
def _inpaint(crop, mask, seed, det_prompt, det_negative):
from core.inference import diffusion_bg_compile
@@ -738,6 +744,7 @@ def _detail_images(
)
if not same_build(result, out):
raise ValueError("the model changed")
+ crop_placements.append(out.get("denoiser_offload"))
if det_negative and out.get("negative_prompt") and not result.get("negative_prompt"):
# Negative prompt engaged only at the Detailer's CFG: record it.
if not settings.negative_prompt:
@@ -770,6 +777,7 @@ def _detail_images(
}
continue
images[index] = detailed.image
+ placements.extend(crop_placements)
records[index] = {
**detailed.record,
**inherited,
@@ -788,6 +796,7 @@ def _detail_images(
records[index]["detect_ms"] = info.get("detect_ms")
result["images"] = images
result["detailer"] = records
+ result["denoiser_offload"] = agreed_placement(placements)
__all__ = [
diff --git a/studio/backend/core/inference/diffusion_hires.py b/studio/backend/core/inference/diffusion_hires.py
index 9a230493670..0be4154257b 100644
--- a/studio/backend/core/inference/diffusion_hires.py
+++ b/studio/backend/core/inference/diffusion_hires.py
@@ -572,6 +572,7 @@ def run_hires(
from core.inference.diffusion_families import DIFFUSION_CANCELLED_MSG, DIFFUSION_NOT_LOADED_MSG
from core.inference.diffusion_memory import (
ImageActivationShortfallError,
+ agreed_placement,
raise_on_image_activation_shortfall,
)
from core.inference.generation_ticket import bind_generation_cancel
@@ -665,6 +666,8 @@ def run_hires(
seeds = list(base.get("seeds") or [base["seed"]] * len(images))
prompts = kwargs.get("prompts") or None
refined: list[Any] = []
+ # a larger refine pass can stream where the base stayed resident
+ placements = [base.get("denoiser_offload")]
upscale_s = 0.0
refine_s = 0.0
upscale_info: dict = {}
@@ -750,11 +753,13 @@ def run_hires(
f"Hires fix refine pass at {target[0]}x{target[1]}: {exc}"
) from exc
refined.extend(out["images"])
+ placements.append(out.get("denoiser_offload"))
refine_s += time.perf_counter() - t_ref
if out.get("negative_prompt") and not refine_negative:
refine_negative = out["negative_prompt"]
result = dict(base)
result["images"] = refined
+ result["denoiser_offload"] = agreed_placement(placements)
if refine_negative and not result.get("negative_prompt"):
# Hires CFG engaged a negative the base pass's guidance left off; the recipe must still carry it.
result["negative_prompt"] = refine_negative
diff --git a/studio/backend/core/inference/diffusion_memory.py b/studio/backend/core/inference/diffusion_memory.py
index 7fd84d13f32..e6ca5119f95 100644
--- a/studio/backend/core/inference/diffusion_memory.py
+++ b/studio/backend/core/inference/diffusion_memory.py
@@ -24,7 +24,7 @@ import os
import sys
import threading
from dataclasses import dataclass, field, replace
-from typing import Any, Callable, Iterator, Optional
+from typing import Any, Callable, Iterable, Iterator, Optional
from .host_pinning import host_pinning_allowed
from .rocm_bf16 import is_rocm_torch
@@ -6659,6 +6659,55 @@ def _streamed_pin_leftover_mib(
_DENOISER_NAMES = ("transformer", "transformer_2", "unconditional_transformer", "unet")
+DENOISER_RESIDENT = "resident"
+DENOISER_PARTIAL = "partial"
+DENOISER_STREAMED = "streamed"
+
+
+def denoiser_residency(pipe: Any) -> Optional[tuple[int, int]]:
+ """``(resident, total)`` offload groups across the denoisers, read off the live hooks: a denoiser another offload
+ hook moves counts as one streamed group, an unhooked one as one resident group, None when unreadable."""
+ resident = total = 0
+ try:
+ for name in _DENOISER_NAMES:
+ module = getattr(pipe, name, None)
+ if module is None:
+ continue
+ groups = _offload_groups(module)
+ if groups:
+ total += len(groups)
+ resident += sum(1 for g in groups if getattr(g, "_unsloth_resident", False))
+ continue
+ registry = getattr(module, "_diffusers_hook", None)
+ total += 1
+ if not (
+ any(getattr(sub, "_hf_hook", None) is not None for sub in module.modules())
+ or any("offload" in str(key) for key in (getattr(registry, "hooks", None) or {}))
+ ):
+ resident += 1
+ except Exception: # noqa: BLE001 - a status read must never fail the load or the render
+ return None
+ return resident, total
+
+
+def denoiser_offload(pipe: Any, offload_policy: Any) -> Optional[str]:
+ """resident | partial | streamed for a group-offloaded pipeline; None for other policies or an unreadable one."""
+ if offload_policy != OFFLOAD_GROUP or pipe is None:
+ return None
+ counts = denoiser_residency(pipe)
+ if counts is None:
+ return None
+ resident, total = counts
+ if resident >= total:
+ return DENOISER_RESIDENT
+ return DENOISER_PARTIAL if resident else DENOISER_STREAMED
+
+
+def agreed_placement(placements: Iterable[Optional[str]]) -> Optional[str]:
+ """The placement every denoise of one image ran with; None when they differ."""
+ distinct = set(placements)
+ return distinct.pop() if len(distinct) == 1 else None
+
def denoisers_pinned_resident(pipe: Any) -> bool:
"""Every denoiser unhooked or with all its offload groups pinned, at least one pinned. The hooks stay so an
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 9dd37f57659..037195e572e 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -5599,6 +5599,11 @@ class GalleryImage(BaseModel):
description = "Offload policy actually engaged: none | group | model | sequential. Part of "
"the build: an offloaded pipeline declines the torchao text-encoder modes.",
)
+ denoiser_offload: Optional[str] = Field(
+ None,
+ description = "Under group offload, where this generation's denoiser ran: resident | partial | "
+ "streamed (streamed blocks move from CPU on every step). Null for other policies and older records.",
+ )
speed_mode: Optional[str] = Field(
None,
description = "Speed profile engaged for this generation (eager | default | max | off), after "
@@ -6075,6 +6080,11 @@ class DiffusionStatusResponse(BaseModel):
offload_policy: Optional[str] = Field(
None, description = "Resolved offload policy: none | group | model | streaming | sequential"
)
+ denoiser_offload: Optional[str] = Field(
+ None,
+ description = "Under group offload, where the denoiser lives now: resident (only the text encoders "
+ "stream) | partial | streamed (blocks move from CPU on every step). Null for other policies.",
+ )
vae_tiling: bool = Field(False, description = "Whether VAE tiling/slicing is enabled")
memory_mode: Optional[str] = Field(None, description = "Requested memory mode")
speed_mode: Optional[str] = Field(None, description = "Requested speed mode")
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 201f66be547..21231dbb389 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -49471,6 +49471,7 @@ async def _generate_diffusion_image_run(
"text_encoder_quant": result.get("text_encoder_quant"),
"memory_mode": result.get("memory_mode"),
"offload_policy": result.get("offload_policy"),
+ "denoiser_offload": result.get("denoiser_offload"),
"speed_mode": result.get("speed_mode"),
"attention_backend": result.get("attention_backend"),
"transformer_cache": result.get("transformer_cache"),
@@ -51411,6 +51412,7 @@ async def _generate_openai_images(
"text_encoder_quant": result.get("text_encoder_quant"),
"memory_mode": result.get("memory_mode"),
"offload_policy": result.get("offload_policy"),
+ "denoiser_offload": result.get("denoiser_offload"),
"speed_mode": result.get("speed_mode"),
"attention_backend": result.get("attention_backend"),
"transformer_cache": result.get("transformer_cache"),
diff --git a/studio/backend/tests/test_diffusion_backend.py b/studio/backend/tests/test_diffusion_backend.py
index 9bbda6a5a47..44dcb7f2411 100644
--- a/studio/backend/tests/test_diffusion_backend.py
+++ b/studio/backend/tests/test_diffusion_backend.py
@@ -14540,3 +14540,128 @@ def test_a_lora_change_drops_the_cfg_parallel_replica(monkeypatch):
assert dropped == [pipe]
backend._apply_loras(_quant_lora_state(pipe), [], ev)
assert dropped == [pipe, pipe]
+
+
+class _PinProbePipe(_FakePipe):
+ """Enters the denoise loop and decoder like diffusers, and runs out of memory on its first attempt."""
+
+ def __init__(self, fail_first: bool) -> None:
+ super().__init__()
+ self.attempts = 0
+ self.fail_first = fail_first
+ self.vae = types.SimpleNamespace(decode = lambda: None)
+
+ def progress_bar(self, *args, **kwargs):
+ return contextlib.nullcontext()
+
+ def __call__(self, **kwargs):
+ self.progress_bar(total = 1)
+ self.attempts += 1
+ if self.fail_first and self.attempts == 1:
+ raise RuntimeError("CUDA out of memory. Tried to allocate 2.00 GiB")
+ if hasattr(self.vae, "decode"):
+ self.vae.decode()
+ return super().__call__(**kwargs)
+
+
+ "pins, pinned_placement, expected",
+ [
+ # the 2-image attempt cannot pin and runs out of memory; both 1-image retries run whole
+ ([False, True, True], "resident", "resident"),
+ # one retry ran whole and the other streamed: no one placement describes the batch
+ ([False, True, False], "resident", None),
+ # the pin covers pipe.transformer only: a second DiT (Ideogram 4) still streams
+ ([False, True, True], "partial", "partial"),
+ ],
+)
+def test_saved_placement_counts_only_chunks_that_finished(
+ fake_runtime, tmp_path, monkeypatch, pins, pinned_placement, expected
+):
+ import core.inference.diffusion as diffusion
+
+ backend = _loaded_backend(tmp_path)
+ state = backend._state
+ pipe = _PinProbePipe(fail_first = True)
+ object.__setattr__(state, "pipe", pipe)
+ object.__setattr__(state, "offload_policy", "group")
+ outcomes = list(pins)
+ held = [False]
+
+ def _pin(*a, **kw):
+ if not outcomes.pop(0):
+ return None
+ held[0] = True
+ return lambda: held.__setitem__(0, False)
+
+ monkeypatch.setattr(diffusion, "_whole_tier_for_request", lambda state, **kw: (1.0, 2.0, 64))
+ monkeypatch.setattr(diffusion, "pin_denoiser_for_call", _pin)
+ # the live hooks: the load streams, a held pin moves what it covers on the GPU
+ monkeypatch.setattr(
+ diffusion,
+ "denoiser_offload",
+ lambda pipe, policy: pinned_placement if held[0] else "streamed",
+ )
+
+ out = backend.generate(prompt = "p", steps = 4, batch_size = 2)
+
+ assert pipe.attempts == 3 and not outcomes
+ assert len(out["images"]) == 2
+ assert out["denoiser_offload"] == expected
+
+
+class _DeferredReturnPipe(_PinProbePipe):
+ """A resident load whose groups a VAE OOM recovery unpinned and left on a deferred return: the first forward
+ returns them, and the next decode's recovery unpins them again."""
+
+ def __init__(self, deferred: bool) -> None:
+ super().__init__(fail_first = False)
+ self.settled = not deferred
+ self.decoded = False
+ self.vae = types.SimpleNamespace(decode = lambda: setattr(self, "decoded", True))
+
+ def progress_bar(self, *args, **kwargs):
+ out = super().progress_bar(*args, **kwargs)
+ self.settled = True
+ return out
+
+ def placement(self) -> str:
+ return "resident" if self.settled and not self.decoded else "streamed"
+
+
[email protected]("deferred", [False, True])
+def test_saved_placement_is_read_after_the_steps_and_before_the_decode(
+ fake_runtime, tmp_path, monkeypatch, deferred
+):
+ import core.inference.diffusion as diffusion
+
+ backend = _loaded_backend(tmp_path)
+ state = backend._state
+ pipe = _DeferredReturnPipe(deferred)
+ object.__setattr__(state, "pipe", pipe)
+ object.__setattr__(state, "offload_policy", "group")
+ monkeypatch.setattr(diffusion, "_whole_tier_for_request", lambda state, **kw: None)
+ monkeypatch.setattr(diffusion, "denoiser_offload", lambda pipe, policy: pipe.placement())
+
+ out = backend.generate(prompt = "p", steps = 4)
+
+ assert pipe.decoded
+ assert out["denoiser_offload"] == "resident"
+
+
+def test_a_pass_that_never_decodes_reads_the_placement_once_it_returns(
+ fake_runtime, tmp_path, monkeypatch
+):
+ import core.inference.diffusion as diffusion
+
+ backend = _loaded_backend(tmp_path)
+ state = backend._state
+ # a latent-output pass (the hires latent-upscaler base) never enters the decoder
+ pipe = _PinProbePipe(fail_first = False)
+ pipe.vae = types.SimpleNamespace()
+ object.__setattr__(state, "pipe", pipe)
+ object.__setattr__(state, "offload_policy", "group")
+ monkeypatch.setattr(diffusion, "_whole_tier_for_request", lambda state, **kw: None)
+ monkeypatch.setattr(diffusion, "denoiser_offload", lambda pipe, policy: "resident")
+
+ assert backend.generate(prompt = "p", steps = 4)["denoiser_offload"] == "resident"
diff --git a/studio/backend/tests/test_diffusion_denoiser_offload.py b/studio/backend/tests/test_diffusion_denoiser_offload.py
new file mode 100644
index 00000000000..e303d46cec0
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_denoiser_offload.py
@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+import types
+
+import pytest
+
+torch = pytest.importorskip("torch")
+hooks = pytest.importorskip("diffusers.hooks")
+
+import core.inference.diffusion_memory as dm
+
+
+class _Blocks(torch.nn.Module):
+ def __init__(self, n: int = 4) -> None:
+ super().__init__()
+ self.blocks = torch.nn.ModuleList([torch.nn.Linear(4, 4) for _ in range(n)])
+
+ def forward(self, x):
+ for block in self.blocks:
+ x = block(x)
+ return x
+
+
+def _streamed(n: int = 4) -> torch.nn.Module:
+ module = _Blocks(n)
+ hooks.apply_group_offloading(
+ module,
+ onload_device = torch.device("cpu"),
+ offload_device = torch.device("cpu"),
+ offload_type = "block_level",
+ num_blocks_per_group = 1,
+ )
+ return module
+
+
+def _pin(module: torch.nn.Module, count: int) -> None:
+ for group in dm._offload_groups(module)[:count]:
+ group._unsloth_resident = True
+
+
+def test_an_unhooked_transformer_under_group_offload_is_resident():
+ pipe = types.SimpleNamespace(transformer = _Blocks())
+ assert dm.denoiser_offload(pipe, dm.OFFLOAD_GROUP) == dm.DENOISER_RESIDENT
+
+
+def test_every_group_streamed_is_streamed():
+ pipe = types.SimpleNamespace(transformer = _streamed())
+ assert dm.denoiser_offload(pipe, dm.OFFLOAD_GROUP) == dm.DENOISER_STREAMED
+
+
+def test_some_groups_pinned_is_partial():
+ module = _streamed()
+ _pin(module, 2)
+ pipe = types.SimpleNamespace(transformer = module)
+ assert dm.denoiser_residency(pipe) == (2, 4)
+ assert dm.denoiser_offload(pipe, dm.OFFLOAD_GROUP) == dm.DENOISER_PARTIAL
+
+
+def test_every_group_pinned_is_resident():
+ module = _streamed()
+ _pin(module, 4)
+ pipe = types.SimpleNamespace(transformer = module)
+ assert dm.denoiser_offload(pipe, dm.OFFLOAD_GROUP) == dm.DENOISER_RESIDENT
+
+
+def test_a_second_streamed_denoiser_counts():
+ first = _streamed()
+ _pin(first, 4)
+ pipe = types.SimpleNamespace(transformer = first, transformer_2 = _streamed())
+ assert dm.denoiser_residency(pipe) == (4, 8)
+ assert dm.denoiser_offload(pipe, dm.OFFLOAD_GROUP) == dm.DENOISER_PARTIAL
+
+
+def test_an_unhooked_resident_denoiser_beside_a_streamed_one_is_partial():
+ pipe = types.SimpleNamespace(transformer = _streamed(), unconditional_transformer = _Blocks())
+ assert dm.denoiser_residency(pipe) == (1, 5)
+ assert dm.denoiser_offload(pipe, dm.OFFLOAD_GROUP) == dm.DENOISER_PARTIAL
+
+
+ "policy", [dm.OFFLOAD_NONE, dm.OFFLOAD_MODEL, dm.OFFLOAD_STREAMING, dm.OFFLOAD_SEQUENTIAL, None]
+)
+def test_other_policies_report_nothing(policy):
+ pipe = types.SimpleNamespace(transformer = _streamed())
+ assert dm.denoiser_offload(pipe, policy) is None
+
+
+def test_an_unreadable_denoiser_reports_nothing_instead_of_raising():
+ pipe = types.SimpleNamespace(transformer = object())
+ assert dm.denoiser_offload(pipe, dm.OFFLOAD_GROUP) is None
+
+
+def test_the_gallery_record_keeps_the_denoiser_placement():
+ from models.inference import DiffusionStatusResponse, GalleryImage
+ assert "denoiser_offload" in GalleryImage.model_fields
+ assert "denoiser_offload" in DiffusionStatusResponse.model_fields
diff --git a/studio/backend/tests/test_diffusion_detailer.py b/studio/backend/tests/test_diffusion_detailer.py
index 252c7e9912b..8996d033246 100644
--- a/studio/backend/tests/test_diffusion_detailer.py
+++ b/studio/backend/tests/test_diffusion_detailer.py
@@ -1411,3 +1411,39 @@ def test_a_template_inheriting_the_negative_saves_it_resolved(
assert saved == expected_saved
# Restored with no main negative (the base recorded none), the saved template expands the same.
assert det.detection_prompt(saved, "", 0) == expected_seen[0]
+
+
+ "crop, expected",
+ [
+ ("resident", "resident"),
+ ("streamed", None),
+ # a failed pass keeps the render, so its crop does not count
+ (RuntimeError("CUDA out of memory"), "resident"),
+ ],
+)
+def test_a_kept_crop_reconciles_the_recorded_placement(monkeypatch, crop, expected):
+ _patch_detect(monkeypatch, [[_face((150, 60, 200, 120))]])
+
+ def _generate(**kwargs):
+ if isinstance(crop, Exception):
+ raise crop
+ image = Image.open(
+ __import__("io").BytesIO(
+ __import__("base64").b64decode(kwargs["init_image"].split(",", 1)[1])
+ )
+ )
+ return {"images": [image.convert("RGB")], "denoiser_offload": crop}
+
+ result = {"images": [_scene()], "seeds": [1], "denoiser_offload": "resident"}
+ det.detail_result(
+ _generate,
+ result,
+ det.DetailerSettings(),
+ prompt_for = lambda i: "p",
+ negative_prompt = None,
+ steps = 4,
+ guidance = 1.0,
+ generate_kwargs = {},
+ )
+ assert result["denoiser_offload"] == expected
diff --git a/studio/backend/tests/test_diffusion_hires.py b/studio/backend/tests/test_diffusion_hires.py
index 4ef676c474e..3304c5c7bb3 100644
--- a/studio/backend/tests/test_diffusion_hires.py
+++ b/studio/backend/tests/test_diffusion_hires.py
@@ -1579,3 +1579,63 @@ def test_upscale_default_strength_keeps_one_step_and_hires_refine_is_untouched()
assert n == 3 and hires.steps_run(n, 0.35, hires.RULE_FLOOR) == 1
refine = hires.refine_inference_steps(1, 0.35, hires.RULE_FLOOR)
assert hires.min_inference_steps(refine, 0.35, hires.RULE_FLOOR) == refine
+
+
+ "base, refines, expected",
+ [
+ ("resident", ["resident", "resident"], "resident"),
+ # the larger refine streamed where the base stayed resident: no one placement describes the image
+ ("resident", ["streamed", "streamed"], None),
+ ("resident", ["resident", "streamed"], None),
+ ("streamed", ["streamed", "streamed"], "streamed"),
+ (None, [None, None], None),
+ ],
+)
+def test_hires_records_a_placement_only_when_every_pass_agrees(base, refines, expected):
+ import contextlib
+ import threading
+
+ from PIL import Image
+
+ class _Backend:
+ def __init__(self):
+ self._state = types.SimpleNamespace(
+ family = _fam("z-image"), offload_policy = "group", device = "cpu"
+ )
+ self._lock = threading.Lock()
+ self._generation_cancel_lock = threading.Lock()
+ self._gen = None
+ self._active_generate_cancel = None
+ self._active_generate_account = None
+
+ @contextlib.contextmanager
+ def _generation_slot(self, cancel):
+ yield
+
+ queued = list(refines)
+
+ def fake_generate(backend, **kw):
+ ctx = kw.pop("_hires_pass")
+ if not ctx.refine:
+ return {
+ "images": [Image.new("RGB", (256, 256))] * 2,
+ "seed": 5,
+ "seeds": [5, 6],
+ "denoiser_offload": base,
+ }
+ return {
+ "images": [ctx.source],
+ "seed": kw["seed"],
+ "seeds": [kw["seed"]],
+ "denoiser_offload": queued.pop(0),
+ }
+
+ out = hires.run_hires(
+ _Backend(),
+ fake_generate,
+ hires.HiresParams(denoise = 0.4, steps = 6),
+ {"prompt": "p", "width": 256, "height": 256, "steps": 8, "seed": 5, "batch_size": 2},
+ )
+ assert not queued
+ assert out["denoiser_offload"] == expected
diff --git a/studio/frontend/src/features/images/api.ts b/studio/frontend/src/features/images/api.ts
index 92d6076a5d1..6d082e2e7d3 100644
--- a/studio/frontend/src/features/images/api.ts
+++ b/studio/frontend/src/features/images/api.ts
@@ -55,6 +55,7 @@ export interface DiffusionStatus {
text_encoder_quant?: string | null;
memory_mode?: string | null;
offload_policy?: string | null;
+ denoiser_offload?: string | null;
speed_mode?: string | null;
speed_optims?: string[];
attention_backend?: string | null;
@@ -328,6 +329,7 @@ export interface GalleryImage {
text_encoder_quant?: string | null;
memory_mode?: string | null;
offload_policy?: string | null;
+ denoiser_offload?: string | null;
speed_mode?: string | null;
attention_backend?: string | null;
transformer_cache?: string | null;
diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsx
index 9d4fdb955bd..d003a5d9749 100644
--- a/studio/frontend/src/features/images/images-page.tsx
+++ b/studio/frontend/src/features/images/images-page.tsx
@@ -214,6 +214,7 @@ import {
formatResolvedValue,
isDenseQuantKind,
isPrecisionRefusal,
+ denoiserPlacement,
memoryRecipeValue,
resolvedBadge,
resolvedSeedKey,
@@ -1329,6 +1330,8 @@ function RecipePopover({
}) {
// PopoverContent portals to body, so the inert page wrapper cannot contain it.
const [open, setOpen] = useState(false);
+ const recipePlacement =
+ image.offload_policy === "group" ? denoiserPlacement(image.denoiser_offload) : null;
useEffect(() => {
if (!active) setOpen(false);
}, [active]);
@@ -1374,6 +1377,13 @@ function RecipePopover({
value={memoryRecipeValue(image.memory_mode, image.offload_policy)}
/>
) : null}
+ {recipePlacement ? (
+ <RecipeRow
+ label="Placement"
+ value={recipePlacement.label}
+ title={recipePlacement.detail}
+ />
+ ) : null}
{image.speed_mode ? (
<RecipeRow
label="Speed"
@@ -1491,6 +1501,7 @@ function BuildRow({ label, value, badge }: { label: string; value: string; badge
function LoadedBuildSummary({ status }: { status: DiffusionStatus | null }) {
if (!status?.loaded) return null;
const offload = status.offload_policy ?? "none";
+ const placement = offload === "group" ? denoiserPlacement(status.denoiser_offload) : null;
return (
<div className="flex flex-col gap-1 rounded-lg border border-border/60 px-2.5 py-2 text-ui-11">
<div className="flex items-center gap-1 pb-0.5 text-xs font-medium text-muted-foreground">
@@ -1535,6 +1546,13 @@ function LoadedBuildSummary({ status }: { status: DiffusionStatus | null }) {
: `${status.memory_mode ?? "auto"} · ${offload} offload`
}
/>
+ {placement ? (
+ <BuildRow
+ label="Placement"
+ value={placement.label}
+ badge={<InfoHint>{placement.detail}</InfoHint>}
+ />
+ ) : null}
<BuildRow
label="Attention"
value={
diff --git a/studio/frontend/src/features/images/lib/image-metadata.ts b/studio/frontend/src/features/images/lib/image-metadata.ts
index c85e36362d7..ed346f6ce24 100644
--- a/studio/frontend/src/features/images/lib/image-metadata.ts
+++ b/studio/frontend/src/features/images/lib/image-metadata.ts
@@ -1020,6 +1020,7 @@ export const INFO_RECIPE_KEYS = [
"text_encoder_quant",
"memory_mode",
"offload_policy",
+ "denoiser_offload",
"speed_mode",
"attention_backend",
"transformer_cache",
diff --git a/studio/frontend/src/lib/resolved-precision.ts b/studio/frontend/src/lib/resolved-precision.ts
index 9ee2a77db30..e7f650062af 100644
--- a/studio/frontend/src/lib/resolved-precision.ts
+++ b/studio/frontend/src/lib/resolved-precision.ts
@@ -177,6 +177,30 @@ export function denseTextEncoderBuildLabel(status: { dtype?: string | null }): s
return status.dtype === "gguf" ? "As in checkpoint" : denseDtypeLabel(status.dtype);
}
+const DENOISER_PLACEMENTS: Record<string, { label: string; detail: string }> = {
+ resident: {
+ label: "Transformer on GPU",
+ detail:
+ "The transformer stays on the GPU, so every denoise step runs at resident speed. Only components used once per prompt, such as the text encoders, stream from CPU.",
+ },
+ partial: {
+ label: "Transformer partly streamed",
+ detail:
+ "Part of the transformer stays on the GPU and the rest streams from CPU on every denoise step (slower than resident).",
+ },
+ streamed: {
+ label: "Transformer streamed",
+ detail:
+ "Every transformer block streams from CPU on every denoise step (slower than resident).",
+ },
+};
+
+export function denoiserPlacement(
+ denoiserOffload: string | null | undefined,
+): { label: string; detail: string } | null {
+ return (denoiserOffload && DENOISER_PLACEMENTS[denoiserOffload]) || null;
+}
+
/** sd.cpp never runs the memory planner, so an absent `memory_mode` reports the offload alone. */
export function memoryRecipeValue(
memoryMode: string | null | undefined,
diff --git a/studio/frontend/tests/resolved-precision.test.ts b/studio/frontend/tests/resolved-precision.test.ts
index 33236ab9c81..15613f95df6 100644
--- a/studio/frontend/tests/resolved-precision.test.ts
+++ b/studio/frontend/tests/resolved-precision.test.ts
@@ -11,6 +11,8 @@ import {
isDenseQuantKind,
isPrecisionRefusal,
isResolvedHonored,
+ denoiserPlacement,
+ memoryRecipeValue,
resolvedBadge,
resolvedSeedKey,
resolvedSelectValue,
@@ -418,3 +420,22 @@ test("a pinned dense text encoder reseeds as Dense, not Default", () => {
};
assert.equal(resolvedSelectValue(declined, toTeOption), "none");
});
+
+test("group offload placements get distinct labels, so the slow tier is not shown as the fast one", () => {
+ const labels = ["resident", "partial", "streamed"].map((tier) => denoiserPlacement(tier)?.label);
+ assert.deepEqual(labels, [
+ "Transformer on GPU",
+ "Transformer partly streamed",
+ "Transformer streamed",
+ ]);
+ assert.match(denoiserPlacement("streamed")?.detail ?? "", /every denoise step/);
+});
+
+test("records and backends without a placement show no placement and keep the memory label", () => {
+ assert.equal(denoiserPlacement(undefined), null);
+ assert.equal(denoiserPlacement(null), null);
+ assert.equal(denoiserPlacement("unknown"), null);
+ assert.equal(memoryRecipeValue("auto", "group"), "auto (group offload)");
+ assert.equal(memoryRecipeValue(null, "model"), "model offload");
+ assert.equal(memoryRecipeValue("fast", "none"), "fast");
+});