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
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.tsxindex 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.tsxindex 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({<buttontype="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.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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,+ ),+ );+});