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.

llama.cpp installer: keep Qualcomm Adreno on the CPU prebuilt unless Vulkan is requested (#14709)

Daniel Han084d397aa327
diff --git a/studio/backend/tests/test_install_resolve_prebuilt.py b/studio/backend/tests/test_install_resolve_prebuilt.py
index 53d014c7670..2726275c77b 100644
--- a/studio/backend/tests/test_install_resolve_prebuilt.py
+++ b/studio/backend/tests/test_install_resolve_prebuilt.py
@@ -2503,7 +2503,11 @@ def test_vulkan_opt_in_routes_windows_arm64_to_vulkan(monkeypatch, env, flag):
assert persist == "vulkan"
-_ADRENO = ("Qualcomm(R) Adreno(TM) X1-85 GPU",)
+# VK_DRIVER_ID_QUALCOMM_PROPRIETARY = 8, VK_DRIVER_ID_ARM_PROPRIETARY = 9, VK_DRIVER_ID_MESA_TURNIP = 18.
+_ADRENO = (ilp._VulkanGpuName("Qualcomm(R) Adreno(TM) X1-85 GPU", 0x5143, 8),)
+_TURNIP = (ilp._VulkanGpuName("Turnip Adreno (TM) 750", 0x5143, 18),)
+_MALI = (ilp._VulkanGpuName("Mali-G720", 0x13B5, 9),)
+_ARM64_GPU = (ilp._VulkanGpuName("Arm64 Vulkan GPU", 0x13B5, 9),)
def _no_vulkan_probe():
@@ -2517,7 +2521,7 @@ def test_windows_arm64_auto_routes_to_vulkan_when_a_gpu_enumerates(
):
monkeypatch.delenv("UNSLOTH_LLAMA_CPP_BACKEND", raising = False)
monkeypatch.delenv("UNSLOTH_FORCE_VULKAN", raising = False)
- monkeypatch.setattr(ilp, "_vulkan_gpu_devices", lambda: _ADRENO)
+ monkeypatch.setattr(ilp, "_vulkan_gpu_devices", lambda: _ARM64_GPU)
routed, repo, tag, persist = ilp._route_to_vulkan_prebuilt(
_windows_arm64_host(has_intel_gpu = has_intel_gpu),
FORK,
@@ -2530,6 +2534,66 @@ def test_windows_arm64_auto_routes_to_vulkan_when_a_gpu_enumerates(
assert (repo, tag, persist) == (FORK, "pin", None)
[email protected]("flag", [None, "auto"])
+def test_windows_arm64_adreno_stays_on_cpu_unless_vulkan_is_requested(monkeypatch, capsys, flag):
+ # ggml-org/llama.cpp#28290: garbage output on Snapdragon X, so Adreno is opt-in only.
+ monkeypatch.delenv("UNSLOTH_LLAMA_CPP_BACKEND", raising = False)
+ monkeypatch.delenv("UNSLOTH_FORCE_VULKAN", raising = False)
+ monkeypatch.setattr(ilp, "_vulkan_gpu_devices", lambda: _ADRENO)
+ host = _windows_arm64_host()
+ routed, repo, tag, persist = ilp._route_to_vulkan_prebuilt(
+ host, FORK, "pin", force_cpu = False, llama_backend = flag
+ )
+ assert routed is host and routed.vulkan_routed is False
+ assert (repo, tag, persist) == (FORK, "pin", None)
+ captured = capsys.readouterr()
+ assert "UNSLOTH_LLAMA_CPP_BACKEND=vulkan" in captured.out + captured.err
+
+
+ "env, flag",
+ [
+ ({"UNSLOTH_LLAMA_CPP_BACKEND": "vulkan"}, None),
+ ({"UNSLOTH_FORCE_VULKAN": "1"}, None),
+ ({}, "vulkan"),
+ ],
+)
+def test_windows_arm64_adreno_takes_vulkan_when_requested(monkeypatch, env, flag):
+ monkeypatch.delenv("UNSLOTH_LLAMA_CPP_BACKEND", raising = False)
+ monkeypatch.delenv("UNSLOTH_FORCE_VULKAN", raising = False)
+ for name, value in env.items():
+ monkeypatch.setenv(name, value)
+ monkeypatch.setattr(ilp, "_vulkan_gpu_devices", lambda: _ADRENO)
+ routed, _repo, _tag, persist = ilp._route_to_vulkan_prebuilt(
+ _windows_arm64_host(), FORK, "pin", force_cpu = False, llama_backend = flag
+ )
+ assert routed.vulkan_routed is True
+ assert persist == "vulkan"
+
+
[email protected]("devices", [_MALI, _TURNIP], ids = ["mali", "turnip"])
+def test_linux_arm64_mesa_and_mali_still_auto_route_to_vulkan(monkeypatch, devices):
+ monkeypatch.delenv("UNSLOTH_LLAMA_CPP_BACKEND", raising = False)
+ monkeypatch.delenv("UNSLOTH_FORCE_VULKAN", raising = False)
+ monkeypatch.delenv("GGML_VK_VISIBLE_DEVICES", raising = False)
+ monkeypatch.setattr(ilp, "_vulkan_gpu_devices", lambda: devices)
+ routed, _repo, _tag, persist = ilp._route_to_vulkan_prebuilt(
+ _cpu_bound_host("Linux", "arm64"), FORK, "pin", force_cpu = False
+ )
+ assert routed.vulkan_routed is True and routed.vulkan_device_required is True
+ assert persist is None
+
+
+def test_the_probe_keeps_each_device_vendor_and_driver(monkeypatch):
+ probe = _probe_result(
+ monkeypatch, [_vk_device("Adreno X1-85"), _vk_device("Mali", vendor = 0x13B5, driver = 9)]
+ )
+ devices = probe()
+ assert devices == ("Adreno X1-85", "Mali")
+ assert [d.vendor for d in devices] == [0x5143, 0x13B5]
+ assert [d.driver for d in devices] == [8, 9]
+
+
@pytest.mark.parametrize("has_intel_gpu", [False, True])
def test_windows_arm64_without_a_vulkan_gpu_keeps_its_cpu_bundle(monkeypatch, has_intel_gpu):
# A stale Intel adapter entry in the registry names no GPU here: only the probe counts.
@@ -2781,7 +2845,7 @@ def _forced_windows_arm64_host():
def test_auto_routed_windows_arm64_picks_arm64_vulkan_then_cpu(monkeypatch):
monkeypatch.delenv("UNSLOTH_LLAMA_CPP_BACKEND", raising = False)
monkeypatch.delenv("UNSLOTH_FORCE_VULKAN", raising = False)
- monkeypatch.setattr(ilp, "_vulkan_gpu_devices", lambda: _ADRENO)
+ monkeypatch.setattr(ilp, "_vulkan_gpu_devices", lambda: _ARM64_GPU)
routed, _repo, _tag, _persist = ilp._route_to_vulkan_prebuilt(
_windows_arm64_host(), FORK, "", force_cpu = False
)
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 6cc2575a2ef..8d8c9ffea32 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -10530,6 +10530,27 @@ print(json.dumps(devices))
"""
# VK_DRIVER_ID_GOOGLE_SWIFTSHADER, _MESA_LLVMPIPE (software), _MESA_DOZEN (Vulkan over D3D12).
_VULKAN_SKIPPED_DRIVER_IDS = frozenset({10, 13, 23})
+# VK_DRIVER_ID_QUALCOMM_PROPRIETARY (Snapdragon X, Windows): garbage output (ggml-org/llama.cpp#28290), so
+# explicit Vulkan requests only until verified there. Mesa Turnip on Adreno is a different driver.
+_VULKAN_AUTO_OPT_IN_DRIVER_IDS = frozenset({8})
+
+
+class _VulkanGpuName(str):
+ """A Vulkan device name that also carries its vendor and driver ids (None when unknown)."""
+
+ vendor = None
+ driver = None
+
+ def __new__(
+ cls,
+ name,
+ vendor = None,
+ driver = None,
+ ):
+ self = super().__new__(cls, name)
+ self.vendor = vendor
+ self.driver = driver
+ return self
@functools.lru_cache(maxsize = 1)
@@ -10568,12 +10589,29 @@ def _vulkan_gpu_devices() -> tuple[str, ...]:
and device["driver"] not in _VULKAN_SKIPPED_DRIVER_IDS
and device["vendor"] not in hidden_vendors
):
- names.append(str(device["name"]))
+ names.append(
+ _VulkanGpuName(str(device["name"]), device["vendor"], device["driver"])
+ )
except (KeyError, TypeError):
continue
return tuple(names)
+def _vulkan_auto_gpu_devices() -> tuple[str, ...]:
+ """The GPUs the automatic route may pick: every accepted one except opt-in-only drivers."""
+ devices = _vulkan_gpu_devices()
+ auto = tuple(
+ d for d in devices if getattr(d, "driver", None) not in _VULKAN_AUTO_OPT_IN_DRIVER_IDS
+ )
+ if devices and not auto:
+ log(
+ f"Vulkan GPU found ({', '.join(dict.fromkeys(devices))}) but llama.cpp's Vulkan backend "
+ "is unverified there, so the CPU llama.cpp prebuilt is used. Set "
+ "UNSLOTH_LLAMA_CPP_BACKEND=vulkan to install the Vulkan prebuilt instead."
+ )
+ return auto
+
+
def _windows_hip_gfx_targets(published_repo: str | None) -> frozenset[str]:
"""gfx targets the Windows HIP bundle of ``published_repo`` is actually built for.
@@ -11155,7 +11193,8 @@ def _route_to_vulkan_prebuilt(
* an auto-detected Intel GPU with NO physical NVIDIA/ROCm, the purpose of the
has_intel_gpu probe;
* any other non-macOS host that would get the CPU bundle, when the Vulkan loader
- enumerates a GPU llama.cpp accepts (Snapdragon X, Linux arm64 GPUs, nouveau).
+ enumerates a GPU llama.cpp accepts (Linux arm64 GPUs, nouveau); Qualcomm's proprietary
+ driver (Snapdragon X) stays behind the explicit request above.
Applied by BOTH the install path and the --resolve-prebuilt probe so the "is a prebuilt
available" answer matches what actually gets installed.
@@ -11194,7 +11233,7 @@ def _route_to_vulkan_prebuilt(
and not host.has_rocm
and not (host.is_x86_64 and host.has_amd_gpu_without_rocm)
and not _vulkan_visible_device_mask_set()
- and bool(_vulkan_gpu_devices())
+ and bool(_vulkan_auto_gpu_devices())
)
if force_cpu or not (forced or auto_intel or auto_no_hip or auto_igpu or auto_device):
return host, published_repo, published_release_tag, None
@@ -11244,7 +11283,7 @@ def _route_to_vulkan_prebuilt(
log("Intel GPU detected; installing the Vulkan llama.cpp prebuilt")
persist_backend = None
else:
- names = ", ".join(dict.fromkeys(_vulkan_gpu_devices()))
+ names = ", ".join(dict.fromkeys(_vulkan_auto_gpu_devices()))
log(
f"Vulkan GPU found ({names}); installing the Vulkan llama.cpp prebuilt, "
"with the CPU bundle as fallback"