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.

fix(studio): distinguish media RAM offloading from insufficient memory (#15341)

Daniel Hane48962cb37b8
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/media-picker-fit.ts b/studio/frontend/src/features/model-picker/components/model-selector/media-picker-fit.ts
new file mode 100644
index 00000000000..f019ac47d48
--- /dev/null
+++ b/studio/frontend/src/features/model-picker/components/model-selector/media-picker-fit.ts
@@ -0,0 +1,56 @@
+// 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 type { GgufFitClass } from "../../../../lib/gguf-fit.ts";
+import type { VramFitStatus } from "../../../../lib/vram.ts";
+import {
+ artifactForRepoId,
+ curatedArtifactFit,
+ type CatalogGroup,
+ type DeviceBudget,
+} from "./model-catalog.ts";
+
+export type PickerFitStatus = GgufFitClass | VramFitStatus | "offload";
+
+/** Presentation and filters may offer offloadable media without changing Auto's preferred
+ * resident artifact. A host pool is already GPU-addressable RAM, never a second allowance. */
+export function curatedPickerFit(
+ repoId: string,
+ catalog: CatalogGroup[],
+ budget: DeviceBudget & { hostPooledMemory?: boolean },
+) {
+ const fit = curatedArtifactFit(repoId, catalog, budget);
+ if (!fit) return undefined;
+ const hit = artifactForRepoId(repoId, catalog);
+ const group = hit?.group;
+ const media = group?.scope === "image" || group?.scope === "video";
+ // Measured tiers carry a minimum resident GPU footprint that host RAM cannot replace.
+ const tiered = Boolean(hit?.artifact.offloadFitTiers?.length);
+ // No GPU: the load runs from RAM, there is nothing to offload from.
+ if (!media || fit.sizeGb == null || budget.gpuGb <= 0) {
+ return { ...fit, status: fit.fits ? null : ("exceeds" as const) };
+ }
+ const ramGb = budget.hostPooledMemory ? 0 : Math.max(0, budget.systemRamGb);
+ const deviceGb = Math.max(0, budget.gpuGb) + ramGb;
+ // Reserve working memory using the catalog's existing 70% allowance.
+ const allowanceGb = deviceGb * 0.7;
+ const withinPool = fit.sizeGb <= allowanceGb;
+ const fits = tiered
+ ? fit.fits && (!budget.hostPooledMemory || withinPool)
+ : (!budget.hostPooledMemory && fit.fits) || withinPool;
+ const offloads = fits && ramGb > 0 && fit.sizeGb > budget.gpuGb * 0.7;
+ const status = !fits ? ("exceeds" as const) : offloads ? ("offload" as const) : null;
+ if (tiered) return { ...fit, fits, status };
+ return {
+ ...fit,
+ fits,
+ allowanceGb,
+ deviceGb,
+ device: ramGb > 0 ? ("GPU + RAM" as const) : ("GPU" as const),
+ status,
+ };
+}
+
+export function mediaGgufPickerStatus(fit: GgufFitClass): PickerFitStatus {
+ return fit === "partial" ? "offload" : fit === "oom" ? "exceeds" : fit;
+}
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx b/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx
index 2a5cfb2d521..fb7d7a8a060 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx
+++ b/studio/frontend/src/features/model-picker/components/model-selector/pickers.tsx
@@ -211,7 +211,6 @@ import {
artifactForRepoId,
classifyGgufFit,
classifyMediaGgufFit,
- curatedArtifactFit,
curatedCapabilitiesFor,
curatedRowLabelFor,
curatedSizeBytesFor,
@@ -219,6 +218,11 @@ import {
groupForRepoId,
recommendedQuantForDevice,
} from "./model-catalog";
+import {
+ curatedPickerFit,
+ mediaGgufPickerStatus,
+ type PickerFitStatus,
+} from "./media-picker-fit";
import { ModelDeleteAction } from "./model-delete-action";
import { ModelLoadSettingsAction } from "./model-load-settings-action";
import { ModelRowMenu } from "./model-row-menu";
@@ -796,13 +800,18 @@ const WONT_FIT: FitVerdict = {
label: "Does not fit",
tone: ORANGE,
// "memory", not "VRAM": this also covers diffusion refusals on a shared pool.
- hint: "Needs more memory than this device has. This model will not load.",
+ hint: "Estimated memory exceeds this device's usable capacity. Try a smaller model or free memory.",
};
/** Fit verdict marks keyed by the Hub's classes; `tight`/`exceeds` come only from torch or
* QLoRA estimates, which never offload. */
-const VRAM_VERDICT: Record<GgufFitClass | VramFitStatus, FitVerdict | null> = {
+const VRAM_VERDICT: Record<PickerFitStatus, FitVerdict | null> = {
fits: null,
+ offload: {
+ label: "RAM offloading",
+ tone: AMBER,
+ hint: "Might be slower with RAM offloading.",
+ },
marginal: MIGHT_FIT,
tight: DEVICE_TIGHT,
partial: OFFLOADS,
@@ -815,23 +824,13 @@ const VRAM_VERDICT: Record<GgufFitClass | VramFitStatus, FitVerdict | null> = {
exceeds: WONT_FIT,
};
-/** On a shared pool a diffusion `oom` is a refusal (MPS high-watermark disabled, OS kills the
- * process). `hostPooled` folds in unified_memory since shared_memory is set only on Windows. */
-function diffusionRefuses(
- fit: GgufFitClass,
- diffusionLoad: boolean,
- hostPooled: boolean,
-): boolean {
- return fit === "oom" && diffusionLoad && hostPooled;
-}
-
/** Zero on a host pool, where offload frees nothing. llama.cpp differs: GGUFs spill to host RAM. */
function mediaRamBudgetGb(systemRamGb: number, hostPooled: boolean): number {
return hostPooled ? 0 : systemRamGb;
}
/** `marginal` is not over budget: it is a full GPU load with little room to spare. */
-function isOverBudget(status?: GgufFitClass | VramFitStatus | null): boolean {
+function isOverBudget(status?: PickerFitStatus | null): boolean {
return (
status === "partial" ||
status === "ram" ||
@@ -859,7 +858,7 @@ function VramBadge({
/** Model rows hold the mark in the layout and paint it on hover; variant rows always show it. */
revealOnHover = false,
}: {
- status?: GgufFitClass | VramFitStatus | null;
+ status?: PickerFitStatus | null;
revealOnHover?: boolean;
}) {
const t = useT();
@@ -1023,8 +1022,10 @@ function artifactBudget(gpu: {
denseQuantSchemes?: readonly string[];
quantisedStreaming?: boolean;
extraOffloadFitTiers?: DeviceBudget["extraOffloadFitTiers"];
-}): DeviceBudget {
+ loadDeviceSharesHostMemory?: boolean;
+}): DeviceBudget & { hostPooledMemory?: boolean } {
return {
+ hostPooledMemory: gpu.loadDeviceSharesHostMemory,
gpuGb: gpu.memoryTotalGb,
systemRamGb: gpu.systemRamAvailableGb,
// Judges a pre-quantised row by that checkpoint's size, not the bf16 shards it replaces.
@@ -1187,7 +1188,7 @@ function ModelRow({
/** Override badge state when authoritative runtime state is available. */
loaded?: boolean;
onClick: () => void;
- vramStatus?: GgufFitClass | VramFitStatus | null;
+ vramStatus?: PickerFitStatus | null;
vramEst?: number;
vramBudget?: CuratedBudget;
gpuGb?: number;
@@ -1228,9 +1229,11 @@ function ModelRow({
? vramBudget
? curatedBudgetText(vramEst, gpuGb, vramBudget)
: `Needs ~${formatGiB(vramEst)} memory (GPU: ${formatGiB(gpuGb)})`
- : vramStatus === "tight" || vramStatus === "marginal"
- ? `~${formatGiB(vramEst)} VRAM (tight fit on ${formatGiB(gpuGb)})`
- : `~${formatGiB(vramEst)} VRAM`
+ : vramStatus === "offload"
+ ? `~${formatGiB(vramEst)} memory. Might be slower with RAM offloading.`
+ : vramStatus === "tight" || vramStatus === "marginal"
+ ? `~${formatGiB(vramEst)} VRAM (tight fit on ${formatGiB(gpuGb)})`
+ : `~${formatGiB(vramEst)} VRAM`
: null;
const { owner, name } = splitRepoLabel(label);
@@ -2414,9 +2417,7 @@ function GgufVariantExpander({
<span className="flex items-center gap-1.5 shrink-0">
<VramBadge
status={
- diffusionRefuses(fit, diffusionLoad, hostPooledMemory)
- ? "exceeds"
- : fit
+ diffusionLoad ? mediaGgufPickerStatus(fit) : fit
}
/>
<span className="font-mono text-ui-10 text-muted-foreground tabular-nums">
@@ -3826,8 +3827,8 @@ export function HubModelPicker({
/** Every list judging a row against the device goes through this, so badges and filters agree. */
const catalogFit = useCallback(
- (id: string, budget: DeviceBudget) =>
- catalog ? curatedArtifactFit(id, catalog, budget) : undefined,
+ (id: string, budget: DeviceBudget & { hostPooledMemory?: boolean }) =>
+ catalog ? curatedPickerFit(id, catalog, budget) : undefined,
[catalog],
);
@@ -4022,7 +4023,7 @@ export function HubModelPicker({
string,
{
meta: string | null;
- status: GgufFitClass | VramFitStatus | null;
+ status: PickerFitStatus | null;
est: number;
budget?: CuratedBudget;
}
@@ -4032,7 +4033,7 @@ export function HubModelPicker({
sizeBytes: number | undefined,
budget: typeof inferenceGpu,
repoId: string,
- ): GgufFitClass | VramFitStatus | null => {
+ ): PickerFitStatus | null => {
const anyBudget =
budget.memoryTotalGb > 0 || budget.systemRamAvailableGb > 0;
if (!budget.budgetKnown && !anyBudget) return null;
@@ -4061,11 +4062,9 @@ export function HubModelPicker({
: budget.unifiedLoadBudgetGb,
});
if (fit === "fits") return null;
- return diffusionRefuses(fit, diffusionLoad, gpu.loadDeviceSharesHostMemory)
- ? "exceeds"
- : fit;
+ return diffusionLoad ? mediaGgufPickerStatus(fit) : fit;
};
- // A task load puts the whole pipeline on one device; inferenceGpu is the GGUF backend's inventory.
+ // A curated pipeline uses one GPU, offloading to host RAM when needed; inferenceGpu is the GGUF backend's inventory.
const rowGpu = loadScopedGpu(gpu, Boolean(task));
const pipelineBudget = artifactBudget(rowGpu);
// Use the inventory of the runtime that places the row: Vulkan may see cards torch cannot.
@@ -4128,7 +4127,7 @@ export function HubModelPicker({
if (curatedFit !== undefined) {
map.set(r.id, {
meta,
- status: curatedFit.fits ? null : "exceeds",
+ status: curatedFit.status,
est: curatedFit.sizeGb ? Math.round(curatedFit.sizeGb) : 0,
budget: curatedBudget(curatedFit),
});
@@ -5697,7 +5696,7 @@ export function HubModelPicker({
string,
{
est: number;
- status: VramFitStatus | null;
+ status: PickerFitStatus | null;
detail: string | null;
budget?: CuratedBudget;
}
@@ -5712,7 +5711,7 @@ export function HubModelPicker({
const params = totalParams ?? curatedTotalParamsFor(id, catalog);
map.set(id, {
est: curatedFit.sizeGb ? Math.round(curatedFit.sizeGb) : 0,
- status: curatedFit.fits ? null : "exceeds",
+ status: curatedFit.status,
detail: params ? formatCompact(params) : null,
budget: curatedBudget(curatedFit),
});
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/recommended-fit.ts b/studio/frontend/src/features/model-picker/components/model-selector/recommended-fit.ts
index 8a999387413..71ea89abe90 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/recommended-fit.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/recommended-fit.ts
@@ -508,12 +508,12 @@ export function orderRecommendedRows<
export type CuratedBudget = {
allowanceGb: number;
deviceGb: number;
- device: "GPU" | "RAM";
+ device: "GPU" | "RAM" | "GPU + RAM";
sizeGb: number;
};
export function curatedBudget(
- fit: NonNullable<ReturnType<typeof curatedArtifactFit>>,
+ fit: Omit<NonNullable<ReturnType<typeof curatedArtifactFit>>, "device"> & { device?: CuratedBudget["device"] },
): CuratedBudget | undefined {
const { allowanceGb, deviceGb, device, sizeGb } = fit;
return allowanceGb != null && deviceGb != null && device && sizeGb != null
@@ -538,7 +538,9 @@ export function curatedBudgetText(
? shownBudget.toFixed(1)
: (Math.floor(budget.allowanceGb * 10 + 1e-9) / 10).toFixed(1);
const of =
- budget.device === "RAM"
+ budget.device === "GPU + RAM"
+ ? `${Number(budget.deviceGb.toFixed(2))}GB combined GPU and available RAM`
+ : budget.device === "RAM"
? `${Number(budget.deviceGb.toFixed(2))}GB available RAM`
: `a ${gpuGb}GB GPU`;
return `Needs ~${needGb}GB for weights (budget: ~${budgetGb}GB, 70% of ${of})`;
diff --git a/studio/frontend/tests/media-picker-fit.test.ts b/studio/frontend/tests/media-picker-fit.test.ts
new file mode 100644
index 00000000000..e0a1eda03b0
--- /dev/null
+++ b/studio/frontend/tests/media-picker-fit.test.ts
@@ -0,0 +1,79 @@
+// 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 { curatedPickerFit, mediaGgufPickerStatus } from "../src/features/model-picker/components/model-selector/media-picker-fit.ts";
+import { IMAGE_CATALOG, VIDEO_CATALOG, AUDIO_CATALOG, pickDefaultArtifact, groupForRepoId } from "../src/features/model-picker/components/model-selector/model-catalog.ts";
+import { curatedBudget, curatedBudgetText } from "../src/features/model-picker/components/model-selector/recommended-fit.ts";
+
+const id = "unsloth/Z-Image-Turbo";
+
+test("discrete GPU media can fit combined memory and warn about offloading", () => {
+ const fit = curatedPickerFit(id, IMAGE_CATALOG, { gpuGb: 12, systemRamGb: 32 });
+ assert.equal(fit?.fits, true);
+ assert.equal(fit?.status, "offload");
+ assert.equal(fit?.device, "GPU + RAM");
+ assert.equal(fit?.deviceGb, 44);
+});
+
+test("only insufficient combined capacity gets an exceeds verdict", () => {
+ const fit = curatedPickerFit(id, IMAGE_CATALOG, { gpuGb: 12, systemRamGb: 8 });
+ assert.equal(fit?.fits, false);
+ assert.equal(fit?.status, "exceeds");
+ const budget = fit && curatedBudget(fit);
+ assert.ok(budget);
+ assert.match(curatedBudgetText(19, 12, budget), /20GB combined GPU and available RAM/);
+});
+
+test("Spark and other shared pools do not count RAM twice", () => {
+ const fit = curatedPickerFit(id, IMAGE_CATALOG, { gpuGb: 16, systemRamGb: 32, hostPooledMemory: true });
+ assert.equal(fit?.fits, false);
+ assert.equal(fit?.deviceGb, 16);
+ assert.equal(fit?.status, "exceeds");
+});
+
+test("resident models need no offload warning", () => {
+ assert.equal(curatedPickerFit(id, IMAGE_CATALOG, { gpuGb: 48, systemRamGb: 32 })?.status, null);
+});
+
+test("a host with no GPU keeps the RAM verdict, not an offload warning", () => {
+ const fit = curatedPickerFit(id, IMAGE_CATALOG, { gpuGb: 0, systemRamGb: 64 });
+ assert.equal(fit?.fits, true);
+ assert.equal(fit?.status, null);
+ assert.equal(fit?.device, "RAM");
+ assert.equal(curatedPickerFit(id, IMAGE_CATALOG, { gpuGb: 0, systemRamGb: 16 })?.status, "exceeds");
+});
+
+test("video uses the same combined-memory rule", () => {
+ assert.equal(curatedPickerFit("Wan-AI/Wan2.1-T2V-14B-Diffusers", VIDEO_CATALOG, { gpuGb: 24, systemRamGb: 64 })?.status, "offload");
+});
+
+test("media GGUF offload and combined shortage have distinct display states", () => {
+ assert.equal(mediaGgufPickerStatus("partial"), "offload");
+ assert.equal(mediaGgufPickerStatus("oom"), "exceeds");
+ assert.equal(mediaGgufPickerStatus("fits"), "fits");
+});
+
+test("audio and Auto artifact routing retain their existing fit policies", () => {
+ assert.equal(curatedPickerFit("unsloth/whisper-large-v3", AUDIO_CATALOG, { gpuGb: 1, systemRamGb: 5 })?.fits, false);
+ const group = groupForRepoId(id, IMAGE_CATALOG);
+ assert.ok(group);
+ assert.equal(pickDefaultArtifact(group, { gpuGb: 8, systemRamGb: 32, isDownloaded: () => false }).format, "gguf");
+});
+
+test("host RAM cannot stand in for a measured tier's GPU floor", () => {
+ const H3 = "MiniMaxAI/MiniMax-H3";
+ for (const gpuGb of [4, 24]) {
+ const fit = curatedPickerFit(H3, VIDEO_CATALOG, { gpuGb, systemRamGb: 256 });
+ assert.equal(fit?.fits, false, `${gpuGb} GB GPU`);
+ assert.equal(fit?.status, "exceeds", `${gpuGb} GB GPU`);
+ }
+ assert.equal(curatedPickerFit(H3, VIDEO_CATALOG, { gpuGb: 80, systemRamGb: 256 })?.status, "offload");
+});
+
+test("measured discrete offload tiers cannot invent a second pool on shared hosts", () => {
+ const fit = curatedPickerFit("MiniMaxAI/MiniMax-H3", VIDEO_CATALOG, { gpuGb: 4, systemRamGb: 64, hostPooledMemory: true });
+ assert.equal(fit?.fits, false);
+ assert.equal(fit?.status, "exceeds");
+});
diff --git a/studio/frontend/tests/on-device-dot-and-header-alignment.test.ts b/studio/frontend/tests/on-device-dot-and-header-alignment.test.ts
index e04d25479c3..6ecb77dc510 100644
--- a/studio/frontend/tests/on-device-dot-and-header-alignment.test.ts
+++ b/studio/frontend/tests/on-device-dot-and-header-alignment.test.ts
@@ -183,7 +183,7 @@ test("one fit badge, so a colour or reveal change cannot miss a list", () => {
assert.ok(!PICKERS.includes(">\n OOM\n"), "no OOM text pill left");
assert.match(
PICKERS,
- /<VramBadge\n\s*status=\{\n\s*diffusionRefuses\(fit, diffusionLoad, hostPooledMemory\)/,
+ /<VramBadge\n\s*status=\{\n\s*diffusionLoad \? mediaGgufPickerStatus\(fit\)/,
);
assert.equal(
PICKERS.split("<VramBadge status={vramStatus} revealOnHover={!selected} />")
@@ -347,7 +347,7 @@ test("each fit verdict is an info mark that explains itself", () => {
assert.ok(PICKERS.includes("exceeds: WONT_FIT"));
assert.ok(
PICKERS.includes(
- 'hint: "Needs more memory than this device has. This model will not load."',
+ "hint: \"Estimated memory exceeds this device's usable capacity. Try a smaller model or free memory.\"",
),
);
assert.ok(!PICKERS.includes("Larger than your VRAM and system RAM together"));
@@ -396,7 +396,7 @@ test("each fit verdict is an info mark that explains itself", () => {
// Torch inference raises on any CPU/disk offload (raise_if_offloaded), so exceeds won't load.
assert.ok(
PICKERS.includes(
- 'hint: "Needs more memory than this device has. This model will not load."',
+ "hint: \"Estimated memory exceeds this device's usable capacity. Try a smaller model or free memory.\"",
),
);
assert.ok(PICKERS.includes("aria-label={verdict.label}"));
@@ -425,47 +425,18 @@ test("a GGUF row takes the GGUF verdict, not the torch refusal", () => {
assert.ok(!PICKERS.includes("exceedsSize"));
assert.match(
PICKERS,
- /const ggufRowFit = \([\s\S]{0,220}\): GgufFitClass \| VramFitStatus \| null =>/,
+ /const ggufRowFit = \([\s\S]{0,220}\): PickerFitStatus \| null =>/,
);
- // Every surviving producer of "exceeds" is a curated torch pipeline, which has no --fit.
- const producers = PICKERS.split("\n").filter(
- (line) => line.includes('"exceeds"') && line.includes("status:"),
- );
- assert.equal(producers.length, 2, "curated rows only");
- for (const line of producers) {
- assert.match(line, /curatedFit\.fits \? null : "exceeds"/);
- }
+ assert.equal(PICKERS.split("status: curatedFit.status,").length - 1, 2);
});
-test("a diffusion model too big for a shared pool is refused, not offloaded", () => {
- // diffusion_memory.py refuses on unified memory, where offload frees nothing.
- assert.ok(PICKERS.includes("function diffusionRefuses("));
- assert.ok(
- PICKERS.includes('return fit === "oom" && diffusionLoad && hostPooled;'),
- );
- // hardware.py sets shared_memory only on Windows, so fold in unified_memory per device.
+test("a diffusion model uses its load device's shared-pool verdict", () => {
assert.ok(!PICKERS.includes("gpu.sharedMemory"), "not the aggregate flag");
- assert.ok(
- GPU_INFO.includes("loadDeviceSharesHostMemory: sharesHostMemory({"),
- "the flag is the load device's, folded",
- );
- assert.match(
- PICKERS,
- /diffusionRefuses\(fit, diffusionLoad, hostPooledMemory\)\n\s*\? "exceeds"/,
- );
- assert.ok(
- PICKERS.includes(
- "diffusionRefuses(fit, diffusionLoad, gpu.loadDeviceSharesHostMemory)",
- ),
- );
- assert.ok(
- PICKERS.includes(
- 'hint: "Needs more memory than this device has. This model will not load."',
- ),
- );
+ assert.ok(GPU_INFO.includes("loadDeviceSharesHostMemory: sharesHostMemory({"));
+ assert.ok(PICKERS.includes("hostPooledMemory: gpu.loadDeviceSharesHostMemory,"));
+ assert.ok(PICKERS.includes("diffusionLoad ? mediaGgufPickerStatus(fit) : fit"));
assert.equal(
- PICKERS.split("hostPooledMemory={gpu.loadDeviceSharesHostMemory}").length -
- 1,
+ PICKERS.split("hostPooledMemory={gpu.loadDeviceSharesHostMemory}").length - 1,
8,
"every task-scoped expander learns the pool kind",
);
diff --git a/studio/frontend/tests/recommended-curated-row-metadata.test.ts b/studio/frontend/tests/recommended-curated-row-metadata.test.ts
index 7ebbd288550..be792dadbfe 100644
--- a/studio/frontend/tests/recommended-curated-row-metadata.test.ts
+++ b/studio/frontend/tests/recommended-curated-row-metadata.test.ts
@@ -293,7 +293,7 @@ test("every list that judges a row against the device asks the same helper", ()
// One verdict for all readers, or a filter calls a row a fit while the badge says OOM.
assert.match(
declarationText("catalogFit"),
- /curatedArtifactFit\(id, catalog, budget\)/,
+ /curatedPickerFit\(id, catalog, budget\)/,
);
for (const declaration of ["recommendedRows", "searchRowFits"]) {
assert.match(