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
// 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 {
isRawTextDatasetFormat,
toBackendTrainingType,
} from "../lib/training-methods";
import type { SystemInfoResponse } from "@/hooks/use-system";
import { drafterEligible, drafterRequestFrom } from "../lib/drafter-config";
import type { TrainingStartRequest } from "../types/api";
import type { TrainingConfigState } from "../types/config";
function parseSliceValue(value: string | null): number | null {
if (value == null) return null;
const trimmed = value.trim();
if (!trimmed) return null;
const num = Number(trimmed);
if (!Number.isFinite(num) || !Number.isInteger(num) || num < 0) return null;
return num;
}
// The backend takes a whole number in [0, 1000]; a half-typed or out-of-range field must not 422 the Start.
function normalizeEarlyStoppingPatience(value: number): number {
if (!Number.isFinite(value) || value < 1) return 0;
return Math.min(Math.floor(value), 1000);
}
function buildS3PayloadConfig(config: TrainingConfigState) {
const s3 = config.datasetSource === "s3" ? config.s3Config : null;
if (!s3) {
return null;
}
if (s3.useIamRole) {
return {
bucket: s3.bucket,
region: s3.region,
prefix: s3.prefix,
useIamRole: s3.useIamRole,
};
}
return s3;
}
/** The backend refuses 4-bit for models routed to the latest-transformers sidecar. */
export function trainingLoadsIn4Bit(
config: Pick<TrainingConfigState, "trainingMethod" | "selectedModel">,
): boolean {
const isCpt = config.trainingMethod === "cpt";
const adapterMethod = config.trainingMethod !== "full";
const isQloraMethod = config.trainingMethod === "qlora";
const isFourBitModel = (config.selectedModel ?? "")
.toLowerCase()
.includes("4bit");
return (adapterMethod && isQloraMethod) || (isCpt && isFourBitModel);
}
/** Whether a run can offload layers: LoRA on the main trainer (embedding and decision models
* train elsewhere, and the Whisper / codec audio paths have no decoder stack to stream; an
* audio-input vision model such as Gemma 3n/4 does) with gradient checkpointing on, which
* swapped layers need. */
export function offloadSupported(
config: Pick<
TrainingConfigState,
| "trainingMethod"
| "isEmbeddingModel"
| "isAudioModel"
| "isVisionModel"
| "modelType"
| "gradientCheckpointing"
>,
): boolean {
return (
config.trainingMethod !== "full" &&
!config.isEmbeddingModel &&
(!config.isAudioModel || config.isVisionModel) &&
config.modelType !== "embeddings" &&
config.modelType !== "decision" &&
config.gradientCheckpointing !== "none"
);
}
/** Whether this host can swap layers to system RAM, by core's install_block_swap rule: a CUDA or
* ROCm backend with at least one card that is not a unified-memory APU (XPU, MLX and CPU have no
* swap path). True until `/api/system` answers; the backend refuses the same cases itself. */
export function offloadHardwareSupported(
system: Pick<SystemInfoResponse, "status" | "device_backend" | "gpu"> | null | undefined,
): boolean {
if (!system || system.status !== "ready") return true;
if (system.device_backend !== "cuda" && system.device_backend !== "rocm") return false;
const devices = system.gpu?.devices ?? [];
return devices.length === 0 || devices.some((device) => device.unified_memory !== true);
}
/** The offload fields, sent off wherever the controls are hidden. `gpuIndices` are the GPUs
* training can see; with more than one, the budget goes out per card. */
export function offloadPayload(
config: Pick<
TrainingConfigState,
| "trainingMethod"
| "isEmbeddingModel"
| "isAudioModel"
| "isVisionModel"
| "modelType"
| "gradientCheckpointing"
| "offloadLayers"
| "offloadVramGb"
| "offloadVramGbPerDevice"
| "prefetchDepth"
>,
gpuIndices: readonly number[] = [],
system: Parameters<typeof offloadHardwareSupported>[0] = null,
): Pick<
TrainingStartRequest,
"offload_layers" | "offload_vram_gb" | "offload_vram_gb_per_device" | "prefetch_depth"
> {
const layers = !(offloadSupported(config) && offloadHardwareSupported(system))
? 0
: config.offloadLayers === "auto"
? "auto"
: Math.min(1024, Math.max(0, Math.floor(config.offloadLayers || 0)));
const depth =
config.prefetchDepth === "auto"
? "auto"
: Math.min(8, Math.max(1, Math.floor(config.prefetchDepth || 2)));
const multi = gpuIndices.length > 1;
return {
offload_layers: layers,
// The budget only sizes "auto"; with a fixed count or off it would cap the run for nothing.
// Several cards hide the single input, so a value left in it from a one-card setup is not sent.
offload_vram_gb:
!multi && layers === "auto" && config.offloadVramGb && config.offloadVramGb > 0
? config.offloadVramGb
: null,
offload_vram_gb_per_device:
multi && layers === "auto"
? perDeviceBudgetPayload(config.offloadVramGbPerDevice, gpuIndices)
: null,
prefetch_depth: depth,
};
}
/** Entry i is GPU index i's budget, null where a card has none; null when no card has one. */
export function perDeviceBudgetPayload(
perDevice: Record<string, number | null> | undefined,
gpuIndices: readonly number[],
): (number | null)[] | null {
const valid = gpuIndices.filter((i) => Number.isInteger(i) && i >= 0);
if (!valid.length) return null;
const out: (number | null)[] = Array.from({ length: Math.max(...valid) + 1 }, () => null);
let any = false;
for (const i of valid) {
const gb = perDevice?.[String(i)];
if (typeof gb === "number" && gb > 0 && gb <= 4096) {
out[i] = gb;
any = true;
}
}
return any ? out : null;
}
/** The GPU indices training sees, from the torch inventory in `/api/system`. */
export function trainingGpuIndices(
gpu: { available?: boolean; devices?: { index?: number | null }[] } | null | undefined,
): number[] {
if (!gpu?.available) return [];
return (gpu.devices ?? [])
.map((d) => d.index)
.filter((i): i is number => typeof i === "number");
}
export function buildTrainingStartPayload(
config: TrainingConfigState,
hfToken: string | null,
system: SystemInfoResponse | null = null,
// The platform store's isCpuTrainingHost(): settled with the health verdict, unlike /api/system.
cpuTrainingHost = false,
): TrainingStartRequest {
const isDecision = config.modelType === "decision";
// Laya trains in 16-bit (LoRA or full); Clef and an LLM decision model also take QLoRA.
const hasLlmBackbone =
isDecision &&
(config.decisionLayout === "clef" || config.decisionLayout === "llm");
const trainingMethod =
isDecision &&
config.trainingMethod !== "full" &&
!(hasLlmBackbone && config.trainingMethod === "qlora")
? "lora"
: config.trainingMethod;
const isCpt = trainingMethod === "cpt";
const adapterMethod = trainingMethod !== "full";
const loraVariants = adapterMethod && !isDecision;
const _selectedModelLower = (config.selectedModel ?? "").toLowerCase();
// DeepSeek OCR ignores user-selected image size; do not send it.
const isDeepseekOcr =
_selectedModelLower.includes("deepseek") &&
_selectedModelLower.includes("ocr");
const isEmbedding =
config.isEmbeddingModel || config.modelType === "embeddings";
const isRawText = isRawTextDatasetFormat(config.datasetFormat);
const hfDataset =
config.datasetSource === "huggingface" ? config.dataset : null;
const localDatasets =
config.datasetSource === "upload" && config.uploadedFile
? [config.uploadedFile]
: [];
const s3Config = buildS3PayloadConfig(config);
const customFormatMapping: Record<string, unknown> | undefined =
!isDecision && Object.keys(config.datasetManualMapping).length > 0
? { ...config.datasetManualMapping }
: undefined;
const hasAdvisorMeta =
config.datasetSystemPrompt ||
Object.keys(config.datasetLabelMapping).length > 0;
if (customFormatMapping && hasAdvisorMeta) {
if (config.datasetSystemPrompt) {
customFormatMapping.__system_prompt = config.datasetSystemPrompt;
}
if (Object.keys(config.datasetLabelMapping).length > 0) {
customFormatMapping.__label_mapping = config.datasetLabelMapping;
}
}
return {
model_name: config.selectedModel ?? "",
project_name: (config.projectName || "").trim() || null,
training_type: toBackendTrainingType(trainingMethod),
hf_token: hfToken,
model_known_cached: config.modelKnownCached,
model_local_path: config.modelKnownCached ? config.modelLocalPath : null,
model_format: config.modelFormat,
load_in_4bit: trainingLoadsIn4Bit({ ...config, trainingMethod }),
// Hidden for decision runs: Laya always trains at 1024 tokens, Clef and LLMs at the recipe's length.
max_seq_length: isDecision && !hasLlmBackbone ? 1024 : config.contextLength,
vision_image_size:
config.isVisionModel && config.isDatasetImage === true && !isDeepseekOcr
? config.visionImageSize
: null,
trust_remote_code: config.trustRemoteCode ?? false,
approved_remote_code_fingerprint:
config.approvedRemoteCodeFingerprint ?? null,
hf_dataset: hfDataset,
dataset_known_cached:
hfDataset && !config.datasetStreaming ? config.datasetKnownCached : false,
dataset_local_path:
hfDataset && !config.datasetStreaming ? config.datasetLocalPath : null,
subset: hfDataset ? config.datasetSubset : null,
train_split: hfDataset ? config.datasetSplit : null,
eval_split: hfDataset ? config.datasetEvalSplit : null,
dataset_streaming:
hfDataset && !isDecision ? config.datasetStreaming : false,
dataset_slice_start: parseSliceValue(config.datasetSliceStart),
dataset_slice_end: parseSliceValue(config.datasetSliceEnd),
local_datasets: localDatasets,
local_eval_datasets:
config.datasetSource === "upload" && config.uploadedEvalFile
? [config.uploadedEvalFile]
: [],
s3_config: s3Config,
format_type: config.datasetFormat,
custom_format_mapping: customFormatMapping,
num_epochs: config.epochs,
learning_rate: String(config.learningRate),
embedding_learning_rate:
isCpt && config.embeddingLearningRate != null
? config.embeddingLearningRate
: null,
batch_size: config.batchSize,
gradient_accumulation_steps: config.gradientAccumulation,
warmup_steps: isEmbedding ? null : config.warmupSteps,
warmup_ratio: isEmbedding ? 0.03 : null,
max_steps: config.maxSteps,
save_steps: config.saveSteps,
eval_steps: config.evalSteps,
early_stopping_patience:
config.evalSteps > 0 && !isDecision && !isEmbedding
? normalizeEarlyStoppingPatience(config.earlyStoppingPatience)
: 0,
weight_decay: config.weightDecay,
// max_grad_norm omitted on purpose: the backend honors an explicit value. Guarded by
// tests/training-start-payload-grad-norm.test.ts.
max_grad_value: null,
random_seed: config.randomSeed,
packing: isEmbedding || isDecision ? false : config.packing,
// Laya's recipe needs torch AdamW; Clef keeps its recipe's (8-bit) optimizer.
optim:
isDecision && config.decisionLayout !== "clef"
? "adamw_torch"
: config.optimizerType,
lr_scheduler_type: config.lrSchedulerType,
use_lora: adapterMethod,
lora_r: config.loraRank,
lora_alpha: config.loraAlpha,
lora_dropout: config.loraDropout,
target_modules: adapterMethod ? config.targetModules : [],
gradient_checkpointing: config.gradientCheckpointing,
...offloadPayload(config, trainingGpuIndices(system?.gpu), system),
use_rslora: loraVariants && config.loraVariant === "rslora",
use_loftq: loraVariants && config.loraVariant === "loftq",
use_dora: loraVariants && config.loraVariant === "dora",
// CPT always trains on full sequences (no chat format masking)
train_on_completions:
isEmbedding || isDecision || isCpt || isRawText
? false
: config.trainOnCompletions,
finetune_vision_layers: config.finetuneVisionLayers,
finetune_language_layers: config.finetuneLanguageLayers,
finetune_attention_modules: config.finetuneAttentionModules,
finetune_mlp_modules: config.finetuneMLPModules,
is_dataset_image: isEmbedding ? false : !!config.isDatasetImage,
// The decision trainer reads its rows itself; this flag selects the chat audio path.
is_dataset_audio: isEmbedding || isDecision ? false : config.isDatasetAudio,
is_embedding: isEmbedding && !isDecision,
is_decision: isDecision,
model_subfolder: isDecision ? config.modelSubfolder : null,
enable_wandb: config.enableWandb,
wandb_token: config.enableWandb ? config.wandbToken.trim() || null : null,
wandb_project: config.enableWandb
? config.wandbProject.trim() || null
: null,
enable_tensorboard: config.enableTensorboard,
tensorboard_dir: config.enableTensorboard
? config.tensorboardDir.trim() || null
: null,
// Spread only when sent: a run without a drafter posts exactly the fields it did before.
...(sendsDrafter(config, system, cpuTrainingHost)
? { drafter: drafterRequestFrom(config) }
: {}),
};
}
/** On, a run type with a drafter phase, not MLX or the CPU backend, and not a model the backend said cannot train one.
* A capability check still pending (or for a previous model) sends it: the backend re-checks the
* model before the drafter phase and reports a warning instead of dropping the request silently. */
export function sendsDrafter(
config: TrainingConfigState,
system: SystemInfoResponse | null = null,
cpuTrainingHost = false,
): boolean {
const capability = config.drafterCapability;
const refused =
capability !== null &&
capability.model_name === config.selectedModel &&
!capability.supported &&
!capability.inconclusive;
return (
config.drafterEnabled &&
drafterEligible(config) &&
system?.device_backend !== "mlx" &&
!cpuTrainingHost &&
system?.device_backend !== "cpu" &&
!refused
);
}