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: price a Qwen-Image-2.1 edit's reference on the group tier so 16 GiB edits stop hooking the resident transformer (L4 first edit -19%, -8.4 GiB host RAM) (#17364)

Daniel Han15bd320b5848
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 2638ada17ed..8eca55c060b 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -154,6 +154,7 @@ from .diffusion_conditioning import (
decode_condition_images,
edit_takes_extra_images,
effective_reference_resolution,
+ reference_request_pixels,
match_source_size,
)
from .diffusion_ideogram4 import ideogram4_repo_is_fp8, load_ideogram4_pipeline
@@ -232,6 +233,8 @@ from .diffusion_memory import (
plan_keeps_transformer_resident,
prequant_seed_device,
raise_on_image_activation_shortfall,
+ image_activation_verdict,
+ ACTIVATION_REFUSE,
raise_on_unified_memory_shortfall,
scoped_allow_oversized_load,
UNIFIED_OVERSIZE_REFUSAL_CODE,
@@ -273,6 +276,9 @@ from .diffusion_memory import (
take_deferred_restore,
resident_group_mib,
hook_resident_denoiser,
+ live_reference_shortfall_mib,
+ static_reference_release_mib,
+ load_covered_reference_need_mib,
measured_request_extra_mib,
DECODE_LEND_ATTR,
decode_lend_from_plan,
@@ -11233,7 +11239,9 @@ class DiffusionBackend:
"measured_runtime_headroom_mib"
)
if headroom and (
- plan.resident_transformer_mib or plan.resident_text_encoder_mib
+ plan.resident_transformer_mib
+ or plan.resident_text_encoder_mib
+ or plan.estimates.get("measured_reference_te_cut_mib")
):
pipe._unsloth_measured_reserve = (
int(headroom),
@@ -11251,6 +11259,13 @@ class DiffusionBackend:
bool(streamed_headroom),
# MEASURED_RESERVE_DENOISE_PHASE_INDEX: the blocks sized from the denoise phase
plan.estimates.get("measured_denoise_phase_headroom_mib"),
+ # MEASURED_RESERVE_REFERENCE_INDEX: the edit the placement priced, if any
+ (
+ int(plan.estimates["measured_reference_phase_mib"]),
+ int(plan.estimates["measured_reference_reserve_mib"]),
+ )
+ if plan.estimates.get("measured_reference_reserve_mib")
+ else None,
)
setattr(pipe, DECODE_LEND_ATTR, decode_lend_from_plan(plan))
@@ -15059,8 +15074,8 @@ class DiffusionBackend:
)
# unweighted reference pixels: a measured placement prices them from their token count
if ref_resolution is not None and not layer_count:
- guard_reference_pixels = int(
- (1 + len(ref_extra)) * ref_resolution * ref_resolution
+ guard_reference_pixels = reference_request_pixels(
+ ref_resolution, len(ref_extra)
)
if layer_count:
# layers + 1 extra canvas-sized frames beside the output-sized one.
@@ -15114,6 +15129,56 @@ class DiffusionBackend:
guard_capture_gen = cuda_graph.capture_generation(_peak_device_index(state))
# groups an earlier oversized request streamed out stay out when this one streams them all too
carried_restore, extra_mib = take_deferred_restore(state.pipe, extra_mib)
+
+ def _guard_kwargs() -> dict:
+ return dict(
+ # Not the settled snapshot: its empty_cache() is wrong per generation (re-mallocs activations).
+ device_memory = reclaimable_snapshot_device_memory(guard_target),
+ width = guard_width,
+ height = guard_height,
+ batch_size = guard_batch,
+ # The hint the load planned with, so the distilled / edit multipliers match.
+ family = state.variant_hint,
+ # Only img2img is bounded by the Resolution control (_fit_within); others need an upload-side fix.
+ source_driven = source_sized and workflow != "img2img",
+ condition_pixels = guard_condition_pixels,
+ vae_tile_side = vae_tile_side(getattr(pipe, "vae", None)),
+ vae_sliced = vae_can_slice(getattr(pipe, "vae", None)),
+ quadratic_attention = guard_quadratic,
+ allow_oversized = allow_oversized,
+ calibrated_placement = bool(
+ getattr(state, "calibrated_placement", False)
+ ),
+ controlnet = workflow == "controlnet" and control_pil is not None,
+ logger = logger,
+ )
+
+ if extra_mib > 0 and guard_reference_pixels > 0:
+ reference_need = load_covered_reference_need_mib(
+ state.pipe,
+ width = guard_width,
+ height = guard_height,
+ batch_size = guard_batch,
+ reference_pixels = guard_reference_pixels,
+ cfg = guard_cfg,
+ quadratic_attention = guard_quadratic,
+ )
+ static_release = (
+ None
+ if reference_need is None
+ else static_reference_release_mib(state.pipe, reference_need)
+ )
+ if static_release is not None and extra_mib <= static_release:
+ short = live_reference_shortfall_mib(
+ state.pipe, reference_need, guard_target.torch_device
+ )
+ # never looser than the activation guard below
+ if short is not None and short < extra_mib:
+ fits = image_activation_verdict(
+ **{k: v for k, v in _guard_kwargs().items() if k != "logger"}
+ )
+ if fits.action != ACTIVATION_REFUSE:
+ extra_mib = short
if extra_mib > 0:
releasable_mib = resident_group_mib(state.pipe)
if (
@@ -15129,25 +15194,7 @@ class DiffusionBackend:
if restore_resident is None
else chained_restore(carried_restore, restore_resident)
)
- guard_kwargs = dict(
- # Not the settled snapshot: its empty_cache() is wrong per generation (re-mallocs activations).
- device_memory = reclaimable_snapshot_device_memory(guard_target),
- width = guard_width,
- height = guard_height,
- batch_size = guard_batch,
- # The hint the load planned with, so the distilled / edit multipliers match.
- family = state.variant_hint,
- # Only img2img is bounded by the Resolution control (_fit_within); others need an upload-side fix.
- source_driven = source_sized and workflow != "img2img",
- condition_pixels = guard_condition_pixels,
- vae_tile_side = vae_tile_side(getattr(pipe, "vae", None)),
- vae_sliced = vae_can_slice(getattr(pipe, "vae", None)),
- quadratic_attention = guard_quadratic,
- allow_oversized = allow_oversized,
- calibrated_placement = bool(getattr(state, "calibrated_placement", False)),
- controlnet = workflow == "controlnet" and control_pil is not None,
- logger = logger,
- )
+ guard_kwargs = _guard_kwargs()
verdict = raise_on_image_activation_shortfall(**guard_kwargs)
if _hires_pass is not None and _hires_pass.preflight is not None:
_hires_pass.preflight(guard_kwargs)
diff --git a/studio/backend/core/inference/diffusion_conditioning.py b/studio/backend/core/inference/diffusion_conditioning.py
index 6a11b967290..820f2c14c41 100644
--- a/studio/backend/core/inference/diffusion_conditioning.py
+++ b/studio/backend/core/inference/diffusion_conditioning.py
@@ -129,6 +129,17 @@ def effective_reference_resolution(fam: Any, requested: Optional[int]) -> Option
return int(requested)
+def reference_request_pixels(ref_resolution: Optional[int], extra_images: int = 0) -> int:
+ """Shared by the load's edit placement and the render-time guard, so both price the same pixels."""
+ if not ref_resolution:
+ return 0
+ return int((1 + max(0, int(extra_images))) * int(ref_resolution) * int(ref_resolution))
+
+
+def default_reference_pixels(fam: Any) -> int:
+ return reference_request_pixels(effective_reference_resolution(fam, None))
+
+
def _decode_bounded(data: str, mode: str, budget: list[int], what: str) -> Any:
from core.inference.diffusion import decode_b64_image
diff --git a/studio/backend/core/inference/diffusion_memory.py b/studio/backend/core/inference/diffusion_memory.py
index 065cd90cf5a..c76bab20637 100644
--- a/studio/backend/core/inference/diffusion_memory.py
+++ b/studio/backend/core/inference/diffusion_memory.py
@@ -5008,7 +5008,41 @@ def _refine_plan_from_loaded_weights(
measured_decode_peak_quadratic = split["quadratic"],
decode_lend_text_encoder_mib = lend,
)
- if dit_room <= 0 and te_room <= 0:
+ reference_cut = 0
+ if (
+ policy == OFFLOAD_GROUP
+ and stream_te
+ and not whole_dit
+ and not wide_dit
+ and (not bool(getattr(plan, "stream_transformer", True)) or dit_room >= dit)
+ ):
+ # The resident transformer must also hold an edit's denoise, else the first edit streams it mid-render.
+ reference = _load_reference_need(
+ pipe,
+ family = family,
+ speed_mode = speed_mode,
+ quant = read_quant,
+ static_seed = static_seed,
+ )
+ if reference is not None:
+ basis = phase_headroom if lend > 0 and phase_headroom is not None else headroom
+ spare = max(
+ 0, int(room) + int(headroom) - int(basis) - int(dit_room) - int(te_room)
+ )
+ short = max(0, int(reference[1]) - int(basis) - spare)
+ # Cut the encoder only when a render-time release of it could not cover the reference.
+ reference_cut = int(te_room) if short > int(te_room) else 0
+ te_room -= reference_cut
+ if lend > 0:
+ lend = max(0, lend - reference_cut)
+ estimates["decode_lend_text_encoder_mib"] = lend
+ estimates.update(
+ measured_reference_phase_mib = reference[0],
+ measured_reference_need_mib = reference[1],
+ measured_reference_reserve_mib = int(basis) + spare + reference_cut,
+ measured_reference_te_cut_mib = reference_cut,
+ )
+ if dit_room <= 0 and te_room <= 0 and not reference_cut:
return plan
if whole_dit or wide_dit:
estimates["resident_dit_slack_mib"] = _resident_dit_slack_mib(memory)
@@ -5042,6 +5076,12 @@ def _refine_plan_from_loaded_weights(
else ""
)
+ "); the rest streams"
+ + (
+ f" ({reference_cut} MiB of the encoders stream instead so the transformer also holds a "
+ f"{estimates['measured_reference_need_mib']} MiB edit denoise)"
+ if reference_cut
+ else ""
+ )
+ (
f" (whole transformer within free memory less a {_resident_dit_slack_mib(memory)} MiB slack;"
f" {encode_room} MiB of it while the encoders run)"
@@ -6201,6 +6241,142 @@ def derived_reference_need_mib(
return int(-(-total // step) * step)
+# "0": the load places for text-to-image only; an edit's reference then streams resident groups mid-render.
+EDIT_LOAD_PLACEMENT_ENV = "UNSLOTH_DIFFUSION_EDIT_LOAD_PLACEMENT"
+# ``_unsloth_measured_reserve`` slot: (denoise phase MiB, MiB the placement covers).
+MEASURED_RESERVE_REFERENCE_INDEX = 14
+
+
+def edit_load_placement_enabled() -> bool:
+ return derived_reference_pricing_enabled() and not _env_off(EDIT_LOAD_PLACEMENT_ENV)
+
+
+def _default_reference_pixels(family: str) -> int:
+ """Uses the request path's helpers so the load and the render-time guard price the same image."""
+ try:
+ from .diffusion_conditioning import default_reference_pixels
+ from .diffusion_families import _FAMILIES
+
+ fam = next((f for f in _FAMILIES if str(f.name).lower() == family), None)
+ return default_reference_pixels(fam) if fam is not None else 0
+ except Exception: # noqa: BLE001 - unreadable: no edit placement
+ return 0
+
+
+def _load_reference_need(
+ pipe: Any,
+ *,
+ family: Optional[str],
+ speed_mode: Optional[str],
+ quant: Optional[str],
+ static_seed: bool,
+) -> Optional[tuple[int, int]]:
+ """(denoise phase MiB, denoise MiB) of a guidance-free default edit; None when unpriced or switched off."""
+ name = (str(family or "").split() or [""])[0].lower()
+ if not edit_load_placement_enabled() or name not in _DERIVED_REFERENCE_FAMILIES:
+ return None
+ phases = _MEASURED_IMAGE_ACTIVATION_MIB.get(name)
+ if (
+ phases is None
+ or not static_seed
+ or not bool(getattr(pipe, "_unsloth_phase_seeds", False))
+ or str(speed_mode or "") not in _MEASURED_PEAK_SPEED_MODES
+ ):
+ return None
+ reference = _default_reference_pixels(name)
+ if not reference:
+ return None
+ step = _MEASURED_PEAK_ROUND_MIB
+ row = phases[1 if speed_mode == "max" else 0]
+ phase = int(math.ceil(row[_PHASE_DENOISE_COLUMN] * _MEASURED_PEAK_MARGIN))
+ phase = int(-(-phase // step) * step)
+ need = derived_reference_need_mib(
+ pipe,
+ family = family,
+ phase_mib = phase,
+ width = DEFAULT_IMAGE_WIDTH,
+ height = DEFAULT_IMAGE_HEIGHT,
+ reference_pixels = reference,
+ cfg = False,
+ )
+ if need is None:
+ return None
+ if quant is not None:
+ learned = measured_image_runtime_mib(
+ family, speed_mode, quant = with_workflow(quant, "edit"), static_seed = False
+ )
+ if learned is not None:
+ need = max(int(need), int(learned))
+ return phase, int(need)
+
+
+def load_covered_reference_need_mib(
+ pipe: Any,
+ *,
+ width: Optional[int],
+ height: Optional[int],
+ batch_size: int = 1,
+ reference_pixels: int = 0,
+ cfg: Optional[bool] = None,
+ quadratic_attention: bool = False,
+) -> Optional[int]:
+ reserve = getattr(pipe, "_unsloth_measured_reserve", None) or ()
+ if len(reserve) <= MEASURED_RESERVE_REFERENCE_INDEX or int(reference_pixels or 0) <= 0:
+ return None
+ covered = reserve[MEASURED_RESERVE_REFERENCE_INDEX]
+ if not covered or not edit_load_placement_enabled():
+ return None
+ return derived_reference_need_mib(
+ pipe,
+ family = reserve[1],
+ phase_mib = int(covered[0]),
+ width = width,
+ height = height,
+ batch_size = batch_size,
+ reference_pixels = int(reference_pixels),
+ cfg = cfg,
+ compute_bytes = reserve[4] if len(reserve) > 4 and reserve[4] else 2,
+ quadratic_attention = quadratic_attention,
+ )
+
+
+def static_reference_release_mib(pipe: Any, need_mib: int) -> Optional[int]:
+ reserve = getattr(pipe, "_unsloth_measured_reserve", None)
+ if not reserve or len(reserve) <= MEASURED_RESERVE_REFERENCE_INDEX:
+ return None
+ covered = reserve[MEASURED_RESERVE_REFERENCE_INDEX]
+ if not covered:
+ return None
+ return max(0, int(need_mib) - max(int(reserve[0]), int(covered[1])))
+
+
+def live_reference_shortfall_mib(
+ pipe: Any,
+ need_mib: int,
+ device: Any = None,
+) -> Optional[int]:
+ """MiB ``need_mib`` lacks in free memory now (driver free less budget reserve, plus reusable cache); None if unreadable."""
+ try:
+ import torch
+
+ dev = torch.device(device if device is not None else "cuda")
+ if dev.type != "cuda":
+ return None
+ if dev.index is None:
+ dev = torch.device("cuda", torch.cuda.current_device())
+ free, total = (int(x) for x in torch.cuda.mem_get_info(dev))
+ free -= user_budget_reserve_bytes(dev, total)
+ cached = max(
+ 0,
+ int(torch.cuda.memory_reserved(dev))
+ - int(torch.cuda.memory_allocated(dev))
+ - _graph_held_cache_bytes(dev.index),
+ )
+ return max(0, int(need_mib) + _DECODE_SLACK_MIB - ((free + cached) >> 20))
+ except Exception: # noqa: BLE001 - unreadable: the planned release stands
+ return None
+
+
def measured_request_extra_mib(
pipe: Any,
*,
@@ -6352,6 +6528,34 @@ def measured_request_extra_mib(
need = own if need is None else max(need, own)
if need is None:
return 0
+ covered = (
+ reserve[MEASURED_RESERVE_REFERENCE_INDEX]
+ if len(reserve) > MEASURED_RESERVE_REFERENCE_INDEX
+ else None
+ )
+ if (
+ not phase
+ and covered
+ and allowance > 0
+ and int(reference_pixels or 0) > 0
+ and tier_peak is None
+ and base_need is not None
+ and int(base_need) <= int(headroom)
+ ):
+ # only the steps grow with the reference (encode and decode run under their own hooks)
+ derived = load_covered_reference_need_mib(
+ pipe,
+ width = width,
+ height = height,
+ batch_size = batch_size,
+ reference_pixels = int(reference_pixels),
+ cfg = cfg,
+ quadratic_attention = quadratic_attention,
+ )
+ if derived is not None:
+ if own_learned is not None:
+ derived = max(int(derived), int(own_learned))
+ return max(0, int(derived) - max(int(headroom), int(covered[1])))
if phase:
pixels = (
max(64, int(width or DEFAULT_IMAGE_WIDTH))
diff --git a/studio/backend/tests/test_diffusion_edit_load_placement.py b/studio/backend/tests/test_diffusion_edit_load_placement.py
new file mode 100644
index 00000000000..4906d330f9d
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_edit_load_placement.py
@@ -0,0 +1,336 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""An edit-capable load places for a reference's denoise, so the first edit does not hook the resident transformer.
+
+Repro: Qwen-Image-2.1 int8 edit at 16 GiB released a flat 3014 MiB, more than the encoder held, so the transformer
+streamed mid-render."""
+
+from __future__ import annotations
+
+import pathlib
+import types
+
+import pytest
+
+import core.inference.diffusion_measured_peaks as mp
+import core.inference.diffusion_memory as dm
+
+Q21_LOADED = {
+ "transformer": (6922, "dit"),
+ "text_encoder": (8959, "text_encoder"),
+ "vae": (644, "other"),
+}
+Q21_FLAT = dict(model_dense_mib = 19630, companion_dense_mib = 12182, text_encoder_dense_mib = 10847)
+REF = 1024 * 1024
+COND = int(REF * 0.32)
+FLAT_EXTRA = int(8192 * 0.32 * dm._MEASURED_PEAK_MARGIN) # 3014, the logged release
+
+
+class _Qwen21:
+ def __init__(self):
+ self.config = types.SimpleNamespace(
+ num_layers = 32,
+ num_attention_heads = 32,
+ attention_head_dim = 128,
+ patch_size = 1,
+ causal_condition = True,
+ )
+
+ def forward(
+ self,
+ hidden_states,
+ kv_cache = None,
+ kv_cache_mode = None,
+ ):
+ return hidden_states
+
+
+def _pipe():
+ return types.SimpleNamespace(
+ transformer = _Qwen21(), vae_scale_factor = 16, _unsloth_phase_seeds = True
+ )
+
+
+def q21(tmp_path, monkeypatch):
+ monkeypatch.setenv(mp.LEARNED_PEAKS_FILE_ENV, str(tmp_path / "peaks.json"))
+ for env in (
+ mp.LEARNED_PEAKS_ENV,
+ mp.PHASE_PEAKS_ENV,
+ dm.MEASURED_ACTIVATION_ENV,
+ dm.PARTIAL_RESIDENT_ENV,
+ dm.DERIVED_REFERENCE_PRICE_ENV,
+ "UNSLOTH_DIFFUSION_EDIT_LOAD_PLACEMENT",
+ ):
+ monkeypatch.delenv(env, raising = False)
+ mp._cache.update(path = None, mtime = None, data = None)
+ monkeypatch.setattr(dm, "_loaded_component_mib", lambda pipe: dict(Q21_LOADED), raising = False)
+ monkeypatch.setattr(dm, "_pipe_denoisers_hold_torchao", lambda pipe: True)
+ return _pipe()
+
+
+def _plan(budget_mib: int, total_mib: int):
+ reserve = dm._reserve_mib("discrete_vram", total_mib)
+ memory = dm.DeviceMemory("cuda", "cuda", "discrete_vram", budget_mib + reserve, total_mib)
+ plan = dm.plan_diffusion_memory(
+ target = types.SimpleNamespace(supports_model_cpu_offload = True),
+ device_memory = memory,
+ runtime_headroom_mib = dm.estimate_image_runtime_mib(
+ width = None, height = None, family = "qwen-image-2.1"
+ ),
+ requested_mode = None,
+ **Q21_FLAT,
+ )
+ if plan.offload_policy == dm.OFFLOAD_MODEL:
+ plan = dm.torchao_streaming_plan(plan)
+ return plan
+
+
+def _refine(pipe, plan):
+ return dm.refine_plan_from_loaded_weights(
+ pipe, plan, family = "qwen-image-2.1", speed_mode = "default"
+ )
+
+
+def _reserve(plan):
+ est = plan.estimates
+ covered = (
+ (int(est["measured_reference_phase_mib"]), int(est["measured_reference_reserve_mib"]))
+ if est.get("measured_reference_reserve_mib")
+ else None
+ )
+ return (
+ int(est["measured_runtime_headroom_mib"]),
+ "qwen-image-2.1",
+ "default",
+ est.get("measured_dense_transformer_mib"),
+ est.get("measured_compute_bytes"),
+ est.get("measured_learned_peak_mib"),
+ est.get("measured_learned_peak_pixels"),
+ est.get("measured_learned_peak_quadratic"),
+ est.get("measured_static_seed", True),
+ est.get("measured_learned_cfg_off", False),
+ est.get("measured_dense_bf16", False),
+ est.get("measured_small_host_int8", False),
+ bool(est.get("measured_streamed_headroom_mib")),
+ est.get("measured_denoise_phase_headroom_mib"),
+ covered,
+ )
+
+
+def _edit_extra(pipe, plan, **kw):
+ pipe._unsloth_measured_reserve = _reserve(plan)
+ args = dict(
+ width = 1024,
+ height = 1024,
+ condition_pixels = COND,
+ reference_pixels = REF,
+ cfg = False,
+ workflow = "edit",
+ )
+ args.update(kw)
+ return dm.measured_request_extra_mib(pipe, **args)
+
+
+def _room(budget):
+ return budget - 2304 - dm.DEFAULT_BASE_OVERHEAD_MIB - 644 - 6922
+
+
+# 24 GiB (the encoder whole beside the transformer), an L4 (most of it), 16 GiB (part of it)
[email protected]("budget,total", [(21432, 24576), (20000, 23034), (14500, 16376)])
+def test_where_the_encoder_can_cover_an_edit_text_to_image_keeps_it_resident(q21, budget, total):
+ plan = _refine(q21, _plan(budget, total))
+ assert plan.offload_policy == dm.OFFLOAD_GROUP and plan.stream_text_encoders
+ assert plan.resident_transformer_mib in (None, 6922)
+ # the guidance-free 1024 edit: 768 x 2 joint sequence + 2048 MiB condition cache x 1.15 -> 4096
+ assert plan.estimates["measured_reference_need_mib"] == 4096
+ assert plan.resident_text_encoder_mib == min(8959, _room(budget))
+ assert plan.estimates["measured_reference_te_cut_mib"] == 0
+ # the edit is priced from its tokens (not the flat 3014 MiB) and the resident encoder alone covers it: no hooks
+ extra = _edit_extra(q21, plan)
+ assert extra == 4096 - plan.estimates["measured_reference_reserve_mib"] < FLAT_EXTRA
+ assert extra <= plan.resident_text_encoder_mib
+
+
+def test_text_to_image_requests_are_priced_as_before(q21):
+ plan = _refine(q21, _plan(14500, 16376))
+ q21._unsloth_measured_reserve = _reserve(plan)
+ assert dm.measured_request_extra_mib(q21, width = 1024, height = 1024) == 0
+ assert dm.measured_request_extra_mib(q21, width = 2048, height = 2048) == 8704 - 2304
+
+
+def test_a_guidance_edit_is_still_priced_past_the_placement(q21):
+ plan = _refine(q21, _plan(14500, 16376))
+ # 2 x (1536 + 2355) = 7782 -> 7936 against the 2304 placed
+ assert _edit_extra(q21, plan, cfg = None) == 7936 - 2304
+
+
+def test_kill_switch_keeps_the_text_to_image_placement(q21, monkeypatch):
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_EDIT_LOAD_PLACEMENT", "0")
+ plan = _refine(q21, _plan(14500, 16376))
+ room = 14500 - 2304 - dm.DEFAULT_BASE_OVERHEAD_MIB - 644 - 6922
+ assert plan.resident_text_encoder_mib == room
+ assert "measured_reference_reserve_mib" not in plan.estimates
+ assert _edit_extra(q21, plan) == FLAT_EXTRA > room
+
+
+def test_the_derived_price_switch_also_turns_it_off(q21, monkeypatch):
+ monkeypatch.setenv(dm.DERIVED_REFERENCE_PRICE_ENV, "0")
+ plan = _refine(q21, _plan(14500, 16376))
+ assert "measured_reference_reserve_mib" not in plan.estimates
+
+
+def test_other_families_are_untouched(q21):
+ plan = _plan(14500, 16376)
+ for family in ("qwen-image-2.1-turbo", "flux.1", "qwen-image"):
+ refined = dm.refine_plan_from_loaded_weights(q21, plan, family = family, speed_mode = "default")
+ assert "measured_reference_reserve_mib" not in refined.estimates
+
+
+def test_a_streaming_tier_load_is_untouched(q21):
+ """8 / 12 GiB stream the transformer: the denoise-phase placement already prices references (#17233)."""
+ for budget, total in ((5600, 8188), (9319, 12288)):
+ plan = _refine(q21, _plan(budget, total))
+ assert "measured_reference_reserve_mib" not in plan.estimates
+
+
+def test_the_encoders_give_way_down_to_none(q21):
+ """16 GiB: the 1489 MiB resident encoder cannot cover the 1792 MiB edit, so the whole encoder streams instead."""
+ plan = _refine(q21, _plan(13407, 16376))
+ assert _room(13407) == 1489 < 4096 - 2304
+ assert plan.resident_text_encoder_mib is None
+ assert plan.estimates["measured_reference_te_cut_mib"] == 1489
+ assert plan.estimates["measured_reference_reserve_mib"] == 2304 + 1489
+ assert 0 < _edit_extra(q21, plan) == 4096 - 3793 < FLAT_EXTRA
+
+
+def test_generate_releases_only_the_live_shortfall_for_a_priced_edit():
+ src = (pathlib.Path(dm.__file__).parent / "diffusion.py").read_text(encoding = "utf-8")
+ at = src.index("reference_need = load_covered_reference_need_mib(")
+ hook = src.index("hook_resident_denoiser(state.pipe, guard_target.torch_device, logger)")
+ assert at < hook
+ trim = src[at:hook]
+ # the trim never runs looser than the activation guard: a request it would refuse keeps the planned release
+ assert "image_activation_verdict(" in trim and "fits.action != ACTIVATION_REFUSE" in trim
+ assert trim.index("fits.action != ACTIVATION_REFUSE") < trim.index("extra_mib = short")
+ assert "guard_kwargs = _guard_kwargs()" in src
+ stored = src.index("MEASURED_RESERVE_REFERENCE_INDEX: the edit the placement priced")
+ assert "measured_reference_reserve_mib" in src[stored : stored + 400]
+
+
+def _q21_family():
+ from core.inference.diffusion_families import _FAMILIES
+ return next(f for f in _FAMILIES if f.name == "qwen-image-2.1")
+
+
+ "budget,total", [(21432, 24576), (20000, 23034), (14500, 16376), (13407, 16376)]
+)
+def test_the_load_and_the_first_edit_guard_agree_on_a_default_edit(q21, budget, total):
+ """A default edit's guard inputs, built as generate() builds them, never need to hook the transformer."""
+ from core.inference.diffusion_conditioning import (
+ effective_reference_resolution,
+ reference_request_pixels,
+ )
+
+ fam = _q21_family()
+ side = effective_reference_resolution(fam, None)
+ reference_pixels = reference_request_pixels(side, 0)
+ condition_pixels = int(1 * side * side * fam.condition_pixel_weight)
+ plan = _refine(q21, _plan(budget, total))
+ assert dm._default_reference_pixels("qwen-image-2.1") == reference_pixels == REF
+ need = dm.load_covered_reference_need_mib(
+ _with_reserve(q21, plan),
+ width = 1024,
+ height = 1024,
+ reference_pixels = reference_pixels,
+ cfg = False,
+ )
+ assert need == plan.estimates["measured_reference_need_mib"]
+ extra = dm.measured_request_extra_mib(
+ q21,
+ width = 1024,
+ height = 1024,
+ condition_pixels = condition_pixels,
+ reference_pixels = reference_pixels,
+ cfg = False,
+ workflow = "edit",
+ )
+ covered = plan.estimates["measured_reference_reserve_mib"]
+ assert extra == max(0, need - covered) < FLAT_EXTRA
+ if plan.estimates["measured_reference_te_cut_mib"]:
+ # every encoder layer already gave way: only the part the plan could not cover is left to the live check
+ assert plan.resident_text_encoder_mib is None
+ else:
+ # what the edit adds fits in the encoder the guard can release first
+ assert extra <= int(plan.resident_text_encoder_mib or 0)
+
+
+def _with_reserve(pipe, plan):
+ pipe._unsloth_measured_reserve = _reserve(plan)
+ return pipe
+
+
+def test_a_larger_reference_resolution_is_priced_past_the_default_placement(q21):
+ from core.inference.diffusion_conditioning import reference_request_pixels
+
+ plan = _refine(q21, _plan(21432, 24576))
+ _with_reserve(q21, plan)
+ two_k = reference_request_pixels(2048, 0)
+ assert (
+ dm.measured_request_extra_mib(
+ q21,
+ width = 1024,
+ height = 1024,
+ condition_pixels = int(two_k * 0.32),
+ reference_pixels = two_k,
+ cfg = False,
+ workflow = "edit",
+ )
+ > 0
+ )
+
+
+def test_generate_prices_the_reference_with_the_shared_helper():
+ src = (pathlib.Path(dm.__file__).parent / "diffusion.py").read_text(encoding = "utf-8")
+ assert "guard_reference_pixels = reference_request_pixels(" in src
+
+
+def _static_release(pipe, plan):
+ pipe._unsloth_measured_reserve = _reserve(plan)
+ need = dm.load_covered_reference_need_mib(
+ pipe, width = 1024, height = 1024, batch_size = 1, reference_pixels = REF, cfg = False
+ )
+ return dm.static_reference_release_mib(pipe, need)
+
+
+def test_the_live_trim_applies_when_the_token_estimate_set_the_release(q21):
+ plan = _refine(q21, _plan(13407, 16376))
+ assert _static_release(q21, plan) == _edit_extra(q21, plan) > 0
+
+
+def test_a_learned_edit_peak_keeps_the_planned_release_whole(q21, monkeypatch):
+ # a learned edit peak above the token estimate raises the planned release; the live trim must not undercut it
+ plan = _refine(q21, _plan(13407, 16376))
+ static = _static_release(q21, plan)
+ q21._unsloth_peak_identity = ("qwen-image-2.1", "int8", "default")
+ real = dm.measured_image_runtime_mib
+
+ def learned(
+ family,
+ speed_mode,
+ quant = None,
+ **kw,
+ ):
+ if quant and "edit" in str(quant):
+ return 12000
+ return real(family, speed_mode, quant = quant, **kw)
+
+ monkeypatch.setattr(dm, "measured_image_runtime_mib", learned)
+ assert _edit_extra(q21, plan) > static
+ src = (pathlib.Path(dm.__file__).parent / "diffusion.py").read_text(encoding = "utf-8")
+ trim = src[src.index("reference_need = load_covered_reference_need_mib(") :]
+ trim = trim[: trim.index("extra_mib = short")]
+ assert "static_reference_release_mib(state.pipe, reference_need)" in trim
+ assert "extra_mib <= static_release" in trim