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: recommend a Hub GGUF quant that fits the Mac's Metal budget (#15848)

Nilay0f51e218612e
diff --git a/studio/frontend/src/features/hub/catalog/download-section.tsx b/studio/frontend/src/features/hub/catalog/download-section.tsx
index 66c491b6c11..a8272d8ac29 100644
--- a/studio/frontend/src/features/hub/catalog/download-section.tsx
+++ b/studio/frontend/src/features/hub/catalog/download-section.tsx
@@ -27,6 +27,7 @@ export function DownloadSection({
gpuGb,
gpuCount,
systemRamGb,
+ unifiedLoadBudgetGb,
cachePath,
knownBytes,
onRun,
@@ -55,6 +56,7 @@ export function DownloadSection({
gpuGb?: number;
gpuCount?: number;
systemRamGb?: number;
+ unifiedLoadBudgetGb?: number | null;
cachePath?: string | null;
knownBytes?: number | null;
onRun?: (selection: HubModelRunSelection) => void;
@@ -79,6 +81,7 @@ export function DownloadSection({
gpuGb={gpuGb}
gpuCount={gpuCount}
systemRamGb={systemRamGb}
+ unifiedLoadBudgetGb={unifiedLoadBudgetGb}
cachePath={cachePath}
isPartial={isPartial}
onRun={onRun}
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 07f55e9b8c6..74be66f1e4f 100644
--- a/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx
+++ b/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx
@@ -24,6 +24,7 @@ import {
TooltipTrigger,
} from "@/components/ui/tooltip";
import { usePlatformStore } from "@/config/env";
+import { useT } from "@/i18n";
import { getCachedModelPath, revealCachedModel } from "@/features/chat";
import {
formatFootprintBytes,
@@ -174,6 +175,7 @@ function QuantBadge({
fit,
lookupTableBytes = 0,
showFit = true,
+ unifiedBudget = false,
variant = "trigger",
tooltipMode = "eager",
}: {
@@ -181,9 +183,11 @@ function QuantBadge({
fit: GgufFitClass;
lookupTableBytes?: number;
showFit?: boolean;
+ unifiedBudget?: boolean;
variant?: "trigger" | "menu";
tooltipMode?: "eager" | "lazy" | "none";
}) {
+ const t = useT();
const meta = FIT_BADGE[fit];
const [tooltipArmed, setTooltipArmed] = useState(false);
const [tooltipOpen, setTooltipOpen] = useState(false);
@@ -248,7 +252,9 @@ function QuantBadge({
{inner}
</TooltipTrigger>
<TooltipContent side="top" sideOffset={4}>
- {meta.tooltip}
+ {fit === "marginal" && unifiedBudget
+ ? t("picker.unifiedTightFitHint")
+ : meta.tooltip}
{lookupTableBytes > 0 && (
<span className="mt-1 block text-muted-foreground">
Lookup tables: {formatFootprintBytes(lookupTableBytes)}
@@ -357,6 +363,7 @@ function createGgufVariantMenuItems(
gpuCount?: number;
systemRamGb?: number;
budgetFraction?: number;
+ unifiedLoadBudgetGb?: number | null;
},
companionBytesByKey: ReadonlyMap<string, number>,
): GgufVariantMenuItem[] {
@@ -548,6 +555,7 @@ const GgufVariantMenuRow = memo(function GgufVariantMenuRow({
mutationBlocked,
liveActive,
showFitInfo,
+ unifiedBudget,
onSelect,
onDelete,
}: {
@@ -557,6 +565,7 @@ const GgufVariantMenuRow = memo(function GgufVariantMenuRow({
mutationBlocked: boolean;
liveActive: boolean;
showFitInfo: boolean;
+ unifiedBudget: boolean;
onSelect: (quant: string) => void;
onDelete: (quant: string) => void;
}) {
@@ -603,6 +612,7 @@ const GgufVariantMenuRow = memo(function GgufVariantMenuRow({
fit={item.fit}
lookupTableBytes={item.lookupTableBytes}
showFit={showFitInfo}
+ unifiedBudget={unifiedBudget}
variant="menu"
tooltipMode="lazy"
/>
@@ -667,6 +677,7 @@ export function GgufDownloadCard({
gpuGb,
gpuCount,
systemRamGb,
+ unifiedLoadBudgetGb,
cachePath,
preferLocalCache = false,
isPartial = false,
@@ -686,6 +697,7 @@ export function GgufDownloadCard({
gpuGb?: number;
gpuCount?: number;
systemRamGb?: number;
+ unifiedLoadBudgetGb?: number | null;
cachePath?: string | null;
preferLocalCache?: boolean;
isPartial?: boolean;
@@ -750,8 +762,16 @@ export function GgufDownloadCard({
gpuCount,
systemRamGb,
budgetFraction,
+ unifiedLoadBudgetGb,
});
- }, [variants, gpuGb, gpuCount, systemRamGb, budgetFraction]);
+ }, [
+ variants,
+ gpuGb,
+ gpuCount,
+ systemRamGb,
+ budgetFraction,
+ unifiedLoadBudgetGb,
+ ]);
const selectLiveGgufVariantStates = useMemo(
() => createLiveGgufVariantStatesSelector(repoId),
[repoId],
@@ -804,6 +824,7 @@ export function GgufDownloadCard({
gpuCount,
systemRamGb,
budgetFraction,
+ unifiedLoadBudgetGb,
},
companionBytesByKey,
),
@@ -813,6 +834,7 @@ export function GgufDownloadCard({
sortedVariants,
systemRamGb,
budgetFraction,
+ unifiedLoadBudgetGb,
companionBytesByKey,
],
);
@@ -906,6 +928,7 @@ export function GgufDownloadCard({
gpuCount,
systemRamGb,
budgetFraction,
+ unifiedLoadBudgetGb,
})
: null;
const selectedDownloadSizeLabel = selected
@@ -1168,6 +1191,7 @@ export function GgufDownloadCard({
fit={selectedFit ?? "oom"}
lookupTableBytes={ggufVariantLookupTableBytes(selected)}
showFit={showFitInfo}
+ unifiedBudget={unifiedLoadBudgetGb != null}
/>
) : (
<span className="text-ui-12p5 text-muted-foreground">
@@ -1254,6 +1278,7 @@ export function GgufDownloadCard({
}
liveActive={liveActive}
showFitInfo={showFitInfo}
+ unifiedBudget={unifiedLoadBudgetGb != null}
onSelect={handleSelectVariant}
onDelete={handleDeleteVariant}
/>
@@ -1311,7 +1336,15 @@ export function GgufDownloadCard({
<button
type="button"
disabled={downloadAction.disabled || assets.checking}
- onClick={() => downloadingThisVariant ? downloadAction.onClick() : void assets.request(downloadAction.onClick)}
+ onClick={() => {
+ if (downloadingThisVariant) {
+ downloadAction.onClick();
+ return;
+ }
+ // The default follows live free memory; pin it so the card keeps this transfer.
+ if (selectedQuant) handleSelectVariant(selectedQuant);
+ void assets.request(downloadAction.onClick);
+ }}
aria-label={
selectedScopedLive ? "Downloading" : downloadAction.ariaLabel
}
diff --git a/studio/frontend/src/features/hub/catalog/model-inspector.tsx b/studio/frontend/src/features/hub/catalog/model-inspector.tsx
index 0dc937913e6..bea0b2baf96 100644
--- a/studio/frontend/src/features/hub/catalog/model-inspector.tsx
+++ b/studio/frontend/src/features/hub/catalog/model-inspector.tsx
@@ -424,6 +424,7 @@ export type ModelInspectorRuntime = {
gpuGb?: number;
gpuCount?: number;
systemRamGb?: number;
+ unifiedLoadBudgetGb?: number | null;
};
export type ModelInspectorActions = {
@@ -464,6 +465,7 @@ export const ModelInspector = memo(function ModelInspector({
gpuGb,
gpuCount,
systemRamGb,
+ unifiedLoadBudgetGb,
} = runtime;
const {
onInventoryChange,
@@ -770,6 +772,9 @@ export const ModelInspector = memo(function ModelInspector({
gpuGb={gpuGb}
gpuCount={gpuCount}
systemRamGb={systemRamGb}
+ unifiedLoadBudgetGb={
+ runsOnMediaRuntime ? null : unifiedLoadBudgetGb
+ }
cachePath={model.path}
knownBytes={model.cachedBytes}
onRun={runAction}
diff --git a/studio/frontend/src/features/hub/hub-page.tsx b/studio/frontend/src/features/hub/hub-page.tsx
index 29a39105c41..69a7c6b7eee 100644
--- a/studio/frontend/src/features/hub/hub-page.tsx
+++ b/studio/frontend/src/features/hub/hub-page.tsx
@@ -452,6 +452,7 @@ export function ModelsPage() {
? checkpoint
: null;
const activeGgufVariant = useChatRuntimeStore((s) => s.activeGgufVariant);
+ const keepModelsLoaded = useChatRuntimeStore((s) => s.keepModelsLoaded);
const loadedIsMlx = useChatRuntimeStore((s) => s.loadedIsMlx);
const loadingModel = useChatRuntimeStore((s) => s.loadingModelPick);
const [initialResidentStatusSettled, setInitialResidentStatusSettled] =
@@ -1838,6 +1839,10 @@ export function ModelsPage() {
inferenceGpu.systemRamAvailableGb > 0
? inferenceGpu.systemRamAvailableGb
: undefined,
+ unifiedLoadBudgetGb:
+ (!keepModelsLoaded && residentCheckpoint
+ ? inferenceGpu.unifiedLoadCeilingGb
+ : inferenceGpu.unifiedLoadBudgetGb) ?? null,
}),
[
isActive,
@@ -1848,6 +1853,10 @@ export function ModelsPage() {
inferenceGpu.memoryTotalGb,
inferenceGpu.deviceCount,
inferenceGpu.systemRamAvailableGb,
+ inferenceGpu.unifiedLoadBudgetGb,
+ inferenceGpu.unifiedLoadCeilingGb,
+ keepModelsLoaded,
+ residentCheckpoint,
],
);
diff --git a/studio/frontend/tests/hub-gguf-card-unified-budget.test.ts b/studio/frontend/tests/hub-gguf-card-unified-budget.test.ts
new file mode 100644
index 00000000000..9b0759256e8
--- /dev/null
+++ b/studio/frontend/tests/hub-gguf-card-unified-budget.test.ts
@@ -0,0 +1,252 @@
+// 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 { registerBundlerResolver } from "./helpers/kit.ts";
+import {
+ type StubElement,
+ loadWithStubs,
+ stubJsxRuntime,
+} from "./helpers/module-stubs.ts";
+
+registerBundlerResolver();
+
+const [ggufFit, variantSort, modelIdentity, ggufFilename, format] =
+ await Promise.all([
+ import("../src/lib/gguf-fit.ts"),
+ import("../src/features/hub/lib/gguf-variant-sort.ts"),
+ import("../src/features/hub/lib/model-identity.ts"),
+ import("../src/features/hub/lib/gguf-filename.ts"),
+ import("../src/features/hub/lib/format.ts"),
+ ]);
+
+const GiB = 1024 ** 3;
+const VARIANTS = [
+ { quant: "Q4_K_M", filename: "Qwen3-8B-Q4_K_M.gguf", size_bytes: 4.68 * GiB },
+ { quant: "Q8_0", filename: "Qwen3-8B-Q8_0.gguf", size_bytes: 8.11 * GiB },
+ { quant: "BF16", filename: "Qwen3-8B-BF16.gguf", size_bytes: 15.26 * GiB },
+];
+
+type Card = {
+ GgufDownloadCard: (props: Record<string, unknown>) => StubElement;
+};
+
+function loadCard(
+ useState?: (initial: unknown) => [unknown, (next: unknown) => void],
+): Card {
+ const noop = () => undefined;
+ const anyExport = new Proxy({}, { get: () => noop });
+ return loadWithStubs<Card>(
+ new URL(
+ "../src/features/hub/catalog/gguf-download-card.tsx",
+ import.meta.url,
+ ),
+ {
+ react: {
+ memo: (component: unknown) => component,
+ useCallback: (fn: unknown) => fn,
+ useEffect: noop,
+ useMemo: (read: () => unknown) => read(),
+ useState:
+ useState ??
+ ((initial: unknown) => [
+ typeof initial === "function" ? initial() : initial,
+ noop,
+ ]),
+ },
+ "react/jsx-runtime": stubJsxRuntime(),
+ "@/lib/gguf-fit": ggufFit,
+ "../lib/gguf-variant-sort": variantSort,
+ "../lib/model-identity": modelIdentity,
+ "../lib/gguf-filename": ggufFilename,
+ "../lib/format": format,
+ "./use-gguf-variant-fetch-state": {
+ useGgufVariantFetchState: () => ({
+ variants: VARIANTS,
+ loading: false,
+ error: null,
+ refreshError: null,
+ refresh: noop,
+ }),
+ },
+ "../download-manager": {
+ downloadManager: { probeAndAdopt: noop },
+ pendingDrafterPresentation: () => null,
+ useDownloadManagerStore: () => new Map(),
+ useHttpPartialsResumable: () => false,
+ useRepoDownload: () => ({ progress: null, cancelling: false }),
+ },
+ "../download-manager/use-hub-download-queue": {
+ useHubDownloadPlan: () => null,
+ },
+ "./gguf-live-variant-states": {
+ activeDownloadState: () => false,
+ applyLiveGgufVariantStates: (variants: unknown) => variants,
+ createLiveGgufVariantStatesSelector: noop,
+ createScopedLiveGgufFilesSelector: noop,
+ isScopedLiveVariant: () => false,
+ },
+ "../hooks/use-media-companion-bytes": {
+ awaitsCompanions: () => false,
+ ggufVariantFootprint: () => null,
+ useMediaCompanionBytes: () => new Map(),
+ },
+ "./use-download-card-state": {
+ useDownloadCardState: () => ({
+ starting: false,
+ ariaLabel: "Download",
+ onClick: noop,
+ }),
+ },
+ "./delete-impact": { DeleteImpactSummary: noop, useDeleteImpact: noop },
+ "./use-delete-confirm-action": {
+ useDeleteConfirmAction: () => ({ deleting: false, runDelete: noop }),
+ },
+ "@/hooks/use-vram-budget-fraction": { useVramBudgetFraction: () => null },
+ "../hooks/use-online-status": { useOnlineStatus: () => true },
+ "../stores/hf-token-store": { useHfTokenStore: () => null },
+ "./use-required-assets-download": {
+ useRequiredAssetsDownload: () => ({ checking: false, request: noop }),
+ },
+ "../download-manager/hub-plan-progress": anyExport,
+ "@/components/model-memory-bar": anyExport,
+ "@/components/ui/dropdown-menu": anyExport,
+ "@/components/ui/popover": anyExport,
+ "@/components/ui/spinner": anyExport,
+ "@/components/ui/tooltip": anyExport,
+ "@/config/env": anyExport,
+ "@/i18n": { useT: () => (key: string) => key },
+ "@/features/chat": anyExport,
+ "@/features/model-picker": anyExport,
+ "@/lib/chevron-icons": anyExport,
+ "@/lib/copy-to-clipboard": anyExport,
+ "@/lib/toast": anyExport,
+ "@/lib/utils": anyExport,
+ "@hugeicons/core-free-icons": anyExport,
+ "@/lib/copy-icon": anyExport,
+ "@hugeicons/react": anyExport,
+ "../inventory": anyExport,
+ "./dot-tag": anyExport,
+ "./download-cancel-indicator": anyExport,
+ "./download-card": anyExport,
+ "./gguf-status-cards": anyExport,
+ },
+ );
+}
+
+function elements(node: unknown, out: StubElement[] = []): StubElement[] {
+ if (Array.isArray(node)) {
+ for (const child of node) elements(child, out);
+ } else if (node && typeof node === "object" && "props" in node) {
+ const element = node as StubElement;
+ out.push(element);
+ for (const value of Object.values(element.props)) elements(value, out);
+ }
+ return out;
+}
+
+function renderOnMac(unifiedLoadBudgetGb: number | null) {
+ const tree = loadCard().GgufDownloadCard({
+ repoId: "unsloth/Qwen3-8B-GGUF",
+ isActive: false,
+ activeQuant: null,
+ isLoadingThisModel: false,
+ gpuGb: 24,
+ gpuCount: 1,
+ systemRamGb: 9,
+ unifiedLoadBudgetGb,
+ });
+ const nodes = elements(tree);
+ const trigger = nodes.find(
+ (node) => "fit" in node.props && "lookupTableBytes" in node.props,
+ );
+ const rows = nodes
+ .map(
+ (node) => node.props.item as { quant: string; fit: string } | undefined,
+ )
+ .filter((item) => item !== undefined);
+ const badge = trigger
+ ? (trigger.type as (props: unknown) => unknown)(trigger.props)
+ : null;
+ return {
+ recommended: trigger?.props.quant,
+ recommendedFit: trigger?.props.fit,
+ fits: Object.fromEntries(rows.map((row) => [row.quant, row.fit])),
+ tooltip: elements(badge)
+ .flatMap((node) => [node.props.children].flat())
+ .filter((child) => typeof child === "string"),
+ };
+}
+
+test("the Hub GGUF card recommends a quant inside the Mac's Metal load budget", () => {
+ const card = renderOnMac(7.5);
+ assert.equal(card.recommended, "Q4_K_M");
+ assert.equal(card.recommendedFit, "fits");
+ assert.deepEqual(card.fits, {
+ Q4_K_M: "fits",
+ BF16: "marginal",
+ Q8_0: "marginal",
+ });
+});
+
+test("without a Metal budget the Hub GGUF card keeps ranking by memory", () => {
+ const card = renderOnMac(null);
+ assert.equal(card.recommended, "BF16");
+ assert.deepEqual(card.fits, { BF16: "fits", Q8_0: "fits", Q4_K_M: "fits" });
+});
+
+test("an over-budget quant on a Mac points at the Metal budget, not the VRAM Budget", () => {
+ const mac = renderOnMac(3);
+ assert.equal(mac.recommendedFit, "marginal");
+ assert.ok(mac.tooltip.includes("picker.unifiedTightFitHint"));
+ const discrete = loadCard().GgufDownloadCard({
+ repoId: "unsloth/Qwen3-8B-GGUF",
+ isActive: false,
+ activeQuant: null,
+ isLoadingThisModel: false,
+ gpuGb: 6.5,
+ gpuCount: 1,
+ systemRamGb: 32,
+ });
+ const trigger = elements(discrete).find(
+ (node) => "lookupTableBytes" in node.props,
+ );
+ assert.equal(trigger?.props.fit, "marginal");
+ const tooltip = elements(
+ (trigger?.type as (props: unknown) => unknown)(trigger?.props),
+ ).flatMap((node) => [node.props.children].flat());
+ assert.ok(tooltip.some((child) => String(child).includes("VRAM Budget")));
+});
+
+test("starting a download pins the recommended quant so a moving Metal budget keeps the transfer on the card", () => {
+ const writes: unknown[] = [];
+ const tree = loadCard((initial) => [
+ typeof initial === "function" ? initial() : initial,
+ (next) => writes.push(next),
+ ]).GgufDownloadCard({
+ repoId: "unsloth/Qwen3-8B-GGUF",
+ isActive: false,
+ activeQuant: null,
+ isLoadingThisModel: false,
+ gpuGb: 24,
+ gpuCount: 1,
+ systemRamGb: 9,
+ unifiedLoadBudgetGb: 7.5,
+ });
+ const download = elements(tree).find(
+ (node) => node.type === "button" && node.props["aria-label"] === "Download",
+ );
+ assert.ok(download);
+ (download.props.onClick as () => void)();
+ assert.ok(
+ writes.some(
+ (write) =>
+ typeof write === "object" &&
+ write !== null &&
+ (write as { quant?: string }).quant === "Q4_K_M" &&
+ (write as { userPicked?: boolean }).userPicked === true,
+ ),
+ );
+});