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
fix(studio): load audio GGUFs selected from custom folders (#13897)
Lee Jackson67f7ab90f3d3
diff --git a/studio/backend/core/inference/audio_cpp_models.py b/studio/backend/core/inference/audio_cpp_models.pyindex 18b905470e0..12ca49c25be 100644--- a/studio/backend/core/inference/audio_cpp_models.py+++ b/studio/backend/core/inference/audio_cpp_models.py@@ -1704,12 +1704,7 @@ def match_variant(wanted: Optional[str],folder: str = "",) -> Optional[AudioCppVariant]:- """The variant ``wanted`` names: its key, its file, or a quant that picks one row.-- A bare quant shared by several rows (ACE-Step ``turbo/Q8_0`` and ``base/Q8_0``) picks the default- ordering's first, which is what the folder row loads by default. ``folder`` is the row's folder in- the repo, whose own name never counts as a scope word.- """+ """match a key, file, or quant; shared quants use default order; row folders are not scopes."""text = (wanted or "").strip().replace("\\", "/")if not text:return None@@ -1717,9 +1712,12 @@ def match_variant(for variant in variants:if variant.key.lower() == low:return variant- for variant in variants:- main = variant.main_file.lower()- if main == low or main.rsplit("/", 1)[-1] in (low, f"{low}.gguf"):+ mains = [(variant, variant.main_file.replace("\\", "/").lower()) for variant in variants]+ for variant, main in mains:+ if main == low:+ return variant+ for variant, main in mains:+ if main.endswith(f"/{low}") or main.rsplit("/", 1)[-1] in (low, f"{low}.gguf"):return variantquant = low.rsplit("/", 1)[-1]matches = [@@ -1730,7 +1728,7 @@ def match_variant(]if matches:return sorted(matches, key = _variant_rank)[0]- # A sub-folder alone (legacy ``.../PocketTTS-GGUF/english``).+ # support legacy requests that name only a subfolder, such as PocketTTS-GGUF/english.scoped = [v for v in variants if v.key.lower().startswith(low + "/")]if scoped:return sorted(scoped, key = _variant_rank)[0]diff --git a/studio/backend/tests/test_audio_cpp_models.py b/studio/backend/tests/test_audio_cpp_models.pyindex 8057a74b43c..d1cca1ebe52 100644--- a/studio/backend/tests/test_audio_cpp_models.py+++ b/studio/backend/tests/test_audio_cpp_models.py@@ -3077,3 +3077,69 @@ def test_samsone_is_refused_for_transcription(hub):with pytest.raises(SttModelIdError, match = "describes audio"):s.resolve_audio_cpp_stt_model(f"{AUDIO_CPP_REPO}/Samsone-GGUF")assert f"{AUDIO_CPP_REPO}/Samsone-GGUF" not in s.downloaded_model_ids()+++ "family,filename",+ [("breeze_tts", "breeze-tts-2-q8_0.gguf"), ("dots_tts", "dots-tts-soar-q8_0.gguf")],+)+def test_audio_page_local_filename_pick_uses_audio_cpp(hub, tmp_path, family, filename):+ from hub.services.models.gguf_variants import get_gguf_variants_response+ from utils.models.model_config import ModelConfig++ folder = tmp_path / "portable-audio-models" / family+ folder.mkdir(parents = True)+ weights = folder / filename+ weights.write_bytes(_gguf_bytes(family = family))+ listing = asyncio.run(get_gguf_variants_response(str(folder)))+ selected = next(v for v in listing.variants if v.filename == filename)+ config = ModelConfig.from_identifier(str(folder), gguf_variant = selected.filename)++ assert config.audio_type == "audiocpp_tts"+ assert config.audio_cpp is not None+ assert config.audio_cpp.family == family+ assert config.path == str(weights)+ assert config.is_gguf is False # audio.cpp bypasses llama-server+++def test_audio_page_split_symlink_alias_keeps_its_resolved_target(hub, tmp_path):+ from utils.models.model_config import ModelConfig++ real = tmp_path / "real"+ real.mkdir()+ first = real / "model-Q8_0-00001-of-00002.gguf"+ first.write_bytes(_gguf_bytes(family = "breeze_tts"))+ (real / "model-Q8_0-00002-of-00002.gguf").write_bytes(b"GGUF")+ links = tmp_path / "links"+ links.mkdir()+ alias = links / "alias-Q8_0-00001-of-00002.gguf"+ try:+ alias.symlink_to(first)+ except OSError:+ pytest.skip("this filesystem or account cannot create symlinks")++ config = ModelConfig.from_identifier(str(links), gguf_variant = alias.name)++ assert config.audio_type == "audiocpp_tts"+ assert config.audio_cpp.family == "breeze_tts"+ assert config.path == str(first)+++def test_filename_variant_matches_a_windows_local_primary():+ filename = "breeze-tts-2-q8_0.gguf"+ variant = AudioCppVariant(+ "Q8_0",+ (RepoFile(filename),),+ rf"C:\models\breeze_tts\{filename}",+ )++ assert acm.match_variant((variant,), filename) is variant+ assert acm.match_variant((variant,), f"breeze_tts/{filename}") is variant+++def test_exact_audio_filename_path_wins_over_an_earlier_suffix_match():+ filename = "model-Q8_0.gguf"+ archived = AudioCppVariant("archive/Q8_0", (RepoFile(filename),), f"archive/chosen/{filename}")+ exact = AudioCppVariant("chosen/Q8_0", (RepoFile(filename),), f"chosen/{filename}")++ assert acm.match_variant((archived, exact), f"chosen/{filename}") is exactdiff --git a/studio/backend/tests/test_gguf_variants_local_resolution.py b/studio/backend/tests/test_gguf_variants_local_resolution.pyindex 2dbdd826717..723ac7355b4 100644--- a/studio/backend/tests/test_gguf_variants_local_resolution.py+++ b/studio/backend/tests/test_gguf_variants_local_resolution.py@@ -725,3 +725,83 @@ def test_loadable_variants_stays_unanswered_for_an_unstatable_direct_file(in_tmp# is_file() cannot express this: it raises here, and answers False from 3.14.monkeypatch.setattr(gguf_variants.Path, "is_file", lambda self: False)assert gguf_variants._loadable_variants(os.fspath(gguf), variants) is None++[email protected]("selector", ["chosen-Q8_0.gguf", "CHOSEN-q8_0.GGUF"])+def test_directory_load_accepts_the_pickers_exact_filename(tmp_path, selector):+ from utils.models.model_config import ModelConfig++ # Both files share a quant, so matching only Q8_0 could load the wrong weights.+ (tmp_path / "aaa-Q8_0.gguf").write_bytes(b"GGUF")+ chosen = tmp_path / "chosen-Q8_0.gguf"+ chosen.write_bytes(b"GGUF")++ config = ModelConfig.from_identifier(str(tmp_path), gguf_variant = selector)+ assert config.is_gguf+ assert config.gguf_file == str(chosen)++[email protected]("separator", ["/", "\\"])+def test_directory_filename_selector_preserves_its_subdirectory(tmp_path, separator):+ from utils.models.model_config import _find_local_gguf_by_variant++ for directory in ("first", "chosen"):+ folder = tmp_path / directory+ folder.mkdir()+ (folder / "model-Q8_0.gguf").write_bytes(b"GGUF")+ selected = _find_local_gguf_by_variant(str(tmp_path), f"chosen{separator}model-Q8_0.gguf")+ assert selected == str(tmp_path / "chosen/model-Q8_0.gguf")+ assert _find_local_gguf_by_variant(str(tmp_path), "missing/model-Q8_0.gguf") is None++[email protected](os.name == "nt", reason = "Windows reserves backslash as a separator")+def test_literal_backslash_filename_wins_over_separator_fallback(tmp_path):+ from utils.models.model_config import _find_local_gguf_by_variant++ literal = tmp_path / "chosen\\model-Q8_0.gguf"+ literal.write_bytes(b"GGUF")+ nested = tmp_path / "chosen" / "model-Q8_0.gguf"+ nested.parent.mkdir()+ nested.write_bytes(b"GGUF")++ assert _find_local_gguf_by_variant(str(tmp_path), literal.name) == str(literal)+++def test_exact_filename_spelling_wins_over_casefold_fallback(tmp_path):+ from utils.models.model_config import _find_local_gguf_by_variant++ upper = tmp_path / "Model-Q8_0.gguf"+ upper.write_bytes(b"GGUF")+ lower = tmp_path / "model-Q8_0.gguf"+ lower.write_bytes(b"GGUF")+ if upper.samefile(lower):+ pytest.skip("filesystem is case-insensitive")++ assert _find_local_gguf_by_variant(str(tmp_path), lower.name) == str(lower)+++def test_split_filename_selector_loads_the_first_shard(tmp_path):+ from utils.models.model_config import _find_local_gguf_by_variant++ first = tmp_path / "model-Q8_0-00001-of-00002.gguf"+ second = tmp_path / "model-Q8_0-00002-of-00002.gguf"+ first.write_bytes(b"GGUF")+ second.write_bytes(b"GGUF")+ assert _find_local_gguf_by_variant(str(tmp_path), second.name) == str(first)+++ "filename", ["mmproj-F16.gguf", "mtp-model-Q8_0.gguf", "stories260K-be.gguf"]+)+def test_exact_filename_does_not_admit_auxiliary_or_big_endian_ggufs(tmp_path, filename):+ from utils.models.model_config import _find_local_gguf_by_variant+ (tmp_path / filename).write_bytes(b"GGUF")+ assert _find_local_gguf_by_variant(str(tmp_path), filename) is None+++def test_loose_file_variant_lookup_accepts_its_filename(tmp_path):+ from utils.models.model_config import _find_local_gguf_by_variant++ model = tmp_path / "model-Q8_0.gguf"+ model.write_bytes(b"GGUF")+ assert _find_local_gguf_by_variant(str(model), model.name) == str(model)diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.pyindex 3160264a7b2..ed52b8967e9 100644--- a/studio/backend/utils/models/model_config.py+++ b/studio/backend/utils/models/model_config.py@@ -3315,31 +3315,21 @@ def _direct_gguf_for_variant(variant: str,model_root: Optional[str] = None,) -> Optional[str]:- """A loose ``.gguf`` file resolved by the quant it already is, or None.-- A marker-less parent leaves ``detect_gguf_model`` loading the file itself, so a- request naming its own quant must resolve too, or load and gate disagree. Only that- one label matches (companions still refused); any other quant finds nothing.-- Case-insensitive, mirroring llama.cpp's own resolution (``_gguf_files_for_variant``):- a lowercase ``--gguf-variant`` must resolve here too, or the load evicts the resident- model on the transformers path before failing.- """+ """resolve a ``.gguf`` by case-insensitive filename or quant labels to match load gating."""f = Path(path).expanduser()if f.suffix.lower() != ".gguf" or not f.is_file():return Nonecontext = f"{f.parent.name}/{f.name}"quant = _extract_quant_label(context)fallback_variant = re.sub(r"-\d{3,}-of-\d{3,}$", "", f.name.rsplit(".", 1)[0])- # The hub extractor drops the -bpw modifier, so accept the shorter label it advertises.+ # the hub extractor drops the -bpw modifier, so accept its shorter advertised label.stripped = re.sub(r"-[0-9]+(?:\.[0-9]+)?bpw$", "", quant, flags = re.IGNORECASE)- # The listing can also name it by another of its own tokens (the hub extractor prefers the- # K-quant in F16-checkpoint-Q4_K_M), and only this file could be meant, so any token resolves.+ # accept any token because the hub extractor prefers K-quants in composite filenames.stem_tokens = [f"{m.group(1) or ''}{m.group(2)}"for m in _GGUF_KNOWN_QUANT_RE.finditer(fallback_variant.rsplit("/", 1)[-1])]- if not _variant_matches(variant, quant, fallback_variant, stripped, *stem_tokens):+ if not _variant_matches(variant, f.name, quant, fallback_variant, stripped, *stem_tokens):return Nonereturn detect_gguf_model(str(f), model_root)@@ -3349,13 +3339,7 @@ def _find_local_gguf_by_variant(variant: str,model_root: Optional[str] = None,) -> Optional[str]:- """Find the GGUF file in *directory* matching a quantization *variant*.-- For sharded GGUFs (multiple files sharing a quant label), returns the- first shard (sorted by name), which is what ``llama-server -m`` expects.-- Returns the absolute path, or ``None`` if no match.- """+ """match a GGUF quant, stem, or relative filename and return llama-server's first shard."""p = _resolve_gguf_dir(Path(directory))if p is None:return _direct_gguf_for_variant(directory, variant, model_root)@@ -3365,9 +3349,18 @@ def _find_local_gguf_by_variant(else _registered_custom_model_root(directory))- # Recurse so variants under a quant-named subdir (``BF16/foo-BF16-00001-of-00002.gguf``)- # are found. Match the relative path so the quant label can come from the dir name.+ # preserve Audio variant paths during recursive search to prevent basename cross-matches+ literal_selector = str(variant)+ path_selector = literal_selector.replace("\\", "/")+ selectors = (+ (literal_selector,)+ if path_selector == literal_selector+ else (literal_selector, path_selector)+ )matches = []+ literal_exact = []+ literal_casefold = []+ path_exact = []owned = []for f in _iter_gguf_files(p, recursive = True):rel = f.relative_to(p).as_posix()@@ -3375,26 +3368,38 @@ def _find_local_gguf_by_variant(continuequant = _extract_quant_label(rel)fallback_variant = re.sub(r"-\d{3,}-of-\d{3,}$", "", rel.rsplit(".", 1)[0])- # Listings advertise the bpw-stripped spelling, and the hub extractor can prefer another- # token of the same BASENAME (F16-checkpoint-Q4_K_M advertises Q4_K_M), so both label this- # file -- but never a parent's quant: Q8_0/model-Q4_K_M.gguf IS the Q4_K_M file.+ # bpw-stripped labels and basename quant tokens identify the file, never a parent quant.stripped = re.sub(r"-[0-9]+(?:\.[0-9]+)?bpw$", "", quant, flags = re.IGNORECASE)basename_stem = fallback_variant.rsplit("/", 1)[-1]stem_tokens = [f"{m.group(1) or ''}{m.group(2)}" for m in _GGUF_KNOWN_QUANT_RE.finditer(basename_stem)]- if not _variant_matches(- variant, quant, fallback_variant, stripped, *stem_tokens+ labels = (rel, quant, fallback_variant, stripped, *stem_tokens)+ if not any(+ _variant_matches(selector, *labels) for selector in selectors) or _is_big_endian_gguf_path(rel, quant):continuematches.append(f)- # A repo holding several checkpoints at one quant offers a row per checkpoint,- # and only one of them is this variant's. Name order alone would hand a request- # for the repo-root ``Q6_K`` the alphabetically earlier ``distilled/`` copy.- if _variant_matches(variant, _gguf_variant_key(rel)):+ # exact ownership prevents a repo-root quant from selecting an earlier subdirectory copy.+ if literal_selector == rel:+ literal_exact.append(f)+ elif _variant_matches(literal_selector, rel):+ literal_casefold.append(f)+ elif path_selector == rel:+ path_exact.append(f)+ elif _variant_matches(path_selector, rel, _gguf_variant_key(rel)):owned.append(f)matches.sort()+ literal_exact.sort()+ literal_casefold.sort()+ path_exact.sort()owned.sort()+ if literal_exact:+ return str(_local_gguf_load_path(literal_exact[0]))+ if literal_casefold:+ return str(_local_gguf_load_path(literal_casefold[0]))+ if path_exact:+ return str(_local_gguf_load_path(path_exact[0]))if owned:return str(_local_gguf_load_path(owned[0]))if matches:@@ -5025,14 +5030,7 @@ class ModelConfig:gguf_hint: Optional[str] = None,gguf_file: Optional[str] = None,) -> Optional["ModelConfig"]:- """A GGUF only audio.cpp runs, as a speech or music config for the native-audio worker.-- Called three ways: up front for an umbrella folder id (``audio-cpp/audio.cpp-gguf/<Folder>``,- which no repo probe below can read), for a local GGUF once found, and for a Hub repo once- its GGUF is known. The last two read the file's header, so an ordinary llama.cpp GGUF- returns None here at the cost of one header read. Raises ``ValueError`` for an audio.cpp- model Studio cannot run in this slot (speech-to-text, an unsupported task or variant).- """+ """resolves umbrella or header-checked audio.cpp GGUFs; raises ValueError if unsupported."""try:from core.inference import audio_cpp_modelsexcept Exception: # noqa: BLE001 - no audio.cpp support, no audio.cpp id@@ -5042,13 +5040,15 @@ class ModelConfig:if header is None or not header.is_audio_cpp:return Nonetarget = gguf_file+ resolved_variant = Path(gguf_file).nameelif gguf_hint is None and not audio_cpp_models.is_umbrella_id(identifier):return Noneelse:target = identifier+ resolved_variant = gguf_variantmodel = audio_cpp_models.resolve(target,- gguf_variant,+ resolved_variant,hf_token,network = not _env_offline(),gguf_hint = gguf_hint,