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.

Unsloth Studio: give the memory planner the companion split on a pipeline image load (#11548)

Leo Borcherdingf2e6a44e60a4
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 0fe7b08e94d..caeda3ee7d0 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -5714,13 +5714,16 @@ class DiffusionBackend:
clear_gpu_cache()
logger.info(
- "diffusion.loaded: repo=%s base=%s device=%s offload=%s tiling=%s reasons=%s",
+ # The estimates too: the verdict alone cannot be checked from a user's log, and a None among these terms
+ # is itself the explanation for a tier the planner skipped.
+ "diffusion.loaded: repo=%s base=%s device=%s offload=%s tiling=%s reasons=%s estimates=%s",
repo_id,
base,
device,
effective_policy,
effective_tiling,
"; ".join(plan.reasons),
+ plan.estimates,
)
return self.status()
@@ -6277,6 +6280,7 @@ class DiffusionBackend:
# A local fp8 mirror never string-matches base_repo, so detect fp8 from the shard headers (a local nf4
# mirror stays compressed).
is_narrow_base = ideogram4_repo_is_fp8(repo_id)
+ table = None
if is_narrow_base:
table = family_bf16_components_gb(fam, fam.base_repo)
if table is not None:
@@ -6286,10 +6290,24 @@ class DiffusionBackend:
model_dense_mib = (
table_mib if model_dense_mib is None else max(model_dense_mib, table_mib)
)
- companion_mib = None
- # No companion total on this branch (the whole repo IS the model), so there is no split to hand the
- # planner either. None, not a guess: it reproduces the old decision.
- text_encoder_mib = None
+ # The whole repo is the model, but its companions still sit in their own subfolders, so the same walk the
+ # GGUF/single-file branch uses splits them out here too. Without the split both group tiers fail on None
+ # and a pipeline that does not fit resident can only ever reach whole-module offload.
+ companion = self._companion_cache_bytes(fetch_base or base, base_local_dir)
+ companion_mib = int(companion // (1024 * 1024)) if companion else None
+ text_encoder = self._text_encoder_cache_bytes(fetch_base or base, base_local_dir)
+ text_encoder_mib = int(text_encoder // (1024 * 1024)) if text_encoder else None
+ if is_narrow_base and table is not None:
+ # model_dense_mib was raised to the bf16 table above; the companions upcast with it, so take their
+ # share from the same table rather than leaving a narrow on-disk figure beside a bf16 total.
+ companion_mib = int(sum(table[1:]) * (1000.0**3) / (1024.0 * 1024.0))
+ text_encoder_mib = int(table[1] * (1000.0**3) / (1024.0 * 1024.0))
+ if companion_mib is not None and model_dense_mib is not None:
+ # The two terms come from different merges over the cache roots, so a repo only one of them can see
+ # must not report companions larger than the model.
+ companion_mib = min(companion_mib, model_dense_mib)
+ if text_encoder_mib is not None:
+ text_encoder_mib = min(text_encoder_mib, companion_mib)
else:
if transformer_resident_override_mib is not None:
# Planning the dense-quant candidate: the auto-policy estimate replaces the file-size derivation.
diff --git a/studio/backend/core/inference/diffusion_memory.py b/studio/backend/core/inference/diffusion_memory.py
index 2d28306f111..516966bde69 100644
--- a/studio/backend/core/inference/diffusion_memory.py
+++ b/studio/backend/core/inference/diffusion_memory.py
@@ -857,7 +857,15 @@ def plan_diffusion_memory(
reasons.append(_STREAMED_TE_REASON)
else:
policy = OFFLOAD_MODEL
- reasons.append("companions exceed budget; whole-module offload of every component")
+ # Both group tiers also fail when the companion split is simply UNKNOWN, and reporting that as "exceeds
+ # budget" sends anyone reading the log looking for a card that is too small.
+ if group_floor is None:
+ reasons.append(
+ "companion size unknown, so no streamed tier can be sized; "
+ "whole-module offload of every component"
+ )
+ else:
+ reasons.append("companions exceed budget; whole-module offload of every component")
# The legacy cpu_offload flag applies only when no memory_mode was supplied, so an explicit `fast` stays resident.
if (
diff --git a/studio/backend/tests/test_diffusion_backend.py b/studio/backend/tests/test_diffusion_backend.py
index 88ba298cb4f..6bcbae45894 100644
--- a/studio/backend/tests/test_diffusion_backend.py
+++ b/studio/backend/tests/test_diffusion_backend.py
@@ -6660,7 +6660,7 @@ def test_plan_memory_sizes_a_pipeline_load_from_the_other_root_snapshot(monkeypa
# Same hole on the full-pipeline branch, where the whole repo IS the base: _cache_bytes walks
# the live root's blobs, so a repo served from the other root sizes as unknown and a 4 GiB
# pipeline that does not fit stays resident.
- from core.inference.diffusion_memory import OFFLOAD_MODEL, OFFLOAD_NONE
+ from core.inference.diffusion_memory import OFFLOAD_GROUP, OFFLOAD_NONE
snapshot = _other_root_base_snapshot(tmp_path, monkeypatch)
target = _small_card(monkeypatch)
@@ -6680,7 +6680,12 @@ def test_plan_memory_sizes_a_pipeline_load_from_the_other_root_snapshot(monkeypa
plan = _plan(base_local_dir = str(snapshot))
# A pipeline load keeps transformer/: 4096 + 150 + 50 = 4296 MiB, well past the 2509 MiB margin.
assert plan.estimates["model_dense_mib"] == 4296
- assert plan.offload_policy == OFFLOAD_MODEL
+ # Group, not whole-module: this branch now hands the planner the companion split too, so the
+ # 2348 MiB group floor (200 companions + 100 headroom + 2048 overhead) is sized and fits. The
+ # assertion read OFFLOAD_MODEL while that split was None, which made every group tier fail the
+ # `is not None` check rather than lose on its arithmetic.
+ assert plan.estimates["companion_dense_mib"] == 200
+ assert plan.offload_policy == OFFLOAD_GROUP
def test_plan_memory_keeps_companions_a_partial_staged_snapshot_omits(monkeypatch, tmp_path):
diff --git a/studio/backend/tests/test_diffusion_memory.py b/studio/backend/tests/test_diffusion_memory.py
index 3fca544b59a..ac839114571 100644
--- a/studio/backend/tests/test_diffusion_memory.py
+++ b/studio/backend/tests/test_diffusion_memory.py
@@ -2050,3 +2050,50 @@ def test_an_automatic_load_still_hands_over_a_bare_device():
assert expected[0] in pipe.calls
if policy is OFFLOAD_MODEL:
assert pipe.offload_device == "cuda"
+
+
+def _a100_40gb():
+ """An idle A100-SXM4-40GB, the card the pipeline-load report came from."""
+ return diffusion_memory.DeviceMemory("cuda", "cuda", "discrete_vram", 40200, 40960)
+
+
+def _offloadable():
+ return types.SimpleNamespace(supports_model_cpu_offload = True)
+
+
+def test_a_pipeline_load_without_a_companion_split_says_unknown_not_over_budget():
+ # Both group tiers are `... is not None and ...`, so an unknown split fails them by
+ # construction rather than on arithmetic. Reporting that as "companions exceed budget" sends
+ # someone on a 40 GB card looking for a bigger card.
+ plan = diffusion_memory.plan_diffusion_memory(
+ target = _offloadable(),
+ device_memory = _a100_40gb(),
+ model_dense_mib = 31566,
+ runtime_headroom_mib = 8192,
+ companion_dense_mib = None,
+ text_encoder_dense_mib = None,
+ )
+ assert plan.offload_policy == OFFLOAD_MODEL
+ reason = "; ".join(plan.reasons)
+ assert "companion size unknown" in reason
+ assert "exceed budget" not in reason
+
+
+def test_the_same_load_reaches_group_offload_once_the_split_is_known():
+ # The CONTROL for the case above, and it passes before the fix too: the planner could always
+ # reach this tier, the pipeline branch just never handed it a split to reach it with. Pinned so
+ # the two halves of the decision stay visible side by side.
+ #
+ # Qwen-Image-2.1 on a 40 GB card: 31,566 MiB of weights do not fit resident, but the 28,264 MiB
+ # group floor does. Whole-module offload pages every component per step and drags VAE tiling on
+ # with it, so losing this tier costs speed and decode quality at once.
+ plan = diffusion_memory.plan_diffusion_memory(
+ target = _offloadable(),
+ device_memory = _a100_40gb(),
+ model_dense_mib = 31566,
+ runtime_headroom_mib = 8192,
+ companion_dense_mib = 18024,
+ text_encoder_dense_mib = 16689,
+ )
+ assert plan.offload_policy == OFFLOAD_GROUP
+ assert plan.vae_tiling is False
diff --git a/studio/frontend/src/features/images/image-generation-defaults.ts b/studio/frontend/src/features/images/image-generation-defaults.ts
index 24ec13382a7..55ebc49ff43 100644
--- a/studio/frontend/src/features/images/image-generation-defaults.ts
+++ b/studio/frontend/src/features/images/image-generation-defaults.ts
@@ -45,3 +45,56 @@ export function defaultsFor(repoId: string): {
? { steps: matched.steps, guidance: matched.guidance }
: DEFAULT_GEN;
}
+
+// The canvas every family is tuned for, and what an unrecognised model gets.
+export const DEFAULT_RESOLUTION = { width: 1024, height: 1024 } as const;
+
+// Families whose QUANTISED pipeline build defaults to a smaller canvas, with the schemes that
+// trigger it.
+//
+// Quantising the denoiser shrinks the weights and leaves the activations alone, so on a family
+// whose activations dominate, the canvas is what decides whether the load fits. Qwen-Image-2.1 at
+// 1024 measures about 26 GB against about 19 GB at 512, which is the difference between running
+// and not on a 24 GB card, and someone who picked a quantised build is telling us the card is the
+// constraint. Dense bf16 keeps 1024: it was never going to fit a small card either way, so
+// shrinking its canvas would cost quality and buy nothing.
+//
+// The GGUF route is deliberately absent. It streams the denoiser off disk, so its footprint does
+// not turn on this, and it keeps 1024.
+const QUANTISED_CANVAS: Array<{
+ match: string;
+ schemes: readonly string[];
+ width: number;
+ height: number;
+}> = [
+ {
+ match: "qwen-image-2.1",
+ schemes: ["fp8", "fp8_dynamic", "int8", "nvfp4"],
+ width: 512,
+ height: 512,
+ },
+];
+
+export function resolutionFor(
+ repoId: string,
+ build: { modelKind?: string | null; transformerQuant?: string | null },
+): { width: number; height: number } {
+ // A GGUF resident reports no family substring in repo_id, so callers pass base_repo; the kind is
+ // what actually excludes that route, not the id.
+ if ((build.modelKind ?? "").toLowerCase() === "gguf") {
+ return DEFAULT_RESOLUTION;
+ }
+ const scheme = (build.transformerQuant ?? "")
+ .toLowerCase()
+ .replace(/-/g, "_");
+ if (!scheme) {
+ return DEFAULT_RESOLUTION;
+ }
+ const id = repoId.toLowerCase();
+ const matched = QUANTISED_CANVAS.find(
+ (entry) => id.includes(entry.match) && entry.schemes.includes(scheme),
+ );
+ return matched
+ ? { width: matched.width, height: matched.height }
+ : DEFAULT_RESOLUTION;
+}
diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsx
index 4c69fca0464..eee9ac49c87 100644
--- a/studio/frontend/src/features/images/images-page.tsx
+++ b/studio/frontend/src/features/images/images-page.tsx
@@ -138,7 +138,7 @@ import {
} from "@/lib/diffusion-route-search";
import { toast } from "@/lib/toast";
import { subscribeModelEjected } from "@/lib/model-lifecycle-events";
-import { DEFAULT_GEN, defaultsFor } from "./image-generation-defaults";
+import { DEFAULT_GEN, defaultsFor, resolutionFor } from "./image-generation-defaults";
import { MAX_DIM, MIN_DIM, restorableSize, snapDim } from "./image-size";
import {
@@ -1413,16 +1413,28 @@ export function ImagesPage({
const recommended =
pendingModelDefaults ??
defaultsFor(status?.base_repo ?? status?.repo_id ?? "");
+ // Reset restores the resident build's canvas, the same one the seed above applied. A constant
+ // here would quietly undo it and put a 24 GB card back over its budget.
+ const size = resolutionFor(status?.base_repo ?? status?.repo_id ?? "", {
+ modelKind: status?.model_kind,
+ transformerQuant: status?.transformer_quant,
+ });
return {
negativePrompt: "",
- width: 1024,
- height: 1024,
+ width: size.width,
+ height: size.height,
steps: recommended.steps,
guidance: recommended.guidance,
batchSize: 1,
runs: 1,
};
- }, [pendingModelDefaults, status?.base_repo, status?.repo_id]);
+ }, [
+ pendingModelDefaults,
+ status?.base_repo,
+ status?.repo_id,
+ status?.model_kind,
+ status?.transformer_quant,
+ ]);
const applyImagePresetParams = useCallback((params: ImageGenerationPresetParams) => {
setNegativePrompt(params.negativePrompt);
// Same rule restoreSettings follows: a negative prompt in effect has to be visible, or the
@@ -2357,7 +2369,26 @@ export function ImagesPage({
setPendingModelDefaults(null);
setSteps(d.steps);
setGuidance(d.guidance);
- }, [imagePresets.storedRecipe, status?.loaded, status?.repo_id, status?.base_repo, status?.model_kind]);
+ // The canvas is part of the resident model's defaults, not a constant: a quantised build shrinks
+ // the weights and leaves the activations alone, so on Qwen-Image-2.1 the canvas is what decides
+ // whether the load fits. Read from the ENGAGED build, so a declined quant request keeps 1024.
+ const size = resolutionFor(status?.base_repo ?? repoId, {
+ modelKind: status?.model_kind,
+ transformerQuant: status?.transformer_quant,
+ });
+ setWidth(size.width);
+ setHeight(size.height);
+ const matched = matchAspect(size.width, size.height);
+ setAspect(matched.key);
+ setPortrait(matched.portrait);
+ }, [
+ imagePresets.storedRecipe,
+ status?.loaded,
+ status?.repo_id,
+ status?.base_repo,
+ status?.model_kind,
+ status?.transformer_quant,
+ ]);
// Reseed the Advanced selects from the LOADED build, so a declined request snaps to what
// engaged and Precision never advertises a scheme the model is not running. Keyed on the
diff --git a/studio/frontend/tests/image-generation-canvas-defaults.test.ts b/studio/frontend/tests/image-generation-canvas-defaults.test.ts
new file mode 100644
index 00000000000..62fb83ed3c5
--- /dev/null
+++ b/studio/frontend/tests/image-generation-canvas-defaults.test.ts
@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+ DEFAULT_RESOLUTION,
+ resolutionFor,
+} from "../src/features/images/image-generation-defaults.ts";
+
+const QWEN21 = "Qwen/Qwen-Image-2.1";
+
+test("a quantised Qwen-Image-2.1 pipeline defaults to 512", () => {
+ // Measured: about 26 GB at 1024 against about 19 GB at 512. Quantising the denoiser leaves the
+ // activations alone, so on this family the canvas is what decides whether the load fits.
+ for (const scheme of ["fp8", "int8", "fp8_dynamic", "nvfp4"]) {
+ const size = resolutionFor(QWEN21, {
+ modelKind: "pipeline",
+ transformerQuant: scheme,
+ });
+ assert.deepEqual(size, { width: 512, height: 512 }, scheme);
+ }
+});
+
+test("the single-file FP8 route gets it too", () => {
+ // The hosted FP8 checkpoint loads as single_file, not pipeline. Only GGUF is excluded.
+ assert.deepEqual(
+ resolutionFor("unsloth/Qwen-Image-2.1-FP8", {
+ modelKind: "single_file",
+ transformerQuant: "fp8",
+ }),
+ { width: 512, height: 512 },
+ );
+});
+
+test("a Qwen-Image-2.1 GGUF keeps 1024", () => {
+ // The GGUF route streams the denoiser off disk, so its footprint does not turn on the canvas.
+ // base_repo still carries the family substring, so the KIND is what has to exclude it.
+ assert.deepEqual(
+ resolutionFor(QWEN21, { modelKind: "gguf", transformerQuant: "int8" }),
+ DEFAULT_RESOLUTION,
+ );
+});
+
+test("a dense Qwen-Image-2.1 keeps 1024", () => {
+ // Nobody running bf16 is short of VRAM, and shrinking its canvas would cost quality for nothing.
+ // "off" is how the engaged record spells no quant; null is an older backend that never said.
+ for (const scheme of ["off", "none", "", null, undefined]) {
+ assert.deepEqual(
+ resolutionFor(QWEN21, {
+ modelKind: "pipeline",
+ transformerQuant: scheme,
+ }),
+ DEFAULT_RESOLUTION,
+ String(scheme),
+ );
+ }
+});
+
+test("other families keep 1024 even when quantised", () => {
+ // The control. This is a per-family measurement, not a rule about quantisation, so a quantised
+ // FLUX or Qwen-Image (2.0) must be untouched.
+ for (const repo of [
+ "black-forest-labs/FLUX.1-dev",
+ "Qwen/Qwen-Image",
+ "Tongyi-MAI/Z-Image-Turbo",
+ ]) {
+ assert.deepEqual(
+ resolutionFor(repo, { modelKind: "pipeline", transformerQuant: "int8" }),
+ DEFAULT_RESOLUTION,
+ repo,
+ );
+ }
+});
+
+test("an unloaded or unknown model keeps 1024", () => {
+ assert.deepEqual(
+ resolutionFor("", { modelKind: null, transformerQuant: null }),
+ DEFAULT_RESOLUTION,
+ );
+});