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: show the curated model fit estimate in picker warnings (#11583)

oobabooga91b525fcbfa2
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
index 5370eabec4e..16eff92454b 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
@@ -1329,34 +1329,56 @@ export function pickDefaultArtifact(
)[0];
}
-/** Whether ONE curated artifact loads on this device, by the rule `pickDefaultArtifact` routes with,
- * since a row click loads that exact artifact. System RAM is not part of a discrete-GPU budget: a
- * pipeline goes wholly on the card unless the catalog states a measured offload tier or the loader
- * falls back to CPU, which only transcription does. A unified-memory host reports RAM and no GPU,
- * and there the RAM is the card. Undefined where nothing can be judged. */
-export function curatedArtifactFitsDevice(
+/** Fit verdict and badge estimate for one curated artifact; undefined if unknown.
+ * Uses GPU memory, or RAM for unified-memory hosts and transcription fallback.
+ * Measured offload tiers return the catalog size without an allowance. */
+export function curatedArtifactFit(
repoId: string,
catalog: CatalogGroup[],
budget: DeviceBudget,
-): boolean | undefined {
+): {
+ fits: boolean;
+ sizeGb?: number;
+ allowanceGb?: number;
+ /** Memory the allowance is 70% of, and which device it is. */
+ deviceGb?: number;
+ device?: "GPU" | "RAM";
+} | undefined {
const hit = artifactForRepoId(repoId, catalog);
if (!hit || hit.artifact.format === "gguf") return undefined;
const { group, artifact } = hit;
if (budget.gpuGb <= 0 && budget.systemRamGb <= 0) return undefined;
- if (artifact.offloadFitTiers?.length) return fitsArtifactBudget(group, artifact, budget);
+ if (artifact.offloadFitTiers?.length) {
+ return {
+ fits: fitsArtifactBudget(group, artifact, budget),
+ sizeGb: artifact.approxSizeGb,
+ };
+ }
// Transcription retries a failed device load on CPU (stt_sidecar.py), so RAM is a real budget
// there, but the WHOLE model lands on one device: the larger of the two, not their sum. An
// image, video or TTS load rejects CPU offload.
- const deviceGb =
- group.task === "stt"
- ? Math.max(budget.gpuGb, budget.systemRamGb)
- : budget.gpuGb > 0
- ? budget.gpuGb
- : budget.systemRamGb;
+ const onRam =
+ group.task === "stt" ? budget.systemRamGb > budget.gpuGb : budget.gpuGb <= 0;
+ const deviceGb = onRam ? budget.systemRamGb : budget.gpuGb;
const allowanceGb = deviceGb * 0.7;
const sizeGb = residentSizeGb(group, artifact, budget, allowanceGb);
if (sizeGb === undefined) return undefined;
- return sizeGb <= allowanceGb;
+ return {
+ fits: sizeGb <= allowanceGb,
+ sizeGb,
+ allowanceGb,
+ deviceGb,
+ device: onRam ? "RAM" : "GPU",
+ };
+}
+
+/** `curatedArtifactFit`'s verdict alone. */
+export function curatedArtifactFitsDevice(
+ repoId: string,
+ catalog: CatalogGroup[],
+ budget: DeviceBudget,
+): boolean | undefined {
+ return curatedArtifactFit(repoId, catalog, budget)?.fits;
}
/** Whether the "fit on device" toggle keeps a group, including measured offload tiers when an
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 26d53532e1d..5925a441978 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
@@ -166,7 +166,7 @@ import {
artifactForRepoId,
classifyGgufFit,
classifyMediaGgufFit,
- curatedArtifactFitsDevice,
+ curatedArtifactFit,
curatedCapabilitiesFor,
curatedRowLabelFor,
curatedSizeBytesFor,
@@ -204,6 +204,9 @@ import {
paramsFromId,
searchRowFitsDevice,
searchableRecommendedIds,
+ type CuratedBudget,
+ curatedBudget,
+ curatedBudgetText,
} from "./recommended-fit";
import {
ggufVariantsMatchForPicker,
@@ -1047,6 +1050,7 @@ function ModelRow({
onClick,
vramStatus,
vramEst,
+ vramBudget,
gpuGb,
tooltipText,
hubUrl,
@@ -1073,6 +1077,8 @@ function ModelRow({
onClick: () => void;
vramStatus?: GgufFitClass | VramFitStatus | null;
vramEst?: number;
+ /** Memory allowance used to judge this curated row's fit. */
+ vramBudget?: CuratedBudget;
gpuGb?: number;
tooltipText?: ReactNode;
/** Hugging Face address for online/Hub rows, surfaced on hover the way local rows show an
@@ -1116,8 +1122,9 @@ function ModelRow({
? exceeds
// "memory", not "VRAM": a GGUF at `partial` splits across VRAM and RAM and the figure
// is weights plus activations plus KV, so "Needs ~47GB VRAM" contradicted the verdict.
- ?
- `Needs ~${vramEst}GB memory (GPU: ${gpuGb}GB)`
+ ? vramBudget
+ ? curatedBudgetText(vramEst, gpuGb, vramBudget)
+ : `Needs ~${vramEst}GB memory (GPU: ${gpuGb}GB)`
: vramStatus === "tight" || vramStatus === "marginal"
? `~${vramEst}GB VRAM (tight fit on ${gpuGb}GB)`
: `~${vramEst}GB VRAM`
@@ -3454,7 +3461,7 @@ export function HubModelPicker({
* cannot disagree. */
const catalogFit = useCallback(
(id: string, budget: DeviceBudget) =>
- catalog ? curatedArtifactFitsDevice(id, catalog, budget) : undefined,
+ catalog ? curatedArtifactFit(id, catalog, budget) : undefined,
[catalog],
);
@@ -3519,7 +3526,7 @@ export function HubModelPicker({
downloadedSet.has(r.id.toLowerCase()) ||
// The catalog's own verdict where it has one, so this list and the OOM badge cannot disagree:
// hfModelFitsDevice counts RAM toward a load that never leaves the card.
- (catalogFit(r.id, pipelineBudget) ??
+ (catalogFit(r.id, pipelineBudget)?.fits ??
hfModelFitsDevice(r, diffusionLoad || !r.isGguf ? rowGpu : rowInferenceGpu, {
budgetFraction,
// Not `&& r.isGguf`: on a task page a safetensors row is placed by the same backend, and this
@@ -3580,6 +3587,7 @@ export function HubModelPicker({
/** GGUF rows carry the classifier's own verdict; curated torch rows carry "exceeds". */
status: GgufFitClass | VramFitStatus | null;
est: number;
+ budget?: CuratedBudget;
}
>();
/** Size-based verdict for a row whose real footprint we know, against the budget that row
@@ -3682,18 +3690,14 @@ export function HubModelPicker({
});
continue;
}
- // A curated pipeline is judged by the catalog, which knows its resident size; the QLoRA
- // estimator reads a diffusion pipeline as a language model it can 4-bit quantize (Wan 2.2
- // TI2V is 30 GB, where 5B params says 5.9).
- const curatedFits = catalogFit(r.id, pipelineBudget);
- if (curatedFits !== undefined) {
- const curatedBytes = catalog
- ? (r.curatedSizeBytes ?? curatedSizeBytesFor(r.id, catalog))
- : undefined;
+ // Use the catalog's fit estimate for both the verdict and badge, not the LLM estimator.
+ const curatedFit = catalogFit(r.id, pipelineBudget);
+ if (curatedFit !== undefined) {
map.set(r.id, {
meta,
- status: curatedFits ? null : "exceeds",
- est: curatedBytes ? Math.round(curatedBytes / 1024 ** 3) : 0,
+ status: curatedFit.fits ? null : "exceeds",
+ est: curatedFit.sizeGb ? Math.round(curatedFit.sizeGb) : 0,
+ budget: curatedBudget(curatedFit),
});
continue;
}
@@ -4615,7 +4619,7 @@ export function HubModelPicker({
estimatedSizeBytes?: number;
curatedSizeBytes?: number;
}) =>
- catalogFit(row.id, artifactBudget(loadScopedGpu(gpu, Boolean(task)))) ??
+ catalogFit(row.id, artifactBudget(loadScopedGpu(gpu, Boolean(task))))?.fits ??
searchRowFitsDevice(
{
...row,
@@ -5085,7 +5089,12 @@ export function HubModelPicker({
const recommendedVramMap = useMemo(() => {
const map = new Map<
string,
- { est: number; status: VramFitStatus | null; detail: string | null }
+ {
+ est: number;
+ status: VramFitStatus | null;
+ detail: string | null;
+ budget?: CuratedBudget;
+ }
>();
const pipelineBudget = artifactBudget(loadScopedGpu(gpu, Boolean(task)));
for (const id of filteredRecommendedIds) {
@@ -5094,16 +5103,16 @@ export function HubModelPicker({
const totalParams = recommendedParamCountById.get(id) ?? paramsFromId(id);
// Same verdict the unfiltered list gives this row: searching for a model must not change what
// it says about the device.
- const curatedFits = catalogFit(id, pipelineBudget);
- if (catalog && curatedFits !== undefined) {
- const curatedBytes = curatedSizeBytesFor(id, catalog);
+ const curatedFit = catalogFit(id, pipelineBudget);
+ if (catalog && curatedFit !== undefined) {
// The catalog is the only source of a count for a curated repo the listing never returns and
// whose id spells no "<n>B".
const params = totalParams ?? curatedTotalParamsFor(id, catalog);
map.set(id, {
- est: curatedBytes ? Math.round(curatedBytes / 1024 ** 3) : 0,
- status: curatedFits ? null : "exceeds",
+ est: curatedFit.sizeGb ? Math.round(curatedFit.sizeGb) : 0,
+ status: curatedFit.fits ? null : "exceeds",
detail: params ? formatCompact(params) : null,
+ budget: curatedBudget(curatedFit),
});
continue;
}
@@ -7196,6 +7205,7 @@ export function HubModelPicker({
}}
vramStatus={info?.status ?? null}
vramEst={info?.est}
+ vramBudget={info?.budget}
gpuGb={isG ? expanderGpuGb : expanderSystemGpuGb}
onArrowDownIntoChildren={
expandedGguf === id
@@ -7314,6 +7324,9 @@ export function HubModelPicker({
vramEst={
isKnownGgufRepo(id) ? undefined : vram?.est
}
+ vramBudget={
+ isKnownGgufRepo(id) ? undefined : vram?.budget
+ }
gpuGb={
isKnownGgufRepo(id)
? expanderGpuGb
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 384102905c5..e7440175419 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
@@ -5,7 +5,7 @@
// the device. No React/DOM deps so they are easy to test.
import { classifyGgufFit } from "../../../../lib/gguf-fit.ts";
-import { classifyMediaGgufFit } from "./model-catalog.ts";
+import { classifyMediaGgufFit, type curatedArtifactFit } from "./model-catalog.ts";
const GGUF_SUFFIX_RE = /-GGUF(?:$|-)/i;
// Mirrors the backend's _looks_like_mlx_repo: owner prefix, or a bounded mlx token in the leaf.
@@ -360,3 +360,39 @@ export function orderRecommendedRows<
);
return [...curated, ...rest];
}
+
+/** The allowance a curated row was judged against, the memory it is 70% of, and the unrounded size. */
+export type CuratedBudget = {
+ allowanceGb: number;
+ deviceGb: number;
+ device: "GPU" | "RAM";
+ sizeGb: number;
+};
+
+export function curatedBudget(
+ fit: NonNullable<ReturnType<typeof curatedArtifactFit>>,
+): CuratedBudget | undefined {
+ const { allowanceGb, deviceGb, device, sizeGb } = fit;
+ return allowanceGb != null && deviceGb != null && device && sizeGb != null
+ ? { allowanceGb, deviceGb, device, sizeGb }
+ : undefined;
+}
+
+/** Over-budget text for a curated row. When the whole-GB badge figure does not read above the
+ * one-decimal budget (24 against 24.1), the size is rounded up and the budget down to a tenth, so
+ * the shown size is always strictly above the shown budget. The epsilon keeps 16.7999... at 16.8. */
+export function curatedBudgetText(est: number, gpuGb: number, budget: CuratedBudget): string {
+ const shownBudget = Number(budget.allowanceGb.toFixed(1));
+ const wholeReadsOver = est > shownBudget;
+ const needGb = wholeReadsOver
+ ? `${est}`
+ : (Math.ceil(budget.sizeGb * 10 - 1e-9) / 10).toFixed(1);
+ const budgetGb = wholeReadsOver
+ ? shownBudget.toFixed(1)
+ : (Math.floor(budget.allowanceGb * 10 + 1e-9) / 10).toFixed(1);
+ const of =
+ 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/dense-quant-prequant-routing.test.ts b/studio/frontend/tests/dense-quant-prequant-routing.test.ts
index e4660e1019c..ad0f5139d0d 100644
--- a/studio/frontend/tests/dense-quant-prequant-routing.test.ts
+++ b/studio/frontend/tests/dense-quant-prequant-routing.test.ts
@@ -14,16 +14,22 @@ import {
VIDEO_CATALOG,
artifactForRepoId,
catalogToModelOptions,
+ curatedArtifactFit,
curatedArtifactFitsDevice,
curatedDisplayNameFor,
curatedRowLabelFor,
groupForRepoId,
pickDefaultArtifact,
} 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 Z_TURBO = "Tongyi-MAI/Z-Image-Turbo";
const QWEN_IMAGE = "Qwen/Qwen-Image";
const QWEN_2512 = "Qwen/Qwen-Image-2512";
+const QWEN_21 = "Qwen/Qwen-Image-2.1";
const H3 = "MiniMaxAI/MiniMax-H3";
const notDownloaded = () => false;
@@ -273,3 +279,74 @@ test("the scheme reaches the name and never the chip", () => {
}
}
});
+
+// Show the verdict's estimate, not the dense catalog size.
+test("Qwen-Image-2.1 is badged with the size its verdict used", () => {
+ const card = onCard(22.49, ["int8", "fp8"]);
+ const fit = curatedArtifactFit(QWEN_21, IMAGE_CATALOG, card);
+ assert.ok(fit?.sizeGb !== undefined);
+ assert.ok(Math.abs(fit.sizeGb - 27.01) < 0.01, String(fit.sizeGb));
+ assert.equal(fit.allowanceGb, 22.49 * 0.7);
+ assert.equal(fit.fits, false);
+ assert.equal(curatedArtifactFitsDevice(QWEN_21, IMAGE_CATALOG, card), fit.fits);
+ // No dense-quant scheme reported: the dense figure.
+ assert.equal(curatedArtifactFit(QWEN_21, IMAGE_CATALOG, onCard(22.49, []))?.sizeGb, 33);
+});
+
+test("a transcription row judged on RAM names RAM as the budget's device", () => {
+ const WHISPER = "unsloth/whisper-large-v3";
+ const onRam = curatedArtifactFit(WHISPER, AUDIO_CATALOG, { gpuGb: 1, systemRamGb: 5 });
+ assert.equal(onRam?.fits, false);
+ assert.equal(onRam?.device, "RAM");
+ assert.equal(onRam?.deviceGb, 5);
+ assert.equal(onRam?.allowanceGb, 5 * 0.7);
+ const onGpu = curatedArtifactFit(WHISPER, AUDIO_CATALOG, { gpuGb: 5, systemRamGb: 1 });
+ assert.equal(onGpu?.device, "GPU");
+ assert.equal(onGpu?.deviceGb, 5);
+});
+
+test("the over-budget text never shows the size below the budget it exceeds", () => {
+ const text = (id: string, gpuGb: number) => {
+ const fit = curatedArtifactFit(id, IMAGE_CATALOG, onCard(gpuGb, ["int8", "fp8"]));
+ assert.ok(fit?.sizeGb !== undefined && fit.fits === false);
+ const budget = curatedBudget(fit);
+ assert.ok(budget);
+ return curatedBudgetText(Math.round(fit.sizeGb), gpuGb, budget);
+ };
+ // 24.40 GB rounds to 24, under the 24.1 budget, so it is shown rounded up.
+ assert.equal(
+ text(Z_TURBO, 34.5),
+ "Needs ~24.4GB for weights (budget: ~24.1GB, 70% of a 34.5GB GPU)",
+ );
+ // A whole 4 GB against a 3.99 allowance: the budget is rounded down so 4.0 still reads as over.
+ const whisper = curatedArtifactFit("unsloth/whisper-large-v3", AUDIO_CATALOG, {
+ gpuGb: 1,
+ systemRamGb: 5.7,
+ });
+ assert.ok(whisper?.sizeGb !== undefined && whisper.fits === false);
+ const whisperBudget = curatedBudget(whisper);
+ assert.ok(whisperBudget);
+ assert.equal(
+ curatedBudgetText(4, 1, whisperBudget),
+ "Needs ~4.0GB for weights (budget: ~3.9GB, 70% of 5.7GB available RAM)",
+ );
+ assert.equal(
+ text(QWEN_21, 22.49),
+ "Needs ~27GB for weights (budget: ~15.7GB, 70% of a 22.49GB GPU)",
+ );
+});
+
+test("Qwen-Image-2.1 routes every card as on main", () => {
+ const group = groupForRepoId(QWEN_21, IMAGE_CATALOG);
+ assert.ok(group);
+ const pick = (gpuGb: number) =>
+ pickDefaultArtifact(group, {
+ ...onCard(gpuGb, ["int8"]),
+ isDownloaded: notDownloaded,
+ }).repoId;
+ // Include 36 GiB to catch changes just below the existing routing threshold.
+ assert.equal(pick(24), "unsloth/Qwen-Image-2.1-GGUF");
+ assert.equal(pick(31.84), "unsloth/Qwen-Image-2.1-GGUF");
+ assert.equal(pick(36), "unsloth/Qwen-Image-2.1-GGUF");
+ assert.equal(pick(39.5), QWEN_21);
+});
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 f4a007a6623..33a01e25990 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
@@ -525,7 +525,7 @@ test("a GGUF row takes the GGUF verdict, not the torch refusal", () => {
);
assert.equal(producers.length, 2, "curated rows only");
for (const line of producers) {
- assert.match(line, /curatedFits \? null : "exceeds"/);
+ assert.match(line, /curatedFit\.fits \? null : "exceeds"/);
}
});
diff --git a/studio/frontend/tests/recommended-curated-row-metadata.test.ts b/studio/frontend/tests/recommended-curated-row-metadata.test.ts
index 179c1da83ee..f2d4e99a50c 100644
--- a/studio/frontend/tests/recommended-curated-row-metadata.test.ts
+++ b/studio/frontend/tests/recommended-curated-row-metadata.test.ts
@@ -298,7 +298,7 @@ test("every list that judges a row against the device asks the same helper", ()
// calls it a fit and painted with the OOM badge at the same time.
assert.match(
declarationText("catalogFit"),
- /curatedArtifactFitsDevice\(id, catalog, budget\)/,
+ /curatedArtifactFit\(id, catalog, budget\)/,
);
for (const declaration of ["recommendedRows", "searchRowFits"]) {
assert.match(