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
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.tsnew file mode 100644index 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.tsxindex 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"><VramBadgestatus={- 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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(