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: centralize GGUF identity rules and exclude incomplete GGUF splits (#15073)

oobabooga0edb8f511efd
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index fd78923ff4f..63c2ebd01ce 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -585,6 +585,8 @@ from utils.first_token_timeout import (
# The leaf module, not utils.models: importing anything from that package runs its __init__,
# which pulls in model_config and therefore PyYAML. This is the chat backend, imported wherever
# Unsloth's Python is, so it must not make the whole models package a hard import dependency.
+from utils import gguf_archs as _gguf_archs
+from utils import gguf_names as _gguf_names
from utils.gguf_archs import (
SPEECH_GGUF_ARCHS as _SPEECH_GGUF_ARCHS,
is_audio_cpp_gguf_architecture,
@@ -3417,64 +3419,30 @@ def _is_mtp_model_name(model_identifier: Optional[str], gguf_path: Optional[str]
return False
-# Mirrors hub.utils.gguf._DRAFTER_KINDS / _DRAFTER_DIR_KINDS.
-_DRAFTER_KINDS = ("mtp", "dspark", "dflash", "eagle3", "lilicorr")
-_DRAFTER_DIR_KINDS = ("mtp", "dspark")
+_DRAFTER_KINDS = _gguf_names.DRAFTER_KINDS
+_DRAFTER_DIR_KINDS = _gguf_names.DRAFTER_DIR_KINDS
# Human label per resolved spec mode, for launch logging and the UI notice.
_DRAFTER_DISPLAY_LABELS = {"dspark": "DSpark", "dflash": "DFlash", "eagle3": "EAGLE-3"}
def _drafter_path_kind(path: str) -> Optional[str]:
- """Drafter kind naming *path*: basename prefix, or exact parent dir for
- ``_DRAFTER_DIR_KINDS``. Never a substring: the kind names double as family
- names, so ``Qwen3.6-35B-A3B-DFlash-Q4_K_M.gguf`` IS the model, as is anything
- in a user's ``dflash/`` folder."""
- p = path.replace("\\", "/").lower()
- if not p.endswith(".gguf"):
- return None
- parts = [segment for segment in p.split("/") if segment]
- name, parents = parts[-1], parts[:-1]
- for kind in _DRAFTER_KINDS:
- if name.startswith(f"{kind}-"):
- return kind
- for kind in _DRAFTER_DIR_KINDS:
- if kind in parents:
- return kind
- return None
+ return _gguf_names.drafter_path_kind(path)
-_IMATRIX_TOKEN_RE = re.compile(r"^imatrix(?:[._\-]|$)|[._\-]imatrix$", re.IGNORECASE)
-# Mirrors hub.utils.gguf._IMATRIX_WEIGHTED_RE.
-_IMATRIX_WEIGHTED_RE = re.compile(
- r"[._\-](?:I?Q[0-9]+_|P?TQ[0-9]+_|(?:MX|NV)FP[0-9])[^/]*[_\-]imatrix$", re.IGNORECASE
-)
+_IMATRIX_TOKEN_RE = _gguf_names.IMATRIX_TOKEN_RE
def _is_companion_gguf_path(path: str) -> bool:
- """True for a non-main GGUF: vision mmproj, a calibration imatrix, or a separate
- drafter (repo-root ``mtp-*.gguf``, the ``MTP/`` subdir copies for Gemma 4, the ``dspark/``
- drafters for DeepSeek V4 Flash, the ``<model>-dspark-<quant>.gguf`` drafters for
- prism-ml Bonsai, the ``eagle3-*.gguf`` draft heads). Mirrors
- hub.utils.gguf so variant resolution never picks a companion as the main model --
- a Gemma ``Q8_0`` request must not resolve to ``MTP/...-Q8_0-MTP.gguf``, which sorts
- ahead of the real weight.
-
- EXCLUSION ONLY. Use ``_is_mtp_only_drafter_path`` to pick a drafter to launch.
- """
+ """Exclude companions from main-model selection; use _is_mtp_only_drafter_path for launch."""
p = path.lower()
if not p.endswith(".gguf"):
return False
if "mmproj" in p:
return True
- # Mirrors hub.utils.gguf.is_imatrix_filename: an imatrix is a valid GGUF container
- # holding calibration statistics, so only the name rules it out.
- stem = Path(p).stem
- if _IMATRIX_TOKEN_RE.search(stem) and not _IMATRIX_WEIGHTED_RE.search(stem):
+ if _gguf_names.is_imatrix_filename(p):
return True
- if _DSPARK_BEFORE_QUANT_RE.search(Path(p).name):
- return True
- return _drafter_path_kind(path) is not None
+ return _gguf_names.is_mtp_drafter_path(path)
def _is_mtp_only_drafter_path(path: str) -> bool:
@@ -3531,22 +3499,8 @@ def _is_root_dflash_drafter_path(path: str) -> bool:
_BIG_ENDIAN_GGUF_FILENAME_RE = re.compile(r"(^|[-_])be(?:[._-]|$)", re.IGNORECASE)
-_GGUF_KNOWN_QUANT_RE = re.compile(
- r"(UD-)?"
- r"((?:MX|NV)FP[0-9]+(?:_[A-Z0-9]+)*"
- r"|IQ[0-9]+_[A-Z]+(?:_[A-Z0-9]+)?"
- r"|P?TQ[0-9]+_[0-9]+"
- r"|Q[0-9]+_K_[A-Z]+"
- r"|P?Q[0-9]+_(?:[0-9]+(?:_G[0-9]+)?|G[0-9]+)"
- r"|Q[0-9]+_K"
- r"|BF16|F16|F32)",
- re.IGNORECASE,
-)
-# Mirrors hub.utils.gguf._DSPARK_BEFORE_QUANT_RE, for _is_companion_gguf_path.
-_DSPARK_BEFORE_QUANT_RE = re.compile(
- rf"-dspark-(?:{_GGUF_KNOWN_QUANT_RE.pattern})(?:-[0-9]{{5}}-of-[0-9]{{5}})?\.gguf$",
- re.IGNORECASE,
-)
+_GGUF_KNOWN_QUANT_RE = _gguf_names.GGUF_QUANT_RE
+_DSPARK_BEFORE_QUANT_RE = _gguf_names.DSPARK_BEFORE_QUANT_RE
def _is_big_endian_gguf_path(path: str, variant_key: str = "") -> bool:
@@ -22462,79 +22416,16 @@ class LlamaCppBackend:
return None
return str(mtp_draft_path)
- # ── Lifecycle ─────────────────────────────────────────────────
-
- # GGUF ``general.architecture`` values for diffusion / image models.
- # llama.cpp has no such architectures, so loading one as a chat model dies
- # with "unknown model architecture: '<arch>'". These match the patched
- # stable-diffusion.cpp / ComfyUI-GGUF enums. Unsloth publishes FLUX and
- # Qwen-Image GGUFs under
- # https://huggingface.co/collections/unsloth/unsloth-diffusion-ggufs.
- # Matched exactly (not a substring) so a chat arch containing "wan"/"sd1"
- # (e.g. "taiwan") isn't misrouted to Images.
- _IMAGE_ARCHES = frozenset(
- (
- "qwen_image",
- "qwen_image21",
- "flux",
- # Krea 2 GGUFs from some converters (molbal/krea2-gguf), #14474.
- "krea2",
- )
- )
- # Archs shared by more than one family, so the header alone does NOT say whether the
- # Images page can run the file: Z-Image's DiT is a Lumina2 derivative, so its GGUFs
- # declare "lumina2" too (measured on unsloth/Z-Image-Turbo-GGUF/z-image-turbo-Q2_K.gguf
- # and on calcuis/lumina-gguf). ``routes.models._arch_to_task`` resolves these from the
- # repo id and the filename and tags the rest ``image-diffusion-unsupported``, hiding
- # them from the Images picker, so the refusal must run the SAME resolution before it
- # names that page -- e.g. ``neta-art/neta-lumina-gguf/checkpoint-e3_s9658-*.gguf``
- # declares "lumina2" and resolves to no family ("lumina-2" is not aliased to bare
- # "lumina"). Mirrors ``routes.models._AMBIGUOUS_DIFFUSION_GGUF_ARCHS``.
- _AMBIGUOUS_IMAGE_ARCHES = frozenset(("lumina2",))
- # Text-to-video archs the Video page can offer. Split from the image set so the refusal
- # names Video: sending a Wan / LTX-2 GGUF to Images is a second dead end.
- _VIDEO_ARCHES = frozenset(
- (
- "ltxv",
- "wan",
- )
- )
- # Media archs Unsloth recognises but NO page can run, so the refusal must not promise
- # one. Mirrors ``routes.models._UNSUPPORTED_DIFFUSION_GGUF_ARCHS``, which tags these
- # ``image-diffusion-unsupported`` and so hides them from the Images AND Video pickers.
- # * "cosmos": no VideoFamily exists at all (``detect_video_family`` returns None for
- # every cosmos repo id and for override="cosmos"), and the published cosmos GGUFs
- # are Cosmos-Predict2-14B-Text2Image, which Images cannot assemble either.
- # * "hyvid": HunyuanVideo 1.0 has no VideoFamily, and the 1.5 GGUFs that do map to
- # one are still tagged unsupported (that family ships no ``gguf_repo``).
- # * "sd1" / "sd3" / "sdxl" / "aura" / "hidream": unsupported on the image side for
- # the same reason, so "use the Images page" was always an empty promise.
- # Kept inside _DIFFUSION_ARCHES so the pre-launch refusal still fires, it just names no
- # destination. Mirrors the whole set: a partial mirror leaves the same dead end.
- _UNRUNNABLE_MEDIA_ARCHES = frozenset(
- (
- "cosmos",
- "hyvid",
- "sd1",
- "sd3",
- "sdxl",
- "aura",
- "hidream",
- )
- )
+ _IMAGE_ARCHES = _gguf_archs.DIFFUSION_IMAGE_GGUF_ARCHS
+ _AMBIGUOUS_IMAGE_ARCHES = _gguf_archs.AMBIGUOUS_DIFFUSION_GGUF_ARCHS
+ _VIDEO_ARCHES = _gguf_archs.VIDEO_GGUF_ARCHS
+ _UNRUNNABLE_MEDIA_ARCHES = _gguf_archs.UNSUPPORTED_DIFFUSION_GGUF_ARCHS
_DIFFUSION_ARCHES = (
_IMAGE_ARCHES | _AMBIGUOUS_IMAGE_ARCHES | _VIDEO_ARCHES | _UNRUNNABLE_MEDIA_ARCHES
)
- # TTS archs llama.cpp cannot load (CSM support is only on an unmerged upstream branch). One
- # shared definition, so this gate and the listing classifier cannot drift.
_SPEECH_ARCHES = _SPEECH_GGUF_ARCHS
- # Not architectures: the literal placeholders gguf-connector writes into
- # general.architecture for its diffusion GGUFs (gguf-org/flux2-dev-gguf and
- # calcuis/cosmos-predict2-gguf both declare "pig"); ComfyUI-GGUF special cases the same
- # two. llama.cpp knows neither, so without this they slip past the arch sets and die in
- # llama-server as the opaque failure this preflight exists to prevent.
- _PLACEHOLDER_ARCHES = frozenset(("pig", "cow"))
+ _PLACEHOLDER_ARCHES = _gguf_archs.PLACEHOLDER_DIFFUSION_GGUF_ARCHS
@staticmethod
def _video_arch_is_pickable(
diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index 3d556ab9888..0c4e255a5f7 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -419,21 +419,22 @@ def _local_gguf_entry(
else:
selected_variants, _has_vision, complete, load_dir = selected
variants, _ = list_local_gguf_variants(str(load_dir), require_existing_files = True)
- if complete:
- complete_keys = {str(quant).casefold() for quant in complete}
- complete_files = {
- str(variant.filename).casefold()
- for variant in selected_variants
- if getattr(variant, "filename", None)
- and getattr(variant, "quant", None)
- and str(variant.quant).casefold() in complete_keys
- }
- variants = [
- variant
- for variant in variants
- if getattr(variant, "filename", None)
- and str(variant.filename).casefold() in complete_files
- ]
+ # Filter even when nothing is complete: the selector can fall back to a snapshot
+ # with no whole quant, and its torn split shards must not be offered.
+ complete_keys = {str(quant).casefold() for quant in complete}
+ complete_files = {
+ str(variant.filename).casefold()
+ for variant in selected_variants
+ if getattr(variant, "filename", None)
+ and getattr(variant, "quant", None)
+ and str(variant.quant).casefold() in complete_keys
+ }
+ variants = [
+ variant
+ for variant in variants
+ if getattr(variant, "filename", None)
+ and str(variant.filename).casefold() in complete_files
+ ]
else:
load_dir = _resolve_load_dir(p) if p.name.startswith("models--") else p
variants, _ = list_local_gguf_variants(str(load_dir), require_existing_files = True)
@@ -1087,6 +1088,26 @@ def recently_downloaded(repo_id: str) -> bool:
return repo_id.strip().lower() in _just_downloaded
+def local_gguf_torn_only(repo_id: str) -> bool:
+ """Whether the HF cache holds GGUF builds of *repo_id* that the index left out because none is whole."""
+ if not isinstance(repo_id, str) or repo_id.strip().count("/") != 1:
+ return False
+ try:
+ from hub.utils.gguf import list_local_gguf_variants
+ from hub.utils.hf_cache_state import iter_repo_cache_dirs
+ for repo_dir in iter_repo_cache_dirs("model", repo_id.strip()):
+ snapshots = repo_dir / "snapshots"
+ if not snapshots.is_dir():
+ continue
+ for snapshot in snapshots.iterdir():
+ variants, _ = list_local_gguf_variants(str(snapshot))
+ if any(getattr(v, "quant", None) for v in variants):
+ return True
+ except Exception:
+ return False
+ return False
+
+
def _snapshot_is_trusted(
timestamp: float,
now: float,
diff --git a/studio/backend/hub/services/models/catalog_classification.py b/studio/backend/hub/services/models/catalog_classification.py
index 60eb39022dd..d4e0d677a2a 100644
--- a/studio/backend/hub/services/models/catalog_classification.py
+++ b/studio/backend/hub/services/models/catalog_classification.py
@@ -16,6 +16,7 @@ from hub.services.models.common import (
_iter_gguf_paths,
_local_path_can_chat,
)
+from utils import gguf_archs as _gguf_archs
from utils.gguf_archs import (
SPEECH_GGUF_ARCHS,
is_audio_cpp_gguf_architecture,
@@ -24,27 +25,12 @@ from utils.gguf_archs import (
from utils.paths.path_utils import file_contents_available_locally
-_DIFFUSION_GGUF_ARCHS = frozenset(
- {
- "flux",
- "flux2",
- "qwen_image",
- "qwenimage",
- "qwen_image21",
- "qwenimage21",
- "z_image",
- "zimage",
- "krea2",
- }
-)
-# Archs that alone name the family. Not "flux" / "qwen_image": several DiTs ship under those (#14474).
-_FAMILY_NAMING_DIFFUSION_GGUF_ARCHS = frozenset({"krea2"})
-_UNSUPPORTED_DIFFUSION_GGUF_ARCHS = frozenset(
- {"sd1", "sd3", "sdxl", "aura", "hidream", "cosmos", "hyvid"}
-)
-_AMBIGUOUS_DIFFUSION_GGUF_ARCHS = frozenset({"lumina2"})
-_PLACEHOLDER_DIFFUSION_GGUF_ARCHS = frozenset({"pig", "cow"})
-_VIDEO_GGUF_ARCHS = frozenset({"ltxv", "wan"})
+_DIFFUSION_GGUF_ARCHS = _gguf_archs.DIFFUSION_IMAGE_GGUF_ARCHS
+_FAMILY_NAMING_DIFFUSION_GGUF_ARCHS = _gguf_archs.FAMILY_NAMING_DIFFUSION_GGUF_ARCHS
+_UNSUPPORTED_DIFFUSION_GGUF_ARCHS = _gguf_archs.UNSUPPORTED_DIFFUSION_GGUF_ARCHS
+_AMBIGUOUS_DIFFUSION_GGUF_ARCHS = _gguf_archs.AMBIGUOUS_DIFFUSION_GGUF_ARCHS
+_PLACEHOLDER_DIFFUSION_GGUF_ARCHS = _gguf_archs.PLACEHOLDER_DIFFUSION_GGUF_ARCHS
+_VIDEO_GGUF_ARCHS = _gguf_archs.VIDEO_GGUF_ARCHS
_VIDEO_GEN_TASK = "text-to-video"
# TTS-only GGUF archs llama.cpp cannot load, tagged speech so the chat picker keeps them out of
diff --git a/studio/backend/hub/utils/gguf.py b/studio/backend/hub/utils/gguf.py
index 89e9bafd582..28038635ce2 100644
--- a/studio/backend/hub/utils/gguf.py
+++ b/studio/backend/hub/utils/gguf.py
@@ -13,6 +13,7 @@ from typing import Iterable, Optional, Sequence
from hub.utils.hf_tokens import call_with_anonymous_retry
from loggers import get_logger
+from utils import gguf_names as _gguf_names
from utils.paths.path_utils import (
drop_shadowed_appledouble_names as _drop_shadowed_appledouble_names,
file_contents_available_locally,
@@ -74,67 +75,25 @@ GGUF_QUANT_PREFERENCE = [
]
_GGUF_SPLIT_SUFFIX_RE = re.compile(r"-\d{3,}-of-(\d{3,})", re.IGNORECASE)
-_GGUF_QUANT_RE = re.compile(
- r"(UD-)?"
- r"((?:MX|NV)FP[0-9]+(?:_[A-Z0-9]+)*"
- r"|IQ[0-9]+_[A-Z]+(?:_[A-Z0-9]+)?"
- r"|P?TQ[0-9]+_[0-9]+"
- r"|Q[0-9]+_K_[A-Z]+"
- r"|P?Q[0-9]+_(?:[0-9]+(?:_G[0-9]+)?|G[0-9]+)"
- r"|Q[0-9]+_K"
- r"|BF16|F16|F32)",
- re.IGNORECASE,
-)
+_GGUF_QUANT_RE = _gguf_names.GGUF_QUANT_RE
def is_mmproj_filename(filename: str) -> bool:
- return "mmproj" in filename.lower()
+ return _gguf_names.is_mmproj_filename(filename)
-# Anchored at an END of the stem, never a substring, for the reason is_mtp_drafter_path documents: a name that merely contains the word (Qwen3-Imatrix-Tuned-Q4_K_M.gguf) is a real model, while every published imatrix leads or closes with it.
-_IMATRIX_TOKEN_RE = re.compile(r"^imatrix(?:[._\-]|$)|[._\-]imatrix$", re.IGNORECASE)
-# llama.cpp reads an imatrix only to quantize, so a quant label before a trailing token marks imatrix-weighted
-# weights (Lewdiculous `<model>-Q4_K_M-imatrix.gguf`), not the calibration file. Float labels do not count, nor does
-# `.imatrix`: mradermacher names its calibration file `<model>.imatrix.gguf`, and model names carry `mxfp4` / `q4_0`.
-_IMATRIX_WEIGHTED_RE = re.compile(
- r"[._\-](?:I?Q[0-9]+_|P?TQ[0-9]+_|(?:MX|NV)FP[0-9])[^/]*[_\-]imatrix$", re.IGNORECASE
-)
+_IMATRIX_TOKEN_RE = _gguf_names.IMATRIX_TOKEN_RE
+_DRAFTER_KINDS = _gguf_names.DRAFTER_KINDS
+_DRAFTER_DIR_KINDS = _gguf_names.DRAFTER_DIR_KINDS
+_DSPARK_BEFORE_QUANT_RE = _gguf_names.DSPARK_BEFORE_QUANT_RE
def is_imatrix_filename(path: str) -> bool:
- """True for a calibration imatrix: ``imatrix.gguf``, ``imatrix_unsloth.gguf``, ``imatrix_unsloth.dat``, ``<model>-imatrix.gguf``, ``<model>.imatrix``; never ``<model>-Q4_K_M-imatrix.gguf``, which is imatrix-weighted weights. It holds activation statistics for llama-quantize, not a model, and llama-server never opens one, so it is neither a selectable variant nor a companion to fetch: unlike mmproj and the MTP drafter it is excluded outright, everywhere they are. Most repos spell it .dat or .gguf_file, which no GGUF listing sees; the ones that publish imatrix_unsloth.gguf (unsloth/Qwen3.8-27B-GGUF) put a valid GGUF container carrying no model in front of the variant menu, download and loader. CANONICAL COPY. Two mirrors must change in lockstep: utils/models/model_config.py ``_is_imatrix_path`` (utils cannot import hub) and core/inference/llama_cpp.py ``_is_companion_gguf_path`` (core avoids hub imports)."""
- name = path.replace("\\", "/").rsplit("/", 1)[-1]
- stem = name.rsplit(".", 1)[0] if "." in name else name
- if _IMATRIX_TOKEN_RE.search(stem) and not _IMATRIX_WEIGHTED_RE.search(stem):
- return True
- return name.lower().endswith(".imatrix")
-
-
-# dspark and dflash are the same DeepSeek V4 Flash drafter: the folder it ships in and the architecture it reports.
-_DRAFTER_KINDS = ("mtp", "dspark", "dflash", "eagle3", "lilicorr")
-
-# Directories only: mtp/ and dspark/ are always a publisher's companion folder, while dflash/ is a family name a user picks for real weights.
-_DRAFTER_DIR_KINDS = ("mtp", "dspark")
-
-# <model>-dspark-<quant>.gguf drafters (prism-ml Bonsai, third-party DSpark GGUFs); a name going on past the quant (DeepSeek-V4-Flash-Dspark-Abliterated-MXFP4-BF16.gguf) is the model.
-_DSPARK_BEFORE_QUANT_RE = re.compile(
- rf"-dspark-(?:{_GGUF_QUANT_RE.pattern})(?:-[0-9]{{5}}-of-[0-9]{{5}})?\.gguf$",
- re.IGNORECASE,
-)
+ return _gguf_names.is_imatrix_filename(path)
def is_mtp_drafter_path(path: str) -> bool:
- """True for a separate-file drafter, a companion to the main model rather than a selectable quant: the repo-root ``mtp-*.gguf`` (the Q8_0 copy unsloth ships for llama.cpp ``-hf`` auto-discovery), the ``MTP/`` subdir copies (Gemma 4), the ``dspark/`` drafters (DeepSeek V4 Flash), the ``<model>-dspark-<quant>.gguf`` drafters (prism-ml Bonsai) the ``eagle3-*.gguf`` draft heads (ggml-org gpt-oss) and the ``lilicorr-*.gguf`` drafters (NVIDIA Nemotron 3.5). Repos that bake the head into the main GGUF (Qwen) have no such file, so this is False for them. Must be excluded from main-model selection everywhere mmproj is. Matched by basename prefix, by an exact parent dir for ``_DRAFTER_DIR_KINDS``, or by ``_DSPARK_BEFORE_QUANT_RE``; never a bare substring, since the kind names double as family names, so ``Qwen3.6-27B-MTP-Q4_K_M.gguf`` and ``Qwen3.6-35B-A3B-DFlash-Q4_K_M.gguf`` ARE the model. CANONICAL COPY. Two mirrors must change in lockstep: utils/models/model_config.py ``_is_mtp_drafter`` (utils cannot import hub) and core/inference/llama_cpp.py ``_is_companion_gguf_path`` (core avoids hub imports; bundles the mmproj check)."""
- p = path.replace("\\", "/").lower()
- if not p.endswith(".gguf"):
- return False
- parts = [segment for segment in p.split("/") if segment]
- name, parents = parts[-1], parts[:-1]
- return (
- any(name.startswith(f"{kind}-") for kind in _DRAFTER_KINDS)
- or any(kind in parents for kind in _DRAFTER_DIR_KINDS)
- or _DSPARK_BEFORE_QUANT_RE.search(name) is not None
- )
+ return _gguf_names.is_mtp_drafter_path(path)
def is_reclaimable_drafter_path(path: str) -> bool:
diff --git a/studio/backend/hub/utils/inventory_scan.py b/studio/backend/hub/utils/inventory_scan.py
index 816a84067ab..99510699385 100644
--- a/studio/backend/hub/utils/inventory_scan.py
+++ b/studio/backend/hub/utils/inventory_scan.py
@@ -1706,6 +1706,20 @@ def is_variant_partial(
)
+def _sibling_snapshot_has_complete_gguf(snapshot_dir: Optional[Path]) -> bool:
+ if snapshot_dir is None or snapshot_dir.parent.name != "snapshots":
+ return False
+ try:
+ siblings = [
+ entry
+ for entry in snapshot_dir.parent.iterdir()
+ if entry.name != snapshot_dir.name and entry.is_dir()
+ ]
+ except OSError:
+ return False
+ return any(snapshot_has_complete_variants(str(entry)) for entry in siblings)
+
+
def is_gguf_repo_partial(
repo_id: str,
repo_cache_dir: Optional[Path] = None,
@@ -1775,9 +1789,11 @@ def is_gguf_repo_partial(
):
variants.add(variant)
if not variants:
- # Nothing named a quant: an interrupted attempt leaves only torn shards.
- return has_legacy_partial or _recovered_snapshot_cannot_serve(
- repo_cache_dir, snapshot_dir, quants = True
+ # No marker names a quant (an `hf download` stopped between shards), so the files decide;
+ # a sibling revision with a whole quant still serves the row, as the loader picks it.
+ return has_legacy_partial or (
+ _snapshot_cannot_serve_its_payload(snapshot_dir, quants = True)
+ and not _sibling_snapshot_has_complete_gguf(snapshot_dir)
)
has_clean = False
has_broken = has_legacy_partial
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index c34a2128b48..aa38294dc07 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -11229,6 +11229,7 @@ async def _reject_unservable_model(
from core.inference.local_model_resolver import (
index_is_built,
local_gguf_pinned_variant,
+ local_gguf_torn_only,
local_gguf_withheld,
recently_downloaded,
resolve_local_gguf,
@@ -11256,7 +11257,7 @@ async def _reject_unservable_model(
),
)
- still_indexing = False
+ still_indexing = torn = False
try:
if await asyncio.to_thread(_loaded_satisfies, requested_model):
return
@@ -11339,6 +11340,13 @@ async def _reject_unservable_model(
or recently_downloaded(base)
or (variant is not None and resolve_local_gguf(base, allow_scan = False) is not None)
)
+ # Torn split sets are kept out of the index, but the name is still ours, not a foreign label.
+ torn = (
+ not here
+ and base.strip().count("/") == 1
+ and await asyncio.to_thread(local_gguf_torn_only, base)
+ )
+ here = here or torn
switchable = downloaded and get_openai_auto_switch_enabled()
except HTTPException:
# A refusal decided above is the answer, not a failure to decide: without this
@@ -11351,7 +11359,7 @@ async def _reject_unservable_model(
logger.debug("unservable-model check failed for %r: %s", requested_model, exc)
if not quantified:
return
- downloaded = here = switchable = False
+ downloaded = here = switchable = torn = False
if still_indexing:
_raise_still_indexing(requested_model, fastapi_request)
if gguf_hub_repo and not (quantified or here):
@@ -11381,6 +11389,12 @@ async def _reject_unservable_model(
f"The model '{requested_model}' is downloaded, but this server could not "
"switch to it. Retry shortly, or load it in Unsloth Studio."
)
+ elif torn:
+ status_code, code = 404, "model_not_found"
+ message = (
+ f"The model '{requested_model}' is only partly downloaded on this server, so it "
+ "cannot be served. Finish the download in Unsloth Studio."
+ )
elif downloaded:
status_code, code = 404, "model_not_found"
message = (
diff --git a/studio/backend/tests/test_gguf_names_single_owner.py b/studio/backend/tests/test_gguf_names_single_owner.py
new file mode 100644
index 00000000000..936e17bc92f
--- /dev/null
+++ b/studio/backend/tests/test_gguf_names_single_owner.py
@@ -0,0 +1,226 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_BACKEND = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_BACKEND))
+
+from utils import gguf_archs, gguf_names # noqa: E402
+
+
+def test_every_layer_reads_the_same_rule_objects():
+ import hub.utils.gguf as hub_gguf
+ import utils.models.model_config as model_config
+ from core.inference import llama_cpp
+
+ assert hub_gguf._GGUF_QUANT_RE is gguf_names.GGUF_QUANT_RE
+ assert model_config._GGUF_KNOWN_QUANT_RE is gguf_names.GGUF_QUANT_RE
+ assert llama_cpp._GGUF_KNOWN_QUANT_RE is gguf_names.GGUF_QUANT_RE
+ for module in (hub_gguf, model_config, llama_cpp):
+ assert module._DRAFTER_KINDS is gguf_names.DRAFTER_KINDS
+ assert module._DRAFTER_DIR_KINDS is gguf_names.DRAFTER_DIR_KINDS
+ assert module._DSPARK_BEFORE_QUANT_RE is gguf_names.DSPARK_BEFORE_QUANT_RE
+ assert module._IMATRIX_TOKEN_RE is gguf_names.IMATRIX_TOKEN_RE
+
+
+def test_the_chat_refusal_and_the_listing_share_every_arch_set():
+ from core.inference.llama_cpp import LlamaCppBackend
+ import hub.services.models.catalog_classification as catalog
+
+ assert LlamaCppBackend._IMAGE_ARCHES is catalog._DIFFUSION_GGUF_ARCHS
+ assert LlamaCppBackend._AMBIGUOUS_IMAGE_ARCHES is catalog._AMBIGUOUS_DIFFUSION_GGUF_ARCHS
+ assert LlamaCppBackend._VIDEO_ARCHES is catalog._VIDEO_GGUF_ARCHS
+ assert LlamaCppBackend._UNRUNNABLE_MEDIA_ARCHES is catalog._UNSUPPORTED_DIFFUSION_GGUF_ARCHS
+ assert LlamaCppBackend._PLACEHOLDER_ARCHES is catalog._PLACEHOLDER_DIFFUSION_GGUF_ARCHS
+
+
[email protected]("arch", ["flux2", "z_image", "zimage", "qwenimage", "qwenimage21"])
+def test_image_archs_the_old_chat_gate_missed_are_refused_before_launch(arch):
+ from core.inference.llama_cpp import LlamaCppBackend
+ from hub.services.models.catalog_classification import _arch_to_task
+
+ assert arch in LlamaCppBackend._DIFFUSION_ARCHES
+ assert _arch_to_task(arch) in ("text-to-image", "image-diffusion-unsupported")
+
+
+ "path,companion",
+ [
+ ("mtp-Q8_0.gguf", True),
+ ("MTP/gemma-4-E2B-it-Q8_0-MTP.gguf", True),
+ ("dspark/dspark-DeepSeek-V4-Flash-Q8_0.gguf", True),
+ ("Bonsai-8B-dspark-Q8_0.gguf", True),
+ ("eagle3-gpt-oss-20b.gguf", True),
+ ("lilicorr-Nemotron-3.5-Q8_0.gguf", True),
+ ("dflash-Qwen3.6-27B-Q8_0.gguf", True),
+ ("Qwen3.6-35B-A3B-DFlash-Q4_K_M.gguf", False),
+ ("dflash/Qwen3.6-27B-Q4_K_M.gguf", False),
+ ("imatrix_unsloth.gguf", True),
+ ("Qwen3-Imatrix-Tuned-Q4_K_M.gguf", False),
+ ("gemma-4-E2B-it-Q4_K_M.gguf", False),
+ ],
+)
+def test_hub_loader_and_backend_agree_on_companions(path, companion):
+ import hub.utils.gguf as hub_gguf
+ import utils.models.model_config as model_config
+ from core.inference import llama_cpp
+
+ hub_says = hub_gguf.is_mtp_drafter_path(path) or hub_gguf.is_imatrix_filename(path)
+ loader_says = model_config._is_mtp_drafter(path) or model_config._is_imatrix_path(path)
+ assert hub_says == loader_says == llama_cpp._is_companion_gguf_path(path) == companion
+
+
+def test_cli_drafter_kinds_match_the_server():
+ """Runs in a subprocess: importing unsloth_cli here would shadow backend modules (``state``)."""
+ import json
+ import subprocess
+
+ repo = _BACKEND.parents[1]
+ out = subprocess.run(
+ [
+ sys.executable,
+ "-c",
+ "import json; from unsloth_cli.commands import start; "
+ "print(json.dumps([start._DRAFTER_KINDS, start._DRAFTER_DIR_KINDS]))",
+ ],
+ cwd = str(repo),
+ capture_output = True,
+ text = True,
+ timeout = 120,
+ )
+ assert out.returncode == 0, out.stderr[-2000:]
+ kinds, dir_kinds = json.loads(out.stdout.strip().splitlines()[-1])
+ assert tuple(kinds) == gguf_names.DRAFTER_KINDS
+ assert tuple(dir_kinds) == gguf_names.DRAFTER_DIR_KINDS
+
+
+def test_the_leaf_modules_import_nothing_from_the_layers_they_serve():
+ import ast
+ for module in (gguf_names, gguf_archs):
+ tree = ast.parse(Path(module.__file__).read_text(encoding = "utf-8"))
+ for node in ast.walk(tree):
+ if isinstance(node, ast.ImportFrom) and node.module:
+ assert node.module.split(".")[0] in ("__future__", "re", "typing")
+ elif isinstance(node, ast.Import):
+ assert all(alias.name in ("re",) for alias in node.names)
+
+
+def _hf_cache_repo(tmp_path, files):
+ repo = tmp_path / "models--org--m-GGUF"
+ snap = repo / "snapshots" / "abc123"
+ snap.mkdir(parents = True)
+ for name, size in files.items():
+ (snap / name).write_bytes(b"x" * size)
+ return repo
+
+
+def test_auto_switch_does_not_offer_a_torn_split_quant_from_the_hf_cache(tmp_path):
+ from types import SimpleNamespace
+
+ from core.inference import local_model_resolver as resolver
+
+ repo = _hf_cache_repo(tmp_path, {"m-Q4_K_M-00001-of-00003.gguf": 400})
+ entry = resolver._local_gguf_entry(
+ "org/m-GGUF", SimpleNamespace(path = str(repo), source = "hf_cache")
+ )
+ assert entry is None
+
+
+def test_a_complete_quant_beside_a_torn_one_is_still_offered(tmp_path):
+ from types import SimpleNamespace
+
+ from core.inference import local_model_resolver as resolver
+
+ repo = _hf_cache_repo(tmp_path, {"m-Q8_0.gguf": 300, "m-Q4_K_M-00001-of-00003.gguf": 400})
+ entry = resolver._local_gguf_entry(
+ "org/m-GGUF", SimpleNamespace(path = str(repo), source = "hf_cache")
+ )
+ assert entry is not None
+ assert [q.upper() for q in entry.variants] == ["Q8_0"]
+
+
+def test_the_inventory_row_calls_a_torn_split_partial_without_any_marker(tmp_path):
+ from hub.utils.inventory_scan import is_gguf_repo_partial
+
+ repo = _hf_cache_repo(tmp_path, {"m-Q4_K_M-00001-of-00003.gguf": 400})
+ snapshot = repo / "snapshots" / "abc123"
+ assert is_gguf_repo_partial("org/m-GGUF", repo, snapshot_dir = snapshot) is True
+
+
+def test_a_whole_quant_keeps_the_row_complete(tmp_path):
+ from hub.utils.inventory_scan import is_gguf_repo_partial
+
+ repo = _hf_cache_repo(tmp_path, {"m-Q8_0.gguf": 300, "m-Q4_K_M-00001-of-00003.gguf": 400})
+ snapshot = repo / "snapshots" / "abc123"
+ assert is_gguf_repo_partial("org/m-GGUF", repo, snapshot_dir = snapshot) is False
+
+
+def test_an_older_whole_revision_keeps_the_row_complete_beside_a_newer_torn_one(tmp_path):
+ import os
+
+ from hub.utils.inventory_scan import is_gguf_repo_partial
+
+ repo = tmp_path / "models--org--m-GGUF"
+ old = repo / "snapshots" / "old"
+ new = repo / "snapshots" / "new"
+ old.mkdir(parents = True)
+ new.mkdir(parents = True)
+ (old / "m-Q4_K_M.gguf").write_bytes(b"GGUF" + b"\0" * 60)
+ (new / "m-Q8_0-00001-of-00002.gguf").write_bytes(b"GGUF" + b"\0" * 60)
+ os.utime(old, (1, 1))
+ assert is_gguf_repo_partial("org/m-GGUF", repo) is False
+ (old / "m-Q4_K_M.gguf").unlink()
+ os.utime(old, (1, 1))
+ assert is_gguf_repo_partial("org/m-GGUF", repo) is True
+
+
+def test_a_request_for_a_torn_only_repo_is_refused_not_answered_by_the_resident(
+ tmp_path, monkeypatch
+):
+ import asyncio
+
+ from fastapi import HTTPException
+
+ import routes.inference as inference_route
+ from core.inference import local_model_resolver as resolver
+
+ repo = tmp_path / "models--publisher--My-Model"
+ snapshot = repo / "snapshots" / "rev"
+ snapshot.mkdir(parents = True)
+ (snapshot / "My-Model-Q4_K_M-00001-of-00002.gguf").write_bytes(b"GGUF" + b"\0" * 60)
+ monkeypatch.setattr("hub.utils.hf_cache_state.hf_cache_roots", lambda **_kw: [tmp_path])
+ assert resolver.local_gguf_torn_only("publisher/My-Model") is True
+ assert resolver.local_gguf_torn_only("publisher/Other") is False
+
+ loaded = type(
+ "L",
+ (),
+ {
+ "is_loaded": True,
+ "model_identifier": "unsloth/A-GGUF",
+ "hf_variant": "Q4_K_M",
+ "_openai_advertised_id": None,
+ },
+ )()
+ 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(resolver, "resolve_local_gguf", lambda name, **_kw: None)
+ monkeypatch.setattr(resolver, "index_is_built", lambda: True)
+ monkeypatch.setattr(resolver, "warm_index_soon", lambda: None)
+ monkeypatch.setattr(
+ "utils.openai_auto_switch_settings.get_openai_auto_switch_enabled", lambda: False
+ )
+ request = type("R", (), {"url": type("U", (), {"path": "/v1/chat/completions"})()})()
+ with pytest.raises(HTTPException) as excinfo:
+ asyncio.run(inference_route._reject_unservable_model("publisher/My-Model", request))
+ assert excinfo.value.status_code == 404
+ assert "partly downloaded" in str(excinfo.value.detail)
+ assert asyncio.run(inference_route._reject_unservable_model("publisher/Other", request)) is None
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index a5c191dd66f..64df20eb13f 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -2827,8 +2827,7 @@ def test_hf_cache_entry_excludes_torn_quant_from_selected_snapshot(tmp_path):
assert entry.variants == ("Q4_K_M",)
-def test_hf_cache_entry_keeps_partial_only_fallback(tmp_path):
- """A repo with no complete quant keeps the pre-existing fallback listing."""
+def test_hf_cache_entry_offers_no_quant_from_a_partial_only_repo(tmp_path):
repo = tmp_path / "models--org--Repo"
snapshot = repo / "snapshots" / "revision"
snapshot.mkdir(parents = True)
@@ -2839,8 +2838,7 @@ def test_hf_cache_entry_keeps_partial_only_fallback(tmp_path):
SimpleNamespace(id = "org/Repo", path = str(repo), source = "hf_cache"),
)
- assert entry is not None
- assert entry.variants == ("Q4_K_M",)
+ assert entry is None
def test_selected_snapshot_preserves_local_variant_labels(tmp_path):
diff --git a/studio/backend/utils/gguf_archs.py b/studio/backend/utils/gguf_archs.py
index d5e85b833b0..d6d6d388d43 100644
--- a/studio/backend/utils/gguf_archs.py
+++ b/studio/backend/utils/gguf_archs.py
@@ -42,6 +42,33 @@ def is_speech_gguf_architecture(architecture: Optional[str]) -> bool:
return any(marker in normalized for marker in _VOCODER_MARKERS)
+DIFFUSION_IMAGE_GGUF_ARCHS = frozenset(
+ {
+ "flux",
+ "flux2",
+ "qwen_image",
+ "qwenimage",
+ "qwen_image21",
+ "qwenimage21",
+ "z_image",
+ "zimage",
+ "krea2",
+ }
+)
+# Archs that alone name the family. Not "flux" / "qwen_image": several DiTs ship under those (#14474).
+FAMILY_NAMING_DIFFUSION_GGUF_ARCHS = frozenset({"krea2"})
+# Recognised, but no Studio page can run them.
+UNSUPPORTED_DIFFUSION_GGUF_ARCHS = frozenset(
+ {"sd1", "sd3", "sdxl", "aura", "hidream", "cosmos", "hyvid"}
+)
+# Shared by several families, so the header alone does not say whether Images can run the file
+# (Z-Image's DiT is a Lumina2 derivative and declares "lumina2").
+AMBIGUOUS_DIFFUSION_GGUF_ARCHS = frozenset({"lumina2"})
+# Not architectures: placeholders gguf-connector writes for its diffusion GGUFs.
+PLACEHOLDER_DIFFUSION_GGUF_ARCHS = frozenset({"pig", "cow"})
+VIDEO_GGUF_ARCHS = frozenset({"ltxv", "wan"})
+
+
# ``general.architecture`` of every GGUF audio.cpp writes. Only audiocpp_server reads these (speech,
# music, transcription); llama.cpp has no such architecture.
AUDIO_CPP_GGUF_ARCHITECTURE = "audiocpp"
diff --git a/studio/backend/utils/gguf_names.py b/studio/backend/utils/gguf_names.py
new file mode 100644
index 00000000000..bcf9038cd7d
--- /dev/null
+++ b/studio/backend/utils/gguf_names.py
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Standard-library-only GGUF filename rules shared by discovery and loading."""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+GGUF_QUANT_RE = re.compile(
+ r"(UD-)?"
+ r"((?:MX|NV)FP[0-9]+(?:_[A-Z0-9]+)*"
+ r"|IQ[0-9]+_[A-Z]+(?:_[A-Z0-9]+)?"
+ r"|P?TQ[0-9]+_[0-9]+"
+ r"|Q[0-9]+_K_[A-Z]+"
+ r"|P?Q[0-9]+_(?:[0-9]+(?:_G[0-9]+)?|G[0-9]+)"
+ r"|Q[0-9]+_K"
+ r"|BF16|F16|F32)",
+ re.IGNORECASE,
+)
+
+
+def is_mmproj_filename(filename: str) -> bool:
+ return "mmproj" in filename.lower()
+
+
+IMATRIX_TOKEN_RE = re.compile(r"^imatrix(?:[._\-]|$)|[._\-]imatrix$", re.IGNORECASE)
+# A quant label before the trailing token marks imatrix-weighted weights. Float labels and
+# `.imatrix` do not count: mradermacher names its calibration file `<model>.imatrix.gguf`.
+IMATRIX_WEIGHTED_RE = re.compile(
+ r"[._\-](?:I?Q[0-9]+_|P?TQ[0-9]+_|(?:MX|NV)FP[0-9])[^/]*[_\-]imatrix$", re.IGNORECASE
+)
+
+
+def is_imatrix_filename(path: str) -> bool:
+ """Exclude calibration files, but retain imatrix-weighted models."""
+ name = path.replace("\\", "/").rsplit("/", 1)[-1]
+ stem = name.rsplit(".", 1)[0] if "." in name else name
+ if IMATRIX_TOKEN_RE.search(stem) and not IMATRIX_WEIGHTED_RE.search(stem):
+ return True
+ return name.lower().endswith(".imatrix")
+
+
+DRAFTER_KINDS = ("mtp", "dspark", "dflash", "eagle3", "lilicorr")
+
+# mtp/ and dspark/ are always a companion folder; dflash/ is a family name users pick for weights.
+DRAFTER_DIR_KINDS = ("mtp", "dspark")
+
+# Names continuing beyond the quant may identify real models.
+DSPARK_BEFORE_QUANT_RE = re.compile(
+ rf"-dspark-(?:{GGUF_QUANT_RE.pattern})(?:-[0-9]{{5}}-of-[0-9]{{5}})?\.gguf$",
+ re.IGNORECASE,
+)
+
+
+def drafter_path_kind(path: str) -> Optional[str]:
+ """Match exact directories or basename prefixes, never family-name substrings."""
+ p = path.replace("\\", "/").lower()
+ if not p.endswith(".gguf"):
+ return None
+ parts = [segment for segment in p.split("/") if segment]
+ name, parents = parts[-1], parts[:-1]
+ for kind in DRAFTER_KINDS:
+ if name.startswith(f"{kind}-"):
+ return kind
+ for kind in DRAFTER_DIR_KINDS:
+ if kind in parents:
+ return kind
+ return None
+
+
+def is_mtp_drafter_path(path: str) -> bool:
+ if drafter_path_kind(path) is not None:
+ return True
+ p = path.replace("\\", "/").lower()
+ return p.endswith(".gguf") and DSPARK_BEFORE_QUANT_RE.search(p.rsplit("/", 1)[-1]) is not None
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index 9efe3c6e875..6e8a6ccce87 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -5,6 +5,7 @@
from dataclasses import dataclass, replace as _dataclass_replace
from typing import Optional, Dict, Any
+from utils import gguf_names as _gguf_names
from utils.paths.storage_roots import own_entry, within_account
from utils.paths import (
normalize_path,
@@ -1920,67 +1921,22 @@ def _detect_audio_from_tokenizer(
def _is_mmproj(filename: str) -> bool:
"""Check if a GGUF filename is a vision projection (mmproj) file."""
- return "mmproj" in filename.lower()
+ return _gguf_names.is_mmproj_filename(filename)
-# Mirrors hub.utils.gguf._IMATRIX_TOKEN_RE and _IMATRIX_WEIGHTED_RE (utils cannot import hub).
-_IMATRIX_TOKEN_RE = re.compile(r"^imatrix(?:[._\-]|$)|[._\-]imatrix$", re.IGNORECASE)
-_IMATRIX_WEIGHTED_RE = re.compile(
- r"[._\-](?:I?Q[0-9]+_|P?TQ[0-9]+_|(?:MX|NV)FP[0-9])[^/]*[_\-]imatrix$", re.IGNORECASE
-)
+_IMATRIX_TOKEN_RE = _gguf_names.IMATRIX_TOKEN_RE
def _is_imatrix_path(path: str) -> bool:
- """True for a calibration imatrix published beside the weights
- (``imatrix_unsloth.gguf``, ``imatrix.gguf``, ``<model>.imatrix``).
-
- Activation statistics for llama-quantize, not a model, so it is excluded
- everywhere mmproj is: a GGUF-suffixed one is a valid container that a
- size-ranked scan would otherwise hand to llama-server.
+ return _gguf_names.is_imatrix_filename(path)
- Mirrors hub.utils.gguf.is_imatrix_filename.
- """
- name = path.replace("\\", "/").rsplit("/", 1)[-1]
- stem = name.rsplit(".", 1)[0] if "." in name else name
- if _IMATRIX_TOKEN_RE.search(stem) and not _IMATRIX_WEIGHTED_RE.search(stem):
- return True
- return name.lower().endswith(".imatrix")
-
-# Mirrors hub.utils.gguf._DRAFTER_KINDS. dflash/ holds real weights, so it is a drafter by prefix only.
-_DRAFTER_KINDS = ("mtp", "dspark", "dflash", "eagle3", "lilicorr")
-_DRAFTER_DIR_KINDS = ("mtp", "dspark")
+_DRAFTER_KINDS = _gguf_names.DRAFTER_KINDS
+_DRAFTER_DIR_KINDS = _gguf_names.DRAFTER_DIR_KINDS
def _is_mtp_drafter(path: str) -> bool:
- """True for a separate-file drafter, a companion to the main model rather
- than a selectable quant: the repo-root ``mtp-*.gguf``, the ``MTP/`` subdir
- copies (Gemma 4), the ``dspark/`` drafters (DeepSeek V4 Flash), the
- ``<model>-dspark-<quant>.gguf`` drafters (prism-ml Bonsai), the
- ``eagle3-*.gguf`` draft heads (ggml-org gpt-oss) or the ``lilicorr-*.gguf``
- drafters (NVIDIA Nemotron 3.5).
-
- Mirrors hub.utils.gguf.is_mtp_drafter_path (utils cannot import hub). Must be
- excluded everywhere mmproj is, or the drafter leaks into variant menus (a
- phantom quant) and quant-matched file lookups -- a ``Q8_0`` request must not
- resolve to ``MTP/...-Q8_0-MTP.gguf``, which sorts ahead of the real weight,
- or to ``dspark/dspark-...-Q8_0.gguf``.
-
- Prefix, an exact directory for ``_DRAFTER_DIR_KINDS``, or
- ``_DSPARK_BEFORE_QUANT_RE``; never a bare substring, since the kind names
- double as family names (``Qwen3.6-35B-A3B-DFlash-Q4_K_M.gguf`` IS the model,
- as is anything in a user's ``dflash/`` folder).
- """
- p = path.replace("\\", "/").lower()
- if not p.endswith(".gguf"):
- return False
- parts = [segment for segment in p.split("/") if segment]
- name, parents = parts[-1], parts[:-1]
- return (
- any(name.startswith(f"{kind}-") for kind in _DRAFTER_KINDS)
- or any(kind in parents for kind in _DRAFTER_DIR_KINDS)
- or _DSPARK_BEFORE_QUANT_RE.search(name) is not None
- )
+ return _gguf_names.is_mtp_drafter_path(path)
# Family tokens for #5347's filename fallback. Lowercase; order irrelevant.
@@ -2928,22 +2884,8 @@ def _extract_quant_label(filename: str) -> str:
_BIG_ENDIAN_GGUF_FILENAME_RE = re.compile(r"(^|[-_])be(?:[._-]|$)", re.IGNORECASE)
-_GGUF_KNOWN_QUANT_RE = re.compile(
- r"(UD-)?"
- r"((?:MX|NV)FP[0-9]+(?:_[A-Z0-9]+)*"
- r"|IQ[0-9]+_[A-Z]+(?:_[A-Z0-9]+)?"
- r"|P?TQ[0-9]+_[0-9]+"
- r"|Q[0-9]+_K_[A-Z]+"
- r"|P?Q[0-9]+_(?:[0-9]+(?:_G[0-9]+)?|G[0-9]+)"
- r"|Q[0-9]+_K"
- r"|BF16|F16|F32)",
- re.IGNORECASE,
-)
-# Mirrors hub.utils.gguf._DSPARK_BEFORE_QUANT_RE, for _is_mtp_drafter.
-_DSPARK_BEFORE_QUANT_RE = re.compile(
- rf"-dspark-(?:{_GGUF_KNOWN_QUANT_RE.pattern})(?:-[0-9]{{5}}-of-[0-9]{{5}})?\.gguf$",
- re.IGNORECASE,
-)
+_GGUF_KNOWN_QUANT_RE = _gguf_names.GGUF_QUANT_RE
+_DSPARK_BEFORE_QUANT_RE = _gguf_names.DSPARK_BEFORE_QUANT_RE
_FLOAT_PRECISION_QUANTS = frozenset({"BF16", "F16", "F32"})
diff --git a/tests/studio/test_model_picker_contracts.py b/tests/studio/test_model_picker_contracts.py
index 0d734698fa1..aa5484ba677 100644
--- a/tests/studio/test_model_picker_contracts.py
+++ b/tests/studio/test_model_picker_contracts.py
@@ -2818,14 +2818,10 @@ def test_backfill_splits_a_quant_suffix_the_way_the_backend_does():
assert "_BPW_SUFFIX" in backend and "bpw" in identity
assert "extract_quant_label(filename).casefold()" in backend, "the label rule"
# The known-quant pattern itself, not tokens from it: #13899 widened MXFP to (?:MX|NV)FP in all
- # three places, which a literal "MXFP" check read as a drift. What has to hold is that the
- # frontend, the hub scanner and the llama.cpp backend spell one pattern, and that it still
- # recognises each quant family.
+ # three places, which a literal "MXFP" check read as a drift. The frontend must spell the
+ # backend's pattern (utils/gguf_names.py) and still recognise each quant family.
patterns = {
- "llama_cpp.py": _python_regex_source(
- _read_backend("core/inference/llama_cpp.py"), "_GGUF_KNOWN_QUANT_RE"
- ),
- "gguf.py": _python_regex_source(_read_backend("hub/utils/gguf.py"), "_GGUF_QUANT_RE"),
+ "gguf.py": _python_regex_source(_read_backend("utils/gguf_names.py"), "GGUF_QUANT_RE"),
"model-identity.ts": re.search(r'const QUANT_TOKEN_SOURCE =\s*"([^"]+)";', identity).group(
1
),
diff --git a/unsloth_cli/commands/start.py b/unsloth_cli/commands/start.py
index 99845852857..534b4600fc2 100644
--- a/unsloth_cli/commands/start.py
+++ b/unsloth_cli/commands/start.py
@@ -2595,8 +2595,8 @@ def _hub_gguf_files(repo: str) -> Optional[list]:
return [n for n in ggufs if not _is_auxiliary_gguf(n)]
-# Mirrors hub.utils.gguf._DRAFTER_KINDS / _DRAFTER_DIR_KINDS: dspark and dflash are the same DeepSeek V4 Flash drafter, but dflash/ is also a real family name, so only mtp/ and dspark/ count as a companion folder.
-_DRAFTER_KINDS = ("mtp", "dspark", "dflash", "eagle3")
+# Keep in sync with utils/gguf_names.py; the remote CLI cannot require backend imports.
+_DRAFTER_KINDS = ("mtp", "dspark", "dflash", "eagle3", "lilicorr")
_DRAFTER_DIR_KINDS = ("mtp", "dspark")