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.

fix(studio): reject standalone GGUF adapters before model teardown (#15421)

AAFI MALEKbb7ac2bfc5ee
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index efa6069160b..281611a972f 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -8048,6 +8048,7 @@ class LlamaCppBackend:
self._vision_disabled_by_user: bool = False
# Block-diffusion model, served by the diffusion runner; set from the GGUF architecture at load.
self._architecture: Optional[str] = None
+ self._gguf_type: Optional[str] = None
self._is_diffusion: bool = False
# Whole header walked? Separates "declares no architecture" from "unreadable".
self._gguf_header_parsed: bool = False
@@ -18423,6 +18424,7 @@ class LlamaCppBackend:
self._shared_kv_layers = None
self._nextn_predict_layers = None
self._architecture = None
+ self._gguf_type = None
self._is_diffusion = False
self._gguf_header_parsed = False
self._gguf_split_index = None
@@ -18431,6 +18433,7 @@ class LlamaCppBackend:
canvas_seen = False
WANTED = {
"general.architecture",
+ "general.type",
"tokenizer.chat_template",
# Vocab size = tokens array length (no vocab_size key in many GGUFs).
"tokenizer.ggml.tokens",
@@ -18507,6 +18510,8 @@ class LlamaCppBackend:
val_s = f.read(slen).decode("utf-8")
if key.startswith("general.") and key != "general.architecture":
general[key] = val_s
+ if key == "general.type":
+ self._gguf_type = val_s.strip().lower()
if key == "general.architecture":
arch = val_s
self._architecture = val_s
@@ -20253,8 +20258,15 @@ class LlamaCppBackend:
return True
def _non_chat_gguf_refusal(self, gguf_path: str) -> Optional[str]:
- """Header-only refusal of media GGUFs: a media architecture, or none at all once the header
- parsed."""
+ """Header-only refusal of adapter and media GGUFs: an adapter, a media architecture, or none
+ at all once the header parsed."""
+ # Metadata, not filenames: an adapter may declare a chat arch; a merged LoRA is a full model.
+ # Checked before the walk gate: a type that was read is definitive even from a partial prefix.
+ if getattr(self, "_gguf_type", None) == "adapter":
+ return (
+ "This GGUF is a LoRA adapter and needs a matching base model. "
+ "Select a full model GGUF for chat, or use this adapter with its base model."
+ )
arch = (self._architecture or "").strip().lower()
# A media arch is KV 0 so a partial remote prefix can carry it; the walk still gates the no-arch fallback, since an incomplete read looks like none.
if (
diff --git a/studio/backend/tests/test_llama_cpp_non_chat_gguf_preflight.py b/studio/backend/tests/test_llama_cpp_non_chat_gguf_preflight.py
index 13952e7e21a..be4bd4813b5 100644
--- a/studio/backend/tests/test_llama_cpp_non_chat_gguf_preflight.py
+++ b/studio/backend/tests/test_llama_cpp_non_chat_gguf_preflight.py
@@ -20,18 +20,20 @@ def _write_gguf(
*,
arch: str | None,
tensor_count: int = 1,
+ general_type: str | None = None,
) -> Path:
- """Minimal GGUF header: magic, version, counts, then one optional
- ``general.architecture`` string KV. The parser never reads the tensor data."""
+ """Minimal GGUF header: magic, version, counts, then optional ``general.architecture`` and
+ ``general.type`` string KVs. The parser never reads the tensor data."""
body = b""
kv_count = 0
- if arch is not None:
- key = b"general.architecture"
- val = arch.encode()
+ for key, value in ((b"general.architecture", arch), (b"general.type", general_type)):
+ if value is None:
+ continue
+ val = value.encode()
body += struct.pack("<Q", len(key)) + key
body += struct.pack("<I", 8)
body += struct.pack("<Q", len(val)) + val
- kv_count = 1
+ kv_count += 1
header = struct.pack("<II", GGUF_MAGIC, 3) + struct.pack("<QQ", tensor_count, kv_count)
path.write_bytes(header + body)
return path
@@ -58,6 +60,30 @@ def test_chat_arch_is_not_refused(tmp_path):
assert message is None
+def test_adapter_gguf_requires_its_base_model(tmp_path):
+ path = _write_gguf(tmp_path / "weights.gguf", arch = "deepseek41", general_type = "adapter")
+ message = LlamaCppBackend._non_chat_gguf_refusal_for_path(str(path), None)
+ assert message is not None
+ assert "LoRA adapter" in message
+ assert "base model" in message
+
+
[email protected]("general_type", [None, "model"])
+def test_merged_lora_model_is_allowed(tmp_path, general_type):
+ path = _write_gguf(tmp_path / "merged-LoRA.gguf", arch = "llama", general_type = general_type)
+ assert LlamaCppBackend._non_chat_gguf_refusal_for_path(str(path), None) is None
+
+
+def test_reading_a_model_clears_the_previous_adapter_type(tmp_path):
+ adapter = _write_gguf(tmp_path / "adapter.gguf", arch = "llama", general_type = "adapter")
+ model = _write_gguf(tmp_path / "model.gguf", arch = "llama")
+ backend = LlamaCppBackend()
+ backend._read_gguf_metadata(str(adapter))
+ assert backend._non_chat_gguf_refusal(str(adapter)) is not None
+ backend._read_gguf_metadata(str(model))
+ assert backend._non_chat_gguf_refusal(str(model)) is None
+
+
def test_image_arch_names_the_images_page(tmp_path):
_, message = _refusal(tmp_path, arch = "flux", name = "flux.gguf")
assert message is not None
diff --git a/studio/backend/tests/test_llama_cpp_remote_non_chat_gguf_preflight.py b/studio/backend/tests/test_llama_cpp_remote_non_chat_gguf_preflight.py
index 5dc24920a2f..38d45e64c56 100644
--- a/studio/backend/tests/test_llama_cpp_remote_non_chat_gguf_preflight.py
+++ b/studio/backend/tests/test_llama_cpp_remote_non_chat_gguf_preflight.py
@@ -25,19 +25,21 @@ def _gguf_bytes(
arch: str | None,
tensor_count: int = 1,
declared_kv: int | None = None,
+ general_type: str | None = None,
) -> bytes:
"""A GGUF header as BYTES. ``declared_kv`` overstates the KV count without writing the
pairs -- the shape a byte-range prefix of a chat model has: the counts say more is
coming and the buffer ends first."""
body = b""
kv_count = 0
- if arch is not None:
- key = b"general.architecture"
- val = arch.encode()
+ for key, value in ((b"general.architecture", arch), (b"general.type", general_type)):
+ if value is None:
+ continue
+ val = value.encode()
body += struct.pack("<Q", len(key)) + key
body += struct.pack("<I", 8)
body += struct.pack("<Q", len(val)) + val
- kv_count = 1
+ kv_count += 1
if declared_kv is not None:
kv_count = declared_kv
return struct.pack("<II", GGUF_MAGIC, 3) + struct.pack("<QQ", tensor_count, kv_count) + body
@@ -90,6 +92,27 @@ def test_a_media_repo_gguf_is_refused_from_its_header_alone(monkeypatch, arch, p
assert requests == [("owner/model", "model-Q4_K_M.gguf")]
+def test_adapter_repo_gguf_is_refused_from_its_header_alone(monkeypatch):
+ message, requests = _probe(
+ monkeypatch,
+ header = _gguf_bytes(arch = "deepseek41", general_type = "adapter"),
+ )
+ assert message is not None
+ assert "LoRA adapter" in message
+ assert "base model" in message
+ assert requests == [("owner/model", "model-Q4_K_M.gguf")]
+
+
+def test_adapter_type_is_refused_from_a_prefix_cut_mid_kv(monkeypatch):
+ # An adapter that embeds its tokenizer can outgrow the 256 KiB probe.
+ message, _ = _probe(
+ monkeypatch,
+ header = _gguf_bytes(arch = "phi3", general_type = "adapter", declared_kv = 32),
+ )
+ assert message is not None
+ assert "LoRA adapter" in message
+
+
def test_a_placeholder_arch_repo_gguf_is_refused(monkeypatch):
# gguf-connector writes a literal 'pig'; the probe must normalise it like the disk check.
message, _ = _probe(
@@ -228,7 +251,21 @@ def _repo_load(monkeypatch, backend, order):
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *_a, **_k: None)
-def test_a_media_repo_load_keeps_the_resident_model_and_never_downloads(monkeypatch):
+ "arch,general_type,repo,message_match",
+ [
+ ("wan", None, "unsloth/Wan2.2-TI2V-5B-GGUF", "Video page"),
+ (
+ "deepseek41",
+ "adapter",
+ "AtomicChat/DeepSeek-V4.1-Flash-1017-Uncensored-GGUF",
+ "LoRA adapter",
+ ),
+ ],
+)
+def test_a_non_chat_repo_load_keeps_the_resident_model_and_never_downloads(
+ monkeypatch, arch, general_type, repo, message_match
+):
backend = LlamaCppBackend()
order: list[str] = []
_repo_load(monkeypatch, backend, order)
@@ -236,15 +273,17 @@ def test_a_media_repo_load_keeps_the_resident_model_and_never_downloads(monkeypa
backend, "_download_gguf", lambda **_kwargs: order.append("download") or "/cache/m.gguf"
)
monkeypatch.setattr(
- diffusion_compat, "_read_gguf_header", lambda *_a, **_k: _gguf_bytes(arch = "wan")
+ diffusion_compat,
+ "_read_gguf_header",
+ lambda *_a, **_k: _gguf_bytes(arch = arch, general_type = general_type),
)
- with pytest.raises(ValueError, match = "Video page"):
+ with pytest.raises(ValueError, match = message_match):
backend.load_model(
GgufLoadIntent(
- hf_repo = "unsloth/Wan2.2-TI2V-5B-GGUF",
+ hf_repo = repo,
hf_variant = "Q4_K_M",
- model_identifier = "unsloth/Wan2.2-TI2V-5B-GGUF",
+ model_identifier = repo,
)
)