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.

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.py
index 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 variant
quant = 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.py
index 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 exact
diff --git a/studio/backend/tests/test_gguf_variants_local_resolution.py b/studio/backend/tests/test_gguf_variants_local_resolution.py
index 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.py
index 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 None
context = 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 None
return 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(
continue
quant = _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):
continue
matches.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_models
except 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 None
target = gguf_file
+ resolved_variant = Path(gguf_file).name
elif gguf_hint is None and not audio_cpp_models.is_umbrella_id(identifier):
return None
else:
target = identifier
+ resolved_variant = gguf_variant
model = audio_cpp_models.resolve(
target,
- gguf_variant,
+ resolved_variant,
hf_token,
network = not _env_offline(),
gguf_hint = gguf_hint,