Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

fix: expose shared VRAM budget in image settings (#17368)

Lee Jackson45f69ced56e4
diff --git a/.github/workflows/studio-ui-smoke.yml b/.github/workflows/studio-ui-smoke.yml
index 7a9d7e9bdd8..e822c172998 100644
--- a/.github/workflows/studio-ui-smoke.yml
+++ b/.github/workflows/studio-ui-smoke.yml
@@ -514,6 +514,12 @@ jobs:
mkdir -p logs/playwright_image_footprint
python tests/studio/playwright_image_model_footprint.py
+ - name: Image VRAM budget regression (Playwright)
+ if: matrix.shard == 'extra'
+ env:
+ BASE_URL: http://127.0.0.1:18894
+ run: python tests/studio/playwright_image_vram_budget.py
+
- name: Image generation time and Images/Video model unload regressions (Playwright)
if: matrix.shard == 'extra'
env:
diff --git a/studio/frontend/src/features/images/api.ts b/studio/frontend/src/features/images/api.ts
index d816cc9f6bb..51412a7915f 100644
--- a/studio/frontend/src/features/images/api.ts
+++ b/studio/frontend/src/features/images/api.ts
@@ -2,6 +2,8 @@
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import { withBackgroundLoadNotice } from "@/lib/model-lifecycle-events";
+// eslint-disable-next-line no-restricted-imports -- leaf import; the UI barrels would cycle.
+import { dropVramBudgetRetry, loadVramBudgetSettings, settleVramBudgetSave, setVramBudgetLocked } from "@/features/settings/api/vram-budget";
import { authFetch } from "@/features/auth";
import { readFastApiError } from "@/lib/format-fastapi-error";
import { parseLoadJson } from "@/lib/multi-model-refusal";
@@ -445,20 +447,48 @@ export async function getGenerateProgress(): Promise<DiffusionGenerateProgress>
return parseJson(await authFetch("/api/inference/images/generate-progress"));
}
+/** The budget edit never reached the server, so nothing may load on the old one. */
+export class VramBudgetSaveError extends Error {
+ constructor(cause: unknown) {
+ super(cause instanceof Error ? cause.message : "Failed to save VRAM budget");
+ this.name = "VramBudgetSaveError";
+ }
+}
+
+/** Settles a slider edit first: the backend snapshots the budget for a load and its download plan. */
+export async function withSettledVramBudget<T>(run: () => Promise<T>): Promise<T> {
+ const budgetSave = settleVramBudgetSave();
+ if (!budgetSave) return run();
+ setVramBudgetLocked(true);
+ try {
+ await budgetSave.catch((error: unknown) => {
+ // Dropped and repainted together, so the slider never shows a value no load will use.
+ dropVramBudgetRetry();
+ void loadVramBudgetSettings({ force: true });
+ throw new VramBudgetSaveError(error);
+ });
+ return await run();
+ } finally {
+ setVramBudgetLocked(false);
+ }
+}
+
export async function loadDiffusionModel(body: DiffusionLoadRequest): Promise<DiffusionStatus> {
// This POST only starts the load, so the notice settles from load-progress, not the response.
- return withBackgroundLoadNotice(
- "image",
- body.model_path,
- async () =>
- parseLoadJson<DiffusionStatus>(
- await authFetch("/api/inference/images/load", {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify(withAllowOversizedLoad(body)),
- }),
- ),
- async (signal) => (await getDiffusionLoadProgress(signal)).phase,
+ return withSettledVramBudget(() =>
+ withBackgroundLoadNotice(
+ "image",
+ body.model_path,
+ async () =>
+ parseLoadJson<DiffusionStatus>(
+ await authFetch("/api/inference/images/load", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(withAllowOversizedLoad(body)),
+ }),
+ ),
+ async (signal) => (await getDiffusionLoadProgress(signal)).phase,
+ ),
);
}
diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsx
index 8c142775335..ebec28d6829 100644
--- a/studio/frontend/src/features/images/images-page.tsx
+++ b/studio/frontend/src/features/images/images-page.tsx
@@ -88,7 +88,9 @@ import {
TooltipTrigger,
} from "@/components/ui/tooltip";
import { InfoHint } from "@/components/ui/info-hint";
-import { useDiffusionGpuChoices } from "@/hooks/use-gpu-info";
+// eslint-disable-next-line no-restricted-imports -- leaf import; the UI barrels would cycle.
+import { VramBudgetControl } from "@/features/settings/components/vram-budget-control";
+import { useDiffusionGpuChoices, useGpuDevices } from "@/hooks/use-gpu-info";
import { usePersistedChoice } from "@/hooks/use-persisted-choice";
import { useScrollFades } from "@/hooks/use-scroll-fades";
import { ModelSelector } from "@/features/model-picker/components/model-selector";
@@ -329,6 +331,8 @@ import {
listDiffusionLoras,
setGalleryImageFlags,
getDiffusionDownloadPlan,
+ withSettledVramBudget,
+ VramBudgetSaveError,
loadDiffusionModel,
moveDiffusionQueueJob,
type ImageQueueJob,
@@ -2060,6 +2064,7 @@ export function ImagesPage({
"auto",
);
const gpuChoices = useDiffusionGpuChoices();
+ const imageGpuDevices = useGpuDevices(true);
const [transformerCache, setTransformerCache] = useState<"auto" | "off" | "fbcache" | "static">("auto");
const [cpuOffload, setCpuOffload] = useState(false);
// The last load descriptor, so "Reapply" can reload the same model with new advanced options without re-picking it.
@@ -4423,9 +4428,11 @@ export function ImagesPage({
let incompatible: string | null = null;
let incompatibleCode: string | null = null;
try {
- const plan = retiredSnapshot
- ? await requestDownloadPlan(repoId, opts, advanced, opts.displayRepoId)
- : await requestDownloadPlan(opts.displayRepoId ?? repoId, opts, advanced);
+ const plan = await withSettledVramBudget(() =>
+ retiredSnapshot
+ ? requestDownloadPlan(repoId, opts, advanced, opts.displayRepoId)
+ : requestDownloadPlan(opts.displayRepoId ?? repoId, opts, advanced),
+ );
// Only load intents are superseded; accepted downloads keep their own plans.
if (!downloadOnly && (pick !== pickSeq.current || !owns())) {
pickToast.dismiss(pickToastId);
@@ -4478,6 +4485,16 @@ export function ImagesPage({
return true;
}
} catch (error) {
+ // Not a plan failure: the fallback load below would run on the budget the user replaced.
+ if (error instanceof VramBudgetSaveError) {
+ pickToast.dismiss(pickToastId);
+ if (ownRevert && quantRevert.current === ownRevert) {
+ revertPick(ownRevert);
+ quantRevert.current = null;
+ }
+ toast.error(error.message);
+ return true;
+ }
if (downloadOnly) {
toast.error("Could not plan the download", {
description: error instanceof Error ? error.message : "Try selecting the model again.",
@@ -6075,6 +6092,9 @@ export function ImagesPage({
["sage", "SageAttention (INT8)"],
]}
/>
+ {!external && imageGpuDevices.length > 0 && (
+ <VramBudgetControl image modelLoading={busy === "loading"} />
+ )}
<AdvancedSelect
label="Memory"
hint="auto measures free VRAM. fast keeps everything resident. balanced streams the transformer. low_vram offloads every component (lowest VRAM, slower)."
diff --git a/studio/frontend/src/features/model-picker/components/advanced-gpu-slider.tsx b/studio/frontend/src/features/model-picker/components/advanced-gpu-slider.tsx
new file mode 100644
index 00000000000..d188da5e7cb
--- /dev/null
+++ b/studio/frontend/src/features/model-picker/components/advanced-gpu-slider.tsx
@@ -0,0 +1,78 @@
+// 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 type { ReactNode, Ref } from "react";
+import { InfoHint } from "@/components/ui/info-hint";
+import { Slider } from "@/components/ui/slider";
+import { useSliderDraft } from "@/hooks/use-slider-draft";
+import {
+ NumericValueInput,
+ type NumericValueInputHandle,
+} from "./numeric-value-input";
+
+const ROW_CLASS = "flex min-h-8 items-center justify-between gap-3";
+const LABEL_CLASS =
+ "min-w-0 truncate text-ui-13 font-medium leading-[1.25] tracking-nav text-foreground";
+const NUMBER_INPUT_CLASS =
+ "panel-field h-8 w-[calc(84px*var(--ui-space-scale,1))] shrink-0";
+
+export function AdvancedGpuSlider({
+ label,
+ value,
+ min,
+ max,
+ onChange,
+ onDraft,
+ format,
+ info,
+ inputRef,
+ step = 1,
+ disabled = false,
+}: {
+ label: string;
+ value: number;
+ min: number;
+ max: number;
+ onChange: (value: number) => void;
+ onDraft?: (value: number | null) => void;
+ format?: (value: number) => string | undefined;
+ info?: ReactNode;
+ inputRef?: Ref<NumericValueInputHandle>;
+ step?: number;
+ disabled?: boolean;
+}) {
+ const { draft, sliderProps } = useSliderDraft(value, onChange, onDraft);
+ const shown = draft ?? value;
+ return (
+ <div className="space-y-2">
+ <div className={ROW_CLASS}>
+ <div className="flex min-w-0 items-center gap-1.5">
+ <span className={LABEL_CLASS}>{label}</span>
+ {info && <InfoHint>{info}</InfoHint>}
+ </div>
+ <NumericValueInput
+ ref={inputRef}
+ value={shown}
+ min={min}
+ max={max}
+ step={step}
+ onChange={onChange}
+ displayValue={format?.(shown)}
+ ariaLabel={label}
+ className={NUMBER_INPUT_CLASS}
+ fixedWidth={true}
+ size={8}
+ disabled={disabled}
+ />
+ </div>
+ <Slider
+ min={min}
+ max={max}
+ step={step}
+ {...sliderProps}
+ aria-label={label}
+ disabled={disabled}
+ />
+ </div>
+ );
+}
diff --git a/studio/frontend/src/features/model-picker/components/model-config-page.tsx b/studio/frontend/src/features/model-picker/components/model-config-page.tsx
index 4d8b6dc1665..bd083395237 100644
--- a/studio/frontend/src/features/model-picker/components/model-config-page.tsx
+++ b/studio/frontend/src/features/model-picker/components/model-config-page.tsx
@@ -1,6 +1,9 @@
// 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 { AdvancedGpuSlider } from "./advanced-gpu-slider";
+// eslint-disable-next-line no-restricted-imports -- leaf import; the UI barrels would cycle.
+import { VramBudgetControl } from "@/features/settings/components/vram-budget-control";
import { HugeiconsIcon } from "@hugeicons/react";
import { InferenceEnginePicker } from "./inference-engines";
import { modelDisplayName } from "../model-config/model-identity";
@@ -65,17 +68,11 @@ import {
} from "@/features/chat/stores/chat-runtime-store";
import { prepareHfTokenForUse } from "@/features/hf-auth";
import {
- type VramBudgetSettings,
dropVramBudgetRetry,
- flushVramBudgetSave,
- isVramBudgetLocked,
loadVramBudgetSettings,
setVramBudgetLocked,
settleVramBudgetSave,
- stageVramBudgetSave,
- subscribeVramBudgetLock,
subscribeVramBudgetSettings,
- updateVramBudgetSettings,
} from "@/features/settings/api/vram-budget";
import {
type GpuIndexKind,
@@ -238,9 +235,6 @@ import {
savePerModelConfig,
storedSpeculativeAuto,
subscribeAdvancedSettingsOpen,
- VRAM_BUDGET_PERCENT_STEP,
- vramFractionToPercent,
- vramPercentToFraction,
} from "../model-config/per-model-config";
import { isAudioRuntimeGguf } from "../../audio/audio-cpp-catalog";
import { isNpuModelId, NPU_DEFAULT_CONTEXT_LENGTH } from "../../npu";
@@ -672,254 +666,9 @@ function clampMaxSeqLength(value: number, max: number): number {
return Math.max(MAX_SEQ_LENGTH_MIN, Math.min(max, normalized));
}
-function AdvancedGpuSlider({
- label,
- value,
- min,
- max,
- onChange,
- onDraft,
- format,
- info,
- inputRef,
- step = 1,
- disabled = false,
-}: {
- label: string;
- value: number;
- min: number;
- max: number;
- onChange: (value: number) => void;
- onDraft?: (value: number | null) => void;
- format?: (value: number) => string | undefined;
- info?: ReactNode;
- inputRef?: Ref<NumericValueInputHandle>;
- step?: number;
- disabled?: boolean;
-}) {
- const { draft, sliderProps } = useSliderDraft(value, onChange, onDraft);
- const shown = draft ?? value;
- return (
- <div className="space-y-2">
- <div className={ROW_CLASS}>
- <div className="flex min-w-0 items-center gap-1.5">
- <span className={LABEL_CLASS}>{label}</span>
- {info && <InfoHint>{info}</InfoHint>}
- </div>
- <NumericValueInput
- ref={inputRef}
- value={shown}
- min={min}
- max={max}
- step={step}
- onChange={onChange}
- displayValue={format?.(shown)}
- ariaLabel={label}
- className={NUMBER_INPUT_CLASS}
- fixedWidth={true}
- size={8}
- disabled={disabled}
- />
- </div>
- <Slider
- min={min}
- max={max}
- step={step}
- {...sliderProps}
- aria-label={label}
- disabled={disabled}
- />
- </div>
- );
-}
-
-// Server-wide, not per model. Whole percents so a dragged value round-trips exactly.
function VramBudgetRow() {
- // macOS sizes Metal from _APPLE_UNIFIED_MEMORY_FRACTION and ignores this budget.
- const isMac = usePlatformStore((s) => s.deviceType === "mac");
- const [settings, setSettings] = useState<VramBudgetSettings | null>(null);
- const [percent, setPercent] = useState<number | null>(null);
- const [draftPercent, setDraftPercent] = useState<number | null>(null);
- const saveTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
- const adviceId = useId();
const modelLoading = useChatRuntimeStore((s) => s.modelLoading);
- const wasModelLoading = useRef(false);
- // Locked while Run settles the budget, or an edit would be flushed with the load.
- const [locked, setLocked] = useState(isVramBudgetLocked);
- useEffect(() => subscribeVramBudgetLock(setLocked), []);
-
- // A queued edit outranks the publish, or a save landing mid-drag would move the slider.
- useEffect(() => {
- if (isMac) {
- return;
- }
- return subscribeVramBudgetSettings((next) => {
- if (saveTimer.current) {
- return;
- }
- setSettings(next);
- setPercent(vramFractionToPercent(next.fraction));
- });
- }, [isMac]);
-
- useEffect(() => {
- let cancelled = false;
- if (isMac) {
- return;
- }
- loadVramBudgetSettings().then((loaded) => {
- if (cancelled || !loaded) {
- return;
- }
- setSettings(loaded);
- setPercent(vramFractionToPercent(loaded.fraction));
- });
- return () => {
- cancelled = true;
- };
- // deviceType settles once /api/health answers, so re-run if the seed guess flips.
- }, [isMac]);
-
- // reloadRequired goes stale when a load finishes; refresh on the falling edge only.
- useEffect(() => {
- const finished = wasModelLoading.current && !modelLoading;
- wasModelLoading.current = modelLoading;
- if (isMac || !finished) {
- return;
- }
- let cancelled = false;
- // Forced: an earlier read describes the child being replaced.
- loadVramBudgetSettings({ force: true }).then((loaded) => {
- if (cancelled || !loaded) {
- return;
- }
- setSettings(loaded);
- });
- return () => {
- cancelled = true;
- };
- }, [isMac, modelLoading]);
-
- // Flush, do not drop: the fraction is held nowhere else.
- useEffect(
- () => () => {
- if (saveTimer.current) {
- clearTimeout(saveTimer.current);
- saveTimer.current = null;
- }
- flushVramBudgetSave()?.catch((error: unknown) => {
- toast.error(
- error instanceof Error ? error.message : "Failed to save VRAM budget",
- );
- });
- },
- [],
- );
-
- if (isMac || !settings || percent === null) {
- return null;
- }
-
- const defaultPercent = vramFractionToPercent(settings.defaultFraction);
- const shownPercent = draftPercent ?? percent;
- // Stored beats UNSLOTH_VRAM_FRACTION, so once the slider has been touched there is otherwise
- // no way back to inheriting it. Clearing is what the null the API accepts is for.
- const resetBudget = () => {
- if (saveTimer.current) {
- clearTimeout(saveTimer.current);
- saveTimer.current = null;
- }
- // Drop a queued drag, or its debounce would store back what this clears.
- stageVramBudgetSave(null);
- updateVramBudgetSettings(null)
- .then((next) => {
- setSettings(next);
- setPercent(vramFractionToPercent(next.fraction));
- })
- .catch((error: unknown) => {
- toast.error(
- error instanceof Error ? error.message : "Failed to reset VRAM budget",
- );
- });
- };
- const commit = (next: number) => {
- setPercent(next);
- // Debounced: a held arrow key commits every step, so one press would be dozens of writes, each
- // invalidating the read cache.
- if (saveTimer.current) {
- clearTimeout(saveTimer.current);
- }
- stageVramBudgetSave(vramPercentToFraction(next));
- saveTimer.current = setTimeout(() => {
- saveTimer.current = null;
- flushVramBudgetSave()
- ?.then(setSettings)
- .catch((error: unknown) => {
- // The client re-stages it, where the write generation can tell if it is still the newest.
- toast.error(
- error instanceof Error ? error.message : "Failed to save VRAM budget",
- );
- });
- }, 400);
- };
-
- return (
- <div className="space-y-1">
- <AdvancedGpuSlider
- label="VRAM Budget"
- value={percent}
- min={vramFractionToPercent(settings.minFraction)}
- max={vramFractionToPercent(settings.maxFraction)}
- step={VRAM_BUDGET_PERCENT_STEP}
- format={(v) => `${v}%`}
- onChange={commit}
- onDraft={setDraftPercent}
- disabled={locked}
- info={
- <div className="flex flex-col gap-1.5">
- <div>
- Share of each GPU Unsloth will claim when it sizes the model and
- context. The rest is left for memory fragmentation, the per-device
- CUDA context on a multi-GPU split, and MoE routing.
- </div>
- <div>
- Applies to every model, not just this one, and takes effect on the
- next load. Default {defaultPercent}%. Even at 100% a load leaves a
- margin on each card, up to the 512 MiB llama.cpp keeps for its own
- fitter, and never more than the default would have reserved.
- </div>
- <div>
- Reset clears the stored value, so UNSLOTH_VRAM_FRACTION applies
- again if it is set.
- </div>
- </div>
- }
- />
- {shownPercent !== defaultPercent && (
- <p id={adviceId} className="text-ui-11 text-amber-500">
- {shownPercent > defaultPercent
- ? "Above the default fits more context but leaves less slack, so a load can run out of memory. llama.cpp treats that as a hard failure rather than falling back."
- : "Below the default is safer on a shared GPU, but a tight fit may push layers onto the CPU and generate slowly."}
- </p>
- )}
- {settings.isStored && (
- <button
- type="button"
- disabled={locked}
- onClick={resetBudget}
- className="text-ui-11 text-muted-foreground underline underline-offset-2 hover:text-foreground"
- >
- Reset to the server default
- </button>
- )}
- {settings.reloadRequired && (
- <p className="text-ui-11 text-muted-foreground">
- The loaded model was sized with a different budget. Reload it to apply
- this one.
- </p>
- )}
- </div>
- );
+ return <VramBudgetControl modelLoading={modelLoading} />;
}
// --tensor-split is set per GPU row but not persisted per model.
diff --git a/studio/frontend/src/features/settings/api/vram-budget.ts b/studio/frontend/src/features/settings/api/vram-budget.ts
index 4f19366a50e..db50bd12ceb 100644
--- a/studio/frontend/src/features/settings/api/vram-budget.ts
+++ b/studio/frontend/src/features/settings/api/vram-budget.ts
@@ -47,6 +47,10 @@ export function stageVramBudgetSave(fraction: number | null) {
stagedVramBudgetSequence += 1;
}
+export function hasStagedVramBudgetSave() {
+ return stagedVramBudgetFraction !== null;
+}
+
/** Drop a re-staged retry before a load, or teardown would flush it and race the load. */
export function dropVramBudgetRetry() {
if (stagedVramBudgetSequence === retryVramBudgetSequence) {
diff --git a/studio/frontend/src/features/settings/components/vram-budget-control.tsx b/studio/frontend/src/features/settings/components/vram-budget-control.tsx
new file mode 100644
index 00000000000..0cc770f2c40
--- /dev/null
+++ b/studio/frontend/src/features/settings/components/vram-budget-control.tsx
@@ -0,0 +1,219 @@
+// 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 { useEffect, useId, useRef, useState } from "react";
+import { toast } from "sonner";
+import { usePlatformStore } from "@/config/env";
+// eslint-disable-next-line no-restricted-imports -- leaf import; the UI barrels would cycle.
+import { AdvancedGpuSlider } from "@/features/model-picker/components/advanced-gpu-slider";
+// eslint-disable-next-line no-restricted-imports -- Pure conversions; avoid the model-picker UI barrel.
+import {
+ VRAM_BUDGET_PERCENT_STEP,
+ vramFractionToPercent,
+ vramPercentToFraction,
+} from "@/features/model-picker/model-config/per-model-config";
+import {
+ type VramBudgetSettings,
+ flushVramBudgetSave,
+ hasStagedVramBudgetSave,
+ isVramBudgetLocked,
+ loadVramBudgetSettings,
+ stageVramBudgetSave,
+ subscribeVramBudgetLock,
+ subscribeVramBudgetSettings,
+ updateVramBudgetSettings,
+} from "../api/vram-budget";
+
+export function VramBudgetControl({
+ modelLoading = false,
+ image = false,
+}: { modelLoading?: boolean; image?: boolean }) {
+ // macOS sizes Metal from _APPLE_UNIFIED_MEMORY_FRACTION and ignores this budget.
+ const isMac = usePlatformStore((s) => s.deviceType === "mac");
+ const [settings, setSettings] = useState<VramBudgetSettings | null>(null);
+ const [percent, setPercent] = useState<number | null>(null);
+ const [draftPercent, setDraftPercent] = useState<number | null>(null);
+ const saveTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+ const adviceId = useId();
+ const wasModelLoading = useRef(false);
+ // Locked while Run settles the budget, or an edit would be flushed with the load.
+ const [locked, setLocked] = useState(isVramBudgetLocked);
+ useEffect(() => subscribeVramBudgetLock(setLocked), []);
+
+ // A staged edit outranks the publish; a dropped one does not, or the slider shows a value no load uses.
+ useEffect(() => {
+ if (isMac) {
+ return;
+ }
+ return subscribeVramBudgetSettings((next) => {
+ if (hasStagedVramBudgetSave()) {
+ return;
+ }
+ setSettings(next);
+ setPercent(vramFractionToPercent(next.fraction));
+ });
+ }, [isMac]);
+
+ useEffect(() => {
+ let cancelled = false;
+ if (isMac) {
+ return;
+ }
+ loadVramBudgetSettings().then((loaded) => {
+ if (cancelled || !loaded) {
+ return;
+ }
+ setSettings(loaded);
+ setPercent(vramFractionToPercent(loaded.fraction));
+ });
+ return () => {
+ cancelled = true;
+ };
+ // deviceType settles once /api/health answers, so re-run if the seed guess flips.
+ }, [isMac]);
+
+ // reloadRequired goes stale when a load finishes; refresh on the falling edge only.
+ useEffect(() => {
+ const finished = wasModelLoading.current && !modelLoading;
+ wasModelLoading.current = modelLoading;
+ if (isMac || !finished) {
+ return;
+ }
+ let cancelled = false;
+ // Forced: an earlier read describes the child being replaced.
+ loadVramBudgetSettings({ force: true }).then((loaded) => {
+ if (cancelled || !loaded) {
+ return;
+ }
+ setSettings(loaded);
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, [isMac, modelLoading]);
+
+ // Flush, do not drop: the fraction is held nowhere else.
+ useEffect(
+ () => () => {
+ if (saveTimer.current) {
+ clearTimeout(saveTimer.current);
+ saveTimer.current = null;
+ }
+ flushVramBudgetSave()?.catch((error: unknown) => {
+ toast.error(
+ error instanceof Error ? error.message : "Failed to save VRAM budget",
+ );
+ });
+ },
+ [],
+ );
+
+ if (isMac || !settings || percent === null) {
+ return null;
+ }
+
+ const defaultPercent = vramFractionToPercent(settings.defaultFraction);
+ const shownPercent = draftPercent ?? percent;
+ // Stored beats UNSLOTH_VRAM_FRACTION, so once the slider has been touched there is otherwise
+ // no way back to inheriting it. Clearing is what the null the API accepts is for.
+ const resetBudget = () => {
+ if (saveTimer.current) {
+ clearTimeout(saveTimer.current);
+ saveTimer.current = null;
+ }
+ // Drop a queued drag, or its debounce would store back what this clears.
+ stageVramBudgetSave(null);
+ updateVramBudgetSettings(null)
+ .then((next) => {
+ setSettings(next);
+ setPercent(vramFractionToPercent(next.fraction));
+ })
+ .catch((error: unknown) => {
+ toast.error(
+ error instanceof Error
+ ? error.message
+ : "Failed to reset VRAM budget",
+ );
+ });
+ };
+ const commit = (next: number) => {
+ setPercent(next);
+ // Debounced: a held arrow key commits every step, so one press would be dozens of writes, each
+ // invalidating the read cache.
+ if (saveTimer.current) {
+ clearTimeout(saveTimer.current);
+ }
+ stageVramBudgetSave(vramPercentToFraction(next));
+ saveTimer.current = setTimeout(() => {
+ saveTimer.current = null;
+ flushVramBudgetSave()
+ ?.then(setSettings)
+ .catch((error: unknown) => {
+ // The client re-stages it, where the write generation can tell if it is still the newest.
+ toast.error(
+ error instanceof Error
+ ? error.message
+ : "Failed to save VRAM budget",
+ );
+ });
+ }, 400);
+ };
+
+ return (
+ <div className="space-y-1">
+ <AdvancedGpuSlider
+ label="VRAM Budget"
+ value={percent}
+ min={vramFractionToPercent(settings.minFraction)}
+ max={vramFractionToPercent(settings.maxFraction)}
+ step={VRAM_BUDGET_PERCENT_STEP}
+ format={(v) => `${v}%`}
+ onChange={commit}
+ onDraft={setDraftPercent}
+ disabled={locked || modelLoading}
+ info={
+ <div className="flex flex-col gap-1.5">
+ <div>
+ Shared across models. Changes apply on the next model load.
+ Default {defaultPercent}%.
+ </div>
+ <div>
+ Sets how much GPU memory Unsloth may use. Each engine also
+ reserves memory for running the model, so 100% does not guarantee
+ full GPU residency.
+ </div>
+ </div>
+ }
+ />
+ {image && (
+ <p className="text-ui-11 text-muted-foreground">
+ Shared across models. Applies on the next load or Reapply. Image
+ models keep additional memory headroom.
+ </p>
+ )}
+ {shownPercent !== defaultPercent && (
+ <p id={adviceId} className="text-ui-11 text-amber-500">
+ {shownPercent > defaultPercent
+ ? "Above the default leaves less headroom and may cause an out-of-memory error."
+ : "Below the default leaves more memory free, but may offload more of the model to CPU and slow generation."}
+ </p>
+ )}
+ {settings.isStored && (
+ <button
+ type="button"
+ disabled={locked || modelLoading}
+ onClick={resetBudget}
+ className="text-ui-11 text-muted-foreground underline underline-offset-2 hover:text-foreground"
+ >
+ Reset to the server default
+ </button>
+ )}
+ {settings.reloadRequired && (
+ <p className="text-ui-11 text-muted-foreground">
+ The loaded model was sized with a different budget. Reload it to apply
+ this one.
+ </p>
+ )}
+ </div>
+ );
+}
diff --git a/studio/frontend/tests/image-generate-no-resend.test.ts b/studio/frontend/tests/image-generate-no-resend.test.ts
index 1eb8d7ffd30..43898279c36 100644
--- a/studio/frontend/tests/image-generate-no-resend.test.ts
+++ b/studio/frontend/tests/image-generate-no-resend.test.ts
@@ -37,6 +37,12 @@ function loadApis(): ImagesApi {
new URL("../src/features/images/api.ts", import.meta.url),
{
"@/lib/model-lifecycle-events": { withBackgroundLoadNotice: (f: unknown) => f },
+ "@/features/settings/api/vram-budget": {
+ dropVramBudgetRetry: () => {},
+ loadVramBudgetSettings: async () => null,
+ settleVramBudgetSave: () => null,
+ setVramBudgetLocked: () => {},
+ },
"@/features/auth": { authFetch: auth.authFetch },
"@/lib/format-fastapi-error": { readFastApiError: async () => "" },
"@/lib/multi-model-refusal": { parseLoadJson: async () => ({}) },
diff --git a/studio/frontend/tests/image-vram-budget.test.ts b/studio/frontend/tests/image-vram-budget.test.ts
new file mode 100644
index 00000000000..a891419a9af
--- /dev/null
+++ b/studio/frontend/tests/image-vram-budget.test.ts
@@ -0,0 +1,180 @@
+// 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 { loadWithStubs } from "./helpers/module-stubs.ts";
+
+function setup() {
+ Object.assign(globalThis, { window: new EventTarget() });
+ const sent: string[] = [];
+ let release!: (response: Response) => void;
+ const reply = new Promise<Response>((resolve) => {
+ release = resolve;
+ });
+ const stored = {
+ fraction: 0.97,
+ is_stored: false,
+ default_fraction: 0.97,
+ min_fraction: 0.1,
+ max_fraction: 1,
+ reload_required: false,
+ };
+ const authFetch = async (path: string, init?: RequestInit) => {
+ sent.push(`${init?.method ?? "GET"} ${path}`);
+ if (path === "/api/settings/vram-budget" && !init?.method) return Response.json(stored);
+ if (path === "/api/settings/vram-budget") return reply;
+ return Response.json({ loaded: false });
+ };
+ const budget = loadWithStubs<
+ typeof import("../src/features/settings/api/vram-budget")
+ >(new URL("../src/features/settings/api/vram-budget.ts", import.meta.url), {
+ "@/features/auth": { authFetch },
+ "@/lib/format-fastapi-error": {
+ readFastApiError: async () => "Budget save failed",
+ },
+ "./settings-route-absent": {
+ SettingsRouteAbsentError: class extends Error {},
+ },
+ });
+ const images = loadWithStubs<typeof import("../src/features/images/api")>(
+ new URL("../src/features/images/api.ts", import.meta.url),
+ {
+ "@/features/settings/api/vram-budget": budget,
+ "@/features/auth": { authFetch },
+ "@/lib/model-lifecycle-events": {
+ withBackgroundLoadNotice: (
+ _kind: string,
+ _model: string,
+ run: () => unknown,
+ ) => run(),
+ },
+ "@/lib/format-fastapi-error": {},
+ "@/lib/multi-model-refusal": {
+ parseLoadJson: (response: Response) => response.json(),
+ },
+ "@/lib/unified-memory-load-refusal": {
+ withAllowOversizedLoad: (body: unknown) => body,
+ },
+ "./lib/memory-refusal": {},
+ },
+ );
+ const ok = () =>
+ release(
+ Response.json({
+ fraction: 0.9,
+ is_stored: true,
+ default_fraction: 0.97,
+ min_fraction: 0.1,
+ max_fraction: 1,
+ reload_required: true,
+ }),
+ );
+ return { budget, images, sent, release, ok };
+}
+
+test("an immediate image load waits for the staged budget save", async () => {
+ const { budget, images, sent, ok } = setup();
+ budget.stageVramBudgetSave(0.9);
+ const loading = images.loadDiffusionModel({ model_path: "example/image" });
+ await new Promise((resolve) => setImmediate(resolve));
+ assert.deepEqual(sent, ["PUT /api/settings/vram-budget"]);
+ assert.equal(budget.isVramBudgetLocked(), true);
+ ok();
+ await loading;
+ assert.deepEqual(sent, [
+ "PUT /api/settings/vram-budget",
+ "POST /api/inference/images/load",
+ ]);
+ assert.equal(budget.isVramBudgetLocked(), false);
+});
+
+test("a rejected budget save prevents image loading and unlocks the slider", async () => {
+ const { budget, images, sent, release } = setup();
+ budget.stageVramBudgetSave(0.9);
+ const loading = images.loadDiffusionModel({ model_path: "example/image" });
+ release(Response.json({ detail: "Budget save failed" }, { status: 500 }));
+ await assert.rejects(loading, /Budget save failed/);
+ assert.deepEqual(sent, ["PUT /api/settings/vram-budget", "GET /api/settings/vram-budget"]);
+ assert.equal(budget.isVramBudgetLocked(), false);
+});
+
+test("a failed in-flight budget save is not retried by the next image load", async () => {
+ const { budget, images, sent, release } = setup();
+ const saving = budget.updateVramBudgetSettings(0.9);
+ const loading = images.loadDiffusionModel({ model_path: "example/image" });
+ release(Response.json({ detail: "Budget save failed" }, { status: 500 }));
+ await assert.rejects(saving, /Budget save failed/);
+ await assert.rejects(loading, /Budget save failed/);
+ assert.equal(budget.flushVramBudgetSave(), null);
+ assert.deepEqual(sent, ["PUT /api/settings/vram-budget", "GET /api/settings/vram-budget"]);
+});
+
+test("image loading also waits for an in-flight reset", async () => {
+ const { budget, images, sent, ok } = setup();
+ const resetting = budget.updateVramBudgetSettings(null);
+ const loading = images.loadDiffusionModel({ model_path: "example/image" });
+ await new Promise((resolve) => setImmediate(resolve));
+ assert.deepEqual(sent, ["PUT /api/settings/vram-budget"]);
+ ok();
+ await Promise.all([resetting, loading]);
+ assert.deepEqual(sent, [
+ "PUT /api/settings/vram-budget",
+ "POST /api/inference/images/load",
+ ]);
+});
+
+test("a Hub download plan waits for the staged budget save", async () => {
+ const { budget, images, sent, ok } = setup();
+ budget.stageVramBudgetSave(0.9);
+ const planning = images.withSettledVramBudget(() =>
+ images.getDiffusionDownloadPlan({ model_path: "example/image" }),
+ );
+ await new Promise((resolve) => setImmediate(resolve));
+ assert.deepEqual(sent, ["PUT /api/settings/vram-budget"]);
+ ok();
+ await planning;
+ assert.deepEqual(sent, [
+ "PUT /api/settings/vram-budget",
+ "POST /api/inference/images/download-plan",
+ ]);
+});
+
+test("a failed budget save surfaces as VramBudgetSaveError and repaints the stored budget", async () => {
+ const { budget, images, sent, release } = setup();
+ const published: number[] = [];
+ budget.subscribeVramBudgetSettings((next) => published.push(next.fraction));
+ budget.stageVramBudgetSave(0.9);
+ const planning = images.withSettledVramBudget(() =>
+ images.getDiffusionDownloadPlan({ model_path: "example/image" }),
+ );
+ release(Response.json({ detail: "Budget save failed" }, { status: 500 }));
+ await assert.rejects(planning, (error: unknown) => error instanceof images.VramBudgetSaveError);
+ assert.deepEqual(sent, ["PUT /api/settings/vram-budget", "GET /api/settings/vram-budget"]);
+ await new Promise((resolve) => setImmediate(resolve));
+ assert.deepEqual(published, [0.97]);
+});
+
+test("the staged Hub plan settles the budget first", async () => {
+ const { readFileSync } = await import("node:fs");
+ const read = (path: string) => readFileSync(new URL(`../src/${path}`, import.meta.url), "utf8");
+ assert.match(
+ read("features/images/images-page.tsx"),
+ /const plan = await withSettledVramBudget\(\(\) =>\s*retiredSnapshot/,
+ );
+ assert.match(
+ read("features/images/images-page.tsx"),
+ /if \(error instanceof VramBudgetSaveError\) \{[\s\S]{0,400}?return true;/,
+ "a failed budget save must not fall through to the fallback load",
+ );
+});
+
+test("a dropped retry no longer counts as a staged edit", async () => {
+ const { budget, release } = setup();
+ const saving = budget.updateVramBudgetSettings(0.9);
+ release(Response.json({ detail: "Budget save failed" }, { status: 500 }));
+ await assert.rejects(saving, /Budget save failed/);
+ assert.equal(budget.hasStagedVramBudgetSave(), true);
+ budget.dropVramBudgetRetry();
+ assert.equal(budget.hasStagedVramBudgetSave(), false);
+});
diff --git a/studio/frontend/tests/slider-draft.test.ts b/studio/frontend/tests/slider-draft.test.ts
index af6bdac5936..53d2bf169a7 100644
--- a/studio/frontend/tests/slider-draft.test.ts
+++ b/studio/frontend/tests/slider-draft.test.ts
@@ -239,7 +239,8 @@ test("keyboard steps go straight to the owner", () => {
test("the Run settings and model picker sliders drag on a draft", () => {
for (const [file, rows] of [
["features/chat/chat-settings-sheet.tsx", 1],
- ["features/model-picker/components/model-config-page.tsx", 3],
+ ["features/model-picker/components/model-config-page.tsx", 2],
+ ["features/model-picker/components/advanced-gpu-slider.tsx", 1],
] as const) {
const source = readSrc(file);
assert.equal(source.match(/= useSliderDraft\(/g)?.length, rows, file);
@@ -248,9 +249,10 @@ test("the Run settings and model picker sliders drag on a draft", () => {
});
test("what an owner shows beside its slider follows the drag", () => {
+ const budget = readSrc("features/settings/components/vram-budget-control.tsx");
+ assert.match(budget, /onDraft=\{setDraftPercent\}/);
+ assert.match(budget, /\{shownPercent !== defaultPercent && \(/, "the VRAM advice contradicted the dragged percent");
const picker = readSrc("features/model-picker/components/model-config-page.tsx");
- assert.match(picker, /onDraft=\{setDraftPercent\}/);
- assert.match(picker, /\{shownPercent !== defaultPercent && \(/, "the VRAM advice contradicted the dragged percent");
assert.match(picker, /displayValue=\{isMlx && windowUnknown && !dragging \? "—" : undefined\}/, "an unknown MLX window showed a dash for the whole drag");
assert.match(picker, /\{renderWarning\(shown\)\}/);
const music = readSrc("features/audio/components/music-edit-inputs.tsx");
diff --git a/studio/frontend/tests/vram-budget.test.ts b/studio/frontend/tests/vram-budget.test.ts
index 460fe4e16eb..157cdbbdc33 100644
--- a/studio/frontend/tests/vram-budget.test.ts
+++ b/studio/frontend/tests/vram-budget.test.ts
@@ -79,11 +79,7 @@ const pageSource = readSrc(
);
function vramBudgetRowSource(): string {
- const start = pageSource.indexOf("function VramBudgetRow()");
- assert.ok(start >= 0, "VramBudgetRow is no longer defined");
- const end = pageSource.indexOf("\n}\n", start);
- assert.ok(end > start, "could not delimit VramBudgetRow");
- return pageSource.slice(start, end);
+ return readSrc("features/settings/components/vram-budget-control.tsx");
}
test("unmount flushes the pending budget save instead of dropping it", () => {
@@ -151,10 +147,10 @@ test("Run waits for a staged budget save before starting the load", () => {
test("the row adopts published settings instead of only its own read", () => {
const row = vramBudgetRowSource();
assert.match(row, /subscribeVramBudgetSettings\(/);
- // A queued edit outranks the publish, or a mid-drag save moves the slider.
+ // A staged edit outranks the publish; a dropped one must not keep the slider on a value no load uses.
const subscribeAt = row.indexOf("subscribeVramBudgetSettings(");
const guard = row.slice(subscribeAt, subscribeAt + 260);
- assert.match(guard, /if \(saveTimer\.current\) \{\s*return;/);
+ assert.match(guard, /if \(hasStagedVramBudgetSave\(\)\) \{\s*return;/);
});
test("Run reports a rejected budget flush instead of voiding it", () => {
@@ -221,9 +217,7 @@ test("the budget reads as a percentage and steps in tenths", () => {
// and reads as neither.
assert.match(row, /format=\{\(v\) => `\$\{v\}%`\}/);
assert.match(row, /step=\{VRAM_BUDGET_PERCENT_STEP\}/);
- const slider = pageSource.slice(
- pageSource.indexOf("function AdvancedGpuSlider"),
- );
+ const slider = readSrc("features/model-picker/components/advanced-gpu-slider.tsx");
assert.match(slider.slice(0, slider.indexOf("</div>")), /step = 1,/);
});
@@ -248,7 +242,7 @@ test("the reload notice is refreshed once a load finishes", () => {
const row = vramBudgetRowSource().replace(/\s+/g, " ");
// Nothing remounts this row on a reload in the sidebar editor, so it must refetch.
assert.match(
- row,
+ pageSource,
/const modelLoading = useChatRuntimeStore\(\(s\) => s\.modelLoading\)/,
);
// Falling edge only: a read during the load describes the child being replaced.
@@ -303,7 +297,7 @@ test("a post-load read is not answered by one taken before the load finished", (
flat,
/if \(inFlightVramBudget === read\) \{ inFlightVramBudget = null;/,
);
- const row = readSrc("features/model-picker/components/model-config-page.tsx");
+ const row = vramBudgetRowSource();
assert.match(row, /loadVramBudgetSettings\(\{ force: true \}\)/);
});
@@ -325,7 +319,7 @@ test("the budget closes while Run settles it, instead of racing the load", () =>
row,
/useEffect\(\(\) => subscribeVramBudgetLock\(setLocked\), \[\]\)/,
);
- assert.match(row, /disabled=\{locked\}/);
+ assert.match(row, /disabled=\{locked \|\| modelLoading\}/);
});
test("a stored budget can be cleared back to the inherited one", () => {
diff --git a/tests/studio/playwright_image_vram_budget.py b/tests/studio/playwright_image_vram_budget.py
new file mode 100644
index 00000000000..021f585a13b
--- /dev/null
+++ b/tests/studio/playwright_image_vram_budget.py
@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Image VRAM budget controls in the real frontend with simulated APIs; no GPU required.
+
+Run with BASE_URL pointing to Vite. Verifies persistence, unsupported hosts/backends,
+failed saves, and flushing a pending edit when navigating away.
+"""
+
+import os
+from urllib.parse import parse_qs, urlparse
+
+from playwright.sync_api import expect, sync_playwright
+from playwright_image_model_footprint import _api_payload
+
+BASE = os.environ.get("BASE_URL", "http://127.0.0.1:4173")
+
+
+def run_case(browser, case):
+ context = browser.new_context(viewport = {"width": 1280, "height": 900}, reduced_motion = "reduce")
+ context.add_init_script("localStorage.setItem('unsloth_auth_token', 'rendered-ui-test');")
+ state = {"fraction": 0.97, "stored": False, "writes": []}
+ errors = []
+
+ def route(request):
+ url = urlparse(request.request.url)
+ if not url.path.startswith("/api/"):
+ if url.netloc == urlparse(BASE).netloc:
+ request.continue_()
+ else:
+ request.fulfill(json = [])
+ return
+ if url.path == "/api/settings/vram-budget":
+ if case == "old-backend":
+ request.fulfill(status = 404, json = {"detail": "Not found"})
+ return
+ if request.request.method == "PUT":
+ value = request.request.post_data_json["fraction"]
+ state["writes"].append(value)
+ if case == "failed-save":
+ request.fulfill(status = 500, json = {"detail": "Budget write refused"})
+ return
+ state.update(fraction = 0.97 if value is None else value, stored = value is not None)
+ data = dict(
+ fraction = state["fraction"],
+ is_stored = state["stored"],
+ default_fraction = 0.97,
+ min_fraction = 0.1,
+ max_fraction = 1,
+ reload_required = False,
+ )
+ else:
+ data = _api_payload(url.path, parse_qs(url.query), full_footprint = True)
+ if url.path == "/api/system":
+ for key in ("gpu", "inference_gpu"):
+ if case == "cpu":
+ data[key].update(available = False, devices = [])
+ else:
+ for device in data[key]["devices"]:
+ device.update(memory_total_gb = 8, vram_free_gb = 7)
+ if case == "cpu":
+ data["device_backend"] = "cpu"
+ if url.path == "/api/health" and case == "mac":
+ data["device_type"] = "mac"
+ request.fulfill(json = data)
+
+ context.route("**/*", route)
+ page = context.new_page()
+ page.on("pageerror", lambda error: errors.append(str(error)))
+ page.goto(f"{BASE}/images", wait_until = "domcontentloaded")
+ page.get_by_role("button", name = "Advanced", exact = True).click()
+ memory = page.get_by_role("combobox", name = "Memory", exact = True)
+ memory.scroll_into_view_if_needed()
+ expect(memory).to_be_visible()
+ value = page.locator('input[aria-label="VRAM Budget"]')
+ if case in {"cpu", "mac", "old-backend"}:
+ # Let the GPU inventory and settings reads settle before checking absence.
+ page.wait_for_timeout(800)
+ expect(value).to_have_count(0)
+ else:
+ expect(value).to_have_value("97%")
+ slider = page.get_by_role("slider", name = "VRAM Budget", exact = True)
+ slider.focus()
+ slider.press("ArrowLeft")
+ if case == "navigate-away":
+ # Before the 400 ms debounce fires: teardown must flush the changed value.
+ page.get_by_role("button", name = "New chat", exact = True).first.click()
+ if case == "failed-save":
+ expect(page.get_by_text("Budget write refused", exact = True).first).to_be_visible()
+ assert state["fraction"] == 0.97
+ else:
+ page.wait_for_timeout(800)
+ assert state["writes"] == [0.969], state
+ page.goto(f"{BASE}/images", wait_until = "domcontentloaded")
+ expect(value).to_have_value("96.9%")
+ page.get_by_role("button", name = "Reset to the server default", exact = True).click()
+ expect(value).to_have_value("97%")
+ assert state["writes"] == [0.969, None], state
+ assert not errors, errors
+ context.close()
+ print(f"PASS image VRAM budget: {case}", flush = True)
+
+
+def main():
+ with sync_playwright() as playwright:
+ browser = playwright.chromium.launch(headless = True)
+ for case in ("save-reset", "navigate-away", "failed-save", "cpu", "mac", "old-backend"):
+ run_case(browser, case)
+ browser.close()
+
+
+if __name__ == "__main__":
+ main()