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: four load and update messages that told the user the wrong thing (#10383)

Daniel Han3a46167cbc14
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index bea65225515..f65b3c5cbc6 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -12602,6 +12602,70 @@ class LlamaCppBackend:
return total if total > 0 else None
return draft_kv + weights + target_ctx_copy + target_recurrent_copies
+ def _mtp_reserve_note(
+ self,
+ reserve_bytes: int,
+ *,
+ n_ctx: int,
+ n_parallel: int,
+ n_ubatch: Optional[int],
+ n_max: Optional[int],
+ target_rollback: bool,
+ flat_fallback: bool,
+ reprice: Optional[Callable[[int, int], int]] = None,
+ ) -> str:
+ """The MTP reserve line, naming only the dimensions that move the number.
+
+ Which ones bite is per-model, so ``reprice`` (the estimator the reserve came
+ from) is asked rather than re-deriving its branches; without it every
+ dimension is named, as before. n_max is not one of its arguments, so that one
+ stays structural. A None micro-batch is rendered as llama.cpp's default, since
+ "ubatch None" names no parameter.
+ """
+ ubatch = self._DEFAULT_N_UBATCH if n_ubatch is None else n_ubatch
+
+ def _moves(*candidates: tuple[int, int]) -> bool:
+ if reprice is None:
+ return True
+ try:
+ # The estimator's own value, not the total: a flat fallback reports 0.
+ base = reprice(n_parallel, ubatch)
+ for slots, ub in candidates:
+ if reprice(slots, ub) != base:
+ return True
+ except Exception:
+ # Cannot answer says nothing about the dependency: keep the name.
+ return True
+ return False
+
+ # Every slot count DIVIDING the padded total reproduces it: at 12288 cells 2, 3
+ # and 4 price the same, only 5 moves. The last candidate exceeds it, so cannot.
+ _cells = _pad_kv_cells(max(1, n_ctx)) // 256
+ slots_named = _moves(
+ (n_parallel + 1, ubatch),
+ (n_parallel + 2, ubatch),
+ (max(n_parallel + 3, n_parallel * 2), ubatch),
+ (max(n_parallel + 3, _cells + 1), ubatch),
+ )
+ # Same padding, via the compact-SWA window: a step of one bucket always crosses.
+ ubatch_named = _moves(
+ (n_parallel, ubatch * 2),
+ (n_parallel, max(1, ubatch // 2)),
+ (n_parallel, ubatch + 256),
+ )
+ scales_with_n_max = bool(
+ target_rollback and n_max and self._rollback_state_bytes(n_parallel) > 0
+ )
+ return (
+ f"MTP reserve: {reserve_bytes / (1024**3):.2f} GB "
+ f"(draft KV @ {n_ctx}"
+ + (f" x {n_parallel} slots" if slots_named else "")
+ + (f", ubatch {ubatch}" if ubatch_named else "")
+ + (f", n_max {n_max}" if scales_with_n_max else "")
+ + (", flat-frac fallback" if flat_fallback else "")
+ + "), "
+ )
+
_DEFAULT_N_UBATCH = _DEFAULT_LLAMA_N_UBATCH
_COMPUTE_BUFFER_SAFETY = 1.15 # upper-bound margin on the compute-buffer estimate
# Soft VRAM the modeled terms omit; charged to the fit budget on tight tiers (#6682).
@@ -16319,10 +16383,12 @@ class LlamaCppBackend:
"different model, or use this model directly through "
"Ollama instead."
)
+ # Not "cannot be run": unlike the branches above, this includes an arch the
+ # INSTALLED build predates (qwen4exp ran after a llama.cpp update).
return (
- f"llama.cpp does not support this GGUF's model architecture "
- f"('{arch}'). The file is valid, but this model type cannot "
- "be run with llama-server."
+ f"The installed llama.cpp does not recognise this GGUF's model "
+ f"architecture ('{arch}'). The file is valid. If the model is newer "
+ "than this llama.cpp build, updating llama.cpp may add support for it."
)
# Other Ollama compat failures that don't name an arch. Only when
@@ -21147,11 +21213,15 @@ class LlamaCppBackend:
else 0
)
if _mtp_will_engage:
- _mtp_note = (
- f"MTP reserve: {_mtp_reserve_bytes / (1024**3):.2f} GB "
- f"(draft KV @ {effective_ctx} + verify n_max={_mtp_eff_n_max}"
- + (", flat-frac fallback" if mtp_overhead_fn is None else "")
- + "), "
+ _mtp_note = self._mtp_reserve_note(
+ _mtp_reserve_bytes,
+ n_ctx = effective_ctx,
+ n_parallel = n_parallel or 1,
+ n_ubatch = _effective_ubatch,
+ n_max = _mtp_eff_n_max,
+ target_rollback = _target_rollback,
+ flat_fallback = mtp_overhead_fn is None,
+ reprice = lambda slots, ub: _mtp_bytes(effective_ctx, slots, ub),
)
else:
_mtp_note = ""
@@ -25724,9 +25794,13 @@ class LlamaCppBackend:
self._cancel_event.set()
with self._lock:
self._unload_epoch += 1
+ # Read before the kill clears it: callers unload from a finally either way.
+ _was_resident = self._process is not None
self._kill_process()
self._cleanup_cpu_fallback_runtime()
- logger.info(f"Unloaded GGUF model: {self._model_identifier}")
+ # The one unload line: routes/inference.py logged a second, differently named.
+ if _was_resident:
+ logger.info(f"Unloaded GGUF model: {self._model_identifier}")
self._model_identifier = None
self._gguf_path = None
self._gguf_load_identity = None
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 55c40c7e2a7..7f581c3a40a 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -15801,7 +15801,8 @@ async def _unload_model_impl(request: UnloadRequest, current_subject: str):
model = _lifecycle_model_label(_unloaded, _unloaded_variant),
reason = "manual",
)
- logger.info(f"Unloaded GGUF model: {request.model_path}")
+ # No log line here: unload_model emits one for every unload, and two
+ # under different names made the reload count ungreppable.
return UnloadResponse(status = "unloaded", model = request.model_path)
# Unload from Unsloth backend off the event loop: unload takes _gen_lock, which
diff --git a/studio/backend/tests/test_llama_backend_switch.py b/studio/backend/tests/test_llama_backend_switch.py
index 3181d39d5fb..b7c65757ecb 100644
--- a/studio/backend/tests/test_llama_backend_switch.py
+++ b/studio/backend/tests/test_llama_backend_switch.py
@@ -210,7 +210,7 @@ def test_a_backend_with_no_build_here_is_reported_by_name(monkeypatch, tmp_path)
job = _await_job()
assert job["state"] == "error"
- assert "Could not install the rocm llama.cpp build on this machine" in job["error"]
+ assert "Could not install a rocm llama.cpp build on this machine" in job["error"]
@pytest.mark.parametrize(
@@ -248,7 +248,40 @@ def test_update_failure_names_the_environment_pinned_backend(
job = _await_job()
assert job["state"] == "error"
- assert f"Could not install the {expected} llama.cpp build on this machine" in job["error"]
+ assert f"Could not install a {expected} llama.cpp build on this machine" in job["error"]
+
+
+def test_an_automatic_update_does_not_blame_a_backend_nobody_requested(monkeypatch, tmp_path):
+ """An update carries no backend_request, so failed_backend is None. The message
+ used to read "the requested llama.cpp build", which names a choice the user never
+ made: three consecutive failures in the field were reported that way, against a
+ log line that recorded only backend=null."""
+ install_dir = _install(monkeypatch, tmp_path)
+ monkeypatch.setattr(
+ upd,
+ "_plan_llama_phase",
+ lambda backend_request = None: {
+ "spec": {
+ "install_dir": install_dir,
+ "repo": "unslothai/llama.cpp",
+ "asset": None,
+ "script": tmp_path / "install_llama_prebuilt.py",
+ "pin_release_tag": "b9597-mix-new",
+ "from_tag": "b9596-mix-abc",
+ "llama_backend": "auto",
+ "rocm_gfx": None,
+ "backend_request": None,
+ }
+ },
+ )
+ _patch_installer(monkeypatch, returncode = upd._EXIT_BACKEND_UNAVAILABLE)
+
+ assert upd.start_update()["started"] is True
+ job = _await_job()
+
+ assert job["state"] == "error"
+ assert "Could not install a llama.cpp build on this machine" in job["error"]
+ assert "requested" not in job["error"]
def test_a_switch_rejects_a_cross_repository_result(monkeypatch, tmp_path):
diff --git a/studio/backend/tests/test_llama_cpp_start_failure_classification.py b/studio/backend/tests/test_llama_cpp_start_failure_classification.py
index 205368a3c35..c9045b61f13 100644
--- a/studio/backend/tests/test_llama_cpp_start_failure_classification.py
+++ b/studio/backend/tests/test_llama_cpp_start_failure_classification.py
@@ -132,6 +132,18 @@ class TestUnsupportedNonDiffusionArchitecture:
assert "enough memory" not in msg.lower()
assert "diffusion" not in msg.lower()
+ def test_an_unknown_llm_arch_points_at_the_build_not_at_the_file(self):
+ """The arch branches above name models llama-server will never run. This
+ one is everything else, and "cannot be run with llama-server" was wrong for
+ the case that actually reached users: a build older than the architecture.
+ Seen on qwen4exp, where the identical file loaded after a llama.cpp update
+ and ran for six days, and the user reinstalled four times in between."""
+ out = "error loading model: unknown model architecture: 'qwen4exp'"
+ msg = _classify(out, "/models/x.gguf", "local/x")
+ assert "qwen4exp" in msg
+ assert "updating llama.cpp" in msg.lower()
+ assert "cannot be run" not in msg.lower()
+
# Exact match: a chat arch merely containing a diffusion token (wan,
# sd1, flux, ...) must not be routed to the Images page.
@pytest.mark.parametrize(
@@ -151,7 +163,7 @@ class TestUnsupportedNonDiffusionArchitecture:
out = f"error loading model: unknown model architecture: '{arch}'"
msg = _classify(out, f"/models/{arch}.gguf", f"local/{arch}")
assert arch in msg
- assert "does not support" in msg.lower()
+ assert "does not recognise" in msg.lower()
assert "diffusion" not in msg.lower()
assert "Images page" not in msg
@@ -171,7 +183,7 @@ class TestOllamaAndFallback:
msg = _classify(out, self._OLLAMA_GGUF, "ollama/some-new")
assert "Ollama" in msg
assert "directly through Ollama" in msg
- assert "does not support" not in msg.lower()
+ assert "does not recognise" not in msg.lower()
def test_ollama_diffusion_arch_still_routes_to_images(self):
# Diffusion routing wins over the Ollama hint.
diff --git a/studio/backend/tests/test_mtp_reserve_note_and_unload_log.py b/studio/backend/tests/test_mtp_reserve_note_and_unload_log.py
new file mode 100644
index 00000000000..c6242a23e9e
--- /dev/null
+++ b/studio/backend/tests/test_mtp_reserve_note_and_unload_log.py
@@ -0,0 +1,215 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Two log lines that named the wrong thing: the MTP reserve naming parameters it
+is not a function of, and an unload event for a backend that held no model."""
+
+import os
+import sys
+
+import pytest
+
+_backend = os.path.join(os.path.dirname(__file__), "..")
+sys.path.insert(0, _backend)
+
+from core.inference import llama_cpp as llama_cpp_module # noqa: E402
+from core.inference.llama_cpp import LlamaCppBackend # noqa: E402
+
+
+def backend(monkeypatch):
+ monkeypatch.setattr(LlamaCppBackend, "_kill_orphaned_servers", lambda self: 0)
+ monkeypatch.setattr(llama_cpp_module.atexit, "register", lambda *_a, **_k: None)
+ return LlamaCppBackend()
+
+
+def _note(backend, **kwargs):
+ params = {
+ "n_ctx": 8192,
+ "n_parallel": 2,
+ "n_ubatch": None,
+ "n_max": 4,
+ "target_rollback": False,
+ "flat_fallback": False,
+ }
+ params.update(kwargs)
+ return backend._mtp_reserve_note(3 * 1024**3, **params)
+
+
+def test_the_default_micro_batch_is_rendered_not_printed_as_none(backend, monkeypatch):
+ # The estimators and the child both read None as llama.cpp's default, so the line
+ # must name that number.
+ monkeypatch.setattr(backend, "_rollback_state_bytes", lambda n_parallel = 1: 0)
+
+ assert f"ubatch {backend._DEFAULT_N_UBATCH}" in _note(backend)
+ assert "ubatch None" not in _note(backend)
+ assert "ubatch 1024" in _note(backend, n_ubatch = 1024)
+
+
+def test_n_max_is_named_exactly_where_it_moves_the_reserve(backend, monkeypatch):
+ # A Hybrid Mamba target allocates one rollback copy per drafted token, so the
+ # reserve scales with n_max there and nowhere else.
+ monkeypatch.setattr(backend, "_rollback_state_bytes", lambda n_parallel = 1: 64 * 1024**2)
+ assert "n_max 4" in _note(backend, target_rollback = True)
+
+ assert "n_max" not in _note(backend, target_rollback = False)
+
+ # Rollback wanted, but no recurrent state to copy.
+ monkeypatch.setattr(backend, "_rollback_state_bytes", lambda n_parallel = 1: 0)
+ assert "n_max" not in _note(backend, target_rollback = True)
+
+
+def test_the_note_still_names_the_context_slots_and_the_fallback(backend, monkeypatch):
+ monkeypatch.setattr(backend, "_rollback_state_bytes", lambda n_parallel = 1: 0)
+ note = _note(backend, flat_fallback = True)
+
+ # No estimator to ask, so every dimension is named -- what the line always did.
+ assert note.startswith("MTP reserve: 3.00 GB (draft KV @ 8192 x 2 slots")
+ assert "flat-frac fallback" in note
+
+
+def test_slots_and_ubatch_are_named_only_where_they_move_the_reserve(backend, monkeypatch):
+ # A dense embedded head under a unified cache reads neither: one stream is
+ # padded_ctx cells at any slot count, and n_ubatch is not read on that branch.
+ monkeypatch.setattr(backend, "_rollback_state_bytes", lambda n_parallel = 1: 0)
+ flat = _note(backend, reprice = lambda slots, ub: 3 * 1024**3)
+ assert flat.startswith("MTP reserve: 3.00 GB (draft KV @ 8192)")
+ assert "slots" not in flat and "ubatch" not in flat
+
+ # A separate drafter's KV follows both, so both come back.
+ both = _note(backend, reprice = lambda slots, ub: 3 * 1024**3 + slots * ub)
+ assert "x 2 slots" in both and f"ubatch {backend._DEFAULT_N_UBATCH}" in both
+
+ # One axis at a time, so a single flag cannot be standing in for the pair.
+ assert "x 2 slots" in _note(backend, reprice = lambda slots, ub: 3 * 1024**3 + slots)
+ assert "ubatch" not in _note(backend, reprice = lambda slots, ub: 3 * 1024**3 + slots)
+ assert "slots" not in _note(backend, reprice = lambda slots, ub: 3 * 1024**3 + ub)
+ assert "ubatch" in _note(backend, reprice = lambda slots, ub: 3 * 1024**3 + ub)
+
+
+def test_a_single_slot_launch_still_probes_a_distinct_slot_count(backend, monkeypatch):
+ # At n_parallel 1 "double it" is also "+1", so the pair probes one point: a real
+ # 8192-cell context splits 1 x 8192 and 2 x 4096, then 3 x 2816.
+ monkeypatch.setattr(backend, "_rollback_state_bytes", lambda n_parallel = 1: 0)
+
+ def _cells(slots, _ub):
+ _, streams, per_stream = llama_cpp_module._kv_cache_cell_layout(8192, slots, False)
+ return streams * per_stream
+
+ assert _cells(1, 0) == _cells(2, 0) and _cells(3, 0) != _cells(1, 0), "premise moved"
+
+ note = _note(backend, n_parallel = 1, reprice = _cells)
+ assert "x 1 slots" in note
+
+
+def test_the_slot_probe_escapes_a_padding_plateau(backend, monkeypatch):
+ # At n_ctx 12288, 2, 3 and 4 slots all price 12288 cells and only 5 moves.
+ monkeypatch.setattr(backend, "_rollback_state_bytes", lambda n_parallel = 1: 0)
+
+ def _cells(slots, _ub):
+ _, streams, per_stream = llama_cpp_module._kv_cache_cell_layout(12288, slots, False)
+ return streams * per_stream
+
+ assert [_cells(s, 0) for s in (2, 3, 4)] == [12288] * 3, "premise moved"
+ assert _cells(5, 0) != 12288
+
+ note = _note(backend, n_ctx = 12288, n_parallel = 2, reprice = _cells)
+ assert "x 2 slots" in note
+
+ # The control: a slot-independent reserve stays unnamed however far it reaches.
+ flat = _note(backend, n_ctx = 12288, n_parallel = 2, reprice = lambda slots, ub: 3 * 1024**3)
+ assert "slots" not in flat
+
+
+def test_the_ubatch_probe_escapes_a_padding_plateau(backend, monkeypatch):
+ # Through the same padding, as a compact-SWA term: a value and its double share
+ # a bucket, so halving and doubling cannot see it.
+ monkeypatch.setattr(backend, "_rollback_state_bytes", lambda n_parallel = 1: 0)
+
+ def _window(_slots, ub):
+ return llama_cpp_module._pad_kv_cells(1024 + ub)
+
+ assert _window(1, 64) == _window(1, 128) == _window(1, 32), "premise moved"
+ assert _window(1, 64 + 256) != _window(1, 64)
+
+ note = _note(backend, n_ubatch = 64, reprice = _window)
+ assert "ubatch 64" in note
+
+ # The control: a reserve the micro-batch does not reach stays unnamed.
+ flat = _note(backend, n_ubatch = 64, reprice = lambda slots, ub: 3 * 1024**3)
+ assert "ubatch" not in flat
+
+
+def test_an_estimator_that_cannot_answer_keeps_the_dimension_named(backend, monkeypatch):
+ # Dropping a name on a raise would under-report a real dependency.
+ monkeypatch.setattr(backend, "_rollback_state_bytes", lambda n_parallel = 1: 0)
+
+ def _raises(slots, ub):
+ raise RuntimeError("unsized")
+
+ note = _note(backend, reprice = _raises)
+ assert "x 2 slots" in note and "ubatch" in note
+
+
+def test_an_unload_with_nothing_resident_logs_no_unload_event(backend, monkeypatch):
+ # Callers unload from a finally either way, and a spurious event makes "how many
+ # times did this model reload" unanswerable by grep.
+ seen: list = []
+ monkeypatch.setattr(llama_cpp_module.logger, "info", lambda msg, *a, **k: seen.append(msg))
+
+ backend.unload_model()
+
+ assert not [line for line in seen if "Unloaded GGUF model" in str(line)]
+
+
+def test_an_unload_of_a_resident_model_still_logs_one_event(backend, monkeypatch):
+ # The control: a fix that silenced the line entirely would pass above.
+ seen: list = []
+ monkeypatch.setattr(llama_cpp_module.logger, "info", lambda msg, *a, **k: seen.append(msg))
+ # Not a Popen: _kill_process treats a non-terminable stand-in as loaded.
+ backend._process = object()
+ backend._model_identifier = "unsloth/B-GGUF:Q4_K_M"
+
+ backend.unload_model()
+
+ assert [line for line in seen if "Unloaded GGUF model: unsloth/B-GGUF:Q4_K_M" in str(line)]
+
+
+def test_the_real_estimator_ignores_both_axes_for_a_dense_embedded_head(backend):
+ """The premise the note now asks about, pinned against the estimator itself.
+
+ Without this the note's tests would only prove it renders whatever a stand-in
+ tells it, and the claim that slots and ubatch really are inert on this branch
+ would rest on reading the code.
+ """
+ backend._nextn_predict_layers = 1
+ backend._n_kv_heads = 8
+ backend._n_heads = 64
+ backend._kv_key_length = 128
+ backend._kv_value_length = 128
+ backend._kv_lora_rank = None # not MLA: no duplicated target context
+ backend._architecture = "qwen3moe"
+
+ def _reserve(n_parallel, n_ubatch):
+ return backend._estimate_mtp_overhead_bytes(
+ 8192,
+ spec_draft_n_max = 4,
+ n_parallel = n_parallel,
+ kv_unified = True,
+ n_ubatch = n_ubatch,
+ )
+
+ base = _reserve(2, 512)
+ assert base and base > 0
+ assert _reserve(3, 512) == base
+ assert _reserve(4, 512) == base
+ assert _reserve(2, 1024) == base
+ assert _reserve(2, 256) == base
+
+ # The control: non-unified pads each stream, so a slot count the context does not
+ # divide does move the number. Three, not two: at two the halves pad back to the
+ # unified total and the control would pass for the wrong reason.
+ split = backend._estimate_mtp_overhead_bytes(
+ 8192, spec_draft_n_max = 4, n_parallel = 3, kv_unified = False, n_ubatch = 512
+ )
+ assert split != base
diff --git a/studio/backend/utils/llama_cpp_update.py b/studio/backend/utils/llama_cpp_update.py
index f169978632e..56bcd121552 100644
--- a/studio/backend/utils/llama_cpp_update.py
+++ b/studio/backend/utils/llama_cpp_update.py
@@ -832,14 +832,20 @@ def _run_llama_phase(
if exc.returncode == _EXIT_BACKEND_UNAVAILABLE:
# This can race hardware or release changes after option resolution.
failed_backend = backend_request or _env_backend_override()
+ # "requested" reads as the user's choice; an automatic update has none.
backend_label = (
- failed_backend
+ f"{failed_backend} "
if failed_backend is not None and failed_backend != "auto"
- else "requested"
+ else ""
+ )
+ # The reason, as every sibling branch does: otherwise the record is "null".
+ logger.warning(
+ "llama update: backend unavailable",
+ backend = failed_backend,
+ error = str(exc),
)
- logger.warning("llama update: backend unavailable", backend = failed_backend)
raise _LlamaPhaseError(
- f"Could not install the {backend_label} llama.cpp build on this machine. "
+ f"Could not install a {backend_label}llama.cpp build on this machine. "
"The installed backend was kept.",
reload_required = model_was_active,
) from exc