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: list every GGUF build that shares a quant in a custom folder (#13957)

oobaboogadb0e78c150bc
diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index ad5e2c2a79a..3d556ab9888 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -42,6 +42,9 @@ class _LocalGgufEntry:
is_gguf: bool = True # False routes the load to the inference orchestrator
repo_level_companions: bool = False
aliases: tuple[tuple[str, str], ...] = () # see _legacy_variant_aliases
+ withheld: tuple[str, ...] = () # listed build keys that cannot be served (torn split sets)
+ build_aliases: tuple[tuple[str, str], ...] = () # see _build_family_aliases
+ exact_builds: bool = False # custom folder: a build-shaped suffix names one file, never a tag
_CACHE_TTL_S = 5.0
@@ -342,6 +345,30 @@ def _legacy_variant_aliases(variants) -> tuple[tuple[str, str], ...]:
return ()
+def _build_family_aliases(variants) -> tuple[tuple[str, str], ...]:
+ """``(file family, current key)`` per custom-folder build: a stem key a build was advertised
+ under keeps naming it after a sibling's removal hands it the bare quant key."""
+ try:
+ from hub.utils.gguf import gguf_variant_family
+
+ current = {str(v.quant).lower() for v in variants if getattr(v, "quant", None)}
+ seen: dict[str, Optional[str]] = {}
+ for variant in variants:
+ quant = getattr(variant, "quant", None)
+ filename = getattr(variant, "filename", None)
+ if not quant or not filename:
+ continue
+ relative = str(filename).replace("\\", "/")
+ # the family (beta-Q4_K_M) and the filename key a collision falls back to (F16.gguf)
+ for spelling in {gguf_variant_family(relative).lower(), relative.lower()}:
+ if not spelling or spelling in current:
+ continue
+ seen[spelling] = None if spelling in seen else str(quant)
+ return tuple((family, quant) for family, quant in seen.items() if quant is not None)
+ except Exception:
+ return ()
+
+
def _local_gguf_entry(
loader_id: str,
info,
@@ -418,6 +445,21 @@ def _local_gguf_entry(
offered, _ = inventory_variants(str(load_dir))
complete_files = {str(v.filename).casefold() for v in offered if v.quant in complete}
variants = [v for v in variants if str(v.filename).casefold() in complete_files]
+ withheld: tuple[str, ...] = ()
+ if cache_repo_dir is None:
+ listed = variants
+ variants = [
+ variant
+ for variant in variants
+ if getattr(variant, "filename", None)
+ and _split_set_is_loadable(Path(load_dir) / variant.filename)
+ ]
+ kept = {str(v.quant).lower() for v in variants if getattr(v, "quant", None)}
+ withheld = tuple(
+ str(v.quant).lower()
+ for v in listed
+ if getattr(v, "quant", None) and str(v.quant).lower() not in kept
+ )
quants = tuple(v.quant for v in variants if getattr(v, "quant", None))
if not quants:
return None
@@ -429,15 +471,45 @@ def _local_gguf_entry(
# preferred_quant is order-sensitive: rank only default_gguf_scope, or a sibling checkpoint can win.
from hub.utils.gguf import default_gguf_scope
- best = preferred_quant(
- default_gguf_scope(
- quants,
- getattr(info, "id", None),
- getattr(info, "model_id", None),
- loader_id,
- str(cache_repo_dir) if cache_repo_dir is not None else None,
- )
+ scope = default_gguf_scope(
+ quants,
+ getattr(info, "id", None),
+ getattr(info, "model_id", None),
+ loader_id,
+ str(cache_repo_dir) if cache_repo_dir is not None else None,
)
+ best = preferred_quant(scope)
+ from hub.utils.gguf import gguf_variant_key
+
+ legacy_groups: dict[str, int] = {}
+ for variant in variants:
+ legacy = gguf_variant_key(variant.filename).casefold()
+ legacy_groups[legacy] = legacy_groups.get(legacy, 0) + 1
+ if any(count > 1 for count in legacy_groups.values()):
+ try:
+ detected = detect_gguf_model(str(load_dir))
+ relative = (
+ Path(detected).relative_to(Path(load_dir)).as_posix() if detected else None
+ )
+ preferred = next((v for v in variants if v.quant == best), None)
+ preferred_group = (
+ gguf_variant_key(preferred.filename).casefold() if preferred else None
+ )
+ # detection only breaks ties between builds of the preferred quant
+ selected = next(
+ (
+ variant
+ for variant in variants
+ if variant.filename == relative
+ and gguf_variant_key(variant.filename).casefold() == preferred_group
+ and legacy_groups.get(preferred_group, 0) > 1
+ ),
+ None,
+ )
+ if selected is not None and selected.quant in scope:
+ best = selected.quant
+ except (OSError, RuntimeError, ValueError):
+ pass
if best and quants[0] != best:
quants = (best, *(q for q in quants if q != best))
return _LocalGgufEntry(
@@ -446,6 +518,9 @@ def _local_gguf_entry(
quants,
repo_level_companions = cache_repo_dir is not None,
aliases = _legacy_variant_aliases(variants),
+ withheld = withheld,
+ build_aliases = _build_family_aliases(variants) if cache_repo_dir is None else (),
+ exact_builds = cache_repo_dir is None,
)
except Exception:
return None
@@ -1329,14 +1404,17 @@ def _resolve_from_index(
for v in entry.variants:
if v.lower() == wanted:
return _result(entry, v)
+ # a listed build that cannot be served misses, never answered by a sibling or alias
+ if wanted in entry.withheld:
+ return None
# ahead of both branches below: one refuses a retired spelling, the other answers it
# with a different quant
- for legacy, current in entry.aliases:
+ for legacy, current in (*entry.aliases, *entry.build_aliases):
if legacy == wanted:
return _result(entry, current)
from core.inference.openai_auto_download import looks_like_quant
- if looks_like_quant(variant):
+ if looks_like_quant(variant) or _names_missing_build(entry, wanted):
return None
# ":latest" or ":8b" names no file, so it means the repo; a real quant that is not on disk still misses, or a
# swap would serve the wrong weights.
@@ -1345,6 +1423,18 @@ def _resolve_from_index(
return None
+def _split_set_is_loadable(path) -> bool:
+ """Whether the loader finds a complete shard set here or, like it, behind a shard-1 symlink."""
+ from utils.models.model_config import colocated_split_shards
+
+ if colocated_split_shards(path)[1]:
+ return True
+ try:
+ return path.is_symlink() and colocated_split_shards(path.resolve())[1]
+ except OSError:
+ return False
+
+
def local_gguf_pinned_variant(requested: str, allow_scan: bool = True) -> Optional[str]:
"""The on-disk quant ``repo:VARIANT`` pins, by current label or legacy alias, else None.
@@ -1364,12 +1454,56 @@ def local_gguf_pinned_variant(requested: str, allow_scan: bool = True) -> Option
for variant in entry.variants:
if variant.lower() == wanted:
return variant
- for legacy, current in entry.aliases:
+ if wanted in entry.withheld:
+ return None
+ for legacy, current in (*entry.aliases, *entry.build_aliases):
if legacy == wanted:
return current
return None
+def _names_missing_build(entry: _LocalGgufEntry, wanted: str) -> bool:
+ """Whether *wanted* is a custom-folder build stem (``beta-Q4_K_M``) no indexed build answers."""
+ from core.inference.openai_auto_download import looks_like_quant
+ from hub.utils.gguf import extract_quant_token
+
+ return (
+ entry.exact_builds
+ and ("/" in wanted or not looks_like_quant(wanted))
+ and extract_quant_token(wanted) is not None
+ and all(v.lower() != wanted for v in entry.variants)
+ and all(legacy != wanted for legacy, _ in (*entry.aliases, *entry.build_aliases))
+ )
+
+
+def local_gguf_same_build(base: Optional[str], resident: str, wanted: str) -> bool:
+ """Whether *resident* names *wanted*, verbatim or through *base*'s index (a build loaded by
+ its stem, ``alpha-Q4_K_M``, is the build the bare key ``Q4_K_M`` now names)."""
+ resident = (resident or "").strip().lower()
+ wanted = (wanted or "").strip().lower()
+ if resident == wanted:
+ return True
+ if not base or not resident:
+ return False
+ canonical = local_gguf_pinned_variant(f"{base}:{resident}", allow_scan = False)
+ return canonical is not None and canonical.lower() == wanted
+
+
+def local_gguf_withheld(requested: str) -> bool:
+ """Whether ``repo:BUILD`` names a build the last index cannot serve: torn, or no longer there."""
+ base, sep, wanted = requested.rpartition(":")
+ if not sep:
+ return False
+ try:
+ entry = _snapshot()[1].get(base.strip().lower())
+ except Exception:
+ return False
+ if entry is None:
+ return False
+ wanted = wanted.strip().lower()
+ return wanted in entry.withheld or _names_missing_build(entry, wanted)
+
+
def local_target_is_gguf(load_path: Optional[str], loader_id: Optional[str] = None) -> bool:
"""Whether an auto-switch target is served by llama.cpp rather than the orchestrator.
diff --git a/studio/backend/core/inference/media_model_index.py b/studio/backend/core/inference/media_model_index.py
index 83121d0fa25..51adacf0561 100644
--- a/studio/backend/core/inference/media_model_index.py
+++ b/studio/backend/core/inference/media_model_index.py
@@ -180,7 +180,8 @@ def _add_gguf_picks(
one id cannot mean different weights here than in the picker.
"""
from core.inference.openai_auto_download import preferred_quant
- from hub.utils.gguf import default_gguf_scope
+ from hub.utils.gguf import default_gguf_scope, gguf_variant_family, gguf_variant_key
+ from hub.utils.gguf import list_local_gguf_variants as list_build_variants
from utils.models.model_config import list_local_gguf_variants
if load_dir.is_file():
@@ -199,7 +200,9 @@ def _add_gguf_picks(
)
return True
# filenames come back relative to this directory, which is what the loader joins them onto
- variants, _ = list_local_gguf_variants(str(load_dir))
+ variants, _ = list_build_variants(str(load_dir))
+ legacy_variants, _ = list_local_gguf_variants(str(load_dir))
+ legacy_quants = {variant.filename: variant.quant for variant in legacy_variants}
by_quant = {v.quant: v for v in variants if v.quant}
if not by_quant:
return False
@@ -211,15 +214,76 @@ def _add_gguf_picks(
}
if not openable:
return True
+ primary_keys: dict[str, str] = {}
for quant, variant in openable.items():
# model_id stays the bare id so a "not found" error lists models, not one row per quant
+ names = [f"{key}:{quant}" for key in keys]
+ primary_keys.update((name.strip().lower(), variant.filename) for name in names)
_register(
index,
- [f"{key}:{quant}" for key in keys],
+ names,
MediaModelPick(keys[0], load_path, variant.filename, "gguf"),
)
+ for quant, variant in openable.items():
+ legacy_quant = legacy_quants.get(variant.filename)
+ if legacy_quant and legacy_quant.lower() != quant.lower():
+ names = [
+ name
+ for name in (f"{key}:{legacy_quant}" for key in keys)
+ if primary_keys.get(name.strip().lower(), variant.filename) == variant.filename
+ ]
+ _register(
+ index,
+ names,
+ MediaModelPick(keys[0], load_path, variant.filename, "gguf"),
+ )
+ # a build's stem or filename key keeps naming it after a sibling's removal re-keys it
+ claims: dict[str, list[str]] = {}
+ for quant, variant in openable.items():
+ relative = variant.filename.replace("\\", "/")
+ for spelling in {gguf_variant_family(relative), relative}:
+ if spelling and spelling.lower() != quant.lower():
+ claims.setdefault(spelling.lower(), []).append(variant.filename)
+ for spelling, files in claims.items():
+ if len(set(files)) != 1:
+ continue
+ names = [
+ name
+ for name in (f"{key}:{spelling}" for key in keys)
+ if primary_keys.get(name.strip().lower(), files[0]) == files[0]
+ ]
+ _register(index, names, MediaModelPick(keys[0], load_path, files[0], "gguf"))
scope = default_gguf_scope(list(openable), *keys, getattr(info, "id", None), str(on_disk))
- best = preferred_quant(scope) or scope[0]
+ best = None
+ legacy_groups: dict[str, int] = {}
+ for variant in openable.values():
+ legacy = gguf_variant_key(variant.filename).lower()
+ legacy_groups[legacy] = legacy_groups.get(legacy, 0) + 1
+ try:
+ root = Path(load_path)
+ if root.is_dir():
+ from utils.models.model_config import detect_gguf_model
+
+ detected = detect_gguf_model(load_path)
+ relative = Path(detected).relative_to(root).as_posix() if detected else None
+ preferred = preferred_quant(scope) or scope[0]
+ preferred_group = gguf_variant_key(openable[preferred].filename).lower()
+ # detection only breaks ties between builds of the preferred quant
+ selected = next(
+ (
+ quant
+ for quant, variant in openable.items()
+ if variant.filename == relative
+ and gguf_variant_key(variant.filename).lower() == preferred_group
+ and legacy_groups.get(preferred_group, 0) > 1
+ ),
+ None,
+ )
+ if selected in scope:
+ best = selected
+ except (OSError, RuntimeError, ValueError, KeyError):
+ pass
+ best = best or preferred_quant(scope) or scope[0]
_register(
index,
keys,
@@ -447,6 +511,9 @@ def resident_is_pick(status: dict[str, Any], name: str, pick: MediaModelPick) ->
)
if pick.model_kind != "gguf" and not resident_is_gguf(status):
return True
+ resident_filename = str(status.get("gguf_filename") or "").strip()
+ if resident_filename:
+ return os.path.normcase(resident_filename) == os.path.normcase(pick.gguf_filename or "")
loaded_quant = str(status.get("gguf_variant") or "").strip().lower()
return loaded_quant == published_token(pick)
@@ -471,8 +538,8 @@ def satisfied_by(status: dict[str, Any], name: str, pick: MediaModelPick) -> boo
"""
if not resident_is_pick(status, name, pick):
return False
- # ambiguity only blocks the skip, never the "did my load land" check: the reload settles it
- return not pick.ambiguous
+ # only a resident filename can tell same-token builds apart; without one ambiguity blocks the skip
+ return not pick.ambiguous or bool(str(status.get("gguf_filename") or "").strip())
def expected_partition(pick: MediaModelPick) -> Optional[str]:
diff --git a/studio/backend/hub/services/models/gguf_variants.py b/studio/backend/hub/services/models/gguf_variants.py
index 5809d108dec..fe2b49558f6 100644
--- a/studio/backend/hub/services/models/gguf_variants.py
+++ b/studio/backend/hub/services/models/gguf_variants.py
@@ -37,6 +37,7 @@ from hub.utils.hf_cache_state import (
from hub.utils.gguf import (
GgufVariantInfo,
extract_quant_label,
+ gguf_variant_family,
gguf_variant_key,
iter_hf_cache_snapshots,
is_big_endian_gguf_path,
@@ -1065,28 +1066,28 @@ class VariantsAnswer(NamedTuple):
# False when the caller may not read this repo's caches, for a reader that falls back
# to the repo id rather than ``context_source``.
cache_authorized: bool = True
- # Per-quant copy the listing answered from, for a reader that resolves each row's metadata
- # from the quant's own cache rather than one shared directory.
+ # per-quant source for resolving row metadata when one shared directory cannot answer
variant_context_sources: Optional[dict[str, str]] = None
def _default_variant_candidates(variants, repo_id: Optional[str] = None) -> list[str]:
- """Filenames the automatic default may be picked from: ``default_gguf_scope`` of the rows.
-
- Every branch here must apply it: ``pick_best_gguf`` is order-sensitive among equal siblings.
- """
+ """return scoped filenames in the order used by the automatic default picker."""
return [v.filename for v in default_gguf_scope(variants, repo_id, key = lambda v: v.quant)]
+def _default_variant_key(variants, repo_id: Optional[str] = None) -> Optional[str]:
+ """return the listed default key because custom-folder builds can share a derived quant key."""
+ best = pick_best_gguf(_default_variant_candidates(variants, repo_id))
+ if not best:
+ return None
+ listed = next((v.quant for v in variants if v.filename == best and v.quant), None)
+ return listed or gguf_variant_key(best)
+
+
async def _audio_cpp_variants_answer(
repo_id: str, hf_token: Optional[str], offline: bool
) -> Optional[VariantsAnswer]:
- """The listing for an audio.cpp umbrella folder row or package repo, else None.
-
- An umbrella folder (``audio-cpp/audio.cpp-gguf/<Folder>``) is not a repo the generic lister can
- read, and a package's quants are component mixes plus config files, which grouping GGUFs by quant
- would split into meaningless rows. Single-file audio.cpp repos list like any GGUF repo.
- """
+ """group audio.cpp umbrella and package components; generic single-file repos return None."""
from core.inference import audio_cpp_models
text = (repo_id or "").strip()
@@ -1424,20 +1425,71 @@ async def get_gguf_variants_answer(
variants,
has_vision: bool,
complete = None,
+ context_root: Optional[str] = None,
) -> GgufVariantsResponse:
- """*complete* is the set of quants whose shards are all on disk; None reports every row
- downloaded. A quant short a shard stays listed to resume or delete, but is not offered
- as ready, since the loader would ask llama-server for files that are not there.
- """
+ """mark *complete* quants ready, keep incomplete rows manageable, and treat None as all ready."""
def _downloaded(v) -> bool:
- # An unlabelled quant cannot be judged, so it is kept as ready.
+ # unlabelled quants cannot be judged and remain ready
return complete is None or not v.quant or v.quant in complete
- # The default comes from the ready rows; with none ready every row is the fallback.
+ if context_root:
+ # absolute, since detect_gguf_model answers absolute paths for a relative id
+ root = Path(context_root).expanduser().absolute()
+ source_root = root.parent if root.is_file() else root
+ rows_by_legacy_key: dict[str, list] = {}
+ for variant in variants:
+ if variant.quant and variant.filename:
+ rows_by_legacy_key.setdefault(
+ gguf_variant_key(variant.filename).lower(), []
+ ).append(variant)
+ for rows in rows_by_legacy_key.values():
+ if len(rows) < 2:
+ continue
+ for variant in rows:
+ if not _downloaded(variant):
+ continue
+ source = source_root / variant.filename
+ if source.is_file():
+ variant_context_sources[variant.quant.lower()] = str(source)
+
ready = [v for v in variants if _downloaded(v)]
- best = pick_best_gguf(_default_variant_candidates(ready or variants, repo_id))
- default_variant = gguf_variant_key(best) if best else None
+ default_variant = _default_variant_key(ready or variants, repo_id)
+ if context_root:
+ if any(len(rows) > 1 for rows in rows_by_legacy_key.values()):
+ try:
+ from utils.models.model_config import detect_gguf_model
+
+ detected = detect_gguf_model(str(root))
+ relative = (
+ Path(detected).relative_to(source_root).as_posix() if detected else None
+ )
+ preferred = next(
+ (v for v in ready or variants if v.quant == default_variant), None
+ )
+ preferred_group = (
+ gguf_variant_key(preferred.filename).lower() if preferred else None
+ )
+ # detection only breaks ties between builds of the preferred quant
+ selected = next(
+ (
+ variant
+ for variant in ready or variants
+ if variant.filename == relative
+ and gguf_variant_key(variant.filename).lower() == preferred_group
+ and len(rows_by_legacy_key.get(preferred_group, [])) > 1
+ ),
+ None,
+ )
+ # the loader-detected row only wins inside the bare id's default scope
+ if (
+ selected is not None
+ and selected.filename
+ in _default_variant_candidates(ready or variants, repo_id)
+ ):
+ default_variant = selected.quant
+ except (OSError, RuntimeError, ValueError):
+ pass
return GgufVariantsResponse(
repo_id = response_repo_id,
@@ -1468,8 +1520,7 @@ async def get_gguf_variants_answer(
def _partial_local_response(
response_repo_id: str, variants, has_vision: bool
) -> GgufVariantsResponse:
- best = pick_best_gguf(_default_variant_candidates(variants, repo_id))
- default_variant = gguf_variant_key(best) if best else None
+ default_variant = _default_variant_key(variants, repo_id)
return GgufVariantsResponse(
repo_id = response_repo_id,
variants = [
@@ -1627,8 +1678,7 @@ async def get_gguf_variants_answer(
return response
variants.extend(extra)
ready = [v for v in variants if v.downloaded and not v.partial]
- best = pick_best_gguf(_default_variant_candidates(ready or variants, repo_id))
- default_variant = gguf_variant_key(best) if best else None
+ default_variant = _default_variant_key(ready or variants, repo_id)
return response.model_copy(
update = {
"variants": variants,
@@ -1636,11 +1686,7 @@ async def get_gguf_variants_answer(
}
)
- # Load-path parity: from_identifier resolves existence-first, so a marker-less relative name that
- # exists here is a local model, not a Hub id, and a direct .gguf file loads without the metadata
- # siblings. It normalizes first, so every question below asks about the same path: under WSL
- # C:\models\qwen maps to /mnt/c/models/qwen, and probing the raw spelling would report a working
- # model unloadable.
+ # normalize once so discovery and loading classify relative, WSL, and direct GGUF paths alike
local_id = _loader_normalize_path(repo_id) if is_local_path(repo_id) else repo_id
local_target = None
try:
@@ -1651,6 +1697,25 @@ async def get_gguf_variants_answer(
local_target = None
if local_target is not None:
variants, has_vision = list_local_gguf_variants(local_id)
+ if local_target.is_file():
+ # the loader opens this file whatever variant is named: same-quant siblings would load it
+ # by shard-stripped family: a split row is listed under its first shard
+ target_family = gguf_variant_family(local_target.name).lower()
+ chosen = next(
+ (
+ v
+ for v in variants
+ if gguf_variant_family(Path(v.filename).name).lower() == target_family
+ ),
+ None,
+ )
+ if chosen is not None:
+ chosen_key = gguf_variant_key(chosen.filename).lower()
+ variants = [
+ v
+ for v in variants
+ if v is chosen or gguf_variant_key(v.filename).lower() != chosen_key
+ ]
# The load id is this path, so a scan-torn quant is still ready when the file the resolver binds opens fine.
complete = _complete_with_servable(local_id, _complete_quants_under(local_id), variants)
if (
@@ -1685,7 +1750,9 @@ async def get_gguf_variants_answer(
answered_locally[0] = True
# Surface the resolution so the CLI gate matches the local resolver's exact labels rather than the
# id's shape, and no client mirrors its grammar.
- return _local_response(repo_id, variants, has_vision, complete).model_copy(
+ return _local_response(
+ repo_id, variants, has_vision, complete, context_root = local_id
+ ).model_copy(
update = {
"resolved_locally": True,
"loadable_variants": _loadable_variants(local_id, variants),
@@ -1807,7 +1874,7 @@ async def get_gguf_variants_answer(
)
return _locally_resolved(response, snapshot) if offline else response
if local_path and is_local_path(local_path):
- # A named Hub snapshot remains a cache read, even on the filesystem fallback.
+ # named Hub snapshots remain cache reads during filesystem fallback
cached_ref = cached_repo_ref_for_path(local_path)
if cached_ref is not None and hub_cached_read_refused(
hf_token,
@@ -1820,9 +1887,12 @@ async def get_gguf_variants_answer(
variants, has_vision = list_local_gguf_variants(local_path)
if variants or has_vision:
answered_from[0] = local_path
- # Same reason as the is_local_path branch above.
+ # torn quants remain ready when their resolver-selected files are servable
+ complete = _complete_with_servable(
+ local_path, _complete_quants_under(local_path), variants
+ )
return _local_response(
- repo_id, variants, has_vision, _complete_quants_under(local_path)
+ repo_id, variants, has_vision, complete, context_root = local_path
)
partial = _quants_from_state(repo_id, hub_cache) if cache_reads_authorized else None
if partial is not None:
@@ -1886,12 +1956,10 @@ async def get_gguf_variants_answer(
return fallback
raise
- # siblings is None only when the lister answered from its own repo-wide cache; falling through is
- # deliberate, since readiness still counts against this request's own cache.
+ # repo-wide cache answers still use this request's cache to determine readiness
if siblings is None:
if not cache_reads_authorized:
- # `variants` is already the cache's answer, so declining a second one is
- # not enough; falling through would serialize the first.
+ # falling through would expose the first cache answer despite rejecting the second read
raise HTTPException(
status_code = 404,
detail = "No GGUF variants available without Hub authorization.",
@@ -1900,17 +1968,13 @@ async def get_gguf_variants_answer(
if fallback is not None:
return fallback
- best = pick_best_gguf(_default_variant_candidates(variants, repo_id))
- default_variant = gguf_variant_key(best) if best else None
+ default_variant = _default_variant_key(variants, repo_id)
- # Per-snapshot accounting: split GGUFs need every shard together, sizes are max across snapshots
- # so shared blobs are not double-counted, and keys are lowercased since cache casing can differ.
+ # snapshot totals keep shard sets intact, take maximum sizes, and compare keys case-insensitively
cached_snapshots: list[tuple[dict[str, int], dict[str, int]]] = []
- # A gated repo can list its files publicly, so reaching here is not authorization:
- # everything below reads the local caches, and would report `downloaded`, `partial`
- # and remaining bytes for the operator's copy to a caller the other paths refuse.
+ # public listings do not authorize exposing a caller's cached download and partial state
if _is_valid_repo_id(repo_id) and cache_reads_authorized:
- # A pinned row resolves inside one directory, so nothing else counts as downloaded.
+ # pinned rows resolve inside one snapshot and ignore other cached copies
scoped_snapshots = (
[snapshot_scope]
if snapshot_scope is not None
@@ -2452,13 +2516,10 @@ async def get_gguf_variants_answer(
variants[key] = detail
response.variants = list(variants.values())
response.has_vision = response.has_vision or any(s.has_vision for s in sources.values())
- # Merging changes the scope, so re-pick the default; prefer ready rows over partial ones.
+ # merged sources require a new default that prefers ready rows
if sources or not response.default_variant:
ready = [v for v in response.variants if v.downloaded and not v.partial]
- best = pick_best_gguf(
- _default_variant_candidates(ready or response.variants, repo_id)
- )
- response.default_variant = gguf_variant_key(best) if best else None
+ response.default_variant = _default_variant_key(ready or response.variants, repo_id)
if response.dependencies_resolved and locally_proven[0] is not None:
rows = frozenset(
(v.quant.lower(), v.filename)
diff --git a/studio/backend/hub/utils/gguf.py b/studio/backend/hub/utils/gguf.py
index 4fc263a30f9..3fe107cd28c 100644
--- a/studio/backend/hub/utils/gguf.py
+++ b/studio/backend/hub/utils/gguf.py
@@ -384,7 +384,26 @@ def default_gguf_scope(
if scoped:
return scoped
root = [item for item in rows if "/" not in str(key_of(item) or "")]
- return root or rows
+ if not root:
+ return rows
+ root_keys = {str(key_of(item) or "").casefold() for item in root}
+
+ def _same_quant_directory(item) -> bool:
+ value = str(key_of(item) or "").replace("\\", "/")
+ parents, separator, _basename = value.rpartition("/")
+ segments = [segment for segment in parents.split("/") if segment]
+ return bool(
+ separator
+ and segments
+ and all(_is_quant_directory(segment) for segment in segments)
+ and bare_quant_alias(value).casefold() in root_keys
+ )
+
+ return [
+ item
+ for item in rows
+ if "/" not in str(key_of(item) or "").replace("\\", "/") or _same_quant_directory(item)
+ ]
def _gguf_stem(filename: str) -> str:
@@ -567,12 +586,22 @@ def gguf_variant_keys_by_checkpoint(
keys: dict[str, str] = {}
for key, members in _paths_by_variant_key(paths).items():
identity_listed = listed[key] if listed and key in listed else _listed_identity(members)
+ colliding: dict[Optional[str], list[str]] = {}
+ for path in members:
+ identity = _checkpoint_identity(path)
+ family = gguf_variant_family(path.replace("\\", "/"))
+ if identity != identity_listed and family.casefold() == key.casefold():
+ colliding.setdefault(identity, []).append(path.replace("\\", "/"))
+ collision_keys = {
+ identity: min(identity_paths) for identity, identity_paths in colliding.items()
+ }
for path in members:
normalized = path.replace("\\", "/")
- if _checkpoint_identity(path) == identity_listed:
+ identity = _checkpoint_identity(path)
+ if identity == identity_listed:
keys[path] = gguf_variant_key(normalized)
else:
- keys[path] = gguf_variant_family(normalized)
+ keys[path] = collision_keys.get(identity, gguf_variant_family(normalized))
return keys
@@ -995,22 +1024,28 @@ def _apply_gguf_display_labels(variants: list[GgufVariantInfo], *repo_ids: objec
f"{token} · {_variant_scope_label(variant.filename, with_stem = collides)}"
)
elif root_label and "/" not in variant.filename.replace("\\", "/"):
- # Else the root quant reads as the default checkpoint.
+ # root quant labels identify the default checkpoint
variant.display_label = f"{variant.quant} · {root_label}"
-def group_gguf_variant_files(entries) -> dict[str, tuple[str, int]]:
- """map each variant key to the loader's first shard set and its total bytes."""
+def group_gguf_variant_files(
+ entries, keys: Optional[dict[str, str]] = None
+) -> dict[str, tuple[str, int]]:
+ """group each variant's first shard set and size, with optional path-specific keys."""
+
+ def key_of(path: str) -> str:
+ return (keys or {}).get(path) or gguf_variant_key(path)
+
families: dict[str, dict[tuple[str, int], list[tuple[str, int]]]] = {}
for path, size in entries:
- families.setdefault(gguf_variant_key(path).casefold(), {}).setdefault(
+ families.setdefault(key_of(path).casefold(), {}).setdefault(
gguf_shard_set(path), []
).append((path, int(size or 0)))
grouped: dict[str, tuple[str, int]] = {}
for by_family in families.values():
chosen = min(by_family.values(), key = lambda members: min(path for path, _ in members))
first = min(path for path, _ in chosen)
- grouped[gguf_variant_key(first)] = (first, sum(size for _, size in chosen))
+ grouped[key_of(first)] = (first, sum(size for _, size in chosen))
return grouped
@@ -1450,14 +1485,15 @@ def list_local_gguf_variants(
main_files: list[tuple[str, int]] = []
has_vision = False
- # Match the cache dir of ANY H3 bundle repo: the aggregation runs over whichever mirror the user actually downloaded. A whole SEGMENT, not a substring: "models--unsloth--MiniMax-H3-GGUF-mirror" (and -v2, -i1) contains the marker while being an ordinary chat repo, and the denoiser filter then left it with no quants, which withholds the auto-switch entry so a downloaded model 404s.
- segments = set(root.as_posix().lower().split("/"))
+ # match H3 bundle caches by full path segment so similarly named chat repos keep their quants
+ path_segments = root.as_posix().lower().split("/")
+ segments = set(path_segments)
h3_bundle_repo = next(
(r for r in _H3_BUNDLE_REPOS if f"models--{r.replace('/', '--')}" in segments), None
)
for file in sorted(iter_gguf_files(root, recursive = True)):
- # Off by default: the Hub lists the dangling link an evicted blob leaves, so a user can see and clean that quant. Only a caller advertising what it loads excludes it.
+ # keep dangling cache links visible for cleanup unless the caller requires loadable files
if require_existing_files and not _is_existing_file(file):
continue
if h3_bundle_repo and not _is_selectable_repo_gguf(h3_bundle_repo, file.name):
@@ -1465,7 +1501,7 @@ def list_local_gguf_variants(
if is_imatrix_filename(file.name):
continue
if is_mmproj_filename(file.name):
- # Header metadata distinguishes vision projectors from audio-only ones, read only when Windows reports the file fully present: opening a cloud placeholder would recall it during discovery.
+ # inspect complete local projectors only because opening a Windows cloud placeholder recalls it
try:
info = file.stat()
has_vision = has_vision or (
@@ -1489,10 +1525,42 @@ def list_local_gguf_variants(
continue
main_files.append((rel, size))
+ # custom folders split shared-quant builds; HF caches keep remote keys, and the first keeps the bare key
+ keys = (
+ None
+ if any(
+ segment.startswith("models--")
+ and index + 2 < len(path_segments)
+ and path_segments[index + 1] == "snapshots"
+ for index, segment in enumerate(path_segments)
+ )
+ else gguf_variant_keys_by_checkpoint(rel for rel, _size in main_files)
+ )
variants = [
GgufVariantInfo(filename = filename, quant = quant, size_bytes = size)
- for quant, (filename, size) in group_gguf_variant_files(main_files).items()
+ for quant, (filename, size) in group_gguf_variant_files(main_files, keys).items()
]
variants.sort(key = lambda variant: -variant.size_bytes)
_apply_gguf_display_labels(variants, directory, model_root)
+ if keys:
+ _label_split_builds(variants, keys)
return variants, has_vision
+
+
+def _label_split_builds(variants: list[GgufVariantInfo], keys: dict[str, str]) -> None:
+ """label all rows for a quant split across builds, including the bare-keyed first build."""
+ split = {
+ variant.filename
+ for variant in variants
+ if keys.get(variant.filename, variant.quant) != gguf_variant_key(variant.filename)
+ }
+ split_tokens = {(quant_token_with_bpw(name) or "").lower() for name in split}
+ for variant in variants:
+ token = quant_token_with_bpw(variant.filename)
+ if token is None or token.lower() not in split_tokens:
+ continue
+ # directory-qualified siblings keep their existing directory labels
+ if variant.filename not in split and variant.quant.lower() != token.lower():
+ continue
+ scope = _variant_scope_label(variant.filename, with_stem = True)
+ variant.display_label = f"{extract_quant_token(variant.filename)} · {scope}"
diff --git a/studio/backend/picker/service.py b/studio/backend/picker/service.py
index 5b3ae113b04..e1d73e29f00 100644
--- a/studio/backend/picker/service.py
+++ b/studio/backend/picker/service.py
@@ -257,11 +257,14 @@ def _iter_ggufs(dir_path: Path) -> list[Path]:
def _variant_matches(relative_path: str, needle: str) -> bool:
- from hub.utils.gguf import gguf_variant_key
+ from hub.utils.gguf import gguf_variant_family, gguf_variant_key
# The variant's own key first: in a repo holding several checkpoints at one quant
# the bare label names every one of them, so it cannot pick between them.
- if gguf_variant_key(relative_path).lower() == needle:
+ if gguf_variant_key(relative_path).lower() == needle or relative_path.lower() == needle:
+ return True
+ # custom folders key a second same-quant build by its file family (#13926)
+ if gguf_variant_family(relative_path).lower() == needle:
return True
quant = _extract_quant_label(relative_path).lower()
if quant == needle:
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index c0a979e1ca1..35585ae3d6f 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -10609,6 +10609,14 @@ def _resident_npu_model():
return npu.loaded_model if npu is not None else None
+def _unindexed_build_stem(variant: str) -> bool:
+ """Whether *variant* may name a same-quant build (``beta-Q4_K_M``) the cold index cannot place yet."""
+ from core.inference.local_model_resolver import index_is_built
+ from hub.utils.gguf import extract_quant_token
+
+ return not index_is_built() and extract_quant_token(variant) is not None
+
+
def _loaded_satisfies(requested: str) -> bool:
"""Whether what is serving right now actually answers to *requested*.
@@ -10645,6 +10653,19 @@ def _loaded_satisfies(requested: str) -> bool:
return _ollama_request_is_resident(requested, llama_backend)
if not _matches_any(requested, candidates) and not _matches_any(base, candidates):
return False
+ if variant and not looks_like_quant(variant):
+ from core.inference.local_model_resolver import (
+ local_gguf_pinned_variant,
+ local_gguf_withheld,
+ )
+
+ pinned_variant = local_gguf_pinned_variant(requested, allow_scan = False)
+ if pinned_variant is not None:
+ return _same_local_build(
+ base, getattr(llama_backend, "hf_variant", None) or "", pinned_variant
+ )
+ if _unindexed_build_stem(variant) or local_gguf_withheld(requested):
+ return False
if not looks_like_quant(variant):
return True
return (getattr(llama_backend, "hf_variant", None) or "").lower() == variant.lower()
@@ -10652,13 +10673,25 @@ def _loaded_satisfies(requested: str) -> bool:
active = getattr(backend, "active_model_name", None)
if not active:
return False
+ matches = _matches_any(
+ base, [active, public_model_id(active), getattr(backend, "_openai_advertised_id", None)]
+ )
+ if not matches:
+ return False
# Only llama.cpp carries a quant identity, so this backend can only match on the repo.
if looks_like_quant(variant):
return False
+ if variant:
+ from core.inference.local_model_resolver import (
+ local_gguf_pinned_variant,
+ local_gguf_withheld,
+ )
+ if local_gguf_pinned_variant(requested, allow_scan = False) is not None:
+ return False
+ if _unindexed_build_stem(variant) or local_gguf_withheld(requested):
+ return False
# The alias too: auto-switch records the repo id there, not in active_model_name.
- return _matches_any(
- base, [active, public_model_id(active), getattr(backend, "_openai_advertised_id", None)]
- )
+ return True
def _loaded_identity_satisfies(requested: str) -> bool:
@@ -10767,10 +10800,15 @@ def _norm_path(value: str) -> str:
return os.path.normcase(str(value)).replace("\\", "/").rstrip("/")
-def _resident_quant_is(variant: Optional[str]) -> bool:
+def _resident_quant_is(variant: Optional[str], base: Optional[str] = None) -> bool:
"""Whether the loaded GGUF is that exact quant."""
resident = getattr(get_llama_cpp_backend(), "hf_variant", None) or ""
- return bool(variant) and resident.lower() == variant.strip().lower()
+ return bool(variant) and _same_local_build(base, resident, variant)
+
+
+def _same_local_build(base: Optional[str], resident: str, wanted: str) -> bool:
+ from core.inference.local_model_resolver import local_gguf_same_build
+ return local_gguf_same_build(base, resident, wanted)
def _blob_identity(identity: Optional[tuple]) -> Optional[tuple]:
@@ -10966,6 +11004,8 @@ async def _reject_unservable_model(
gguf_hub_repo = looks_like_gguf_hub_repo_id(base)
from core.inference.local_model_resolver import (
index_is_built,
+ local_gguf_pinned_variant,
+ local_gguf_withheld,
recently_downloaded,
resolve_local_gguf,
warm_index_soon,
@@ -11022,12 +11062,23 @@ async def _reject_unservable_model(
warm_index_soon()
still_indexing = True
resolved = None
+ if resolved is not None:
+ # canonical even for a quant-shaped key: a saved build key can be re-keyed
+ pinned_variant = local_gguf_pinned_variant(requested_model, allow_scan = False)
+ if pinned_variant is not None:
+ variant = pinned_variant
+ quantified = True
+ elif local_gguf_withheld(requested_model):
+ # names a build that cannot be served, so no sibling may answer for it
+ quantified = True
# A manual load stores the on-disk path the resolver advertises under an alias,
# so match on the path too. Quants of one repo share a directory, so the path
# alone cannot tell them apart: without the variant check an explicit :Q8_0
# would be answered by a resident Q4_K_M.
# Off-loop: reads the Transformers singleton, and the llama.cpp short-circuits above
# skip the offloaded reads, so on a restart this built the singleton on the loop.
+ # the resolver's colon base: split_model_ref keeps a slash-qualified pin whole
+ index_base = requested_model.rpartition(":")[0] or base
resolved_is_resident = (
resolved is not None
and (
@@ -11036,7 +11087,7 @@ async def _reject_unservable_model(
)
)[1]
)
- if resolved_is_resident and (not quantified or _resident_quant_is(variant)):
+ if resolved_is_resident and (not quantified or _resident_quant_is(variant, index_base)):
return
downloaded = resolved is not None
# /v1/models may have advertised this id off its own scan while the index is cold.
@@ -11054,7 +11105,7 @@ async def _reject_unservable_model(
)
)[1]
)
- if advertised_is_resident and (not quantified or _resident_quant_is(variant)):
+ if advertised_is_resident and (not quantified or _resident_quant_is(variant, index_base)):
return
# The exact ref may miss on the quant alone, so ask about the repo too.
here = (
@@ -11150,6 +11201,17 @@ async def _require_named_model_access(
await _cached_local_catalog()
if await asyncio.to_thread(_own_local_model_for_alias, alias) is not None:
return
+ # split_model_ref keeps a quant-directory build pin (custom:Q4_K_M/beta-Q4_K_M) whole
+ from core.inference.local_model_resolver import local_gguf_pinned_variant
+
+ pinned_base = named_model.rpartition(":")[0].strip().lower()
+ if (
+ pinned_base
+ and pinned_base != alias
+ and await asyncio.to_thread(local_gguf_pinned_variant, named_model) is not None
+ and await asyncio.to_thread(_own_local_model_for_alias, pinned_base) is not None
+ ):
+ return
if await _caller_token_authorizes_download(named_model, fastapi_request):
return
raise HTTPException(status_code = 404, detail = "Model not found")
@@ -11433,6 +11495,7 @@ async def _maybe_auto_switch_model(
)
from core.inference.local_model_resolver import (
local_gguf_companion_roots,
+ local_gguf_pinned_variant,
local_gguf_companion_state,
local_target_is_gguf,
resolve_local_gguf_for_switch,
@@ -11705,7 +11768,11 @@ async def _maybe_auto_switch_model(
# _loaded_satisfies and the resolver read it. Treating it as a quant tears down
# a serving Q8 to load the preferred Q4 for a request either satisfies.
_, _requested_variant = split_model_ref(requested_model)
- bare = not looks_like_quant(_requested_variant)
+ # the index pin also covers directory-qualified keys split_model_ref cannot parse
+ bare = (
+ not looks_like_quant(_requested_variant)
+ and local_gguf_pinned_variant(requested_model, allow_scan = False) is None
+ )
ollama_target = target_is_gguf and is_ollama_manifest_ref(target_id)
ollama_source_identity = (
diff --git a/studio/backend/routes/llama_compat.py b/studio/backend/routes/llama_compat.py
index ae6181399f8..0cc0fad4fcd 100644
--- a/studio/backend/routes/llama_compat.py
+++ b/studio/backend/routes/llama_compat.py
@@ -315,9 +315,14 @@ def _catalog_match(catalog: list[dict], model_id: str) -> Optional[tuple[str, di
return row["id"], row, False
from core.inference.openai_auto_download import looks_like_quant
+ from core.inference.local_model_resolver import local_gguf_pinned_variant
+
base, sep, suffix = wanted.rpartition(":")
- # Only a quant: the resolver maps any other suffix (":latest", ":") back to the bare repo.
- row = rows.get(base.strip().lower()) if sep and looks_like_quant(suffix) else None
+ # only a quant or an indexed build key: any other suffix (":latest") means the bare repo
+ named = sep and (
+ looks_like_quant(suffix) or local_gguf_pinned_variant(wanted, allow_scan = False) is not None
+ )
+ row = rows.get(base.strip().lower()) if named else None
return (wanted, row, True) if row is not None else None
@@ -329,7 +334,14 @@ async def _chat_catalog() -> list[dict]:
async def _catalog_row(model_id: str) -> tuple[str, dict, bool]:
# The caller's own catalog, so a managed account only reaches models listed to it.
- matched = _catalog_match(await _chat_catalog(), model_id)
+ catalog = await _chat_catalog()
+ matched = _catalog_match(catalog, model_id)
+ if matched is None and ":" in model_id:
+ from core.inference.local_model_resolver import local_gguf_pinned_variant
+
+ # a cold index cannot vouch for a build key yet: scan once, off the loop, then retry
+ if await asyncio.to_thread(local_gguf_pinned_variant, model_id) is not None:
+ matched = _catalog_match(catalog, model_id)
if matched is None:
raise HTTPException(status_code = 404, detail = "Model not found")
return matched
@@ -368,8 +380,14 @@ async def _unload_target(model_id: str, row: dict, pinned: bool) -> Optional[str
base, suffix = split_model_ref(model_id)
# Only a quant the caller named: a bare id resolves to the preferred quant, not the resident one.
# The resolver's spelling of it, which maps a legacy label (BF16) onto the current quant.
- wanted_variant = None
- if suffix and looks_like_quant(suffix):
+ from core.inference.local_model_resolver import (
+ local_gguf_pinned_variant,
+ local_gguf_same_build,
+ )
+
+ # not gated on suffix: split_model_ref cannot parse a directory-qualified build key
+ wanted_variant = local_gguf_pinned_variant(model_id, allow_scan = False)
+ if wanted_variant is None and suffix and looks_like_quant(suffix):
wanted_variant = (resolved[1] if resolved else None) or suffix
llama = inf.get_llama_cpp_backend()
@@ -393,7 +411,9 @@ async def _unload_target(model_id: str, row: dict, pinned: bool) -> Optional[str
if not named:
continue
# A pin names one quant: another one, or a backend with none, may sit in a kept slot instead.
- if wanted_variant and (running_variant or "").lower() != wanted_variant.lower():
+ if wanted_variant and not local_gguf_same_build(
+ model_id.rpartition(":")[0], running_variant or "", wanted_variant
+ ):
continue
return running
filling = inf.model_slots.visible_loading()
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index 3a2729a4434..b2747be898b 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -5046,23 +5046,19 @@ def _one_shard_family_of(entries: list) -> list:
def _main_variant_rank(rel_path: str, want: str) -> Optional[int]:
- """How well *want* names this file's variant: 0 for its own key, 1 for the legacy quant-label spelling, None
- for neither.
-
- *want* is the request VERBATIM: the bare-quant folding is applied per comparison, because doing it once
- up front strips a qualified key's own path punctuation and folds ``exp-a/`` into ``expa/``.
- Directory-qualified keys keep their legacy bare spelling, since stored pins predate them. Root-level H3
- stems do not: a bare quant names both FL2VA and Ref2VA, and picking the first file would load a
- different task.
- """
- from hub.utils.gguf import is_qualified_gguf_variant_key
+ """rank an exact variant as 0, its legacy quant alias as 1, or no match as None without normalizing paths."""
+ from hub.utils.gguf import gguf_variant_family, is_qualified_gguf_variant_key
from utils.models.model_config import _gguf_variant_key
label = _main_variant_gguf_label(rel_path)
if label is None:
return None
key = _gguf_variant_key(rel_path)
- if _variant_keys_match(key, want):
+ # a second same-quant build in a custom folder is keyed by its family (#13926)
+ want_family = gguf_variant_family(want) if want.lower().endswith(".gguf") else want
+ if _variant_keys_match(key, want) or (
+ gguf_variant_family(rel_path).casefold() == want_family.strip().casefold()
+ ):
return 0
if is_qualified_gguf_variant_key(key) and "/" not in key.replace("\\", "/"):
return None
@@ -5070,10 +5066,7 @@ def _main_variant_rank(rel_path: str, want: str) -> Optional[int]:
def _variant_keys_match(key: str, want: str) -> bool:
- """Whether *want* is *key*, for the exact-key test. ``_normalized_quant_label`` strips hyphens and
- underscores, which is right for a bare quant (``UD-Q4_K_XL`` and ``udq4kxl`` are the same ask) and wrong
- for a path: it folds ``exp-a/`` and ``expa/`` into one, so two advertised checkpoints both answered to
- the other's key."""
+ """match exact variant keys without folding punctuation in qualified paths."""
from hub.utils.gguf import is_qualified_gguf_variant_key
if is_qualified_gguf_variant_key(key) or is_qualified_gguf_variant_key(want):
diff --git a/studio/backend/tests/test_gguf_delete_keeps_sibling_builds.py b/studio/backend/tests/test_gguf_delete_keeps_sibling_builds.py
index d09e0e376c7..7948fe409de 100644
--- a/studio/backend/tests/test_gguf_delete_keeps_sibling_builds.py
+++ b/studio/backend/tests/test_gguf_delete_keeps_sibling_builds.py
@@ -1,7 +1,7 @@
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-"""GGUF listings expose one build per quant (#13327), but deletion must preserve cached siblings."""
+"""HF cache GGUF listings expose one build per quant (#13327), but deletion must preserve cached siblings."""
from __future__ import annotations
@@ -60,15 +60,304 @@ def test_only_a_different_build_leaves_the_key():
def test_the_listing_still_offers_one_build_per_quant(tmp_path):
- snapshot = tmp_path / "snap"
- snapshot.mkdir()
- for name in BUILDS:
- (snapshot / name).write_bytes(b"x" * 64)
- (snapshot / "config.json").write_text("{}")
+ _repo, snapshot = _cache_repo(tmp_path, BUILDS)
variants, _ = list_local_gguf_variants(str(snapshot))
assert [(v.quant, v.filename) for v in variants] == [("IQ3_S", LISTED)]
+def test_a_custom_folder_lists_every_build_at_one_quant(tmp_path):
+ from routes.models import _resolve_quant_gguf
+ from utils.models.model_config import _find_local_gguf_by_variant
+
+ # custom folders have no remote listing to constrain their keys, so every build keeps a row (#13926).
+ folder = tmp_path / "esatapedico" / "Qwen3.8-27B-NVFP4-MTP-GGUF"
+ folder.mkdir(parents = True)
+ names = [f"Qwen3.8-27B-NVFP4-MTP-{build}.gguf" for build in ("HIGHEST", "LOW", "MID-HIGH_enru")]
+ for name in names:
+ (folder / name).write_bytes(b"x" * 64)
+ variants, _ = list_local_gguf_variants(str(folder))
+ listed = {v.quant: v.filename for v in variants}
+ # the first build keeps the bare quant so existing pins still name the same file
+ assert listed == {"NVFP4": names[0], **{name[: -len(".gguf")]: name for name in names[1:]}}
+ for quant, filename in listed.items():
+ assert Path(_find_local_gguf_by_variant(str(folder), quant)).name == filename
+ assert Path(_resolve_quant_gguf(str(folder), quant, True)[0]).name == filename
+ assert {v.display_label for v in variants} == {
+ f"NVFP4 · {name[: -len('.gguf')]}" for name in names
+ }
+
+
+def test_each_custom_build_reads_context_from_its_own_file(tmp_path, monkeypatch):
+ import asyncio
+
+ from routes import models as models_route
+
+ names = ["alpha-Q4_K_M.gguf", "beta-Q4_K_M.gguf"]
+ for name in names:
+ (tmp_path / name).write_bytes(b"x")
+ contexts = {names[0]: 4096, names[1]: 8192}
+ reads = []
+
+ async def read_context(model, _is_local):
+ source = Path(model)
+ reads.append(source)
+ return contexts.get(source.name, 1024)
+
+ monkeypatch.setattr(models_route, "_read_native_context_length_bounded", read_context)
+ response = asyncio.run(
+ models_route.get_gguf_variants(
+ repo_id = str(tmp_path),
+ prefer_local_cache = True,
+ hf_token = None,
+ hf_token_header = None,
+ current_subject = "test-user",
+ via_api_key = False,
+ )
+ )
+
+ assert {variant.filename: variant.context_length for variant in response.variants} == contexts
+ assert set(reads) == {tmp_path, *(tmp_path / name for name in names)}
+
+
+def test_direct_file_reads_context_from_the_chosen_file_only(tmp_path, monkeypatch):
+ import asyncio
+
+ from routes import models as models_route
+
+ (tmp_path / "config.json").write_text("{}")
+ names = ["alpha-Q4_K_M.gguf", "beta-Q4_K_M.gguf"]
+ for name in names:
+ (tmp_path / name).write_bytes(b"x")
+ contexts = {names[0]: 4096, names[1]: 8192}
+ reads = []
+
+ async def read_context(model, _is_local):
+ source = Path(model)
+ reads.append(source)
+ return contexts[source.name]
+
+ monkeypatch.setattr(models_route, "_read_native_context_length_bounded", read_context)
+ response = asyncio.run(
+ models_route.get_gguf_variants(
+ repo_id = str(tmp_path / names[0]),
+ prefer_local_cache = True,
+ hf_token = None,
+ hf_token_header = None,
+ current_subject = "test-user",
+ via_api_key = False,
+ )
+ )
+
+ # the loader opens a direct file whatever variant is named, so its same-quant sibling is not offered
+ assert {variant.filename: variant.context_length for variant in response.variants} == {
+ names[0]: contexts[names[0]]
+ }
+ assert tmp_path / names[1] not in set(reads)
+
+
+def test_ready_sibling_keeps_its_context_when_the_other_build_is_partial(tmp_path, monkeypatch):
+ import asyncio
+
+ from routes import models as models_route
+
+ partial = "alpha-Q4_K_M-00001-of-00002.gguf"
+ ready = "beta-Q4_K_M.gguf"
+ for name in (partial, ready):
+ (tmp_path / name).write_bytes(b"x")
+ contexts = {partial: 4096, ready: 8192}
+ reads = []
+
+ async def read_context(model, _is_local):
+ source = Path(model)
+ reads.append(source)
+ return contexts.get(source.name, 1024)
+
+ monkeypatch.setattr(models_route, "_read_native_context_length_bounded", read_context)
+ response = asyncio.run(
+ models_route.get_gguf_variants(
+ repo_id = str(tmp_path),
+ prefer_local_cache = True,
+ hf_token = None,
+ hf_token_header = None,
+ current_subject = "test-user",
+ via_api_key = False,
+ )
+ )
+
+ rows = {variant.filename: variant for variant in response.variants}
+ assert rows[partial].downloaded is False
+ assert rows[ready].downloaded is True
+ assert rows[ready].context_length == contexts[ready]
+ assert set(reads) == {tmp_path, tmp_path / ready}
+
+
+def test_default_build_matches_variantless_local_file_ranking(tmp_path):
+ import asyncio
+
+ from hub.services.models.gguf_variants import get_gguf_variants_response
+
+ alpha = "alpha-Q4_K_M.gguf"
+ beta = "beta-Q4_K_M-00001-of-00002.gguf"
+ (tmp_path / alpha).write_bytes(b"x" * 100)
+ (tmp_path / beta).write_bytes(b"x" * 60)
+ (tmp_path / "beta-Q4_K_M-00002-of-00002.gguf").write_bytes(b"x" * 60)
+
+ response = asyncio.run(get_gguf_variants_response(str(tmp_path), prefer_local_cache = True))
+
+ assert response.default_variant == "Q4_K_M"
+
+
+def test_default_build_matches_variantless_ranking_for_a_relative_folder(tmp_path, monkeypatch):
+ import asyncio
+
+ from hub.services.models.gguf_variants import get_gguf_variants_response
+
+ folder = tmp_path / "custom"
+ folder.mkdir()
+ (folder / "alpha-Q4_K_M.gguf").write_bytes(b"x" * 100)
+ (folder / "beta-Q4_K_M-00001-of-00002.gguf").write_bytes(b"x" * 60)
+ (folder / "beta-Q4_K_M-00002-of-00002.gguf").write_bytes(b"x" * 60)
+ monkeypatch.chdir(tmp_path)
+
+ response = asyncio.run(get_gguf_variants_response("custom", prefer_local_cache = True))
+
+ assert response.default_variant == "Q4_K_M"
+
+
+def test_the_detected_build_does_not_leave_a_curated_default_scope(tmp_path):
+ import asyncio
+
+ from hub.services.models.gguf_variants import get_gguf_variants_response
+
+ folder = tmp_path / "unsloth" / "LTX-2.5-GGUF"
+ (folder / "distilled").mkdir(parents = True)
+ (folder / "a-Q4_K_M.gguf").write_bytes(b"x" * 100)
+ (folder / "b-Q4_K_M.gguf").write_bytes(b"x" * 90)
+ (folder / "distilled" / "model-Q4_K_M.gguf").write_bytes(b"x" * 80)
+
+ response = asyncio.run(get_gguf_variants_response(str(folder), prefer_local_cache = True))
+
+ assert response.default_variant == "distilled/model-Q4_K_M"
+
+
+def test_a_larger_sibling_build_does_not_override_the_preferred_default(tmp_path):
+ import asyncio
+
+ from hub.services.models.gguf_variants import get_gguf_variants_response
+
+ (tmp_path / "model-Q4_K_M.gguf").write_bytes(b"x" * 50)
+ (tmp_path / "alpha-F16.gguf").write_bytes(b"x" * 100)
+ (tmp_path / "beta-F16.gguf").write_bytes(b"x" * 120)
+
+ response = asyncio.run(get_gguf_variants_response(str(tmp_path), prefer_local_cache = True))
+
+ assert response.default_variant == "Q4_K_M"
+
+
+def test_a_direct_file_listing_offers_no_same_quant_sibling_build(tmp_path):
+ import asyncio
+
+ from hub.services.models.gguf_variants import get_gguf_variants_response
+
+ (tmp_path / "config.json").write_text("{}")
+ (tmp_path / "alpha-Q4_K_M.gguf").write_bytes(b"x" * 100)
+ (tmp_path / "beta-Q4_K_M.gguf").write_bytes(b"x" * 90)
+ (tmp_path / "gamma-Q8_0.gguf").write_bytes(b"x" * 80)
+
+ response = asyncio.run(
+ get_gguf_variants_response(str(tmp_path / "alpha-Q4_K_M.gguf"), prefer_local_cache = True)
+ )
+
+ files = {v.filename for v in response.variants}
+ assert "beta-Q4_K_M.gguf" not in files
+ assert {"alpha-Q4_K_M.gguf", "gamma-Q8_0.gguf"} <= files
+
+
+def test_a_direct_non_first_shard_lists_no_same_quant_sibling(tmp_path):
+ import asyncio
+
+ from hub.services.models.gguf_variants import get_gguf_variants_response
+
+ (tmp_path / "config.json").write_text("{}")
+ (tmp_path / "alpha-Q4_K_M-00001-of-00002.gguf").write_bytes(b"x" * 60)
+ (tmp_path / "alpha-Q4_K_M-00002-of-00002.gguf").write_bytes(b"x" * 60)
+ (tmp_path / "beta-Q4_K_M.gguf").write_bytes(b"x" * 90)
+
+ response = asyncio.run(
+ get_gguf_variants_response(
+ str(tmp_path / "alpha-Q4_K_M-00002-of-00002.gguf"), prefer_local_cache = True
+ )
+ )
+
+ assert "beta-Q4_K_M.gguf" not in {v.filename for v in response.variants}
+
+
+def test_a_bare_named_sibling_cannot_collide_with_the_legacy_quant_key(tmp_path):
+ import asyncio
+
+ from hub.services.models.gguf_variants import get_gguf_variants_response
+ from routes.models import _delete_gguf_variant_files, _resolve_quant_gguf
+ from utils.models.model_config import _find_local_gguf_by_variant
+
+ names = [
+ "0-model-Q4_K_M.gguf",
+ "Q4_K_M-00001-of-00002.gguf",
+ "Q4_K_M-00002-of-00002.gguf",
+ ]
+ for index, name in enumerate(names, 1):
+ (tmp_path / name).write_bytes(b"x" * (index * 16))
+
+ variants, _ = list_local_gguf_variants(str(tmp_path))
+ listed = {v.quant: (v.filename, v.size_bytes) for v in variants}
+ sibling_key = names[1]
+ assert listed == {"Q4_K_M": (names[0], 16), sibling_key: (names[1], 80)}
+ assert Path(_find_local_gguf_by_variant(str(tmp_path), "Q4_K_M")).name == names[0]
+ assert Path(_find_local_gguf_by_variant(str(tmp_path), sibling_key)).name == names[1]
+ resolved, size = _resolve_quant_gguf(str(tmp_path), sibling_key, True)
+ assert Path(resolved).name == names[1]
+ assert size == 80
+ response = asyncio.run(get_gguf_variants_response(str(tmp_path), prefer_local_cache = True))
+ assert response.default_variant == sibling_key
+ assert response.loadable_variants[:2] == [sibling_key, "Q4_K_M"]
+ assert _delete_gguf_variant_files(tmp_path, sibling_key)[0] == 2
+ assert (tmp_path / names[0]).exists()
+ assert not (tmp_path / names[1]).exists()
+ assert not (tmp_path / names[2]).exists()
+
+
+def test_an_ordinary_models_prefixed_folder_is_not_an_hf_snapshot(tmp_path):
+ folder = tmp_path / "models--custom-collections" / "ordinary-folder"
+ folder.mkdir(parents = True)
+ names = ["alpha-Q4_K_M.gguf", "beta-Q4_K_M.gguf"]
+ for name in names:
+ (folder / name).write_bytes(b"x")
+
+ variants, _ = list_local_gguf_variants(str(folder))
+ assert {variant.filename for variant in variants} == set(names)
+
+
+def test_split_build_labels_leave_other_rows_alone(tmp_path):
+ for rel in ("model-Q6_K.gguf", "other-Q6_K.gguf", "distilled/model-Q6_K.gguf", "m-Q8_0.gguf"):
+ (tmp_path / rel).parent.mkdir(parents = True, exist_ok = True)
+ (tmp_path / rel).write_bytes(b"x" * 64)
+ labels = {v.filename: v.display_label for v in list_local_gguf_variants(str(tmp_path))[0]}
+ assert labels == {
+ "model-Q6_K.gguf": "Q6_K · model-Q6_K",
+ "other-Q6_K.gguf": "Q6_K · other-Q6_K",
+ # a directory already tells this checkpoint apart, and an unsplit quant needs no name
+ "distilled/model-Q6_K.gguf": "Q6_K · distilled",
+ "m-Q8_0.gguf": None,
+ }
+
+ # two builds in one quant folder cannot be distinguished by the folder alone
+ quant_dir = tmp_path / "quant-dir" / "Q4_K_M"
+ quant_dir.mkdir(parents = True)
+ for name in ("a-Q4_K_M.gguf", "b-Q4_K_M.gguf"):
+ (quant_dir / name).write_bytes(b"x" * 64)
+ labels = {v.display_label for v in list_local_gguf_variants(str(quant_dir.parent))[0]}
+ assert labels == {"Q4_K_M · Q4_K_M/a-Q4_K_M", "Q4_K_M · Q4_K_M/b-Q4_K_M"}
+
+
def test_quant_key_case_exposes_and_deletes_the_same_build(tmp_path):
from hub.services.models.deletion import _delete_gguf_variant_from_repos
from hub.utils.gguf import group_gguf_variant_files
@@ -76,19 +365,14 @@ def test_quant_key_case_exposes_and_deletes_the_same_build(tmp_path):
alpha = "alpha-Q4_K_M.gguf"
beta = "beta-q4_k_m.gguf"
- snapshot = tmp_path / "snapshot"
- snapshot.mkdir()
- for name in (alpha, beta):
- (snapshot / name).write_bytes(b"x" * 64)
- (snapshot / "config.json").write_text("{}")
+ repo, cache_snapshot = _cache_repo(tmp_path / "cache", [alpha, beta])
- variants, _ = list_local_gguf_variants(str(snapshot))
+ variants, _ = list_local_gguf_variants(str(cache_snapshot))
assert [(variant.quant, variant.filename) for variant in variants] == [("Q4_K_M", alpha)]
hub_grouped = group_gguf_variant_files([(alpha, 64), (beta, 128)])
inference_grouped = _group_gguf_variant_files([(alpha, "Q4_K_M", 64), (beta, "q4_k_m", 128)])
assert inference_grouped == hub_grouped == {"Q4_K_M": (alpha, 64)}
- repo, cache_snapshot = _cache_repo(tmp_path / "cache", [alpha, beta])
_delete_gguf_variant_from_repos(repo.repo_id, variants[0].quant, [repo], None, root = tmp_path)
assert not (cache_snapshot / alpha).is_symlink()
assert (cache_snapshot / beta).is_symlink()
diff --git a/studio/backend/tests/test_gguf_split_build_grouping.py b/studio/backend/tests/test_gguf_split_build_grouping.py
new file mode 100644
index 00000000000..50f29cec2d2
--- /dev/null
+++ b/studio/backend/tests/test_gguf_split_build_grouping.py
@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+
+from itertools import permutations
+
+from hub.utils.gguf import group_gguf_variant_files
+
+ALPHA_FIRST = "alpha-Q4_K_M-00001-of-00002.gguf"
+ALPHA_SECOND = "alpha-Q4_K_M-00002-of-00002.gguf"
+BETA_FIRST = "beta-Q4_K_M-00001-of-00002.gguf"
+BETA_SECOND = "beta-Q4_K_M-00002-of-00002.gguf"
+ENTRIES = [(ALPHA_FIRST, 10), (ALPHA_SECOND, 20), (BETA_FIRST, 30), (BETA_SECOND, 40)]
+EXPECTED = {"Q4_K_M": (ALPHA_FIRST, 30), "beta-Q4_K_M": (BETA_FIRST, 70)}
+
+
+def test_split_build_keys_keep_totals_separate_for_every_entry_order():
+ keys = {
+ ALPHA_FIRST: "Q4_K_M",
+ ALPHA_SECOND: "Q4_K_M",
+ BETA_FIRST: "beta-Q4_K_M",
+ BETA_SECOND: "beta-Q4_K_M",
+ }
+ for entries in permutations(ENTRIES):
+ assert group_gguf_variant_files(entries, keys) == EXPECTED
+
+
+def test_partial_key_overrides_keep_the_unmapped_builds_legacy_key():
+ keys = {BETA_FIRST: "beta-Q4_K_M", BETA_SECOND: "beta-Q4_K_M"}
+ assert group_gguf_variant_files(iter(reversed(ENTRIES)), keys) == EXPECTED
+
+
+def test_omitted_and_empty_overrides_keep_one_legacy_shard_family():
+ expected = {"Q4_K_M": (ALPHA_FIRST, 30)}
+ assert group_gguf_variant_files(ENTRIES) == expected
+ assert group_gguf_variant_files(ENTRIES, None) == expected
+ assert group_gguf_variant_files(ENTRIES, {}) == expected
diff --git a/studio/backend/tests/test_gguf_variant_rows.py b/studio/backend/tests/test_gguf_variant_rows.py
index 2f5a932c201..b9401f95f1d 100644
--- a/studio/backend/tests/test_gguf_variant_rows.py
+++ b/studio/backend/tests/test_gguf_variant_rows.py
@@ -1149,20 +1149,20 @@ def test_every_branch_derives_the_default_from_the_root_rows():
types.SimpleNamespace(filename = "model-Q6_K.gguf", quant = "Q6_K"),
]
assert service._default_variant_candidates(rows) == ["model-Q6_K.gguf"]
- # Nothing at the root falls back to the whole set rather than answering nothing.
+ # empty root candidates fall back to all rows.
assert service._default_variant_candidates(rows[:1]) == ["distilled/model-Q6_K.gguf"]
- # No branch may call pick_best_gguf on the raw filenames any more.
+ # guards every response branch against selecting from raw filenames.
source = inspect.getsource(service)
- # Whitespace-insensitive: the formatter may wrap a call across lines.
- assert len(re.findall(r"pick_best_gguf\(\s*_default_variant_candidates\(", source)) == 5
+ # accepts formatter line wrapping.
+ assert len(re.findall(r"pick_best_gguf\(\s*_default_variant_candidates\(", source)) == 1
+ assert len(re.findall(r"default_variant = _default_variant_key\(", source)) == 5
assert "pick_best_gguf(filenames)" not in source
+ # custom folders use the selected row key because stem keys need not identify the file (#13926).
+ assert "gguf_variant_key(best) if best" not in source
def test_the_kv_cache_estimate_sizes_one_shard_family():
- """A snapshot holding the same quant twice (QwQ-32B's two BF16 shard sets) would report double
- the weights the loader opens, which /kv-cache-estimate turns into a false exceeds-memory
- warning -- and which can make a snapshot look "more complete" purely for holding a redundant
- copy. Same rule group_gguf_variant_files applies."""
+ """only one duplicate BF16 shard family contributes to the kv-cache estimate."""
from routes.models import _one_shard_family_of
duplicated = [
diff --git a/studio/backend/tests/test_gguf_variants_local_resolution.py b/studio/backend/tests/test_gguf_variants_local_resolution.py
index 723ac7355b4..98a1cfd1a03 100644
--- a/studio/backend/tests/test_gguf_variants_local_resolution.py
+++ b/studio/backend/tests/test_gguf_variants_local_resolution.py
@@ -429,7 +429,7 @@ def test_relative_identifiers_keep_their_relative_alias(in_tmp_cwd):
def test_loadable_variants_include_the_relative_fallback_label(in_tmp_cwd):
- # The resolver accepts the snapshot-relative stem, so the answer must not omit it.
+ # snapshot-relative stems accepted by the resolver must remain advertised.
from utils.models.model_config import _find_local_gguf_by_variant
(in_tmp_cwd / "config.json").write_text("{}")
@@ -443,20 +443,20 @@ def test_loadable_variants_include_the_relative_fallback_label(in_tmp_cwd):
def test_a_torn_split_keeps_its_quant_partial(in_tmp_cwd):
- # A short shard-like name is ready alone, but not when the file the resolver binds for
- # that quant is an earlier torn five-digit split.
- (in_tmp_cwd / "config.json").write_text("{}")
- (in_tmp_cwd / "a-Q4_K_M-00001-of-00002.gguf").write_bytes(b"GGUF")
- (in_tmp_cwd / "z-Q4_K_M-001-of-002.gguf").write_bytes(b"GGUF")
-
- response = _variants(os.fspath(in_tmp_cwd))
+ # an HF snapshot lists one build per quant, so the earlier torn split hides the ready short shard.
+ snapshot = in_tmp_cwd / "models--org--Model-GGUF" / "snapshots" / "rev1"
+ snapshot.mkdir(parents = True)
+ (snapshot / "config.json").write_text("{}")
+ (snapshot / "a-Q4_K_M-00001-of-00002.gguf").write_bytes(b"GGUF")
+ (snapshot / "z-Q4_K_M-001-of-002.gguf").write_bytes(b"GGUF")
+
+ response = _variants(os.fspath(snapshot))
assert response.variants[0].partial is True
assert response.loadable_variants == []
def test_short_shard_like_name_in_a_directory_reads_ready(in_tmp_cwd):
- # The cache scan's looser grammar calls this torn, but the load opens a -001-of-002
- # name as an ordinary file.
+ # cache scanning marks -001-of-002 as torn, but loading treats it as an ordinary file.
from utils.models.model_config import detect_gguf_model
(in_tmp_cwd / "config.json").write_text("{}")
diff --git a/studio/backend/tests/test_hf_cache_dangling_refs.py b/studio/backend/tests/test_hf_cache_dangling_refs.py
index 4266c56fa15..313f4be6850 100644
--- a/studio/backend/tests/test_hf_cache_dangling_refs.py
+++ b/studio/backend/tests/test_hf_cache_dangling_refs.py
@@ -2865,11 +2865,9 @@ def test_a_payload_split_across_snapshots_is_not_advertised_runnable(tmp_path, m
def test_a_complete_quant_family_does_not_vouch_for_a_torn_sibling(tmp_path):
- """One quant label can cover several shard families and the lister offers only the
- lexicographically first file under it, so grouping on the shard total alone let the complete B
- family mark the torn A file downloadable."""
- snapshot = tmp_path / "snap"
- snapshot.mkdir()
+ """a complete sibling must not make the lexicographically selected torn family downloadable."""
+ snapshot = tmp_path / "models--org--Model-GGUF" / "snapshots" / "rev1"
+ snapshot.mkdir(parents = True)
for name in (
"A-Q4_K_M-00001-of-00002.gguf",
"B-Q4_K_M-00001-of-00002.gguf",
@@ -3805,40 +3803,75 @@ def test_an_unreadable_manifest_keeps_the_fixed_denoiser_pair(tmp_path):
assert inventory_scan.snapshot_pipeline_missing_denoiser(snapshot) is False
-def _snapshot_with(tmp_path, files: dict) -> Path:
- snapshot = tmp_path / "snap"
- snapshot.mkdir()
+def _snapshot_with(
+ tmp_path,
+ files: dict,
+ subdir: str = "snap",
+) -> Path:
+ snapshot = tmp_path / subdir
+ snapshot.mkdir(parents = True)
for name, size in files.items():
(snapshot / name).write_bytes(b"\0" * size)
return snapshot
+_HF_SNAPSHOT = "models--org--Model-GGUF/snapshots/rev1"
+
+
def test_a_torn_sibling_family_does_not_veto_the_quant_that_loads(tmp_path):
- """Two families can share one quant label. The lister offers the lexicographically first file
- and the loader loads that family alone, so the torn z- set beside a whole a-Q4_K_M.gguf is
- never selected and must not make the label unavailable."""
+ """the selected complete family stays ready even when a torn sibling shares its quant."""
snapshot = _snapshot_with(
tmp_path,
{"a-Q4_K_M.gguf": 64, "z-Q4_K_M-00001-of-00002.gguf": 16},
+ _HF_SNAPSHOT,
)
assert inventory_scan._completed_gguf_variants(snapshot) == {"Q4_K_M"}
assert _local_offer(snapshot) == [("Q4_K_M", True)]
def test_a_whole_sibling_family_does_not_vouch_for_the_torn_one_that_loads(tmp_path):
- """The other direction, which is why this keys on the selected family rather than on any
- complete one: the torn set sorts first, so that is what the loader picks."""
+ """the selected torn family stays incomplete even when a complete sibling shares its quant."""
snapshot = _snapshot_with(
tmp_path,
{"a-Q4_K_M-00001-of-00002.gguf": 16, "z-Q4_K_M.gguf": 64},
+ _HF_SNAPSHOT,
)
assert inventory_scan._completed_gguf_variants(snapshot) == set()
assert _local_offer(snapshot) == [("Q4_K_M", False)]
+def test_a_custom_folder_judges_each_build_at_one_quant_on_its_own_files(tmp_path):
+ """custom folders track readiness and default selection per build, even at one quant."""
+ import asyncio
+
+ from hub.services.models import gguf_variants
+ from utils.models.model_config import _find_local_gguf_by_variant
+
+ for files, offer, default, default_file in (
+ (
+ {"a-Q4_K_M.gguf": 64, "z-Q4_K_M-00001-of-00002.gguf": 16},
+ [("Q4_K_M", True), ("z-Q4_K_M", False)],
+ "Q4_K_M",
+ "a-Q4_K_M.gguf",
+ ),
+ (
+ {"a-Q4_K_M-00001-of-00002.gguf": 16, "z-Q4_K_M.gguf": 64},
+ [("Q4_K_M", False), ("z-Q4_K_M", True)],
+ "z-Q4_K_M",
+ "z-Q4_K_M.gguf",
+ ),
+ ):
+ folder = _snapshot_with(tmp_path, files, f"folder-{default}")
+ assert _local_offer(folder) == offer
+ response = asyncio.run(
+ gguf_variants.get_gguf_variants_response(str(folder), prefer_local_cache = True)
+ )
+ assert response.default_variant == default
+ assert Path(_find_local_gguf_by_variant(str(folder), default)).name == default_file
+
+
def test_the_selected_family_is_judged_on_its_own_shards(tmp_path):
- """A complete split set selected ahead of a torn sibling stays complete: the missing shard
- belongs to a family nothing reads."""
+ """a missing shard in an unselected sibling must not make the selected family incomplete."""
snapshot = _snapshot_with(
tmp_path,
{
diff --git a/studio/backend/tests/test_llama_compat_routes.py b/studio/backend/tests/test_llama_compat_routes.py
index 0c6c6b199a7..11e251e08c1 100644
--- a/studio/backend/tests/test_llama_compat_routes.py
+++ b/studio/backend/tests/test_llama_compat_routes.py
@@ -1134,6 +1134,7 @@ def _no_local_gguf(monkeypatch):
monkeypatch.setattr(resolver, "resolve_trusted_cached_local_gguf", lambda *a, **k: None)
monkeypatch.setattr(resolver, "resolve_local_gguf", lambda *a, **k: None)
+ monkeypatch.setattr(resolver, "local_gguf_pinned_variant", lambda *a, **k: None)
monkeypatch.setattr(overrides, "resolve_override_for_load", lambda *a, **k: (None, {}))
monkeypatch.setattr(resolver, "local_target_is_gguf", lambda *a, **k: True)
return resolver
@@ -1380,6 +1381,118 @@ def test_management_unload_keeps_a_resident_of_another_quant(monkeypatch, _no_lo
assert calls == [("unload", "/media/models/qwen/model.gguf")]
+def test_management_unload_keeps_a_resident_of_another_named_build(monkeypatch, _no_local_gguf):
+ build = QWEN + ":beta-Q4_K_M"
+ monkeypatch.setattr(
+ _no_local_gguf,
+ "resolve_local_gguf",
+ lambda requested, **kwargs: (
+ "/media/models/qwen/model.gguf",
+ "beta-Q4_K_M",
+ QWEN,
+ ),
+ )
+ monkeypatch.setattr(
+ _no_local_gguf,
+ "local_gguf_pinned_variant",
+ lambda requested, **kwargs: "beta-Q4_K_M" if requested == build else None,
+ )
+ backend = _Backend()
+ backend.hf_variant = "Q4_K_M"
+ pin = {"id": build, "object": "model", "loaded": False}
+ mod, calls = _management(backend = backend, catalog = CATALOG + [pin])
+
+ with _client(mod) as client:
+ assert client.post("/models/unload", json = {"model": build}).status_code == 200
+
+ assert calls == []
+
+
+def test_management_unload_keeps_a_resident_of_another_quant_directory_build(
+ monkeypatch, _no_local_gguf
+):
+ build = "custom-model:Q4_K_M/beta-Q4_K_M"
+ monkeypatch.setattr(
+ _no_local_gguf,
+ "resolve_local_gguf",
+ lambda requested, **kwargs: ("/media/models/custom", "Q4_K_M/beta-Q4_K_M", "custom-model"),
+ )
+ monkeypatch.setattr(
+ _no_local_gguf,
+ "local_gguf_pinned_variant",
+ lambda requested, **kwargs: "Q4_K_M/beta-Q4_K_M" if requested == build else None,
+ )
+ backend = _Backend()
+ backend.hf_variant = "Q4_K_M"
+ backend.model_identifier = "/media/models/custom"
+ backend._openai_advertised_id = "custom-model"
+ pin = {"id": build, "object": "model", "loaded": False}
+ mod, calls = _management(backend = backend, catalog = CATALOG + [pin])
+
+ with _client(mod) as client:
+ assert client.post("/models/unload", json = {"model": build}).status_code == 200
+
+ assert calls == []
+
+
+def test_management_unload_releases_a_build_loaded_by_its_rekeyed_stem(monkeypatch, _no_local_gguf):
+ build = QWEN + ":Q4_K_M"
+ monkeypatch.setattr(
+ _no_local_gguf,
+ "resolve_local_gguf",
+ lambda requested, **kwargs: ("/media/models/qwen/model.gguf", "Q4_K_M", QWEN),
+ )
+
+ def _pinned(requested, **kwargs):
+ return {build: "Q4_K_M", QWEN + ":beta-q4_k_m": "Q4_K_M"}.get(requested)
+
+ monkeypatch.setattr(_no_local_gguf, "local_gguf_pinned_variant", _pinned)
+ backend = _Backend()
+ backend.hf_variant = "beta-Q4_K_M"
+ pin = {"id": build, "object": "model", "loaded": False}
+ mod, calls = _management(backend = backend, catalog = CATALOG + [pin])
+
+ with _client(mod) as client:
+ assert client.post("/models/unload", json = {"model": build}).status_code == 200
+
+ assert calls != []
+
+
+def test_an_indexed_build_key_matches_its_listed_base_row(monkeypatch, _no_local_gguf):
+ monkeypatch.setattr(
+ _no_local_gguf,
+ "local_gguf_pinned_variant",
+ lambda requested, **kwargs: "Q4_K_M" if requested == QWEN + ":beta-Q4_K_M" else None,
+ )
+ catalog = [{"id": QWEN, "object": "model"}]
+ mod, _calls = _management(backend = _Backend(), catalog = catalog)
+
+ assert mod._catalog_match(catalog, QWEN + ":beta-Q4_K_M") is not None
+ assert mod._catalog_match(catalog, QWEN + ":gamma-Q4_K_M") is None
+
+
+def test_a_build_key_is_matched_after_a_cold_index_scan(monkeypatch, _no_local_gguf):
+ import asyncio
+
+ warm = []
+
+ def _pinned(requested, allow_scan = True):
+ if allow_scan:
+ warm.append(requested)
+ return "beta-Q4_K_M" if warm and requested == QWEN + ":beta-Q4_K_M" else None
+
+ monkeypatch.setattr(_no_local_gguf, "local_gguf_pinned_variant", _pinned)
+ catalog = [{"id": QWEN, "object": "model"}]
+ mod, _calls = _management(backend = _Backend(), catalog = catalog)
+
+ async def _catalog():
+ return catalog
+
+ monkeypatch.setattr(mod, "_chat_catalog", _catalog)
+
+ assert asyncio.run(mod._catalog_row(QWEN + ":beta-Q4_K_M"))[0] == QWEN + ":beta-Q4_K_M"
+
+
def test_management_unload_of_a_bare_id_ignores_the_preferred_quant(monkeypatch, _no_local_gguf):
"""A bare id resolves to the preferred quant on disk, which need not be the resident one."""
monkeypatch.setattr(
diff --git a/studio/backend/tests/test_on_device_gguf_discovery.py b/studio/backend/tests/test_on_device_gguf_discovery.py
index 489e4fe4058..2b0674bfefc 100644
--- a/studio/backend/tests/test_on_device_gguf_discovery.py
+++ b/studio/backend/tests/test_on_device_gguf_discovery.py
@@ -209,6 +209,17 @@ def test_an_explicit_non_hub_folder_keeps_its_local_listing(cached_model, tmp_pa
assert cached_model.calls == []
+def test_an_explicit_folder_marks_every_build_at_one_quant_ready(cached_model, tmp_path):
+ local = tmp_path / "local-model"
+ local.mkdir()
+ for name in (MAIN, f"other-{QUANT}.gguf"):
+ (local / name).write_bytes((cached_model.snapshot / MAIN).read_bytes())
+ response = asyncio.run(
+ GV.get_gguf_variants_response(REPO, local_path = str(local), offline = True, hf_token = False)
+ )
+ assert sorted(v.quant for v in response.variants if v.downloaded) == [QUANT, f"other-{QUANT}"]
+
+
@pytest.mark.parametrize("prefix", ["/api/hub", "/api/models"])
def test_online_remote_discovery_still_lists_published_quants(cached_model, monkeypatch, prefix):
from hub.utils.gguf import GgufVariantInfo
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 1976455c403..7a2e38ff257 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -1825,6 +1825,111 @@ def test_a_sibling_quant_in_the_same_directory_is_not_the_resident_one(monkeypat
assert asyncio.run(inference_route._reject_unservable_model("org/model:Q4_K_M", _Req())) is None
+def test_a_sibling_build_stem_is_not_the_resident_one(monkeypatch):
+ entry = resolver._LocalGgufEntry("org/model", "/models/model", ("Q4_K_M", "beta-Q4_K_M"))
+ monkeypatch.setattr(resolver, "_scan", (time.monotonic(), {"org/model": entry}))
+ loaded = _Loaded("org/model", "Q4_K_M")
+ loaded.gguf_path = "/models/model/alpha-Q4_K_M.gguf"
+ monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+ monkeypatch.setattr(
+ inference_route,
+ "get_inference_backend",
+ lambda: type("B", (), {"active_model_name": None})(),
+ )
+ monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
+
+ with pytest.raises(HTTPException):
+ asyncio.run(inference_route._reject_unservable_model("org/model:beta-Q4_K_M", _Req()))
+
+
+def test_a_withheld_build_is_not_admitted_through_the_advertised_folder(monkeypatch):
+ entry = resolver._LocalGgufEntry(
+ "org/model", "/models/model", ("Q4_K_M",), withheld = ("beta-q4_k_m",), exact_builds = True
+ )
+ monkeypatch.setattr(resolver, "_scan", (time.monotonic(), {"org/model": entry}))
+ loaded = _Loaded("org/model", "Q4_K_M")
+ loaded.gguf_path = "/models/model/alpha-Q4_K_M.gguf"
+ monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+ monkeypatch.setattr(
+ inference_route,
+ "get_inference_backend",
+ lambda: type("B", (), {"active_model_name": None})(),
+ )
+ monkeypatch.setattr(inference_route, "_advertised_local_path", lambda name: "/models/model")
+ monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
+
+ with pytest.raises(HTTPException):
+ asyncio.run(inference_route._reject_unservable_model("org/model:beta-Q4_K_M", _Req()))
+
+
+def test_a_rekeyed_quant_directory_build_is_admitted_against_its_resident(monkeypatch):
+ entry = resolver._LocalGgufEntry(
+ "org/model",
+ "/models/model",
+ ("Q4_K_M",),
+ build_aliases = (("q4_k_m/beta-q4_k_m", "Q4_K_M"),),
+ exact_builds = True,
+ )
+ monkeypatch.setattr(resolver, "_scan", (time.monotonic(), {"org/model": entry}))
+ loaded = _Loaded("org/model", "Q4_K_M")
+ loaded.gguf_path = "/models/model/Q4_K_M/beta-Q4_K_M.gguf"
+ monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+ monkeypatch.setattr(
+ inference_route,
+ "get_inference_backend",
+ lambda: type("B", (), {"active_model_name": None})(),
+ )
+ monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
+
+ asyncio.run(inference_route._reject_unservable_model("org/model:Q4_K_M/beta-Q4_K_M", _Req()))
+
+
+def test_a_build_loaded_by_its_stem_still_answers_its_canonical_key(monkeypatch):
+ entry = resolver._LocalGgufEntry(
+ "org/model",
+ "/models/model",
+ ("Q4_K_M", "beta-Q4_K_M"),
+ build_aliases = (("alpha-q4_k_m", "Q4_K_M"),),
+ exact_builds = True,
+ )
+ monkeypatch.setattr(resolver, "_scan", (time.monotonic(), {"org/model": entry}))
+ loaded = _Loaded("org/model", "alpha-Q4_K_M")
+ loaded.gguf_path = "/models/model/alpha-Q4_K_M.gguf"
+ monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+ monkeypatch.setattr(
+ inference_route,
+ "get_inference_backend",
+ lambda: type("B", (), {"active_model_name": None})(),
+ )
+ monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
+
+ assert inference_route._loaded_satisfies("org/model:alpha-Q4_K_M") is True
+ assert inference_route._loaded_satisfies("org/model:beta-Q4_K_M") is False
+ asyncio.run(inference_route._reject_unservable_model("org/model:alpha-Q4_K_M", _Req()))
+
+
+def test_a_rekeyed_slash_pin_is_admitted_for_a_bare_local_id(monkeypatch):
+ entry = resolver._LocalGgufEntry(
+ "custom",
+ "/models/custom",
+ ("Q4_K_M",),
+ build_aliases = (("q4_k_m/beta-q4_k_m", "Q4_K_M"),),
+ exact_builds = True,
+ )
+ monkeypatch.setattr(resolver, "_scan", (time.monotonic(), {"custom": entry}))
+ loaded = _Loaded("custom", "Q4_K_M/beta-Q4_K_M")
+ loaded.gguf_path = "/models/custom/Q4_K_M/beta-Q4_K_M.gguf"
+ monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+ monkeypatch.setattr(
+ inference_route,
+ "get_inference_backend",
+ lambda: type("B", (), {"active_model_name": None})(),
+ )
+ monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
+
+ asyncio.run(inference_route._reject_unservable_model("custom:Q4_K_M/beta-Q4_K_M", _Req()))
+
+
def test_a_remote_tag_that_names_no_quant_picks_the_preferred_one(hub):
# ":latest" and ":8b" name no quant, so remote admission must default-select like a
# bare repo id (as the local resolver does) instead of 404ing on a non-quant.
@@ -1927,9 +2032,75 @@ def test_a_non_quant_tag_does_not_tear_down_a_serving_quant(monkeypatch):
monkeypatch.setattr(
"utils.openai_auto_switch_settings.get_openai_auto_switch_enabled", lambda: True
)
+ probes = []
+ real_pinned_variant = resolver.local_gguf_pinned_variant
+
+ def _record_probe(requested, allow_scan = True):
+ probes.append((requested, allow_scan))
+ return real_pinned_variant(requested, allow_scan = allow_scan)
+
+ monkeypatch.setattr(resolver, "local_gguf_pinned_variant", _record_probe)
for tag in ("org/model:latest", "org/model:8b", "org/model"):
asyncio.run(inference_route._maybe_auto_switch_model(tag, _Req(), "tester"))
assert loads == [], "a tag naming no quant swapped the serving model out"
+ assert probes == [("org/model:latest", False), ("org/model:8b", False)]
+
+
+def test_a_split_build_stem_switches_away_from_the_resident_sibling(monkeypatch):
+ entry = resolver._LocalGgufEntry("org/model", "/models/model", ("Q4_K_M", "beta-Q4_K_M"))
+ monkeypatch.setattr(resolver, "_scan", (time.monotonic(), {"org/model": entry}))
+ loaded = _Loaded("org/model", "Q4_K_M")
+ loaded.gguf_path = "/models/model/alpha-Q4_K_M.gguf"
+ monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+ monkeypatch.setattr(
+ inference_route,
+ "get_inference_backend",
+ lambda: type("B", (), {"active_model_name": None})(),
+ )
+ loads: list = []
+
+ async def _record_load(request, *args, **kwargs):
+ variant = getattr(request, "gguf_variant", None)
+ loads.append(variant)
+ loaded.hf_variant = variant
+
+ monkeypatch.setattr(inference_route, "_load_model_impl", _record_load)
+ monkeypatch.setattr(
+ "utils.openai_auto_switch_settings.get_openai_auto_switch_enabled", lambda: True
+ )
+
+ asyncio.run(inference_route._maybe_auto_switch_model("org/model:beta-Q4_K_M", _Req(), "tester"))
+
+ assert loads == ["beta-Q4_K_M"]
+
+
+def test_a_quant_directory_build_key_switches_away_from_the_resident_sibling(monkeypatch):
+ key = "Q4_K_M/beta-Q4_K_M"
+ entry = resolver._LocalGgufEntry("custom-model", "/models/model", ("Q4_K_M", key))
+ monkeypatch.setattr(resolver, "_scan", (time.monotonic(), {"custom-model": entry}))
+ loaded = _Loaded("custom-model", "Q4_K_M")
+ loaded.gguf_path = "/models/model/Q4_K_M/alpha-Q4_K_M.gguf"
+ monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+ monkeypatch.setattr(
+ inference_route,
+ "get_inference_backend",
+ lambda: type("B", (), {"active_model_name": None})(),
+ )
+ loads: list = []
+
+ async def _record_load(request, *args, **kwargs):
+ variant = getattr(request, "gguf_variant", None)
+ loads.append(variant)
+ loaded.hf_variant = variant
+
+ monkeypatch.setattr(inference_route, "_load_model_impl", _record_load)
+ monkeypatch.setattr(
+ "utils.openai_auto_switch_settings.get_openai_auto_switch_enabled", lambda: True
+ )
+
+ asyncio.run(inference_route._maybe_auto_switch_model(f"custom-model:{key}", _Req(), "tester"))
+
+ assert loads == [key]
def test_the_trust_probe_never_falls_back_to_the_server_identity(hub, monkeypatch):
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index dda419fbcf3..9d56113adf1 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -725,6 +725,185 @@ def test_local_gguf_entry_filters_non_gguf_and_recurses(tmp_path):
assert e2 is not None and e2.variants
+def test_local_gguf_entry_uses_the_variantless_same_quant_default(tmp_path):
+ alpha = tmp_path / "alpha-Q4_K_M.gguf"
+ beta_one = tmp_path / "beta-Q4_K_M-00001-of-00002.gguf"
+ beta_two = tmp_path / "beta-Q4_K_M-00002-of-00002.gguf"
+ alpha.write_bytes(b"x" * 100)
+ beta_one.write_bytes(b"x" * 60)
+ beta_two.write_bytes(b"x" * 60)
+
+ entry = resolver._local_gguf_entry("local/model", SimpleNamespace(path = str(tmp_path)))
+
+ assert entry is not None
+ assert entry.variants[0] == "Q4_K_M"
+ assert resolver._resolve_from_index("local/model", {"local/model": entry})[1] == "Q4_K_M"
+
+
+def test_local_gguf_entry_does_not_publish_a_torn_sibling_build(tmp_path):
+ (tmp_path / "alpha-Q4_K_M.gguf").write_bytes(b"x" * 100)
+ (tmp_path / "beta-Q4_K_M-00001-of-00002.gguf").write_bytes(b"x" * 200)
+
+ entry = resolver._local_gguf_entry("local/model", SimpleNamespace(path = str(tmp_path)))
+
+ assert entry is not None
+ assert entry.variants == ("Q4_K_M",)
+
+
+def test_local_gguf_entry_keeps_a_split_build_linked_to_its_complete_set(tmp_path):
+ store = tmp_path / "store"
+ store.mkdir()
+ for index in (1, 2):
+ (store / f"beta-Q4_K_M-0000{index}-of-00002.gguf").write_bytes(b"x" * 60)
+ folder = tmp_path / "models"
+ folder.mkdir()
+ (folder / "alpha-Q4_K_M.gguf").write_bytes(b"x" * 100)
+ try:
+ (folder / "beta-Q4_K_M-00001-of-00002.gguf").symlink_to(
+ store / "beta-Q4_K_M-00001-of-00002.gguf"
+ )
+ except (OSError, NotImplementedError):
+ pytest.skip("symlinks unavailable")
+
+ entry = resolver._local_gguf_entry("local/model", SimpleNamespace(path = str(folder)))
+
+ assert entry is not None
+ assert len(entry.variants) == 2
+
+
+def test_local_gguf_entry_keeps_the_preferred_quant_over_a_larger_sibling_build(tmp_path):
+ (tmp_path / "model-Q4_K_M.gguf").write_bytes(b"x" * 50)
+ (tmp_path / "alpha-F16.gguf").write_bytes(b"x" * 100)
+ (tmp_path / "beta-F16.gguf").write_bytes(b"x" * 120)
+
+ entry = resolver._local_gguf_entry("local/model", SimpleNamespace(path = str(tmp_path)))
+
+ assert entry is not None
+ assert entry.variants[0] == "Q4_K_M"
+
+
+def test_a_torn_build_key_misses_instead_of_serving_its_sibling(tmp_path, monkeypatch):
+ (tmp_path / "alpha-Q4_K_M.gguf").write_bytes(b"x" * 100)
+ (tmp_path / "beta-Q4_K_M-00001-of-00002.gguf").write_bytes(b"x" * 200)
+ entry = resolver._local_gguf_entry("local/model", SimpleNamespace(path = str(tmp_path)))
+ assert entry is not None and "beta-q4_k_m" in entry.withheld
+
+ index = {"local/model": entry}
+ assert resolver._resolve_from_index("local/model:beta-Q4_K_M", index) is None
+ assert resolver._resolve_from_index("local/model:latest", index)[1] == "Q4_K_M"
+ torn_first = resolver._LocalGgufEntry(
+ "local/model",
+ str(tmp_path),
+ ("beta-Q4_K_M",),
+ aliases = (("q4_k_m", "beta-Q4_K_M"),),
+ withheld = ("q4_k_m",),
+ )
+ assert resolver._resolve_from_index("local/model:Q4_K_M", {"local/model": torn_first}) is None
+
+ monkeypatch.setattr(resolver, "_scan", (1.0, index))
+ loaded = _FakeBackend(loaded_id = "local/model", hf_variant = "Q4_K_M")
+ monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+ assert inference_route._loaded_satisfies("local/model:beta-Q4_K_M") is False
+ assert inference_route._loaded_satisfies("local/model:latest") is True
+
+
+def test_a_build_stem_still_resolves_after_its_sibling_is_removed(tmp_path):
+ (tmp_path / "alpha-F16.gguf").write_bytes(b"x" * 80)
+ (tmp_path / "beta-F16.gguf").write_bytes(b"x" * 80)
+ (tmp_path / "model-Q4_K_M.gguf").write_bytes(b"x" * 40)
+ entry = resolver._local_gguf_entry("local/model", SimpleNamespace(path = str(tmp_path)))
+ assert "beta-F16" in entry.variants
+
+ (tmp_path / "alpha-F16.gguf").unlink()
+ entry = resolver._local_gguf_entry("local/model", SimpleNamespace(path = str(tmp_path)))
+
+ resolved = resolver._resolve_from_index("local/model:beta-F16", {"local/model": entry})
+ assert resolved is not None and resolved[1] == "F16"
+ assert entry.aliases == ()
+
+
+def test_a_filename_build_key_still_resolves_after_its_sibling_is_removed(tmp_path):
+ (tmp_path / "0-model-F16.gguf").write_bytes(b"x" * 80)
+ (tmp_path / "F16.gguf").write_bytes(b"x" * 80)
+ (tmp_path / "model-Q4_K_M.gguf").write_bytes(b"x" * 40)
+ entry = resolver._local_gguf_entry("local/model", SimpleNamespace(path = str(tmp_path)))
+ assert "F16.gguf" in entry.variants
+
+ (tmp_path / "0-model-F16.gguf").unlink()
+ entry = resolver._local_gguf_entry("local/model", SimpleNamespace(path = str(tmp_path)))
+
+ resolved = resolver._resolve_from_index("local/model:F16.gguf", {"local/model": entry})
+ assert resolved is not None and resolved[1] == "F16"
+
+
+def test_a_deleted_build_stem_misses_instead_of_serving_its_sibling(tmp_path, monkeypatch):
+ (tmp_path / "alpha-Q4_K_M.gguf").write_bytes(b"x" * 100)
+ (tmp_path / "beta-Q4_K_M.gguf").write_bytes(b"x" * 90)
+ (tmp_path / "beta-Q4_K_M.gguf").unlink()
+ entry = resolver._local_gguf_entry("local/model", SimpleNamespace(path = str(tmp_path)))
+ index = {"local/model": entry}
+
+ assert resolver._resolve_from_index("local/model:beta-Q4_K_M", index) is None
+ assert resolver._resolve_from_index("local/model:alpha-Q4_K_M", index)[1] == "Q4_K_M"
+ assert resolver._resolve_from_index("local/model:latest", index)[1] == "Q4_K_M"
+
+ monkeypatch.setattr(resolver, "_scan", (1.0, index))
+ loaded = _FakeBackend(loaded_id = "local/model", hf_variant = "Q4_K_M")
+ monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+ assert inference_route._loaded_satisfies("local/model:beta-Q4_K_M") is False
+ assert inference_route._loaded_satisfies("local/model:alpha-Q4_K_M") is True
+
+
+def test_a_deleted_quant_directory_build_is_withheld(tmp_path, monkeypatch):
+ (tmp_path / "Q4_K_M").mkdir()
+ (tmp_path / "Q4_K_M" / "alpha-Q4_K_M.gguf").write_bytes(b"x" * 100)
+ entry = resolver._local_gguf_entry("custom-model", SimpleNamespace(path = str(tmp_path)))
+ index = {"custom-model": entry}
+ pin = "custom-model:Q4_K_M/beta-Q4_K_M"
+
+ assert resolver._resolve_from_index(pin, index) is None
+ monkeypatch.setattr(resolver, "_scan", (1.0, index))
+ assert resolver.local_gguf_withheld(pin) is True
+ assert resolver.local_gguf_withheld("custom-model:latest") is False
+
+
+def test_a_quant_directory_build_pin_is_authorized_by_its_base_model(monkeypatch):
+ from fastapi import HTTPException
+
+ def _refuse(_name):
+ raise HTTPException(status_code = 404, detail = "Model not found")
+
+ async def _no_catalog():
+ return None
+
+ async def _no_token(*_args):
+ return False
+
+ pinned = "custom-model:Q4_K_M/beta-Q4_K_M"
+ monkeypatch.setattr(inference_route.account_access, "require_model_access", _refuse)
+ monkeypatch.setattr(inference_route, "_cached_local_catalog", _no_catalog)
+ monkeypatch.setattr(inference_route, "_caller_token_authorizes_download", _no_token)
+ monkeypatch.setattr(
+ inference_route,
+ "_own_local_model_for_alias",
+ lambda alias: "/models/custom" if alias == "custom-model" else None,
+ )
+ scans = []
+
+ def _pinned(requested, allow_scan = True):
+ scans.append(allow_scan)
+ return "Q4_K_M/beta-Q4_K_M" if requested == pinned else None
+
+ monkeypatch.setattr(resolver, "local_gguf_pinned_variant", _pinned)
+
+ asyncio.run(inference_route._require_named_model_access(pinned))
+ # a cold index after restart must not refuse the pin, so this lookup may scan
+ assert scans[-1] is True
+ with pytest.raises(HTTPException) as refused:
+ asyncio.run(inference_route._require_named_model_access("custom-model:Q4_K_M/other"))
+ assert refused.value.status_code == 404
+
+
def test_local_gguf_entry_labels_a_quantless_filename_as_the_picker_does(tmp_path):
# No quant token in the name, so the picker and every saved setting key this variant by
# the stem. Labelling it "v2" here left an API load reading a key nothing wrote (#10227).
@@ -8728,6 +8907,21 @@ def test_two_local_paths_differing_only_in_case_are_not_the_same_model(monkeypat
assert inference_route._loaded_satisfies("unsloth/qwen3-4b-gguf") is True
+def test_a_cold_index_does_not_answer_a_build_stem_with_the_resident_sibling(monkeypatch):
+ # alpha-Q4_K_M is resident under the bare Q4_K_M key; before the first scan nothing can
+ # pin beta-Q4_K_M, so the resident sibling must not count as serving it (#13957).
+ loaded = _FakeBackend(loaded_id = "local/model")
+ loaded.hf_variant = "Q4_K_M"
+ monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+ monkeypatch.setattr(resolver, "_scan", (0.0, {}))
+ assert inference_route._loaded_satisfies("local/model:beta-Q4_K_M") is False
+ assert inference_route._loaded_satisfies("local/model:latest") is True
+ assert inference_route._loaded_satisfies("local/model:Q4_K_M") is True
+
+ monkeypatch.setattr(resolver, "_scan", (1.0, {}))
+ assert inference_route._loaded_satisfies("local/model:beta-Q4_K_M") is True
+
+
def test_abs_path_ids_are_recognised_in_either_platform_spelling():
"""Path() follows the running OS, so a Windows host read "/home/me/x.gguf" as
relative and a POSIX host read "C:\\models\\x.gguf" the same way, and either
diff --git a/studio/backend/tests/test_openai_models_media.py b/studio/backend/tests/test_openai_models_media.py
index 3414351dab7..f648206450f 100644
--- a/studio/backend/tests/test_openai_models_media.py
+++ b/studio/backend/tests/test_openai_models_media.py
@@ -262,6 +262,126 @@ def test_a_standalone_gguf_resident_is_matched_by_its_load_directory(monkeypatch
assert "/srv/" not in json.dumps(data)
+def test_media_index_keeps_same_quant_custom_builds(tmp_path, monkeypatch):
+ names = ["alpha-Q4_K_M.gguf", "beta-Q4_K_M.gguf"]
+ for name in names:
+ (tmp_path / name).write_bytes(b"x")
+ info = _Info("local-image", "Local Image", path = str(tmp_path), task = "text-to-image")
+ monkeypatch.setattr(mmi, "_loader_can_open", lambda *_args: True)
+
+ picks = {}
+ assert mmi._add_gguf_picks(picks, info, (info.id,), tmp_path, tmp_path)
+
+ assert picks["local-image:q4_k_m"].gguf_filename == names[0]
+ assert picks["local-image:beta-q4_k_m"].gguf_filename == names[1]
+
+ marked = mmi._mark_ambiguous_builds(picks)
+ beta = marked["local-image:beta-q4_k_m"]
+ assert beta.ambiguous
+ assert mmi.satisfied_by(
+ {
+ "loaded": True,
+ "repo_id": str(tmp_path),
+ "gguf_variant": "Q4_K_M",
+ "gguf_filename": names[1],
+ "model_kind": "gguf",
+ },
+ "local-image:beta-q4_k_m",
+ beta,
+ )
+
+
+def test_media_index_keeps_the_legacy_fallback_quant_alias(tmp_path, monkeypatch):
+ filename = "flux1-dev-fp16.gguf"
+ (tmp_path / filename).write_bytes(b"x")
+ info = _Info("local-image", "Local Image", path = str(tmp_path), task = "text-to-image")
+ monkeypatch.setattr(mmi, "_loader_can_open", lambda *_args: True)
+
+ picks = {}
+ assert mmi._add_gguf_picks(picks, info, (info.id,), tmp_path, tmp_path)
+
+ assert picks["local-image:flux1-dev-fp16"].gguf_filename == filename
+ assert picks["local-image:fp16"].gguf_filename == filename
+
+
+def test_legacy_media_alias_does_not_replace_a_current_exact_key(tmp_path, monkeypatch):
+ legacy = "flux1-dev-fp16.gguf"
+ exact = "fp16.gguf"
+ for filename in (legacy, exact):
+ (tmp_path / filename).write_bytes(b"x")
+ info = _Info("local-image", "Local Image", path = str(tmp_path), task = "text-to-image")
+ monkeypatch.setattr(mmi, "_loader_can_open", lambda *_args: True)
+
+ picks = {}
+ assert mmi._add_gguf_picks(picks, info, (info.id,), tmp_path, tmp_path)
+
+ assert picks["local-image:flux1-dev-fp16"].gguf_filename == legacy
+ assert picks["local-image:fp16"].gguf_filename == exact
+
+
+def test_media_bare_id_matches_variantless_local_file_ranking(tmp_path, monkeypatch):
+ alpha = "alpha-Q4_K_M.gguf"
+ beta = "beta-Q4_K_M-00001-of-00002.gguf"
+ (tmp_path / alpha).write_bytes(b"x" * 100)
+ (tmp_path / beta).write_bytes(b"x" * 60)
+ (tmp_path / "beta-Q4_K_M-00002-of-00002.gguf").write_bytes(b"x" * 60)
+ info = _Info("local-image", "Local Image", path = str(tmp_path), task = "text-to-image")
+ monkeypatch.setattr(mmi, "_loader_can_open", lambda *_args: True)
+
+ picks = {}
+ assert mmi._add_gguf_picks(picks, info, (info.id,), tmp_path, tmp_path)
+
+ assert picks["local-image"].gguf_filename == alpha
+
+
+def test_a_larger_sibling_build_does_not_override_the_preferred_media_quant(tmp_path, monkeypatch):
+ (tmp_path / "model-Q4_K_M.gguf").write_bytes(b"x" * 50)
+ (tmp_path / "alpha-F16.gguf").write_bytes(b"x" * 100)
+ (tmp_path / "beta-F16.gguf").write_bytes(b"x" * 120)
+ info = _Info("local-image", "Local Image", path = str(tmp_path), task = "text-to-image")
+ monkeypatch.setattr(mmi, "_loader_can_open", lambda *_args: True)
+
+ picks = {}
+ assert mmi._add_gguf_picks(picks, info, (info.id,), tmp_path, tmp_path)
+
+ assert picks["local-image"].gguf_filename == "model-Q4_K_M.gguf"
+
+
+def test_a_media_build_stem_survives_its_sibling_removal(tmp_path, monkeypatch):
+ (tmp_path / "alpha-Q4_K_M.gguf").write_bytes(b"x" * 100)
+ (tmp_path / "beta-Q4_K_M.gguf").write_bytes(b"x" * 90)
+ info = _Info("local-image", "Local Image", path = str(tmp_path), task = "text-to-image")
+ monkeypatch.setattr(mmi, "_loader_can_open", lambda *_args: True)
+ picks = {}
+ assert mmi._add_gguf_picks(picks, info, (info.id,), tmp_path, tmp_path)
+ assert picks["local-image:beta-q4_k_m"].gguf_filename == "beta-Q4_K_M.gguf"
+
+ (tmp_path / "alpha-Q4_K_M.gguf").unlink()
+ picks = {}
+ assert mmi._add_gguf_picks(picks, info, (info.id,), tmp_path, tmp_path)
+
+ assert picks["local-image:beta-q4_k_m"].gguf_filename == "beta-Q4_K_M.gguf"
+
+
+def test_quant_directory_siblings_share_the_media_default_scope(tmp_path, monkeypatch):
+ quant_dir = tmp_path / "Q4_K_M"
+ quant_dir.mkdir()
+ alpha = "Q4_K_M/alpha-Q4_K_M.gguf"
+ beta = "Q4_K_M/beta-Q4_K_M.gguf"
+ (tmp_path / alpha).write_bytes(b"x" * 100)
+ (tmp_path / beta).write_bytes(b"x" * 120)
+ info = _Info("local-image", "Local Image", path = str(tmp_path), task = "text-to-image")
+ monkeypatch.setattr(mmi, "_loader_can_open", lambda *_args: True)
+ monkeypatch.setattr(
+ "utils.models.model_config.detect_gguf_model", lambda *_args: str(tmp_path / beta)
+ )
+
+ picks = {}
+ assert mmi._add_gguf_picks(picks, info, (info.id,), tmp_path, tmp_path)
+
+ assert picks["local-image"].gguf_filename == beta
+
+
def test_edit_only_checkpoints_are_not_offered_for_text_to_image(monkeypatch):
"""The catalog tags an instruction-editing checkpoint text-to-image, but it ships no
txt2img workflow: the switch refuses it with a 400 and a resident one is refused by
diff --git a/studio/backend/tests/test_picker_service.py b/studio/backend/tests/test_picker_service.py
index 230512c7c4e..3019a702f4d 100644
--- a/studio/backend/tests/test_picker_service.py
+++ b/studio/backend/tests/test_picker_service.py
@@ -46,6 +46,27 @@ def test_find_gguf_in_dir_matches_quant_label(tmp_path):
assert _find_gguf_in_dir(tmp_path, "Q4_K") is None
+def test_find_gguf_in_dir_matches_a_same_quant_build_key(tmp_path):
+ alpha = tmp_path / "alpha-Q4_K_M.gguf"
+ beta = tmp_path / "beta-Q4_K_M-00001-of-00002.gguf"
+ alpha.write_bytes(b"GGUF")
+ beta.write_bytes(b"GGUF")
+ (tmp_path / "beta-Q4_K_M-00002-of-00002.gguf").write_bytes(b"GGUF")
+
+ assert _find_gguf_in_dir(tmp_path, "beta-Q4_K_M") == beta
+ assert _find_gguf_in_dir(tmp_path, "Q4_K_M") == alpha
+
+
+def test_find_gguf_in_dir_matches_a_filename_build_key(tmp_path):
+ first = tmp_path / "0-model-Q4_K_M.gguf"
+ bare = tmp_path / "Q4_K_M.gguf"
+ first.write_bytes(b"GGUF")
+ bare.write_bytes(b"GGUF")
+
+ assert _find_gguf_in_dir(tmp_path, "Q4_K_M.gguf") == bare
+ assert _find_gguf_in_dir(tmp_path, "Q4_K_M") == first
+
+
def test_find_gguf_in_dir_without_variant_prefers_largest_model(tmp_path):
smaller = tmp_path / "a-model-Q4_K_M.gguf"
larger = tmp_path / "z-model-Q8_0.gguf"