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.

7.2 KB
Raw Blame
// 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 { validateHubResourceId } from "@/components/resource-picker/hub-resource-id";
import type { TranslationKey } from "@/i18n";
import { isAdapterMethod } from "@/types/training";
import type { TrainingConfigState } from "../types/config";
import { requiresExplicitCachedDatasetSplit } from "./dataset-split-policy";
import {
  validateManualDatasetSplit,
  validateManualDatasetSubset,
} from "./manual-dataset-options";
import { isLocalTrainingModelSelection } from "./model-selection";
import { isUntrainableModelFormat } from "./model-support";
import {
  isTrainingLoraVariantSupportedOnDevice,
  isTrainingModelTypeSupportedOnDevice,
} from "./training-methods";

export type StartValidationResult =
  | { ok: true; errorKey: null }
  | { ok: false; errorKey: TranslationKey };

function isTrainingConfigSupportedOnDevice(
  config: TrainingConfigState,
  deviceType?: string,
): boolean {
  if (!isTrainingModelTypeSupportedOnDevice(config.modelType, deviceType)) {
    return false;
  }
  if (
    !isTrainingLoraVariantSupportedOnDevice(
      config.loraVariant,
      config.trainingMethod,
      deviceType,
    )
  ) {
    return false;
  }
  if (deviceType !== "mac") {
    return true;
  }
  // MLX trains audio only as input to an audio-capable vision-language model (Gemma 3n/4).
  const audioVlm = config.isVisionModel && config.isAudioModel;
  return !(
    config.isEmbeddingModel ||
    (hasChatAudioRows(config, deviceType) && !audioVlm)
  );
}

/** A Mac Clef (or Clef-head LLM) trainer reads its own audio rows; elsewhere, and for Laya, they train as text. */
function hasChatAudioRows(
  config: TrainingConfigState,
  deviceType?: string,
): boolean {
  const trainerReadsRows =
    deviceType === "mac" &&
    config.modelType === "decision" &&
    (config.decisionLayout === "clef" || config.decisionLayout === "llm");
  return config.isDatasetAudio === true && !trainerReadsRows;
}

export function hasIncompatibleTrainingModalities(
  config: TrainingConfigState,
  deviceType?: string,
): boolean {
  return (
    (!config.isVisionModel && config.isDatasetImage === true) ||
    // Unknown means tokenizer_config.json was unreadable (gated, offline), not that audio is
    // missing; let the run fail on the real download error.
    (!config.audioCapabilityUnknown &&
      !config.isAudioModel &&
      hasChatAudioRows(config, deviceType))
  );
}

export function validateS3Source(
  config: TrainingConfigState,
): StartValidationResult {
  // Audio manifests are rewritten to downloaded paths (#4539); image references are not.
  if (config.modelType === "vision" || config.isVisionModel) {
    return {
      ok: false,
      errorKey: "studio.training.validation.s3MultimodalUnsupported",
    };
  }
  const s3 = config.s3Config;
  if (!s3 || !s3.bucket.trim()) {
    return {
      ok: false,
      errorKey: "studio.training.validation.s3BucketRequired",
    };
  }
  const hasKeys = Boolean(s3.accessKeyId && s3.secretAccessKey);
  if (!s3.useIamRole && !hasKeys) {
    return {
      ok: false,
      errorKey: "studio.training.validation.s3CredentialsRequired",
    };
  }
  return { ok: true, errorKey: null };
}

function validateDatasetSelection(
  config: TrainingConfigState,
): StartValidationResult {
  if (config.datasetSource === "huggingface") {
    if (!config.dataset) {
      return {
        ok: false,
        errorKey: "studio.training.validation.hfDatasetRequired",
      };
    }
    if (!validateHubResourceId(config.dataset).ok) {
      return {
        ok: false,
        errorKey: "studio.datasetPicker.reasonInvalidHubId",
      };
    }
    if (config.manualDatasetOptionsValid === false) {
      return {
        ok: false,
        errorKey: "studio.dataset.selectors.manualInvalid",
      };
    }
    const requiresSplit = requiresExplicitCachedDatasetSplit(config);
    if (requiresSplit) {
      return {
        ok: false,
        errorKey: "studio.training.validation.hfDatasetSplitRequired",
      };
    }
    if (
      validateManualDatasetSubset(config.datasetSubset ?? "") !== null ||
      validateManualDatasetSplit(
        config.datasetSplit ?? "",
        false,
        !config.datasetStreaming,
      ) !== null ||
      validateManualDatasetSplit(
        config.datasetEvalSplit ?? "",
        false,
        !config.datasetStreaming,
      ) !== null
    ) {
      return {
        ok: false,
        errorKey: "studio.dataset.selectors.manualInvalid",
      };
    }
  } else if (config.datasetSource === "upload") {
    if (!config.uploadedFile) {
      return {
        ok: false,
        errorKey: "studio.training.validation.localDatasetRequired",
      };
    }
  } else if (config.datasetSource === "s3") {
    return validateS3Source(config);
  } else {
    return {
      ok: false,
      errorKey: "studio.training.validation.unsupportedDatasetSource",
    };
  }

  return { ok: true, errorKey: null };
}

export function validateTrainingConfig(
  config: TrainingConfigState,
  deviceType?: string,
  isOwner = true,
): StartValidationResult {
  if (!config.selectedModel) {
    return {
      ok: false,
      errorKey: "studio.training.validation.modelRequired",
    };
  }
  if (
    !isLocalTrainingModelSelection({
      model: config.selectedModel,
      knownCached: config.modelKnownCached,
      localPath: config.modelLocalPath,
    }) &&
    !validateHubResourceId(config.selectedModel).ok
  ) {
    return {
      ok: false,
      errorKey: "studio.modelPicker.reasonInvalidHubId",
    };
  }
  if (isUntrainableModelFormat(config.modelFormat)) {
    if (config.modelFormat === "gguf") {
      return { ok: false, errorKey: "studio.modelPicker.reasonGguf" };
    }
    // Adapter format is valid when continuing LoRA / CPT from a saved adapter (#13140).
    // Decision and embedding runs build a fresh adapter, so they need a base.
    // Only a saved local adapter folder is continued; a Hub adapter repo is not yet.
    if (
      !isAdapterMethod(config.trainingMethod) ||
      !isLocalTrainingModelSelection({
        model: config.selectedModel,
        knownCached: config.modelKnownCached,
        localPath: config.modelLocalPath,
      }) ||
      config.modelType === "decision" ||
      config.isEmbeddingModel
    ) {
      return { ok: false, errorKey: "studio.modelPicker.reasonAdapter" };
    }
  }

  if (!isTrainingConfigSupportedOnDevice(config, deviceType)) {
    return {
      ok: false,
      errorKey: "studio.params.notSupportedAppleSilicon",
    };
  }
  if (config.modelType === "decision" && !isOwner) {
    return {
      ok: false,
      errorKey: "studio.training.validation.decisionOwnerOnly",
    };
  }

  if (!Number.isFinite(config.learningRate) || config.learningRate <= 0) {
    return {
      ok: false,
      errorKey: "studio.training.validation.learningRatePositive",
    };
  }
  if (
    config.trainingMethod === "cpt" &&
    config.embeddingLearningRate != null &&
    (!Number.isFinite(config.embeddingLearningRate) ||
      config.embeddingLearningRate <= 0 ||
      config.embeddingLearningRate >= 1)
  ) {
    return {
      ok: false,
      errorKey: "studio.training.validation.embeddingLearningRateRange",
    };
  }

  return validateDatasetSelection(config);
}