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.

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.py
index 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 FastModel
diff --git a/studio/backend/core/inference/inference.py b/studio/backend/core/inference/inference.py
index 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_model
abs_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 on
diff --git a/studio/backend/tests/test_spark_tts_adapter_base.py b/studio/backend/tests/test_spark_tts_adapter_base.py
new file mode 100644
index 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.py
index 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 False
try:
setattr(config, attribute, repo_id)
diff --git a/studio/backend/utils/models/spark_tts_adapter.py b/studio/backend/utils/models/spark_tts_adapter.py
new file mode 100644
index 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)