Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Fix Studio preferring MTP sidecars over embedded heads (#10181)

Wasim Yousef Said368e1cb9f868
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 52a41270c53..6a2a1189f8b 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -13459,6 +13459,8 @@ class LlamaCppBackend:
arch_keys: dict[str, str] = {} # gguf_key -> attribute name
arch = None
pooling_by_arch: dict[str, int] = {}
+
+ nextn_by_arch: dict[str, int] = {}
sliding_window_pattern_period: Optional[int] = None
general: dict[str, str] = {}
@@ -13506,7 +13508,12 @@ class LlamaCppBackend:
break
try:
- if key in WANTED or key in arch_keys or key.endswith(".pooling_type"):
+ if (
+ key in WANTED
+ or key in arch_keys
+ or key.endswith(".pooling_type")
+ or key.endswith(".nextn_predict_layers")
+ ):
if vtype == 8: # STRING
slen = struct.unpack("<Q", f.read(8))[0]
val_s = f.read(slen).decode("utf-8")
@@ -13554,6 +13561,9 @@ class LlamaCppBackend:
canvas_seen = True
if key.endswith(".pooling_type"):
pooling_by_arch[key] = val_i
+
+ if key.endswith(".nextn_predict_layers"):
+ nextn_by_arch[key] = val_i
attr = arch_keys.get(key)
if attr:
if attr == "sliding_window_pattern":
@@ -13596,10 +13606,13 @@ class LlamaCppBackend:
else:
kv_complete = True
- # GGUF metadata has no key-order contract. Pooling can precede
- # general.architecture, so bind the buffered value after the sweep.
+ # Bind buffered metadata after discovering the architecture namespace.
if arch is not None:
self._pooling_type = pooling_by_arch.get(f"{arch}.pooling_type", self._pooling_type)
+ self._nextn_predict_layers = nextn_by_arch.get(
+ f"{arch}.nextn_predict_layers",
+ self._nextn_predict_layers,
+ )
# Decide diffusion routing before the SWA resolver below: it can raise on an arch transformers
# does not know, which would otherwise drop a DiffusionGemma model to plain llama-server.
@@ -14641,6 +14654,12 @@ class LlamaCppBackend:
if cancel_event.is_set():
return None
+ if near_path:
+ from utils.models.gguf_metadata import read_gguf_nextn_predict_layers
+ if (read_gguf_nextn_predict_layers(near_path) or 0) > 0:
+ logger.info("Main GGUF contains an embedded MTP head; skipping separate drafter.")
+ return None
+
pick = _pick_mtp if allow_nested else _pick_mtp_root_only
if near_path:
@@ -18610,6 +18629,15 @@ class LlamaCppBackend:
# Read GGUF metadata (context_length, chat_template); header-only.
self._read_gguf_metadata(model_path)
+ if (
+ self._nextn_predict_layers
+ and mtp_draft_path
+ and _spec_canon not in ("dspark", "dflash")
+ ):
+ # A root mtp-*.gguf may mirror the embedded head; -md would replace it.
+ logger.info("Main GGUF contains an embedded MTP head; ignoring separate drafter.")
+ mtp_draft_path = None
+
if _load_cancelled():
logger.info("Load cancelled after download phase")
return False
@@ -24828,6 +24856,15 @@ class LlamaCppBackend:
# Canonical UI-facing requested mode (legacy values mapped via
# _canonicalize_spec_mode).
canonical_mode = _canonicalize_spec_mode(speculative_type)
+ user_owns_spec_type = _extra_args_set_spec_type(extra_args)
+ if (
+ not user_owns_spec_type
+ and canonical_mode in ("auto", "mtp", "mtp+ngram")
+ and self._nextn_predict_layers
+ and mtp_draft_path
+ ):
+ # Backstop for callers that bypass load_model's discovery normalization.
+ mtp_draft_path = None
# MTP signals: head baked into the main GGUF (Qwen, via metadata or
# name), or a separate drafter resolved from the repo (Gemma).
is_mtp_model = (
@@ -24835,7 +24872,6 @@ class LlamaCppBackend:
or _is_mtp_model_name(model_identifier, model_path)
or bool(mtp_draft_path)
)
- user_owns_spec_type = _extra_args_set_spec_type(extra_args)
_mtp_size_b = _extract_model_size_b(model_identifier)
# The sub-3B regression is an embedded-head cost; a separate drafter
# (Gemma) is a cheap standalone model that wins below 3B, so exempt it.
diff --git a/studio/backend/hub/utils/gguf_plan.py b/studio/backend/hub/utils/gguf_plan.py
index 154f2b29268..1fb8742c156 100644
--- a/studio/backend/hub/utils/gguf_plan.py
+++ b/studio/backend/hub/utils/gguf_plan.py
@@ -9,11 +9,11 @@ from typing import Optional, Sequence
from hub.utils.download_manifest import ExpectedFile
from hub.utils.gguf import (
bare_quant_alias,
+ drop_shadowed_appledouble_siblings,
extract_quant_label,
gguf_variant_family,
gguf_variant_key,
is_big_endian_gguf_path,
- drop_shadowed_appledouble_siblings,
is_gguf_filename,
is_imatrix_filename,
is_mmproj_filename,
@@ -233,9 +233,7 @@ def build_gguf_variant_plans(siblings: Sequence) -> dict[str, GgufVariantPlan]:
companion_expected = expected_file_from_sibling(companion) if companion is not None else None
mtp_sibling = preferred_mtp_sibling(siblings)
mtp_expected = expected_file_from_sibling(mtp_sibling) if mtp_sibling is not None else None
- companions_expected = tuple(
- file for file in (companion_expected, mtp_expected) if file is not None
- )
+ common_companions_expected = (companion_expected,) if companion_expected is not None else ()
for sibling in siblings:
name = _gguf_rfilename(sibling)
@@ -282,7 +280,12 @@ def build_gguf_variant_plans(siblings: Sequence) -> dict[str, GgufVariantPlan]:
[n for n in all_weight_names if n != target_weight_name],
max_bytes = sum(max(0, int(file.size or 0)) for file in kept_main),
)
- expected_files = (*main_expected, *companions_expected, *dflash_expected)
+ expected_files = (
+ *main_expected,
+ *common_companions_expected,
+ *((mtp_expected,) if mtp_expected is not None else ()),
+ *dflash_expected,
+ )
plans[quant] = plan_from_expected_files(
quant,
expected_files,
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index 2df6b7a2037..80119198500 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -3817,7 +3817,12 @@ def _resolve_mtp_drafter(
and it rejects an incomplete split set. Never raises: a drafter we cannot
find just costs a segment.
"""
+
try:
+ from utils.models.gguf_metadata import read_gguf_nextn_predict_layers
+
+ if (read_gguf_nextn_predict_layers(main_gguf_path) or 0) > 0:
+ return None, 0
from core.inference.llama_cpp import (
LlamaCppBackend,
_companion_snapshot_sibling,
diff --git a/studio/backend/tests/test_gguf_metadata.py b/studio/backend/tests/test_gguf_metadata.py
index 3cd7a505c5f..38c8e009eda 100644
--- a/studio/backend/tests/test_gguf_metadata.py
+++ b/studio/backend/tests/test_gguf_metadata.py
@@ -11,6 +11,9 @@ from pathlib import Path
from typing import Iterable, Mapping
from unittest.mock import patch
+
+import pytest
+
from utils.models.gguf_metadata import (
is_gguf_embedding_architecture,
is_gguf_embedding_model,
@@ -20,6 +23,7 @@ from utils.models.gguf_metadata import (
read_gguf_architecture,
read_gguf_context_length,
read_gguf_general_metadata,
+ read_gguf_nextn_predict_layers,
read_gguf_staged_dims,
read_mmproj_audio_capability,
)
@@ -168,6 +172,52 @@ def test_context_length_ignores_foreign_arch_key(tmp_path: Path):
assert read_gguf_context_length(str(p)) is None
+def test_nextn_predict_layers_uses_the_active_architecture_namespace(tmp_path: Path, monkeypatch):
+ embedded = _write_synthetic_gguf(
+ tmp_path / "embedded.gguf",
+ {"general.architecture": "qwen35"},
+ extra_uint32 = {
+ "qwen35.nextn_predict_layers": 1,
+ "qwen3.nextn_predict_layers": 9,
+ },
+ )
+ headless = _write_synthetic_gguf(
+ tmp_path / "headless.gguf",
+ {"general.architecture": "qwen35"},
+ extra_uint64 = {"qwen35.nextn_predict_layers": 0},
+ )
+ absent = _write_synthetic_gguf(
+ tmp_path / "absent.gguf",
+ {"general.architecture": "qwen35"},
+ extra_uint32 = {"qwen3.nextn_predict_layers": 7},
+ )
+ malformed = tmp_path / "malformed.gguf"
+ malformed.write_bytes(b"not a GGUF")
+
+ reversed_order = tmp_path / "reversed.gguf"
+ reversed_body = _enc_kv_uint32("qwen35.nextn_predict_layers", 2) + _enc_kv_string(
+ "general.architecture", "qwen35"
+ )
+ reversed_order.write_bytes(struct.pack("<IIQQ", _GGUF_MAGIC, 3, 0, 2) + reversed_body)
+
+ assert read_gguf_nextn_predict_layers(str(embedded)) == 1
+ assert read_gguf_nextn_predict_layers(str(headless)) == 0
+ assert read_gguf_nextn_predict_layers(str(absent)) is None
+ assert read_gguf_nextn_predict_layers(str(malformed)) is None
+
+ assert read_gguf_nextn_predict_layers(str(reversed_order)) == 2
+
+ # Verify the file-identity cache.
+ import utils.models.gguf_metadata as metadata
+
+ monkeypatch.setattr(
+ metadata,
+ "_parse_gguf_arch_uints",
+ lambda *_args, **_kwargs: pytest.fail("cached NextN metadata was reparsed"),
+ )
+ assert read_gguf_nextn_predict_layers(str(embedded)) == 1
+
+
# --- read_gguf_staged_dims (one pass: context + layer + moe counts) ----
diff --git a/studio/backend/tests/test_kv_cache_estimate_route.py b/studio/backend/tests/test_kv_cache_estimate_route.py
index 5d9e3e274f0..c4220d81e66 100644
--- a/studio/backend/tests/test_kv_cache_estimate_route.py
+++ b/studio/backend/tests/test_kv_cache_estimate_route.py
@@ -343,12 +343,23 @@ class TestDrafterDiscoveryMatchesTheLoader:
got, _ = models_routes._resolve_mtp_drafter(str(main))
assert got == str(nested)
- def test_a_root_mirror_is_taken_by_every_architecture(self, tmp_path):
- """Only the nested fallback is gated. A root mtp- companion beside the
- weights says it is the one to use, which is how Gemma 4 ships."""
+ def test_an_embedded_head_ignores_a_root_compatibility_mirror(self, tmp_path):
snap = self._snapshot(tmp_path)
- main = _write_gguf(snap / "model-Q4_K_M.gguf", {**_MLA_NO_HEAD, "nextn_predict_layers": 1})
- companion = _write_gguf(snap / "mtp-model.gguf", _MLA_NO_HEAD)
+ main = _write_gguf(
+ snap / "RVN-Q6_K-mtp.gguf",
+ {**_MLA_NO_HEAD, "nextn_predict_layers": 1},
+ arch = "qwen35",
+ )
+ _write_gguf(snap / "mtp-RVN.gguf", _MLA_NO_HEAD)
+
+ got, size = models_routes._resolve_mtp_drafter(str(main))
+ assert got is None
+ assert size == 0
+
+ def test_a_headless_model_still_takes_a_root_drafter(self, tmp_path):
+ snap = self._snapshot(tmp_path)
+ main = _write_gguf(snap / "gemma-4-Q4_K_M.gguf", _MLA_NO_HEAD, arch = "gemma3")
+ companion = _write_gguf(snap / "mtp-gemma-4.gguf", _MLA_NO_HEAD)
got, _ = models_routes._resolve_mtp_drafter(str(main))
assert got == str(companion)
diff --git a/studio/backend/tests/test_llama_cpp_mtp_detection.py b/studio/backend/tests/test_llama_cpp_mtp_detection.py
index cd716b672a0..20892d7dfaf 100644
--- a/studio/backend/tests/test_llama_cpp_mtp_detection.py
+++ b/studio/backend/tests/test_llama_cpp_mtp_detection.py
@@ -112,14 +112,16 @@ def _write_minimal_gguf(
arch: str,
nextn: int | None,
extra_uint32: dict[str, int] | None = None,
+ nextn_first: bool = False,
) -> Path:
"""Header-only GGUF with arch + optional nextn_predict_layers."""
extra_uint32 = dict(extra_uint32 or {})
- body = _enc_kv_string("general.architecture", arch)
- kv_count = 1
- if nextn is not None:
- body += _enc_kv_uint32(f"{arch}.nextn_predict_layers", nextn)
- kv_count += 1
+ arch_entry = _enc_kv_string("general.architecture", arch)
+ nextn_entry = (
+ _enc_kv_uint32(f"{arch}.nextn_predict_layers", nextn) if nextn is not None else b""
+ )
+ body = nextn_entry + arch_entry if nextn_first else arch_entry + nextn_entry
+ kv_count = 1 + int(nextn is not None)
for k, v in extra_uint32.items():
body += _enc_kv_uint32(k, v)
kv_count += 1
@@ -728,6 +730,19 @@ def test_read_gguf_metadata_captures_nextn_predict_layers(tmp_path, arch, nextn)
assert backend._nextn_predict_layers == nextn
+def test_read_gguf_metadata_captures_nextn_before_architecture(tmp_path):
+ gguf = _write_minimal_gguf(
+ tmp_path / "reversed.gguf",
+ arch = "qwen35",
+ nextn = 1,
+ nextn_first = True,
+ )
+ backend = LlamaCppBackend()
+ backend._read_gguf_metadata(str(gguf))
+ assert backend._architecture == "qwen35"
+ assert backend._nextn_predict_layers == 1
+
+
def test_read_gguf_metadata_leaves_nextn_unset_for_non_mtp_arch(tmp_path):
gguf = _write_minimal_gguf(
tmp_path / "model.gguf",
@@ -1955,6 +1970,40 @@ def test_auto_keeps_embedded_mtp(monkeypatch):
assert backend.spec_fallback_reason is None
+ ("mode", "expected_spec_type"),
+ [
+ ("auto", "draft-mtp"),
+ ("mtp", "draft-mtp"),
+ ("mtp+ngram", "ngram-mod,draft-mtp"),
+ ],
+)
+def test_embedded_mtp_ignores_discovered_root_sidecar(
+ monkeypatch, tmp_path, mode, expected_spec_type
+):
+ backend = _resolver_backend(monkeypatch)
+ backend._nextn_predict_layers = 1
+ sidecar = tmp_path / "mtp-RVN.gguf"
+ sidecar.write_bytes(b"draft")
+
+ flags = backend._build_speculative_flags(
+ speculative_type = mode,
+ spec_draft_n_max = None,
+ extra_args = None,
+ model_identifier = "0bserverx/Qwen3.8-27B-GGUF",
+ model_path = str(tmp_path / "RVN-Q6_K-mtp.gguf"),
+ gpus = True,
+ binary = "/fake/llama-server",
+ mtp_draft_path = str(sidecar),
+ dspark_draft_path = None,
+ )
+
+ parsed = _flags_dict(flags)
+ assert parsed["--spec-type"] == expected_spec_type
+ assert "--model-draft" not in parsed
+ assert backend.spec_fallback_reason is None
+
+
def test_auto_does_not_promote_dspark_on_a_binary_that_cannot_run_it(monkeypatch, tmp_path):
"""_download_dspark still reports a cached sidecar an incapable binary cannot
launch. Promoting there would turn Auto's fallback into no speculation at all,
@@ -2200,10 +2249,8 @@ def test_auto_non_mla_embedded_mtp_keeps_draft_mtp(monkeypatch):
assert backend.spec_fallback_reason is None
-def test_auto_mla_separate_drafter_keeps_mtp(monkeypatch):
- # Auto + MLA + a separate drafter (mtp_draft_path) -> the drafter exemption
- # wins over the MLA gate: still draft-mtp (Gemma-style external drafter is
- # not the slow embedded MLA/DSA path).
+def test_auto_mla_embedded_head_ignores_separate_drafter(monkeypatch):
+ # Embedded NextN metadata wins: -md would replace the head and bypass MLA's gate.
backend = _mla_resolver_backend(monkeypatch)
flags = backend._build_speculative_flags(
speculative_type = "auto",
@@ -2216,9 +2263,10 @@ def test_auto_mla_separate_drafter_keeps_mtp(monkeypatch):
mtp_draft_path = "/fake/mtp-draft.gguf",
)
parsed = _flags_dict(flags)
- assert parsed.get("--spec-type") == "draft-mtp"
- assert backend.speculative_type == "draft-mtp"
- assert backend.spec_fallback_reason is None
+ assert parsed.get("--spec-type") == "ngram-mod"
+ assert "--model-draft" not in parsed
+ assert backend.speculative_type == "ngram-mod"
+ assert backend.spec_fallback_reason == "mla_mtp_disabled"
def test_auto_non_mtp_mla_model_unaffected(monkeypatch):
diff --git a/studio/backend/tests/test_mtp_drafter_companion.py b/studio/backend/tests/test_mtp_drafter_companion.py
index faf46bad703..7f0172f5492 100644
--- a/studio/backend/tests/test_mtp_drafter_companion.py
+++ b/studio/backend/tests/test_mtp_drafter_companion.py
@@ -161,6 +161,21 @@ def test_baked_in_repo_plans_unchanged():
assert plans["q4_k_m"].target_filenames == ("Qwen3.6-27B-MTP-Q4_K_M.gguf",)
+def test_variant_plan_keeps_root_mtp_sidecar_until_metadata_is_available():
+ siblings = [
+ _sib("RVN-Q6_K-mtp.gguf", 4_000, "main"),
+ _sib("mtp-RVN.gguf", 100, "drafter"),
+ _sib("mmproj-F16.gguf", 500, "mmproj"),
+ ]
+
+ plan = build_gguf_variant_plans(siblings)["q6_k"]
+
+ assert plan.target_filenames == ("RVN-Q6_K-mtp.gguf", "mmproj-F16.gguf", "mtp-RVN.gguf")
+ assert plan.companion_hashes == frozenset({"drafter", "mmproj"})
+ assert plan.required_hashes == frozenset({"drafter", "main", "mmproj"})
+ assert plan.download_size_bytes == 4_600
+
+
def test_old_manifest_resume_reclassifies_drafter():
# Pre-fix manifests could leak the drafter into a quant's expected
# files; resume must classify it as a companion, not a main shard.
@@ -188,6 +203,18 @@ def test_detect_mtp_file_finds_root_sibling(tmp_path):
assert found.endswith("mtp-model.gguf")
+def test_detect_mtp_file_ignores_sidecar_for_embedded_head(tmp_path, monkeypatch):
+ weight = tmp_path / "RVN-Q6_K-mtp.gguf"
+ weight.write_bytes(b"main")
+ (tmp_path / "mtp-RVN.gguf").write_bytes(b"draft")
+ monkeypatch.setattr(
+ "utils.models.model_config.read_gguf_nextn_predict_layers",
+ lambda path: 1 if path == str(weight) else None,
+ )
+
+ assert detect_mtp_file(str(weight)) is None
+
+
def test_detect_mtp_file_none_without_sibling(tmp_path):
(tmp_path / "model-Q4_K_M.gguf").write_bytes(b"x")
assert detect_mtp_file(str(tmp_path / "model-Q4_K_M.gguf")) is None
@@ -823,6 +850,29 @@ def test_download_mtp_prefers_main_snapshot_offline(tmp_path, monkeypatch):
assert got == str(old_drafter)
+def test_download_mtp_skips_discovery_for_embedded_head(tmp_path, monkeypatch):
+ from core.inference.llama_cpp import LlamaCppBackend
+
+ main = tmp_path / "RVN-Q6_K-mtp.gguf"
+ main.write_bytes(b"main")
+ reached = False
+
+ def _unexpected_download(**_kwargs):
+ nonlocal reached
+ reached = True
+ return str(tmp_path / "mtp-RVN.gguf")
+
+ monkeypatch.setattr(
+ "utils.models.gguf_metadata.read_gguf_nextn_predict_layers",
+ lambda path: 1 if path == str(main) else None,
+ )
+ backend = LlamaCppBackend()
+ backend._download_companion_gguf = _unexpected_download
+
+ assert backend._download_mtp(hf_repo = "org/repo", near_path = str(main)) is None
+ assert reached is False
+
+
def test_download_mtp_online_skips_cache_reuse(tmp_path, monkeypatch):
# Online, do not reuse a cached copy: go to the download path so a changed
# drafter is refetched (hf_hub_download checks the current revision).
diff --git a/studio/backend/utils/models/gguf_metadata.py b/studio/backend/utils/models/gguf_metadata.py
index afab031e12d..bc66e21870b 100644
--- a/studio/backend/utils/models/gguf_metadata.py
+++ b/studio/backend/utils/models/gguf_metadata.py
@@ -63,6 +63,10 @@ _CLASSIFIER_HEAD_CACHE: Dict[_CacheKey, Optional[bool]] = {}
_DIMS_CACHE: Dict[_CacheKey, Optional[Dict[str, Optional[int]]]] = {}
+# Cache the embedded speculative-head count separately for discovery, launch, and sizing.
+_NEXTN_CACHE: Dict[_CacheKey, Optional[int]] = {}
+
+
def _cache_key(path: str) -> Optional[_CacheKey]:
try:
st = os.stat(path)
@@ -181,13 +185,15 @@ def read_gguf_context_length(path: str) -> Optional[int]:
def _parse_gguf_arch_uints(path: str, wanted_suffixes: frozenset[str]) -> Optional[Dict[str, int]]:
- """Walk a GGUF header once and return the requested architecture-namespaced
- uint (vtype 4/10) keys, e.g. ``{"block_count": 32}``. Keys are
- ``{arch}.<suffix>``; the arch is learned from ``general.architecture`` (GGUF
- writes general.* before arch.* keys, matching the loader's own parser).
- Returns ``None`` if not a GGUF / unreadable, else a dict (possibly empty or
- partial when some keys are absent)."""
+ """Walk a GGUF header once and return requested architecture-namespaced
+ uint (vtype 4/10) keys, e.g. ``{"block_count": 32}``.
+
+ GGUF does not guarantee KV order, so matching uints are buffered until
+ ``general.architecture`` identifies the active namespace. Returns ``None``
+ if the file is unreadable/not GGUF, otherwise a possibly partial dict.
+ """
arch: Optional[str] = None
+ buffered: Dict[str, int] = {}
found: Dict[str, int] = {}
try:
with open(path, "rb") as f:
@@ -226,24 +232,36 @@ def _parse_gguf_arch_uints(path: str, wanted_suffixes: frozenset[str]) -> Option
if len(sbytes) < slen:
break
arch = sbytes.decode("utf-8", "replace")
- elif (
- arch is not None
- and vtype in (4, 10)
- and key.startswith(f"{arch}.")
- and key[len(arch) + 1 :] in wanted_suffixes
- ):
+ for suffix in wanted_suffixes:
+ full_key = f"{arch}.{suffix}"
+ if full_key in buffered:
+ found[suffix] = buffered[full_key]
+ elif vtype in (4, 10):
+ suffix = next(
+ (
+ candidate
+ for candidate in wanted_suffixes
+ if key.endswith(f".{candidate}")
+ ),
+ None,
+ )
+ if suffix is None:
+ if not _skip_gguf_value(f, vtype):
+ break
+ continue
width = 4 if vtype == 4 else 8
n_bytes = f.read(width)
if len(n_bytes) < width:
break
- found[key[len(arch) + 1 :]] = struct.unpack(
- "<I" if vtype == 4 else "<Q", n_bytes
- )[0]
- if len(found) == len(wanted_suffixes):
- break
+ value = struct.unpack("<I" if vtype == 4 else "<Q", n_bytes)[0]
+ buffered[key] = value
+ if arch is not None and key == f"{arch}.{suffix}":
+ found[suffix] = value
else:
if not _skip_gguf_value(f, vtype):
break
+ if arch is not None and len(found) == len(wanted_suffixes):
+ break
except (struct.error, UnicodeDecodeError):
break
except OSError as e:
@@ -255,6 +273,31 @@ def _parse_gguf_arch_uints(path: str, wanted_suffixes: frozenset[str]) -> Option
return found
+def read_gguf_nextn_predict_layers(path: str) -> Optional[int]:
+ """Return the selected architecture's embedded NextN/MTP layer count.
+
+ ``0`` is a real headless verdict. ``None`` means the key is absent or the
+ header is unreadable, so callers that suppress a separate drafter can do so
+ only on a positive value.
+ """
+ key = _cache_key(path)
+ if key is None:
+ return None
+ with _CACHE_LOCK:
+ if key in _NEXTN_CACHE:
+ return _NEXTN_CACHE[key]
+ values = _parse_gguf_arch_uints(path, frozenset({"nextn_predict_layers"}))
+ result = values.get("nextn_predict_layers") if values is not None else None
+ with _CACHE_LOCK:
+ while len(_NEXTN_CACHE) >= _CACHE_MAX_ENTRIES:
+ try:
+ _NEXTN_CACHE.pop(next(iter(_NEXTN_CACHE)))
+ except StopIteration:
+ break
+ _NEXTN_CACHE[key] = result
+ return result
+
+
def _parse_gguf_staged_dims(path: str) -> Optional[Dict[str, Optional[int]]]:
vals = _parse_gguf_arch_uints(
path,
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index a1ecbe69059..f4acafe3fb8 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -38,6 +38,7 @@ from utils.models.gguf_metadata import (
mmproj_accepts_image,
pairing_score,
read_gguf_general_metadata,
+ read_gguf_nextn_predict_layers,
)
import structlog
from loggers import get_logger
@@ -1924,6 +1925,10 @@ def detect_mtp_file(
rejection as no drafter at all.
"""
+ if Path(path).is_file() and (read_gguf_nextn_predict_layers(path) or 0) > 0:
+ # A root mtp-*.gguf may mirror an embedded head; -md would replace it.
+ return None
+
def _matches_weight(candidate: Path) -> bool:
return _drafter_matches_weight(candidate.name, weight_name, kind = "mtp")