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: warn when a GGUF is tight for Apple unified memory (#14598)

Michael Han3569dfa8a534
diff --git a/studio/backend/tests/test_mlx_metal_working_set_visibility.py b/studio/backend/tests/test_mlx_metal_working_set_visibility.py
new file mode 100644
index 00000000000..65a810fbb26
--- /dev/null
+++ b/studio/backend/tests/test_mlx_metal_working_set_visibility.py
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from unittest.mock import patch
+
+import pytest
+
+from utils.hardware import DeviceType
+from utils.hardware import hardware as hw
+
+_MEM = {"available": True, "total_gb": 64.0, "device_name": "Apple M3 Max"}
+
+
+def _mlx_device(working_set):
+ with (
+ patch.object(hw, "get_gpu_memory_info", return_value = dict(_MEM)),
+ patch.object(hw, "_metal_recommended_working_set_bytes", working_set),
+ ):
+ info = hw._probe_backend_visible_gpu_info(DeviceType.MLX)
+ assert info["available"] is True
+ (device,) = info["devices"]
+ return device
+
+
+def test_mlx_device_reports_metal_working_set():
+ device = _mlx_device(lambda: int(51.84 * 1024**3))
+ assert device["metal_working_set_gb"] == pytest.approx(51.84)
+ assert device["memory_total_gb"] == 64.0
+ assert device["shared_memory"] is True
+
+
[email protected]("value", [0, None])
+def test_mlx_device_working_set_unknown_is_none(value):
+ assert _mlx_device(lambda: value)["metal_working_set_gb"] is None
+
+
+def test_mlx_device_working_set_probe_failure_is_none():
+ def boom():
+ raise RuntimeError("no metal")
+
+ device = _mlx_device(boom)
+ assert device["metal_working_set_gb"] is None
+ assert device["memory_total_gb"] == 64.0
diff --git a/studio/backend/utils/hardware/hardware.py b/studio/backend/utils/hardware/hardware.py
index e2cc9d543ec..d63acb30904 100644
--- a/studio/backend/utils/hardware/hardware.py
+++ b/studio/backend/utils/hardware/hardware.py
@@ -7209,6 +7209,14 @@ def _probe_backend_visible_gpu_info(device) -> Dict[str, Any]:
"index_kind": "relative",
}
memory_total_gb = round(mem.get("total_gb", 0), 2)
+ # The loader budgets min(this, available) * 0.85, not total RAM; the picker flags tight GGUFs with it.
+ try:
+ working_set_bytes = int(_metal_recommended_working_set_bytes() or 0)
+ except Exception:
+ working_set_bytes = 0
+ metal_working_set_gb = (
+ round(working_set_bytes / (1024**3), 2) if working_set_bytes > 0 else None
+ )
return {
"available": True,
"backend": _backend_label(device),
@@ -7223,6 +7231,7 @@ def _probe_backend_visible_gpu_info(device) -> Dict[str, Any]:
"memory_total_gb": memory_total_gb,
"shared_memory": True,
"shared_memory_host_backed_gb": memory_total_gb,
+ "metal_working_set_gb": metal_working_set_gb,
}
],
"index_kind": "relative",
diff --git a/studio/frontend/scripts/check-bundle-budget.ts b/studio/frontend/scripts/check-bundle-budget.ts
index 3e75b03b1c2..2112d24d7a9 100644
--- a/studio/frontend/scripts/check-bundle-budget.ts
+++ b/studio/frontend/scripts/check-bundle-budget.ts
@@ -381,8 +381,10 @@ export const BUDGET = {
// 2,080,708 B transfer (Node 26, 98 chunks). Raised to that plus about 200 B.
// Settings API / Remote / LAN strings (#14596) merged with main at 870f37741: 6,907,886 B raw / 2,080,818 B
// transfer (Node 26, 98 chunks). Raised to that plus about 200 B.
- transferBytes: 2_081_018,
- rawBytes: 6_908_086,
+ // Apple unified-memory fit hint (#14598) merged with main at a29487c52: 6,909,320 B raw / 2,081,284 B
+ // transfer (Node 26, 98 chunks). Raised to that plus about 200 B.
+ transferBytes: 2_081_484,
+ rawBytes: 6_909_520,
};
// The chunk count is reported but not budgeted. Splitting a page out of the entry raises it while lowering the
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 ed852b34397..4dab3abbe4e 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
@@ -1307,6 +1307,8 @@ export interface DeviceBudget {
budgetFraction?: number;
/** GPUs gpuGb sums, for the loader's per-card VRAM reserve. Absent means one. */
gpuCount?: number;
+ /** Apple MLX loader budget (`GpuInfo.unifiedLoadBudgetGb`); past it a GGUF reads `marginal`. */
+ unifiedLoadBudgetGb?: number | null;
/** Dense quant schemes this host runs, best first; empty keeps the bf16 sizing rule. */
denseQuantSchemes?: readonly string[];
/** Group offload can stream torchao weights; absent = unknown, so streamed tiers are not offered. */
@@ -1345,7 +1347,8 @@ export function classifyGgufFit(
/** Fit rule for a GGUF the IMAGES / VIDEO / AUDIO pickers offer, the one case the shared llama.cpp
* formula must not judge: those loads go through the diffusion backend, which cannot offload and
* budgets free memory minus a reserve at a 0.85 margin (`diffusion_memory.py`). On a 64 GiB Mac
- * that planner allows ~43.5 GiB, llama.cpp 62.1 and this rule 44.8: not the planner, just closer. */
+ * that planner allows ~43.5 GiB and this rule 44.8: not the planner, just closer. The llama.cpp
+ * rule's 62.1 is total RAM; its loader caps at `min(working set, free) * 0.85`, ~44 at best. */
export function classifyMediaGgufFit(
sizeBytes: number,
gpuGb: number,
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 e69185201c0..b4383211792 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
@@ -145,6 +145,7 @@ import {
Settings02Icon,
ViewIcon,
} from "@hugeicons/core-free-icons";
+import { useT } from "@/i18n";
import { AiSpeechIcon } from "@/lib/hugeicons-derived";
import { HugeiconsIcon } from "@hugeicons/react";
import { useNavigate } from "@tanstack/react-router";
@@ -166,6 +167,7 @@ import {
} from "react";
import {
audioCppHubPath,
+ audioCppModelFor,
isAudioCppFolderId,
} from "../../../audio/audio-cpp-catalog.ts";
import { audioPickSearch } from "../../../audio/route-search.ts";
@@ -605,6 +607,34 @@ const CapabilityScope = createContext<readonly (keyof ModelCapabilities)[] | nul
null,
);
+/** `GpuInfo.unifiedLoadBudgetGb` of the inventory GGUF chat loads into: non-null only on an Apple
+ * MLX host, where `marginal` means past the loader's unified budget rather than the VRAM Budget. */
+const UnifiedLoadBudget = createContext<number | null>(null);
+
+/** audio.cpp GGUFs load through the audio runtime, not under llama.cpp's Metal budget; Mac TTS
+ * GGUFs (Orpheus and the like) do load through llama.cpp, so the Audio task alone decides nothing. */
+function loadsOnAudioCpp(repoId: string): boolean {
+ return audioCppModelFor(repoId) !== null || isAudioCppFolderId(repoId);
+}
+
+function PickerScopes({
+ capabilityScope,
+ unifiedLoadBudgetGb,
+ children,
+}: {
+ capabilityScope: readonly (keyof ModelCapabilities)[] | null;
+ unifiedLoadBudgetGb: number | null;
+ children: ReactNode;
+}) {
+ return (
+ <CapabilityScope.Provider value={capabilityScope}>
+ <UnifiedLoadBudget.Provider value={unifiedLoadBudgetGb}>
+ {children}
+ </UnifiedLoadBudget.Provider>
+ </CapabilityScope.Provider>
+ );
+}
+
// The row reserves a fixed slot for these (META_COLUMN.badge), so the cap is what keeps every column after it lined up.
const MAX_CAPABILITY_BADGES = 3;
@@ -849,7 +879,18 @@ function VramBadge({
status?: GgufFitClass | VramFitStatus | null;
revealOnHover?: boolean;
}) {
- const verdict = status ? VRAM_VERDICT[status] : null;
+ const t = useT();
+ const unifiedLoadBudgetGb = useContext(UnifiedLoadBudget);
+ const verdict =
+ status === "marginal" && unifiedLoadBudgetGb !== null
+ ? {
+ label: t("picker.unifiedTightFit"),
+ tone: AMBER,
+ hint: t("picker.unifiedTightFitHint"),
+ }
+ : status
+ ? VRAM_VERDICT[status]
+ : null;
if (!verdict) return null;
return (
<Tooltip delayDuration={0}>
@@ -1962,6 +2003,10 @@ function GgufVariantExpander({
const [defaultVariant, setDefaultVariant] = useState<string | null>(null);
const [hasVision, setHasVision] = useState<boolean | undefined>(undefined);
const capabilityScope = useContext(CapabilityScope);
+ // Diffusion loads never read it; keeping it out stops memory drift from re-planning downloads.
+ const chatLoadBudgetGb = useContext(UnifiedLoadBudget);
+ const unifiedLoadBudgetGb =
+ diffusionLoad || loadsOnAudioCpp(repoId) ? null : chatLoadBudgetGb;
const visionInScope =
capabilityScope === null || capabilityScope.includes("vision");
const showVision = hasVision === true && visionInScope;
@@ -2130,6 +2175,7 @@ function GgufVariantExpander({
systemRamGb: systemRamGb ?? 0,
budgetFraction,
gpuCount,
+ unifiedLoadBudgetGb,
});
},
[
@@ -2138,6 +2184,7 @@ function GgufVariantExpander({
gpuGb,
systemRamGb,
budgetFraction,
+ unifiedLoadBudgetGb,
diffusionLoad,
hostPooledMemory,
gpuCount,
@@ -3171,6 +3218,14 @@ export function HubModelPicker({
? selectedCheckpoint
: undefined;
const loadedModelId = loadedModelIdOverride ?? chatLoadedModelId;
+ // The loader frees the resident model before reading free memory, so only the ceiling holds then.
+ // Not chatModelLoaded: it counts a remote API model, which frees nothing. Keep-loaded mode may
+ // leave the resident beside the new load, so the live budget stays in force there.
+ const keepModelsLoaded = useChatRuntimeStore((s) => s.keepModelsLoaded);
+ const loadFreesResident =
+ !keepModelsLoaded &&
+ typeof residentCheckpoint === "string" &&
+ residentCheckpoint !== "";
// Loaded GGUF quant of the active model; marks the matching pinned row.
const storeGgufVariant = useChatRuntimeStore((s) => s.activeGgufVariant);
const activeGgufVariant =
@@ -4198,6 +4253,7 @@ export function HubModelPicker({
const ggufRowFit = (
sizeBytes: number | undefined,
budget: typeof inferenceGpu,
+ repoId: string,
): GgufFitClass | VramFitStatus | null => {
const anyBudget =
budget.memoryTotalGb > 0 || budget.systemRamAvailableGb > 0;
@@ -4221,6 +4277,11 @@ export function HubModelPicker({
systemRamGb: budget.systemRamAvailableGb,
budgetFraction,
gpuCount: budget.deviceCount,
+ unifiedLoadBudgetGb: loadsOnAudioCpp(repoId)
+ ? null
+ : loadFreesResident
+ ? budget.unifiedLoadCeilingGb
+ : budget.unifiedLoadBudgetGb,
});
if (fit === "fits") return null;
return diffusionRefuses(fit, diffusionLoad, gpu.loadDeviceSharesHostMemory)
@@ -4279,7 +4340,7 @@ export function HubModelPicker({
// The classifier's own verdict, so a GGUF row never borrows the torch-only "exceeds", scoped
// to the device the load LANDS on: unscoped, a downloaded media parent read as safe while
// every variant inside it read as oom.
- status: ggufRowFit(sizeBytes, rowInferenceGpu),
+ status: ggufRowFit(sizeBytes, rowInferenceGpu, r.id),
// The figure the verdict was reached with, not the raw file size: classifyGgufFit scores
// weights plus activations and KV, so a 20 GiB quant needing 24 GiB read "tight fit" beside
// "~20GB VRAM". The media rule scores the raw size and keeps it.
@@ -4325,6 +4386,7 @@ export function HubModelPicker({
isKnownGgufRepo,
gpu,
inferenceGpu,
+ loadFreesResident,
]);
// Hub pipeline tag per repo id, handed to the page on pick so a task page can classify an uncurated repo.
@@ -7312,7 +7374,14 @@ export function HubModelPicker({
(!showHfSection || npuBrowseRows.length > 0);
return (
- <CapabilityScope.Provider value={capabilityScope}>
+ <PickerScopes
+ capabilityScope={capabilityScope}
+ unifiedLoadBudgetGb={
+ (loadFreesResident
+ ? inferenceGpu.unifiedLoadCeilingGb
+ : inferenceGpu.unifiedLoadBudgetGb) ?? null
+ }
+ >
<div className="relative space-y-2">
{/* A small right inset shortens the search bar so Search Hub lands on the last dropdown's right edge. */}
<div
@@ -8950,7 +9019,7 @@ export function HubModelPicker({
reasoningConfig={infoModel.reasoningConfig}
/>
) : null}
- </CapabilityScope.Provider>
+ </PickerScopes>
);
}
diff --git a/studio/frontend/src/hooks/use-gpu-info.ts b/studio/frontend/src/hooks/use-gpu-info.ts
index 5e3e2d0fa4a..d788bf30a1a 100644
--- a/studio/frontend/src/hooks/use-gpu-info.ts
+++ b/studio/frontend/src/hooks/use-gpu-info.ts
@@ -24,6 +24,7 @@ import {
systemRamAvailableOutsideSharedPoolGb,
} from "./gpu-vram";
import {
+ type GpuDevice,
type SystemInfoResponse,
fetchSystemInfo,
getCachedSystemInfo,
@@ -93,6 +94,55 @@ export interface GpuInfo {
/** Whether host available memory was reported, including a real zero. */
systemRamAvailableKnown?: boolean;
systemRamTotalGb: number;
+ /** Apple MLX only: what llama.cpp and MLX admit right now, `min(working set, free) * 0.85`
+ * (`_apple_metal_memory_budget_bytes`). Null on every other host and on older backends. */
+ unifiedLoadBudgetGb?: number | null;
+ /** `min(working set, free + AGX in use) * 0.85`: the budget once the loader has freed a resident model. */
+ unifiedLoadCeilingGb?: number | null;
+}
+
+/** `_APPLE_UNIFIED_MEMORY_FRACTION` in llama_cpp.py and mlx_inference.py. */
+const APPLE_UNIFIED_MEMORY_FRACTION = 0.85;
+
+function finitePositive(value: number | null | undefined): number | null {
+ return typeof value === "number" && Number.isFinite(value) && value > 0
+ ? value
+ : null;
+}
+
+// A real 0 GiB free reading is the most pressured case, so it must not read as unknown.
+function finiteNonNegative(value: number | null | undefined): number | null {
+ return typeof value === "number" && Number.isFinite(value) && value >= 0
+ ? value
+ : null;
+}
+
+function appleUnifiedLoadBudgetGb(
+ data: SystemInfoResponse | null,
+ devices: readonly GpuDevice[],
+ afterUnload = false,
+): number | null {
+ if (data?.device_backend !== "mlx" || devices.length !== 1) return null;
+ const device = devices[0];
+ const workingSetGb = finitePositive(device.metal_working_set_gb);
+ if (device.shared_memory !== true || workingSetGb === null) return null;
+ let freeGb =
+ finiteNonNegative(device.vram_free_gb) ??
+ finiteNonNegative(data.memory?.available_gb);
+ if (afterUnload) {
+ // The AGX in-use figure holds the resident model's Metal buffers, which the loader frees first;
+ // other apps' memory stays counted. Unknown usage leaves only the working-set ceiling.
+ const usedGb = finiteNonNegative(device.vram_used_gb);
+ freeGb = freeGb !== null && usedGb !== null ? freeGb + usedGb : null;
+ }
+ // Floored to 0.25 GiB: free memory drifts every poll, and each change re-renders every picker row.
+ return (
+ Math.floor(
+ Math.min(workingSetGb, freeGb ?? workingSetGb) *
+ APPLE_UNIFIED_MEMORY_FRACTION *
+ 4,
+ ) / 4
+ );
}
const DEFAULT_GPU: GpuInfo = {
@@ -121,6 +171,8 @@ const DEFAULT_GPU: GpuInfo = {
systemRamAvailableHostGb: 0,
systemRamAvailableKnown: false,
systemRamTotalGb: 0,
+ unifiedLoadBudgetGb: null,
+ unifiedLoadCeilingGb: null,
};
function toGpuInfo(
@@ -190,6 +242,8 @@ function toGpuInfo(
unifiedMemory: loadDevice?.unified_memory === true,
}),
deviceCount: devices.length,
+ unifiedLoadBudgetGb: appleUnifiedLoadBudgetGb(data, devices),
+ unifiedLoadCeilingGb: appleUnifiedLoadBudgetGb(data, devices, true),
};
}
diff --git a/studio/frontend/src/hooks/use-system.ts b/studio/frontend/src/hooks/use-system.ts
index f42de00879d..30ba5f0c2e4 100644
--- a/studio/frontend/src/hooks/use-system.ts
+++ b/studio/frontend/src/hooks/use-system.ts
@@ -28,6 +28,8 @@ export interface GpuDevice {
unified_memory?: boolean;
/** host-backed portion of the shared pool; the rest is reserved GPU memory. */
shared_memory_host_backed_gb?: number | null;
+ /** Apple MLX only: Metal's recommendedMaxWorkingSetSize. Absent elsewhere and on older backends. */
+ metal_working_set_gb?: number | null;
/** Live readings from the same probe as vram_used_gb; absent where the backend has none. */
gpu_utilization_pct?: number | null;
temperature_c?: number | null;
diff --git a/studio/frontend/src/i18n/locales/ar.ts b/studio/frontend/src/i18n/locales/ar.ts
index 81f7cef59b0..07c4d160269 100644
--- a/studio/frontend/src/i18n/locales/ar.ts
+++ b/studio/frontend/src/i18n/locales/ar.ts
@@ -625,6 +625,8 @@ export const ar = {
temporaryChatDescription: "لن تظهر هذه الدردشة في سجلك ولن تُحفظ. ستختفي عند مغادرتك.",
},
picker: {
+ unifiedTightFit: "ملاءمة محدودة",
+ unifiedTightFitHint: "قد يُحمَّل بسياق أقصر أو يعمل بشكل أبطأ على جهاز Mac هذا.",
onDevice: "على الجهاز",
huggingFace: "Hugging Face",
retry: "إعادة المحاولة",
diff --git a/studio/frontend/src/i18n/locales/de.ts b/studio/frontend/src/i18n/locales/de.ts
index b9dbfe3a4fe..e03269f7ac4 100644
--- a/studio/frontend/src/i18n/locales/de.ts
+++ b/studio/frontend/src/i18n/locales/de.ts
@@ -626,6 +626,8 @@ export const de = {
"Dieser Chat erscheint nicht in deinem Verlauf und wird nicht gespeichert. Er verschwindet, wenn du ihn verlässt.",
},
picker: {
+ unifiedTightFit: "Knapp",
+ unifiedTightFitHint: "Lädt auf diesem Mac eventuell nur mit kürzerem Kontext oder läuft langsamer.",
onDevice: "Auf dem Gerät",
huggingFace: "Hugging Face",
retry: "Erneut versuchen",
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index 5b743f62694..9679a5a8f02 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -679,6 +679,8 @@ export const en = {
"This chat won't appear in your history and isn't saved. It disappears when you leave.",
},
picker: {
+ unifiedTightFit: "Tight fit",
+ unifiedTightFitHint: "May load with a shorter context or run slower on this Mac.",
onDevice: "On Device",
huggingFace: "Hugging Face",
retry: "Retry",
diff --git a/studio/frontend/src/i18n/locales/es.ts b/studio/frontend/src/i18n/locales/es.ts
index afb6ceb4527..80dec1a03ca 100644
--- a/studio/frontend/src/i18n/locales/es.ts
+++ b/studio/frontend/src/i18n/locales/es.ts
@@ -626,6 +626,8 @@ export const es = {
"Este chat no aparecerá en tu historial ni se guardará. Desaparece cuando salgas.",
},
picker: {
+ unifiedTightFit: "Ajuste justo",
+ unifiedTightFitHint: "Puede cargarse con un contexto más corto o ir más lento en este Mac.",
onDevice: "En el dispositivo",
huggingFace: "Hugging Face",
retry: "Reintentar",
diff --git a/studio/frontend/src/i18n/locales/fr.ts b/studio/frontend/src/i18n/locales/fr.ts
index 88725dee20c..2b9ed410d6b 100644
--- a/studio/frontend/src/i18n/locales/fr.ts
+++ b/studio/frontend/src/i18n/locales/fr.ts
@@ -626,6 +626,8 @@ export const fr = {
"Ce chat n’apparaîtra pas dans votre historique et n’est pas enregistré. Il disparaît quand vous le quittez.",
},
picker: {
+ unifiedTightFit: "Juste",
+ unifiedTightFitHint: "Peut se charger avec un contexte plus court ou être plus lent sur ce Mac.",
onDevice: "Sur l'appareil",
huggingFace: "Hugging Face",
retry: "Réessayer",
diff --git a/studio/frontend/src/i18n/locales/he.ts b/studio/frontend/src/i18n/locales/he.ts
index 1f920f21ced..5a9c1952380 100644
--- a/studio/frontend/src/i18n/locales/he.ts
+++ b/studio/frontend/src/i18n/locales/he.ts
@@ -711,6 +711,8 @@ export const he = {
temporaryChatDescription: "הצ'אט הזה לא יופיע בהיסטוריה שלך ולא נשמר. הוא נעלם כשתעזוב.",
},
picker: {
+ unifiedTightFit: "התאמה צפופה",
+ unifiedTightFitHint: "ייתכן שייטען עם הקשר קצר יותר או ירוץ לאט יותר ב-Mac הזה.",
onDevice: "במכשיר",
huggingFace: "Hugging Face",
retry: "נסה שוב",
diff --git a/studio/frontend/src/i18n/locales/hi.ts b/studio/frontend/src/i18n/locales/hi.ts
index d85f7e355ab..36701063311 100644
--- a/studio/frontend/src/i18n/locales/hi.ts
+++ b/studio/frontend/src/i18n/locales/hi.ts
@@ -626,6 +626,8 @@ export const hi = {
"यह चैट आपके इतिहास में नहीं दिखेगी और सेव नहीं होती। आपके जाने पर यह गायब हो जाती है।",
},
picker: {
+ unifiedTightFit: "तंग फ़िट",
+ unifiedTightFitHint: "इस Mac पर छोटे कॉन्टेक्स्ट के साथ लोड हो सकता है या धीमा चल सकता है।",
onDevice: "डिवाइस पर",
huggingFace: "Hugging Face",
retry: "पुनः प्रयास करें",
diff --git a/studio/frontend/src/i18n/locales/it.ts b/studio/frontend/src/i18n/locales/it.ts
index 38932252d20..855f9a83ec8 100644
--- a/studio/frontend/src/i18n/locales/it.ts
+++ b/studio/frontend/src/i18n/locales/it.ts
@@ -3361,6 +3361,8 @@ export const it = {
"Questa chat non comparirà nella cronologia e non viene salvata. Scompare quando esci.",
},
picker: {
+ unifiedTightFit: "Al limite",
+ unifiedTightFitHint: "Su questo Mac potrebbe caricarsi con un contesto più breve o essere più lento.",
onDevice: "Sul dispositivo",
huggingFace: "Hugging Face",
retry: "Riprova",
diff --git a/studio/frontend/src/i18n/locales/ja.ts b/studio/frontend/src/i18n/locales/ja.ts
index 37213c8a1f6..8502946a75f 100644
--- a/studio/frontend/src/i18n/locales/ja.ts
+++ b/studio/frontend/src/i18n/locales/ja.ts
@@ -626,6 +626,8 @@ export const ja = {
temporaryChatDescription: "このチャットは履歴に表示されず、保存されません。離れると消えます。",
},
picker: {
+ unifiedTightFit: "ぎりぎり",
+ unifiedTightFitHint: "この Mac では短いコンテキストで読み込まれるか、動作が遅くなる可能性があります。",
onDevice: "デバイス上",
huggingFace: "Hugging Face",
retry: "再試行",
diff --git a/studio/frontend/src/i18n/locales/ko.ts b/studio/frontend/src/i18n/locales/ko.ts
index 1ff4ea31cee..5967f442394 100644
--- a/studio/frontend/src/i18n/locales/ko.ts
+++ b/studio/frontend/src/i18n/locales/ko.ts
@@ -625,6 +625,8 @@ export const ko = {
temporaryChatDescription: "이 채팅은 기록에 표시되지 않으며 저장되지 않습니다. 나가면 사라집니다.",
},
picker: {
+ unifiedTightFit: "빠듯함",
+ unifiedTightFitHint: "이 Mac에서는 더 짧은 컨텍스트로 로드되거나 느리게 실행될 수 있습니다.",
onDevice: "기기",
huggingFace: "Hugging Face",
retry: "다시 시도",
diff --git a/studio/frontend/src/i18n/locales/pt-br.ts b/studio/frontend/src/i18n/locales/pt-br.ts
index eb480f05dc5..8cddafaa8f1 100644
--- a/studio/frontend/src/i18n/locales/pt-br.ts
+++ b/studio/frontend/src/i18n/locales/pt-br.ts
@@ -626,6 +626,8 @@ export const ptBR = {
"Este chat não aparecerá no seu histórico e não será salvo. Ele desaparece quando você sair.",
},
picker: {
+ unifiedTightFit: "Ajuste apertado",
+ unifiedTightFitHint: "Pode carregar com um contexto menor ou rodar mais devagar neste Mac.",
onDevice: "No dispositivo",
huggingFace: "Hugging Face",
retry: "Tentar novamente",
diff --git a/studio/frontend/src/i18n/locales/ru.ts b/studio/frontend/src/i18n/locales/ru.ts
index b883a6543f8..4a4fd5d699f 100644
--- a/studio/frontend/src/i18n/locales/ru.ts
+++ b/studio/frontend/src/i18n/locales/ru.ts
@@ -626,6 +626,8 @@ export const ru = {
"Этот чат не появится в истории и не сохраняется. Он исчезнет, когда вы уйдёте.",
},
picker: {
+ unifiedTightFit: "Впритык",
+ unifiedTightFitHint: "На этом Mac может загрузиться с более коротким контекстом или работать медленнее.",
onDevice: "На устройстве",
huggingFace: "Hugging Face",
retry: "Повторить",
diff --git a/studio/frontend/src/i18n/locales/sv.ts b/studio/frontend/src/i18n/locales/sv.ts
index 8dc41933afe..3f730a1ead4 100644
--- a/studio/frontend/src/i18n/locales/sv.ts
+++ b/studio/frontend/src/i18n/locales/sv.ts
@@ -728,6 +728,8 @@ export const sv = {
"Den här chatten visas inte i din historik och sparas inte. Den försvinner när du lämnar den.",
},
picker: {
+ unifiedTightFit: "Snäv passform",
+ unifiedTightFitHint: "Kan laddas med kortare kontext eller köras långsammare på den här Macen.",
onDevice: "På enheten",
huggingFace: "Hugging Face",
retry: "Försök igen",
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
index faa93a0f681..fdc51620a4c 100644
--- a/studio/frontend/src/i18n/locales/zh-CN.ts
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -625,6 +625,8 @@ export const zhCN = {
temporaryChatDescription: "此聊天不会出现在你的历史记录中,也不会被保存。离开后即消失。",
},
picker: {
+ unifiedTightFit: "勉强可用",
+ unifiedTightFitHint: "在这台 Mac 上可能以更短的上下文加载,或运行更慢。",
onDevice: "本机",
huggingFace: "Hugging Face",
retry: "重试",
diff --git a/studio/frontend/src/lib/gguf-fit.ts b/studio/frontend/src/lib/gguf-fit.ts
index 0b58f9e113e..16589f8f266 100644
--- a/studio/frontend/src/lib/gguf-fit.ts
+++ b/studio/frontend/src/lib/gguf-fit.ts
@@ -29,6 +29,8 @@ export interface GgufFitInput {
* above the default budget; absent means one card, which is what every verdict
* scored against before it existed. */
gpuCount?: number;
+ /** Apple MLX loader budget (`GpuInfo.unifiedLoadBudgetGb`): past it, `fits` becomes `marginal`. */
+ unifiedLoadBudgetGb?: number | null;
}
/** Fraction of GPU VRAM treated as usable.
@@ -68,7 +70,13 @@ export function requiredGgufMemoryGb(
export function classifyGgufFit(
sizeBytes: number,
- { gpuGb, systemRamGb, budgetFraction, gpuCount }: GgufFitInput,
+ {
+ gpuGb,
+ systemRamGb,
+ budgetFraction,
+ gpuCount,
+ unifiedLoadBudgetGb,
+ }: GgufFitInput,
): GgufFitClass {
const required = requiredGgufMemoryGb(sizeBytes);
if (!gpuGb || gpuGb <= 0) {
@@ -105,7 +113,14 @@ export function classifyGgufFit(
(1 - DEFAULT_VRAM_BUDGET_FRACTION) * (gpuGb / cards),
);
const budget = gpuGb - Math.max((1 - fraction) * gpuGb, reserveFloorGb);
- if (required <= budget) return "fits";
+ if (required <= budget) {
+ // A warning, not a refusal: llama.cpp still loads it with a shorter context or slower.
+ return typeof unifiedLoadBudgetGb === "number" &&
+ unifiedLoadBudgetGb >= 0 &&
+ required > unifiedLoadBudgetGb
+ ? "marginal"
+ : "fits";
+ }
// Raw card, deliberately. This band means "over your budget, still card-sized", which is the only
// thing that distinguishes it from `fits`: scoring it against `budget` too would make it
// unreachable, since `required <= budget` has already returned above. It is a warning tier, not a
diff --git a/studio/frontend/tests/apple-unified-gguf-fit.test.ts b/studio/frontend/tests/apple-unified-gguf-fit.test.ts
new file mode 100644
index 00000000000..62470fbbd05
--- /dev/null
+++ b/studio/frontend/tests/apple-unified-gguf-fit.test.ts
@@ -0,0 +1,233 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// The picker's GGUF badge on an Apple host pool: total RAM is not what llama.cpp admits, the
+// loader's `min(working set, free) * 0.85` is. Past it a quant warns instead of reading `fits`.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import type * as GpuHooks from "../src/hooks/use-gpu-info.ts";
+import { classifyGgufFit } from "../src/lib/gguf-fit.ts";
+import { normalizeDenseQuantSchemes } from "../src/lib/dense-quant-schemes.ts";
+import { normalizeReportedOffloadFitTiers } from "../src/lib/offload-fit-tiers.ts";
+import { loadWithStubs } from "./helpers/module-stubs.ts";
+
+const GiB = 1024 ** 3;
+
+let snapshot: unknown = null;
+const hooks = loadWithStubs<typeof GpuHooks>(
+ new URL("../src/hooks/use-gpu-info.ts", import.meta.url),
+ {
+ react: {
+ useState: (initial: unknown) => [
+ typeof initial === "function" ? initial() : initial,
+ () => {},
+ ],
+ useEffect: () => {},
+ useMemo: (read: () => unknown) => read(),
+ },
+ "./use-system": { getCachedSystemInfo: () => snapshot },
+ "@/lib/dense-quant-schemes": { normalizeDenseQuantSchemes },
+ "@/lib/offload-fit-tiers": { normalizeReportedOffloadFitTiers },
+ },
+ { relativePassthrough: true },
+);
+
+/** Bytes whose `requiredGgufMemoryGb` (size * 1.15 + 1) is exactly `requiredGb`. */
+const bytesRequiring = (requiredGb: number) => ((requiredGb - 1) / 1.15) * GiB;
+
+function macInfo(device: Record<string, unknown>, availableGb = 25) {
+ const gpu = {
+ available: true,
+ backend: "mlx",
+ devices: [
+ {
+ index: 0,
+ index_kind: "relative",
+ name: "Apple M3 Max",
+ memory_total_gb: 64,
+ shared_memory: true,
+ shared_memory_host_backed_gb: 64,
+ ...device,
+ },
+ ],
+ };
+ snapshot = {
+ status: "ready",
+ device_backend: "mlx",
+ gpu,
+ inference_gpu: gpu,
+ memory: { total_gb: 64, available_gb: availableGb },
+ };
+ return hooks.useInferenceGpuInfo();
+}
+
+function fitOn(gpu: ReturnType<typeof macInfo>, requiredGb: number) {
+ return classifyGgufFit(bytesRequiring(requiredGb), {
+ gpuGb: gpu.memoryTotalGb,
+ systemRamGb: gpu.systemRamAvailableGb,
+ gpuCount: gpu.deviceCount,
+ unifiedLoadBudgetGb: gpu.unifiedLoadBudgetGb,
+ });
+}
+
+test("an Apple host pool publishes min(working set, free) * 0.85, floored to 0.25 GiB, as its load budget", () => {
+ const gpu = macInfo({ metal_working_set_gb: 51.84, vram_free_gb: 22 });
+ assert.equal(gpu.memoryTotalGb, 64);
+ assert.ok(
+ Math.abs((gpu.unifiedLoadBudgetGb ?? 0) - Math.floor(22 * 0.85 * 4) / 4) <
+ 1e-9,
+ );
+ // Idle Mac: the working set binds.
+ const idle = macInfo({ metal_working_set_gb: 51.84, vram_free_gb: 60 });
+ assert.ok(
+ Math.abs(
+ (idle.unifiedLoadBudgetGb ?? 0) - Math.floor(51.84 * 0.85 * 4) / 4,
+ ) < 1e-9,
+ );
+ // No device free figure: the host's available RAM stands in.
+ const noFree = macInfo({ metal_working_set_gb: 51.84 }, 30);
+ assert.ok(
+ Math.abs(
+ (noFree.unifiedLoadBudgetGb ?? 0) - Math.floor(30 * 0.85 * 4) / 4,
+ ) < 1e-9,
+ );
+});
+
+test("the ceiling ignores free memory, which a resident model the loader frees still holds", () => {
+ // 20 GiB model resident: 22 GiB reads free, but the loader sees ~42 once it has freed it.
+ const gpu = macInfo({ metal_working_set_gb: 51.84, vram_free_gb: 22 });
+ assert.ok(
+ Math.abs(
+ (gpu.unifiedLoadCeilingGb ?? 0) - Math.floor(51.84 * 0.85 * 4) / 4,
+ ) < 1e-9,
+ );
+ const reloaded = classifyGgufFit(bytesRequiring(22.2), {
+ gpuGb: gpu.memoryTotalGb,
+ systemRamGb: gpu.systemRamAvailableGb,
+ gpuCount: gpu.deviceCount,
+ unifiedLoadBudgetGb: gpu.unifiedLoadCeilingGb,
+ });
+ assert.equal(reloaded, "fits");
+});
+
+test("an older backend without the working set keeps today's verdicts", () => {
+ for (const ws of [undefined, null, 0, -1, Number.NaN]) {
+ const gpu = macInfo({ metal_working_set_gb: ws, vram_free_gb: 22 });
+ assert.equal(gpu.unifiedLoadBudgetGb, null);
+ assert.equal(gpu.unifiedLoadCeilingGb, null);
+ }
+});
+
+test("64 GiB Mac, 51.84 GiB working set, 22 GiB free", () => {
+ const gpu = macInfo({ metal_working_set_gb: 51.84, vram_free_gb: 22 });
+ const today = (requiredGb: number) =>
+ classifyGgufFit(bytesRequiring(requiredGb), {
+ gpuGb: gpu.memoryTotalGb,
+ systemRamGb: gpu.systemRamAvailableGb,
+ gpuCount: gpu.deviceCount,
+ });
+ // Inside today's total-RAM budget but past the loader's: a warning, never a refusal.
+ assert.equal(today(22.2), "fits");
+ assert.equal(fitOn(gpu, 22.2), "marginal");
+ assert.equal(fitOn(gpu, 15), "fits");
+ assert.equal(fitOn(gpu, 63.5), today(63.5));
+ assert.equal(fitOn(gpu, 63.5), "marginal");
+ assert.equal(fitOn(gpu, 200), today(200));
+});
+
+test("discrete NVIDIA 24 GiB is untouched", () => {
+ snapshot = {
+ status: "ready",
+ device_backend: "cuda",
+ gpu: {
+ available: true,
+ backend: "cuda",
+ devices: [
+ {
+ index: 0,
+ index_kind: "physical",
+ memory_total_gb: 24,
+ vram_free_gb: 4,
+ // Never honoured off Apple, even if a future backend sent it.
+ metal_working_set_gb: 10,
+ },
+ ],
+ },
+ memory: { total_gb: 64, available_gb: 48 },
+ };
+ const gpu = hooks.useInferenceGpuInfo();
+ assert.equal(gpu.unifiedLoadBudgetGb, null);
+ assert.equal(gpu.unifiedLoadCeilingGb, null);
+ for (const requiredGb of [10, 22.2, 23.5, 40, 200]) {
+ assert.equal(
+ fitOn(gpu, requiredGb),
+ classifyGgufFit(bytesRequiring(requiredGb), {
+ gpuGb: 24,
+ systemRamGb: gpu.systemRamAvailableGb,
+ gpuCount: 1,
+ }),
+ );
+ }
+ assert.equal(fitOn(gpu, 22.2), "fits");
+});
+
+test("a loader budget floored to zero still warns rather than reading as unknown", () => {
+ const fit = classifyGgufFit(bytesRequiring(10), {
+ gpuGb: 64,
+ systemRamGb: 0,
+ unifiedLoadBudgetGb: 0,
+ });
+ assert.equal(fit, "marginal");
+});
+
+test("keep-loaded mode keeps the live budget: the resident may stay beside the new load", async () => {
+ const { readFileSync } = await import("node:fs");
+ const src = readFileSync(
+ new URL(
+ "../src/features/model-picker/components/model-selector/pickers.tsx",
+ import.meta.url,
+ ),
+ "utf8",
+ );
+ assert.match(
+ src,
+ /const loadFreesResident =\s*!keepModelsLoaded &&\s*typeof residentCheckpoint === "string"/,
+ );
+ assert.equal(src.match(/loadFreesResident\s*\?/g)?.length, 2);
+});
+
+test("after unload the budget gains the resident's AGX memory, not every app's", () => {
+ // 20 GiB resident in AGX: the loader sees 22 + 20 = 42 GiB once it frees it.
+ const resident = macInfo({ metal_working_set_gb: 51.84, vram_free_gb: 22, vram_used_gb: 20 });
+ assert.equal(resident.unifiedLoadCeilingGb, Math.floor(42 * 0.85 * 4) / 4);
+ // 5 GiB resident, 25 GiB held by other apps: only 10 + 5 GiB returns, so 22.2 GiB stays tight.
+ const pressured = macInfo({ metal_working_set_gb: 51.84, vram_free_gb: 10, vram_used_gb: 5 });
+ assert.equal(pressured.unifiedLoadCeilingGb, Math.floor(15 * 0.85 * 4) / 4);
+ const fit = classifyGgufFit(bytesRequiring(22.2), {
+ gpuGb: pressured.memoryTotalGb,
+ systemRamGb: pressured.systemRamAvailableGb,
+ gpuCount: pressured.deviceCount,
+ unifiedLoadBudgetGb: pressured.unifiedLoadCeilingGb,
+ });
+ assert.equal(fit, "marginal");
+});
+
+test("a 0 GiB free reading is the tightest budget, not an unknown one", () => {
+ const gpu = macInfo({ metal_working_set_gb: 51.84, vram_free_gb: 0 });
+ assert.equal(gpu.unifiedLoadBudgetGb, 0);
+});
+
+test("only audio.cpp GGUFs skip the llama.cpp budget; Mac TTS GGUFs load through llama.cpp", async () => {
+ const { readFileSync } = await import("node:fs");
+ const src = readFileSync(
+ new URL(
+ "../src/features/model-picker/components/model-selector/pickers.tsx",
+ import.meta.url,
+ ),
+ "utf8",
+ );
+ assert.match(src, /unifiedLoadBudgetGb: loadsOnAudioCpp\(repoId\)\s*\?\s*null/);
+ assert.match(src, /diffusionLoad \|\| loadsOnAudioCpp\(repoId\) \? null : chatLoadBudgetGb/);
+ assert.doesNotMatch(src, /unifiedLoadBudgetGb: audioTaskPicker/);
+});
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 819f66bb5ba..2bed0dcac9b 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
@@ -420,7 +420,7 @@ test("each fit verdict is an info mark that explains itself", () => {
test("a GGUF row takes the GGUF verdict, not the torch refusal", () => {
assert.ok(
- PICKERS.includes("status: ggufRowFit(sizeBytes, rowInferenceGpu),"),
+ PICKERS.includes("status: ggufRowFit(sizeBytes, rowInferenceGpu, r.id),"),
);
assert.ok(!PICKERS.includes("exceedsSize"));
assert.match(
diff --git a/studio/frontend/tests/recommended-curated-row-metadata.test.ts b/studio/frontend/tests/recommended-curated-row-metadata.test.ts
index da95c9e503d..7ebbd288550 100644
--- a/studio/frontend/tests/recommended-curated-row-metadata.test.ts
+++ b/studio/frontend/tests/recommended-curated-row-metadata.test.ts
@@ -307,7 +307,7 @@ test("every list that judges a row against the device asks the same helper", ()
test("GGUF rows keep the inference backend's budget", () => {
assert.match(
declarationText("recommendedMeta"),
- /ggufRowFit\(sizeBytes, rowInferenceGpu\)/,
+ /ggufRowFit\(sizeBytes, rowInferenceGpu, r\.id\)/,
);
// Use the inventory of the runtime that places the row, not its file format.
assert.match(