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): use the target's embedded MTP head when the MLX checkpoint keeps it under the language model (#14974)

Long Yixingc5482a5b5714
diff --git a/studio/backend/core/inference/mlx_speculative.py b/studio/backend/core/inference/mlx_speculative.py
index b8318eb4e52..a6d50992b9f 100644
--- a/studio/backend/core/inference/mlx_speculative.py
+++ b/studio/backend/core/inference/mlx_speculative.py
@@ -248,8 +248,13 @@ def has_builtin_head(model_dir: Optional[str]) -> bool:
if not model_dir:
return False
try:
- from mlx_vlm.speculative.drafters.mtp_split import detect_mtp_splitter
- return detect_mtp_splitter(Path(model_dir)) is not None
+ try:
+ # Also finds heads MLX conversions keep under the language model (``language_model.mtp.*``).
+ from unsloth_zoo.mlx.speculative import has_native_mtp_head
+ except ImportError:
+ from mlx_vlm.speculative.drafters.mtp_split import detect_mtp_splitter
+ return detect_mtp_splitter(Path(model_dir)) is not None
+ return has_native_mtp_head(model_dir)
except Exception as exc:
logger.debug("MLX speculative: no MTP splitter check for %s: %s", model_dir, exc)
return False
diff --git a/studio/backend/tests/test_memory_estimate.py b/studio/backend/tests/test_memory_estimate.py
index 6b315503047..34cea441659 100644
--- a/studio/backend/tests/test_memory_estimate.py
+++ b/studio/backend/tests/test_memory_estimate.py
@@ -4967,8 +4967,10 @@ def test_a_real_checkpoint_is_fitted_to_the_byte(budget_gib, fitted):
@_NEEDS_MLX
-def test_a_companion_drafter_adds_its_stored_weights_and_a_cache_to_the_load():
+def test_a_companion_drafter_adds_its_stored_weights_and_a_cache_to_the_load(monkeypatch):
_on_bfloat16_chip()
+ # unsloth-zoo otherwise loads a bf16 DFlash drafter at 4 bits, and sizes it so.
+ monkeypatch.setenv("UNSLOTH_MLX_DRAFTER_BITS", "0")
target = _local_snapshot("mlx-community/Qwen3.5-4B-4bit")
drafter = _local_snapshot("z-lab/Qwen3.5-4B-DFlash")
stored = 0
diff --git a/studio/backend/tests/test_mlx_speculative.py b/studio/backend/tests/test_mlx_speculative.py
index 3087ac9f8ea..31d0e1eb54d 100644
--- a/studio/backend/tests/test_mlx_speculative.py
+++ b/studio/backend/tests/test_mlx_speculative.py
@@ -184,3 +184,23 @@ def test_a_drafter_carrying_its_own_model_module_is_never_found_or_attached(cach
assert spec.cached_drafters(_TARGET, {"vocab_size": 10}) == []
assert not _resolve("auto").sources and not _resolve("dflash").sources
assert _resolve("dflash", "a/Qwen3.5-4B-DFlash").reason == spec.DRAFTER_NOT_FOUND
+
+
+def test_the_built_in_head_is_found_by_the_zoos_detection_or_mlx_vlms_without_it(
+ monkeypatch, tmp_path
+):
+ import sys
+
+ found = lambda name: lambda path: str(path) == str(tmp_path / name)
+ zoo = SimpleNamespace(has_native_mtp_head = found("zoo"))
+ vlm = SimpleNamespace(detect_mtp_splitter = lambda path: found("vlm")(path) or None)
+ monkeypatch.setitem(sys.modules, "mlx_vlm.speculative.drafters.mtp_split", vlm)
+ # An unsloth-zoo without has_native_mtp_head leaves detection to mlx-vlm.
+ for module, finder in ((zoo, "zoo"), (SimpleNamespace(), "vlm")):
+ monkeypatch.setitem(sys.modules, "unsloth_zoo.mlx.speculative", module)
+ heads = [spec.has_builtin_head(str(tmp_path / name)) for name in ("zoo", "vlm")]
+ assert heads == [finder == "zoo", finder == "vlm"]
+ monkeypatch.setitem(sys.modules, "unsloth_zoo.mlx.speculative", zoo)
+ assert not spec.has_builtin_head(None)
+ monkeypatch.setattr(zoo, "has_native_mtp_head", lambda path: 1 / 0)
+ assert not spec.has_builtin_head(str(tmp_path / "zoo"))