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: unload a model under the id the API lists for it (#13810)

Daniel Han9396996c9e8f
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 7eda56981e8..15ccc8a2d10 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -17428,6 +17428,47 @@ def _ollama_ref_for_link(model_path: str) -> Optional[str]:
return None
+def _names_the_resident_gguf(llama_backend, model_path: str) -> bool:
+ """Whether a client's ``model_path`` names the GGUF ``llama_backend`` runs.
+
+ A scan-folder load runs as its directory while /v1/models, status and the monitor publish its
+ repo id (the monitor as ``repo:QUANT``), and chat is served under that id, so /unload must
+ accept it too or it answers success and leaves the model loaded (#13766).
+ """
+ identifier = llama_backend.model_identifier
+ if (
+ identifier == model_path
+ or is_registered_native_path_label(identifier, model_path)
+ or _names_the_resident_model(identifier, model_path)
+ ):
+ return True
+ # A load in flight can still carry the previous model's advertised id.
+ if not getattr(llama_backend, "is_loaded", False):
+ return False
+ from core.inference.openai_auto_download import split_model_ref
+
+ published = [
+ getattr(llama_backend, "_openai_advertised_id", None),
+ _llama_public_model_id(llama_backend),
+ ]
+ if _matches_any(model_path, published):
+ return True
+ base, variant = split_model_ref(model_path)
+ resident_variant = getattr(llama_backend, "hf_variant", None) or ""
+ return (
+ bool(variant)
+ and variant.lower() == resident_variant.lower()
+ and _matches_any(base, published)
+ )
+
+
+def _names_the_resident_standard_model(backend, active: str, model_path: str) -> bool:
+ """``_names_the_resident_model`` plus the repo id auto-switch advertises for ``active``."""
+ return _names_the_resident_model(active, model_path) or _matches_any(
+ model_path, [getattr(backend, "_openai_advertised_id", None)]
+ )
+
+
def _names_the_loading_model(loading: str, model_path: str) -> bool:
"""Whether a client's ``model_path`` names the load already in flight.
@@ -17448,7 +17489,7 @@ def _resident_standard_model_name(backend, model_path: str) -> str:
name it was registered with rather than the id the client shows.
"""
active = getattr(backend, "active_model_name", None)
- if isinstance(active, str) and _names_the_resident_model(active, model_path):
+ if isinstance(active, str) and _names_the_resident_standard_model(backend, active, model_path):
return active
loaded = getattr(backend, "models", None)
if isinstance(loaded, dict):
@@ -17476,7 +17517,11 @@ def _unload_evicts_standard_backend(backend, model_path: str) -> bool:
return True
if isinstance(active, str) and active and active.lower() == (model_path or "").lower():
return True
- if isinstance(active, str) and _names_the_resident_model(active, model_path):
+ if (
+ isinstance(active, str)
+ and active
+ and _names_the_resident_standard_model(backend, active, model_path)
+ ):
return True
if not isinstance(loaded, dict):
return False
@@ -17511,9 +17556,7 @@ def _unload_may_evict(model_path: str) -> bool:
return True
llama_backend = get_llama_cpp_backend()
if llama_backend.is_active and (
- llama_backend.model_identifier == model_path
- or is_registered_native_path_label(llama_backend.model_identifier, model_path)
- or _names_the_resident_model(llama_backend.model_identifier, model_path)
+ _names_the_resident_gguf(llama_backend, model_path)
# Up but not serving is mid-load, evicted whatever model was named.
or not llama_backend.is_loaded
):
@@ -21759,11 +21802,7 @@ async def _unload_model_impl(request: UnloadRequest, current_subject: str):
# Check if the GGUF backend has this model loaded or is loading it.
llama_backend = get_llama_cpp_backend()
if llama_backend.is_active and (
- llama_backend.model_identifier == request.model_path
- or is_registered_native_path_label(
- llama_backend.model_identifier, request.model_path
- )
- or _names_the_resident_model(llama_backend.model_identifier, request.model_path)
+ _names_the_resident_gguf(llama_backend, request.model_path)
or not llama_backend.is_loaded
):
# Read the identity before teardown clears it, so the row reads repo:QUANT.
@@ -21800,7 +21839,8 @@ async def _unload_model_impl(request: UnloadRequest, current_subject: str):
# a slow SSE stream paused between tokens still holds, so a sync call would block
# the loop that drives the stream's next token and the lock release.
backend = await asyncio.to_thread(get_inference_backend)
- if _unload_evicts_standard_backend(backend, request.model_path):
+ evicts = _unload_evicts_standard_backend(backend, request.model_path)
+ if evicts:
# Point of no return for the standard path, same rule as above.
_raise_or_cancel_active_generations(
force = request.force_cancel_active, action = "Unloading the model"
@@ -21818,12 +21858,14 @@ async def _unload_model_impl(request: UnloadRequest, current_subject: str):
note_model_unloaded()
account_access.clear_resident("chat")
await asyncio.to_thread(release_chat_gpu_claim)
- api_monitor.record_lifecycle(
- event = "unload",
- model = _lifecycle_model_label(request.model_path),
- reason = "manual",
- )
- logger.info(f"Unloaded model: {request.model_path}")
+ # The no-op stays a 200 for stale tabs, but logging it read as an unload of whatever is resident.
+ if evicts:
+ api_monitor.record_lifecycle(
+ event = "unload",
+ model = _lifecycle_model_label(request.model_path),
+ reason = "manual",
+ )
+ logger.info(f"Unloaded model: {request.model_path}")
return UnloadResponse(status = "unloaded", model = request.model_path)
except HTTPException:
diff --git a/studio/backend/tests/test_unload_published_id.py b/studio/backend/tests/test_unload_published_id.py
new file mode 100644
index 00000000000..a544f866877
--- /dev/null
+++ b/studio/backend/tests/test_unload_published_id.py
@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""POST /unload finds a model under the ids Studio publishes for it, and logs only real unloads (#13766)."""
+
+import asyncio
+
+import pytest
+
+import core.inference.model_slots as model_slots
+import core.inference.orchestrator as orchestrator
+import routes.inference as inf
+from models.inference import UnloadRequest
+
+SCAN_DIR = "/srv/models/org/X-GGUF"
+
+
+class FakeLlama:
+ holds_no_vram = False
+
+ def __init__(
+ self,
+ identifier = None,
+ variant = None,
+ advertised = None,
+ ):
+ self.model_identifier = identifier
+ self.hf_variant = variant
+ self._openai_advertised_id = advertised
+ self.is_loaded = self.is_active = identifier is not None
+ self.is_vision = False
+ self.context_length = 4096
+
+ def unload_model(self):
+ self.is_loaded = self.is_active = False
+
+
+class FakeOrchestrator:
+ def __init__(
+ self,
+ active = None,
+ advertised = None,
+ ):
+ self.active_model_name = active
+ self.models = {active: {}} if active else {}
+ self._openai_advertised_id = advertised
+ self.unloaded = []
+
+ def unload_model(self, name):
+ if name == self.active_model_name:
+ self.unloaded.append(name)
+ self.active_model_name = None
+ self.models = {}
+ return True
+
+
+def lifecycle(monkeypatch):
+ rows = []
+ monkeypatch.setattr(model_slots, "slots", [])
+ monkeypatch.setattr(model_slots, "stuck", [])
+ monkeypatch.setattr(inf, "_raise_if_sidecar_swap_in_progress", lambda: None)
+ monkeypatch.setattr(inf.api_monitor, "record_lifecycle", lambda **kwargs: rows.append(kwargs))
+ return rows
+
+
+def _serve(
+ monkeypatch,
+ llama,
+ orch = None,
+):
+ monkeypatch.setattr(inf, "_llama_cpp_backend", llama)
+ monkeypatch.setattr(orchestrator, "_inference_backend", orch or FakeOrchestrator())
+
+
+def _unload(model_path):
+ return asyncio.run(inf._unload_model_impl(UnloadRequest(model_path = model_path), "s"))
+
+
+ "named",
+ [
+ "org/X-GGUF", # /v1/models and status.active_model
+ "ORG/x-gguf",
+ "org/X-GGUF:X-custom-NVFP4", # the API monitor's loaded-model label
+ SCAN_DIR, # status.model_identifier, what the Unload button sends
+ ],
+)
+def test_scan_folder_gguf_unloads_under_every_published_id(monkeypatch, lifecycle, named):
+ llama = FakeLlama(SCAN_DIR, "X-custom-NVFP4", advertised = "org/X-GGUF")
+ _serve(monkeypatch, llama)
+ assert _unload(named).status == "unloaded"
+ assert not llama.is_loaded
+ assert [row["model"] for row in lifecycle] == ["org/X-GGUF:X-custom-NVFP4"]
+
+
[email protected]("named", ["org/X-GGUF:Q8_0", "org/Other-GGUF", "X-custom-NVFP4"])
+def test_a_name_for_another_model_leaves_it_loaded_and_logs_nothing(monkeypatch, lifecycle, named):
+ llama = FakeLlama(SCAN_DIR, "X-custom-NVFP4", advertised = "org/X-GGUF")
+ _serve(monkeypatch, llama)
+ # Still the documented idempotent no-op for a stale tab.
+ assert _unload(named).status == "unloaded"
+ assert llama.is_loaded
+ assert lifecycle == []
+
+
+def test_unload_with_nothing_loaded_logs_nothing(monkeypatch, lifecycle):
+ _serve(monkeypatch, FakeLlama())
+ assert _unload("org/X-GGUF").status == "unloaded"
+ assert lifecycle == []
+
+
+def test_a_load_in_flight_is_not_matched_by_a_stale_advertised_id(monkeypatch):
+ llama = FakeLlama("/srv/models/org/New-GGUF", "Q4_K_M", advertised = "org/Old-GGUF")
+ llama.is_loaded = False
+ assert not inf._names_the_resident_gguf(llama, "org/Old-GGUF")
+ assert inf._names_the_resident_gguf(llama, "/srv/models/org/New-GGUF")
+
+
+def test_auto_switched_safetensors_unloads_under_its_advertised_id(monkeypatch, lifecycle):
+ orch = FakeOrchestrator("/srv/models/org/Y", advertised = "org/Y")
+ _serve(monkeypatch, FakeLlama(), orch)
+ assert _unload("org/Y").status == "unloaded"
+ assert orch.unloaded == ["/srv/models/org/Y"]
+ assert [row["model"] for row in lifecycle] == ["org/Y"]