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
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.ymlindex 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_footprintpython 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.tsindex 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.0import { 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.tsxindex 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"} />+ )}<AdvancedSelectlabel="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.tsxnew file mode 100644index 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.tsxindex 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.tsindex 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.tsxnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.pynew file mode 100644index 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()