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
Studio: keep Spark-TTS LoRA checkpoints exportable (#13424)
Daniel Han071e87e7d7b0
diff --git a/studio/backend/core/export/export.py b/studio/backend/core/export/export.pyindex 0468fff846b..aec6246850d 100644--- a/studio/backend/core/export/export.py+++ b/studio/backend/core/export/export.py@@ -875,17 +875,22 @@ class ExportBackend:elif self._audio_type == "bicodec":from unsloth import FastModel+ from utils.models.spark_tts_adapter import spark_tts_adapter_load_target+logger.info("Loading as BiCodec (Spark-TTS) audio model...")- model, tokenizer = FastModel.from_pretrained(- model_name = checkpoint_path,- max_seq_length = max_seq_length,- dtype = None if _IS_MLX else torch.float32,- load_in_4bit = False,- trust_remote_code = trust_remote_code,- token = token,- local_files_only = local_files_only,- **_device_map_kw,- )+ with spark_tts_adapter_load_target(+ checkpoint_path, hf_token = token, local_files_only = local_files_only+ ) as load_target:+ model, tokenizer = FastModel.from_pretrained(+ model_name = load_target,+ max_seq_length = max_seq_length,+ dtype = None if _IS_MLX else torch.float32,+ load_in_4bit = False,+ trust_remote_code = trust_remote_code,+ token = token,+ local_files_only = local_files_only,+ **_device_map_kw,+ )elif self._audio_type == "dac":from unsloth import FastModeldiff --git a/studio/backend/core/inference/inference.py b/studio/backend/core/inference/inference.pyindex b41c88432e5..102f33e74ec 100644--- a/studio/backend/core/inference/inference.py+++ b/studio/backend/core/inference/inference.py@@ -747,6 +747,8 @@ class InferenceBackend:if config.is_lora and config.base_model:# LoRA adapter: base_model is .../Spark-TTS-0.5B/LLM;# BiCodec weights live in the parent dir.+ from utils.models.spark_tts_adapter import spark_tts_adapter_load_target+base_path = config.base_modelabs_repo_path = audio_codec_path or resolve_bicodec_repo_path(base_path, hf_token = hf_token@@ -755,16 +757,19 @@ class InferenceBackend:logger.info(f"Spark-TTS LoRA: loading adapter from {config.path}, BiCodec from {abs_repo_path}")- model, tokenizer = FastModel.from_pretrained(- config.path,- dtype = torch.float32,- # Flash Attention cannot run float32- attn_implementation = "sdpa",- load_in_4bit = False,- device_map = device_map,- token = _hf_token_for_loader(hf_token),- trust_remote_code = trust_remote_code,- )+ with spark_tts_adapter_load_target(+ config.path, hf_token = _hf_token_for_loader(hf_token)+ ) as load_target:+ model, tokenizer = FastModel.from_pretrained(+ load_target,+ dtype = torch.float32,+ # Flash Attention cannot run float32+ attn_implementation = "sdpa",+ load_in_4bit = False,+ device_map = device_map,+ token = _hf_token_for_loader(hf_token),+ trust_remote_code = trust_remote_code,+ )elif config.is_local and os.path.isdir(config.path):# A merged export saves the LLM straight into the export directory, so# there is no repo to download and no LLM/ child. snapshot_download ondiff --git a/studio/backend/tests/test_spark_tts_adapter_base.py b/studio/backend/tests/test_spark_tts_adapter_base.pynew file mode 100644index 00000000000..02c3b289f70--- /dev/null+++ b/studio/backend/tests/test_spark_tts_adapter_base.py@@ -0,0 +1,131 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Spark-TTS LoRA checkpoints must stay exportable (#13411).++Spark-TTS trains from ``<snapshot>/LLM``. Rewriting that pinned path to the bare repo id dropped the+subfolder, so adapter_config.json named a repo root with no config.json and every export failed.+"""++import json+import sys+from pathlib import Path+from types import SimpleNamespace++sys.path.insert(0, str(Path(__file__).resolve().parent.parent))++import huggingface_hub # noqa: E402++from utils.models.spark_tts_adapter import spark_tts_adapter_load_target # noqa: E402+from utils.models.model_identity import restore_hf_cache_repo_identity # noqa: E402+++_SNAPSHOT = (+ "/home/user/.cache/huggingface/hub/models--unsloth--Spark-TTS-0.5B/snapshots/0123456789abcdef"+)+++def test_pinned_spark_tts_llm_subfolder_keeps_its_path():+ llm = f"{_SNAPSHOT}/LLM"+ config = SimpleNamespace(_name_or_path = llm)+ adapter_config = SimpleNamespace(base_model_name_or_path = llm)+ model = SimpleNamespace(+ config = config, name_or_path = llm, peft_config = {"default": adapter_config}+ )++ restored = restore_hf_cache_repo_identity(+ model, _SNAPSHOT, expected_repo_id = "unsloth/Spark-TTS-0.5B"+ )++ assert restored is None+ assert config._name_or_path == llm+ assert model.name_or_path == llm+ assert adapter_config.base_model_name_or_path == llm+++def test_snapshot_root_with_trailing_separator_is_still_restored():+ config = SimpleNamespace(_name_or_path = _SNAPSHOT + "/")+ restored = restore_hf_cache_repo_identity(+ SimpleNamespace(config = config), _SNAPSHOT, expected_repo_id = "unsloth/Spark-TTS-0.5B"+ )+ assert restored == "unsloth/Spark-TTS-0.5B"+ assert config._name_or_path == "unsloth/Spark-TTS-0.5B"+++def _spark_repo(root: Path) -> Path:+ (root / "LLM").mkdir(parents = True)+ (root / "LLM" / "config.json").write_text('{"model_type": "qwen2"}', encoding = "utf-8")+ (root / "config.yaml").write_text("sample_rate: 16000\n", encoding = "utf-8")+ return root+++def _checkpoint(path: Path, base: str) -> Path:+ path.mkdir(parents = True)+ adapter = {"base_model_name_or_path": base, "r": 8, "peft_type": "LORA"}+ (path / "adapter_config.json").write_text(json.dumps(adapter), encoding = "utf-8")+ (path / "adapter_model.safetensors").write_bytes(b"weights")+ (path / "tokenizer_config.json").write_text("{}", encoding = "utf-8")+ (path / "optimizer.pt").write_bytes(b"optimizer state")+ return path+++def test_legacy_adapter_naming_repo_root_loads_through_llm_subfolder(tmp_path):+ repo = _spark_repo(tmp_path / "Spark-TTS-0.5B")+ ckpt = _checkpoint(tmp_path / "checkpoint-30", str(repo))+ original = (ckpt / "adapter_config.json").read_bytes()++ with spark_tts_adapter_load_target(str(ckpt)) as target:+ staged = Path(target)+ assert staged != ckpt+ config = json.loads((staged / "adapter_config.json").read_text(encoding = "utf-8"))+ assert config["base_model_name_or_path"] == str(repo / "LLM")+ assert config["r"] == 8+ assert (staged / "adapter_model.safetensors").read_bytes() == b"weights"+ assert (staged / "tokenizer_config.json").is_file()+ assert not (staged / "optimizer.pt").exists()++ assert not staged.exists()+ assert (ckpt / "adapter_config.json").read_bytes() == original+++def test_legacy_adapter_naming_hub_repo_id_uses_cached_snapshot(tmp_path, monkeypatch):+ snapshot = _spark_repo(tmp_path / "snapshot")+ ckpt = _checkpoint(tmp_path / "checkpoint-30", "unsloth/Spark-TTS-0.5B")+ calls = []++ def fake_snapshot_download(repo_id, **kwargs):+ calls.append((repo_id, kwargs))+ return str(snapshot)++ monkeypatch.setattr(huggingface_hub, "snapshot_download", fake_snapshot_download)++ with spark_tts_adapter_load_target(str(ckpt), hf_token = False, local_files_only = True) as target:+ config = json.loads((Path(target) / "adapter_config.json").read_text(encoding = "utf-8"))+ assert config["base_model_name_or_path"] == str(snapshot / "LLM")++ assert calls[0][0] == "unsloth/Spark-TTS-0.5B"+ assert calls[0][1]["token"] is False+ assert calls[0][1]["local_files_only"] is True+++def test_loadable_bases_and_non_adapters_are_unchanged(tmp_path, monkeypatch):+ repo = _spark_repo(tmp_path / "Spark-TTS-0.5B")+ llm_ckpt = _checkpoint(tmp_path / "llm_base", str(repo / "LLM"))+ plain = tmp_path / "plain_base"+ plain.mkdir()+ (plain / "config.json").write_text('{"model_type": "qwen2"}', encoding = "utf-8")+ (plain / "LLM").mkdir()+ (plain / "LLM" / "config.json").write_text("{}", encoding = "utf-8")+ plain_ckpt = _checkpoint(tmp_path / "plain_ckpt", str(plain))+ merged = tmp_path / "merged"+ merged.mkdir()++ def offline_failure(repo_id, **kwargs):+ raise OSError("offline")++ monkeypatch.setattr(huggingface_hub, "snapshot_download", offline_failure)+ unresolvable = _checkpoint(tmp_path / "unresolvable", "unsloth/Spark-TTS-0.5B")++ for path in (llm_ckpt, plain_ckpt, merged, unresolvable):+ with spark_tts_adapter_load_target(str(path)) as target:+ assert target == str(path)diff --git a/studio/backend/utils/models/model_identity.py b/studio/backend/utils/models/model_identity.pyindex 3f6699b857f..df554f32821 100644--- a/studio/backend/utils/models/model_identity.py+++ b/studio/backend/utils/models/model_identity.py@@ -43,8 +43,22 @@ def _snapshot_repo_id(value: Any) -> Optional[str]:return hf_cache_repo_id(identifier) if has_revision else None+def _is_snapshot_root(value: Any) -> bool:+ identifier = _identifier(value)+ if not identifier:+ return False+ parts = identifier.replace("\\", "/").split("/")+ for index, part in enumerate(parts):+ if part.startswith("models--") and parts[index + 1 : index + 2] == ["snapshots"]:+ return not any(parts[index + 3 :])+ return False++def _set_standard_identity(config: Any, attribute: str, repo_id: str) -> bool:- if config is None or not _cache_path_matches_repo(getattr(config, attribute, None), repo_id):+ value = getattr(config, attribute, None) if config is not None else None+ # A path inside the snapshot (Spark-TTS loads <snapshot>/LLM) is not the repo root, so the repo id would lose the+ # subfolder and point PEFT at a root with no config.json (#13411).+ if not _cache_path_matches_repo(value, repo_id) or not _is_snapshot_root(value):return Falsetry:setattr(config, attribute, repo_id)diff --git a/studio/backend/utils/models/spark_tts_adapter.py b/studio/backend/utils/models/spark_tts_adapter.pynew file mode 100644index 00000000000..9772e0217f2--- /dev/null+++ b/studio/backend/utils/models/spark_tts_adapter.py@@ -0,0 +1,95 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Load Spark-TTS LoRA checkpoints whose adapter_config.json names the repo root instead of LLM/."""++from __future__ import annotations++import contextlib+import json+import os+import shutil+import tempfile+from pathlib import Path+from typing import Optional++from loggers import get_logger++logger = get_logger(__name__)+++_ADAPTER_VIEW_SKIP = ("optimizer", "scheduler", "rng_state", "training_args")+++def _spark_tts_llm_dir(+ base: str, hf_token: Optional[str] | bool, local_files_only: Optional[bool]+) -> Optional[Path]:+ """``<base>/LLM`` when ``base`` is a Spark-TTS repo root (no config.json of its own), else None."""+ if not base or base.replace("\\", "/").rstrip("/").lower().endswith("/llm"):+ return None+ root = Path(base).expanduser()+ if not root.is_dir():+ from huggingface_hub import snapshot_download+ from utils.hf_cache_settings import active_hf_hub_cache+ from utils.utils import hf_env_offline++ root = Path(+ snapshot_download(+ base,+ allow_patterns = ["config.json", "LLM/*"],+ token = False if hf_token is False else (hf_token or None),+ cache_dir = active_hf_hub_cache(),+ local_files_only = hf_env_offline() if local_files_only is None else local_files_only,+ )+ )+ llm = root / "LLM"+ if (root / "config.json").is_file() or not (llm / "config.json").is_file():+ return None+ return llm+++def spark_tts_adapter_load_target(+ checkpoint_path: str,+ *,+ hf_token: Optional[str] | bool = None,+ local_files_only: Optional[bool] = None,+):+ """Yield a path FastModel.from_pretrained can load a Spark-TTS checkpoint from.++ Adapters saved before #13411 name the repo root (no config.json) as their base; they load through a temporary+ copy whose adapter_config.json names LLM/, leaving the checkpoint untouched.+ """+ checkpoint = Path(checkpoint_path).expanduser()+ llm = None+ try:+ adapter_config = json.loads(+ (checkpoint / "adapter_config.json").read_text(encoding = "utf-8")+ )+ base = str(adapter_config.get("base_model_name_or_path") or "").strip()+ llm = _spark_tts_llm_dir(base, hf_token, local_files_only)+ except Exception as e: # noqa: BLE001 -- unresolvable keeps the original load and its error+ logger.debug(f"Spark-TTS adapter base not redirected: {e}")+ if llm is None:+ yield checkpoint_path+ return++ staged = Path(tempfile.mkdtemp(prefix = "unsloth_spark_adapter_"))+ try:+ for item in checkpoint.iterdir():+ if not item.is_file() or item.name == "adapter_config.json":+ continue+ if item.name.startswith(_ADAPTER_VIEW_SKIP):+ continue+ try:+ os.link(item, staged / item.name)+ except OSError:+ shutil.copy2(item, staged / item.name)+ adapter_config["base_model_name_or_path"] = str(llm)+ (staged / "adapter_config.json").write_text(+ json.dumps(adapter_config, indent = 2), encoding = "utf-8"+ )+ logger.info(f"Spark-TTS adapter base {base} has no config.json; loading it from {llm}")+ yield str(staged)+ finally:+ shutil.rmtree(staged, ignore_errors = True)