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 repo id from its scan-folder copy instead of re-downloading it (#13034)

Daniel Hanbcdc3d2b241e
diff --git a/studio/backend/core/inference/chat_templates.py b/studio/backend/core/inference/chat_templates.py
index ae2ae2fc2d0..7357e788e17 100644
--- a/studio/backend/core/inference/chat_templates.py
+++ b/studio/backend/core/inference/chat_templates.py
@@ -46,7 +46,11 @@ def _canonical_repo_id(model_identifier: str) -> str:
runs on the raw ``request.model_path`` (before that canonicalization), so apply
the same rule here, otherwise shorthand loads would skip the override.
"""
+ from core.inference.model_ids import hf_cache_repo_id
+
mid = model_identifier.strip()
+ # A snapshot of the repo (scan-folder copy, pinned cache row) is that repo; other paths are not.
+ mid = hf_cache_repo_id(mid) or mid
if mid and "/" not in mid:
mid = f"unsloth/{mid}"
return mid
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 3e6f4fa831d..9c07077f6d1 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -3064,7 +3064,11 @@ def detect_reasoning_flags(
# template only branches on 'max', so the literal scan misses 'high'. Add it
# (matched on whole repo-name segments, so 'deepseek-v40' won't false-match)
# to expose the full high/max ladder instead of max alone.
- segments = re.split(r"[-_.]", (model_identifier or "").lower().split("/")[-1])
+ from core.inference.model_ids import hf_cache_repo_id
+
+ # A snapshot path's last component is the revision, so read it as its repo id first.
+ repo_name = hf_cache_repo_id(model_identifier) or model_identifier or ""
+ segments = re.split(r"[-_.]", repo_name.lower().split("/")[-1])
is_dsv4 = "deepseek4" in segments or any(
a == "deepseek" and b == "v4" for a, b in zip(segments, segments[1:])
)
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 7c63594a46b..1f5a03899cf 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -8808,6 +8808,52 @@ def _as_ollama_manifest_request(request):
return request.model_copy(update = {"model_path": ref})
+def _as_local_scan_folder_request(request, owner_session: bool):
+ """*request* with a repo id whose GGUF copy sits outside the active hub cache (e.g. a scan folder) rewritten to it."""
+ from core.inference.local_model_resolver import _is_abs_path_id, resolve_local_gguf
+ from core.inference.model_ids import hf_cache_repo_id
+
+ identifier = (request.model_path or "").strip()
+ # Bare names mean unsloth/<name> remotely; a same-stemmed local file must not win them.
+ if (
+ not identifier
+ or "/" not in identifier
+ or is_ollama_manifest_ref(identifier)
+ or _is_abs_path_id(identifier)
+ ):
+ return request
+ # Owner session only (as _refused_repo_cached_gguf); a native lease names one exact artifact.
+ if not owner_session or getattr(request, "native_path_lease", None):
+ return request
+ wanted = f"{identifier}:{request.gguf_variant}" if request.gguf_variant else identifier
+ try:
+ resolved = resolve_local_gguf(wanted)
+ except Exception:
+ return request
+ if resolved is None:
+ return request
+ load_path, variant = str(resolved[0]), resolved[1]
+ # Only a GGUF snapshot of this repo: its path maps back to the repo id (status, unload, consent).
+ if not variant or (hf_cache_repo_id(load_path) or "").lower() != identifier.lower():
+ return request
+ # A repo directly in the active hub cache already loads by repo id without downloading.
+ try:
+ from hub.utils.hf_cache_state import same_existing_path
+ from routes.models import _resolve_hf_cache_dir
+
+ repo_dir = next(p for p in Path(load_path).parents if p.name.startswith("models--"))
+ if same_existing_path(repo_dir.parent, Path(_resolve_hf_cache_dir())):
+ return request
+ except Exception:
+ return request
+ logger.info(
+ "Resolved repo id '%s' to local path %s instead of downloading",
+ identifier,
+ load_path,
+ )
+ return request.model_copy(update = {"model_path": load_path, "gguf_variant": variant})
+
+
async def _lease_ollama_model_ref(
request: LoadRequest | ValidateModelRequest, *, operation: str, stack: ExitStack
) -> Optional[str]:
@@ -18072,6 +18118,14 @@ async def _load_model_impl(
if account_access.managed_account() and not native_access_deferred:
await asyncio.to_thread(account_access.require_model_access, request.model_path)
request = await asyncio.to_thread(_as_ollama_manifest_request, request)
+ _requested_model_id = request.model_path
+ request = await asyncio.to_thread(
+ _as_local_scan_folder_request, request, _owner_session(fastapi_request)
+ )
+ # The client keeps the repo id it picked as the checkpoint; only the load reads the copy.
+ scan_folder_public_id = (
+ _requested_model_id if request.model_path != _requested_model_id else None
+ )
if account_access.managed_account():
request = request.model_copy(
update = {"hf_token": account_access.account_hf_token(request.hf_token)}
@@ -18323,7 +18377,9 @@ async def _load_model_impl(
return _gguf_load_response(
llama_backend,
"already_loaded",
- model_log_label if native_grant_backed else llama_backend.model_identifier,
+ model_log_label
+ if native_grant_backed
+ else scan_folder_public_id or llama_backend.model_identifier,
display_name = model_log_label if native_grant_backed else display_name,
is_local_model = _loaded_is_local_model(
llama_backend, native_grant_backed, llama_backend.model_identifier
@@ -19030,7 +19086,9 @@ async def _load_model_impl(
return _gguf_load_response(
llama_backend,
"loaded",
- model_log_label if native_grant_backed else public_model_identifier,
+ model_log_label
+ if native_grant_backed
+ else scan_folder_public_id or public_model_identifier,
display_name = model_log_label if native_grant_backed else config.display_name,
is_local_model = config.is_local,
inference_identifier = config.identifier,
@@ -19599,6 +19657,10 @@ async def validate_model(
if account_access.managed_account() and not native_access_deferred:
await asyncio.to_thread(account_access.require_model_access, request.model_path)
request = await asyncio.to_thread(_as_ollama_manifest_request, request)
+ # The chat flow validates before /load; offline the remote probe would refuse the id.
+ request = await asyncio.to_thread(
+ _as_local_scan_folder_request, request, _owner_session(fastapi_request)
+ )
from core.inference.llama_cpp import (
LlamaServerNotFoundError,
_hf_offline_if_unreachable_for,
diff --git a/studio/backend/tests/test_deepseek_v4_thinking_effort.py b/studio/backend/tests/test_deepseek_v4_thinking_effort.py
index 0d60d9b5ec3..ded1f097c55 100644
--- a/studio/backend/tests/test_deepseek_v4_thinking_effort.py
+++ b/studio/backend/tests/test_deepseek_v4_thinking_effort.py
@@ -95,6 +95,15 @@ def test_deepseek_v4_surfaces_high_as_plain_tier():
assert flags["reasoning_effort_levels"] == ["high", "max"]
+def test_deepseek_v4_snapshot_path_keeps_high():
+ """A copy loaded from its HF snapshot dir is still DeepSeek-V4."""
+ from core.inference.llama_cpp import detect_reasoning_flags
+
+ path = "/scan/models--unsloth--DeepSeek-V4-Flash-GGUF/snapshots/0123abcd"
+ flags = detect_reasoning_flags(DEEPSEEK_V4_TEMPLATE, path)
+ assert flags["reasoning_effort_levels"] == ["high", "max"]
+
+
def test_glm_style_two_level_template_unchanged():
"""A template that already names a sub-'max' tier is left as-is."""
from core.inference.llama_cpp import detect_reasoning_flags
diff --git a/studio/backend/tests/test_gemma4_chat_template_override.py b/studio/backend/tests/test_gemma4_chat_template_override.py
index 96796d06267..9e22a732b59 100644
--- a/studio/backend/tests/test_gemma4_chat_template_override.py
+++ b/studio/backend/tests/test_gemma4_chat_template_override.py
@@ -110,6 +110,8 @@ def _detect_reasoning_flags():
("google/gemma-4-31B-it-GGUF", False), # not unsloth
("unsloth/Qwen3.5-9B-MTP-GGUF", False),
("/home/user/models/gemma-4-E2B.Q4_K_M.gguf", False), # local path
+ ("/scan/models--unsloth--gemma-4-E2B-it-GGUF/snapshots/abc", True), # repo snapshot
+ ("C:\\scan\\models--google--gemma-4-31B-it-GGUF\\snapshots\\abc", False),
("", False),
(None, False),
],
diff --git a/studio/backend/tests/test_inference_status_loaded_gguf.py b/studio/backend/tests/test_inference_status_loaded_gguf.py
index 2aefc8976e4..de7e3e85d6d 100644
--- a/studio/backend/tests/test_inference_status_loaded_gguf.py
+++ b/studio/backend/tests/test_inference_status_loaded_gguf.py
@@ -171,6 +171,24 @@ def test_an_auto_applied_chat_template_is_not_reported_as_the_users(status_route
assert status_route(backend).chat_template_override is None
+def test_a_bundled_template_on_a_snapshot_path_load_is_not_reported_as_the_users(
+ status_route, monkeypatch
+):
+ from core.inference.chat_templates import resolve_effective_chat_template_override
+
+ monkeypatch.setattr(
+ inference_route,
+ "resolve_effective_chat_template_override",
+ resolve_effective_chat_template_override,
+ )
+ bundled = resolve_effective_chat_template_override(
+ model_identifier = "unsloth/gemma-4-12b-it-GGUF", user_override = None
+ )
+ backend = _StatusBackend("/scan/models--unsloth--gemma-4-12b-it-GGUF/snapshots/abc")
+ backend.chat_template_override = bundled
+ assert status_route(backend).chat_template_override is None
+
+
def test_status_publishes_the_running_pass_through_arguments(status_route):
# A tab opened while a model is already running never saw the load, so the only
# place it can learn what the server was invoked with is here. Without it, a
diff --git a/studio/backend/tests/test_load_scan_folder_resolution.py b/studio/backend/tests/test_load_scan_folder_resolution.py
new file mode 100644
index 00000000000..81231529264
--- /dev/null
+++ b/studio/backend/tests/test_load_scan_folder_resolution.py
@@ -0,0 +1,253 @@
+# 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 repo id a registered local root holds must load from disk, not re-download into the hub."""
+
+import pytest
+
+import core.inference.local_model_resolver as resolver
+import routes.inference as inf
+from models.inference import LoadRequest
+
+
+_SNAPSHOT = "C:/scan-folder/models--unsloth--Muse-Glimmer-30B-GGUF/snapshots/abc"
+
+
+def _request(**kwargs):
+ kwargs.setdefault("model_path", "unsloth/Muse-Glimmer-30B-GGUF")
+ return LoadRequest(**kwargs)
+
+
+def test_repo_id_resolves_to_local_scan_folder_copy(monkeypatch):
+ seen = []
+
+ def fake_resolve(wanted, **kwargs):
+ seen.append(wanted)
+ return (_SNAPSHOT, "Q4_K_XL", "unsloth/Muse-Glimmer-30B-GGUF")
+
+ monkeypatch.setattr(resolver, "resolve_local_gguf", fake_resolve)
+ rewritten = inf._as_local_scan_folder_request(_request(), True)
+ assert seen == ["unsloth/Muse-Glimmer-30B-GGUF"]
+ assert rewritten.model_path == _SNAPSHOT
+ assert rewritten.gguf_variant == "Q4_K_XL"
+
+
+def test_pinned_variant_resolves_by_repo_and_quant(monkeypatch):
+ seen = []
+
+ def fake_resolve(wanted, **kwargs):
+ seen.append(wanted)
+ return (_SNAPSHOT, "Q8_0", "loader")
+
+ monkeypatch.setattr(resolver, "resolve_local_gguf", fake_resolve)
+ rewritten = inf._as_local_scan_folder_request(_request(gguf_variant = "Q8_0"), True)
+ assert seen == ["unsloth/Muse-Glimmer-30B-GGUF:Q8_0"]
+ assert rewritten.model_path == _SNAPSHOT
+ assert rewritten.gguf_variant == "Q8_0"
+
+
+def test_local_miss_keeps_the_request_untouched(monkeypatch):
+ monkeypatch.setattr(resolver, "resolve_local_gguf", lambda wanted, **kwargs: None)
+ original = _request()
+ assert inf._as_local_scan_folder_request(original, True) is original
+
+
+def test_bare_name_stays_remote_for_the_hub(monkeypatch):
+ def fail(wanted, **kwargs):
+ pytest.fail("resolver consulted for a bare name")
+
+ monkeypatch.setattr(resolver, "resolve_local_gguf", fail)
+ request = _request(model_path = "Muse-Glimmer-30B-GGUF")
+ assert inf._as_local_scan_folder_request(request, True) is request
+
+
+def test_resolved_variant_replaces_the_requested_one(monkeypatch):
+ seen = []
+
+ def fake_resolve(wanted, **kwargs):
+ seen.append(wanted)
+ return (_SNAPSHOT, "Q4_K_XL", "loader")
+
+ monkeypatch.setattr(resolver, "resolve_local_gguf", fake_resolve)
+ rewritten = inf._as_local_scan_folder_request(_request(gguf_variant = "BF16"), True)
+ assert seen == ["unsloth/Muse-Glimmer-30B-GGUF:BF16"]
+ assert rewritten.gguf_variant == "Q4_K_XL"
+
+
+def test_paths_and_manifest_refs_never_consult_the_resolver(monkeypatch):
+ def fail(wanted, **kwargs):
+ pytest.fail("resolver consulted for a non-repo-id path")
+
+ monkeypatch.setattr(resolver, "resolve_local_gguf", fail)
+ for path in (
+ "C:/scan-folder/models--x/snapshots/abc",
+ "/home/me/model.gguf",
+ "ollama-manifest:sha256:deadbeef",
+ ):
+ request = _request(model_path = path)
+ assert inf._as_local_scan_folder_request(request, True) is request
+
+
+def test_resolver_failure_or_ollama_target_keeps_the_request(monkeypatch):
+ def boom(wanted, **kwargs):
+ raise OSError("scan root unreadable")
+
+ monkeypatch.setattr(resolver, "resolve_local_gguf", boom)
+ original = _request()
+ assert inf._as_local_scan_folder_request(original, True) is original
+
+ monkeypatch.setattr(
+ resolver,
+ "resolve_local_gguf",
+ lambda wanted, **kwargs: ("ollama-manifest:sha256:deadbeef", None, "loader"),
+ )
+ tagged = _request()
+ assert inf._as_local_scan_folder_request(tagged, True) is tagged
+
+
+def test_a_caller_other_than_the_owner_session_keeps_the_requested_id(monkeypatch):
+ seen = []
+ monkeypatch.setattr(
+ resolver, "resolve_local_gguf", lambda wanted, **kwargs: seen.append(wanted)
+ )
+ original = _request()
+ assert inf._as_local_scan_folder_request(original, False) is original
+ assert seen == []
+
+
+def test_native_path_lease_keeps_the_requested_id(monkeypatch):
+ def fail(wanted, **kwargs):
+ pytest.fail("resolver consulted under a native lease")
+
+ monkeypatch.setattr(resolver, "resolve_local_gguf", fail)
+ original = _request(native_path_lease = "lease-token")
+ assert inf._as_local_scan_folder_request(original, True) is original
+
+
+_REPO = "unsloth/Tiny-Probe-GGUF"
+
+
+def _cache_repo(root, files):
+ repo_dir = root / ("models--" + _REPO.replace("/", "--"))
+ (repo_dir / "refs").mkdir(parents = True)
+ (repo_dir / "refs" / "main").write_text("abc")
+ snapshot = repo_dir / "snapshots" / "abc"
+ snapshot.mkdir(parents = True)
+ for name in files:
+ (snapshot / name).write_bytes(b"GGUF" + b"\0" * 64)
+ return snapshot
+
+
+def roots(monkeypatch, tmp_path):
+ from storage import studio_db
+
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "home"))
+ active = tmp_path / "hub"
+ active.mkdir()
+ scan = tmp_path / "scan"
+ scan.mkdir()
+ monkeypatch.setattr("routes.models._resolve_hf_cache_dir", lambda: active)
+ monkeypatch.setattr("utils.paths.legacy_hf_cache_dir", lambda: tmp_path / "legacy")
+ monkeypatch.setattr("utils.paths.hf_default_cache_dir", lambda: tmp_path / "default")
+ monkeypatch.setattr("utils.paths.lmstudio_model_dirs", lambda: [])
+ monkeypatch.setattr("utils.paths.hermes_model_dirs", lambda: [], raising = False)
+ monkeypatch.setattr("utils.paths.ollama_model_dirs", lambda: [], raising = False)
+ monkeypatch.setattr("utils.paths.omlx_model_dirs", lambda: [], raising = False)
+ monkeypatch.setattr("utils.hf_cache_settings.known_hf_hub_caches", lambda: [active])
+ monkeypatch.chdir(tmp_path)
+ connection = studio_db.get_connection()
+ with connection:
+ connection.execute(
+ "INSERT INTO scan_folders (path, created_at) VALUES (?, datetime('now'))",
+ (str(scan),),
+ )
+ connection.close()
+ resolver.invalidate_index()
+ yield active, scan
+ resolver.invalidate_index()
+
+
+def test_scan_folder_only_copy_loads_from_disk(roots):
+ _active, scan = roots
+ snapshot = _cache_repo(scan, ["Tiny-Probe-UD-Q5_K_XL.gguf"])
+ rewritten = inf._as_local_scan_folder_request(_request(model_path = _REPO), True)
+ assert (rewritten.model_path, rewritten.gguf_variant) == (str(snapshot), "UD-Q5_K_XL")
+ pinned = inf._as_local_scan_folder_request(
+ _request(model_path = _REPO, gguf_variant = "UD-Q5_K_XL"), True
+ )
+ assert pinned.model_path == str(snapshot)
+ missing = inf._as_local_scan_folder_request(
+ _request(model_path = _REPO, gguf_variant = "Q8_0"), True
+ )
+ assert (missing.model_path, missing.gguf_variant) == (_REPO, "Q8_0")
+
+
[email protected]("in_scan_folder", [False, True])
+def test_active_hub_cache_copy_keeps_the_repo_id(roots, in_scan_folder):
+ active, scan = roots
+ _cache_repo(active, ["Tiny-Probe-Q4_K_M.gguf", "Tiny-Probe-Q8_0.gguf"])
+ if in_scan_folder:
+ _cache_repo(scan, ["Tiny-Probe-Q4_K_M.gguf"])
+ for variant in (None, "Q8_0"):
+ request = _request(model_path = _REPO, gguf_variant = variant)
+ assert inf._as_local_scan_folder_request(request, True) is request
+
+
+def test_weightless_hub_skeleton_does_not_hide_the_scan_folder_copy(roots):
+ active, scan = roots
+ _cache_repo(active, [])
+ snapshot = _cache_repo(scan, ["Tiny-Probe-Q4_K_M.gguf"])
+ rewritten = inf._as_local_scan_folder_request(_request(model_path = _REPO), True)
+ assert rewritten.model_path == str(snapshot)
+
+
+def test_validate_reads_the_scan_folder_copy_offline(roots, monkeypatch):
+ import asyncio
+
+ from models.inference import ValidateModelRequest
+
+ _active, scan = roots
+ _cache_repo(scan, ["Tiny-Probe-Q4_K_M.gguf"])
+ monkeypatch.setenv("HF_HUB_OFFLINE", "1")
+ monkeypatch.setattr(inf, "_owner_session", lambda fastapi_request: True)
+ result = asyncio.run(inf.validate_model(ValidateModelRequest(model_path = _REPO), None, "owner"))
+ assert result.valid and result.is_gguf
+ # An API key caller may not read the owner's copy, so it keeps the remote refusal.
+ monkeypatch.setattr(inf, "_owner_session", lambda fastapi_request: False)
+ with pytest.raises(inf.HTTPException):
+ asyncio.run(inf.validate_model(ValidateModelRequest(model_path = _REPO), None, "owner"))
+
+
+ "hit",
+ [
+ ("C:/lmstudio/models/unsloth/Muse-Glimmer-30B-GGUF", "Q4_K_XL", "loader"),
+ (_SNAPSHOT, None, "loader"),
+ ("C:/scan-folder/models--unsloth--Other-GGUF/snapshots/abc", "Q4_K_XL", "loader"),
+ ],
+ ids = ["non_hf_layout", "non_gguf", "other_repo"],
+)
+def test_only_a_gguf_snapshot_of_the_requested_repo_is_taken(monkeypatch, hit):
+ monkeypatch.setattr(resolver, "resolve_local_gguf", lambda wanted, **kwargs: hit)
+ request = _request()
+ assert inf._as_local_scan_folder_request(request, True) is request
+
+
+def test_scan_folder_nested_inside_the_hub_cache_still_loads_from_disk(roots, monkeypatch):
+ from storage import studio_db
+
+ active, _scan = roots
+ nested = active / "archive"
+ nested.mkdir()
+ connection = studio_db.get_connection()
+ with connection:
+ connection.execute(
+ "INSERT INTO scan_folders (path, created_at) VALUES (?, datetime('now'))",
+ (str(nested),),
+ )
+ connection.close()
+ resolver.invalidate_index()
+ snapshot = _cache_repo(nested, ["Tiny-Probe-Q4_K_M.gguf"])
+ rewritten = inf._as_local_scan_folder_request(_request(model_path = _REPO), True)
+ assert rewritten.model_path == str(snapshot)