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.

Unsloth Studio / Desktop: let the GPUs picker say how much of the model each card gets (#12015)

Leo Borcherding3cbe541dbb5f
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
index d279b6d3381..8fd491d0fa4 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
@@ -1541,10 +1541,13 @@ export function useChatModelRuntime() {
});
},
parallelSlots: managedFlags?.defaultParallelSlots || null,
- // Never a config field, so the store is the only place it can come from, and the reset clears it
- splitRatio: resetsPerModelSettings
- ? null
- : useChatRuntimeStore.getState().splitRatio,
+ // Only a config page pick carries one; else the store (cleared on reset)
+ splitRatio:
+ pendingConfig?.tensorSplit !== undefined
+ ? pendingConfig.tensorSplit
+ : resetsPerModelSettings
+ ? null
+ : useChatRuntimeStore.getState().splitRatio,
// What /load sends: a pick saved in another index namespace, or naming GPUs that are gone, is
// reconciled to Automatic before it leaves.
reconcileGpuIds: (ids, savedIndexKind) =>
@@ -2040,7 +2043,10 @@ export function useChatModelRuntime() {
pendingLoadConfig?.gpuLayers ?? stateBeforeUnload.gpuLayers;
let loadNCpuMoe =
pendingLoadConfig?.nCpuMoe ?? stateBeforeUnload.nCpuMoe;
- let loadSplitRatio = stateBeforeUnload.splitRatio;
+ let loadSplitRatio =
+ pendingLoadConfig?.tensorSplit !== undefined
+ ? pendingLoadConfig.tensorSplit
+ : stateBeforeUnload.splitRatio;
// Reconcile the persisted pick against the GPUs present now, so a stale cross-host pick is
// dropped before /load rather than rejected there. Warm the device cache first: a cold cache
// would pass the pick through unvalidated.
@@ -2389,7 +2395,7 @@ export function useChatModelRuntime() {
: null;
loadGpuLayers = pendingLoadConfig?.gpuLayers ?? GPU_LAYERS_AUTO;
loadNCpuMoe = pendingLoadConfig?.nCpuMoe ?? 0;
- loadSplitRatio = null;
+ loadSplitRatio = pendingLoadConfig?.tensorSplit ?? null;
}
// The Context Length the USER set for this load, captured before the clamp below can stand in for
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 3d18c87f9e3..4755d1581ed 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
@@ -22,6 +22,10 @@ import {
resolveStagedDiffusionClassification,
useChatRuntimeStore,
} from "@/features/chat";
+import {
+ distributeByWeight,
+ rebalanceSplit,
+} from "@/features/chat/stores/chat-runtime-store";
import { prepareHfTokenForUse } from "@/features/hf-auth";
import {
type VramBudgetSettings,
@@ -741,7 +745,7 @@ function VramBudgetRow() {
}
// GPU Memory placement controls, GGUF only. Slider ceilings come from the GGUF header dims;
-// --tensor-split is not persisted per model.
+// --tensor-split is set per GPU row but not persisted per model.
function GpuMemorySettings({
config,
update,
@@ -783,11 +787,44 @@ function GpuMemorySettings({
// The list order IS the device order the backend pins, so a re-checked GPU goes
// to the end rather than back to its numeric slot.
const orderedGpuIds = selectedGpuIds ?? gpuContext.ids ?? [];
- const commitGpuIds = (next: number[]) => {
+ // Mirrors the backend's --tensor-split gate.
+ const splitTotal = Math.max(0, Math.min(gpuLayers, gpuLayersMax));
+ const showSplit =
+ !isDiffusion &&
+ isManual &&
+ !autoLayers &&
+ splitTotal > 0 &&
+ showGpuPicker &&
+ orderedGpuIds.length > 1;
+ const splitIsPercent = Boolean(config.tensorParallel);
+ const splitScale = splitIsPercent ? 100 : splitTotal;
+ const tensorSplit = config.tensorSplit ?? null;
+ const splitIsCustom =
+ tensorSplit != null && tensorSplit.length === orderedGpuIds.length;
+ // Untouched: show a VRAM-proportional split and send nothing.
+ const splitShares = showSplit
+ ? distributeByWeight(
+ splitScale,
+ splitIsCustom
+ ? tensorSplit
+ : orderedGpuIds.map(
+ (id) =>
+ pinnableDevices.find((d) => d.index === id)?.memoryTotalGb ?? 1,
+ ),
+ )
+ : [];
+ const setSplitShare = (id: number, value: number) => {
+ const k = orderedGpuIds.indexOf(id);
+ if (k < 0) return;
+ update({ tensorSplit: rebalanceSplit(splitScale, splitShares, k, value) });
+ };
+ const commitGpuIds = (next: number[], nextSplit: number[] | null = null) => {
if (next.length === 0) return; // keep at least one GPU selected
update({
selectedGpuIds: next,
selectedGpuIndexKind: gpuIndexKind,
+ // Positional, so a different GPU set invalidates it.
+ tensorSplit: nextSplit,
});
};
const toggleGpu = (index: number) => {
@@ -810,7 +847,12 @@ function GpuMemorySettings({
if (from < 0 || to < 0 || to >= orderedGpuIds.length) return;
const next = [...orderedGpuIds];
[next[from], next[to]] = [next[to], next[from]];
- commitGpuIds(next);
+ let nextSplit: number[] | null = null;
+ if (splitIsCustom) {
+ nextSplit = [...tensorSplit];
+ [nextSplit[from], nextSplit[to]] = [nextSplit[to], nextSplit[from]];
+ }
+ commitGpuIds(next, nextSplit);
};
return (
<>
@@ -843,6 +885,7 @@ function GpuMemorySettings({
nCpuMoe: undefined,
selectedGpuIds: undefined,
selectedGpuIndexKind: undefined,
+ tensorSplit: null,
},
)
}
@@ -875,7 +918,9 @@ function GpuMemorySettings({
value={Math.max(GPU_LAYERS_AUTO, Math.min(gpuLayers, gpuLayersMax))}
min={GPU_LAYERS_AUTO}
max={gpuLayersMax}
- onChange={(v) => update({ gpuLayers: v })}
+ onChange={(v) =>
+ update(v < 0 ? { gpuLayers: v, tensorSplit: null } : { gpuLayers: v })
+ }
displayValue={autoLayers ? "Auto" : undefined}
info={
<>
@@ -912,7 +957,20 @@ function GpuMemorySettings({
{!isDiffusion &&
" Their order here is the order the model gets them."}{" "}
Keep at least one selected.
+ {showSplit &&
+ (splitIsPercent
+ ? " The number beside each is its share of every layer, in percent (--tensor-split)."
+ : " The number beside each is how many of the GPU Layers it holds (--tensor-split).")}
</InfoHint>
+ {showSplit && splitIsCustom && (
+ <button
+ type="button"
+ className="ml-auto shrink-0 rounded px-1 text-ui-12 text-muted-foreground hover:text-foreground"
+ onClick={() => update({ tensorSplit: null })}
+ >
+ Reset split
+ </button>
+ )}
</div>
<div className="flex flex-col gap-2">
{orderedPinnableDevices.map((d, position) => (
@@ -926,6 +984,29 @@ function GpuMemorySettings({
? ` · ${Math.round(d.memoryTotalGb)} GiB`
: ""}
</span>
+ {showSplit && isGpuChecked(d.index) && (
+ <div className="ml-auto flex shrink-0 items-center gap-1">
+ <NumericValueInput
+ value={splitShares[orderedGpuIds.indexOf(d.index)] ?? 0}
+ min={0}
+ max={splitScale}
+ step={1}
+ onChange={(v) => setSplitShare(d.index, v)}
+ derived={!splitIsCustom}
+ ariaLabel={
+ splitIsPercent
+ ? `Share of each layer on GPU ${d.index}, percent`
+ : `Layers on GPU ${d.index}`
+ }
+ className="panel-field h-7 w-[calc(52px*var(--ui-space-scale,1))] shrink-0"
+ fixedWidth={true}
+ size={4}
+ />
+ <span className="w-[3.25em] text-ui-12 text-muted-foreground">
+ {splitIsPercent ? "%" : "layers"}
+ </span>
+ </div>
+ )}
{/* Not for diffusion: that runner drives one device and matches_gpu_ids
reduces the request to its lowest id, so the arrows would move a row
without moving the model, under help text promising the opposite. */}
diff --git a/studio/frontend/src/features/model-picker/hooks/use-active-model-config.ts b/studio/frontend/src/features/model-picker/hooks/use-active-model-config.ts
index ecf10816653..45cd02c9971 100644
--- a/studio/frontend/src/features/model-picker/hooks/use-active-model-config.ts
+++ b/studio/frontend/src/features/model-picker/hooks/use-active-model-config.ts
@@ -63,6 +63,7 @@ export function useActiveModelConfig(): ActiveModelConfigState {
const selectedGpuIndexKind = useChatRuntimeStore(
(s) => s.selectedGpuIndexKind,
);
+ const splitRatio = useChatRuntimeStore((s) => s.splitRatio);
const isGguf = isServedByLlamaCpp({
loadedIsGguf,
@@ -119,6 +120,7 @@ export function useActiveModelConfig(): ActiveModelConfigState {
nCpuMoe,
selectedGpuIds,
selectedGpuIndexKind,
+ tensorSplit: splitRatio,
};
}, [
checkpoint,
@@ -147,6 +149,7 @@ export function useActiveModelConfig(): ActiveModelConfigState {
nCpuMoe,
selectedGpuIds,
selectedGpuIndexKind,
+ splitRatio,
]);
return { checkpoint, isGguf, config };
diff --git a/studio/frontend/src/features/model-picker/model-config/apply-per-model-config.ts b/studio/frontend/src/features/model-picker/model-config/apply-per-model-config.ts
index 9bf10673025..e9ec9af341e 100644
--- a/studio/frontend/src/features/model-picker/model-config/apply-per-model-config.ts
+++ b/studio/frontend/src/features/model-picker/model-config/apply-per-model-config.ts
@@ -24,6 +24,16 @@ function cleanTemplate(value: string | null | undefined): string | null {
return value?.trim() ? value : null;
}
+function cleanTensorSplit(value: number[] | null | undefined): number[] | null {
+ if (!value || value.length < 2) {
+ return null;
+ }
+ if (!value.every((v) => Number.isFinite(v) && v >= 0)) {
+ return null;
+ }
+ return value.some((v) => v > 0) ? value : null;
+}
+
export function applyPerModelConfigToRuntime(
config: PerModelConfig,
options: { isDiffusion?: boolean } = {},
@@ -77,8 +87,8 @@ export function applyPerModelConfigToRuntime(
: (config.disableVision ?? false),
chatTemplateOverride: cleanTemplate(config.chatTemplateOverride),
// GPU Memory knobs are per-model (GGUF-only). Absent = defaults; the mode is a standing
- // preference so an absent mode falls back to the persisted one. The per-GPU split ratio is
- // never remembered. The GPU pick is reconciled against the GPUs present now. A diffusion
+ // preference so an absent mode falls back to the persisted one. The per-GPU split is never
+ // stored. The GPU pick is reconciled against the GPUs present now. A diffusion
// config is sanitized to gpuMemoryMode "auto" because the mode does not apply, not because
// the user chose Auto: writing that into the live standing preference would strand the session
// on Auto, since the load skips saveGpuMemoryMode for diffusion and the next ordinary GGUF
@@ -88,7 +98,7 @@ export function applyPerModelConfigToRuntime(
: (config.gpuMemoryMode ?? readPersistedGpuMemoryMode()),
gpuLayers: config.gpuLayers ?? GPU_LAYERS_AUTO,
nCpuMoe: config.nCpuMoe ?? 0,
- splitRatio: null,
+ splitRatio: options.isDiffusion ? null : cleanTensorSplit(config.tensorSplit),
selectedGpuIds: gpuSelection.ids,
selectedGpuIndexKind: gpuSelection.indexKind,
});
@@ -135,12 +145,13 @@ export function currentRuntimePerModelConfig(
disableVision: s.disableVision ?? false,
chatTemplateOverride: cleanTemplate(s.chatTemplateOverride),
// Snapshot the live GPU knobs too so a failed switch rolls the previous model's GPU Memory
- // settings back. The split ratio is intentionally never remembered.
+ // settings back, split included (never stored).
gpuMemoryMode: s.gpuMemoryMode,
gpuLayers: s.gpuLayers,
nCpuMoe: s.nCpuMoe,
selectedGpuIds: s.selectedGpuIds,
selectedGpuIndexKind: s.selectedGpuIndexKind,
+ tensorSplit: s.splitRatio,
};
}
diff --git a/studio/frontend/src/features/model-picker/model-config/config-signature.ts b/studio/frontend/src/features/model-picker/model-config/config-signature.ts
index 08940d24800..c9506c44bb7 100644
--- a/studio/frontend/src/features/model-picker/model-config/config-signature.ts
+++ b/studio/frontend/src/features/model-picker/model-config/config-signature.ts
@@ -9,7 +9,7 @@
import type { PerModelConfig } from "./per-model-config";
// Serialize the GPU knobs with the store's "absent == default" coalescing: mode auto, gpuLayers
-// Auto (< 0), nCpuMoe 0, and null or absent GPU picks as automatic.
+// Auto (< 0), nCpuMoe 0, null or absent GPU picks as automatic, and no split as the default one.
export function gpuFieldsSignature(config: PerModelConfig): string {
const gpuSelection =
config.selectedGpuIds == null
@@ -27,6 +27,7 @@ export function gpuFieldsSignature(config: PerModelConfig): string {
config.gpuLayers == null || config.gpuLayers < 0 ? -1 : config.gpuLayers,
config.nCpuMoe ?? 0,
gpuSelection,
+ (config.tensorSplit ?? []).join(","),
].join("|");
}
diff --git a/studio/frontend/src/features/model-picker/model-config/per-model-config.ts b/studio/frontend/src/features/model-picker/model-config/per-model-config.ts
index db6eec24216..9fffeccf493 100644
--- a/studio/frontend/src/features/model-picker/model-config/per-model-config.ts
+++ b/studio/frontend/src/features/model-picker/model-config/per-model-config.ts
@@ -51,12 +51,14 @@ export interface PerModelConfig {
* to launch with. */
llamaExtraArgs?: string[] | null;
// GPU Memory controls (per-model, GGUF-only), optional so older blobs parse. Absent or null
- // selectedGpuIds means automatic. --tensor-split is not remembered: it follows the GPU set.
+ // selectedGpuIds means automatic.
gpuMemoryMode?: "auto" | "manual";
gpuLayers?: number;
nCpuMoe?: number;
selectedGpuIds?: number[] | null;
selectedGpuIndexKind?: GpuIndexKind | null;
+ /** --tensor-split in picker order, never stored. `undefined` defers to the store, `null` = default. */
+ tensorSplit?: number[] | null;
}
export const DEFAULT_PER_MODEL_CONFIG: PerModelConfig = {
diff --git a/studio/frontend/tests/gpu-tensor-split.test.ts b/studio/frontend/tests/gpu-tensor-split.test.ts
new file mode 100644
index 00000000000..d3f560b2880
--- /dev/null
+++ b/studio/frontend/tests/gpu-tensor-split.test.ts
@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// GPUs picker per-row share sent as tensor_split (unslothai/unsloth#11474).
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { readSrc } from "./helpers/kit.ts";
+
+const physical = (ids: number[], tensorSplit?: number[] | null) =>
+ ({
+ gpuMemoryMode: "manual",
+ gpuLayers: 40,
+ selectedGpuIds: ids,
+ selectedGpuIndexKind: "physical",
+ tensorSplit,
+ }) as never;
+
+test("a split edit is a config change, so Load and Apply stay reachable", async () => {
+ const { gpuFieldsSignature } = await import(
+ "../src/features/model-picker/model-config/config-signature.ts"
+ );
+ assert.notEqual(
+ gpuFieldsSignature(physical([0, 1], [26, 14])),
+ gpuFieldsSignature(physical([0, 1], [20, 20])),
+ );
+ assert.notEqual(
+ gpuFieldsSignature(physical([0, 1], [26, 14])),
+ gpuFieldsSignature(physical([0, 1], null)),
+ );
+});
+
+test("no split, whether unset or cleared, reads as the default distribution", async () => {
+ const { gpuFieldsSignature } = await import(
+ "../src/features/model-picker/model-config/config-signature.ts"
+ );
+ assert.equal(
+ gpuFieldsSignature(physical([0, 1], null)),
+ gpuFieldsSignature(physical([0, 1], undefined)),
+ );
+});
+
+test("the split is never stored with the model's config", () => {
+ const src = readSrc("features/model-picker/model-config/per-model-config.ts");
+ const stored = src.slice(
+ src.indexOf("const STORED_CONFIG_FIELDS"),
+ src.indexOf("]);", src.indexOf("const STORED_CONFIG_FIELDS")),
+ );
+ assert.doesNotMatch(stored, /tensorSplit/);
+});
+
+test("the picker drops the split when the set changes and carries it on a reorder", () => {
+ const src = readSrc("features/model-picker/components/model-config-page.tsx");
+ const commit = src.slice(src.indexOf("const commitGpuIds"));
+ assert.match(
+ commit.slice(0, 600),
+ /nextSplit: number\[\] \| null = null[\s\S]*tensorSplit: nextSplit/,
+ "a toggle must reset the positional split",
+ );
+ const move = src.slice(src.indexOf("const moveGpu"));
+ assert.match(
+ move.slice(0, 700),
+ /\[nextSplit\[from\], nextSplit\[to\]\] = \[nextSplit\[to\], nextSplit\[from\]\]/,
+ "a reorder must move each share with its GPU",
+ );
+});
+
+test("the shares show only where the backend emits --tensor-split", () => {
+ const src = readSrc("features/model-picker/components/model-config-page.tsx");
+ const gate = src.slice(src.indexOf("const showSplit ="));
+ assert.match(
+ gate.slice(0, 300),
+ /!isDiffusion &&\s*isManual &&\s*!autoLayers &&\s*splitTotal > 0 &&\s*showGpuPicker &&\s*orderedGpuIds\.length > 1/,
+ );
+});
+
+test("the load sends the editor's split, and the dedupe compares it", () => {
+ const src = readSrc("features/chat/hooks/use-chat-model-runtime.ts");
+ assert.match(
+ src,
+ /let loadSplitRatio =\s*pendingLoadConfig\?\.tensorSplit !== undefined\s*\? pendingLoadConfig\.tensorSplit/,
+ );
+ assert.match(src, /loadSplitRatio = pendingLoadConfig\?\.tensorSplit \?\? null;/);
+ assert.match(
+ src,
+ /splitRatio:\s*pendingConfig\?\.tensorSplit !== undefined\s*\? pendingConfig\.tensorSplit/,
+ );
+ const apply = readSrc("features/model-picker/model-config/apply-per-model-config.ts");
+ assert.match(apply, /splitRatio: options\.isDiffusion \? null : cleanTensorSplit\(config\.tensorSplit\)/);
+});
diff --git a/studio/frontend/tests/resident-config-match-accelerator-matrix.test.ts b/studio/frontend/tests/resident-config-match-accelerator-matrix.test.ts
index 709db1d8db6..68ea65f21d7 100644
--- a/studio/frontend/tests/resident-config-match-accelerator-matrix.test.ts
+++ b/studio/frontend/tests/resident-config-match-accelerator-matrix.test.ts
@@ -473,6 +473,8 @@ test("every PerModelConfig field is either compared or deliberately excluded", (
// Qualifies selectedGpuIds rather than adding a dimension of its own: it is read, as
// the reconciler's namespace argument, but /status has no field to compare it against.
"selectedGpuIndexKind",
+ // Compared through standing.splitRatio, which the caller seeds from it.
+ "tensorSplit",
]);
const unclassified = [...declared].filter(
(field) => !compared.has(field) && !excluded.has(field),