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 Hub GGUF fit estimates for companion files (#10249)

Lee Jackson8ab155ba429a
diff --git a/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx b/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx
index d73cfdaac42..3bbfca9e990 100644
--- a/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx
+++ b/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx
@@ -23,10 +23,10 @@ import {
import { usePlatformStore } from "@/config/env";
import { getCachedModelPath, revealCachedModel } from "@/features/chat";
import { pinKey, usePinnedModelsStore } from "@/features/model-picker";
+import { useVramBudgetFraction } from "@/hooks/use-vram-budget-fraction";
import { ChevronDownStandardIcon } from "@/lib/chevron-icons";
import { copyToClipboard } from "@/lib/copy-to-clipboard";
-import { type GgufFitClass, classifyGgufFit } from "@/lib/gguf-fit";
-import { useVramBudgetFraction } from "@/hooks/use-vram-budget-fraction";
+import { type GgufFitClass, classifyGgufVariantFit } from "@/lib/gguf-fit";
import { toast } from "@/lib/toast";
import { cn } from "@/lib/utils";
import {
@@ -269,7 +269,7 @@ function createGgufVariantMenuItems(
key: normalizeGgufVariantIdentity(variant.quant),
quant: variant.quant,
label: ggufVariantDisplayLabel(variant),
- fit: classifyGgufFit(variant.size_bytes, resources),
+ fit: classifyGgufVariantFit(variant, resources),
downloaded: Boolean(variant.downloaded),
partial: Boolean(variant.partial),
downloadSizeLabel: ggufVariantTransferLabel(variant),
@@ -783,18 +783,14 @@ export function GgufDownloadCard({
// No verdict beats a wrong one: a media repo's fit is the diffusion planner's question, and
// this card only knows how to answer llama.cpp's. The picker still badges those rows.
const showFitInfo = !mediaRuntime && (Boolean(gpuGb) || Boolean(systemRamGb));
- const selectedFit = useMemo(
- () =>
- selected
- ? classifyGgufFit(selected.size_bytes, {
- gpuGb,
- gpuCount,
- systemRamGb,
- budgetFraction,
- })
- : null,
- [gpuGb, gpuCount, selected?.size_bytes, systemRamGb, budgetFraction],
- );
+ const selectedFit = selected
+ ? classifyGgufVariantFit(selected, {
+ gpuGb,
+ gpuCount,
+ systemRamGb,
+ budgetFraction,
+ })
+ : null;
const selectedDownloadSizeLabel = selected
? ggufVariantTransferLabel(selected)
: null;
diff --git a/studio/frontend/src/features/hub/lib/gguf-variant-sort.ts b/studio/frontend/src/features/hub/lib/gguf-variant-sort.ts
index 34e9557b56d..7fe155f36c1 100644
--- a/studio/frontend/src/features/hub/lib/gguf-variant-sort.ts
+++ b/studio/frontend/src/features/hub/lib/gguf-variant-sort.ts
@@ -3,19 +3,8 @@
import type { GgufVariantDetail } from "@/features/hub/inventory";
import { formatBytes } from "@/features/hub/lib/format";
-import { classifyGgufFit } from "@/lib/gguf-fit";
import { ggufVariantsMatch } from "@/features/hub/lib/model-identity";
-
-type GgufVariantResources = {
- gpuGb?: number;
- systemRamGb?: number;
- /** The saved VRAM Budget, so the sort ranks against the line the loader will
- * actually admit at rather than against the default. */
- budgetFraction?: number;
- /** GPUs gpuGb sums, so the sort charges the loader's per-card VRAM reserve as
- * many times as the loader does. */
- gpuCount?: number;
-};
+import { type GgufFitInput, classifyGgufVariantFit } from "@/lib/gguf-fit";
export function ggufVariantDisplayLabel(
variant: Pick<GgufVariantDetail, "display_label" | "quant">,
@@ -54,9 +43,9 @@ export function ggufVariantTransferLabel(variant: GgufVariantTransfer): string {
export function ggufVariantFitRank(
variant: GgufVariantDetail,
- resources: GgufVariantResources,
+ resources: GgufFitInput,
): number {
- switch (classifyGgufFit(variant.size_bytes, resources)) {
+ switch (classifyGgufVariantFit(variant, resources)) {
case "fits":
return 0;
case "marginal":
@@ -72,7 +61,7 @@ export function ggufVariantFitRank(
export function compareGgufVariantFitAndSize(
a: GgufVariantDetail,
b: GgufVariantDetail,
- resources: GgufVariantResources,
+ resources: GgufFitInput,
): number {
const aFit = ggufVariantFitRank(a, resources);
const bFit = ggufVariantFitRank(b, resources);
@@ -90,7 +79,7 @@ export function ggufVariantDownloadStatusRank(
export function sortDownloadableGgufVariants(
variants: readonly GgufVariantDetail[],
- resources: GgufVariantResources,
+ resources: GgufFitInput,
): GgufVariantDetail[] {
return [...variants].sort((a, b) => {
const statusDelta =
@@ -102,7 +91,7 @@ export function sortDownloadableGgufVariants(
export function sortLocalGgufVariants(
variants: readonly GgufVariantDetail[],
- options: GgufVariantResources & {
+ options: GgufFitInput & {
activeGgufVariant?: string | null;
defaultVariant?: string | null;
},
diff --git a/studio/frontend/src/lib/gguf-fit.ts b/studio/frontend/src/lib/gguf-fit.ts
index ddb56677152..9f9db042acd 100644
--- a/studio/frontend/src/lib/gguf-fit.ts
+++ b/studio/frontend/src/lib/gguf-fit.ts
@@ -125,3 +125,34 @@ export function classifyGgufFit(
if (required <= combined) return "partial";
return "oom";
}
+
+/** Structural rather than the Hub's `GgufVariantDetail`, so this module stays below
+ * the features that own it. */
+export interface GgufVariantSizes {
+ size_bytes: number;
+ download_size_bytes?: number;
+}
+
+/** Byte basis for a fit verdict on a listed variant.
+ *
+ * `size_bytes` is the main weights; `download_size_bytes` also covers the companion
+ * GGUFs fetched beside them — a vision model's mmproj, and the MTP or DFlash drafter
+ * `auto` speculation may promote to.
+ *
+ * Leans high on purpose. One aggregate cannot say which of those stay resident, while
+ * the load planner charges a projector at a multiple of its file size, skips it with
+ * vision off, and prices a drafter only when one would open (`/kv-cache-estimate` in
+ * routes/models.py).
+ *
+ * The larger of the two, never the total alone: the offline listing path reports it as
+ * the weights and an older backend as zero (hub/services/models/gguf_variants.py). */
+export function ggufVariantFitSizeBytes(variant: GgufVariantSizes): number {
+ return Math.max(variant.size_bytes, variant.download_size_bytes ?? 0);
+}
+
+export function classifyGgufVariantFit(
+ variant: GgufVariantSizes,
+ input: GgufFitInput,
+): GgufFitClass {
+ return classifyGgufFit(ggufVariantFitSizeBytes(variant), input);
+}
diff --git a/studio/frontend/tests/gguf-variant-transfer-size.test.ts b/studio/frontend/tests/gguf-variant-transfer-size.test.ts
index 9cee9930cd8..89676e8ce64 100644
--- a/studio/frontend/tests/gguf-variant-transfer-size.test.ts
+++ b/studio/frontend/tests/gguf-variant-transfer-size.test.ts
@@ -12,9 +12,8 @@ import { registerBundlerResolver } from "./helpers/kit.ts";
registerBundlerResolver();
-const { ggufVariantTransferBytes, ggufVariantTransferLabel } = await import(
- "../src/features/hub/lib/gguf-variant-sort.ts"
-);
+const { ggufVariantFitRank, ggufVariantTransferBytes, ggufVariantTransferLabel } =
+ await import("../src/features/hub/lib/gguf-variant-sort.ts");
const GB = 1000 ** 3;
@@ -76,3 +75,25 @@ test("a partial with nothing left reads as zero rather than the total", () => {
assert.equal(ggufVariantTransferBytes(variant), 0);
});
+
+test("the menu is ranked by the footprint the rows are badged by", () => {
+ // Ranking on the weights while badging the total put a "partial" row above "fits".
+ const resources = { gpuGb: 16, systemRamGb: 32 };
+ const main = 12_789_199_648;
+ const row = (over: { download_size_bytes?: number }) => ({
+ quant: "Q3_K_S",
+ filename: "muse-Q3_K_S.gguf",
+ size_bytes: main,
+ download_size_bytes: main,
+ ...over,
+ });
+
+ assert.equal(ggufVariantFitRank(row({}), resources), 0);
+ assert.equal(
+ ggufVariantFitRank(
+ row({ download_size_bytes: main + 3_849_173_920 + 1_451_094_176 }),
+ resources,
+ ),
+ 2,
+ );
+});
diff --git a/studio/frontend/tests/memory-shared-core.test.ts b/studio/frontend/tests/memory-shared-core.test.ts
index 019627b16c0..0d3c0c3d5b8 100644
--- a/studio/frontend/tests/memory-shared-core.test.ts
+++ b/studio/frontend/tests/memory-shared-core.test.ts
@@ -384,3 +384,41 @@ test("the budget read is shared, not one request per mounted card", async () =>
"the change event must refresh the cache, or a save never reaches the cards",
);
});
+
+// ---------------------------------------------------------------------------
+// A verdict on a VARIANT scores the whole footprint the download plan fetches
+
+test("a variant's fit counts the companions fetched with it", async () => {
+ // Bartowski Muse Glimmer Q3_K_S: 12.79 GB of weights, a 3.85 GB projector and a
+ // 1.45 GB DFlash drafter. Only the weights clear a 16 GiB card.
+ const { classifyGgufVariantFit, ggufVariantFitSizeBytes } = await import(
+ "../src/lib/gguf-fit.ts"
+ );
+ const weights = 12_789_199_648;
+ const variant = {
+ size_bytes: weights,
+ download_size_bytes: weights + 3_849_173_920 + 1_451_094_176,
+ };
+ const budget = { gpuGb: 16, systemRamGb: 32 };
+
+ assert.equal(ggufVariantFitSizeBytes(variant), variant.download_size_bytes);
+ assert.equal(
+ classifyGgufVariantFit({ size_bytes: weights }, budget),
+ "fits",
+ "the fixture only proves anything while the weights alone still fit",
+ );
+ assert.equal(classifyGgufVariantFit(variant, budget), "partial");
+});
+
+test("a total below the weights never lowers the estimate", async () => {
+ // A positive-but-smaller total is the case a `??` or `||` fallback lets through.
+ const { ggufVariantFitSizeBytes } = await import("../src/lib/gguf-fit.ts");
+ const bytes = 12 * GIB;
+ for (const download_size_bytes of [undefined, 0, bytes - 1, 1]) {
+ assert.equal(
+ ggufVariantFitSizeBytes({ size_bytes: bytes, download_size_bytes }),
+ bytes,
+ `a total of ${download_size_bytes} must not score below the weights`,
+ );
+ }
+});