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: route AMD integrated GPUs to the Vulkan llama.cpp prebuilt (#10381)

Daniel Han8b369281f0ae
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 7f581c3a40a..d7eaa0f9806 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -8288,6 +8288,7 @@ async def _maybe_auto_switch_model(
# "<path>:LABEL" is read too, after the bare path used today.
from utils.openai_auto_switch_settings import (
resolve_override_for_load,
+ stored_gpu_index_kind,
)
# The candidate order above, kept in one place so the panel
@@ -8301,10 +8302,10 @@ async def _maybe_auto_switch_model(
)
saved_gpu_ids = load_kwargs.get("gpu_ids")
if saved_gpu_ids and not await _override_gpu_ids_still_resolve(
- saved_gpu_ids
+ saved_gpu_ids, stored_gpu_index_kind(override)
):
- # Stale pin (GPU removed, another host): drop the one dead
- # field rather than 400 the whole load.
+ # Stale pin (GPU removed, another host, or a backend change
+ # renumbering these ids): drop it rather than 400 the load.
load_kwargs.pop("gpu_ids", None)
logger.warning(
"Dropping saved gpu_ids %s for %s: not available here.",
@@ -11379,13 +11380,24 @@ def _classify_diffusion_gguf(config: ModelConfig) -> Optional[bool]:
return True if name_says_diffusion else None
-async def _override_gpu_ids_still_resolve(gpu_ids: List[int]) -> bool:
+async def _override_gpu_ids_still_resolve(
+ gpu_ids: List[int], stored_index_kind: str = "physical"
+) -> bool:
"""Whether a per-model GPU pin is usable on this machine right now.
normalize_model_override cannot know the device list, so it stores whatever
was valid where the config was written. This is the load-time reconciliation
for the device-availability rules, which are the ones that go stale.
+ ``stored_index_kind`` is the namespace those ids were written in, and it is checked
+ before availability because the two failures look nothing alike: an id that no longer
+ exists is caught below, while an id that still exists in the OTHER index space pins a
+ different device and every availability check passes. A Vulkan build numbers devices by
+ compact ggml ordinal and a CUDA/ROCm build by physical id, and a host moves between them
+ -- an AMD integrated GPU is routed to the Vulkan prebuilt by preference. Mirrors
+ reconcileGpuSelection in the UI (hooks/gpu-selection.ts), which drops the pin on the
+ same mismatch.
+
Deliberately not exhaustive: model-dependent rules (a Vulkan diffusion GGUF
refuses gpu_ids outright) need a ModelConfig this has no reason to build.
The caller's retry-without-the-pin covers those, and covers rules added
@@ -11406,6 +11418,8 @@ async def _override_gpu_ids_still_resolve(gpu_ids: List[int]) -> bool:
)
device, is_vulkan, resolved = await asyncio.to_thread(_device_and_resolution)
+ if stored_index_kind != ("vulkan" if is_vulkan else "physical"):
+ return False
if device == DeviceType.XPU and not is_vulkan:
# Rejected outright on XPU.
return False
diff --git a/studio/backend/routes/llama.py b/studio/backend/routes/llama.py
index e2303ae35f5..fa0487c2649 100644
--- a/studio/backend/routes/llama.py
+++ b/studio/backend/routes/llama.py
@@ -113,6 +113,20 @@ class LlamaUpdateStatusResponse(BaseModel):
update_size_bytes: Optional[int] = Field(
None, description = "Download size of the prebuilt Update would fetch, in bytes."
)
+ backend_migration_available: bool = Field(
+ False,
+ description = (
+ "True when the install recorded an AUTOMATIC backend choice and detection "
+ "now resolves elsewhere, so Update would move it. Independent of "
+ "update_available: the release can be current while the backend has drifted."
+ ),
+ )
+ from_backend: Optional[str] = Field(
+ None, description = "Installed backend, when a migration is available."
+ )
+ to_backend: Optional[str] = Field(
+ None, description = "Backend a re-applied automatic selection would install."
+ )
whisper: Optional[WhisperSubStatus] = Field(
None, description = "Whisper piggyback sub-status; None when the probe is unavailable."
)
diff --git a/studio/backend/routes/settings.py b/studio/backend/routes/settings.py
index aae36f59eae..9060229d679 100644
--- a/studio/backend/routes/settings.py
+++ b/studio/backend/routes/settings.py
@@ -812,6 +812,9 @@ class ModelOverridePayload(BaseModel):
gpu_layers: Optional[int] = Field(default = None, ge = -1, le = 1024)
n_cpu_moe: Optional[int] = Field(default = None, ge = 0, le = 1024)
gpu_ids: Optional[list[int]] = Field(default = None, max_length = MAX_GPU_IDS)
+ # Which index space gpu_ids is in. Absent means physical, the only thing a client
+ # written before this field could have meant.
+ gpu_index_kind: Optional[Literal["physical", "vulkan"]] = None
# An all-default save carries no fields, like a forget; None keeps the legacy contract.
remove: Optional[bool] = None
# Fill in, don't replace: the backfill reads the map once then writes each model.
@@ -1801,6 +1804,7 @@ def update_openai_auto_switch_override(
gpu_layers = payload.gpu_layers,
n_cpu_moe = payload.n_cpu_moe,
gpu_ids = payload.gpu_ids,
+ gpu_index_kind = payload.gpu_index_kind,
fill_absent_fields = payload.fill_absent_fields,
)
# A repo cached outside the active HF cache is keyed here by its repo id
diff --git a/studio/backend/storage/studio_db.py b/studio/backend/storage/studio_db.py
index 4e4a27308b3..be5d0ef95ce 100644
--- a/studio/backend/storage/studio_db.py
+++ b/studio/backend/storage/studio_db.py
@@ -4539,6 +4539,7 @@ def upsert_app_setting_map_entry(
entry_value: dict[str, Any] | None,
*,
fill_absent_fields: bool = False,
+ coupled_fields: tuple[tuple[str, ...], ...] = (),
) -> dict[str, Any]:
"""Set (or delete, when entry_value is falsy) one sub-entry of a dict-valued
app setting, atomically under BEGIN IMMEDIATE so concurrent writers to other
@@ -4552,6 +4553,12 @@ def upsert_app_setting_map_entry(
backfill, whose contract is that the server copy is the newer authority: an
upgraded install can hold an entry with only the fields an older release knew,
while this browser holds the rest, and entry-level skipping would strand them.
+
+ ``coupled_fields`` names groups that only mean anything together. Field-by-field
+ filling would otherwise take a qualifier from this browser and leave the value it
+ qualifies as the server wrote it: a stored ``gpu_ids`` in one index space, relabelled
+ with the other space's ``gpu_index_kind``, points at a different GPU while looking
+ stored. A group any part of which is already held is skipped whole.
"""
conn = get_connection()
try:
@@ -4566,8 +4573,12 @@ def upsert_app_setting_map_entry(
return current
stored = current.get(entry_key)
if isinstance(stored, dict):
+ incoming = entry_value
+ for group in coupled_fields:
+ if any(field in stored for field in group):
+ incoming = {k: v for k, v in incoming.items() if k not in group}
# Stored values win field by field, so this only adds.
- merged = {**entry_value, **stored}
+ merged = {**incoming, **stored}
if merged == stored:
conn.rollback()
return current
diff --git a/studio/backend/tests/test_combined_update.py b/studio/backend/tests/test_combined_update.py
index b62ff266bda..2934461d578 100644
--- a/studio/backend/tests/test_combined_update.py
+++ b/studio/backend/tests/test_combined_update.py
@@ -97,7 +97,12 @@ def _patch_llama_installer(
# Only intercept the installer invocation: importing routes.inference inside
# the worker can Popen unrelated host probes (ldconfig etc).
def _popen(cmd, **kw):
- is_installer = any("install_llama_prebuilt" in str(part) for part in cmd)
+ parts = [str(part) for part in cmd]
+ # The read-only resolvers run the same script, so faking them would answer the
+ # backend-drift probe with an install's canned output.
+ is_installer = any("install_llama_prebuilt" in part for part in parts) and not any(
+ part.startswith("--resolve-") for part in parts
+ )
return _FakeInstallerPopen(
cmd,
returncode = returncode if is_installer else 0,
@@ -157,6 +162,7 @@ def _clean_state(monkeypatch, tmp_path):
wfresh.reset_caches()
upd._reset_job_for_tests()
upd._resolve_memo.clear()
+ upd._backends_memo.clear()
wupd._resolve_memo.clear()
monkeypatch.setattr(freshness, "_cache_dir", lambda: tmp_path / ".llama_cache")
monkeypatch.setattr(wfresh, "_cache_dir", lambda: tmp_path / ".whisper_cache")
@@ -175,6 +181,7 @@ def _clean_state(monkeypatch, tmp_path):
wfresh.reset_caches()
upd._reset_job_for_tests()
upd._resolve_memo.clear()
+ upd._backends_memo.clear()
wupd._resolve_memo.clear()
@@ -752,6 +759,61 @@ def _slim_phase(**over):
return phase
+def _llama_installed_as(monkeypatch, backend, asset, *, whisper_kind):
+ monkeypatch.setattr(wupd, "_installed_llama_bundle", lambda: (backend, asset))
+ monkeypatch.setattr(wupd, "_find_binary", lambda: "whisper-server")
+ monkeypatch.setattr(
+ wupd, "read_install_marker", lambda _b: {"install_kind": whisper_kind, "backend": "rocm"}
+ )
+
+
+def test_a_migrated_llama_re_pairs_the_chained_phase(monkeypatch):
+ """The plan named the backend whisper was installed against, and the llama phase has
+ since replaced it: a slim install would hardlink a ggml that is no longer there."""
+ seen = {}
+ monkeypatch.setattr(
+ wupd,
+ "_resolve_prebuilt_for_host",
+ lambda **kw: seen.update(kw) or {"prebuilt_available": True},
+ )
+ monkeypatch.setattr(wupd, "run_chained_phase", lambda phase, _sp: dict(phase))
+ _llama_installed_as(
+ monkeypatch, "vulkan", "llama-b1-bin-win-vulkan-x64.zip", whisper_kind = "slim"
+ )
+
+ installed = wupd.run_chained_phase_after_llama(_slim_phase(backend = "rocm"), lambda _f: None)
+ assert seen["backend"] == "vulkan"
+ assert installed["backend"] == "vulkan"
+ assert installed["asset"] == "llama-b1-bin-win-vulkan-x64.zip"
+
+
+def test_a_self_contained_install_keeps_its_own_backend(monkeypatch):
+ """The control: only a slim install rides llama's ggml, so only it follows the
+ migration. A fat one carries its own and llama's backend is not its backend."""
+ monkeypatch.setattr(
+ wupd, "_resolve_prebuilt_for_host", lambda **_kw: {"prebuilt_available": True}
+ )
+ monkeypatch.setattr(wupd, "run_chained_phase", lambda phase, _sp: dict(phase))
+ _llama_installed_as(monkeypatch, "vulkan", "vulkan.zip", whisper_kind = "fat")
+
+ installed = wupd.run_chained_phase_after_llama(_slim_phase(backend = "rocm"), lambda _f: None)
+ assert installed["backend"] == "rocm"
+
+
+def test_an_ordinary_update_leaves_the_phase_alone(monkeypatch):
+ """No migration, no re-pair: the backend the plan named is the one llama still has."""
+ monkeypatch.setattr(
+ wupd, "_resolve_prebuilt_for_host", lambda **_kw: {"prebuilt_available": True}
+ )
+ monkeypatch.setattr(wupd, "run_chained_phase", lambda phase, _sp: dict(phase))
+ _llama_installed_as(monkeypatch, "rocm", "rocm-new.zip", whisper_kind = "slim")
+
+ installed = wupd.run_chained_phase_after_llama(
+ _slim_phase(backend = "rocm", asset = "rocm-old.zip"), lambda _f: None
+ )
+ assert (installed["backend"], installed["asset"]) == ("rocm", "rocm-old.zip")
+
+
def test_a_slim_pairing_gap_skips_instead_of_failing_the_job(monkeypatch):
"""The state the pipeline was in for ten days: no whisper release paired to the
llama being installed, so the phase exits 2 and fails a job llama already won."""
diff --git a/studio/backend/tests/test_install_resolve_prebuilt.py b/studio/backend/tests/test_install_resolve_prebuilt.py
index 5989188b847..2a887936a40 100644
--- a/studio/backend/tests/test_install_resolve_prebuilt.py
+++ b/studio/backend/tests/test_install_resolve_prebuilt.py
@@ -16,6 +16,7 @@ from __future__ import annotations
import dataclasses
import importlib
import json
+import os
import sys
from pathlib import Path
from types import SimpleNamespace
@@ -31,6 +32,9 @@ ilp = importlib.import_module("install_llama_prebuilt")
if not hasattr(ilp, "resolve_simple_install_release_plans"):
pytest.skip("PR symbols not present - check branch", allow_module_level = True)
+# Captured before the autouse fixture stubs it, so the probe's own tests reach the real one.
+_REAL_AMD_VULKAN_ICD_PRESENT = ilp._amd_vulkan_icd_present
+
FORK = ilp.DEFAULT_PUBLISHED_REPO # unslothai/llama.cpp
UPSTREAM = ilp.UPSTREAM_REPO # ggml-org/llama.cpp
@@ -47,6 +51,16 @@ def _no_ambient_hip_device_mask(monkeypatch):
monkeypatch.delenv(_env, raising = False)
[email protected](autouse = True)
+def _no_amd_vulkan_icd(monkeypatch):
+ """Same reason as the mask fixture: describe the host through HostInfo, not the box.
+
+ The probe reads this machine's real manifests, and mesa ships radeon_icd.json on hosts
+ with no AMD GPU, so leaving it live makes the route fire or not per developer. Absent
+ is the pre-route answer; the tests about it turn it on explicitly."""
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", lambda: False)
+
+
def _host(**kw):
base = dict(
system = "Linux",
@@ -1655,6 +1669,19 @@ def test_route_to_vulkan_prebuilt_keeps_every_fork_windows_rocm_arch(gfx, monkey
assert persist is None
[email protected]("gfx", sorted(ilp.VULKAN_PREFERRED_GFX_TARGETS))
+def test_the_integrated_archs_are_the_one_exception_to_that_sweep(gfx, monkeypatch):
+ monkeypatch.delenv("UNSLOTH_LLAMA_CPP_BACKEND", raising = False)
+ monkeypatch.delenv("UNSLOTH_FORCE_VULKAN", raising = False)
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", lambda: True)
+ assert gfx in ilp.WINDOWS_HIP_PREBUILT_GFX_TARGETS, "a preference, not a missing bundle"
+ host = _windows_amd_host(rocm_gfx_target = gfx, rocm_gfx_targets = [gfx])
+ routed, repo, tag, persist = ilp._route_to_vulkan_prebuilt(host, FORK, "pin", force_cpu = False)
+ assert routed.has_rocm is False
+ assert (repo, tag) == (FORK, "pin")
+ assert persist == "auto"
+
+
def test_forwarded_gfx_does_not_undo_visible_device_auto_vulkan(monkeypatch):
# Mixed-AMD Windows host: GPU 0 = gfx1100 (HIP prebuilt exists), GPU 1 = gfx1010 (none).
# Under CUDA_VISIBLE_DEVICES=1 setup.ps1 still resolves GPU 0 and forwards gfx1100, but
@@ -1743,14 +1770,586 @@ def test_forwarded_gfx_still_fills_an_unprobed_arch(monkeypatch):
monkeypatch.delenv("UNSLOTH_FORCE_VULKAN", raising = False)
monkeypatch.delenv("UNSLOTH_ROCM_GFX_ARCH", raising = False)
host = _windows_amd_host(rocm_gfx_target = None, rocm_gfx_targets = [])
- host = ilp._apply_host_overrides(host, override_rocm_gfx = "gfx1151")
- assert ilp._active_rocm_gfx_target(host) == "gfx1151"
+ host = ilp._apply_host_overrides(host, override_rocm_gfx = "gfx1100")
+ assert ilp._active_rocm_gfx_target(host) == "gfx1100"
assert ilp._should_auto_vulkan_for_amd_windows(host) is False
_routed, repo, _tag, persist = ilp._route_to_vulkan_prebuilt(host, FORK, "pin", force_cpu = False)
assert repo == FORK
assert persist is None
+def amd_vulkan_icd(monkeypatch):
+ """This host has an AMD Vulkan driver, the precondition for the integrated route."""
+ monkeypatch.delenv("UNSLOTH_LLAMA_CPP_BACKEND", raising = False)
+ monkeypatch.delenv("UNSLOTH_FORCE_VULKAN", raising = False)
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", lambda: True)
+
+
+def _amd_host(*, windows, **overrides):
+ if windows:
+ return _windows_amd_host(**overrides)
+ defaults = dict(
+ system = "Linux",
+ machine = "x86_64",
+ is_linux = True,
+ is_x86_64 = True,
+ has_rocm = True,
+ )
+ defaults.update(overrides)
+ return _host(**defaults)
+
+
[email protected]("windows", [True, False])
[email protected]("gfx", sorted(ilp.VULKAN_PREFERRED_GFX_TARGETS))
+def test_integrated_amd_prefers_vulkan_on_both_platforms(gfx, windows, amd_vulkan_icd):
+ # Not Windows-only, unlike the #7357 fallback: the Linux fault is the more severe.
+ host = _amd_host(windows = windows, rocm_gfx_target = gfx, rocm_gfx_targets = [gfx])
+ assert ilp._should_prefer_vulkan_for_amd_igpu(host) is True
+ routed, repo, tag, persist = ilp._route_to_vulkan_prebuilt(host, FORK, "pin", force_cpu = False)
+ assert routed.has_rocm is False
+ assert routed.has_intel_gpu is True
+ assert (repo, tag) == (FORK, "pin")
+ # Automatic, so the marker keeps rocm_gfx and re-selecting ROCm finds its bundle.
+ assert persist == "auto"
+
+
+def test_integrated_amd_keeps_rocm_without_an_amd_vulkan_driver(monkeypatch):
+ monkeypatch.delenv("UNSLOTH_LLAMA_CPP_BACKEND", raising = False)
+ monkeypatch.delenv("UNSLOTH_FORCE_VULKAN", raising = False)
+ host = _windows_amd_host(rocm_gfx_target = "gfx1151", rocm_gfx_targets = ["gfx1151"])
+ assert ilp._should_prefer_vulkan_for_amd_igpu(host) is False
+ routed, _repo, _tag, persist = ilp._route_to_vulkan_prebuilt(host, FORK, "pin", force_cpu = False)
+ assert routed is host
+ assert persist is None
+
+
[email protected]("gfx", ["gfx908", "gfx90a", "gfx1030", "gfx1100", "gfx1201"])
+def test_only_the_integrated_archs_are_preferred_onto_vulkan(gfx, amd_vulkan_icd):
+ # Why this is an allowlist: ROCm ships no Vulkan ICD, so CDNA would get a dead backend
+ # rather than a slower one, and discrete RDNA is unmeasured.
+ host = _windows_amd_host(rocm_gfx_target = gfx, rocm_gfx_targets = [gfx])
+ assert ilp._should_prefer_vulkan_for_amd_igpu(host) is False
+ routed, _repo, _tag, persist = ilp._route_to_vulkan_prebuilt(host, FORK, "pin", force_cpu = False)
+ assert routed is host
+ assert persist is None
+
+
+def test_a_discrete_card_beside_the_apu_keeps_the_whole_host_on_rocm(amd_vulkan_icd):
+ # Judged over every physical gfx: Vulkan honours no HIP mask, so routing here would
+ # hand the discrete card over too.
+ host = _windows_amd_host(
+ rocm_gfx_target = "gfx1151",
+ rocm_gfx_targets = ["gfx1151", "gfx1100"],
+ )
+ assert ilp._should_prefer_vulkan_for_amd_igpu(host) is False
+
+
+def test_integrated_route_declines_beside_a_physical_nvidia_card(amd_vulkan_icd):
+ host = _windows_amd_host(
+ rocm_gfx_target = "gfx1151",
+ rocm_gfx_targets = ["gfx1151"],
+ has_physical_nvidia = True,
+ )
+ assert ilp._should_prefer_vulkan_for_amd_igpu(host) is False
+
+
+def test_integrated_route_declines_under_a_vulkan_device_mask(amd_vulkan_icd, monkeypatch):
+ # An ICD proves a driver, not that this process sees the device: a mask excluding the
+ # APU enumerates nothing.
+ host = _windows_amd_host(rocm_gfx_target = "gfx1151", rocm_gfx_targets = ["gfx1151"])
+ monkeypatch.setenv("GGML_VK_VISIBLE_DEVICES", "1")
+ assert ilp._should_prefer_vulkan_for_amd_igpu(host) is False
+
+ monkeypatch.delenv("GGML_VK_VISIBLE_DEVICES")
+ assert ilp._should_prefer_vulkan_for_amd_igpu(host) is True
+
+
+ "mask_env", ["HIP_VISIBLE_DEVICES", "ROCR_VISIBLE_DEVICES", "CUDA_VISIBLE_DEVICES"]
+)
+def test_integrated_route_declines_under_a_hip_device_mask(mask_env, amd_vulkan_icd, monkeypatch):
+ # Under a mask the inventory is unknowable, so "every GPU is integrated" is unprovable.
+ monkeypatch.setenv(mask_env, "0")
+ host = _windows_amd_host(rocm_gfx_target = "gfx1151", rocm_gfx_targets = ["gfx1151"])
+ assert ilp._should_prefer_vulkan_for_amd_igpu(host) is False
+
+
[email protected]("backend", ["rocm", "cpu", "cuda"])
+def test_an_explicit_backend_opts_out_of_the_integrated_route(backend, amd_vulkan_icd):
+ host = _windows_amd_host(rocm_gfx_target = "gfx1151", rocm_gfx_targets = ["gfx1151"])
+ routed, _repo, _tag, persist = ilp._route_to_vulkan_prebuilt(
+ host, FORK, "pin", force_cpu = False, llama_backend = backend
+ )
+ assert routed is host
+ assert persist is None
+
+
+def test_forced_vulkan_on_an_integrated_host_persists_as_automatic(amd_vulkan_icd):
+ host = _windows_amd_host(rocm_gfx_target = "gfx1151", rocm_gfx_targets = ["gfx1151"])
+ _routed, _repo, _tag, persist = ilp._route_to_vulkan_prebuilt(
+ host, FORK, "pin", force_cpu = False, llama_backend = "vulkan"
+ )
+ assert persist == "auto"
+
+
+def test_force_cpu_wins_over_the_integrated_route(amd_vulkan_icd):
+ host = _windows_amd_host(rocm_gfx_target = "gfx1151", rocm_gfx_targets = ["gfx1151"])
+ routed, _repo, _tag, persist = ilp._route_to_vulkan_prebuilt(host, FORK, "pin", force_cpu = True)
+ assert routed is host
+ assert persist is None
+
+
+def test_route_backend_request_keeps_the_arch_for_a_migrated_integrated_host(amd_vulkan_icd):
+ # Read before the route rewrites the host to Vulkan-only; after it the marker loses
+ # the arch and the next update re-detects a ROCm-less host.
+ host = _windows_amd_host(rocm_gfx_target = "gfx1151", rocm_gfx_targets = ["gfx1151"])
+ route = ilp.route_backend_request(
+ backend = None, published_repo = FORK, published_release_tag = "pin", host = host
+ )
+ assert route.host.has_rocm is False
+ assert route.persist_llama_backend == "auto"
+ assert route.persist_rocm_gfx == "gfx1151"
+
+
+def test_route_backend_request_keeps_rocm_as_the_fallback_for_the_preference(amd_vulkan_icd):
+ # _vulkan_only_host clears has_rocm, so uncarried the selectors read this box as CPU
+ # and a bad Vulkan asset installs CPU inference.
+ host = _windows_amd_host(rocm_gfx_target = "gfx1151", rocm_gfx_targets = ["gfx1151"])
+ route = ilp.route_backend_request(
+ backend = None, published_repo = FORK, published_release_tag = "pin", host = host
+ )
+ assert route.rocm_fallback_host is not None
+ assert route.rocm_fallback_host.has_rocm is True
+ assert route.rocm_fallback_host.rocm_gfx_target == "gfx1151"
+
+
+def test_route_backend_request_carries_no_rocm_fallback_for_the_no_hip_route(monkeypatch):
+ # Keeps the two routes apart: #7357 turns to Vulkan because no HIP prebuilt covers the
+ # arch, so a fallback would name a bundle this box cannot run.
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", lambda: False)
+ host = _windows_amd_host(rocm_gfx_target = "gfx900", rocm_gfx_targets = ["gfx900"])
+ route = ilp.route_backend_request(
+ backend = None, published_repo = FORK, published_release_tag = "pin", host = host
+ )
+ assert route.host.has_rocm is False, "the #7357 route should still have fired"
+ assert route.rocm_fallback_host is None
+
+
+def test_the_preference_plan_tries_rocm_before_the_cpu_fallback(monkeypatch, amd_vulkan_icd):
+ plan_calls: list[bool] = []
+
+ def _plans(_tag, plan_host, _repo, _release, **_kw):
+ plan_calls.append(bool(plan_host.has_rocm))
+ kinds = ["windows-hip"] if plan_host.has_rocm else ["windows-vulkan", "windows-cpu"]
+ return "b1", [
+ ilp.InstallReleasePlan(
+ requested_tag = "b1",
+ llama_tag = "b1",
+ release_tag = "b1",
+ attempts = [
+ ilp.AssetChoice(
+ repo = FORK,
+ tag = "b1",
+ name = k,
+ url = f"https://x/{k}",
+ source_label = "test",
+ install_kind = k,
+ )
+ for k in kinds
+ ],
+ approved_checksums = {},
+ )
+ ]
+
+ monkeypatch.setattr(ilp, "resolve_simple_install_release_plans", _plans)
+ host = _windows_amd_host(rocm_gfx_target = "gfx1151", rocm_gfx_targets = ["gfx1151"])
+
+ selection = ilp.select_backend_install(
+ backend = None,
+ llama_tag = "b1",
+ published_repo = FORK,
+ published_release_tag = "pin",
+ host = host,
+ )
+ assert [a.install_kind for a in selection.release_plans[0].attempts] == [
+ "windows-vulkan",
+ "windows-hip",
+ "windows-cpu",
+ ]
+ assert plan_calls == [False, True], "the ROCm plan is resolved from the pre-route host"
+
+ # A named request gets only what it named, so this cannot smuggle ROCm into one.
+ named = ilp.select_backend_install(
+ backend = "vulkan",
+ llama_tag = "b1",
+ published_repo = FORK,
+ published_release_tag = "pin",
+ host = host,
+ )
+ assert [a.install_kind for a in named.release_plans[0].attempts] == ["windows-vulkan"]
+
+
+def _one_plan(*kinds, release_tag = "b1"):
+ return ilp.InstallReleasePlan(
+ requested_tag = "b1",
+ llama_tag = "b1",
+ release_tag = release_tag,
+ attempts = [
+ ilp.AssetChoice(
+ repo = FORK,
+ tag = "b1",
+ name = k,
+ url = f"https://x/{k}",
+ source_label = "test",
+ install_kind = k,
+ )
+ for k in kinds
+ ],
+ approved_checksums = {},
+ )
+
+
[email protected]("rocm_plans", ["raises", "empty"])
+def test_no_rocm_attempt_means_no_cpu_tail_either(monkeypatch, amd_vulkan_icd, rocm_plans):
+ # The preference is not a rescue: this host's ROCm install works, so with nothing to
+ # insert the CPU tail is the very outcome the route exists to avoid.
+ def _plans(_tag, plan_host, _repo, _release, **_kw):
+ if not plan_host.has_rocm:
+ return "b1", [_one_plan("windows-vulkan", "windows-cpu")]
+ if rocm_plans == "raises":
+ raise RuntimeError("no ROCm asset for this release")
+ return "b1", []
+
+ monkeypatch.setattr(ilp, "resolve_simple_install_release_plans", _plans)
+ host = _windows_amd_host(rocm_gfx_target = "gfx1151", rocm_gfx_targets = ["gfx1151"])
+ selection = ilp.select_backend_install(
+ backend = None,
+ llama_tag = "b1",
+ published_repo = FORK,
+ published_release_tag = "pin",
+ host = host,
+ )
+ assert [a.install_kind for a in selection.release_plans[0].attempts] == ["windows-vulkan"]
+
+
[email protected]("rocm_plans", ["raises", "empty"])
+def test_a_release_that_is_nothing_but_cpu_fails_rather_than_installing_it(
+ monkeypatch, amd_vulkan_icd, rocm_plans
+):
+ # A plan that IS the tail cannot be narrowed, and keeping it is the same silent CPU
+ # install by another route.
+ def _plans(_tag, plan_host, _repo, _release, **_kw):
+ if not plan_host.has_rocm:
+ return "b1", [_one_plan("windows-cpu")]
+ if rocm_plans == "raises":
+ raise RuntimeError("no ROCm asset for this release")
+ return "b1", []
+
+ monkeypatch.setattr(ilp, "resolve_simple_install_release_plans", _plans)
+ host = _windows_amd_host(rocm_gfx_target = "gfx1151", rocm_gfx_targets = ["gfx1151"])
+ with pytest.raises(ilp.PrebuiltFallback):
+ ilp.select_backend_install(
+ backend = None,
+ llama_tag = "b1",
+ published_repo = FORK,
+ published_release_tag = "pin",
+ host = host,
+ )
+
+
+def test_release_order_survives_narrowing(monkeypatch, amd_vulkan_icd):
+ # Release order is preference order, and reordering it installs an older build.
+ def _plans(_tag, plan_host, _repo, _release, **_kw):
+ if not plan_host.has_rocm:
+ return "b2", [
+ _one_plan("windows-vulkan", "windows-cpu", release_tag = "b2"),
+ _one_plan("windows-vulkan", "windows-cpu", release_tag = "b1"),
+ ]
+ return "b2", [_one_plan("windows-hip", release_tag = "b1")]
+
+ monkeypatch.setattr(ilp, "resolve_simple_install_release_plans", _plans)
+ host = _windows_amd_host(rocm_gfx_target = "gfx1151", rocm_gfx_targets = ["gfx1151"])
+ selection = ilp.select_backend_install(
+ backend = None,
+ llama_tag = "b2",
+ published_repo = FORK,
+ published_release_tag = "pin",
+ host = host,
+ )
+ assert [p.release_tag for p in selection.release_plans] == ["b2", "b1"]
+ assert [a.install_kind for a in selection.release_plans[0].attempts] == ["windows-vulkan"]
+ assert [a.install_kind for a in selection.release_plans[1].attempts] == [
+ "windows-vulkan",
+ "windows-hip",
+ "windows-cpu",
+ ]
+
+
+def test_a_plan_that_already_carries_rocm_keeps_its_cpu_tail(monkeypatch, amd_vulkan_icd):
+ def _plans(_tag, plan_host, _repo, _release, **_kw):
+ if not plan_host.has_rocm:
+ return "b1", [_one_plan("windows-vulkan", "windows-hip", "windows-cpu")]
+ return "b1", [_one_plan("windows-hip")]
+
+ monkeypatch.setattr(ilp, "resolve_simple_install_release_plans", _plans)
+ host = _windows_amd_host(rocm_gfx_target = "gfx1151", rocm_gfx_targets = ["gfx1151"])
+ selection = ilp.select_backend_install(
+ backend = None,
+ llama_tag = "b1",
+ published_repo = FORK,
+ published_release_tag = "pin",
+ host = host,
+ )
+ assert [a.install_kind for a in selection.release_plans[0].attempts] == [
+ "windows-vulkan",
+ "windows-hip",
+ "windows-cpu",
+ ]
+
+
+def _icd(path, library = "libvulkan_driver.so"):
+ """Write a manifest where the loader would look, and return its path as a string.
+
+ Real, because the probe reads it: a driver beside the manifest named by a relative
+ library_path, the shape Adrenalin and mesa both ship. ``library = None`` omits the
+ library, i.e. the leftover an uninstall leaves behind.
+ """
+ path.parent.mkdir(parents = True, exist_ok = True)
+ driver = path.parent / (library or "gone_driver.so")
+ if library is not None:
+ driver.write_text("", encoding = "utf-8")
+ path.write_text(json.dumps({"ICD": {"library_path": str(driver)}}), encoding = "utf-8")
+ return str(path)
+
+
+def test_amd_vulkan_icd_probe_reads_the_loader_overrides_first(monkeypatch, tmp_path):
+ monkeypatch.setattr(ilp.sys, "platform", "linux")
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", _REAL_AMD_VULKAN_ICD_PRESENT)
+ monkeypatch.delenv("VK_DRIVER_FILES", raising = False)
+ monkeypatch.setenv("VK_ICD_FILENAMES", _icd(tmp_path / "intel_icd.json"))
+ assert ilp._amd_vulkan_icd_present() is False
+ monkeypatch.setenv(
+ "VK_DRIVER_FILES",
+ os.pathsep.join([_icd(tmp_path / "intel_icd.json"), _icd(tmp_path / "radeon_icd.json")]),
+ )
+ assert ilp._amd_vulkan_icd_present() is True
+
+
+def test_an_override_naming_a_removed_amd_manifest_does_not_answer_for_the_driver(
+ monkeypatch, tmp_path
+):
+ monkeypatch.setattr(ilp.sys, "platform", "linux")
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", _REAL_AMD_VULKAN_ICD_PRESENT)
+ monkeypatch.delenv("VK_ICD_FILENAMES", raising = False)
+ monkeypatch.setattr(ilp, "_vulkan_icd_search_dirs", lambda: [])
+ monkeypatch.setenv("VK_DRIVER_FILES", str(tmp_path / "gone" / "radeon_icd.x86_64.json"))
+ assert ilp._amd_vulkan_icd_present() is False
+ monkeypatch.setenv("VK_DRIVER_FILES", _icd(tmp_path / "gone" / "radeon_icd.x86_64.json"))
+ assert ilp._amd_vulkan_icd_present() is True
+
+
+def test_a_manifest_the_loader_filters_out_does_not_answer_for_the_driver(monkeypatch, tmp_path):
+ # VK_LOADER_DRIVERS_DISABLE / _SELECT exclude a registered driver from being loaded, so
+ # counting one hands this host a Vulkan build with no AMD device.
+ monkeypatch.setattr(ilp.sys, "platform", "linux")
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", _REAL_AMD_VULKAN_ICD_PRESENT)
+ for name in (
+ "VK_DRIVER_FILES",
+ "VK_ICD_FILENAMES",
+ "VK_LOADER_DRIVERS_SELECT",
+ "VK_LOADER_DRIVERS_DISABLE",
+ ):
+ monkeypatch.delenv(name, raising = False)
+ icd_dir = tmp_path / "usr/share/vulkan/icd.d"
+ monkeypatch.setattr(ilp, "_vulkan_icd_search_dirs", lambda: [icd_dir])
+ _icd(icd_dir / "radeon_icd.x86_64.json")
+ assert ilp._amd_vulkan_icd_present() is True
+
+ monkeypatch.setenv("VK_LOADER_DRIVERS_DISABLE", "*radeon*")
+ assert ilp._amd_vulkan_icd_present() is False
+ # Disable is read first so a select list names drivers back in, which is the loader's order.
+ monkeypatch.setenv("VK_LOADER_DRIVERS_SELECT", "RADEON_ICD.X86_64.JSON")
+ assert ilp._amd_vulkan_icd_present() is True
+ # And a select list naming someone else's driver excludes this one on its own.
+ monkeypatch.setenv("VK_LOADER_DRIVERS_SELECT", "intel_*")
+ assert ilp._amd_vulkan_icd_present() is False
+
+
+def test_the_loader_filters_reach_a_force_list_as_well(monkeypatch, tmp_path):
+ # The filters apply to known drivers, and a force list is how the loader knows them.
+ monkeypatch.setattr(ilp.sys, "platform", "linux")
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", _REAL_AMD_VULKAN_ICD_PRESENT)
+ monkeypatch.delenv("VK_ICD_FILENAMES", raising = False)
+ for name in ("VK_LOADER_DRIVERS_SELECT", "VK_LOADER_DRIVERS_DISABLE"):
+ monkeypatch.delenv(name, raising = False)
+ monkeypatch.setattr(ilp, "_vulkan_icd_search_dirs", lambda: [])
+ monkeypatch.setenv("VK_DRIVER_FILES", _icd(tmp_path / "radeon_icd.x86_64.json"))
+ assert ilp._amd_vulkan_icd_present() is True
+
+ monkeypatch.setenv("VK_LOADER_DRIVERS_DISABLE", "*")
+ assert ilp._amd_vulkan_icd_present() is False
+
+
+def test_a_32_bit_linux_manifest_does_not_answer_for_the_x64_bundle(monkeypatch, tmp_path):
+ # multilib mesa ships radeon_icd.i686.json, which a 64-bit llama-server cannot load.
+ monkeypatch.setattr(ilp.sys, "platform", "linux")
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", _REAL_AMD_VULKAN_ICD_PRESENT)
+ for name in ("VK_DRIVER_FILES", "VK_ICD_FILENAMES"):
+ monkeypatch.delenv(name, raising = False)
+ icd_dir = tmp_path / "usr/share/vulkan/icd.d"
+ monkeypatch.setattr(ilp, "_vulkan_icd_search_dirs", lambda: [icd_dir])
+
+ for name in ("radeon_icd.i686.json", "amd_icd32.json", "amd-vulkan32.json"):
+ _icd(icd_dir / name)
+ assert ilp._amd_vulkan_icd_present() is False
+
+ _icd(icd_dir / "radeon_icd.x86_64.json")
+ assert ilp._amd_vulkan_icd_present() is True
+
+
+def test_an_override_of_only_stale_paths_answers_on_its_own(monkeypatch, tmp_path):
+ # A force list: the loader searches no directories, so falling through to a manifest
+ # it will never read misjudges the host.
+ monkeypatch.setattr(ilp.sys, "platform", "linux")
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", _REAL_AMD_VULKAN_ICD_PRESENT)
+ monkeypatch.delenv("VK_ICD_FILENAMES", raising = False)
+ icd_dir = tmp_path / "usr/share/vulkan/icd.d"
+ icd_dir.mkdir(parents = True)
+ monkeypatch.setattr(ilp, "_vulkan_icd_search_dirs", lambda: [icd_dir])
+ _icd(icd_dir / "radeon_icd.x86_64.json")
+
+ monkeypatch.delenv("VK_DRIVER_FILES", raising = False)
+ assert ilp._amd_vulkan_icd_present() is True
+
+ monkeypatch.setenv("VK_DRIVER_FILES", str(tmp_path / "gone" / "intel_icd.json"))
+ assert ilp._amd_vulkan_icd_present() is False
+
+
+def test_the_deprecated_override_is_not_consulted_behind_the_current_one(monkeypatch, tmp_path):
+ # VK_DRIVER_FILES supersedes VK_ICD_FILENAMES rather than joining it.
+ monkeypatch.setattr(ilp.sys, "platform", "linux")
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", _REAL_AMD_VULKAN_ICD_PRESENT)
+ monkeypatch.setattr(ilp, "_vulkan_icd_search_dirs", lambda: [])
+ amd = _icd(tmp_path / "radeon_icd.x86_64.json")
+ intel = _icd(tmp_path / "intel_icd.x86_64.json")
+ monkeypatch.setenv("VK_ICD_FILENAMES", amd)
+
+ monkeypatch.delenv("VK_DRIVER_FILES", raising = False)
+ assert ilp._amd_vulkan_icd_present() is True
+
+ monkeypatch.setenv("VK_DRIVER_FILES", intel)
+ assert ilp._amd_vulkan_icd_present() is False
+
+
+def test_the_icd_search_dirs_follow_the_xdg_variables(monkeypatch, tmp_path):
+ # Those are only the defaults, so scanning them alone misses a custom layout's only
+ # usable manifest.
+ monkeypatch.setenv("XDG_DATA_DIRS", f"{tmp_path / 'a'}{os.pathsep}{tmp_path / 'b'}")
+ monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path / "home-data"))
+ monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "home-config"))
+ monkeypatch.setenv("XDG_CONFIG_DIRS", str(tmp_path / "sys-config"))
+
+ dirs = [str(d) for d in ilp._vulkan_icd_search_dirs()]
+ for base in ("home-config", "sys-config", "home-data", "a", "b"):
+ assert str(tmp_path / base / "vulkan/icd.d") in dirs, base
+ assert "/usr/share/vulkan/icd.d" not in dirs, "a set XDG_DATA_DIRS replaces the default"
+ assert dirs.index(str(tmp_path / "home-config" / "vulkan/icd.d")) < dirs.index(
+ str(tmp_path / "home-data" / "vulkan/icd.d")
+ )
+
+ for var in ("XDG_DATA_DIRS", "XDG_DATA_HOME", "XDG_CONFIG_HOME", "XDG_CONFIG_DIRS"):
+ monkeypatch.delenv(var, raising = False)
+ defaults = [str(d) for d in ilp._vulkan_icd_search_dirs()]
+ assert "/usr/share/vulkan/icd.d" in defaults
+ assert "/usr/local/share/vulkan/icd.d" in defaults
+ assert "/etc/vulkan/icd.d" in defaults
+
+
+ "manifest",
+ ["radeon_icd.x86_64.json", "amd_icd64.json", "amd_pro_icd64.json", "amdvlk64.json"],
+)
+def test_amd_vulkan_icd_probe_recognises_every_shipped_amd_manifest(
+ manifest, monkeypatch, tmp_path
+):
+ monkeypatch.setattr(ilp.sys, "platform", "linux")
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", _REAL_AMD_VULKAN_ICD_PRESENT)
+ monkeypatch.delenv("VK_ICD_FILENAMES", raising = False)
+ monkeypatch.setenv("VK_DRIVER_FILES", _icd(tmp_path / manifest))
+ assert ilp._amd_vulkan_icd_present() is True
+
+
+def test_amd_vulkan_icd_probe_judges_the_manifest_name_not_the_directory(monkeypatch, tmp_path):
+ # Negative control, and a bug it caught: matching "amd" anywhere in the path answered
+ # True for any host whose directories contain it -- pytest's tmp_path did.
+ monkeypatch.setattr(ilp.sys, "platform", "linux")
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", _REAL_AMD_VULKAN_ICD_PRESENT)
+ monkeypatch.delenv("VK_ICD_FILENAMES", raising = False)
+ monkeypatch.setattr(ilp, "_vulkan_icd_search_dirs", lambda: [])
+ monkeypatch.setenv("VK_DRIVER_FILES", _icd(tmp_path / "amd_vulkan_stuff" / "intel_icd.json"))
+ assert ilp._amd_vulkan_icd_present() is False
+
+
+def test_amd_vulkan_icd_probe_scans_the_loader_search_directories(monkeypatch, tmp_path):
+ monkeypatch.setattr(ilp.sys, "platform", "linux")
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", _REAL_AMD_VULKAN_ICD_PRESENT)
+ for _env in ("VK_DRIVER_FILES", "VK_ICD_FILENAMES"):
+ monkeypatch.delenv(_env, raising = False)
+ icd_dir = tmp_path / "usr/share/vulkan/icd.d"
+ icd_dir.mkdir(parents = True)
+ monkeypatch.setattr(ilp, "_vulkan_icd_search_dirs", lambda: [icd_dir])
+ _icd(icd_dir / "nvidia_icd.json")
+ assert ilp._amd_vulkan_icd_present() is False
+ _icd(icd_dir / "radeon_icd.x86_64.json")
+ assert ilp._amd_vulkan_icd_present() is True
+
+
+def test_a_manifest_whose_driver_is_gone_is_not_evidence(monkeypatch, tmp_path):
+ # A leftover JSON would move a working ROCm install onto a Vulkan build with no device.
+ monkeypatch.setattr(ilp.sys, "platform", "linux")
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", _REAL_AMD_VULKAN_ICD_PRESENT)
+ monkeypatch.delenv("VK_ICD_FILENAMES", raising = False)
+ monkeypatch.setattr(ilp, "_vulkan_icd_search_dirs", lambda: [])
+ stale = _icd(tmp_path / "stale" / "radeon_icd.x86_64.json", library = None)
+ monkeypatch.setenv("VK_DRIVER_FILES", stale)
+ assert ilp._amd_vulkan_icd_present() is False
+ monkeypatch.setenv("VK_DRIVER_FILES", _icd(tmp_path / "live" / "radeon_icd.x86_64.json"))
+ assert ilp._amd_vulkan_icd_present() is True
+
+
+def test_an_unparsable_or_libraryless_manifest_is_not_evidence(monkeypatch, tmp_path):
+ monkeypatch.setattr(ilp.sys, "platform", "linux")
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", _REAL_AMD_VULKAN_ICD_PRESENT)
+ monkeypatch.delenv("VK_ICD_FILENAMES", raising = False)
+ monkeypatch.setattr(ilp, "_vulkan_icd_search_dirs", lambda: [])
+ for body in ("{ not json", "{}", '{"ICD": {}}', '{"ICD": {"library_path": ""}}'):
+ path = tmp_path / "radeon_icd.x86_64.json"
+ path.write_text(body, encoding = "utf-8")
+ monkeypatch.setenv("VK_DRIVER_FILES", str(path))
+ assert ilp._amd_vulkan_icd_present() is False, body
+
+
+def test_a_bare_driver_name_is_accepted(monkeypatch, tmp_path):
+ # Adrenalin registers a bare "amdvlk64.dll", resolved through the system search path;
+ # failing that towards ROCm would decline every ordinary Windows host.
+ monkeypatch.setattr(ilp.sys, "platform", "linux")
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_present", _REAL_AMD_VULKAN_ICD_PRESENT)
+ monkeypatch.delenv("VK_ICD_FILENAMES", raising = False)
+ monkeypatch.setattr(ilp, "_vulkan_icd_search_dirs", lambda: [])
+ path = tmp_path / "amdvlk64.json"
+ path.write_text(json.dumps({"ICD": {"library_path": "amdvlk64.dll"}}), encoding = "utf-8")
+ monkeypatch.setenv("VK_DRIVER_FILES", str(path))
+ assert ilp._amd_vulkan_icd_present() is True
+
+
+def test_amd_vulkan_icd_probe_never_raises(monkeypatch):
+ monkeypatch.setattr(
+ ilp, "_amd_vulkan_icd_manifest_paths", lambda: (_ for _ in ()).throw(OSError("boom"))
+ )
+ assert ilp._amd_vulkan_icd_present() is False
+
+
def test_llama_cpp_backend_cpu_opts_out_of_auto_vulkan(monkeypatch):
# cpu is an explicit non-Vulkan choice, so it suppresses the auto-fallback.
monkeypatch.setenv("UNSLOTH_LLAMA_CPP_BACKEND", "cpu")
@@ -2210,3 +2809,147 @@ def test_the_forced_cpu_guard_is_not_vacuous():
llama_backend = "vulkan",
)
assert out_repo != repo or persist == "vulkan"
+
+
+def test_the_icd_search_path_is_built_per_call_not_at_import(monkeypatch):
+ """A host with no resolvable home directory must still be able to INSTALL.
+
+ ``Path.home()`` raises rather than defaulting (a Windows service account with no
+ USERPROFILE), so evaluating it at module scope takes the installer down at import over
+ a directory only the Vulkan probe reads -- and the failure would not mention Vulkan.
+ """
+
+ def _no_home():
+ raise RuntimeError("Could not determine home directory.")
+
+ monkeypatch.setattr(ilp.Path, "home", staticmethod(_no_home))
+ dirs = ilp._vulkan_icd_search_dirs()
+ assert dirs, "the system search directories must survive an unresolvable home"
+ assert all("icd.d" in str(entry) for entry in dirs)
+ monkeypatch.setattr(ilp.sys, "platform", "linux")
+ assert _REAL_AMD_VULKAN_ICD_PRESENT() in (True, False)
+
+
+# ---------------------------------------------------------------------------
+# The Windows Vulkan ICD registry: values, not subkeys, with the enable flag in the DWORD.
+# ---------------------------------------------------------------------------
+
+
+class _FakeIcdWinreg:
+ HKEY_LOCAL_MACHINE = object()
+ REG_DWORD = 4
+ REG_SZ = 1
+
+ def __init__(self, by_key):
+ self._by_key = by_key
+
+ def OpenKey(self, parent, name):
+ if name not in self._by_key:
+ raise FileNotFoundError(name)
+ entries = self._by_key[name]
+
+ class _Key:
+ def __enter__(_self):
+ return entries
+
+ def __exit__(_self, *exc):
+ return False
+
+ return _Key()
+
+ def QueryInfoKey(self, entries):
+ return (0, len(entries), 0)
+
+ def EnumValue(self, entries, index):
+ return entries[index]
+
+
+def _icd_paths(monkeypatch, by_key):
+ monkeypatch.setattr(ilp.sys, "platform", "win32")
+ for name in ("VK_DRIVER_FILES", "VK_ICD_FILENAMES"):
+ monkeypatch.delenv(name, raising = False)
+ monkeypatch.setitem(sys.modules, "winreg", _FakeIcdWinreg(by_key))
+ return ilp._amd_vulkan_icd_manifest_paths()
+
+
+def test_the_windows_registry_is_not_read_when_the_loader_is_forced(
+ monkeypatch, _present_manifest, tmp_path
+):
+ # VK_DRIVER_FILES overrides discovery on Windows too, so a registered manifest is not
+ # evidence when the loader has been pointed elsewhere.
+ monkeypatch.setattr(ilp.sys, "platform", "win32")
+ registry = {_DRIVERS_KEY: [(_present_manifest, 0, _FakeIcdWinreg.REG_DWORD)]}
+ monkeypatch.setitem(sys.modules, "winreg", _FakeIcdWinreg(registry))
+ for name in ("VK_DRIVER_FILES", "VK_ICD_FILENAMES"):
+ monkeypatch.delenv(name, raising = False)
+ assert ilp._amd_vulkan_icd_manifest_paths() == [_present_manifest]
+
+ intel = _icd(tmp_path / "intel_icd.json")
+ monkeypatch.setenv("VK_DRIVER_FILES", intel)
+ assert ilp._amd_vulkan_icd_manifest_paths() == [intel]
+ assert _REAL_AMD_VULKAN_ICD_PRESENT() is False
+ monkeypatch.setenv("VK_ICD_FILENAMES", _present_manifest)
+ assert ilp._amd_vulkan_icd_manifest_paths() == [intel]
+ monkeypatch.delenv("VK_DRIVER_FILES")
+ assert ilp._amd_vulkan_icd_manifest_paths() == [_present_manifest]
+
+
+_DRIVERS_KEY = r"SOFTWARE\Khronos\Vulkan\Drivers"
+
+
+def _present_manifest(tmp_path):
+ """A registered manifest that is really on disk, since the probe now checks."""
+ return _icd(tmp_path / "amd-vulkan64.json")
+
+
+def test_the_windows_radeon_manifest_is_recognized(monkeypatch):
+ # Adrenalin registers amd-vulkan64.json, not amdvlk64.json; knowing only the AMDVLK
+ # spelling answered False on the ordinary Windows gfx115x host.
+ monkeypatch.setattr(
+ ilp,
+ "_amd_vulkan_icd_manifest_paths",
+ lambda: [r"C:\Windows\System32\amd-vulkan64.json"],
+ )
+ monkeypatch.setattr(ilp, "_amd_vulkan_icd_usable", lambda _path: True)
+ assert _REAL_AMD_VULKAN_ICD_PRESENT() is True
+
+
+def test_a_disabled_registry_registration_does_not_answer_for_the_driver(
+ monkeypatch, _present_manifest
+):
+ # Value name is the manifest path, DWORD data the enable flag: only zero loads
+ # (LoaderDriverInterface.md).
+ disabled = _icd_paths(
+ monkeypatch,
+ {_DRIVERS_KEY: [(_present_manifest, 1, _FakeIcdWinreg.REG_DWORD)]},
+ )
+ assert disabled == []
+ enabled = _icd_paths(
+ monkeypatch,
+ {_DRIVERS_KEY: [(_present_manifest, 0, _FakeIcdWinreg.REG_DWORD)]},
+ )
+ assert enabled == [_present_manifest]
+
+
+def test_an_enabled_registration_whose_manifest_is_gone_does_not_answer(monkeypatch, tmp_path):
+ missing = str(tmp_path / "gone" / "amd-vulkan64.json")
+ assert _icd_paths(monkeypatch, {_DRIVERS_KEY: [(missing, 0, _FakeIcdWinreg.REG_DWORD)]}) == []
+
+
+def test_a_32_bit_registration_does_not_answer_for_the_x64_bundle(monkeypatch, tmp_path):
+ wow = str(tmp_path / "amd-vulkan32.json")
+ _icd(tmp_path / "amd-vulkan32.json")
+ paths = _icd_paths(
+ monkeypatch,
+ {r"SOFTWARE\WOW6432Node\Khronos\Vulkan\Drivers": [(wow, 0, _FakeIcdWinreg.REG_DWORD)]},
+ )
+ assert paths == []
+
+
+def test_a_non_dword_icd_registration_is_ignored(monkeypatch, _present_manifest):
+ paths = _icd_paths(
+ monkeypatch,
+ {_DRIVERS_KEY: [(_present_manifest, "0", _FakeIcdWinreg.REG_SZ)]},
+ )
+ assert paths == []
diff --git a/studio/backend/tests/test_llama_backend_switch.py b/studio/backend/tests/test_llama_backend_switch.py
index b7c65757ecb..75b4e9844e8 100644
--- a/studio/backend/tests/test_llama_backend_switch.py
+++ b/studio/backend/tests/test_llama_backend_switch.py
@@ -30,8 +30,9 @@ import utils.whisper_cpp_update as whisper_upd # noqa: E402
MARKER = "UNSLOTH_PREBUILT_INFO.json"
-# Captured before the autouse fixture stubs it out on the module.
+# Captured before the autouse fixture stubs them out on the module.
_whisper_phase_plan = upd._whisper_phase_plan
+_resolve_backends_for_host = upd._resolve_backends_for_host
class _FakeInstallerPopen:
@@ -144,6 +145,137 @@ def _await_job(state = ("success", "error")) -> dict:
raise AssertionError(f"job never reached {state}: {upd.get_update_status()['job']}")
+# ── The automatic choice drifting ──
+
+
+def _drifted(monkeypatch, resolved_backend = "vulkan"):
+ """Detection now resolves somewhere other than what the marker records."""
+ monkeypatch.setattr(
+ upd,
+ "_resolve_backends_for_host",
+ lambda install_dir, **kwargs: {
+ "backends": [
+ {
+ "backend": backend,
+ "available": True,
+ "resolved_backend": (resolved_backend if backend == "auto" else backend),
+ "asset": f"app-b9596-mix-abc-linux-x64-{backend}.tar.gz",
+ }
+ for backend in ("auto", "cpu", "cuda", "rocm", "vulkan")
+ ]
+ },
+ )
+
+
+def test_a_drifted_automatic_install_is_offered_as_an_update(monkeypatch, tmp_path):
+ _install(monkeypatch, tmp_path, backend = "rocm", backend_request = "auto")
+ _drifted(monkeypatch)
+ status = upd.get_update_status()
+ assert status["update_available"] is False
+ assert status["backend_migration_available"] is True
+ assert (status["from_backend"], status["to_backend"]) == ("rocm", "vulkan")
+
+
+def test_a_deliberate_backend_choice_is_never_offered_a_migration(monkeypatch, tmp_path):
+ # A concrete choice is recorded only on an install that honoured it, so re-applying
+ # detection would undo a decision by hand.
+ _install(monkeypatch, tmp_path, backend = "rocm", backend_request = "rocm")
+ _drifted(monkeypatch)
+ status = upd.get_update_status()
+ assert status["backend_migration_available"] is False
+ assert status["to_backend"] is None
+
+
+def test_an_undrifted_automatic_install_is_offered_nothing(monkeypatch, tmp_path):
+ _install(monkeypatch, tmp_path, backend = "cuda", backend_request = "auto")
+ status = upd.get_update_status()
+ assert status["backend_migration_available"] is False
+
+
+def test_an_environment_override_suppresses_the_migration_offer(monkeypatch, tmp_path):
+ monkeypatch.setenv("UNSLOTH_LLAMA_CPP_BACKEND", "rocm")
+ _install(monkeypatch, tmp_path, backend = "rocm", backend_request = "auto")
+ _drifted(monkeypatch)
+ assert upd.get_update_status()["backend_migration_available"] is False
+
+
+def test_applying_a_migration_re_applies_auto_and_stays_an_update(monkeypatch, tmp_path):
+ # "auto", not "vulkan": naming it stores a choice nobody made and drops rocm_gfx. The
+ # operation stays the "update" the banner offered, since the banner hides a "switch".
+ install_dir = _install(monkeypatch, tmp_path, backend = "rocm", backend_request = "auto")
+ _drifted(monkeypatch)
+ seen: dict = {}
+
+ def _on_start(cmd, kwargs):
+ seen["cmd"] = cmd
+ seen["env"] = kwargs.get("env") or {}
+ _write_install(
+ install_dir,
+ asset = "app-b9596-mix-abc-linux-x64-vulkan.tar.gz",
+ install_kind = "linux-vulkan",
+ backend = "vulkan",
+ backend_request = "auto",
+ )
+
+ _patch_installer(monkeypatch, on_start = _on_start)
+
+ assert upd.start_update()["started"] is True
+ job = _await_job()
+
+ assert job["state"] == "success", job
+ assert job["operation"] == "update"
+ assert job["requested_backend"] == "auto"
+ assert seen["cmd"][seen["cmd"].index("--llama-backend") + 1] == "auto"
+ assert seen["cmd"][seen["cmd"].index("--published-release-tag") + 1] == "b9596-mix-abc"
+
+
+def test_a_migration_that_lands_back_on_the_old_backend_says_so(monkeypatch, tmp_path):
+ # The ROCm fallback behind the Vulkan preference reinstalls the backend already here,
+ # so "now running on rocm" would read as applied and the next check re-offer it.
+ install_dir = _install(monkeypatch, tmp_path, backend = "rocm", backend_request = "auto")
+ _drifted(monkeypatch)
+
+ def _on_start(cmd, kwargs):
+ _write_install(install_dir, backend = "rocm", backend_request = "auto")
+
+ _patch_installer(monkeypatch, on_start = _on_start)
+
+ assert upd.start_update()["started"] is True
+ job = _await_job()
+
+ assert job["state"] == "success", job
+ assert "could not be moved to vulkan" in job["message"]
+ assert "now running on rocm" not in job["message"]
+
+
+def test_a_migration_that_lands_on_its_target_reports_the_new_backend(monkeypatch, tmp_path):
+ install_dir = _install(monkeypatch, tmp_path, backend = "rocm", backend_request = "auto")
+ _drifted(monkeypatch)
+ _patch_installer(
+ monkeypatch,
+ on_start = lambda cmd, kwargs: _write_install(
+ install_dir,
+ asset = "app-b9596-mix-abc-linux-x64-vulkan.tar.gz",
+ install_kind = "linux-vulkan",
+ backend = "vulkan",
+ backend_request = "auto",
+ ),
+ )
+
+ assert upd.start_update()["started"] is True
+ job = _await_job()
+
+ assert job["state"] == "success", job
+ assert "now running on vulkan" in job["message"]
+
+
+def test_an_up_to_date_install_with_no_drift_still_refuses(monkeypatch, tmp_path):
+ _install(monkeypatch, tmp_path, backend = "cuda", backend_request = "auto")
+ result = upd.start_update()
+ assert result["started"] is False
+ assert result["reason"] == "up_to_date"
+
+
# ── Applying ──
@@ -806,6 +938,317 @@ def test_backend_resolution_failures_are_not_cached(monkeypatch, tmp_path):
assert responses == []
+def test_the_migration_resolver_replays_the_arch_the_marker_recorded(monkeypatch, tmp_path):
+ """A Windows host whose HIP probes are absent installs on ROCm because setup.ps1
+ inferred the arch from the GPU name and forwarded it. This resolver re-probes from
+ scratch, so without the replay it sees no ROCm GPU, resolves "auto" to CPU, and a
+ working GPU install reads as drifted -- offering, in the update banner, a migration
+ that replaces GPU inference with CPU."""
+ install_dir = _install(
+ monkeypatch,
+ tmp_path,
+ backend = "rocm",
+ install_kind = "linux-rocm",
+ asset = "app-b9596-mix-abc-linux-x64-rocm-gfx1151.tar.gz",
+ rocm_gfx = "gfx1151",
+ )
+ marker = upd.read_install_marker(upd._find_binary())
+ seen: list = []
+
+ def _resolver(**kwargs):
+ seen.append(kwargs.get("extra_env"))
+ gfx = (kwargs.get("extra_env") or {}).get("UNSLOTH_ROCM_GFX_REMEMBERED")
+ resolved = "rocm" if gfx else "cpu"
+ return {"backends": [{"backend": "auto", "available": True, "resolved_backend": resolved}]}
+
+ monkeypatch.setattr(upd, "_resolve_backends_for_host", _resolve_backends_for_host)
+ monkeypatch.setattr(upd._flow, "resolve_prebuilt_for_host", _resolver)
+ upd._backends_memo.clear()
+
+ assert upd._pending_backend_migration(upd._find_binary(), marker) is None
+ assert seen == [{"UNSLOTH_ROCM_GFX_REMEMBERED": "gfx1151"}]
+ assert install_dir.exists()
+
+
+def test_a_marker_with_no_recorded_arch_passes_no_replay(monkeypatch, tmp_path):
+ # Negative control: the replay is a previous install's record, not a default, so a host
+ # that never had one resolves as it does today.
+ _install(monkeypatch, tmp_path)
+ marker = upd.read_install_marker(upd._find_binary())
+ seen: list = []
+
+ def _resolver(**kwargs):
+ seen.append(kwargs.get("extra_env"))
+ return {"backends": [{"backend": "auto", "available": True, "resolved_backend": "cpu"}]}
+
+ monkeypatch.setattr(upd, "_resolve_backends_for_host", _resolve_backends_for_host)
+ monkeypatch.setattr(upd._flow, "resolve_prebuilt_for_host", _resolver)
+ upd._backends_memo.clear()
+
+ upd._pending_backend_migration(upd._find_binary(), marker)
+ assert seen == [None]
+
+
+def test_the_picker_describes_the_same_host_the_update_check_does(monkeypatch, tmp_path):
+ """Settings and the update banner must not disagree about what this box is.
+
+ Without the recovery the picker's resolve sees no arch, reads an AMD host whose
+ probes name none as CPU-only, and offers an Automatic that installs a backend the
+ banner never advertised."""
+ _install(
+ monkeypatch,
+ tmp_path,
+ backend = "rocm",
+ backend_request = "auto",
+ install_kind = "windows-rocm",
+ asset = "app-b9596-mix-abc-windows-x64-rocm-gfx1151.zip",
+ )
+ assert upd.read_install_marker(upd._find_binary()).get("rocm_gfx") is None
+
+ def _resolver(**kwargs):
+ gfx = (kwargs.get("extra_env") or {}).get("UNSLOTH_ROCM_GFX_REMEMBERED")
+ return {
+ "backends": [
+ {
+ "backend": backend,
+ "available": bool(gfx) or backend in ("auto", "cpu", "vulkan"),
+ "resolved_backend": (
+ ("vulkan" if gfx else "cpu") if backend == "auto" else backend
+ ),
+ }
+ for backend in ("auto", "cpu", "rocm", "vulkan")
+ ]
+ }
+
+ monkeypatch.setattr(upd, "_resolve_backends_for_host", _resolve_backends_for_host)
+ monkeypatch.setattr(upd._flow, "resolve_prebuilt_for_host", _resolver)
+ monkeypatch.setattr(upd, "latest_release_assets", lambda repo, force_refresh = False: {})
+ upd._backends_memo.clear()
+
+ status = upd.get_backend_status()
+ by_backend = {option["backend"]: option for option in status["options"]}
+ assert by_backend["auto"]["resolved_backend"] == "vulkan"
+ assert by_backend["rocm"]["available"] is True
+
+
+def test_the_arch_is_recovered_from_the_installed_bundle_when_none_was_recorded(
+ monkeypatch, tmp_path
+):
+ # The marker records rocm_gfx only when the install resolved one, and the host needing
+ # the replay most is the one that never did. The per-gfx bundle names the family.
+ _install(
+ monkeypatch,
+ tmp_path,
+ backend = "rocm",
+ install_kind = "windows-rocm",
+ asset = "app-b9596-mix-abc-windows-x64-rocm-gfx1151.zip",
+ )
+ marker = upd.read_install_marker(upd._find_binary())
+ assert marker.get("rocm_gfx") is None
+ seen: list = []
+
+ def _resolver(**kwargs):
+ seen.append(kwargs.get("extra_env"))
+ gfx = (kwargs.get("extra_env") or {}).get("UNSLOTH_ROCM_GFX_REMEMBERED")
+ return {
+ "backends": [
+ {
+ "backend": "auto",
+ "available": True,
+ "resolved_backend": "rocm" if gfx else "cpu",
+ }
+ ]
+ }
+
+ monkeypatch.setattr(upd, "_resolve_backends_for_host", _resolve_backends_for_host)
+ monkeypatch.setattr(upd._flow, "resolve_prebuilt_for_host", _resolver)
+ upd._backends_memo.clear()
+
+ assert upd._pending_backend_migration(upd._find_binary(), marker) is None
+ assert seen == [{"UNSLOTH_ROCM_GFX_REMEMBERED": "gfx1151"}]
+
+
+def test_a_gpu_install_is_never_offered_a_migration_onto_cpu(monkeypatch, tmp_path):
+ # An empty probe and a host that really lost its GPU read the same from here, and
+ # moving a working GPU install onto CPU is the costly side of that. Settings still can.
+ _install(
+ monkeypatch,
+ tmp_path,
+ backend = "rocm",
+ install_kind = "linux-rocm",
+ asset = "app-b9596-mix-abc-linux-x64-rocm-gfx1151.tar.gz",
+ rocm_gfx = "gfx1151",
+ )
+ marker = upd.read_install_marker(upd._find_binary())
+
+ monkeypatch.setattr(upd, "_resolve_backends_for_host", _resolve_backends_for_host)
+ monkeypatch.setattr(
+ upd._flow,
+ "resolve_prebuilt_for_host",
+ lambda **_kw: {
+ "backends": [{"backend": "auto", "available": True, "resolved_backend": "cpu"}]
+ },
+ )
+ upd._backends_memo.clear()
+ assert upd._pending_backend_migration(upd._find_binary(), marker) is None
+
+ monkeypatch.setattr(
+ upd._flow,
+ "resolve_prebuilt_for_host",
+ lambda **_kw: {
+ "backends": [{"backend": "auto", "available": True, "resolved_backend": "vulkan"}]
+ },
+ )
+ upd._backends_memo.clear()
+ assert upd._pending_backend_migration(upd._find_binary(), marker) == "vulkan"
+
+
+def test_applying_a_migration_replays_the_arch_the_offer_was_made_with(monkeypatch, tmp_path):
+ """The apply re-resolves before it installs, and that second resolve must see what
+ the first one saw. Without the replay it resolves "auto" back onto the installed
+ backend, reads as already applied, and refuses the migration the banner offered --
+ silently, since a refusal at that point is indistinguishable from nothing to do."""
+ install_dir = _install(
+ monkeypatch,
+ tmp_path,
+ backend = "rocm",
+ backend_request = "auto",
+ install_kind = "linux-rocm",
+ asset = "app-b9596-mix-abc-linux-x64-rocm-gfx1151.tar.gz",
+ rocm_gfx = "gfx1151",
+ )
+
+ def _resolver(**kwargs):
+ gfx = (kwargs.get("extra_env") or {}).get("UNSLOTH_ROCM_GFX_REMEMBERED")
+ # The arch is what routes this host to Vulkan; without it the installer sees no
+ # known AMD iGPU and keeps the ROCm build.
+ auto = "vulkan" if gfx else "rocm"
+ return {
+ "backends": [
+ {
+ "backend": backend,
+ "available": True,
+ "resolved_backend": (auto if backend == "auto" else backend),
+ "asset": f"app-b9596-mix-abc-linux-x64-{backend}.tar.gz",
+ }
+ for backend in ("auto", "cpu", "rocm", "vulkan")
+ ]
+ }
+
+ monkeypatch.setattr(upd, "_resolve_backends_for_host", _resolve_backends_for_host)
+ monkeypatch.setattr(upd._flow, "resolve_prebuilt_for_host", _resolver)
+ upd._backends_memo.clear()
+
+ assert upd.get_update_status()["backend_migration_available"] is True
+
+ seen: dict = {}
+
+ def _on_start(cmd, kwargs):
+ seen["cmd"] = cmd
+ _write_install(
+ install_dir,
+ asset = "app-b9596-mix-abc-linux-x64-vulkan.tar.gz",
+ install_kind = "linux-vulkan",
+ backend = "vulkan",
+ backend_request = "auto",
+ )
+
+ _patch_installer(monkeypatch, on_start = _on_start)
+
+ result = upd.start_update()
+ assert result["started"] is True, result
+ job = _await_job()
+ assert job["state"] == "success", job
+ assert seen["cmd"][seen["cmd"].index("--llama-backend") + 1] == "auto"
+
+
+def test_applying_a_migration_replays_an_arch_only_the_bundle_names(monkeypatch, tmp_path):
+ """The offer is made through the recovered arch, so the apply has to use the same one.
+
+ Reading the marker field alone leaves this second resolve without an arch on exactly
+ the host the recovery exists for, and it then resolves "auto" back onto ROCm, reads as
+ already applied, and refuses the migration the banner is still showing."""
+ install_dir = _install(
+ monkeypatch,
+ tmp_path,
+ backend = "rocm",
+ backend_request = "auto",
+ install_kind = "linux-rocm",
+ asset = "app-b9596-mix-abc-linux-x64-rocm-gfx1151.tar.gz",
+ )
+ assert upd.read_install_marker(upd._find_binary()).get("rocm_gfx") is None
+
+ def _resolver(**kwargs):
+ gfx = (kwargs.get("extra_env") or {}).get("UNSLOTH_ROCM_GFX_REMEMBERED")
+ auto = "vulkan" if gfx else "rocm"
+ return {
+ "backends": [
+ {
+ "backend": backend,
+ "available": True,
+ "resolved_backend": (auto if backend == "auto" else backend),
+ "asset": f"app-b9596-mix-abc-linux-x64-{backend}.tar.gz",
+ }
+ for backend in ("auto", "cpu", "rocm", "vulkan")
+ ]
+ }
+
+ monkeypatch.setattr(upd, "_resolve_backends_for_host", _resolve_backends_for_host)
+ monkeypatch.setattr(upd._flow, "resolve_prebuilt_for_host", _resolver)
+ upd._backends_memo.clear()
+
+ assert upd.get_update_status()["backend_migration_available"] is True
+
+ def _on_start(cmd, kwargs):
+ _write_install(
+ install_dir,
+ asset = "app-b9596-mix-abc-linux-x64-vulkan.tar.gz",
+ install_kind = "linux-vulkan",
+ backend = "vulkan",
+ backend_request = "auto",
+ )
+
+ _patch_installer(monkeypatch, on_start = _on_start)
+
+ result = upd.start_update()
+ assert result["started"] is True, result
+ job = _await_job()
+ assert job["state"] == "success", job
+
+
+def test_an_apply_that_no_longer_drifts_still_refuses(monkeypatch, tmp_path):
+ _install(
+ monkeypatch,
+ tmp_path,
+ backend = "vulkan",
+ backend_request = "auto",
+ install_kind = "linux-vulkan",
+ asset = "app-b9596-mix-abc-linux-x64-vulkan.tar.gz",
+ rocm_gfx = "gfx1151",
+ )
+
+ def _resolver(**kwargs):
+ return {
+ "backends": [
+ {
+ "backend": backend,
+ "available": True,
+ "resolved_backend": ("vulkan" if backend == "auto" else backend),
+ "asset": f"app-b9596-mix-abc-linux-x64-{backend}.tar.gz",
+ }
+ for backend in ("auto", "cpu", "rocm", "vulkan")
+ ]
+ }
+
+ monkeypatch.setattr(upd, "_resolve_backends_for_host", _resolve_backends_for_host)
+ monkeypatch.setattr(upd._flow, "resolve_prebuilt_for_host", _resolver)
+ upd._backends_memo.clear()
+
+ result = upd.start_update()
+ assert result["started"] is False
+ assert result["reason"] == "up_to_date"
+
+
def test_running_job_status_does_not_resolve_options_again(monkeypatch, tmp_path):
_install(monkeypatch, tmp_path)
@@ -822,3 +1265,90 @@ def test_running_job_status_does_not_resolve_options_again(monkeypatch, tmp_path
assert status["job"]["state"] == "running"
assert status["options"] == []
+
+
+def test_an_explicit_auto_in_the_environment_still_gets_the_migration(monkeypatch, tmp_path):
+ # "auto" is an override value asking for the detection the migration re-applies, so
+ # suppressing on "an override exists" withheld the offer from a host that can take it.
+ monkeypatch.setenv("UNSLOTH_LLAMA_CPP_BACKEND", "auto")
+ _install(monkeypatch, tmp_path, backend = "rocm", backend_request = "auto")
+ _drifted(monkeypatch)
+ assert upd.get_update_status()["backend_migration_available"] is True
+
+
+def test_an_explicit_recheck_re_resolves_the_backend(monkeypatch, tmp_path):
+ # The resolver is memoized for 24h, so force_refresh has to reach it or "check again"
+ # answers from the pre-change resolve for the rest of the TTL.
+ _install(monkeypatch, tmp_path, backend = "rocm", backend_request = "auto")
+ _drifted(monkeypatch)
+ seen: list = []
+ real = upd._pending_backend_migration
+
+ def _spy(
+ binary,
+ marker,
+ *,
+ force_refresh = False,
+ ):
+ seen.append(force_refresh)
+ return real(binary, marker, force_refresh = force_refresh)
+
+ monkeypatch.setattr(upd, "_pending_backend_migration", _spy)
+ upd.get_update_status(force_refresh = True)
+ assert seen == [True], seen
+
+
+def test_a_migration_keeps_a_pending_whisper_update(monkeypatch):
+ # A migration carries a backend request but is update-behaved, and the switch branch's
+ # repair_pairing_plan() returns no phase for a self-contained whisper install.
+ chained = {"phase": {"kind": "whisper", "tag": "w2"}, "update_available": True}
+ monkeypatch.setattr(upd, "_whisper_chain_status", lambda **kw: chained)
+ repair_calls = []
+ monkeypatch.setattr(
+ whisper_upd, "repair_pairing_plan", lambda: (repair_calls.append(True), {})[1]
+ )
+ monkeypatch.setattr(whisper_upd, "slim_pairing_is_stale", lambda: True)
+
+ plan = _whisper_phase_plan("auto", llama_will_run = True, migration = True)
+ assert plan == chained, plan
+ assert repair_calls == [], "a migration must not take the repair-only branch"
+
+
+def test_a_plain_update_that_can_move_the_backend_still_re_pairs_whisper(monkeypatch, tmp_path):
+ # An update passes no --llama-backend, so a default can move under it, and with whisper
+ # current nothing carries the re-pair a slim install needs.
+ _install(monkeypatch, tmp_path) # backend_request "auto"
+ monkeypatch.setattr(upd, "_whisper_chain_status", lambda **kw: {"skip_reason": "up_to_date"})
+ repair = {"update_available": True, "phase": {"repair": True}}
+ monkeypatch.setattr(whisper_upd, "repair_pairing_plan", lambda: repair)
+
+ assert _whisper_phase_plan(None, llama_will_run = True) is repair
+ assert _whisper_phase_plan(None, llama_will_run = False)["skip_reason"] == "up_to_date"
+
+
+def test_a_recorded_backend_choice_does_not_schedule_a_re_pair(monkeypatch, tmp_path):
+ # Control: a recorded choice is preserved, so an update cannot move that install's
+ # backend and its pairing cannot go stale.
+ _install(monkeypatch, tmp_path, backend_request = "cuda")
+ monkeypatch.setattr(upd, "_whisper_chain_status", lambda **kw: {"skip_reason": "up_to_date"})
+ monkeypatch.setattr(whisper_upd, "repair_pairing_plan", lambda: {"phase": {"repair": True}})
+ assert _whisper_phase_plan(None, llama_will_run = True)["skip_reason"] == "up_to_date"
+
+
+def test_a_self_contained_whisper_keeps_its_up_to_date_reason(monkeypatch, tmp_path):
+ # A re-pair exists only for a slim install, and reporting "self_contained" where
+ # whisper has nothing to catch up on renames a reason the UI already shows.
+ _install(monkeypatch, tmp_path)
+ monkeypatch.setattr(upd, "_whisper_chain_status", lambda **kw: {"skip_reason": "up_to_date"})
+ monkeypatch.setattr(
+ whisper_upd, "repair_pairing_plan", lambda: {"skip_reason": "self_contained", "phase": None}
+ )
+ assert _whisper_phase_plan(None, llama_will_run = True)["skip_reason"] == "up_to_date"
+
+
+def test_a_deliberate_switch_still_takes_the_repair_branch(monkeypatch):
+ monkeypatch.setattr(upd, "_whisper_chain_status", lambda **kw: {"phase": {"kind": "whisper"}})
+ marker = {"repaired": True}
+ monkeypatch.setattr(whisper_upd, "repair_pairing_plan", lambda: marker)
+ monkeypatch.setattr(whisper_upd, "slim_pairing_is_stale", lambda: True)
+ assert _whisper_phase_plan("vulkan", llama_will_run = True) is marker
diff --git a/studio/backend/tests/test_llama_cpp_update.py b/studio/backend/tests/test_llama_cpp_update.py
index 2e593f1475a..d2860700ede 100644
--- a/studio/backend/tests/test_llama_cpp_update.py
+++ b/studio/backend/tests/test_llama_cpp_update.py
@@ -67,7 +67,17 @@ _REAL_POPEN = subprocess.Popen
def _installer_command(cmd) -> bool:
- return any("install_llama_prebuilt" in str(part) for part in cmd)
+ """An INSTALL spawn, not one of the installer's read-only resolvers.
+
+ The same script answers --resolve-prebuilt / --resolve-backends, and the status
+ poll runs one to spot a drifted automatic backend. Faking those would hand the
+ caller's captured argv to a probe instead of to the install, which is the #8170
+ failure the docstring below describes, arriving from inside this module.
+ """
+ parts = [str(part) for part in cmd]
+ if not any("install_llama_prebuilt" in part for part in parts):
+ return False
+ return not any(part.startswith("--resolve-") for part in parts)
def _patch_installer_popen(
@@ -144,6 +154,7 @@ def _clean_state(monkeypatch, tmp_path):
freshness.reset_caches()
upd._reset_job_for_tests()
upd._resolve_memo.clear()
+ upd._backends_memo.clear()
# Isolate the freshness disk cache so the suite never writes the real
# ~/.unsloth cache (the default when storage_roots can't be imported).
monkeypatch.setattr(freshness, "_cache_dir", lambda: tmp_path / ".freshness_cache")
@@ -159,6 +170,7 @@ def _clean_state(monkeypatch, tmp_path):
freshness.reset_caches()
upd._reset_job_for_tests()
upd._resolve_memo.clear()
+ upd._backends_memo.clear()
def _no_prebuilt(monkeypatch):
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 7dc7bc21432..6822a6abacc 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -1095,6 +1095,7 @@ def _mock_override_store(monkeypatch):
entry_value,
*,
fill_absent_fields = False,
+ coupled_fields = (),
):
current = dict(store.get(key) or {})
if fill_absent_fields:
@@ -1103,7 +1104,11 @@ def _mock_override_store(monkeypatch):
return current
stored = current.get(entry_key)
if isinstance(stored, dict):
- current[entry_key] = {**entry_value, **stored}
+ incoming = entry_value
+ for group in coupled_fields:
+ if any(field in stored for field in group):
+ incoming = {k: v for k, v in incoming.items() if k not in group}
+ current[entry_key] = {**incoming, **stored}
else:
current[entry_key] = entry_value
elif entry_value:
@@ -6222,6 +6227,30 @@ def test_normalize_model_override_drops_unusable_fields_and_keeps_the_rest():
assert entry == {"max_seq_length": 8192, "speculative_type": "mtp", "gpu_ids": [1, 0, 2]}
+def test_gpu_index_kind_is_stored_only_when_it_is_not_the_legacy_default():
+ # Absent means physical, so writing it back would churn every row for no information.
+ physical = settings.normalize_model_override({"gpu_ids": [0], "gpu_index_kind": "physical"})
+ assert physical == {"gpu_ids": [0]}
+ assert settings.normalize_model_override({"gpu_ids": [0]}) == {"gpu_ids": [0]}
+ vulkan = settings.normalize_model_override({"gpu_ids": [0], "gpu_index_kind": "vulkan"})
+ assert vulkan == {"gpu_ids": [0], "gpu_index_kind": "vulkan"}
+ assert settings.normalize_model_override({"gpu_index_kind": "vulkan"}) == {}
+
+
+ "override, expected",
+ [
+ ({}, "physical"),
+ ({"gpu_ids": [0]}, "physical"),
+ ({"gpu_ids": [0], "gpu_index_kind": "vulkan"}, "vulkan"),
+ ({"gpu_ids": [0], "gpu_index_kind": "metal"}, "physical"),
+ ({"gpu_ids": [0], "gpu_index_kind": None}, "physical"),
+ ],
+)
+def test_stored_gpu_index_kind_reads_absent_as_physical(override, expected):
+ assert settings.stored_gpu_index_kind(override) == expected
+
+
def test_normalize_model_override_rejects_oversized_chat_template():
small = settings.normalize_model_override({"chat_template_override": "{{ bos }}"})
assert small["chat_template_override"] == "{{ bos }}"
@@ -6752,6 +6781,25 @@ def test_retiring_a_spelling_leaves_every_other_entry_alone(override_store):
assert resp.overrides[_LEGACY_SNAPSHOT]["max_seq_length"] == 4096
+def test_a_fill_never_labels_the_server_s_gpu_pin_with_this_browser_s_index_space(override_store):
+ # Two browsers against one server: the stored pin is physical and this backfill offers
+ # Vulkan ordinals, so the qualifier cannot arrive without its ids.
+ settings.set_model_override("unsloth/B-GGUF:Q4_K_M", gpu_ids = [0, 1])
+
+ resp = _put(
+ "unsloth/B-GGUF:Q4_K_M",
+ gpu_ids = [2],
+ gpu_index_kind = "vulkan",
+ max_seq_length = 32768,
+ fill_absent_fields = True,
+ )
+ entry = resp.overrides["unsloth/B-GGUF:Q4_K_M"]
+ assert entry["gpu_ids"] == [0, 1]
+ assert "gpu_index_kind" not in entry
+ assert settings.stored_gpu_index_kind(entry) == "physical"
+ assert entry["max_seq_length"] == 32768
+
+
def test_the_one_time_fill_retires_nothing(override_store):
# fill_absent_fields only adds what is missing; the migration mirroring both spellings
# of one row must not have its own first write deleted by its second.
@@ -6799,7 +6847,7 @@ def test_stale_gpu_ids_are_dropped_not_fatal(monkeypatch):
lambda mid: {"gpu_ids": [0, 1], "max_seq_length": 4096},
)
- async def _unusable(ids):
+ async def _unusable(ids, index_kind = "physical"):
return False
monkeypatch.setattr(inference_route, "_override_gpu_ids_still_resolve", _unusable)
@@ -6823,7 +6871,7 @@ def test_usable_gpu_ids_are_kept(monkeypatch):
)
monkeypatch.setattr(settings, "get_model_override", lambda mid: {"gpu_ids": [0, 1]})
- async def _usable(ids):
+ async def _usable(ids, index_kind = "physical"):
return True
monkeypatch.setattr(inference_route, "_override_gpu_ids_still_resolve", _usable)
@@ -6854,9 +6902,9 @@ def test_vulkan_ordinal_absent_from_the_probe_is_unusable(monkeypatch):
monkeypatch.setattr(
LlamaCppBackend, "_get_gpu_memory", staticmethod(lambda binary: [(0, 8192)])
)
- assert asyncio.run(inference_route._override_gpu_ids_still_resolve([0])) is True
- assert asyncio.run(inference_route._override_gpu_ids_still_resolve([7])) is False
- assert asyncio.run(inference_route._override_gpu_ids_still_resolve([0, 1])) is False
+ assert asyncio.run(inference_route._override_gpu_ids_still_resolve([0], "vulkan")) is True
+ assert asyncio.run(inference_route._override_gpu_ids_still_resolve([7], "vulkan")) is False
+ assert asyncio.run(inference_route._override_gpu_ids_still_resolve([0, 1], "vulkan")) is False
def test_vulkan_probe_without_a_binary_does_not_block_the_load(monkeypatch):
@@ -6865,7 +6913,56 @@ def test_vulkan_probe_without_a_binary_does_not_block_the_load(monkeypatch):
monkeypatch.setattr(LlamaCppBackend, "_is_vulkan_backend", staticmethod(lambda: True))
monkeypatch.setattr(LlamaCppBackend, "_find_llama_server_binary", staticmethod(lambda: None))
- assert asyncio.run(inference_route._override_gpu_ids_still_resolve([0])) is True
+ assert asyncio.run(inference_route._override_gpu_ids_still_resolve([0], "vulkan")) is True
+
+
+def _pin_resolves_on_a_host_with_device_0(monkeypatch):
+ """Make device 0 exist, so the index-kind check is the only thing under test.
+
+ Without this the whole helper falls to its `except: return False` on a CPU-only
+ runner, which is how the mismatch cases below would pass for the wrong reason and
+ how the matching case failed on CI while passing on a GPU box.
+ """
+ import utils.hardware as hardware_pkg
+ from utils.hardware import DeviceType
+ from utils.hardware import hardware as hardware_mod
+
+ monkeypatch.setattr(hardware_pkg, "get_device", lambda: DeviceType.CUDA)
+ monkeypatch.setattr(
+ hardware_mod, "resolve_requested_gpu_ids", lambda ids, is_vulkan = False: list(ids)
+ )
+
+
+def test_a_pin_written_in_the_other_index_space_is_unusable(monkeypatch):
+ # What the availability checks cannot see: ordinal 0 and physical device 0 both exist,
+ # so a pin carried across a backend change passes every presence test.
+ from core.inference.llama_cpp import LlamaCppBackend
+
+ _pin_resolves_on_a_host_with_device_0(monkeypatch)
+ monkeypatch.setattr(
+ LlamaCppBackend, "_find_llama_server_binary", staticmethod(lambda: "/bin/llama-server")
+ )
+ monkeypatch.setattr(
+ LlamaCppBackend, "_get_gpu_memory", staticmethod(lambda binary: [(0, 8192)])
+ )
+ for installed_is_vulkan, stored_kind in (
+ (True, "physical"),
+ (False, "vulkan"),
+ ):
+ monkeypatch.setattr(
+ LlamaCppBackend, "_is_vulkan_backend", staticmethod(lambda: installed_is_vulkan)
+ )
+ assert (
+ asyncio.run(inference_route._override_gpu_ids_still_resolve([0], stored_kind)) is False
+ ), (installed_is_vulkan, stored_kind)
+
+
+def test_a_rocm_pin_survives_while_the_backend_is_still_rocm(monkeypatch):
+ from core.inference.llama_cpp import LlamaCppBackend
+
+ _pin_resolves_on_a_host_with_device_0(monkeypatch)
+ monkeypatch.setattr(LlamaCppBackend, "_is_vulkan_backend", staticmethod(lambda: False))
+ assert asyncio.run(inference_route._override_gpu_ids_still_resolve([0], "physical")) is True
def test_default_save_preserves_flags_instead_of_removing(override_store):
@@ -7074,7 +7171,7 @@ def test_load_retries_without_gpu_ids_when_the_loader_rejects_the_pin(monkeypatc
settings, "get_model_override", lambda mid: {"gpu_ids": [0], "max_seq_length": 4096}
)
- async def _usable(ids):
+ async def _usable(ids, index_kind = "physical"):
return True
monkeypatch.setattr(inference_route, "_override_gpu_ids_still_resolve", _usable)
@@ -7113,7 +7210,7 @@ def test_a_non_gpu_load_failure_is_not_retried(monkeypatch):
)
monkeypatch.setattr(settings, "get_model_override", lambda mid: {"gpu_ids": [0]})
- async def _usable(ids):
+ async def _usable(ids, index_kind = "physical"):
return True
monkeypatch.setattr(inference_route, "_override_gpu_ids_still_resolve", _usable)
@@ -7781,6 +7878,41 @@ def test_map_entry_fill_reads_and_writes_in_one_transaction(tmp_path, monkeypatc
assert db.get_app_setting(key) == {"a": {"v": 9}}
+def test_a_fill_never_relabels_a_stored_gpu_pin_with_this_browser_s_index_space(
+ tmp_path, monkeypatch
+):
+ """A pin and the index space it is written in are one value.
+
+ The server holds physical ids with no qualifier, which is what every writer
+ before the field meant; this browser's backfill offers Vulkan ordinals. Field
+ by field the ids would stay and the qualifier would land, and the row would
+ then name devices in a space it was never written in.
+ """
+ import storage.studio_db as db
+
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))
+ monkeypatch.setattr(db, "_schema_ready", False)
+
+ key = "test_map_entry_coupled"
+ coupled = (("gpu_ids", "gpu_index_kind"),)
+ db.upsert_app_setting_map_entry(key, "m", {"gpu_ids": [0, 1]})
+ assert db.upsert_app_setting_map_entry(
+ key,
+ "m",
+ {"gpu_ids": [2], "gpu_index_kind": "vulkan", "max_seq_length": 4096},
+ fill_absent_fields = True,
+ coupled_fields = coupled,
+ ) == {"m": {"gpu_ids": [0, 1], "max_seq_length": 4096}}
+ db.upsert_app_setting_map_entry(key, "n", {"max_seq_length": 2048})
+ assert db.upsert_app_setting_map_entry(
+ key,
+ "n",
+ {"gpu_ids": [2], "gpu_index_kind": "vulkan"},
+ fill_absent_fields = True,
+ coupled_fields = coupled,
+ )["n"] == {"max_seq_length": 2048, "gpu_ids": [2], "gpu_index_kind": "vulkan"}
+
+
def test_gpu_ids_dedupe_is_not_a_scan_of_the_list_being_built():
"""gpu_ids arrives from an authenticated client and normalize_model_override
de-duplicates it. Testing membership against the growing list walks up to
diff --git a/studio/backend/utils/llama_cpp_update.py b/studio/backend/utils/llama_cpp_update.py
index 56bcd121552..59a45ecb1c1 100644
--- a/studio/backend/utils/llama_cpp_update.py
+++ b/studio/backend/utils/llama_cpp_update.py
@@ -509,6 +509,14 @@ def _llama_only_status(
except Exception as exc: # pragma: no cover - network defensive
logger.debug("llama update: size lookup failed", error = str(exc))
+ # An automatic install whose detection now resolves elsewhere; nothing else surfaces
+ # it. Skipped while a job runs, and when an update is offered: that update re-detects.
+ to_backend = (
+ None
+ if job_running or update_available
+ else _pending_backend_migration(binary, marker, force_refresh = force_refresh)
+ )
+
with _job_lock:
job = dict(_job)
@@ -523,6 +531,9 @@ def _llama_only_status(
"age_days": freshness.get("age_days"),
"source_build": False,
"update_size_bytes": update_size_bytes,
+ "backend_migration_available": to_backend is not None,
+ "from_backend": marker_backend(marker) if to_backend else None,
+ "to_backend": to_backend,
"job": job,
}
@@ -536,8 +547,14 @@ def _resolve_backends_for_host(
*,
force_refresh: bool = False,
published_repo: Optional[str] = None,
+ rocm_gfx: Optional[str] = None,
) -> Optional[dict]:
- """Ask the installer which backends it could install here. None on any failure."""
+ """Ask the installer which backends it could install here. None on any failure.
+
+ ``rocm_gfx`` replays the marker's arch, as _run_llama_phase does for the install: this
+ subprocess re-probes from scratch, so a host whose arch only Windows setup could infer
+ resolves "auto" to CPU. The REMEMBERED spelling, so a live probe still wins.
+ """
args: list[str] = []
if install_dir is not None:
args.extend(("--install-dir", str(install_dir)))
@@ -550,6 +567,7 @@ def _resolve_backends_for_host(
log_message = "llama backend: resolve-backends failed",
mode = ("--resolve-backends", "latest"),
extra_args = tuple(args),
+ extra_env = {"UNSLOTH_ROCM_GFX_REMEMBERED": rocm_gfx} if rocm_gfx else None,
)
@@ -619,6 +637,65 @@ def _selection_applied(
return resolved is None or installed_backend is None or resolved == installed_backend
+def _remembered_rocm_gfx(marker: Optional[dict]) -> Optional[str]:
+ """The arch to replay when re-resolving, falling back to the installed asset's name.
+
+ The marker carries rocm_gfx only when the install resolved one, and a host whose probe
+ never named an arch is the one that needs the replay. The bundle it runs names the
+ family, which is the record setup.sh reads too.
+ """
+ recorded = (marker or {}).get("rocm_gfx")
+ if recorded:
+ return recorded
+ args = _flow.rocm_install_args((marker or {}).get("asset"))
+ return args[1] if len(args) == 2 and args[0] == "--rocm-gfx" else None
+
+
+def _pending_backend_migration(
+ binary: Optional[str],
+ marker: Optional[dict],
+ *,
+ force_refresh: bool = False,
+) -> Optional[str]:
+ """The backend a re-applied AUTOMATIC selection would install, when it differs.
+
+ The one drift an install can develop untouched: "auto" recorded what detection chose
+ then, and a default can move later (AMD integrated GPUs now route to Vulkan). NOT
+ computed for a concrete recorded choice, which is a decision by hand this must never
+ offer to undo -- which also makes the offer self-limiting, since picking a backend in
+ Settings ends the drift. None on anything unresolved. Shares _backends_memo with
+ get_backend_status, so this costs a subprocess a day.
+ """
+ if marker is None or _switch_support(binary, marker) is not None:
+ return None
+ _override = _env_backend_override()
+ if _override is not None and _override != "auto":
+ # The environment owns the backend, so an offer could not be applied. "auto" is
+ # the exception: it asks for the detection the migration re-applies.
+ return None
+ if marker_backend_request(marker) != "auto":
+ return None
+ repo = marker.get("published_repo") or DEFAULT_PUBLISHED_REPO
+ resolved = _resolve_backends_for_host(
+ _install_dir_for(binary),
+ force_refresh = force_refresh,
+ published_repo = repo,
+ rocm_gfx = _remembered_rocm_gfx(marker),
+ )
+ if not resolved:
+ return None
+ options = _backend_options(resolved)
+ if _selection_applied("auto", marker_backend(marker), options):
+ return None
+ auto = next((option for option in options if option["backend"] == "auto"), None)
+ target = (auto or {}).get("resolved_backend")
+ if target == "cpu" and marker_backend(marker) not in (None, "cpu"):
+ # An empty probe and a host that really lost its GPU look identical from here, and
+ # moving a working GPU install onto CPU is the costly side of that. Settings can.
+ return None
+ return target
+
+
def get_backend_status(*, force_refresh: bool = False) -> dict:
"""Return the installed backend and host-compatible alternatives."""
binary = _find_binary()
@@ -646,7 +723,13 @@ def get_backend_status(*, force_refresh: bool = False) -> dict:
return status
repo = (marker or {}).get("published_repo") or DEFAULT_PUBLISHED_REPO
resolved = _resolve_backends_for_host(
- _install_dir_for(binary), force_refresh = force_refresh, published_repo = repo
+ _install_dir_for(binary),
+ force_refresh = force_refresh,
+ published_repo = repo,
+ # The same recovery the update-status path uses, or the picker describes a
+ # different host: no arch here reads an AMD box with no probes as CPU-only,
+ # so Settings offers an Automatic that installs something else.
+ rocm_gfx = _remembered_rocm_gfx(marker),
)
if not resolved:
# Keep showing the installed backend without guessing alternatives.
@@ -676,6 +759,7 @@ def _run_llama_phase(
llama_backend: Optional[str] = None,
rocm_gfx: Optional[str] = None,
backend_request: Optional[str] = None,
+ migration_target: Optional[str] = None,
) -> dict:
"""The llama phase of a chained update: put the backend into a maintenance
state, run the installer for the latest prebuilt, then refresh caches so the
@@ -795,14 +879,23 @@ def _run_llama_phase(
)
kept_existing = backend_request is None and new_tag is not None and new_tag == prior_tag
+ # A migration asks for "auto", so it can land back where it started (the ROCm
+ # fallback behind the preference), which would read as applied and be re-offered.
+ migration_kept = bool(migration_target) and new_backend != migration_target
logger.info(
"llama update: success",
to_tag = new_tag,
backend = new_backend,
kept_existing = kept_existing,
+ migration_applied = None if not migration_target else not migration_kept,
)
reload_hint = " Reload your model to use it." if model_was_active else ""
- if backend_request is not None:
+ if migration_kept:
+ message = (
+ f"llama.cpp could not be moved to {migration_target} right now, so the "
+ f"existing {new_backend or 'installed'} build was kept. Try again later."
+ )
+ elif backend_request is not None:
message = f"llama.cpp is now running on {new_backend or backend_request}.{reload_hint}"
elif kept_existing:
# The phase only runs when a newer release was offered, so naming the kept
@@ -818,6 +911,7 @@ def _run_llama_phase(
"backend": new_backend,
"reload_required": model_was_active,
"kept_existing": kept_existing,
+ "migration_applied": None if not migration_target else not migration_kept,
"message": message,
}
except _flow.InstallerExit as exc:
@@ -961,6 +1055,8 @@ def _plan_llama_phase(backend_request: Optional[str] = None) -> dict:
# start an install when the latest is not actually newer (force a fresh
# check so a stale 24h cache can't wrongly block a real update either).
# A switch replaces the backend at the same release.
+ migration = False
+ migration_target = None
status = (
{}
if backend_request is not None
@@ -970,21 +1066,33 @@ def _plan_llama_phase(backend_request: Optional[str] = None) -> dict:
)
)
if backend_request is None and not status.get("update_available"):
- return {
- "skip_reason": "up_to_date",
- "refusal": {
- "started": False,
- "reason": "up_to_date",
- "message": "The installed llama.cpp build is already at the latest prebuilt.",
- },
- }
+ # Nothing newer to install, but "auto" can resolve elsewhere now. Re-asking for
+ # "auto" keeps it automatic, so rocm_gfx and the crash recovery survive.
+ migration_target = _pending_backend_migration(binary, marker)
+ if migration_target is None:
+ return {
+ "skip_reason": "up_to_date",
+ "refusal": {
+ "started": False,
+ "reason": "up_to_date",
+ "message": (
+ "The installed llama.cpp build is already at the latest prebuilt."
+ ),
+ },
+ }
+ backend_request = "auto"
+ migration = True
install_dir = _install_dir_for(binary)
repo = marker.get("published_repo") or DEFAULT_PUBLISHED_REPO
from_tag = marker.get("tag") or marker.get("release_tag")
asset = marker.get("asset")
# Updates let the installer preserve the marker's recorded choice.
llama_backend = marker.get("llama_backend")
- rocm_gfx = marker.get("rocm_gfx")
+ # Recovered, not read: the status path offers the migration through
+ # _remembered_rocm_gfx, so an apply reading the bare field would re-resolve
+ # without the arch on exactly the host the recovery exists for, and refuse
+ # the offer it just made as already_selected.
+ rocm_gfx = _remembered_rocm_gfx(marker)
# Install exactly the release the banner offered: the installer's own
# "latest" is commit-date ordered and can lag the published_at pick
# above, reinstalling the current build in a loop (the #6219 class).
@@ -1051,6 +1159,8 @@ def _plan_llama_phase(backend_request: Optional[str] = None) -> dict:
# No pin: source-build detection resolves via --resolve-prebuilt latest,
# the same resolver the unpinned apply uses, so the two already agree.
pin_release_tag = None
+ migration = False
+ migration_target = None
if install_dir is None:
return {
@@ -1072,6 +1182,11 @@ def _plan_llama_phase(backend_request: Optional[str] = None) -> dict:
"llama_backend": llama_backend,
"rocm_gfx": rocm_gfx,
"backend_request": backend_request,
+ # So the caller keeps presenting this as the update it is, not the switch its
+ # backend_request would make it look like.
+ "migration": migration,
+ # The backend the offer named, so the phase can say whether it landed.
+ "migration_target": migration_target,
}
}
@@ -1120,11 +1235,40 @@ def start_backend_switch(backend: str) -> dict:
return _start_llama_job(backend_request = normalized)
+def _update_can_move_the_backend(llama_will_run: bool) -> bool:
+ """Whether an update that names no backend could still land on a different one.
+
+ Detection re-runs, so a default can move under it; only an automatic install is
+ exposed. Read from the marker rather than resolved, since resolving costs a subprocess
+ at planning time, and over-answering is cheap: the repair phase does nothing when the
+ backend did not move.
+ """
+ if not llama_will_run:
+ return False
+ return marker_backend_request(read_install_marker(_find_binary())) == "auto"
+
+
+def _repair_pairing_plan_or_empty(llama_will_run: bool, llama_skip_reason: Optional[str]) -> dict:
+ """The slim re-pair plan, or {} when there is nothing to re-pair against."""
+ try:
+ from utils import whisper_cpp_update
+ if not llama_will_run:
+ if llama_skip_reason != "already_selected":
+ return {}
+ if not whisper_cpp_update.slim_pairing_is_stale():
+ return {}
+ return whisper_cpp_update.repair_pairing_plan()
+ except Exception as exc: # pragma: no cover - defensive
+ logger.debug("llama switch: whisper repair probe failed", error = str(exc))
+ return {}
+
+
def _whisper_phase_plan(
backend_request: Optional[str],
*,
llama_will_run: bool,
llama_skip_reason: Optional[str] = None,
+ migration: bool = False,
) -> dict:
"""Whisper's half of the chained job: catch up on releases for an update, or
re-pair with the new backend for a switch.
@@ -1141,21 +1285,22 @@ def _whisper_phase_plan(
away and back. So allow a repair-only job for that one refusal, and only while the
pairing is genuinely stale, which keeps an ordinary already-selected request a
refusal rather than a no-op job reporting success."""
- if backend_request is None:
- return (
+ # A migration is switch-shaped but update-behaved, so whisper needs the chained plan:
+ # the repair-only branch has no phase for a self-contained install and drops updates.
+ if backend_request is None or migration:
+ chained = (
_whisper_chain_status(force_refresh = True, paired_llama_will_update = llama_will_run) or {}
)
- try:
- from utils import whisper_cpp_update
- if not llama_will_run:
- if llama_skip_reason != "already_selected":
- return {}
- if not whisper_cpp_update.slim_pairing_is_stale():
- return {}
- return whisper_cpp_update.repair_pairing_plan()
- except Exception as exc: # pragma: no cover - defensive
- logger.debug("llama switch: whisper repair probe failed", error = str(exc))
- return {}
+ if chained.get("phase") is not None:
+ return chained
+ if backend_request is None:
+ if not _update_can_move_the_backend(llama_will_run):
+ return chained
+ # Whisper has nothing to catch up on, so the chained answer stands unless a
+ # re-pair is owed.
+ repair = _repair_pairing_plan_or_empty(llama_will_run, llama_skip_reason)
+ return repair if repair.get("phase") is not None else chained
+ return _repair_pairing_plan_or_empty(llama_will_run, llama_skip_reason)
def _claim_operation(backend_request: Optional[str]) -> bool:
@@ -1226,17 +1371,28 @@ def _start_llama_job(backend_request: Optional[str] = None) -> dict:
}
handed_to_worker = False
+ migration = False
try:
# The operation reservation starts before any marker read or resolver
# call. A second update/switch cannot change the install between this
# plan and the worker that applies it.
llama_plan = _plan_llama_phase(backend_request)
llama_spec = llama_plan.get("spec")
+ if llama_spec is not None and llama_spec.get("migration"):
+ # The planner turned an up-to-date update into a re-application of "auto";
+ # adopt its request, and keep the claimed operation the offered "update".
+ migration = True
+ backend_request = llama_spec["backend_request"]
+ with _job_lock:
+ _job.update(requested_backend = backend_request)
if backend_request is not None and llama_spec is not None:
resolved = _resolve_backends_for_host(
llama_spec["install_dir"],
force_refresh = True,
published_repo = llama_spec["repo"],
+ # Same replay the status path uses: without it this re-probe resolves
+ # "auto" to CPU and the offered migration refuses as already_selected.
+ rocm_gfx = llama_spec.get("rocm_gfx"),
)
if not resolved:
return _finish_planning_refusal(
@@ -1272,6 +1428,7 @@ def _start_llama_job(backend_request: Optional[str] = None) -> dict:
backend_request,
llama_will_run = llama_spec is not None,
llama_skip_reason = llama_plan.get("skip_reason"),
+ migration = migration,
)
whisper_spec = (whisper_plan or {}).get("phase")
if llama_spec is None and whisper_spec is None:
@@ -1302,7 +1459,7 @@ def _start_llama_job(backend_request: Optional[str] = None) -> dict:
"weight": _LLAMA_PHASE_WEIGHT,
"failure_message": (
f"Could not switch llama.cpp to {backend_request}."
- if backend_request is not None
+ if backend_request is not None and not migration
else "llama.cpp update failed."
),
"skip_reason": llama_plan.get("skip_reason"),
@@ -1318,6 +1475,7 @@ def _start_llama_job(backend_request: Optional[str] = None) -> dict:
llama_backend = llama_spec.get("llama_backend"),
rocm_gfx = llama_spec.get("rocm_gfx"),
backend_request = llama_spec.get("backend_request"),
+ migration_target = llama_spec.get("migration_target"),
)
)
if llama_spec
diff --git a/studio/backend/utils/openai_auto_switch_settings.py b/studio/backend/utils/openai_auto_switch_settings.py
index 434511878da..9ca05a93ff2 100644
--- a/studio/backend/utils/openai_auto_switch_settings.py
+++ b/studio/backend/utils/openai_auto_switch_settings.py
@@ -43,7 +43,7 @@ import os
import re
import threading
import time
-from typing import Any, Optional
+from typing import Any, Mapping, Optional
OPENAI_AUTO_SWITCH_SETTING_KEY = "openai_api_auto_switch_model"
OPENAI_AUTO_DOWNLOAD_SETTING_KEY = "openai_api_auto_download_model"
@@ -461,6 +461,13 @@ MAX_CHAT_TEMPLATE_OVERRIDE_BYTES = 65_536
# Highest device index a gpu_ids entry may name; also bounds how many ids one entry holds.
MAX_GPU_ID = 1024
+# Which index space a stored gpu_ids belongs to: the same integers are ggml Vulkan ordinals
+# under a Vulkan build and physical device ids elsewhere, so the namespace travels with the
+# ids or a pin addresses another card. Mirrors GpuIndexKind in hooks/gpu-selection.ts,
+# legacy rule included: an absent kind is "physical".
+VALID_GPU_INDEX_KINDS = frozenset({"physical", "vulkan"})
+LEGACY_GPU_INDEX_KIND = "physical"
+
def _clean_str(value: Any, allowed: frozenset[str]) -> Optional[str]:
if not isinstance(value, str):
@@ -621,10 +628,26 @@ def normalize_model_override(
cleaned_ids.append(parsed)
if cleaned_ids:
entry["gpu_ids"] = cleaned_ids
+ index_kind = _clean_str(payload.get("gpu_index_kind"), VALID_GPU_INDEX_KINDS)
+ # Stored only when it is not the legacy default, so existing rows stay
+ # byte-identical.
+ if index_kind and index_kind != LEGACY_GPU_INDEX_KIND:
+ entry["gpu_index_kind"] = index_kind
return entry
+def stored_gpu_index_kind(override: Mapping[str, Any]) -> str:
+ """The index space ``override["gpu_ids"]`` was written in.
+
+ Absent means physical, which is the only thing any writer before the field could
+ have meant. Anything unrecognised means the same: a row this build cannot read is
+ not evidence of a Vulkan pin.
+ """
+ kind = override.get("gpu_index_kind")
+ return kind if kind in VALID_GPU_INDEX_KINDS else LEGACY_GPU_INDEX_KIND
+
+
def resolve_fit_max_seq_length(override: dict[str, Any], *, is_gguf: bool) -> Optional[int]:
"""The ``max_seq_length`` an API load should send for this override.
@@ -1085,6 +1108,9 @@ def set_model_override(
model_id.strip(),
entry or None,
fill_absent_fields = fill_absent_fields,
+ # The pin and its index space are one value: filling the qualifier onto ids this
+ # browser did not write relabels them.
+ coupled_fields = (("gpu_ids", "gpu_index_kind"),),
)
_invalidate(MODEL_OVERRIDES_SETTING_KEY)
return entry
diff --git a/studio/backend/utils/prebuilt/update_flow.py b/studio/backend/utils/prebuilt/update_flow.py
index cad61f09350..bdef55fc069 100644
--- a/studio/backend/utils/prebuilt/update_flow.py
+++ b/studio/backend/utils/prebuilt/update_flow.py
@@ -264,12 +264,18 @@ def resolve_prebuilt_for_host(
log_message: str,
extra_args: tuple[str, ...] = (),
mode: tuple[str, ...] = ("--resolve-prebuilt", "latest"),
+ extra_env: Optional[dict[str, str]] = None,
) -> Optional[dict]:
"""Run one of the installer's read-only resolvers (``--resolve-prebuilt latest``
by default) with ``--output-format json``; return the parsed payload or None.
- Fail-open: any error -> None so a source build never blocks the app."""
+ Fail-open: any error -> None so a source build never blocks the app.
+
+ ``extra_env`` carries what the resolver cannot re-derive: the arch a previous
+ install recorded, which setup forwarded from a probe this subprocess does not
+ have. Part of the cache key, so changing it re-resolves rather than replaying a
+ value found without it."""
now = time.time()
- cache_key = (*mode, *extra_args)
+ cache_key = (*mode, *extra_args, *sorted((extra_env or {}).items()))
if not force_refresh and memo.get("key") == cache_key:
if now - memo.get("at", 0.0) < RESOLVE_TTL_SECONDS:
return memo.get("value")
@@ -293,6 +299,7 @@ def resolve_prebuilt_for_host(
encoding = "utf-8",
errors = "replace",
timeout = 60,
+ env = {**os.environ, **extra_env} if extra_env else None,
)
out = (proc.stdout or "").strip()
if proc.returncode == 0 and out:
diff --git a/studio/backend/utils/whisper_cpp_update.py b/studio/backend/utils/whisper_cpp_update.py
index 33b657cfe27..321423e0196 100644
--- a/studio/backend/utils/whisper_cpp_update.py
+++ b/studio/backend/utils/whisper_cpp_update.py
@@ -589,6 +589,28 @@ def chained_phase_plan(
return plan
+def _phase_repaired_to_installed_llama(phase: dict) -> dict:
+ """Point a slim phase at the backend the llama phase actually installed.
+
+ The plan is built before that phase runs, so on a backend migration it still names
+ the outgoing runtime: installing it would fetch a whisper build for a ggml that is no
+ longer there, and pass the old asset's arch flags with it. A self-contained install
+ carries its own ggml, so llama's backend is not its backend and it keeps its own.
+ """
+ backend, asset = _installed_llama_bundle()
+ if not backend or backend == phase.get("backend"):
+ return phase
+ marker = read_install_marker(_find_binary())
+ if not marker or marker.get("install_kind") != "slim":
+ return phase
+ logger.info(
+ "whisper update: re-pairing the chained phase with the installed llama backend",
+ was = phase.get("backend"),
+ now = backend,
+ )
+ return {**phase, "backend": backend, "asset": asset}
+
+
def run_chained_phase_after_llama(phase: dict, set_progress) -> dict:
"""Make the pairing check chained_phase_plan deferred, now that llama is installed.
@@ -599,6 +621,7 @@ def run_chained_phase_after_llama(phase: dict, set_progress) -> dict:
An attempt that goes ahead still surfaces exit 2, which is what keeps an
incompatible release actionable rather than a false success.
"""
+ phase = _phase_repaired_to_installed_llama(phase)
try:
backend = phase.get("backend")
repo = phase.get("repo")
diff --git a/studio/frontend/src/components/llama-update-banner.tsx b/studio/frontend/src/components/llama-update-banner.tsx
index eec80260e38..0baf588e82b 100644
--- a/studio/frontend/src/components/llama-update-banner.tsx
+++ b/studio/frontend/src/components/llama-update-banner.tsx
@@ -4,8 +4,15 @@
import { Button } from "@/components/ui/button";
import { LlamaUpdateChangelogPanel } from "@/components/update/llama-update-changelog-panel";
import { resyncInferenceStatusAfterServerModelChange } from "@/features/chat";
-import { useLlamaUpdateCheck } from "@/hooks/use-llama-update-check";
+import {
+ llamaUpdateOffered,
+ useLlamaUpdateCheck,
+} from "@/hooks/use-llama-update-check";
import { useShowLlamaUpdateBanner } from "@/hooks/use-llama-update-pref";
+import {
+ llamaReleaseChanged,
+ llamaUpdateToastMessage,
+} from "@/lib/llama-job-lifecycle";
import { toast } from "@/lib/toast";
import { cn } from "@/lib/utils";
import { Download } from "lucide-react";
@@ -13,6 +20,24 @@ import { type ReactElement, useEffect, useRef, useState } from "react";
// Creep toward this cap between coarse backend progress updates.
const RUNNING_CAP = 0.95;
+// The banner is not translated, so these mirror features/settings/lib/llama-backend-
+// labels.ts. An unknown backend prints its own identifier rather than nothing.
+const BACKEND_LABELS: Record<string, string> = {
+ auto: "Automatic",
+ cpu: "CPU",
+ cuda: "CUDA",
+ rocm: "ROCm",
+ vulkan: "Vulkan",
+ metal: "Metal",
+};
+
+function backendLabel(backend: string | null | undefined): string {
+ if (!backend) {
+ return "";
+ }
+ return BACKEND_LABELS[backend] ?? backend;
+}
+
// Smooth coarse backend progress without freezing between milestones.
function useSmoothedProgress(
active: boolean,
@@ -96,13 +121,20 @@ export function LlamaUpdateBanner({
async function handleUpdate() {
const component = status?.component ?? "llama.cpp";
+ // Read before applying: the status refreshes as the job runs.
+ const migrating = Boolean(status?.backend_migration_available);
const result = await apply();
if (result?.ok) {
const updatedTag = result.tag ?? status?.latest_tag ?? "the latest build";
- const reloadHint = result.reloadRequired
- ? " Reload your model to use it."
- : "";
- toast.success(`${component} updated to ${updatedTag}.${reloadHint}`);
+ toast.success(
+ llamaUpdateToastMessage({
+ component,
+ migrating,
+ jobMessage: result.message,
+ updatedTag,
+ reloadRequired: result.reloadRequired,
+ }),
+ );
} else if (result) {
toast.error(
`${component} update failed: ${result.error ?? "unknown error"}`,
@@ -114,13 +146,33 @@ export function LlamaUpdateBanner({
showBannerPref &&
visible &&
status != null &&
- (status.update_available || applying);
+ (llamaUpdateOffered(status) || applying);
const sizeBytes = status?.update_size_bytes ?? null;
const component = status?.component ?? "llama.cpp";
const latestTag = status?.latest_tag ?? null;
const installedTag = status?.installed_tag ?? null;
+ // A migration re-applies the install's own automatic choice, so it can be offered at a
+ // release the machine already has, where the backend pair replaces the version line.
+ const backendChange =
+ status?.backend_migration_available && status.to_backend
+ ? `${backendLabel(status.from_backend)} \u2192 ${backendLabel(status.to_backend)}`
+ : null;
+ const versionChanged = llamaReleaseChanged(
+ Boolean(status?.update_available),
+ installedTag,
+ latestTag,
+ );
+ // Only the migration offer, and only the pair it was measured on: a version update
+ // or a hand-picked switch keeps the plain line.
+ const restartNote =
+ backendChange &&
+ !versionChanged &&
+ status?.from_backend === "rocm" &&
+ status?.to_backend === "vulkan"
+ ? "Vulkan is >10% faster than ROCM. No restart needed after update"
+ : "No restart needed after update";
const changelogKey =
- component === "llama.cpp" && installedTag && latestTag
+ component === "llama.cpp" && versionChanged
? `${installedTag}\0${latestTag}`
: null;
const changelogAvailable = Boolean(changelogKey && !status?.source_build);
@@ -200,17 +252,33 @@ export function LlamaUpdateBanner({
<p className="font-heading text-base font-medium text-foreground">
{applying
? `Updating ${component}...`
- : `New ${component} update`}
+ : backendChange && !versionChanged
+ ? `New ${component} backend`
+ : `New ${component} update`}
</p>
<p className="mt-0.5 text-xs text-muted-foreground">
- {status?.installed_tag ?? "unknown"} &rarr;{" "}
- <span className="font-medium text-foreground">
- {status?.latest_tag ?? ""}
- </span>
+ {versionChanged || !backendChange ? (
+ <>
+ {installedTag ?? "unknown"} &rarr;{" "}
+ <span className="font-medium text-foreground">
+ {latestTag ?? ""}
+ </span>
+ </>
+ ) : (
+ <>
+ {backendLabel(status?.from_backend)} &rarr;{" "}
+ <span className="font-medium text-foreground">
+ {backendLabel(status?.to_backend)}
+ </span>
+ </>
+ )}
</p>
<p className="mt-1 text-ui-11 text-muted-foreground/70">
- {sizeLabel ? `${sizeLabel} download · ` : ""}No restart needed
- after update
+ {sizeLabel ? `${sizeLabel} download · ` : ""}
+ {versionChanged && backendChange
+ ? `${backendChange} backend · `
+ : ""}
+ {restartNote}
</p>
</div>
</div>
diff --git a/studio/frontend/src/features/model-picker/api/model-overrides.ts b/studio/frontend/src/features/model-picker/api/model-overrides.ts
index 1153caea684..d7847e28d65 100644
--- a/studio/frontend/src/features/model-picker/api/model-overrides.ts
+++ b/studio/frontend/src/features/model-picker/api/model-overrides.ts
@@ -6,6 +6,7 @@
// routes/inference.py reads this map and rebuilds the picker's LoadRequest.
import { authFetch } from "@/features/auth";
+import type { GpuIndexKind } from "@/hooks/gpu-selection";
import { readFastApiError } from "@/lib/format-fastapi-error";
import {
normalizeGgufVariantIdentity,
@@ -65,6 +66,9 @@ export interface ApiModelOverride {
n_cpu_moe?: number;
// biome-ignore lint/style/useNamingConvention: API schema
gpu_ids?: number[];
+ // Which index space gpu_ids is in. Absent means "physical", all an older row could mean.
+ // biome-ignore lint/style/useNamingConvention: API schema
+ gpu_index_kind?: GpuIndexKind;
}
export type ApiModelOverrides = Record<string, ApiModelOverride>;
@@ -278,8 +282,7 @@ export function fromApiOverride(
const extraArgs = Array.isArray(override.llama_extra_args)
? override.llama_extra_args
: local.llamaExtraArgs;
- // Only a physical pin travels (toApiOverride drops the rest), so a row without ids says
- // nothing about placement and a local Vulkan ordinal keeps its own namespace.
+ // A row without ids says nothing about placement, so the local pin keeps its namespace.
const serverGpuIds = override.gpu_ids?.length ? override.gpu_ids : null;
// The pin is ONE setting in one of two fields, and an edit clears the other
// (contextPinPatch). Filling them from different sources mints a record that loads at
@@ -317,8 +320,9 @@ export function fromApiOverride(
gpuLayers: override.gpu_layers ?? local.gpuLayers,
nCpuMoe: override.n_cpu_moe ?? local.nCpuMoe,
selectedGpuIds: serverGpuIds ?? local.selectedGpuIds ?? null,
+ // reconcileGpuSelection drops the pin if this host numbers its devices the other way.
selectedGpuIndexKind: serverGpuIds
- ? "physical"
+ ? (override.gpu_index_kind ?? "physical")
: (local.selectedGpuIndexKind ?? null),
});
// normalizePerModelConfig collapses an empty list to null. The server uses [] as a tombstone
@@ -407,16 +411,16 @@ export function toApiOverride(config: PerModelConfig | null): ApiModelOverride {
if (typeof config.nCpuMoe === "number" && config.nCpuMoe > 0) {
payload.n_cpu_moe = config.nCpuMoe;
}
- // Only a physical pin travels. The same integers are a Vulkan ordinal under Vulkan and a
- // CUDA/ROCm index elsewhere, and the override carries no namespace, so after a backend
- // change the server would pin a different device. An absent kind predates the field.
+ // The pin travels with its namespace, or after a backend change the server pins a
+ // different device; reconcileGpuSelection drops it on a mismatch instead.
const gpuIndexKind = config.selectedGpuIndexKind ?? "physical";
- if (
- config.selectedGpuIds &&
- config.selectedGpuIds.length > 0 &&
- gpuIndexKind === "physical"
- ) {
+ if (config.selectedGpuIds && config.selectedGpuIds.length > 0) {
payload.gpu_ids = config.selectedGpuIds;
+ // Sent only when it is not the legacy default, so a physical pin's payload is
+ // unchanged from before this field.
+ if (gpuIndexKind !== "physical") {
+ payload.gpu_index_kind = gpuIndexKind;
+ }
}
return payload;
}
diff --git a/studio/frontend/src/hooks/use-llama-update-check.ts b/studio/frontend/src/hooks/use-llama-update-check.ts
index 8ae74d5fee3..7d98f503530 100644
--- a/studio/frontend/src/hooks/use-llama-update-check.ts
+++ b/studio/frontend/src/hooks/use-llama-update-check.ts
@@ -48,9 +48,20 @@ export interface LlamaUpdateStatus {
latest_tag: string | null;
// Prebuilt download size in bytes, if known.
update_size_bytes: number | null;
+ // The install recorded "auto" and detection now resolves elsewhere, so Update would move
+ // it. Independent of update_available: reported only when the release is current.
+ backend_migration_available: boolean;
+ from_backend: string | null;
+ to_backend: string | null;
job: LlamaUpdateJob;
}
+/** Whether the banner has anything to offer: a newer release, or a backend the
+ * install's own recorded "auto" would resolve to today. */
+export function llamaUpdateOffered(status: LlamaUpdateStatus): boolean {
+ return status.update_available || status.backend_migration_available;
+}
+
function parseJob(value: unknown): LlamaUpdateJob {
const job = (value ?? {}) as Record<string, unknown>;
return {
@@ -105,6 +116,11 @@ function parseStatus(value: unknown): LlamaUpdateStatus | null {
typeof details.update_size_bytes === "number"
? details.update_size_bytes
: null,
+ // Always from the top level: the backend belongs to the llama.cpp install whatever
+ // component the version fields describe.
+ backend_migration_available: s.backend_migration_available === true,
+ from_backend: typeof s.from_backend === "string" ? s.from_backend : null,
+ to_backend: typeof s.to_backend === "string" ? s.to_backend : null,
job: parseJob(s.job),
};
}
@@ -168,6 +184,9 @@ export interface LlamaApplyResult {
tag?: string | null;
reloadRequired?: boolean | null;
error?: string | null;
+ // What the job says it did: a migration can finish at the release and on the backend it
+ // started from, so "updated to <tag>" fits neither.
+ message?: string;
}
/** Tracks llama.cpp update visibility and apply progress. */
@@ -233,7 +252,7 @@ export function useLlamaUpdateCheck({
const s = await fetchStatus();
if (!s) return;
setStatus(s);
- const presentation = llamaUpdatePresentation(s.update_available, s.job);
+ const presentation = llamaUpdatePresentation(llamaUpdateOffered(s), s.job);
setApplying(presentation.applying);
setVisible(presentation.visible);
if (presentation.running) return;
@@ -250,6 +269,7 @@ export function useLlamaUpdateCheck({
ok: true,
tag: s.job.to_tag,
reloadRequired: s.job.reload_required,
+ message: s.job.message,
});
} else if (s.job.state === "error") {
// Keep the banner visible so retry is available. A partial chained
@@ -269,7 +289,7 @@ export function useLlamaUpdateCheck({
if (!next) return;
setStatus(next);
const presentation = llamaUpdatePresentation(
- next.update_available,
+ llamaUpdateOffered(next),
next.job,
);
setApplying(presentation.applying);
diff --git a/studio/frontend/src/lib/llama-job-lifecycle.ts b/studio/frontend/src/lib/llama-job-lifecycle.ts
index 894eff89400..365ea45a129 100644
--- a/studio/frontend/src/lib/llama-job-lifecycle.ts
+++ b/studio/frontend/src/lib/llama-job-lifecycle.ts
@@ -67,3 +67,51 @@ export function llamaUpdatePresentation(
running: true,
};
}
+
+/**
+ * Whether the banner's version line has anything to say.
+ *
+ * `updateAvailable` is the only field reporting that the release moved. The tags cannot:
+ * `installed_tag` is normalized (`b9596`) while `latest_tag` is the full identity
+ * (`b9596-mix-<sha>`), so a fork install shows them differing at the release it is
+ * running -- which is exactly where a migration is offered.
+ */
+export function llamaReleaseChanged(
+ updateAvailable: boolean,
+ installedTag: string | null,
+ latestTag: string | null,
+): boolean {
+ return Boolean(
+ updateAvailable && installedTag && latestTag && installedTag !== latestTag,
+ );
+}
+
+/** What to tell the user a finished Update actually did.
+ *
+ * A migration runs at the release already installed and can end on the backend already
+ * installed, so "updated to <tag>" describes neither -- and the tag is llama's even when
+ * a pending whisper update named the toast. The job's own message is accurate.
+ */
+export function llamaUpdateToastMessage({
+ component,
+ migrating,
+ jobMessage,
+ updatedTag,
+ reloadRequired,
+}: {
+ component: string;
+ migrating: boolean;
+ jobMessage: string | null | undefined;
+ updatedTag: string;
+ reloadRequired: boolean | null | undefined;
+}): string {
+ const reloadHint = reloadRequired ? " Reload your model to use it." : "";
+ const migrationMessage = migrating ? (jobMessage ?? "").trim() : "";
+ if (!migrationMessage) {
+ return `${component} updated to ${updatedTag}.${reloadHint}`;
+ }
+ // The phase appends its own reload hint when it has one to give.
+ return migrationMessage.includes("Reload")
+ ? migrationMessage
+ : `${migrationMessage}${reloadHint}`;
+}
diff --git a/studio/frontend/tests/llama-extra-args-override-lookup.test.ts b/studio/frontend/tests/llama-extra-args-override-lookup.test.ts
index f5356522fd9..8a61566536e 100644
--- a/studio/frontend/tests/llama-extra-args-override-lookup.test.ts
+++ b/studio/frontend/tests/llama-extra-args-override-lookup.test.ts
@@ -19,8 +19,12 @@ import { registerStoreStubResolver } from "./helpers/kit.ts";
registerStoreStubResolver();
-const { fromApiOverride, resolveStoredExtraArgs, resolveStoredOverride } =
- await import("../src/features/model-picker/api/model-overrides.ts");
+const {
+ fromApiOverride,
+ resolveStoredExtraArgs,
+ resolveStoredOverride,
+ toApiOverride,
+} = await import("../src/features/model-picker/api/model-overrides.ts");
const ARGS = ["--numa", "distribute"];
@@ -263,6 +267,36 @@ test("a server physical GPU pin replaces a local Vulkan pin", () => {
assert.equal(config.selectedGpuIndexKind, "physical");
});
+test("a server row states which index space its pin is in", () => {
+ // The row carries the namespace now, so a Vulkan ordinal saved on one host is read
+ // back as one rather than being relabelled a physical device id.
+ const vulkan = fromApiOverride({ gpu_ids: [1], gpu_index_kind: "vulkan" });
+ assert.deepEqual(vulkan.selectedGpuIds, [1]);
+ assert.equal(vulkan.selectedGpuIndexKind, "vulkan");
+ // Absent stays physical, or every row written before the field reads back unusable.
+ const legacy = fromApiOverride({ gpu_ids: [1] });
+ assert.equal(legacy.selectedGpuIndexKind, "physical");
+});
+
+test("a pin travels to the server with its index space", () => {
+ const physical = toApiOverride({
+ ...fromApiOverride({}),
+ selectedGpuIds: [1],
+ selectedGpuIndexKind: "physical",
+ });
+ // Byte-identical to what a physical pin sent before the field existed.
+ assert.deepEqual(physical.gpu_ids, [1]);
+ assert.equal("gpu_index_kind" in physical, false);
+
+ const vulkan = toApiOverride({
+ ...fromApiOverride({}),
+ selectedGpuIds: [1],
+ selectedGpuIndexKind: "vulkan",
+ });
+ assert.deepEqual(vulkan.gpu_ids, [1]);
+ assert.equal(vulkan.gpu_index_kind, "vulkan");
+});
+
test("a row that carries less than the local config does not erase the rest", () => {
// The mirror is best-effort: a PUT that never landed, a legacy config migrated
// into this browser, a field the backend normalizer refused. Hydration adopting
diff --git a/studio/frontend/tests/llama-job-lifecycle.test.ts b/studio/frontend/tests/llama-job-lifecycle.test.ts
index 157e094d110..a1f1b8969e6 100644
--- a/studio/frontend/tests/llama-job-lifecycle.test.ts
+++ b/studio/frontend/tests/llama-job-lifecycle.test.ts
@@ -2,10 +2,13 @@
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
import test from "node:test";
import {
+ llamaReleaseChanged,
llamaUpdateAdoptsRunningJob,
llamaUpdatePresentation,
+ llamaUpdateToastMessage,
ownedLlamaSwitchOutcome,
} from "../src/lib/llama-job-lifecycle.ts";
@@ -103,3 +106,94 @@ test("an apply adopts an already-running update but never a switch", () => {
false,
);
});
+
+test("a backend migration at the installed release reports no version change", () => {
+ // What a fork install at the current release sends: the display tag is normalized and
+ // the latest tag is the full identity, so they differ while naming one release.
+ assert.equal(
+ llamaReleaseChanged(false, "b9596", "b9596-mix-4b653db"),
+ false,
+ );
+ assert.equal(
+ llamaReleaseChanged(true, "b9596", "b10715-mix-86bd2d3"),
+ true,
+ );
+});
+
+test("a release change still needs both tags to name it", () => {
+ assert.equal(llamaReleaseChanged(true, null, "b10715-mix-86bd2d3"), false);
+ assert.equal(llamaReleaseChanged(true, "b9596", null), false);
+ assert.equal(llamaReleaseChanged(true, "b9596", "b9596"), false);
+});
+
+test("the banner asks the helper rather than comparing the two tags itself", () => {
+ const banner = readFileSync(
+ new URL("../src/components/llama-update-banner.tsx", import.meta.url),
+ "utf8",
+ );
+ assert.match(banner, /const versionChanged = llamaReleaseChanged\(/);
+ assert.doesNotMatch(banner, /installedTag !== latestTag/);
+});
+
+test("a backend migration is reported by what the job did, not by the version fields", () => {
+ // The migration runs at the release already installed, so composing the toast from the
+ // tags announces an update that did not happen.
+ assert.equal(
+ llamaUpdateToastMessage({
+ component: "whisper.cpp",
+ migrating: true,
+ jobMessage: "llama.cpp is now running on vulkan.",
+ updatedTag: "b9596-mix-abc",
+ reloadRequired: false,
+ }),
+ "llama.cpp is now running on vulkan.",
+ );
+
+ assert.equal(
+ llamaUpdateToastMessage({
+ component: "llama.cpp",
+ migrating: true,
+ jobMessage:
+ "llama.cpp could not be moved to vulkan right now, so the existing rocm build was kept. Try again later.",
+ updatedTag: "b9596-mix-abc",
+ reloadRequired: false,
+ }),
+ "llama.cpp could not be moved to vulkan right now, so the existing rocm build was kept. Try again later.",
+ );
+
+ assert.equal(
+ llamaUpdateToastMessage({
+ component: "llama.cpp",
+ migrating: true,
+ jobMessage: "llama.cpp is now running on vulkan.",
+ updatedTag: "b9596-mix-abc",
+ reloadRequired: true,
+ }),
+ "llama.cpp is now running on vulkan. Reload your model to use it.",
+ );
+});
+
+test("an ordinary update still reports the release it moved to", () => {
+ // Control: always deferring to the job would drop the tag from every real update, and
+ // a migration with nothing to say would print blank.
+ assert.equal(
+ llamaUpdateToastMessage({
+ component: "llama.cpp",
+ migrating: false,
+ jobMessage: "llama.cpp is now running on vulkan.",
+ updatedTag: "b9600-mix-def",
+ reloadRequired: true,
+ }),
+ "llama.cpp updated to b9600-mix-def. Reload your model to use it.",
+ );
+ assert.equal(
+ llamaUpdateToastMessage({
+ component: "llama.cpp",
+ migrating: true,
+ jobMessage: " ",
+ updatedTag: "b9600-mix-def",
+ reloadRequired: false,
+ }),
+ "llama.cpp updated to b9600-mix-def.",
+ );
+});
diff --git a/studio/frontend/tests/server-tuning-upgrade-downgrade-compat.test.ts b/studio/frontend/tests/server-tuning-upgrade-downgrade-compat.test.ts
index 3a09a5252ac..a97efdf2606 100644
--- a/studio/frontend/tests/server-tuning-upgrade-downgrade-compat.test.ts
+++ b/studio/frontend/tests/server-tuning-upgrade-downgrade-compat.test.ts
@@ -545,8 +545,8 @@ test("an empty server argument list clears a local list rather than being ignore
test("an empty server GPU list does not clear a local pin", () => {
// Deliberate, and worth pinning next to the tombstone above so the two are not
- // "fixed" into agreement: only a PHYSICAL pin travels, so a row without ids says
- // nothing about placement and a Vulkan ordinal keeps its own namespace.
+ // "fixed" into agreement: a row without ids says nothing about placement, so the
+ // local pin keeps both its ids and its namespace.
const local = fromApiOverride({});
local.selectedGpuIds = [1];
local.selectedGpuIndexKind = "vulkan";
@@ -555,9 +555,16 @@ test("an empty server GPU list does not clear a local pin", () => {
const hydrated = fromApiOverride({ gpu_ids: [] }, local);
assert.deepEqual(hydrated.selectedGpuIds, [1]);
assert.equal(hydrated.selectedGpuIndexKind, "vulkan");
- // And toApiOverride is why: a Vulkan pin is never sent, so a row that lacks ids is
- // exactly what a browser holding one produces.
- assert.equal(toApiOverride(local).gpu_ids, undefined);
+ // The pin travels with its namespace, so a Vulkan ordinal is never silently reread as
+ // a physical index on the other side.
+ const sent = toApiOverride(local);
+ assert.deepEqual(sent.gpu_ids, [1]);
+ assert.equal(sent.gpu_index_kind, "vulkan");
+ // A physical pin's payload is unchanged: the field is omitted at the legacy default.
+ assert.equal(
+ toApiOverride({ ...local, selectedGpuIndexKind: "physical" }).gpu_index_kind,
+ undefined,
+ );
});
// The identity table the panel's hydration now depends on, mirrored from
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 6850ed00a85..457344ce5e6 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -42,7 +42,7 @@ try:
except ImportError:
FileLock = None
FileLockTimeout = None
-from pathlib import Path
+from pathlib import Path, PurePath
from typing import Any, Callable, Iterable, Iterator, Union
# Shared component-agnostic machinery lives in prebuilt_core (same directory);
@@ -106,6 +106,10 @@ WINDOWS_HIP_PREBUILT_GFX_TARGETS = frozenset(
# Family labels forwarded by update markers / --rocm-gfx (gfx110X.zip assets).
WINDOWS_ROCM_FAMILY_GFX_LABELS = frozenset({"gfx103x", "gfx110x", "gfx120x"})
+# HIP builds these, but Vulkan measurably wins (gfx1151 prefill +22.9%, decode +8.3%) and
+# cannot reach the managed-memory faults. An allowlist because CDNA ships no Vulkan ICD.
+VULKAN_PREFERRED_GFX_TARGETS = frozenset({"gfx1150", "gfx1151"})
+
# APUs that lead HIP enumeration and shadow a discrete card (#7776). Mirrors
# install_python_stack.py / setup.ps1 (TestShadowingIntegratedGfxParity keeps them in step);
# duplicated rather than imported because this module is vendored standalone into the backend.
@@ -7620,6 +7624,13 @@ def _hip_visible_device_mask_set() -> bool:
)
+def _vulkan_visible_device_mask_set() -> bool:
+ """Whether GGML_VK_VISIBLE_DEVICES is set, which can leave the Vulkan bundle with
+ nothing to enumerate. Presence is the whole test, as for the HIP masks: the ordinals
+ are Vulkan's own, so which device an index names is unknowable here."""
+ return os.environ.get("GGML_VK_VISIBLE_DEVICES") is not None
+
+
def _windows_hip_gfx_targets(published_repo: str | None) -> frozenset[str]:
"""gfx targets the Windows HIP bundle of ``published_repo`` is actually built for.
@@ -7691,6 +7702,226 @@ def _should_auto_vulkan_for_amd_windows(host: HostInfo, published_repo: str | No
return not any(_gfx_is_windows_hip_supported(target, published_repo) for target in targets)
+# 64-bit only: WOW6432Node holds 32-bit registrations windows-x64-vulkan cannot load.
+_VULKAN_ICD_REGISTRY_KEYS = (r"SOFTWARE\Khronos\Vulkan\Drivers",)
+# RADV radeon_icd.x86_64.json, AMDVLK amd_icd64 / amd_pro_icd64 / amdvlk64, Adrenalin
+# amd-vulkan64.json. Matched on the basename ("amd" names directories too) with "-" folded
+# to "_", without which the ordinary Adrenalin host answered False.
+_AMD_VULKAN_ICD_NEEDLES = ("radeon", "radv", "amdvlk", "amd_icd", "amd_pro", "amd_vulkan")
+# The 32-bit halves a 64-bit llama-server cannot load; a host left with only those keeps ROCm.
+_AMD_VULKAN_ICD_32_BIT_NEEDLES = ("i686", "i386")
+
+
+def _vulkan_glob_matches(pattern: str, name: str) -> bool:
+ """The loader's four driver-filter globs, case-insensitively: "s", "s*", "*s", "*s*"."""
+ pattern, name = pattern.lower(), name.lower()
+ starts, ends = pattern.startswith("*"), pattern.endswith("*")
+ core = pattern[1 if starts else 0 : len(pattern) - 1 if ends else len(pattern)]
+ if starts and ends:
+ return core in name
+ if starts:
+ return name.endswith(core)
+ if ends:
+ return name.startswith(core)
+ return name == core
+
+
+def _vulkan_loader_allows(path: str) -> bool:
+ """Whether the loader's own driver filters leave this manifest loadable.
+
+ They apply to every driver the loader knows, a force list included, and match the
+ manifest's basename. A manifest filtered out is registered and never loaded, so
+ counting it hands an integrated host a Vulkan build with no AMD device.
+
+ Disable is read before select precisely so "disable everything, then name one back"
+ works, hence select answering alone when it is set.
+ """
+
+ def _globs(env_name: str) -> list[str]:
+ value = os.environ.get(env_name) or ""
+ return [entry.strip() for entry in value.split(",") if entry.strip()]
+
+ name = PurePath(path).name
+ select = _globs("VK_LOADER_DRIVERS_SELECT")
+ if select:
+ return any(_vulkan_glob_matches(pattern, name) for pattern in select)
+ disable = _globs("VK_LOADER_DRIVERS_DISABLE")
+ return not any(_vulkan_glob_matches(pattern, name) for pattern in disable)
+
+
+# Per call, not at import: Path.home() raises with no USERPROFILE.
+def _vulkan_icd_search_dirs() -> list[Path]:
+ """The icd.d directories the loader would search, in its own order.
+
+ From the XDG variables, since the loader falls back to the defaults only when one is
+ unset: reading the defaults regardless both misses a custom layout's only AMD manifest
+ and counts stale ones the loader would never read.
+ """
+
+ def _paths(var: str, default: str) -> list[Path]:
+ value = os.environ.get(var)
+ raw = value if (value or "").strip() else default
+ return [Path(entry) for entry in raw.split(os.pathsep) if entry.strip()]
+
+ def _home(var: str, default: str) -> list[Path]:
+ value = os.environ.get(var)
+ if (value or "").strip():
+ return [Path(value)]
+ try:
+ return [Path.home() / default]
+ except Exception:
+ return []
+
+ dirs: list[Path] = []
+ # Loader order: XDG_CONFIG_HOME, XDG_CONFIG_DIRS, then XDG_DATA_HOME, XDG_DATA_DIRS.
+ for base in (
+ *_home("XDG_CONFIG_HOME", ".config"),
+ *_paths("XDG_CONFIG_DIRS", "/etc/xdg"),
+ ):
+ dirs.append(base / "vulkan/icd.d")
+ dirs.append(Path("/etc/vulkan/icd.d"))
+ for base in (
+ *_home("XDG_DATA_HOME", ".local/share"),
+ *_paths("XDG_DATA_DIRS", "/usr/local/share" + os.pathsep + "/usr/share"),
+ ):
+ dirs.append(base / "vulkan/icd.d")
+ seen: set[str] = set()
+ unique: list[Path] = []
+ for directory in dirs:
+ key = str(directory)
+ if key not in seen:
+ seen.add(key)
+ unique.append(directory)
+ return unique
+
+
+def _amd_vulkan_icd_manifest_paths() -> list[str]:
+ """Vulkan ICD manifests this host has registered, by loader search order.
+
+ A file list or a registry key, both readable in-process: vulkaninfo is absent on most
+ Windows hosts and libvulkan on a headless ROCm box, the case being tested for.
+ """
+ # Force lists, not hints: on every platform the loader reads only these, and
+ # VK_DRIVER_FILES supersedes VK_ICD_FILENAMES rather than joining it.
+ for env_name in ("VK_DRIVER_FILES", "VK_ICD_FILENAMES"):
+ value = os.environ.get(env_name)
+ if not (value or "").strip():
+ continue
+ forced = []
+ for entry in value.split(os.pathsep):
+ if not entry:
+ continue
+ try:
+ if os.path.isfile(entry):
+ forced.append(entry)
+ except OSError:
+ continue
+ return forced
+ if sys.platform == "win32":
+ try:
+ import winreg
+ except ImportError:
+ return []
+ paths: list[str] = []
+ for key_path in _VULKAN_ICD_REGISTRY_KEYS:
+ try:
+ with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, key_path) as key:
+ for index in range(winreg.QueryInfoKey(key)[1]):
+ try:
+ name, value, kind = winreg.EnumValue(key, index)
+ except OSError:
+ continue
+ # Name is the path, DWORD data the enable flag, 0 loads.
+ if kind != winreg.REG_DWORD or value != 0:
+ continue
+ # And present, or an uninstall's leftover answers for it.
+ try:
+ if not os.path.isfile(name):
+ continue
+ except OSError:
+ continue
+ paths.append(name)
+ except OSError:
+ continue
+ return paths
+ paths = []
+ for directory in _vulkan_icd_search_dirs():
+ try:
+ paths.extend(str(entry) for entry in sorted(directory.glob("*.json")))
+ except OSError:
+ continue
+ return paths
+
+
+def _amd_vulkan_icd_usable(path: str) -> bool:
+ """Whether a manifest still points at a driver library that is there: a leftover JSON
+ is a registration with no device behind it. A bare name is accepted, since the loader
+ resolves it through a search path this cannot see."""
+ try:
+ with open(path, "r", encoding = "utf-8") as handle:
+ manifest = json.load(handle)
+ library = (manifest.get("ICD") or {}).get("library_path")
+ except Exception:
+ return False
+ if not isinstance(library, str) or not library.strip():
+ return False
+ library = library.strip()
+ if not (os.path.isabs(library) or "/" in library or "\\" in library):
+ return True
+ if not os.path.isabs(library):
+ # Relative to the manifest's directory, per the loader's interface document.
+ library = os.path.join(os.path.dirname(path), library)
+ try:
+ return os.path.isfile(library)
+ except OSError:
+ return False
+
+
+def _amd_vulkan_icd_present() -> bool:
+ """Whether an AMD Vulkan driver is installed, so the Vulkan bundle has a device.
+
+ What makes the route safe by construction rather than by allowlist alone: no AMD ICD
+ keeps ROCm rather than silently running on CPU, and it fails towards the status quo.
+ """
+
+ def _is_amd_64_bit(name: str) -> bool:
+ stem = PurePath(name).stem.lower().replace("-", "_")
+ if stem.endswith("32") or any(n in stem for n in _AMD_VULKAN_ICD_32_BIT_NEEDLES):
+ return False
+ return any(needle in stem for needle in _AMD_VULKAN_ICD_NEEDLES)
+
+ try:
+ return any(
+ _is_amd_64_bit(PurePath(path).name)
+ and _vulkan_loader_allows(path)
+ and _amd_vulkan_icd_usable(path)
+ for path in _amd_vulkan_icd_manifest_paths()
+ )
+ except Exception:
+ return False
+
+
+def _should_prefer_vulkan_for_amd_igpu(host: HostInfo) -> bool:
+ """True when every AMD GPU here is an integrated part Vulkan serves better.
+
+ A preference, not a fallback: unlike _should_auto_vulkan_for_amd_windows these archs
+ have a working HIP prebuilt, just slower. Both platforms, the Linux fault being worse.
+ Every guard that fallback applies is applied here for the same reasons, over every
+ PHYSICAL gfx so a masked-off discrete card is not moved.
+ """
+ active = _active_rocm_gfx_target(host)
+ if not active:
+ return False
+ if not (host.has_rocm and not host.has_physical_nvidia):
+ return False
+ if _hip_visible_device_mask_set() or _vulkan_visible_device_mask_set():
+ return False
+ targets = list(dict.fromkeys([*_host_rocm_gfx_targets(host), active]))
+ if not all(target in VULKAN_PREFERRED_GFX_TARGETS for target in targets):
+ return False
+ return _amd_vulkan_icd_present()
+
+
def _has_no_vulkan_prebuilt(host: HostInfo) -> bool:
"""Platforms that ship no Vulkan prebuilt at all, so routing there is pointless.
@@ -7762,6 +7993,8 @@ def _route_to_vulkan_prebuilt(
* ``UNSLOTH_LLAMA_CPP_BACKEND=vulkan`` / ``UNSLOTH_FORCE_VULKAN`` /
``--llama-backend vulkan`` forces Vulkan over the detected CUDA/ROCm backend;
* Windows AMD with no HIP-prebuilt gfx arch auto-falls back to Vulkan (#7357);
+ * an AMD host whose every GPU is an integrated part Vulkan serves better prefers
+ Vulkan over the HIP bundle it could otherwise run;
* an auto-detected Intel GPU with NO physical NVIDIA/ROCm, the purpose of the
has_intel_gpu probe.
Applied by BOTH the install path and the --resolve-prebuilt probe so the "is a prebuilt
@@ -7775,16 +8008,18 @@ def _route_to_vulkan_prebuilt(
# Host-only test, so a forced Vulkan run can still tell this box would have
# routed itself to Vulkan anyway.
amd_no_hip_host = _should_auto_vulkan_for_amd_windows(host, published_repo)
+ amd_igpu_host = _should_prefer_vulkan_for_amd_igpu(host)
# Auto-fall back only when the run named no accelerator: an explicit hip/cpu/cuda is
# the opt-out. "auto" names detection itself, so it keeps both automatic routes.
detecting = explicit_backend in (None, "auto")
auto_no_hip = detecting and amd_no_hip_host
+ auto_igpu = detecting and amd_igpu_host
# No PHYSICAL NVIDIA, not merely no usable one: Vulkan ignores CUDA_VISIBLE_DEVICES, so
# auto-routing a host that hides its NVIDIA card would let it grab the reserved GPU.
auto_intel = (
detecting and host.has_intel_gpu and not host.has_physical_nvidia and not host.has_rocm
)
- if force_cpu or not (forced or auto_intel or auto_no_hip):
+ if force_cpu or not (forced or auto_intel or auto_no_hip or auto_igpu):
return host, published_repo, published_release_tag, None
if host.is_macos:
if forced:
@@ -7808,6 +8043,16 @@ def _route_to_vulkan_prebuilt(
)
host = _vulkan_only_host(host)
persist_backend = "auto"
+ elif auto_igpu:
+ log(
+ "AMD integrated GPU detected "
+ f"({_active_rocm_gfx_target(host) or 'unknown'}); installing the Vulkan "
+ "llama.cpp prebuilt, which is faster on these parts than ROCm"
+ )
+ host = _vulkan_only_host(host)
+ # Automatic, so the marker keeps rocm_gfx, re-selecting ROCm finds its bundle,
+ # and the Vulkan CPU crash recovery stays armed.
+ persist_backend = "auto"
elif forced:
log(
"Vulkan llama.cpp backend requested; installing the Vulkan "
@@ -7817,7 +8062,7 @@ def _route_to_vulkan_prebuilt(
# A host with no HIP-capable AMD GPU routes here anyway, so the bundle is the
# same. Persist it as automatic so pre-#8050 installs (and the --llama-backend
# vulkan every update re-asserts) stay eligible for the CPU crash recovery.
- persist_backend = "auto" if amd_no_hip_host else "vulkan"
+ persist_backend = "auto" if (amd_no_hip_host or amd_igpu_host) else "vulkan"
else:
log("Intel GPU detected; installing the Vulkan llama.cpp prebuilt")
persist_backend = None
@@ -8019,6 +8264,9 @@ class BackendRoute:
published_release_tag: str
persist_llama_backend: str | None
persist_rocm_gfx: str | None
+ # The pre-route host when Vulkan was preferred over a working HIP bundle, so the plan
+ # falls back to it rather than to CPU. None on #7357, where no HIP build fits.
+ rocm_fallback_host: HostInfo | None = None
def route_backend_request(
@@ -8074,7 +8322,93 @@ def route_backend_request(
published_release_tag = release_tag,
persist_llama_backend = persist_llama_backend,
persist_rocm_gfx = persist_rocm_gfx,
+ # Only the integrated-GPU preference turns away from a runnable HIP bundle.
+ rocm_fallback_host = (
+ resolved_host
+ if (
+ resolved_host.has_rocm
+ and not routed_host.has_rocm
+ and _should_prefer_vulkan_for_amd_igpu(resolved_host)
+ )
+ else None
+ ),
+ )
+
+
+def _with_rocm_behind_vulkan(
+ plans: list[InstallReleasePlan],
+ llama_tag: str,
+ rocm_host: HostInfo,
+ published_repo: str,
+ published_release_tag: str,
+) -> list[InstallReleasePlan]:
+ """Put this host's ROCm bundle behind Vulkan and ahead of the generic CPU fallback.
+
+ _vulkan_only_host clears has_rocm, so the selectors read the box as Intel/CPU and end
+ the plan in a CPU attempt: a Vulkan asset that fails validation would then replace a
+ working ROCm install with CPU inference. A named backend request is filtered
+ afterwards, so this cannot smuggle ROCm into an explicit --llama-backend vulkan.
+ """
+ # A source build is slow and a CPU prebuilt is silent, so fail towards the visible one.
+ _NO_GPU_BUNDLE = (
+ "no published release carries a Vulkan or matching ROCm bundle for this host, "
+ "and a CPU prebuilt would replace a working ROCm install"
)
+ cpu_kinds = install_kinds_for_backend("cpu")
+
+ def _without_cpu(plan: InstallReleasePlan) -> InstallReleasePlan | None:
+ """Drop the CPU tail from a plan with no ROCm attempt behind Vulkan: a failed
+ Vulkan install is recoverable, a silent CPU one is "it got slow". A release that
+ published neither bundle is only its CPU fallback, so it drops out whole."""
+ attempts = [attempt for attempt in plan.attempts if attempt.install_kind not in cpu_kinds]
+ if len(attempts) == len(plan.attempts):
+ return plan
+ return dataclasses_replace(plan, attempts = attempts) if attempts else None
+
+ def _drop_cpu_only(candidates: list[InstallReleasePlan]) -> list[InstallReleasePlan]:
+ """Apply _without_cpu across releases, or fail rather than install CPU."""
+ kept = [narrowed for plan in candidates if (narrowed := _without_cpu(plan)) is not None]
+ if candidates and not kept:
+ raise PrebuiltFallback(_NO_GPU_BUNDLE)
+ return kept
+
+ try:
+ _tag, rocm_plans = resolve_simple_install_release_plans(
+ llama_tag, rocm_host, published_repo, published_release_tag
+ )
+ except Exception:
+ # Not a reason to fail the Vulkan install, but a reason to drop the CPU tail.
+ return _drop_cpu_only(plans)
+ rocm_attempts = {plan.release_tag: plan.attempts for plan in rocm_plans}
+ out: list[InstallReleasePlan] = []
+ for plan in plans:
+ present = {attempt.install_kind for attempt in plan.attempts}
+ candidates = rocm_attempts.get(plan.release_tag, [])
+ extra = [
+ attempt
+ for attempt in candidates
+ if attempt.install_kind not in present and attempt.install_kind not in cpu_kinds
+ ]
+ if not extra:
+ # Either the plan already carries this host's ROCm attempt, or none resolved
+ # for this release; only the second is the hazard above.
+ if any(attempt.install_kind in present for attempt in candidates):
+ out.append(plan)
+ else:
+ narrowed = _without_cpu(plan)
+ if narrowed is not None:
+ out.append(narrowed)
+ continue
+ at = next(
+ (i for i, a in enumerate(plan.attempts) if a.install_kind in cpu_kinds),
+ len(plan.attempts),
+ )
+ out.append(
+ dataclasses_replace(plan, attempts = [*plan.attempts[:at], *extra, *plan.attempts[at:]])
+ )
+ if plans and not out:
+ raise PrebuiltFallback(_NO_GPU_BUNDLE)
+ return out
def select_backend_install(
@@ -8103,6 +8437,14 @@ def select_backend_install(
requested_tag, release_plans = resolve_simple_install_release_plans(
llama_tag, route.host, route.published_repo, route.published_release_tag
)
+ if route.rocm_fallback_host is not None:
+ release_plans = _with_rocm_behind_vulkan(
+ release_plans,
+ llama_tag,
+ route.rocm_fallback_host,
+ route.published_repo,
+ route.published_release_tag,
+ )
# macOS publishes one universal Metal bundle, so there is nothing to hold a
# request to; setup.sh says as much for cpu and vulkan there rather than failing.
if route.backend in CONCRETE_BACKENDS and not route.host.is_macos:
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index 3c1a020c33d..4da6ff89569 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -5770,8 +5770,12 @@ if ($LocalLlamaCppLinked) {
try {
$existingMeta = Get-Content -LiteralPath $existingMetaPath -Raw | ConvertFrom-Json
$existingKind = $existingMeta.install_kind
- # ROCm hosts carry windows-rocm or -hip; CPU covers -cpu and -arm64. Inert for now.
- $expectedKinds = if ($HasROCm -or $script:ROCmGfxArch) { @("windows-rocm", "windows-hip") } elseif ($HasNvidiaSmi) { @("windows-cuda") } else { @("windows-cpu", "windows-arm64") }
+ # ROCm hosts carry windows-rocm or -hip; CPU covers -cpu and -arm64.
+ # Inert: the marker records "backend", never "install_kind", so
+ # $existingKind is always null. windows-vulkan is in every branch because
+ # any x64 Windows host can end up there, and repairing this guard without
+ # it would delete a working Vulkan install on every setup run.
+ $expectedKinds = if ($HasROCm -or $script:ROCmGfxArch) { @("windows-rocm", "windows-hip", "windows-vulkan") } elseif ($HasNvidiaSmi) { @("windows-cuda", "windows-vulkan") } else { @("windows-cpu", "windows-arm64", "windows-vulkan") }
if ($existingKind -and ($existingKind -notin $expectedKinds)) {
substep "Removing mismatched llama.cpp install (found '$existingKind', need one of: $($expectedKinds -join ', '))..."
Remove-Item -Recurse -Force -LiteralPath $LlamaCppDir -ErrorAction SilentlyContinue
diff --git a/tests/studio/test_model_picker_contracts.py b/tests/studio/test_model_picker_contracts.py
index d30a77b012d..32804efb62d 100644
--- a/tests/studio/test_model_picker_contracts.py
+++ b/tests/studio/test_model_picker_contracts.py
@@ -2990,7 +2990,9 @@ def test_the_backfill_fills_in_fields_rather_than_skipping_known_keys():
# The merge is the server's, in the write's transaction: a client-side one reopens the race.
db = _read_backend("storage/studio_db.py")
- assert "merged = {**entry_value, **stored}" in db
+ # `incoming` is entry_value minus any coupled group the stored row already states,
+ # so a field-by-field backfill cannot pair one half of a pin with the other's.
+ assert "merged = {**incoming, **stored}" in db
assert "BEGIN IMMEDIATE" in db
@@ -3275,13 +3277,17 @@ def test_detail_settings_defers_a_derived_quant_to_a_fresh_status_read():
assert "onOpenSettings(selectedQuant ?? null, quantIsUserPicked)" in card
-def test_only_a_physical_gpu_pin_is_mirrored_to_the_server():
- """The same integers are Vulkan ordinals under Vulkan and device indices elsewhere,
- and the server override carries no namespace, so a backend change would pin the model
- to a different device with ids that validate."""
+def test_a_gpu_pin_is_mirrored_to_the_server_with_its_index_space():
+ """The same integers are Vulkan ordinals under Vulkan and device indices elsewhere, so
+ a pin mirrored without its namespace would, after a backend change, address a different
+ device with ids that validate. The namespace travels with it and the server drops the
+ pin on a mismatch instead."""
mirror = " ".join(_read("features/model-picker/api/model-overrides.ts").split())
assert 'const gpuIndexKind = config.selectedGpuIndexKind ?? "physical";' in mirror
- assert 'gpuIndexKind === "physical"' in mirror
+ assert "payload.gpu_ids = config.selectedGpuIds;" in mirror
+ # Omitted at the legacy default, so a physical pin's payload is what it always was and
+ # a row written before this field still reads as physical.
+ assert 'if (gpuIndexKind !== "physical") { payload.gpu_index_kind = gpuIndexKind; }' in mirror
def test_a_cached_repo_keeps_the_settings_saved_under_its_old_key():