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: load a downloaded GGUF from disk when the Hub cannot be read or refuses it (#12161)

Daniel Han866b5bcff5e0
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 2e814690646..9ba1453e73d 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -3209,8 +3209,12 @@ def _cached_variant_candidates(
hf_variant: str,
*,
require_mmproj: bool = False,
+ strict: bool = False,
) -> Generator[tuple[str, str, list[str], Path], None, None]:
- """Yield complete cached variant copies in snapshot preference order."""
+ """Yield complete cached variant copies in snapshot preference order.
+
+ A copy whose recorded download is unfinished or cancelled comes last, and ``strict``
+ drops it: only a copy that can run without the Hub qualifies then."""
try:
from hub.utils.gguf_sources import (
cached_gguf_manifest_complete,
@@ -3249,7 +3253,8 @@ def _cached_variant_candidates(
continue
yield candidate
# Keep existing reuse semantics when no completed duplicate is available.
- yield from pending_downloads
+ if not strict:
+ yield from pending_downloads
except Exception as e:
logger.debug(f"Cache lookup for variant failed: {e}")
@@ -3354,8 +3359,10 @@ def cached_gguf_for_load(
require_mmproj: bool = False,
verify_sizes: bool = False,
hf_token: Optional[str] = None,
+ strict: bool = False,
) -> Optional[str]:
- """Return a cached GGUF that can be loaded without downloading."""
+ """Return a cached GGUF that can be loaded without downloading (``strict``: and whose
+ recorded download is complete, see _cached_variant_candidates)."""
if not hf_variant:
return None
hf_repo = _resolve_repo_id_casing(hf_repo)
@@ -3363,6 +3370,7 @@ def cached_gguf_for_load(
hf_repo,
hf_variant,
require_mmproj = require_mmproj,
+ strict = strict,
):
if verify_sizes and not _cached_candidate_matches_revision_size(
hf_repo, candidate, hf_token
@@ -7206,6 +7214,8 @@ class LlamaCppBackend:
self._last_load_warning: Optional[str] = None
# Same, for a quant fallback: the download fills the pair, the launch publishes it.
self._variant_fallback_warning: Optional[str] = None
+ # The route's Hub notice for the running model, so /status matches the load response.
+ self.hub_access_warning: Optional[str] = None
self._pending_variant_fallback: Optional[tuple[str, str]] = None
# Set per launch by _record_carveout_advice; None on nearly every load.
self._last_carveout_advice: Optional[dict] = None
@@ -14687,6 +14697,7 @@ class LlamaCppBackend:
reverse -- the placement everything was priced against is the one that just
died."""
self._last_load_warning = None
+ self.hub_access_warning = None
# Same lifetime, same reason: the advice describes the placement the dying
# child was priced against and must not be reported against its replacement.
self._last_carveout_advice = None
diff --git a/studio/backend/hub/services/models/gguf_variants.py b/studio/backend/hub/services/models/gguf_variants.py
index 8464fcf5e67..0dc6dc5fcbd 100644
--- a/studio/backend/hub/services/models/gguf_variants.py
+++ b/studio/backend/hub/services/models/gguf_variants.py
@@ -177,14 +177,41 @@ def _variant_requirement_cache_get(key: tuple[str, str, str]) -> Optional[_GgufV
def _variant_requirement_cache_set_many(
repo_id: str, hf_token: Optional[str], requirements: dict[str, _GgufVariantRequirement]
) -> None:
+ global _VARIANT_REQUIREMENT_FORGOTTEN
with _VARIANT_HASH_LOCK:
now = time.monotonic()
for quant, requirement in requirements.items():
key = _variant_hash_cache_key(repo_id, quant, hf_token)
_VARIANT_REQUIREMENT_CACHE[key] = (requirement, now)
_VARIANT_REQUIREMENT_CACHE.move_to_end(key)
+ known = key[:2]
+ _VARIANT_REQUIREMENT_LAST_KNOWN[known] = requirement
+ _VARIANT_REQUIREMENT_LAST_KNOWN.move_to_end(known)
while len(_VARIANT_REQUIREMENT_CACHE) > _VARIANT_HASH_MAX:
_VARIANT_REQUIREMENT_CACHE.popitem(last = False)
+ while len(_VARIANT_REQUIREMENT_LAST_KNOWN) > _VARIANT_REQUIREMENT_LAST_KNOWN_MAX:
+ _VARIANT_REQUIREMENT_LAST_KNOWN.popitem(last = False)
+ _VARIANT_REQUIREMENT_FORGOTTEN = True
+
+
+# Newest requirement per (repo, variant), kept past the TTL so an expired entry never reads as
+# "nothing required". Not keyed by credential: it describes the repo's files.
+_VARIANT_REQUIREMENT_LAST_KNOWN: "OrderedDict[tuple[str, str], _GgufVariantRequirement]" = (
+ OrderedDict()
+)
+# After any eviction an absent entry may be a forgotten companion.
+_VARIANT_REQUIREMENT_LAST_KNOWN_MAX = 65536
+_VARIANT_REQUIREMENT_FORGOTTEN = False
+
+
+def _variant_requirement_last_known(key: tuple[str, ...]) -> Optional[_GgufVariantRequirement]:
+ with _VARIANT_HASH_LOCK:
+ return _VARIANT_REQUIREMENT_LAST_KNOWN.get(key[:2])
+
+
+def _variant_requirement_may_be_forgotten() -> bool:
+ with _VARIANT_HASH_LOCK:
+ return _VARIANT_REQUIREMENT_FORGOTTEN
def _build_gguf_variant_requirements(siblings: list) -> dict[str, _GgufVariantRequirement]:
@@ -1073,6 +1100,8 @@ async def get_gguf_variants_answer(
cache_authorized = [True]
variant_context_sources: dict[str, str] = {}
hub_listing = None
+ # The downloaded rows a Hub-less answer proved complete from disk, see _locally_resolved.
+ locally_proven: list[Optional[frozenset]] = [None]
def _compute(local_path: Optional[str] = local_path) -> GgufVariantsResponse:
nonlocal hub_listing
@@ -1401,6 +1430,57 @@ async def get_gguf_variants_answer(
hf_token, repo_id = repo_id, is_cached = lambda: True, offline = bool(offline)
)
+ def _locally_resolved(
+ response: GgufVariantsResponse, snapshot: Optional[Path]
+ ) -> GgufVariantsResponse:
+ """*response* marked ``dependencies_resolved`` when the disk alone proves every
+ downloaded row loadable. Only for answers given because the Hub could not be read
+ (offline, or the listing failed): with the Hub up, a companion the current revision
+ added is only visible in its listing, which is why a local-first answer never
+ carries this. The proof, per downloaded quant: its main file is in *snapshot*, the
+ snapshot's own manifest, cancel marker and blobs do not make it partial, the
+ download's recorded plan (main shards and companions) is all on disk, and so is
+ every companion a Hub answer earlier in this process named. A drafter that is still
+ missing only turns speculative decoding off at load, so a quant downloaded before
+ manifests existed is judged on its shards alone."""
+ if snapshot is None or response.dependencies_resolved:
+ return response
+ from hub.utils.gguf_sources import (
+ cached_gguf_manifest_complete,
+ cached_gguf_source_partial,
+ )
+
+ downloaded = [v for v in response.variants if v.downloaded]
+ if not downloaded or any(v.partial for v in downloaded):
+ return response
+ proven = set()
+ for v in downloaded:
+ if not v.quant or not v.filename:
+ return response
+ try:
+ if not (snapshot / v.filename).is_file():
+ return response
+ if cached_gguf_source_partial(response.repo_id, v.quant, snapshot):
+ return response
+ if not cached_gguf_manifest_complete(response.repo_id, v.quant, snapshot):
+ return response
+ requirement = _variant_requirement_last_known(
+ _variant_hash_cache_key(response.repo_id, v.quant, hf_token)
+ )
+ if requirement is None and _variant_requirement_may_be_forgotten():
+ return response
+ for expected in requirement.expected_files if requirement is not None else ():
+ target = snapshot / expected.path
+ if not target.is_file() or (
+ expected.size and target.stat().st_size != expected.size
+ ):
+ return response
+ except (OSError, RuntimeError, ValueError):
+ return response
+ proven.add((v.quant.lower(), v.filename))
+ locally_proven[0] = frozenset(proven)
+ return response.model_copy(update = {"dependencies_resolved": True})
+
def _scoped_local_response():
"""The pinned snapshot's own answer, or None when it holds nothing."""
if snapshot_scope is None or not cache_reads_authorized:
@@ -1420,7 +1500,11 @@ async def get_gguf_variants_answer(
if local_only:
scoped_response = _scoped_local_response()
if scoped_response is not None:
- return scoped_response
+ return (
+ _locally_resolved(scoped_response, snapshot_scope)
+ if offline
+ else scoped_response
+ )
cached = (
select_gguf_cache_snapshot(repo_id, root = hub_cache)
if cache_reads_authorized
@@ -1434,10 +1518,11 @@ async def get_gguf_variants_answer(
# repo-dir walk a sibling revision's.
answered_from[0] = str(snapshot)
# The lister leaves torn quants in: they stay listed for management, but not ready.
- return _with_state_partials(
+ response = _with_state_partials(
_local_response(repo_id, variants, has_vision, complete),
snapshot,
)
+ return _locally_resolved(response, snapshot) if offline else response
if local_path and is_local_path(local_path):
variants, has_vision = list_local_gguf_variants(local_path)
if variants or has_vision:
@@ -1475,7 +1560,7 @@ async def get_gguf_variants_answer(
return None
scoped_response = _scoped_local_response()
if scoped_response is not None:
- return scoped_response
+ return _locally_resolved(scoped_response, snapshot_scope)
cached = select_gguf_cache_snapshot(repo_id, root = hub_cache)
if cached is not None:
variants, has_vision, complete, snapshot = _merge_when_the_repo_id_loads(
@@ -1484,8 +1569,11 @@ async def get_gguf_variants_answer(
answered_from[0] = str(snapshot)
# Same reason as the local_only branch above: an unreachable Hub is exactly when a resume has
# nowhere else to surface, so state partials are included.
- return _with_state_partials(
- _local_response(repo_id, variants, has_vision, complete),
+ return _locally_resolved(
+ _with_state_partials(
+ _local_response(repo_id, variants, has_vision, complete),
+ snapshot,
+ ),
snapshot,
)
partial = _quants_from_state(repo_id, hub_cache)
@@ -1934,9 +2022,11 @@ async def get_gguf_variants_answer(
if cached is None:
original_source = answered_from[0]
original_local = answered_locally[0]
+ original_proven = locally_proven[0]
try:
scoped = _compute(str(snapshot))
finally:
+ locally_proven[0] = original_proven
answered_from[0] = original_source
# Restored too: this is a nested lookup, not the outer answer, and
# leaving it set would suppress the merge that reads it.
@@ -2077,6 +2167,16 @@ async def get_gguf_variants_answer(
ready = [v for v in response.variants if v.downloaded and not v.partial]
best = pick_best_gguf(_default_variant_candidates(ready or response.variants))
response.default_variant = gguf_variant_key(best) if best else None
+ if response.dependencies_resolved and locally_proven[0] is not None:
+ rows = frozenset(
+ (v.quant.lower(), v.filename)
+ for v in response.variants
+ if v.downloaded and v.quant and v.filename
+ )
+ if rows != locally_proven[0] or any(
+ v.partial for v in response.variants if v.downloaded
+ ):
+ response = response.model_copy(update = {"dependencies_resolved": False})
if skip or answered_locally[0]:
return response
return _mark_empty_dir_cleanables(
diff --git a/studio/backend/hub/utils/hf_tokens.py b/studio/backend/hub/utils/hf_tokens.py
index 9abc5f9d570..dcd36467e84 100644
--- a/studio/backend/hub/utils/hf_tokens.py
+++ b/studio/backend/hub/utils/hf_tokens.py
@@ -1042,6 +1042,15 @@ HUB_TOKEN_REJECTED_WARNING = (
"model was read without it. Update or clear the token in Settings to keep access to "
"gated and private models."
)
+
+
+def hub_refused_cached_copy_warning(repo_id: str) -> str:
+ return (
+ f"Hugging Face refused {repo_id}, so Studio is running the copy already downloaded on "
+ "this machine. It will not receive updates until access is restored."
+ )
+
+
HUB_TOKEN_REJECTED_ERROR = (
"Hugging Face rejected the saved token (HTTP 401); it may be expired or revoked. "
"Update or clear it in Settings, then try again."
@@ -1051,9 +1060,11 @@ HUB_TOKEN_REJECTED_ERROR = (
class HubTokenRejections:
"""What one request learned about its credential. Shared by the threads it hands off to."""
- __slots__ = ("recovered", "refused", "_rejected", "_recovered")
+ __slots__ = ("recovered", "refused", "served_from_cache", "_rejected", "_recovered")
def __init__(self) -> None:
+ # Repos the Hub refused that this request loaded from their downloaded copy instead.
+ self.served_from_cache: "list[str]" = []
self.recovered = False
self.refused = False
# Digests, never tokens: a traceback or debugger can print this.
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index f6a6ed12180..2113471124e 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -88,6 +88,7 @@ from hub.utils.hf_tokens import (
HfTokenArg,
call_hub_with_anonymous_retry,
collecting_hub_token_rejections,
+ hub_refused_cached_copy_warning,
)
from hub.services.models.ollama import (
acquire_ollama_model_ref,
@@ -16147,15 +16148,56 @@ def _cancel_scoped_load_attempt(
return attempt, is_running
+def _hub_access_warnings(token_rejections) -> list[str]:
+ """What this request's Hub reads tell the user: a refused token, a refused repo's copy."""
+ warnings = [HUB_TOKEN_REJECTED_WARNING] if token_rejections.recovered else []
+ warnings += [
+ hub_refused_cached_copy_warning(repo)
+ for repo in dict.fromkeys(token_rejections.served_from_cache)
+ ]
+ return warnings
+
+
def _with_token_rejected_warning(response, token_rejections):
- """Tell the user the model loaded without their token, which Hugging Face refused."""
- if not token_rejections.recovered or not isinstance(response, LoadResponse):
+ """Tell the user the model loaded without their token, or from a copy the Hub now refuses."""
+ warnings = _hub_access_warnings(token_rejections)
+ if not warnings or not isinstance(response, LoadResponse):
return response
existing = response.memory_warning
- warning = f"{existing} {HUB_TOKEN_REJECTED_WARNING}" if existing else HUB_TOKEN_REJECTED_WARNING
+ warning = " ".join(([existing] if existing else []) + warnings)
return response.model_copy(update = {"memory_warning": warning})
+def _remember_hub_access_warning(response, token_rejections) -> None:
+ """Keep a GGUF load's Hub notice for /status, whose warning the client re-shows after a load."""
+ if isinstance(response, LoadResponse) and response.is_gguf:
+ warnings = _hub_access_warnings(token_rejections)
+ get_llama_cpp_backend().hub_access_warning = " ".join(warnings) or None
+
+
+def _status_load_warning(llama_backend) -> Optional[str]:
+ """The running GGUF's load warning as its load response carried it."""
+ notices = (llama_backend.last_load_warning, getattr(llama_backend, "hub_access_warning", None))
+ return " ".join(notice for notice in notices if notice) or None
+
+
+# True only in the user's /load, the one that shows the warning; background loads stay refused.
+_load_warnings_reach_user: contextvars.ContextVar[bool] = contextvars.ContextVar(
+ "load_warnings_reach_user", default = False
+)
+
+
+def _owner_session(fastapi_request) -> bool:
+ """The machine owner's own UI session: not a managed account and no API key of any kind.
+
+ _request_has_api_key, not _request_used_api_key: the latter excludes Unsloth's internal
+ workflow keys for API monitoring, and a data-recipe subprocess holds one of those.
+ """
+ if fastapi_request is None or account_access.managed_account():
+ return False
+ return not _request_has_api_key(fastapi_request)
+
+
async def _run_tracked_load_model_impl(
request: LoadRequest,
fastapi_request: Request,
@@ -16174,16 +16216,22 @@ async def _run_tracked_load_model_impl(
try:
if attempt.cancel_event.is_set():
raise HTTPException(status_code = 409, detail = "Model load cancelled")
- with collecting_hub_token_rejections() as token_rejections:
- response = await _load_model_impl(
- request,
- fastapi_request,
- current_subject,
- current_request_counted = current_request_counted,
- on_reload_confirmed = on_reload_confirmed,
- load_cancel_event = attempt.cancel_event,
- )
- return _with_token_rejected_warning(response, token_rejections)
+ warnings_token = _load_warnings_reach_user.set(True)
+ try:
+ with collecting_hub_token_rejections() as token_rejections:
+ response = await _load_model_impl(
+ request,
+ fastapi_request,
+ current_subject,
+ current_request_counted = current_request_counted,
+ on_reload_confirmed = on_reload_confirmed,
+ load_cancel_event = attempt.cancel_event,
+ )
+ finally:
+ _load_warnings_reach_user.reset(warnings_token)
+ response = _with_token_rejected_warning(response, token_rejections)
+ _remember_hub_access_warning(response, token_rejections)
+ return response
finally:
if attempt.cancel_event.is_set() and not attempt.cancel_complete.is_set():
if not await asyncio.to_thread(
@@ -16907,17 +16955,21 @@ async def _load_model_impl(
chat_template = _chat_template,
)
+ _caller_is_owner = _owner_session(fastapi_request) and _load_warnings_reach_user.get()
+
# is_lora auto-detected from adapter_config.json on disk/HF.
# Probe wrap so offline loads skip 30-60s of soft-failed network checks before
# the worker starts. Off-loop: the guard can spend seconds on DNS plus a HEAD and
# its TCP fallback, and this handler is awaited directly by the route, so running
# it inline would stall every unrelated request. Same shape as /validate.
+
def _resolve_config():
with _hf_offline_if_unreachable_for(model_identifier):
return ModelConfig.from_identifier(
model_id = model_identifier,
hf_token = request.hf_token,
gguf_variant = request.gguf_variant,
+ owner_session = _caller_is_owner,
# A native grant covers one directory, and this is the first
# pass that touches a drafter candidate, so the boundary has
# to travel with it rather than being applied afterwards.
@@ -17108,16 +17160,20 @@ async def _load_model_impl(
# Mark the load and refuse one the download manager already owns BEFORE the eviction below: this 409 leaves nothing
# loaded. It runs after argument inheritance, since a carried --no-mmproj changes the companion requirement.
- if config.is_gguf and config.gguf_hf_repo:
+ # A refused repo's downloaded copy loads as a file, from that repo's cache all the same.
+ interlock_repo = config.is_gguf and (
+ config.gguf_hf_repo or getattr(config, "gguf_cache_repo", None)
+ )
+ if interlock_repo:
from core.inference.llama_cpp import gguf_load_in_flight
- gguf_load_stack.enter_context(gguf_load_in_flight(config.gguf_hf_repo))
+ gguf_load_stack.enter_context(gguf_load_in_flight(interlock_repo))
from core.inference.llama_cpp import _hub_download_blocks_gguf_load
if await asyncio.to_thread(
_hub_download_blocks_gguf_load,
- config.gguf_hf_repo,
+ interlock_repo,
config.gguf_variant,
# Same predicate as the marker's own check, and as the loader's
# download gate: the projector is fetched whenever the repo ships one
@@ -17999,12 +18055,15 @@ async def validate_model(
# /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
# from_identifier builds the detection registry (transformers, or the warm's lock).
+ _caller_is_owner = _owner_session(fastapi_request)
+
def _resolve_config():
with _hf_offline_if_unreachable_for(model_identifier):
return ModelConfig.from_identifier(
model_id = model_identifier,
hf_token = request.hf_token,
gguf_variant = request.gguf_variant,
+ owner_session = _caller_is_owner,
# A native grant covers one directory, and this is the first
# pass that touches a drafter candidate, so the boundary has
# to travel with it rather than being applied afterwards.
@@ -18320,10 +18379,8 @@ async def validate_model(
return restore_inventory_handles(
ValidateModelResponse(
valid = True,
- message = (
- f"Model identifier is valid. {HUB_TOKEN_REJECTED_WARNING}"
- if token_rejections.recovered
- else "Model identifier is valid."
+ message = " ".join(
+ ["Model identifier is valid."] + _hub_access_warnings(token_rejections)
),
identifier = model_log_label if native_grant_backed else config.identifier,
resident = await asyncio.to_thread(
@@ -20129,7 +20186,7 @@ async def get_status(current_subject: str):
llama_backend, _native_grant_backed, _model_id
),
gguf_variant = llama_backend.hf_variant,
- memory_warning = llama_backend.last_load_warning,
+ memory_warning = _status_load_warning(llama_backend),
loading = _loading,
# Plus anything the Unsloth registry still holds: the GGUF load
# only unloaded the ACTIVE one, so a model cached behind it is
diff --git a/studio/backend/tests/test_gguf_hub_unreadable.py b/studio/backend/tests/test_gguf_hub_unreadable.py
index 4574b888783..64c1098db71 100644
--- a/studio/backend/tests/test_gguf_hub_unreadable.py
+++ b/studio/backend/tests/test_gguf_hub_unreadable.py
@@ -104,13 +104,28 @@ def test_hub_401_on_gguf_repo_raises_clear_error(monkeypatch):
assert isinstance(exc_info.value, ValueError)
-def test_hub_401_is_not_served_from_a_stale_cache(monkeypatch, _isolated):
+ "hf_token",
+ [None, False, "hf_" + "k" * 34],
+ ids = ["no_token", "anonymous", "explicit_token"],
+)
+def test_hub_401_is_not_served_from_a_stale_cache(monkeypatch, _isolated, hf_token):
+ # Not the owner's own session (an API key or another account): the cached copy stays
+ # refused. The owner's session case lives in test_gguf_refused_cached_load.py.
_cache(_isolated, REPO, GGUF)
monkeypatch.setattr(
huggingface_hub, "model_info", _hub(RepositoryNotFoundError("401 Client Error"))
)
+ monkeypatch.setattr(
+ llama_cpp, "cached_gguf_for_load", lambda repo, variant, **kwargs: str(_isolated / GGUF)
+ )
+ monkeypatch.setattr(
+ hf_tokens,
+ "_explicit_token_reaches_repo",
+ lambda repo, token, repo_type, offline = False: False,
+ )
with pytest.raises(GgufRepoUnreadableError):
- ModelConfig.from_identifier(REPO)
+ ModelConfig.from_identifier(REPO, hf_token = hf_token)
def test_repeated_timeouts_on_uncached_gguf_repo_raise_clear_error(monkeypatch):
diff --git a/studio/backend/tests/test_gguf_refused_cached_load.py b/studio/backend/tests/test_gguf_refused_cached_load.py
new file mode 100644
index 00000000000..f6a1ea3759a
--- /dev/null
+++ b/studio/backend/tests/test_gguf_refused_cached_load.py
@@ -0,0 +1,575 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""A GGUF the owner already downloaded still runs when the Hub refuses its repo.
+
+A repo that was deleted, made private or gated after the download answers 401/403/404 to every
+listing, and #12117 made that a clear error instead of a Transformers misroute. The machine
+owner's own session may still run the complete copy on its disk, with a warning; anyone the
+cache rules would refuse (anonymous, an API key without a token, another account, a token the
+Hub says cannot reach the repo) is refused exactly as before.
+"""
+
+from pathlib import Path
+from types import SimpleNamespace
+
+import huggingface_hub
+import pytest
+
+import core.inference.llama_cpp as llama_cpp
+import hub.utils.hf_tokens as hf_tokens
+import utils.hf_cache_settings as hf_cache_settings
+import utils.models.model_config as mc
+from hub.utils.hf_tokens import (
+ AmbientAuthorizedToken,
+ collecting_hub_token_rejections,
+ hub_refused_cached_copy_warning,
+)
+from utils.models.model_config import GgufRepoUnreadableError, ModelConfig
+
+REPO = "unsloth/Qwen3-0.6B-GGUF"
+VARIANT = "UD-Q4_K_XL"
+GGUF = f"Qwen3-0.6B-{VARIANT}.gguf"
+REV = "a" * 40
+
+
+class RepositoryNotFoundError(Exception):
+ """Matched by type name, as detect_gguf_model_remote does."""
+
+ def __init__(
+ self,
+ message,
+ status_code = 401,
+ ):
+ super().__init__(message)
+ self.response = SimpleNamespace(status_code = status_code, headers = {})
+
+
+class GatedRepoError(RepositoryNotFoundError):
+ pass
+
+
[email protected](autouse = True)
+def _isolated(tmp_path, monkeypatch):
+ monkeypatch.delenv("HF_HUB_OFFLINE", raising = False)
+ monkeypatch.delenv("TRANSFORMERS_OFFLINE", raising = False)
+ monkeypatch.setattr(
+ hf_cache_settings, "get_hf_cache_paths", lambda: SimpleNamespace(hub_cache = tmp_path)
+ )
+ monkeypatch.setattr(mc.time, "sleep", lambda *_: None)
+ monkeypatch.setattr(hf_tokens, "_ambient_hf_token", lambda: (True, None))
+ monkeypatch.setattr(
+ llama_cpp.LlamaCppBackend,
+ "_find_llama_server_binary",
+ staticmethod(lambda *, include_denied = False: "/fake/llama-server"),
+ )
+ monkeypatch.setattr(mc, "is_vision_model", lambda *a, **k: False)
+ monkeypatch.setattr(mc, "detect_audio_type", lambda *a, **k: None)
+ monkeypatch.setattr(mc, "is_model_cached", lambda *a, **k: False)
+ # Only this test's cache: no copies remembered from caches the host used before.
+ import hub.utils.gguf_sources as gguf_sources
+
+ monkeypatch.setattr(gguf_sources, "gguf_cache_snapshots", lambda repo: [])
+ from collections import OrderedDict
+
+ from hub.services.models import gguf_variants
+
+ monkeypatch.setattr(gguf_variants, "_VARIANT_REQUIREMENT_LAST_KNOWN", OrderedDict())
+ monkeypatch.setattr(gguf_variants, "_VARIANT_REQUIREMENT_FORGOTTEN", False)
+ return tmp_path
+
+
+def _snapshot(root: Path) -> Path:
+ snapshot = root / f"models--{REPO.replace('/', '--')}" / "snapshots" / REV
+ snapshot.mkdir(parents = True, exist_ok = True)
+ refs = snapshot.parent.parent / "refs"
+ refs.mkdir(exist_ok = True)
+ (refs / "main").write_text(REV)
+ return snapshot
+
+
+def _download(root: Path, *names: str) -> Path:
+ snapshot = _snapshot(root)
+ for name in names:
+ path = snapshot / name
+ path.parent.mkdir(parents = True, exist_ok = True)
+ path.write_bytes(b"GGUF" + b"\0" * 64)
+ return snapshot
+
+
+def _hub(behaviour):
+ def model_info(repo_id, **kwargs):
+ if isinstance(behaviour, BaseException):
+ raise behaviour
+ return SimpleNamespace(siblings = [SimpleNamespace(rfilename = f) for f in behaviour])
+
+ return model_info
+
+
+def _refuse(monkeypatch, error = None):
+ monkeypatch.setattr(
+ huggingface_hub,
+ "model_info",
+ _hub(error if error is not None else RepositoryNotFoundError("401 Client Error")),
+ )
+
+
+def _load(**kwargs):
+ with collecting_hub_token_rejections() as rejections:
+ config = ModelConfig.from_identifier(REPO, **kwargs)
+ return config, rejections
+
+
+ "error",
+ [
+ RepositoryNotFoundError("401 Client Error"),
+ RepositoryNotFoundError("404 Client Error", status_code = 404),
+ GatedRepoError("403 Client Error", status_code = 403),
+ ],
+ ids = ["401", "404", "gated"],
+)
[email protected]("variant", [VARIANT, None], ids = ["variant", "auto"])
+def test_owner_runs_the_downloaded_copy_when_the_hub_refuses(
+ monkeypatch, _isolated, error, variant
+):
+ snapshot = _download(_isolated, GGUF)
+ _refuse(monkeypatch, error)
+ config, rejections = _load(gguf_variant = variant, owner_session = True)
+ assert config.is_gguf
+ assert config.gguf_hf_repo is None, "must not go back to the Hub for the weights"
+ assert Path(config.gguf_file) == snapshot / GGUF
+ assert config.identifier == REPO
+ assert config.gguf_variant == VARIANT
+ assert rejections.served_from_cache == [REPO]
+
+
+ "token",
+ [None, AmbientAuthorizedToken("hf_" + "u" * 34)],
+ ids = ["ambient", "ui_saved_token"],
+)
+def test_the_owner_session_is_authorized_with_or_without_a_saved_token(
+ monkeypatch, _isolated, token
+):
+ _download(_isolated, GGUF)
+ _refuse(monkeypatch)
+ config, _ = _load(hf_token = token, gguf_variant = VARIANT, owner_session = True)
+ assert config.is_gguf and config.gguf_file
+
+
+def test_the_warning_names_the_repo():
+ warning = hub_refused_cached_copy_warning(REPO)
+ assert REPO in warning and "downloaded" in warning and "updates" in warning
+
+
+def test_a_split_copy_missing_a_shard_is_refused(monkeypatch, _isolated):
+ _download(_isolated, f"{VARIANT}/Qwen3-0.6B-{VARIANT}-00001-of-00002.gguf")
+ _refuse(monkeypatch)
+ with pytest.raises(GgufRepoUnreadableError):
+ _load(gguf_variant = VARIANT, owner_session = True)
+
+
+def test_a_copy_its_manifest_calls_incomplete_is_refused(monkeypatch, _isolated):
+ # The download recorded a projector the variant needs, and it never arrived.
+ _download(_isolated, GGUF)
+ import hub.utils.gguf_sources as gguf_sources
+
+ monkeypatch.setattr(
+ gguf_sources, "cached_gguf_manifest_complete", lambda repo, quant, snapshot: False
+ )
+ _refuse(monkeypatch)
+ with pytest.raises(GgufRepoUnreadableError):
+ _load(gguf_variant = VARIANT, owner_session = True)
+
+
+def test_only_a_projector_on_disk_is_refused(monkeypatch, _isolated):
+ _download(_isolated, "mmproj-F16.gguf")
+ _refuse(monkeypatch)
+ with pytest.raises(GgufRepoUnreadableError):
+ _load(owner_session = True)
+
+
+ "token",
+ [False, None, "hf_" + "k" * 34],
+ ids = ["anonymous", "api_key_without_token", "api_key_with_token"],
+)
+def test_callers_the_cache_rules_refuse_stay_refused(monkeypatch, _isolated, token):
+ # owner_session=False: an sk-unsloth API key or a managed account. No token there is
+ # anonymous, not the installation's; an explicit token must reach the repo, which the
+ # Hub just refused.
+ _download(_isolated, GGUF)
+ _refuse(monkeypatch)
+ monkeypatch.setattr(
+ hf_tokens,
+ "_explicit_token_reaches_repo",
+ lambda repo, token, repo_type, offline = False: False,
+ )
+ with pytest.raises(GgufRepoUnreadableError):
+ _load(hf_token = token, gguf_variant = VARIANT)
+
+
+ "verdict", [True, None], ids = ["cached_auth_check_yes", "probe_cannot_answer"]
+)
+def test_a_token_the_hub_just_refused_is_not_outranked_by_the_cache_rule(
+ monkeypatch, _isolated, verdict
+):
+ # The listing refused this very token. A /auth-check "yes" still in its cache, or a probe
+ # that times out on a host whose only credential downloaded the repo, must not let an API
+ # key or another account read the downloaded copy.
+ _download(_isolated, GGUF)
+ _refuse(monkeypatch, GatedRepoError("403 Client Error", status_code = 403))
+ monkeypatch.setattr(
+ hf_tokens,
+ "_explicit_token_reaches_repo",
+ lambda repo, token, repo_type, offline = False: verdict,
+ )
+ # This token downloaded the copy, so an unanswerable probe would otherwise be settled by it.
+ monkeypatch.setattr(hf_tokens, "_caller_populated_the_cache", lambda *a, **k: True)
+ monkeypatch.setattr(hf_tokens, "_repo_present_on_disk", lambda *a, **k: True)
+ for _ in range(2):
+ with pytest.raises(GgufRepoUnreadableError):
+ _load(hf_token = "hf_" + "k" * 34, gguf_variant = VARIANT, owner_session = False)
+
+
+def test_a_revoked_grant_is_refused_even_for_a_managed_accounts_token(monkeypatch, _isolated):
+ # A managed account's own token whose access the Hub has withdrawn: the cache is another
+ # person's download, and /auth-check says this token no longer reaches the repo.
+ _download(_isolated, GGUF)
+ _refuse(monkeypatch)
+ monkeypatch.setattr(
+ hf_tokens,
+ "_explicit_token_reaches_repo",
+ lambda repo, token, repo_type, offline = False: False,
+ )
+ with pytest.raises(GgufRepoUnreadableError):
+ _load(hf_token = "hf_" + "m" * 34, gguf_variant = VARIANT, owner_session = False)
+
+
+def test_timeouts_keep_todays_cache_route(monkeypatch, _isolated):
+ _download(_isolated, GGUF)
+ monkeypatch.setattr(huggingface_hub, "model_info", _hub(TimeoutError("read timed out")))
+ monkeypatch.setattr(
+ mc,
+ "list_gguf_variants",
+ lambda identifier, hf_token = None: (
+ [mc.GgufVariantInfo(filename = GGUF, quant = VARIANT, size_bytes = 1)],
+ False,
+ ),
+ )
+ config, rejections = _load(gguf_variant = VARIANT, owner_session = True)
+ assert config.is_gguf and config.gguf_hf_repo == REPO
+ assert rejections.served_from_cache == []
+
+
+def test_a_healthy_hub_is_unchanged(monkeypatch, _isolated):
+ _download(_isolated, GGUF)
+ monkeypatch.setattr(huggingface_hub, "model_info", _hub([GGUF, "README.md"]))
+ monkeypatch.setattr(
+ mc,
+ "list_gguf_variants",
+ lambda identifier, hf_token = None: (
+ [mc.GgufVariantInfo(filename = GGUF, quant = VARIANT, size_bytes = 1)],
+ False,
+ ),
+ )
+ config, rejections = _load(gguf_variant = VARIANT, owner_session = True)
+ assert config.is_gguf and config.gguf_hf_repo == REPO
+ assert rejections.served_from_cache == []
+
+
+def test_an_uncached_refused_repo_still_raises_the_clear_error(monkeypatch, _isolated):
+ _refuse(monkeypatch)
+ with pytest.raises(GgufRepoUnreadableError, match = "HTTP 401"):
+ _load(gguf_variant = VARIANT, owner_session = True)
+
+
+def test_the_load_response_carries_the_cached_copy_warning():
+ from models.inference import LoadResponse
+ from routes.inference import _with_token_rejected_warning
+
+ response = LoadResponse(status = "loaded", model = REPO, display_name = REPO, inference = {})
+ with collecting_hub_token_rejections() as rejections:
+ assert _with_token_rejected_warning(response, rejections) is response
+ rejections.served_from_cache += [REPO, REPO]
+ warned = _with_token_rejected_warning(response, rejections)
+ assert warned.memory_warning == hub_refused_cached_copy_warning(REPO)
+
+
+ "managed,api_key,expected",
+ [(False, False, True), (False, True, False), (True, False, False)],
+ ids = ["owner_ui", "api_key", "managed_account"],
+)
+def test_only_the_owners_own_session_counts_as_the_owner(monkeypatch, managed, api_key, expected):
+ import routes.inference as inference
+
+ monkeypatch.setattr(inference.account_access, "managed_account", lambda: managed)
+ monkeypatch.setattr(inference, "_request_has_api_key", lambda request: api_key)
+ assert inference._owner_session(object()) is expected
+ assert inference._owner_session(None) is False
+
+
+def test_an_internal_workflow_key_is_not_the_owner(monkeypatch):
+ # A data-recipe subprocess holds an internal sk-unsloth key: never the owner's session.
+ import routes.inference as inference
+
+ monkeypatch.setattr(inference.account_access, "managed_account", lambda: False)
+ monkeypatch.setattr(inference, "_request_api_key_token", lambda request: "sk-unsloth-internal")
+ monkeypatch.setattr(inference.auth_storage, "is_internal_api_key", lambda token: True)
+ assert inference._request_used_api_key(object()) is False
+ assert inference._owner_session(object()) is False
+
+
+def test_a_cancelled_download_is_not_run_when_the_hub_refuses(monkeypatch, _isolated):
+ # Its main file is on disk, but the download was cancelled: not a complete copy.
+ _download(_isolated, GGUF)
+ import hub.utils.gguf_sources as gguf_sources
+
+ monkeypatch.setattr(
+ gguf_sources, "cached_gguf_source_partial", lambda repo, quant, snapshot: True
+ )
+ _refuse(monkeypatch)
+ with pytest.raises(GgufRepoUnreadableError):
+ _load(gguf_variant = VARIANT, owner_session = True)
+
+
+def test_auto_selection_falls_back_to_the_next_complete_variant(monkeypatch, _isolated):
+ # The preferred UD-Q4_K_XL was interrupted after its first shard; Q8_0 is complete.
+ snapshot = _download(
+ _isolated,
+ f"{VARIANT}/Qwen3-0.6B-{VARIANT}-00001-of-00002.gguf",
+ "Qwen3-0.6B-Q8_0.gguf",
+ )
+ _refuse(monkeypatch)
+ config, rejections = _load(owner_session = True)
+ assert Path(config.gguf_file) == snapshot / "Qwen3-0.6B-Q8_0.gguf"
+ assert config.gguf_variant == "Q8_0"
+ assert rejections.served_from_cache == [REPO]
+
+
+def test_the_refusal_fallback_passes_the_snapshot_root_as_the_companion_root(
+ monkeypatch, _isolated
+):
+ # A main file in a non-quant subdirectory still finds a repo-root projector or drafter.
+ monkeypatch.setattr(
+ hf_cache_settings,
+ "get_hf_cache_paths",
+ lambda: SimpleNamespace(hub_cache = _isolated, source = "environment"),
+ )
+ snapshot = _download(_isolated, f"distilled/Qwen3-0.6B-{VARIANT}.gguf")
+ _refuse(monkeypatch)
+ seen = []
+ real = ModelConfig.from_identifier.__func__
+
+ def spy(cls, model_id, *args, **kwargs):
+ if model_id != REPO:
+ seen.append(kwargs.get("gguf_companion_roots"))
+ return real(cls, model_id, *args, **kwargs)
+
+ monkeypatch.setattr(ModelConfig, "from_identifier", classmethod(spy))
+ config, _ = _load(owner_session = True)
+ assert config.is_gguf
+ assert seen == [(str(snapshot),)]
+
+
+def test_a_repo_not_named_gguf_still_runs_its_downloaded_gguf(monkeypatch, _isolated):
+ # _looks_like_gguf_repo says no for this name, yet a healthy Hub would have found the GGUF.
+ monkeypatch.setattr(mc, "_looks_like_gguf_repo", lambda *a, **k: False)
+ snapshot = _download(_isolated, GGUF)
+ _refuse(monkeypatch)
+ config, rejections = _load(gguf_variant = VARIANT, owner_session = True)
+ assert Path(config.gguf_file) == snapshot / GGUF
+ assert rejections.served_from_cache == [REPO]
+
+
+def test_auto_selection_finds_a_complete_variant_in_an_older_snapshot(monkeypatch, _isolated):
+ # The newest snapshot holds only an interrupted UD-Q4_K_XL; an older one a complete Q8_0.
+ import os
+
+ older = _download(_isolated, "Qwen3-0.6B-Q8_0.gguf")
+ newer = older.parent / ("b" * 40)
+ (newer / VARIANT).mkdir(parents = True)
+ (newer / VARIANT / f"Qwen3-0.6B-{VARIANT}-00001-of-00002.gguf").write_bytes(
+ b"GGUF" + b"\0" * 64
+ )
+ (older.parent.parent / "refs" / "main").write_text("b" * 40)
+ os.utime(older, (1_000_000_000, 1_000_000_000))
+ _refuse(monkeypatch)
+ config, rejections = _load(owner_session = True)
+ assert Path(config.gguf_file) == older / "Qwen3-0.6B-Q8_0.gguf"
+ assert config.gguf_variant == "Q8_0"
+ assert rejections.served_from_cache == [REPO]
+
+
+def test_the_downloaded_copy_keeps_its_repo_for_the_download_interlock(monkeypatch, _isolated):
+ # Not gguf_hf_repo (that would fetch from the Hub), but /load's marker and 409 need the repo.
+ _download(_isolated, GGUF)
+ _refuse(monkeypatch)
+ config, _ = _load(gguf_variant = VARIANT, owner_session = True)
+ assert config.gguf_hf_repo is None
+ assert config.gguf_cache_repo == REPO
+
+
+def test_a_missing_llama_server_fails_before_the_cached_copy_is_returned(monkeypatch, _isolated):
+ # /load must not unload the resident model for a launch that cannot start.
+ _download(_isolated, GGUF)
+ _refuse(monkeypatch)
+ monkeypatch.setattr(
+ llama_cpp.LlamaCppBackend,
+ "_find_llama_server_binary",
+ staticmethod(lambda *, include_denied = False: None),
+ )
+ with pytest.raises(llama_cpp.LlamaServerNotFoundError):
+ _load(gguf_variant = VARIANT, owner_session = True)
+
+
[email protected]("listed", ["root_first", "subdir_first"])
+def test_auto_selection_prefers_the_root_checkpoint_whatever_the_listing_order(
+ monkeypatch, _isolated, listed
+):
+ # As the healthy-Hub pick: the bare repo id is the root checkpoint, not distilled/.
+ root, sub = "Qwen3-0.6B-Q6_K.gguf", "distilled/Qwen3-0.6B-Q6_K.gguf"
+ snapshot = _download(_isolated, root, sub)
+ order = [root, sub] if listed == "root_first" else [sub, root]
+ monkeypatch.setattr(mc, "_hf_cache_main_gguf_files", lambda repo, **k: list(order))
+ _refuse(monkeypatch)
+ config, _ = _load(owner_session = True)
+ assert Path(config.gguf_file) == snapshot / root
+
+
+def test_auto_selection_finds_a_copy_in_a_remembered_cache(
+ monkeypatch, _isolated, tmp_path_factory
+):
+ # The active cache was switched to an empty one; the explicit-variant lookup still finds the
+ # remembered copy, so automatic selection must too.
+ import hub.utils.gguf_sources as gguf_sources
+
+ remembered = _download(tmp_path_factory.mktemp("previous_cache"), GGUF)
+ monkeypatch.setattr(
+ gguf_sources,
+ "gguf_cache_snapshots",
+ lambda repo: [remembered] if repo == REPO else [],
+ )
+ _refuse(monkeypatch)
+ config, _ = _load(owner_session = True)
+ assert Path(config.gguf_file) == remembered / GGUF
+ assert config.gguf_variant == VARIANT
+
+
+def test_the_downloaded_copy_is_reported_as_a_hub_model(monkeypatch, _isolated):
+ # Not the user's own file: /load reports is_local_model from this, and the chat settings
+ # then give Hub recovery guidance rather than "put the drafter beside your file".
+ _download(_isolated, GGUF)
+ _refuse(monkeypatch)
+ config, _ = _load(gguf_variant = VARIANT, owner_session = True)
+ assert config.is_local is False
+
+
[email protected]("projector_on_disk", [False, True])
+def test_a_companion_an_earlier_listing_named_must_be_on_disk(
+ monkeypatch, _isolated, projector_on_disk
+):
+ # No manifest, so the shards alone look complete; the live listing said it needs a projector.
+ from hub.services.models import gguf_variants
+ from hub.utils import download_manifest
+
+ snapshot = _download(_isolated, GGUF)
+ if projector_on_disk:
+ (snapshot / "mmproj-F16.gguf").write_bytes(b"GGUF" + b"\0" * 60)
+ requirement = SimpleNamespace(
+ expected_files = (
+ download_manifest.ExpectedFile(GGUF, (snapshot / GGUF).stat().st_size),
+ download_manifest.ExpectedFile("mmproj-F16.gguf", 64),
+ )
+ )
+ gguf_variants._variant_requirement_cache_set_many(REPO, None, {VARIANT: requirement})
+ _refuse(monkeypatch)
+ for variant in (VARIANT, None):
+ if projector_on_disk:
+ config, _ = _load(gguf_variant = variant, owner_session = True)
+ assert Path(config.gguf_file) == snapshot / GGUF
+ else:
+ with pytest.raises(GgufRepoUnreadableError):
+ _load(gguf_variant = variant, owner_session = True)
+
+
+def test_only_the_load_that_shows_the_warning_may_use_the_cached_copy(monkeypatch):
+ # Auto-switch, idle restore and preview call the impl directly and drop its response, so
+ # the warning would never be seen; only the /load wrapper turns the fallback on.
+ import asyncio
+
+ import routes.inference as inference
+
+ seen = []
+
+ async def impl(*args, **kwargs):
+ seen.append(inference._load_warnings_reach_user.get())
+ return None
+
+ monkeypatch.setattr(inference, "_load_model_impl", impl)
+ from models.inference import LoadRequest
+
+ request = LoadRequest(model_path = REPO)
+ asyncio.run(inference._run_tracked_load_model_impl(request, object(), "subject"))
+ assert seen == [True]
+ assert inference._load_warnings_reach_user.get() is False
+
+
[email protected]("status", [403, 404])
+def test_a_refusal_known_only_by_its_status_takes_the_refused_repo_policy(
+ monkeypatch, _isolated, status
+):
+ # DisabledRepoError or a bare HTTP 403: not retried into the ordinary cache route, where an
+ # API key would get the copy with no warning.
+ class DisabledRepoError(Exception):
+ def __init__(self):
+ super().__init__(f"{status} Client Error")
+ self.response = SimpleNamespace(status_code = status, headers = {})
+
+ _download(_isolated, GGUF)
+ _refuse(monkeypatch, DisabledRepoError())
+ config, rejections = _load(gguf_variant = VARIANT, owner_session = True)
+ assert rejections.served_from_cache == [REPO]
+ with pytest.raises(GgufRepoUnreadableError):
+ _load(hf_token = "hf_" + "k" * 34, gguf_variant = VARIANT, owner_session = False)
+
+
+def test_status_keeps_the_cached_copy_warning_the_load_carried(monkeypatch):
+ # The client re-applies /status after a load and shows its memory_warning, so a warning only
+ # on the load response is dismissed as soon as it appears.
+ import routes.inference as inference_routes
+ from models.inference import LoadResponse
+
+ backend = SimpleNamespace(last_load_warning = "Runs partly from disk.", hub_access_warning = None)
+ monkeypatch.setattr(inference_routes, "get_llama_cpp_backend", lambda: backend)
+ response = LoadResponse(
+ status = "loaded",
+ model = REPO,
+ display_name = REPO,
+ inference = {},
+ is_gguf = True,
+ memory_warning = backend.last_load_warning,
+ )
+ with collecting_hub_token_rejections() as rejections:
+ rejections.served_from_cache.append(REPO)
+ warned = inference_routes._with_token_rejected_warning(response, rejections)
+ inference_routes._remember_hub_access_warning(warned, rejections)
+ assert inference_routes._status_load_warning(backend) == warned.memory_warning
+ assert hub_refused_cached_copy_warning(REPO) in warned.memory_warning
+
+ # The next GGUF load that the Hub answers drops it.
+ with collecting_hub_token_rejections() as rejections:
+ inference_routes._remember_hub_access_warning(response, rejections)
+ assert inference_routes._status_load_warning(backend) == "Runs partly from disk."
+
+
+def test_a_new_load_forgets_the_previous_hub_warning():
+ backend = llama_cpp.LlamaCppBackend.__new__(llama_cpp.LlamaCppBackend)
+ backend._last_load_warning = None
+ backend._variant_fallback_warning = None
+ backend.hub_access_warning = "Hugging Face refused it."
+ backend._begin_load_warnings()
+ assert backend.hub_access_warning is None
diff --git a/studio/backend/tests/test_gguf_variants_local_dependencies.py b/studio/backend/tests/test_gguf_variants_local_dependencies.py
new file mode 100644
index 00000000000..9e23579775e
--- /dev/null
+++ b/studio/backend/tests/test_gguf_variants_local_dependencies.py
@@ -0,0 +1,267 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""A downloaded GGUF must stay a one-click On Device row when the Hub cannot be read.
+
+The picker collapses a repo holding one complete quant only when the variants answer says its
+dependencies are resolved. Only a live Hub listing used to say so, so with the Hub offline,
+unreachable or refusing the saved token, every downloaded sole-quant repo fell back to the
+expander. A Hub-less answer now proves it from disk: the quant's shards, its snapshot's own
+partial state, the download's recorded plan and any companion a Hub answer named earlier.
+With the Hub up a local-first answer still never claims it, since a companion the current
+revision added is only visible in the listing (#10243).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+
+from collections import OrderedDict
+
+import pytest
+
+from hub.services.models import gguf_variants
+from hub.utils import download_manifest, inventory_scan
+from utils import hf_cache_settings
+
+REPO = "org/Sole-GGUF"
+REV = "0123456789abcdef0123456789abcdef01234567"
+QUANT = "Q4_K_M"
+MAIN = f"Sole-{QUANT}.gguf"
+
+
+def _snapshot():
+ hub_cache = hf_cache_settings.get_hf_cache_paths().hub_cache
+ repo = hub_cache / "models--org--Sole-GGUF"
+ snapshot = repo / "snapshots" / REV
+ snapshot.mkdir(parents = True, exist_ok = True)
+ (repo / "refs").mkdir(exist_ok = True)
+ (repo / "refs" / "main").write_text(REV)
+ return repo, snapshot
+
+
+def _write(path, size: int = 256):
+ path.parent.mkdir(parents = True, exist_ok = True)
+ path.write_bytes(b"GGUF" + b"\0" * (size - 4))
+ return path
+
+
+def _record_plan(repo, files):
+ assert download_manifest.write_manifest(
+ "model",
+ REPO,
+ QUANT,
+ [download_manifest.ExpectedFile(name, size) for name, size in files],
+ hub_cache = repo.parent,
+ )
+
+
+def hub_calls(monkeypatch, tmp_path):
+ # A cache of this test's own: the suite-wide empty cache is shared across tests.
+ hub_cache = str(tmp_path / "hub")
+ monkeypatch.setitem(hf_cache_settings._EXPLICIT_CACHE_ENV, "HF_HUB_CACHE", hub_cache)
+ monkeypatch.setenv("HF_HUB_CACHE", hub_cache)
+ monkeypatch.setattr("huggingface_hub.constants.HF_HUB_CACHE", hub_cache)
+ calls = []
+
+ def refused(*args, **kwargs):
+ calls.append(args)
+ raise ConnectionError("hub unreachable")
+
+ monkeypatch.setattr(gguf_variants, "list_gguf_variants", refused)
+ monkeypatch.setattr(gguf_variants, "_gguf_all_variant_requirements", refused)
+ monkeypatch.setattr("huggingface_hub.model_info", refused)
+ monkeypatch.setattr("huggingface_hub.list_repo_files", refused)
+ inventory_scan.invalidate_hf_cache_scans()
+ monkeypatch.setattr(
+ gguf_variants, "_VARIANT_REQUIREMENT_LAST_KNOWN", OrderedDict(), raising = False
+ )
+ monkeypatch.setattr(gguf_variants, "_VARIANT_REQUIREMENT_FORGOTTEN", False, raising = False)
+ return calls
+
+
+def _answer(**kwargs):
+ inventory_scan.invalidate_hf_cache_scans()
+ return asyncio.run(gguf_variants.get_gguf_variants_response(REPO, **kwargs))
+
+
+# What the picker sends when it believes the Hub is offline, and a Hub that fails a request.
+HUBLESS = [
+ pytest.param({"prefer_local_cache": True, "offline": True}, id = "offline"),
+ pytest.param({}, id = "hub_failed"),
+]
+
+
[email protected]("request_kwargs", HUBLESS)
+def test_a_complete_download_is_resolved_without_the_hub(hub_calls, request_kwargs):
+ repo, snapshot = _snapshot()
+ _write(snapshot / MAIN)
+ _record_plan(repo, [(MAIN, 256)])
+
+ response = _answer(**request_kwargs)
+
+ assert [v.quant for v in response.variants] == [QUANT]
+ assert response.variants[0].downloaded is True
+ assert response.dependencies_resolved is True
+ if request_kwargs.get("offline"):
+ assert hub_calls == [], "an offline answer must not reach the Hub"
+
+
[email protected]("request_kwargs", HUBLESS)
+def test_a_download_from_before_manifests_is_judged_on_its_shards(hub_calls, request_kwargs):
+ _repo, snapshot = _snapshot()
+ _write(snapshot / MAIN)
+
+ assert _answer(**request_kwargs).dependencies_resolved is True
+
+
+def test_a_local_first_answer_with_the_hub_up_still_defers_to_the_listing(hub_calls):
+ """#10243: a companion the current revision added only shows in the Hub listing."""
+ repo, snapshot = _snapshot()
+ _write(snapshot / MAIN)
+ _record_plan(repo, [(MAIN, 256)])
+
+ response = _answer(prefer_local_cache = True)
+
+ assert response.variants[0].downloaded is True
+ assert response.dependencies_resolved is False
+
+
[email protected]("request_kwargs", HUBLESS)
+ "companion",
+ ["mmproj-F16.gguf", f"mtp-Sole-{QUANT}.gguf"],
+ ids = ["mmproj", "mtp_drafter"],
+)
+def test_a_planned_companion_that_is_missing_leaves_it_unresolved(
+ hub_calls, request_kwargs, companion
+):
+ repo, snapshot = _snapshot()
+ _write(snapshot / MAIN)
+ _record_plan(repo, [(MAIN, 256), (companion, 128)])
+
+ assert _answer(**request_kwargs).dependencies_resolved is False
+
+
[email protected]("request_kwargs", HUBLESS)
+def test_a_truncated_planned_file_leaves_it_unresolved(hub_calls, request_kwargs):
+ repo, snapshot = _snapshot()
+ _write(snapshot / MAIN, 200)
+ _record_plan(repo, [(MAIN, 256)])
+
+ assert _answer(**request_kwargs).dependencies_resolved is False
+
+
[email protected]("request_kwargs", HUBLESS)
+def test_a_split_quant_short_a_shard_leaves_it_unresolved(hub_calls, request_kwargs):
+ _repo, snapshot = _snapshot()
+ _write(snapshot / QUANT / f"Sole-{QUANT}-00001-of-00002.gguf")
+
+ response = _answer(**request_kwargs)
+
+ assert all(not v.downloaded for v in response.variants)
+ assert response.dependencies_resolved is False
+
+
[email protected]("request_kwargs", HUBLESS)
+def test_a_cancelled_download_leaves_it_unresolved(hub_calls, request_kwargs):
+ repo, snapshot = _snapshot()
+ _write(snapshot / MAIN)
+ _record_plan(repo, [(MAIN, 256)])
+ download_manifest.write_cancel_marker("model", REPO, QUANT, hub_cache = repo.parent)
+
+ assert _answer(**request_kwargs).dependencies_resolved is False
+
+
[email protected]("request_kwargs", HUBLESS)
[email protected]("drafter_on_disk", [False, True], ids = ["missing", "present"])
+def test_a_companion_the_hub_named_earlier_must_be_on_disk(
+ hub_calls, monkeypatch, request_kwargs, drafter_on_disk
+):
+ _repo, snapshot = _snapshot()
+ _write(snapshot / MAIN)
+ drafter = f"mtp-Sole-{QUANT}.gguf"
+ if drafter_on_disk:
+ _write(snapshot / drafter, 128)
+ requirement = SimpleNamespace(
+ expected_files = (
+ download_manifest.ExpectedFile(MAIN, 256),
+ download_manifest.ExpectedFile(drafter, 128),
+ )
+ )
+ monkeypatch.setattr(gguf_variants, "_variant_requirement_last_known", lambda key: requirement)
+
+ assert _answer(**request_kwargs).dependencies_resolved is drafter_on_disk
+
+
[email protected]("request_kwargs", HUBLESS)
+def test_a_requirement_past_its_refresh_ttl_still_counts_without_the_hub(hub_calls, request_kwargs):
+ _repo, snapshot = _snapshot()
+ _write(snapshot / MAIN)
+ drafter = f"mtp-Sole-{QUANT}.gguf"
+ requirement = SimpleNamespace(
+ expected_files = (
+ download_manifest.ExpectedFile(MAIN, 256),
+ download_manifest.ExpectedFile(drafter, 128),
+ )
+ )
+ gguf_variants._variant_requirement_cache_set_many("org/Sole-GGUF", None, {QUANT: requirement})
+ # The live listing's entry expires; what it said the variant needs does not.
+ gguf_variants._VARIANT_REQUIREMENT_CACHE.clear()
+ assert _answer(**request_kwargs).dependencies_resolved is False
+
+
+def test_a_live_listing_still_resolves_dependencies(hub_calls, monkeypatch):
+ _repo, snapshot = _snapshot()
+ _write(snapshot / MAIN)
+ info = SimpleNamespace(filename = MAIN, quant = QUANT, display_label = None, size_bytes = 256)
+ sibling = SimpleNamespace(rfilename = MAIN, size = 256, blob_id = "b", lfs = None)
+ monkeypatch.setattr(
+ gguf_variants, "list_gguf_variants", lambda *a, **k: ([info], False, [sibling])
+ )
+ monkeypatch.setattr(gguf_variants, "_gguf_all_variant_requirements", lambda *a, **k: {})
+
+ assert _answer().dependencies_resolved is True
+
+
[email protected]("request_kwargs", HUBLESS)
+def test_a_requirement_learned_under_another_token_still_counts(hub_calls, request_kwargs):
+ # The listing that named the drafter ran with the old token; the owner has since replaced
+ # or cleared it. The drafter is still missing, so the copy is still not resolved.
+ _repo, snapshot = _snapshot()
+ _write(snapshot / MAIN)
+ requirement = SimpleNamespace(
+ expected_files = (
+ download_manifest.ExpectedFile(MAIN, 256),
+ download_manifest.ExpectedFile(f"mtp-Sole-{QUANT}.gguf", 128),
+ )
+ )
+ gguf_variants._variant_requirement_cache_set_many(REPO, "hf_" + "a" * 34, {QUANT: requirement})
+ gguf_variants._VARIANT_REQUIREMENT_CACHE.clear()
+ assert _answer(**request_kwargs).dependencies_resolved is False
+
+
[email protected]("request_kwargs", HUBLESS)
+def test_an_evicted_requirement_is_not_read_as_nothing_required(
+ hub_calls, monkeypatch, request_kwargs
+):
+ # A long session listed enough variants to push this one's requirement out. Its drafter may
+ # still be missing, so the copy stays unresolved rather than being called complete.
+ _repo, snapshot = _snapshot()
+ _write(snapshot / MAIN)
+ requirement = SimpleNamespace(
+ expected_files = (
+ download_manifest.ExpectedFile(MAIN, 256),
+ download_manifest.ExpectedFile(f"mtp-Sole-{QUANT}.gguf", 128),
+ )
+ )
+ for cap in ("_VARIANT_HASH_MAX", "_VARIANT_REQUIREMENT_LAST_KNOWN_MAX"):
+ monkeypatch.setattr(gguf_variants, cap, 2, raising = False)
+ gguf_variants._variant_requirement_cache_set_many(REPO, None, {QUANT: requirement})
+ gguf_variants._variant_requirement_cache_set_many(
+ "org/Other-GGUF", None, {"Q8_0": requirement, "Q6_K": requirement}
+ )
+ gguf_variants._VARIANT_REQUIREMENT_CACHE.clear()
+ assert _answer(**request_kwargs).dependencies_resolved is False
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index c993e64531f..23b4842aa2c 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -3,7 +3,7 @@
"""Model and LoRA configuration handling."""
-from dataclasses import dataclass
+from dataclasses import dataclass, replace as _dataclass_replace
from typing import Optional, Dict, Any
from utils.paths.storage_roots import own_entry, within_account
from utils.paths import (
@@ -30,6 +30,7 @@ from hub.utils.hf_tokens import (
call_with_anonymous_retry,
collecting_hub_token_rejections,
HUB_TOKEN_REJECTED_ERROR,
+ hf_token_arg,
is_rejected_credential_error,
is_anonymous,
normalize_token,
@@ -3300,7 +3301,21 @@ def _detect_gguf_from_hf_cache(repo_id: str) -> Optional[str]:
Excludes mmproj (vision projector) files so a partial cache holding only
the projector cannot route it as the main model.
"""
- for snap in _iter_hf_cache_snapshots(repo_id):
+ rel_files = _hf_cache_main_gguf_files(repo_id)
+ return _pick_best_gguf(rel_files) if rel_files else None
+
+
+def _hf_cache_main_gguf_files(repo_id: str, *, every_snapshot: bool = False) -> list[str]:
+ """Main GGUF paths of the first cached snapshot of *repo_id* that holds any, or with
+ *every_snapshot* of all of them (newest first, each path once), remembered caches included
+ as the strict load lookup includes them."""
+ found: list[str] = []
+ if every_snapshot:
+ from core.inference.llama_cpp import _cached_gguf_snapshots
+ snapshots = _cached_gguf_snapshots(repo_id)
+ else:
+ snapshots = _iter_hf_cache_snapshots(repo_id)
+ for snap in snapshots:
rel_files = []
for f in _iter_gguf_files(snap, recursive = True):
rel = f.relative_to(snap).as_posix()
@@ -3313,9 +3328,10 @@ def _detect_gguf_from_hf_cache(repo_id: str) -> Optional[str]:
):
continue
rel_files.append(rel)
- if rel_files:
- return _pick_best_gguf(rel_files)
- return None
+ if rel_files and not every_snapshot:
+ return rel_files
+ found += [rel for rel in rel_files if rel not in found]
+ return found
class GgufRepoUnreadableError(ValueError):
@@ -3383,6 +3399,100 @@ def _gguf_repo_unreadable_message(
)
+def _is_hub_refusal(error: Exception) -> bool:
+ """The Hub answered no (401/403/404, gated), as opposed to not answering at all."""
+ from hub.utils.hf_tokens import _is_probe_timeout
+
+ if _is_probe_timeout(error):
+ return False
+ if type(error).__name__ in ("RepositoryNotFoundError", "GatedRepoError"):
+ return True
+ status = getattr(getattr(error, "response", None), "status_code", None)
+ return status in (401, 403, 404)
+
+
+def _refused_repo_cache_token(hf_token: HfTokenArg, owner_session: bool) -> HfTokenArg:
+ """The credential class ``cache_reads_authorized`` judges a refused repo's cache read by.
+
+ The machine owner's UI session reads its own downloads (``AmbientAuthorizedToken`` or
+ ambient); anyone else is judged as they would be for any cache read, with "no token"
+ meaning anonymous rather than borrowing the installation's."""
+ if is_anonymous(hf_token):
+ return False
+ token = hf_token.strip() if isinstance(hf_token, str) else ""
+ return hf_token_arg(token, allow_ambient_token = owner_session)
+
+
+def _remembered_companions_present(repo_id: str, variant: str, local_file: str) -> bool:
+ """Whether every file an earlier live listing said *variant* needs is beside *local_file*.
+ A manifest-less download is otherwise judged by its shards alone."""
+ from core.inference.llama_cpp import _snapshot_dir_of
+ from hub.services.models import gguf_variants
+
+ requirement = gguf_variants._variant_requirement_last_known((repo_id.lower(), variant.lower()))
+ if requirement is None:
+ return not gguf_variants._variant_requirement_may_be_forgotten()
+ snapshot = _snapshot_dir_of(local_file)
+ if snapshot is None:
+ return False
+ try:
+ for expected in requirement.expected_files:
+ target = Path(snapshot) / expected.path
+ if not target.is_file() or (expected.size and target.stat().st_size != expected.size):
+ return False
+ except OSError:
+ return False
+ return True
+
+
+def _refused_repo_cached_gguf(
+ repo_id: str, gguf_variant: Optional[str], hf_token: HfTokenArg, *, owner_session: bool
+) -> Optional[tuple[str, str]]:
+ """``(main file, variant)`` of a complete downloaded copy this caller may run while the Hub
+ refuses the repo, or None.
+
+ Complete means every shard present and, when the download recorded a manifest, every file
+ it names (a projector or drafter the variant needs included). Only the owner's session,
+ which may read its own downloads: anyone else sent the token the Hub just refused for this
+ repo, and neither an earlier ``/auth-check`` verdict nor a probe that cannot answer outranks
+ that refusal."""
+ if not owner_session:
+ return None
+ if not cache_reads_authorized(
+ _refused_repo_cache_token(hf_token, owner_session), repo_id = repo_id
+ ):
+ return None
+ from core.inference.llama_cpp import cached_gguf_for_load
+
+ if gguf_variant:
+ local_file = cached_gguf_for_load(repo_id, gguf_variant, strict = True)
+ if local_file and _remembered_companions_present(repo_id, gguf_variant, local_file):
+ return local_file, gguf_variant
+ return None
+ # Auto: preferred variant first, falling through incomplete ones, across every snapshot.
+ remaining = sorted(_hf_cache_main_gguf_files(repo_id, every_snapshot = True))
+ while remaining:
+ # Repo-root checkpoint first, as the healthy-Hub pick does.
+ root_rows = [
+ f for f in remaining if "/" not in _qualified_variant_name(f, _extract_quant_label(f))
+ ]
+ best = _pick_best_gguf(root_rows or remaining)
+ if not best:
+ return None
+ label = _extract_quant_label(best)
+ variant = _qualified_variant_name(best, label) if label else None
+ local_file = cached_gguf_for_load(repo_id, variant, strict = True) if variant else None
+ if local_file and _remembered_companions_present(repo_id, variant, local_file):
+ return local_file, variant
+ remaining = [
+ f
+ for f in remaining
+ if f != best
+ and not (label and _qualified_variant_name(f, _extract_quant_label(f)) == variant)
+ ]
+ return None
+
+
def detect_gguf_model_remote(repo_id: str, hf_token: Optional[str] = None) -> Optional[str]:
"""Return the best GGUF filename in a HF repo, or None.
@@ -3417,12 +3527,13 @@ def detect_gguf_model_remote(repo_id: str, hf_token: Optional[str] = None) -> Op
last_err = e
# 404 / RepoNotFound is permanent -- don't retry
err_name = type(e).__name__
+ # Status-only refusals too (DisabledRepoError, bare 403), or the refused-repo policy is skipped.
if err_name in (
"RepositoryNotFoundError",
"GatedRepoError",
"RevisionNotFoundError",
"EntryNotFoundError",
- ):
+ ) or _is_hub_refusal(e):
logger.debug(f"Could not check GGUF files for '{repo_id}': {e}")
_note_gguf_remote_detect_failure(e)
return None
@@ -4078,6 +4189,8 @@ class ModelConfig:
gguf_hf_repo: Optional[str] = (
None # HF repo ID for -hf mode (e.g. "unsloth/gemma-3-4b-it-GGUF")
)
+ # Repo a refused-Hub cached GGUF came from, for the download interlock.
+ gguf_cache_repo: Optional[str] = None
gguf_variant: Optional[str] = None # Quantization variant (e.g. "Q4_K_M")
base_model: Optional[str] = None # Base model (for LoRAs)
@@ -4140,6 +4253,7 @@ class ModelConfig:
drafter_accept: Optional[Callable[[str, str, str, str], bool]] = None,
gguf_companion_roots: Optional[Tuple[str, ...]] = None,
mmproj_accept: Optional[Callable[[str, str], bool]] = None,
+ owner_session: bool = False,
) -> Optional["ModelConfig"]:
"""Create ModelConfig from a clean model identifier (HF repo or local
path), for FastAPI routes that send sanitized paths.
@@ -4165,6 +4279,8 @@ class ModelConfig:
compatible mmproj without changing the selected main weights.
mmproj_accept: ``(candidate, gguf_file) -> bool`` admission rule
applied before reading projector metadata for native loads.
+ owner_session: the caller is the machine owner's own UI session, which may
+ run a GGUF it already downloaded when the Hub refuses the repo.
Returns:
ModelConfig or None if it cannot be created.
@@ -4328,7 +4444,50 @@ class ModelConfig:
gguf_filename = detect_gguf_model_remote(identifier, hf_token = hf_token)
finally:
_gguf_remote_detect_failure.reset(failure_token)
- # A failed listing is not "no GGUF"; a refused repo is never served from cache (#11551).
+ # A failed listing is not "no GGUF" (#11551): a refused repo's downloaded copy goes
+ # only to a caller who may read that cache, with a warning.
+ if not gguf_filename and detect_failures and _is_hub_refusal(detect_failures[-1]):
+ cached = _refused_repo_cached_gguf(
+ identifier, gguf_variant, hf_token, owner_session = owner_session
+ )
+ if cached is not None:
+ local_file, cached_variant = cached
+ logger.warning(
+ "Hugging Face refused '%s' (%s); loading the downloaded copy.",
+ identifier,
+ type(detect_failures[-1]).__name__,
+ )
+ from core.inference.llama_cpp import _snapshot_dir_of
+
+ # Snapshot root, so a repo-root mmproj or drafter is found.
+ snapshot = _snapshot_dir_of(local_file)
+ local_config = cls.from_identifier(
+ model_id = local_file,
+ hf_token = hf_token,
+ gguf_variant = cached_variant,
+ drafter_accept = drafter_accept,
+ gguf_companion_roots = gguf_companion_roots
+ or ((str(snapshot),) if snapshot is not None else None),
+ mmproj_accept = mmproj_accept,
+ )
+ if local_config is not None and local_config.is_gguf:
+ # Preflight, so /load never unloads the resident model for nothing.
+ from core.inference.llama_cpp import (
+ LLAMA_SERVER_NOT_FOUND_DETAIL,
+ LlamaCppBackend,
+ LlamaServerNotFoundError,
+ )
+
+ if not LlamaCppBackend._find_llama_server_binary(include_denied = True):
+ raise LlamaServerNotFoundError(LLAMA_SERVER_NOT_FOUND_DETAIL)
+ token_rejections.served_from_cache.append(identifier)
+ return _dataclass_replace(
+ local_config,
+ identifier = identifier,
+ display_name = f"{identifier.split('/')[-1]} ({cached_variant})",
+ gguf_cache_repo = identifier,
+ is_local = False,
+ )
if not gguf_filename and _looks_like_gguf_repo(identifier, gguf_variant):
if detect_failures:
raise GgufRepoUnreadableError(