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
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.pyindex 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 = Noneif 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.pyindex 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.pyindex 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_NONEsnapshot = _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(monkeypaplan = _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_GROUPdef 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.pyindex 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.callsif 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 Falsediff --git a/studio/frontend/src/features/images/image-generation-defaults.ts b/studio/frontend/src/features/images/image-generation-defaults.tsindex 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.tsxindex 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 thediff --git a/studio/frontend/tests/image-generation-canvas-defaults.test.ts b/studio/frontend/tests/image-generation-canvas-defaults.test.tsnew file mode 100644index 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,+ );+});