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: 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.pynew file mode 100644index 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.0diff --git a/studio/backend/utils/hardware/hardware.py b/studio/backend/utils/hardware/hardware.pyindex 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.tsindex 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 thediff --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.tsindex 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.tsxindex 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)[] | nulnull,);+/** `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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 adiff --git a/studio/frontend/tests/apple-unified-gguf-fit.test.ts b/studio/frontend/tests/apple-unified-gguf-fit.test.tsnew file mode 100644index 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.tsindex 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.tsindex 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(