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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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 applythe 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 midif mid and "/" not in mid:mid = f"unsloth/{mid}"return middiff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.pyindex 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.pyindex 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.pyindex 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_flagsdiff --git a/studio/backend/tests/test_gemma4_chat_template_override.py b/studio/backend/tests/test_gemma4_chat_template_override.pyindex 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.pyindex 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_routeassert 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, adiff --git a/studio/backend/tests/test_load_scan_folder_resolution.py b/studio/backend/tests/test_load_scan_folder_resolution.pynew file mode 100644index 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)