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: measured activation rows for MOSS-Image and FLUX.3 Klein base; layer split prices Z-Image from its measured row (#14950)

Daniel Hanbef946c65040
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index c18afa7f987..8f56e3cfe33 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -2582,6 +2582,20 @@ def _tile_for_verdict(
return restore_vae
+def plan_is_calibrated(plan: Any) -> bool:
+ """Whether ``plan`` was fitted to the measured activation row rather than the flat estimate: the one-card plan, or
+ a multi-GPU split priced with ``calibrated_split_headroom_mib``. The generate guard then charges conditioning
+ (ControlNet, references) on top and drops the flat default-resolution exemption."""
+ estimates = getattr(plan, "estimates", None) or {}
+ if "calibrated_headroom_mib" in estimates:
+ return True
+ split = (
+ getattr(plan, "layer_split", None) is not None
+ or getattr(plan, "secondary_ordinal", None) is not None
+ )
+ return split and "calibrated_split_headroom_mib" in estimates
+
+
def _controlnet_streams(state: Any) -> bool:
"""Whether a ControlNet added at generate time streams from host memory instead of loading whole beside the base
model: under any offload policy, a calibrated placement (budgets only the base model), and a multi-GPU split
@@ -10278,7 +10292,7 @@ class DiffusionBackend:
kind = kind,
cpu_offload = effective_policy != OFFLOAD_NONE,
offload_policy = effective_policy,
- calibrated_placement = "calibrated_headroom_mib" in plan.estimates,
+ calibrated_placement = plan_is_calibrated(plan),
vae_tiling = effective_tiling,
memory_mode = plan.requested_mode,
speed_mode = effective_speed,
diff --git a/studio/backend/core/inference/diffusion_memory.py b/studio/backend/core/inference/diffusion_memory.py
index 9223651cb30..031839c9658 100644
--- a/studio/backend/core/inference/diffusion_memory.py
+++ b/studio/backend/core/inference/diffusion_memory.py
@@ -1488,6 +1488,10 @@ _MEASURED_IMAGE_ACTIVATION_MIB: dict[
# untiled 2048 decode is 9_738. References are charged through ``condition_pixel_weight``. The base (CFG) is
# unmeasured and keeps the flat estimate.
"flux.3-klein": ((301, 901, 2_437, 2_437, 3_359), (301, 901, 2_437, 2_437, 3_359)),
+ # FLUX.3 Klein base, B200 bf16: per column the larger of Klein and base (same DiT / VAE, one Flux2 formula in ComfyUI).
+ "flux.3-klein-base": ((301, 901, 2_512, 2_512, 3_359), (301, 901, 2_512, 2_512, 3_359)),
+ # MOSS-Image SFT, B200 bf16 measurements; both tiers take the eager worst.
+ "moss-image": ((1_940, 528, 3_666, 3_662, 3_750), (1_940, 528, 3_666, 3_662, 3_750)),
"z-image": ((744, 1_199, 2_666, 2_456, 4_327), (744, 1_271, 2_669, 2_456, 4_327)),
}
@@ -2518,6 +2522,11 @@ def plan_diffusion_memory(
any_offload = policy != OFFLOAD_NONE
reasons.append(reason)
estimates["calibrated_headroom_mib"] = calibrated_activation.headroom(tile)
+ if calibrated_activation is not None and "calibrated_headroom_mib" not in estimates:
+ from .diffusion_multigpu import current_selection
+ if current_selection() is not None:
+ # Untiled: a layer split keeps the VAE resident on the primary.
+ estimates["calibrated_split_headroom_mib"] = calibrated_activation.headroom(False)
split = _multigpu_companion_split(
target = target,
device_memory = device_memory,
diff --git a/studio/backend/core/inference/diffusion_multigpu.py b/studio/backend/core/inference/diffusion_multigpu.py
index afd9f220d1d..cdfa46941e9 100644
--- a/studio/backend/core/inference/diffusion_multigpu.py
+++ b/studio/backend/core/inference/diffusion_multigpu.py
@@ -755,6 +755,7 @@ def refine_plan_for_multigpu(
headroom = int(
plan.estimates.get("measured_runtime_headroom_mib")
or plan.estimates.get("calibrated_headroom_mib")
+ or plan.estimates.get("calibrated_split_headroom_mib")
or plan.estimates.get("runtime_headroom_mib")
or 0
)
diff --git a/studio/backend/tests/test_diffusion_activation_factors.py b/studio/backend/tests/test_diffusion_activation_factors.py
new file mode 100644
index 00000000000..2aa5dd991d5
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_activation_factors.py
@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The newer image families resolve to their own measured activation rows, not the flat 8 GiB per megapixel default. CPU only."""
+
+from __future__ import annotations
+
+import types
+
+import pytest
+
+import core.inference.diffusion as diffusion
+import core.inference.diffusion_memory as dm
+from core.inference.diffusion_families import _FAMILIES
+
+# family -> (text encoder, denoise, untiled decode, tiled decode, 2048^2 worst) MiB, B200 measurements
+MEASURED = {
+ "qwen-image-2.1": (1_849, 2_489, 7_648, 1_697, 9_602),
+ "moss-image": (1_940, 528, 3_666, 3_662, 3_750),
+ "flux.3-klein": (301, 901, 2_437, 2_437, 3_359),
+ "flux.3-klein-base": (301, 901, 2_512, 2_512, 3_359),
+}
+
+
[email protected]("family", sorted(MEASURED))
+def test_family_resolves_to_its_measured_row(family):
+ act = dm.calibrated_image_activation(family, max_speed = True)
+ assert act is not None, family
+ expected = tuple(int(v * dm._ACTIVATION_MARGIN) for v in MEASURED[family])
+ assert (
+ act.text_encoder_mib,
+ act.denoise_mib,
+ act.decode_mib,
+ act.tiled_decode_mib,
+ act.max_canvas_mib,
+ ) == expected
+ flat = dm.estimate_image_runtime_mib(width = None, height = None, family = family)
+ assert act.headroom(tiled = True) < flat
+
+
[email protected]("family", sorted(MEASURED))
+def test_tiers_only_grow_with_speed(family):
+ off, fast = dm._MEASURED_IMAGE_ACTIVATION_MIB[family]
+ assert all(b >= a for a, b in zip(off, fast))
+
+
+def test_flux3_base_is_priced_at_least_like_klein():
+ base = dm._MEASURED_IMAGE_ACTIVATION_MIB["flux.3-klein-base"]
+ klein = dm._MEASURED_IMAGE_ACTIVATION_MIB["flux.3-klein"]
+ for tb, tk in zip(base, klein):
+ assert all(b >= k for b, k in zip(tb, tk))
+
+
[email protected]("family", sorted(MEASURED))
+def test_load_plan_reads_the_row_on_nvidia(monkeypatch, family):
+ fam = next((f for f in _FAMILIES if f.name == family), None)
+ assert fam is not None, family
+ target = types.SimpleNamespace(backend = "cuda", vendor = "nvidia", dtype = None)
+ monkeypatch.setattr(diffusion, "sdpa_subquadratic_confirmed", lambda target: True)
+ monkeypatch.setattr(diffusion, "_resolve_diffusion_compute_dtype", lambda fam, dtype: None)
+ monkeypatch.setattr(diffusion, "_float_load_itemsize", lambda compute: 2)
+ act = diffusion._calibrated_activation(fam, target)
+ assert act is not None, family
+ assert act.decode_mib == int(MEASURED[family][2] * dm._ACTIVATION_MARGIN)
diff --git a/studio/backend/tests/test_diffusion_auto_placement.py b/studio/backend/tests/test_diffusion_auto_placement.py
index 99313af90bf..b1fa8956a78 100644
--- a/studio/backend/tests/test_diffusion_auto_placement.py
+++ b/studio/backend/tests/test_diffusion_auto_placement.py
@@ -189,6 +189,7 @@ def decide(
gpu_ids: Optional[list[int]] = None,
preload_split: bool = True,
place: bool = True,
+ calibrated: Optional[dm.CalibratedImageActivation] = None,
) -> Decision:
"""What an Automatic load (``gpu_ids`` None) or an explicit selection decides on ``host`` for ``sizes``."""
host.install(monkeypatch)
@@ -225,6 +226,7 @@ def decide(
text_encoder_dense_mib = tes,
runtime_headroom_mib = headroom,
requested_mode = "auto",
+ calibrated_activation = calibrated,
)
with mg.selection_scope(selection):
plan = mg.refine_plan_for_multigpu(pipe, one_card)
@@ -564,3 +566,56 @@ def test_layer_split_decline_reports_the_encode_activation_it_charged():
)
assert split is None
assert "5555 MiB of activations" in reason
+
+
+# Kaggle 2x T4 Z-Image-Turbo fp16: the split was priced with the flat estimate and declined by ~1 GB.
+_ZIMAGE_T4 = dict(dit = 11739, te = 7672, vae = 211)
+_ZIMAGE_FLAT = 6963
+
+
+def test_zimage_on_two_t4s_flat_estimate_declines_the_layer_split(monkeypatch):
+ host = Host([Card(0, T4, 300), Card(1, T4, 300)])
+ d = decide(monkeypatch, host, _sizes(**_ZIMAGE_T4), headroom = _ZIMAGE_FLAT)
+ assert d.plan.layer_split is None and d.plan.offload_policy != dm.OFFLOAD_NONE
+ layer = [r["reason"] for r in _placement(d)["rejected"] if r["kind"] == "layer_split"]
+ assert layer and "11931 MiB of denoiser and VAE weights" in layer[0]
+ assert "6963 MiB of activations" in layer[0] and "short by about" in layer[0]
+
+
+def test_zimage_on_two_t4s_layer_split_fits_with_the_measured_activations(monkeypatch):
+ host = Host([Card(0, T4, 300), Card(1, T4, 300)])
+ act = dm.calibrated_image_activation("z-image", max_speed = False)
+ assert act is not None and act.headroom(False) < _ZIMAGE_FLAT
+ d = decide(monkeypatch, host, _sizes(**_ZIMAGE_T4), headroom = _ZIMAGE_FLAT, calibrated = act)
+ assert d.one_card.estimates["calibrated_split_headroom_mib"] == act.headroom(False)
+ assert d.plan.layer_split is not None and d.plan.layer_split.cards == (0, 1)
+ assert _placement(d)["chosen"] == "layer_split"
+ for ordinal, required in d.plan.layer_split.card_required_mib:
+ assert required <= dict(d.plan.layer_split.card_limit_mib)[ordinal]
+
+
+def test_image_activation_estimate_scales_with_resolution():
+ hint = "z-image Tongyi-MAI/Z-Image-Turbo"
+ at_1024 = dm.estimate_image_runtime_mib(width = 1024, height = 1024, family = hint)
+ at_768 = dm.estimate_image_runtime_mib(width = 768, height = 768, family = hint)
+ assert (
+ at_1024
+ == _ZIMAGE_FLAT
+ == dm.estimate_image_runtime_mib(width = None, height = None, family = hint)
+ )
+ assert at_768 == int(8192 * (768 * 768) / (1024 * 1024) * 0.85) < at_1024
+
+
+def test_a_split_priced_with_the_measured_row_is_a_calibrated_placement(monkeypatch):
+ # The generate guard must treat the split as calibrated (it never reserved the flat figure).
+ from core.inference.diffusion import plan_is_calibrated
+
+ host = Host([Card(0, T4, 300), Card(1, T4, 300)])
+ act = dm.calibrated_image_activation("z-image", max_speed = False)
+ split = decide(monkeypatch, host, _sizes(**_ZIMAGE_T4), headroom = _ZIMAGE_FLAT, calibrated = act)
+ assert split.plan.layer_split is not None and plan_is_calibrated(split.plan)
+ # the one-card fallback that carries the key but was decided from the flat estimate stays uncalibrated
+ assert "calibrated_split_headroom_mib" in split.one_card.estimates
+ assert not plan_is_calibrated(split.one_card)
+ flat = decide(monkeypatch, host, _sizes(**_ZIMAGE_T4), headroom = _ZIMAGE_FLAT)
+ assert flat.plan.layer_split is None and not plan_is_calibrated(flat.plan)
diff --git a/studio/backend/tests/test_diffusion_flux3.py b/studio/backend/tests/test_diffusion_flux3.py
index 482875c29f4..9f158923156 100644
--- a/studio/backend/tests/test_diffusion_flux3.py
+++ b/studio/backend/tests/test_diffusion_flux3.py
@@ -490,8 +490,10 @@ def test_measured_memory_rows():
(301, 901, 2_437, 2_437, 3_359),
)
assert mem._MEASURED_DENSE_EAGER_PEAK_MIB["flux.3-klein"] == (2437, 10600)
- # The base runs CFG and is unmeasured: flat estimate.
- assert "flux.3-klein-base" not in mem._MEASURED_IMAGE_ACTIVATION_MIB
+ assert mem._MEASURED_IMAGE_ACTIVATION_MIB["flux.3-klein-base"] == (
+ (301, 901, 2_512, 2_512, 3_359),
+ (301, 901, 2_512, 2_512, 3_359),
+ )
def test_variant_mismatch_and_bfl_quant_packages_are_refused():
@@ -2091,8 +2093,10 @@ def test_flux3_reference_edits_use_the_measured_activations(monkeypatch):
assert distilled.reference and not tuple(getattr(distilled, "reference_resolutions", ()) or ())
act = d._calibrated_activation(distilled, nvidia)
assert act is not None and act == d.calibrated_image_activation("flux.3-klein", max_speed = True)
- # the base runs CFG (two denoiser batches) and has no measured row: it keeps the flat estimate
- assert d._calibrated_activation(_family("flux.3-klein-base"), nvidia) is None
+ base = d._calibrated_activation(_family("flux.3-klein-base"), nvidia)
+ assert base is not None and base == d.calibrated_image_activation(
+ "flux.3-klein-base", max_speed = True
+ )
@pytest.mark.parametrize("with_upsampler", [False, True])