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.

Find a GGUF companion published after the weights on the chat load route (#11448)

Daniel Han004351bafb42
diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index 99874d4b86b..e186a6f305e 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -176,14 +176,32 @@ def local_gguf_companion_roots(load_path: str, *, repo_level: bool = False) -> t
return ()
except OSError:
return ()
+ # A sibling must resolve back inside this repo dir: `is_dir()` follows symlinks
+ # (`follow_symlinks=False` is 3.13+) and only the named snapshot was authorized.
+ try:
+ repo_resolved = repo.resolve()
+ # By identity, not spelling: a sibling symlinked to the selected snapshot made one
+ # snapshot look like two, defeating the `len(roots) > 1` guard downstream.
+ selected_resolved = selected.resolve()
+ except OSError as exc:
+ logger.debug("Stopping at unresolvable repo dir %s: %s", repo, exc)
+ return ()
siblings = []
try:
for path in snapshots.iterdir():
if path == selected:
continue
try:
- if path.is_dir():
- siblings.append(path)
+ if not path.is_dir():
+ continue
+ path_resolved = path.resolve()
+ if path_resolved == selected_resolved:
+ logger.debug("Skipping companion snapshot aliasing %s: %s", selected, path)
+ continue
+ if repo_resolved not in path_resolved.parents:
+ logger.debug("Skipping companion snapshot outside %s: %s", repo_resolved, path)
+ continue
+ siblings.append(path)
except OSError as exc:
logger.debug("Skipping unreadable companion snapshot %s: %s", path, exc)
except OSError as exc:
@@ -192,6 +210,44 @@ def local_gguf_companion_roots(load_path: str, *, repo_level: bool = False) -> t
return (str(selected), *(str(path) for path in siblings))
+def local_path_gguf_companion_roots(load_path: str) -> tuple[str, ...]:
+ """Companion roots for a load naming a snapshot DIRECTORY, not a repo id (#10599).
+
+ Widened only when this directory is the one a repo-level selection would hand out
+ anyway, so any other revision counts as pinned; siblings of one ``models--`` dir only.
+ """
+ from pathlib import Path
+ from hub.utils.gguf import select_gguf_cache_snapshot_for_repo_dir
+ from hub.utils.hf_cache_state import same_existing_path
+
+ try:
+ selected = Path(load_path)
+ except (TypeError, ValueError):
+ return ()
+ snapshots = selected.parent
+ repo = snapshots.parent
+ # Same predicate as local_gguf_companion_roots, or the two disagree on what a snapshot is.
+ if snapshots.name != "snapshots" or not repo.name.startswith("models--"):
+ return ()
+ try:
+ if not selected.is_dir():
+ return ()
+ except OSError:
+ return ()
+ try:
+ chosen = select_gguf_cache_snapshot_for_repo_dir(repo)
+ except OSError as exc:
+ logger.debug("Stopping at unreadable repo dir %s: %s", repo, exc)
+ return ()
+ # samefile, not string equality: spellings differ by symlink, or by case on Windows.
+ if chosen is None or not same_existing_path(chosen[3], selected):
+ return ()
+ roots = local_gguf_companion_roots(load_path, repo_level = True)
+ # A lone root is not inert: callers read `roots is not None` as
+ # `allow_disjoint_search_root`, defeating the guard at model_config.py:2062.
+ return roots if len(roots) > 1 else ()
+
+
def local_gguf_companion_state(roots: tuple[str, ...]) -> tuple:
from pathlib import Path
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index b48d36a7fa0..32eaac613e1 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -56,6 +56,9 @@ class LoadRequest(BaseModel):
model_path: str = Field(..., description = "Model identifier or local path")
_gguf_companion_roots: tuple[str, ...] = PrivateAttr(default = ())
+ # `()` is both the default and auto-switch's deliberate "do not widen", so only this
+ # marker separates unset from explicitly empty.
+ _gguf_companion_roots_set: bool = PrivateAttr(default = False)
load_request_id: Optional[str] = Field(
None,
min_length = 1,
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 2b7dec0330a..7165cda7ff2 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -7412,12 +7412,18 @@ def _drafter_for_path(
*,
kind: str = "mtp",
log_native_fallback: bool = False,
+ companion_roots: tuple[str, ...] = (),
) -> Optional[str]:
"""The drafter of ``kind`` that pairs with a local GGUF, or None.
A native-grant-backed load filters candidates through the native rules in
preference order, so a root drafter it must reject still falls through to
the in-bounds subdirectory copy instead of reading as no drafter at all.
+
+ *companion_roots* are the roots the launch searched, tried in the same order
+ ModelConfig.from_identifier tries them. The Apply dedup compares this answer
+ against the drafter the server actually opened, so a narrower search here
+ reports a widened load as drafterless and reloads it on every Apply.
"""
if not gguf_path:
return None
@@ -7439,7 +7445,14 @@ def _drafter_for_path(
rejected |= not usable
return usable
- detected = detect(gguf_path, search_root = root, accept = accept)
+ detected = next(
+ (
+ found
+ for search_root in (companion_roots or (root,))
+ if (found := detect(gguf_path, search_root = search_root, accept = accept))
+ ),
+ None,
+ )
if log_native_fallback and rejected and detected:
logger.info(
"Using %s subdirectory drafter for native load: %s",
@@ -7449,6 +7462,20 @@ def _drafter_for_path(
return detected
+def _path_load_companion_roots(model_identifier: str, native_grant_backed: bool) -> tuple[str, ...]:
+ """Companion roots for a request that named a local snapshot path, else ``()``.
+
+ _maybe_auto_switch_model widens only a repo-id request. A native grant covers ONE
+ directory and is never widened: refusing a candidate after discovery read its header
+ is already too late.
+ """
+ if native_grant_backed or not model_identifier:
+ return ()
+ from core.inference.local_model_resolver import local_path_gguf_companion_roots
+
+ return local_path_gguf_companion_roots(model_identifier)
+
+
def _native_mmproj_accept(candidate: str, gguf_path: str) -> bool:
"""Apply native projector authorization before discovery reads its header."""
try:
@@ -7483,9 +7510,13 @@ def _mtp_draft_for_path(
native_grant_backed: bool,
*,
log_native_fallback: bool = False,
+ companion_roots: tuple[str, ...] = (),
) -> Optional[str]:
return _drafter_for_path(
- gguf_path, native_grant_backed, log_native_fallback = log_native_fallback
+ gguf_path,
+ native_grant_backed,
+ log_native_fallback = log_native_fallback,
+ companion_roots = companion_roots,
)
@@ -7494,12 +7525,14 @@ def _dspark_draft_for_path(
native_grant_backed: bool,
*,
log_native_fallback: bool = False,
+ companion_roots: tuple[str, ...] = (),
) -> Optional[str]:
return _drafter_for_path(
gguf_path,
native_grant_backed,
kind = "dspark",
log_native_fallback = log_native_fallback,
+ companion_roots = companion_roots,
)
@@ -7508,12 +7541,14 @@ def _dflash_draft_for_path(
native_grant_backed: bool,
*,
log_native_fallback: bool = False,
+ companion_roots: tuple[str, ...] = (),
) -> Optional[str]:
return _drafter_for_path(
gguf_path,
native_grant_backed,
kind = "dflash",
log_native_fallback = log_native_fallback,
+ companion_roots = companion_roots,
)
@@ -7566,6 +7601,9 @@ def _active_gguf_intent(
hf_repo = llama_backend.hf_repo,
hf_variant = llama_backend.hf_variant,
)
+ # What the launch searched, not what one snapshot holds. Recorded at load, so a
+ # request that deliberately pinned one revision is still compared against one root.
+ _loaded_roots = tuple(getattr(llama_backend, "_openai_gguf_companion_roots", ()) or ())
return _gguf_request_intent(
source,
request,
@@ -7587,9 +7625,15 @@ def _active_gguf_intent(
preserve_multi_gpu_on_layer = (
llama_backend.layer_preserves_tensor_intent and not _is_explicit_tensor_drop(request)
),
- mtp_draft_path = _mtp_draft_for_path(llama_backend.gguf_path, native_grant_backed),
- dspark_draft_path = _dspark_draft_for_path(llama_backend.gguf_path, native_grant_backed),
- dflash_draft_path = _dflash_draft_for_path(llama_backend.gguf_path, native_grant_backed),
+ mtp_draft_path = _mtp_draft_for_path(
+ llama_backend.gguf_path, native_grant_backed, companion_roots = _loaded_roots
+ ),
+ dspark_draft_path = _dspark_draft_for_path(
+ llama_backend.gguf_path, native_grant_backed, companion_roots = _loaded_roots
+ ),
+ dflash_draft_path = _dflash_draft_for_path(
+ llama_backend.gguf_path, native_grant_backed, companion_roots = _loaded_roots
+ ),
compare_mtp_draft = True,
extra_args_inherited = inherits_extras and not batch_overrides_inherit,
)
@@ -10168,6 +10212,7 @@ async def _maybe_auto_switch_model(
try:
load_request = LoadRequest(**load_kwargs)
load_request._gguf_companion_roots = gguf_companion_roots
+ load_request._gguf_companion_roots_set = True
await _load_model_impl(
load_request,
fastapi_request,
@@ -10193,6 +10238,7 @@ async def _maybe_auto_switch_model(
load_kwargs.pop("gpu_ids", None)
load_request = LoadRequest(**load_kwargs)
load_request._gguf_companion_roots = gguf_companion_roots
+ load_request._gguf_companion_roots_set = True
await _load_model_impl(
load_request,
fastapi_request,
@@ -15849,6 +15895,13 @@ async def _load_model_impl(
# Keep the inventory ref public while loading the materialized artifact.
public_model_identifier = _public_model_identifier(request.model_path, model_identifier)
+ # Only when unset: auto-switch and the idle stash own their own scope. Walks
+ # snapshots/, so off-loop.
+ if not request._gguf_companion_roots and not request._gguf_companion_roots_set:
+ request._gguf_companion_roots = await asyncio.to_thread(
+ _path_load_companion_roots, model_identifier, native_grant_backed
+ )
+ request._gguf_companion_roots_set = True
ollama_advertised_id = (
await asyncio.to_thread(ollama_model_ref_public_id, request.model_path)
if resolved_ollama_path is not None
@@ -16132,12 +16185,21 @@ async def _load_model_impl(
if speech_codec_path is not None:
gguf_intent = replace(gguf_intent, audio_codec_path = speech_codec_path)
same_loaded_model = llama_backend.matches_load_source(gguf_intent)
+ _loaded_companion_roots = tuple(
+ getattr(llama_backend, "_openai_gguf_companion_roots", ()) or ()
+ )
if same_loaded_model and config.gguf_hf_repo and llama_backend.gguf_path:
gguf_intent = replace(
gguf_intent,
- mtp_draft_path = _mtp_draft_for_path(llama_backend.gguf_path, False),
- dspark_draft_path = _dspark_draft_for_path(llama_backend.gguf_path, False),
- dflash_draft_path = _dflash_draft_for_path(llama_backend.gguf_path, False),
+ mtp_draft_path = _mtp_draft_for_path(
+ llama_backend.gguf_path, False, companion_roots = _loaded_companion_roots
+ ),
+ dspark_draft_path = _dspark_draft_for_path(
+ llama_backend.gguf_path, False, companion_roots = _loaded_companion_roots
+ ),
+ dflash_draft_path = _dflash_draft_for_path(
+ llama_backend.gguf_path, False, companion_roots = _loaded_companion_roots
+ ),
compare_mtp_draft = True,
)
_effective_tensor = _effective_tensor_parallel(
@@ -17089,6 +17151,12 @@ async def validate_model(
if native_access_deferred:
await asyncio.to_thread(account_access.require_model_access, model_identifier)
+ # Same roots /load will use, or a sibling-revision projector reads as text-only here
+ # and the load then serves vision.
+ _validate_companion_roots = await asyncio.to_thread(
+ _path_load_companion_roots, model_identifier, native_grant_backed
+ )
+
# The frontend validates before it loads, so this needs the same guard as
# /load; otherwise the stall just moves here and /load is never reached.
# Off-loop twice over: the guard is a network round trip, and the first
@@ -17104,6 +17172,7 @@ async def validate_model(
# to travel with it rather than being applied afterwards.
drafter_accept = _native_drafter_accept if native_grant_backed else None,
mmproj_accept = _native_mmproj_accept if native_grant_backed else None,
+ gguf_companion_roots = _validate_companion_roots or None,
)
config = await asyncio.to_thread(_resolve_config)
@@ -17996,6 +18065,9 @@ def _cached_estimate_config(
return _ESTIMATE_NOT_ON_DISK
from core.inference.llama_cpp import _hf_offline_if_unreachable_for
+ # Same roots /load will use: a sibling-revision head or projector is weight it maps.
+ _estimate_companion_roots = _path_load_companion_roots(model_identifier, native_grant_backed)
+
def _resolve():
return ModelConfig.from_identifier(
model_id = model_identifier,
@@ -18003,6 +18075,7 @@ def _cached_estimate_config(
gguf_variant = gguf_variant,
drafter_accept = _native_drafter_accept if native_grant_backed else None,
mmproj_accept = _native_mmproj_accept if native_grant_backed else None,
+ gguf_companion_roots = _estimate_companion_roots or None,
)
# Offline FIRST, not only when the Hub is unreachable. The gate above established
diff --git a/studio/backend/tests/test_detect_mmproj_file.py b/studio/backend/tests/test_detect_mmproj_file.py
index b3e2d0ca09a..156ae347b03 100644
--- a/studio/backend/tests/test_detect_mmproj_file.py
+++ b/studio/backend/tests/test_detect_mmproj_file.py
@@ -380,6 +380,42 @@ def test_trusted_companion_snapshot_finds_nested_projector(tmp_path: Path):
) == str(projector.resolve())
+def test_a_containing_trusted_root_does_not_recurse_into_a_sibling_quant(tmp_path: Path):
+ """#10599's widening must not reach the quant next door.
+
+ ``allow_disjoint_search_root`` used to set ``recursive_root`` for every root, including
+ the one holding the weights, which is the case the incremental walk at the top of
+ detect_mmproj_file exists to confine. Every other quant subdirectory of the snapshot
+ became a candidate, and since none of them shares a prefix with the weight stem they
+ all tie at zero, so the shorter-stem rule handed UD-Q4_K_XL the IQ1_S projector.
+ """
+ snapshot = tmp_path / "snapshots" / "rev"
+ weight = _touch(snapshot / "UD-Q4_K_XL" / "Qwen3-VL-235B-UD-Q4_K_XL.gguf")
+ mine = _touch(snapshot / "UD-Q4_K_XL" / "mmproj-UD-Q4_K_XL.gguf")
+ _touch(snapshot / "UD-IQ1_S" / "Qwen3-VL-235B-UD-IQ1_S.gguf")
+ _touch(snapshot / "UD-IQ1_S" / "mmproj-UD-IQ1_S.gguf")
+
+ assert detect_mmproj_file(
+ str(weight), search_root = str(snapshot), allow_disjoint_search_root = True
+ ) == str(mine.resolve())
+
+
+def test_a_containing_trusted_root_keeps_its_own_root_level_projector(tmp_path: Path):
+ """The same guard, where the only correct projector sits at the snapshot root.
+
+ The ancestor walk still has to reach it, and a foreign quant's projector must not win
+ on a longer shared prefix just because the recursion made it a candidate.
+ """
+ snapshot = tmp_path / "snapshots" / "rev"
+ weight = _touch(snapshot / "UD-Q4_K_XL" / "vision-model-UD-Q4_K_XL.gguf")
+ root_level = _touch(snapshot / "mmproj-F16.gguf")
+ _touch(snapshot / "UD-IQ1_S" / "mmproj-vision-model-UD-Q4_K_XL-F16.gguf")
+
+ assert detect_mmproj_file(
+ str(weight), search_root = str(snapshot), allow_disjoint_search_root = True
+ ) == str(root_level.resolve())
+
+
def test_finds_the_projector_hermes_stages_under_assets(tmp_path: Path):
"""Hermes keeps a download's mmproj in models/assets/ so its router never lists it as a
model; the weight sits one level up. A sibling-only walk loads Qwen3.8-27B text-only."""
diff --git a/studio/backend/tests/test_gguf_load_cache_reuse.py b/studio/backend/tests/test_gguf_load_cache_reuse.py
index 307f1b2f6e1..e7b3a3ecc26 100644
--- a/studio/backend/tests/test_gguf_load_cache_reuse.py
+++ b/studio/backend/tests/test_gguf_load_cache_reuse.py
@@ -11,6 +11,7 @@ from __future__ import annotations
import asyncio
import importlib.util
import logging
+import os
import sys
import threading
import types as _types
@@ -1433,3 +1434,358 @@ class TestLoadHubDownloadExclusion:
assert (
self._capture_hub_guard_require_mmproj(["--no-mmproj"], request_extra_args = []) is True
)
+
+
+class _CompanionMetadataReached(BaseException):
+ """Raised from a stubbed from_identifier so the load stops with its kwargs captured."""
+
+
+def _companion_cache_repo(tmp_path, *, weights: str = "weights-revision"):
+ """An HF cache repo whose weights snapshot predates the one holding the companions.
+
+ The shape #10599 reports: the MTP head and the mmproj were published after the
+ quant, so ``refs/main`` names a revision that holds no weights at all and the
+ companions sit beside it, in a snapshot the weights' own directory does not reach.
+ """
+ repo = tmp_path / "models--org--Vision-GGUF"
+ selected = repo / "snapshots" / weights
+ companions = repo / "snapshots" / "companion-revision"
+ selected.mkdir(parents = True)
+ companions.mkdir(parents = True)
+ (repo / "blobs").mkdir(exist_ok = True)
+ (repo / "refs").mkdir(exist_ok = True)
+ (repo / "refs" / "main").write_text("companion-revision")
+ (selected / "vision-model-Q4_K_M.gguf").write_bytes(b"GGUF weights")
+ (companions / "mtp-vision-model-Q4_0.gguf").write_bytes(b"GGUF drafter")
+ (companions / "mmproj-vision-model-F16.gguf").write_bytes(b"GGUF companion")
+ os.utime(selected, (1_000, 1_000))
+ os.utime(companions, (2_000, 2_000))
+ return repo, selected, companions
+
+
+@contextmanager
+def _capture_load_config(
+ route,
+ seen,
+ *,
+ native_grant_backed = False,
+ model_identifier = None,
+):
+ backend = SimpleNamespace(
+ is_loaded = False,
+ model_identifier = None,
+ holds_no_vram = False,
+ active_model_name = None,
+ _audio_probed = True,
+ adopt_load_intent_if_matched = lambda _intent: False,
+ )
+
+ def _from_identifier(**kwargs):
+ seen.update(kwargs)
+ raise _CompanionMetadataReached()
+
+ with (
+ patch.object(
+ route,
+ "_resolve_model_identifier_for_request",
+ return_value = (model_identifier, model_identifier, native_grant_backed),
+ ),
+ patch.object(route, "resolve_effective_chat_template_override", return_value = None),
+ patch.object(route, "get_llama_cpp_backend", return_value = backend),
+ patch.object(route, "get_inference_backend", return_value = backend),
+ patch.object(route, "ModelConfig", SimpleNamespace(from_identifier = _from_identifier)),
+ ):
+ yield
+
+
+class TestPathLoadCompanionRoots:
+ """#10599: a model picked in chat loads by PATH, so the auto-switch route's
+ repo-level widening never ran for it and an MTP head or mmproj published into a
+ later revision of the same repo dir stayed invisible until the user deleted and
+ refetched the whole repo."""
+
+ def _roots_for(self, tmp_path, name, **kwargs):
+ from models.inference import LoadRequest
+
+ route = _load_route_module(name, "routes/inference.py")
+ load_path = kwargs.pop("load_path")
+ preset = kwargs.pop("preset_roots", None)
+ preset_set = kwargs.pop("preset_set", False)
+ request = LoadRequest(model_path = load_path, gguf_variant = "Q4_K_M")
+ if preset is not None:
+ request._gguf_companion_roots = preset
+ if preset_set:
+ request._gguf_companion_roots_set = True
+ seen = {}
+ with _capture_load_config(route, seen, model_identifier = load_path, **kwargs):
+ with pytest.raises(_CompanionMetadataReached):
+ _run_route_load(route, request)
+ return seen.get("gguf_companion_roots")
+
+ def test_path_load_widens_to_the_sibling_snapshot_holding_the_companions(self, tmp_path):
+ _repo, selected, companions = _companion_cache_repo(tmp_path)
+ roots = self._roots_for(
+ tmp_path,
+ "inference_route_module_for_path_load_widening",
+ load_path = str(selected),
+ )
+ assert tuple(map(Path, roots or ())) == (selected, companions)
+
+ def test_path_load_resolves_both_the_mtp_head_and_the_mmproj(self, tmp_path):
+ """The user-visible symptom, through the real ModelConfig: both companions."""
+ from utils.models.model_config import ModelConfig
+ from core.inference.local_model_resolver import local_path_gguf_companion_roots
+
+ _repo, selected, companions = _companion_cache_repo(tmp_path)
+ assert (
+ ModelConfig.from_identifier(str(selected), gguf_variant = "Q4_K_M").gguf_mtp_file is None
+ )
+ config = ModelConfig.from_identifier(
+ str(selected),
+ gguf_variant = "Q4_K_M",
+ gguf_companion_roots = local_path_gguf_companion_roots(str(selected)),
+ )
+ assert config.gguf_mtp_file == str((companions / "mtp-vision-model-Q4_0.gguf").resolve())
+ assert config.gguf_mmproj_file == str(
+ (companions / "mmproj-vision-model-F16.gguf").resolve()
+ )
+
+ def test_a_pinned_non_selected_revision_is_not_widened(self, tmp_path):
+ """Naming a revision the repo-level selection would not hand out pins it."""
+ repo, pinned, _companions = _companion_cache_repo(tmp_path)
+ newer_weights = repo / "snapshots" / "newer-weights-revision"
+ newer_weights.mkdir(parents = True)
+ (newer_weights / "vision-model-Q4_K_M.gguf").write_bytes(b"GGUF weights")
+ os.utime(newer_weights, (3_000, 3_000))
+ assert not self._roots_for(
+ tmp_path,
+ "inference_route_module_for_pinned_revision",
+ load_path = str(pinned),
+ )
+
+ def test_a_native_grant_backed_load_is_not_widened(self, tmp_path):
+ """A native grant covers one directory; a sibling revision is outside it."""
+ _repo, selected, _companions = _companion_cache_repo(tmp_path)
+ assert not self._roots_for(
+ tmp_path,
+ "inference_route_module_for_native_grant_widening",
+ load_path = str(selected),
+ native_grant_backed = True,
+ )
+
+ def test_roots_the_caller_already_set_are_left_alone(self, tmp_path):
+ """Auto-switch resolved these from the repo, and the idle stash restores what
+ the last load actually used: neither may be recomputed from the path."""
+ _repo, selected, _companions = _companion_cache_repo(tmp_path)
+ roots = self._roots_for(
+ tmp_path,
+ "inference_route_module_for_preset_roots",
+ load_path = str(selected),
+ preset_roots = (str(selected),),
+ )
+ assert tuple(map(Path, roots or ())) == (selected,)
+
+ def test_an_explicitly_empty_scope_is_left_alone(self, tmp_path):
+ """`()` from a caller that resolved an exact revision means do not widen.
+
+ The default is `()` too, so only the marker separates them. Without it the
+ route recomputes the scope from the path and the pinned request picks up a
+ projector or drafter from a revision it excluded.
+ """
+ _repo, selected, _companions = _companion_cache_repo(tmp_path)
+ assert not self._roots_for(
+ tmp_path,
+ "inference_route_module_for_empty_preset_roots",
+ load_path = str(selected),
+ preset_roots = (),
+ preset_set = True,
+ )
+
+ def test_a_bare_repo_id_is_not_widened(self, tmp_path):
+ assert not self._roots_for(
+ tmp_path,
+ "inference_route_module_for_repo_id_load",
+ load_path = REPO,
+ )
+
+
+def _mtp_cache_repo(tmp_path):
+ """Weights in the older snapshot, the MTP head alone in the newer one (#10599)."""
+ repo = tmp_path / "models--org--Draft-GGUF"
+ weights = repo / "snapshots" / "weights-revision"
+ companions = repo / "snapshots" / "companion-revision"
+ weights.mkdir(parents = True)
+ companions.mkdir(parents = True)
+ (weights / "draft-model-Q4_K_M.gguf").write_bytes(b"GGUF weights")
+ (companions / "mtp-draft-model.gguf").write_bytes(b"GGUF drafter")
+ os.utime(weights, (1_000, 1_000))
+ os.utime(companions, (2_000, 2_000))
+ return repo, weights, companions
+
+
+def test_the_apply_dedup_sees_the_drafter_the_launch_opened(tmp_path):
+ """A widened load must not read as drafterless, or every Apply reloads it.
+
+ _active_gguf_intent recomputes the drafter to compare against the running
+ server. Searching only the weights' snapshot answers None while the server
+ holds the sibling revision's head, so matches_load_source reports a model
+ change and a settings Apply restarts a healthy llama-server.
+ """
+ from core.inference.local_model_resolver import local_path_gguf_companion_roots
+ from models.inference import LoadRequest
+ from utils.models.model_config import ModelConfig
+
+ route = _load_route_module("inference_route_module_for_apply_dedup", "routes/inference.py")
+ _repo, weights, companions = _mtp_cache_repo(tmp_path)
+ main = weights / "draft-model-Q4_K_M.gguf"
+ head = companions / "mtp-draft-model.gguf"
+
+ roots = local_path_gguf_companion_roots(str(weights))
+ assert tuple(map(Path, roots)) == (weights, companions)
+ # The drafter the launch actually opens, through the real ModelConfig.
+ launched = ModelConfig.from_identifier(
+ str(weights), gguf_variant = "Q4_K_M", gguf_companion_roots = roots
+ ).gguf_mtp_file
+ assert launched == str(head.resolve())
+
+ backend = SimpleNamespace(
+ extra_args = (),
+ last_load_intent = None,
+ hf_repo = None,
+ hf_variant = None,
+ gguf_path = str(main),
+ layer_preserves_tensor_intent = False,
+ _openai_gguf_companion_roots = tuple(roots),
+ )
+ intent = route._active_gguf_intent(
+ LoadRequest(model_path = str(weights), gguf_variant = "Q4_K_M"),
+ backend,
+ model_identifier = str(weights),
+ chat_template_override = None,
+ n_parallel = 1,
+ native_grant_backed = False,
+ )
+ assert intent.mtp_draft_path == launched
+
+ # A load that recorded no widening keeps the single-snapshot answer, so a
+ # deliberately pinned revision is still compared against its own root only.
+ backend._openai_gguf_companion_roots = ()
+ pinned = route._active_gguf_intent(
+ LoadRequest(model_path = str(weights), gguf_variant = "Q4_K_M"),
+ backend,
+ model_identifier = str(weights),
+ chat_template_override = None,
+ n_parallel = 1,
+ native_grant_backed = False,
+ )
+ assert pinned.mtp_draft_path is None
+
+
+def test_a_symlinked_sibling_snapshot_is_not_a_trusted_root(tmp_path):
+ """`is_dir()` follows symlinks, and `follow_symlinks=False` is 3.13+.
+
+ Access is validated for the snapshot the caller named. A directory symlink placed
+ under `snapshots/` would otherwise be handed back as a trusted disjoint search root,
+ so `ModelConfig.from_identifier` would read GGUF companions from wherever it points.
+ """
+ from core.inference.local_model_resolver import local_gguf_companion_roots
+
+ repo = tmp_path / "cache" / "models--a--b"
+ snapshots = repo / "snapshots"
+ selected = snapshots / "rev1"
+ selected.mkdir(parents = True)
+ (selected / "model.gguf").touch()
+ real_sibling = snapshots / "rev2"
+ real_sibling.mkdir()
+ (real_sibling / "mmproj.gguf").touch()
+ outside = tmp_path / "other_tenant"
+ outside.mkdir()
+ (outside / "leaked.gguf").touch()
+ (snapshots / "rev3").symlink_to(outside, target_is_directory = True)
+
+ roots = local_gguf_companion_roots(str(selected), repo_level = True)
+ names = [os.path.basename(root) for root in roots]
+ assert "rev1" in names and "rev2" in names
+ assert "rev3" not in names, f"escaped symlink returned as a trusted root: {roots}"
+ assert all(str(outside) not in root for root in roots)
+
+
+def test_a_repo_with_no_sibling_snapshot_widens_nothing(tmp_path):
+ """One root is the caller's own snapshot, so there is nothing to widen to.
+
+ Callers read a non-None roots tuple as `allow_disjoint_search_root`, which makes the
+ mmproj scan recursive, so returning a bare single root silently relaxes a guard
+ instead of being inert.
+ """
+ from core.inference.local_model_resolver import local_path_gguf_companion_roots
+
+ repo = tmp_path / "cache" / "models--a--b"
+ snapshots = repo / "snapshots"
+ selected = snapshots / "only"
+ selected.mkdir(parents = True)
+ (selected / "model.gguf").touch()
+
+ assert local_path_gguf_companion_roots(str(selected)) == ()
+
+
+def test_a_sibling_symlinked_to_the_selected_snapshot_is_not_a_second_root(tmp_path):
+ """One physical snapshot plus an alias of it is still one snapshot.
+
+ The sibling scan excluded the selected snapshot by path equality while the gate above
+ it compared with `samefile`, so `snapshots/alias -> snapshots/only` came back as a
+ second root. That defeats the `len(roots) > 1` guard, which is what stops a lone root
+ from being handed to callers who read a non-None tuple as
+ `allow_disjoint_search_root`.
+ """
+ from core.inference.local_model_resolver import local_path_gguf_companion_roots
+
+ repo = tmp_path / "cache" / "models--a--b"
+ snapshots = repo / "snapshots"
+ selected = snapshots / "only"
+ selected.mkdir(parents = True)
+ (selected / "model.gguf").touch()
+ (snapshots / "alias").symlink_to(selected, target_is_directory = True)
+
+ assert local_path_gguf_companion_roots(str(selected)) == ()
+
+
+def test_an_aliased_sibling_does_not_displace_a_real_one(tmp_path):
+ """The alias drops out; a genuine sibling revision still widens the scope."""
+ from core.inference.local_model_resolver import local_gguf_companion_roots
+
+ repo = tmp_path / "cache" / "models--a--b"
+ snapshots = repo / "snapshots"
+ selected = snapshots / "weights"
+ selected.mkdir(parents = True)
+ (selected / "model.gguf").touch()
+ real = snapshots / "companion"
+ real.mkdir()
+ (real / "mmproj.gguf").touch()
+ (snapshots / "alias").symlink_to(selected, target_is_directory = True)
+
+ roots = local_gguf_companion_roots(str(selected), repo_level = True)
+ assert tuple(map(Path, roots)) == (selected, real)
+
+
+def test_an_explicitly_empty_companion_scope_is_not_recomputed():
+ """`()` means two different things and only one of them may be widened.
+
+ It is the default, meaning nobody has decided yet, and it is also what the
+ auto-switch route and the idle stash assign when they resolved an exact revision
+ and deliberately want no sibling widening. A truthiness test conflates them, and
+ the pinned request then picks up a projector or drafter from another revision.
+ """
+ from models.inference import LoadRequest
+
+ unset = LoadRequest(model_path = "/models/x")
+ assert unset._gguf_companion_roots == ()
+ assert unset._gguf_companion_roots_set is False
+
+ pinned = LoadRequest(model_path = "/models/x")
+ pinned._gguf_companion_roots = ()
+ pinned._gguf_companion_roots_set = True
+ assert pinned._gguf_companion_roots == ()
+ # Private, so the marker cannot be set through the wire model either.
+ assert "_gguf_companion_roots_set" not in pinned.model_dump()
+ injected = LoadRequest(model_path = "/models/x", _gguf_companion_roots_set = True)
+ assert injected._gguf_companion_roots_set is False
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index e192fcbe9dd..9b17d3aa48c 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -2463,6 +2463,48 @@ def test_snapshot_selector_skips_only_the_unreadable_child(tmp_path, monkeypatch
assert selected[3] == readable
+def test_path_companion_roots_widen_only_the_snapshot_the_repo_would_hand_out(tmp_path):
+ """#10599: loading by path widens to the sibling revisions of the SAME repo dir,
+ and only when the path is the one a repo-level selection resolves to."""
+ repo, old, newer = _vision_gguf_cache_repo(tmp_path)
+ (newer / "mmproj-vision-model-F16.gguf").write_bytes(b"GGUF companion")
+ os.utime(old, (1_000, 1_000))
+ os.utime(newer, (2_000, 2_000))
+
+ assert tuple(map(Path, resolver.local_path_gguf_companion_roots(str(old)))) == (old, newer)
+ # A revision the selector would not hand out is pinned, so it keeps its own root only.
+ assert resolver.local_path_gguf_companion_roots(str(newer)) == ()
+
+ pinned = repo / "snapshots" / "newer-weights-revision"
+ pinned.mkdir(parents = True)
+ (pinned / "vision-model-Q4_K_M.gguf").write_bytes(b"GGUF weights")
+ os.utime(pinned, (3_000, 3_000))
+ assert resolver.local_path_gguf_companion_roots(str(old)) == ()
+ assert tuple(map(Path, resolver.local_path_gguf_companion_roots(str(pinned)))) == (
+ pinned,
+ newer,
+ old,
+ )
+
+
[email protected]("kind", ["plain_dir", "repo_dir", "missing", "file", "repo_id"])
+def test_path_companion_roots_refuse_anything_outside_an_hf_cache_snapshot(tmp_path, kind):
+ """The widening reaches sibling revisions of one ``models--`` dir and nothing else."""
+ repo, old, _newer = _vision_gguf_cache_repo(tmp_path)
+ candidates = {
+ "plain_dir": tmp_path / "loose-model-dir",
+ "repo_dir": repo,
+ "missing": old.parent / "absent-revision",
+ "file": old / "vision-model-Q4_K_M.gguf",
+ "repo_id": Path("org/Vision-GGUF"),
+ }
+ target = candidates[kind]
+ if kind == "plain_dir":
+ target.mkdir()
+ (target / "vision-model-Q4_K_M.gguf").write_bytes(b"GGUF weights")
+ assert resolver.local_path_gguf_companion_roots(str(target)) == ()
+
+
def test_disjoint_companion_roots_preserve_selected_snapshot_ancestor_walk(tmp_path):
"""A selected snapshot still walks intermediate parents before sibling revisions."""
from utils.models.model_config import detect_mmproj_file
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index ccc342fe66f..9f4f1bef1fe 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -2105,7 +2105,11 @@ def detect_mmproj_file(
break
elif allow_disjoint_search_root:
_add(root_resolved)
- if allow_disjoint_search_root:
+ # Only a root that does NOT hold the weights: for the one that does, the
+ # ancestor walk above IS this function's guard and rglob defeats it, so a
+ # sibling QUANT's projector becomes a candidate and wins the shorter-stem
+ # tiebreak. A disjoint revision still recurses, which #10210 needs.
+ if allow_disjoint_search_root and not root_contains_start:
recursive_root = root_resolved
except OSError:
pass