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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: keep a working GPU llama.cpp prebuilt over a CPU-only source fallback, and say so in the footer (#10975)
Daniel Han6f6439892829
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.pyindex 0be0ff35d67..a253a43a0fe 100644--- a/studio/install_llama_prebuilt.py+++ b/studio/install_llama_prebuilt.py@@ -8148,6 +8148,40 @@ def _binary_image_runs(return True+def _kept_install_covers_host(marker: "dict[str, Any] | None", host: HostInfo) -> bool:+ """Whether the bundle's recorded GPU coverage still includes this host's GPU.++ A same-vendor card swap or a driver downgrade passes the vendor checks, and `--version`+ runs no kernels, so the recorded supported_sms / mapped_targets / runtime_line are the+ only record of what the bundle was built for. A marker without them (CPU, Vulkan,+ older) cannot tell and passes, as does a host whose driver or SMs are unknown.+ """+ marker = marker or {}+ backend = marker_backend(marker)+ if backend == "cuda":+ line = marker.get("runtime_line")+ if isinstance(line, str) and line.startswith("cuda") and host.driver_cuda_version:+ lines = (+ compatible_windows_runtime_lines(host)+ if host.is_windows+ else compatible_linux_runtime_lines(host)+ )+ if line not in lines:+ return False+ supported = set(normalize_compute_caps(marker.get("supported_sms") or []))+ # Under a mask the visible caps are empty; the physical ones are what the card is.+ host_sms = normalize_compute_caps(host.compute_caps or host.physical_compute_caps or [])+ return not supported or not host_sms or all(sm in supported for sm in host_sms)+ if backend == "rocm":+ mapped = {+ str(t).strip().lower() for t in marker.get("mapped_targets") or [] if str(t).strip()+ }+ gfx = (host.rocm_gfx_target or "").strip().lower()+ family = str(marker.get("gfx_target") or "").strip().lower()+ return not mapped or not gfx or gfx in mapped or gfx == family+ return True++def _existing_install_runs(install_dir: Path, host: HostInfo) -> bool:"""Check whether the setup scripts could reuse and run this install."""if not _install_tree_is_usable(install_dir, host):@@ -10194,6 +10228,14 @@ def parse_args() -> argparse.Namespace:"runs the check."),)+ resolve_group.add_argument(+ "--check-installed",+ metavar = "DIR",+ help = (+ "Exit 0 when the install at DIR is complete and its binaries load (the same "+ "network-free check the updater uses before keeping an install), else 2."+ ),+ )parser.add_argument("--install-kind",default = None,@@ -10359,6 +10401,20 @@ def resolve_backends_payload(def main() -> int:args = parse_args()+ if args.check_installed is not None:+ # setup.sh asks before keeping a GPU prebuilt over a CPU source build: no download,+ # since the update that failed usually failed for want of one.+ install_dir = Path(args.check_installed)+ try:+ host = detect_host()+ runs = _existing_install_runs(install_dir, host) and _kept_install_covers_host(+ load_prebuilt_metadata(install_dir), host+ )+ except Exception as exc:+ print(f"install check failed: {exc}", file = sys.stderr)+ runs = False+ return EXIT_SUCCESS if runs else EXIT_FALLBACK+if args.validate_install is not None:try:validate_existing_install(diff --git a/studio/setup.sh b/studio/setup.shindex ad9eb2d538a..87d7e4a0647 100755--- a/studio/setup.sh+++ b/studio/setup.sh@@ -3127,6 +3127,11 @@ _NEED_LLAMA_SOURCE_BUILD=false_LLAMA_CPP_DEGRADED=false_LLAMA_CPP_NO_SPACE=false_LLAMA_KEEP_PREBUILT_ACTIVE=false+# The installed GPU prebuilt was kept because the source fallback could only build CPU.+_LLAMA_KEPT_GPU_PREBUILT=""+_LLAMA_UPDATE_FAIL_REASON=""+# A GPU host ended on a CPU-only llama.cpp: named in the footer, not just mid-log (#9255).+_LLAMA_CPU_ONLY_ON_GPU_HOST=false_LLAMA_FORCE_COMPILE="${UNSLOTH_LLAMA_FORCE_COMPILE:-0}"_REQUESTED_LLAMA_TAG="${UNSLOTH_LLAMA_TAG:-${_DEFAULT_LLAMA_TAG}}"_HOST_SYSTEM="$(uname -s 2>/dev/null || true)"@@ -3217,6 +3222,87 @@ _has_local_llama_server() {[ -x "$1/llama-server" ] || [ -x "$1/build/bin/llama-server" ]}+# The backend the installed prebuilt's marker records (cuda/rocm/vulkan/cpu), or nothing.+# `backend` arrived with #8520; older markers name it in llama_backend or only in the asset.+_installed_prebuilt_backend() {+ [ -f "$1/UNSLOTH_PREBUILT_INFO.json" ] || return 0+ python - "$1/UNSLOTH_PREBUILT_INFO.json" <<'PY' 2>/dev/null || true+import json+import sys++KNOWN = ("cuda", "rocm", "vulkan", "cpu")+try:+ marker = json.load(open(sys.argv[1], encoding="utf-8"))+except Exception:+ marker = {}+if not isinstance(marker, dict):+ marker = {}+def _field(key):+ value = marker.get(key)+ value = value.strip().lower() if isinstance(value, str) else ""+ return "rocm" if value == "hip" else value++# A recorded backend is final, known to this script or not; llama_backend was the request.+answer = _field("backend")+if not answer and _field("llama_backend") in KNOWN:+ answer = _field("llama_backend")+if not answer:+ asset = marker.get("asset")+ asset = asset.lower() if isinstance(asset, str) else ""+ for value in KNOWN:+ if f"-{value}" in asset or (value == "rocm" and "-hip" in asset):+ answer = value+ break+print(answer)+PY+}++# The updater's own completeness check, offline: a marker and an executable do not prove the+# tree loads. Not --validate-install, which downloads a probe model the failed update cannot.+# Why the prebuilt update failed, in a few words, from the helper's log.+_llama_update_fail_reason() {+ if grep -qiE "429|rate limit" "$1" 2>/dev/null; then+ echo "GitHub rate limit"+ elif grep -qiE "timed out|timeout|connection|resol|network|unreachable|50[234]" "$1" 2>/dev/null; then+ echo "network error"+ else+ echo "download failed"+ fi+}++_installed_prebuilt_runs() {+ python "$SCRIPT_DIR/install_llama_prebuilt.py" --check-installed "$1" >/dev/null 2>&1+}++# An Intel GPU by DRM vendor id, the probe the prebuilt router uses for the Vulkan route.+_setup_has_intel_gpu() {+ grep -qs -i "^0x8086" /sys/class/drm/card*/device/vendor 2>/dev/null+}++# A CPU-only source build must not replace a working GPU prebuilt while the GPU is still+# there (#9255). Prints the backend to keep; false when there is nothing to keep, the GPU+# the marker names is gone, or the build was asked for by hand. Vulkan fits any vendor.+_gpu_prebuilt_to_keep_over_cpu_build() {+ local install_dir=$1 backend+ [ "$_LLAMA_FORCE_COMPILE" != "1" ] || return 1+ [ -z "$_LLAMA_PR" ] || return 1+ # An explicit version pin asked for that version, which the old install is not.+ [ -z "${UNSLOTH_LLAMA_RELEASE_TAG:-}" ] || return 1+ case "${UNSLOTH_LLAMA_TAG:-}" in ""|latest|master) ;; *) return 1 ;; esac+ _has_local_llama_server "$install_dir" || return 1+ backend="$(_installed_prebuilt_backend "$install_dir")"+ case "$backend" in+ cuda) [ "$_setup_nvidia_physical" = true ] || return 1 ;;+ rocm) [ "$_setup_amd_detected" = true ] || return 1 ;;+ vulkan)+ [ "$_setup_amd_detected" = true ] || [ "$_setup_nvidia_physical" = true ] \+ || _setup_has_intel_gpu || return 1 ;;+ *) return 1 ;;+ esac+ _installed_prebuilt_runs "$install_dir" || return 1+ printf '%s' "$backend"+}+# UNSLOTH_LLAMA_KEEP_PREBUILT=1: keep an installed GPU prebuilt already matching the requested tag/fork.# The Docker Studio build sets it -- no GPU is visible there, so detection installs a CPU bundle over the baked CUDA one._keep_installed_gpu_prebuilt() {@@ -3516,6 +3602,7 @@ elseelif [ "$_PREBUILT_STATUS" -eq 2 ]; thenstep "llama.cpp" "prebuilt install failed" "$C_WARN"print_llama_error_log "$_PREBUILT_LOG"+ _LLAMA_UPDATE_FAIL_REASON="$(_llama_update_fail_reason "$_PREBUILT_LOG")"rm -f "$_PREBUILT_LOG"if [ -d "$LLAMA_CPP_DIR" ]; thensubstep "prebuilt update failed; existing install restored"@@ -3523,8 +3610,13 @@ else# Exit 2 means no concrete backend was in play: a request the installer# could not honour -- named here or recorded in the install marker, which# this script cannot see -- exits 5 above instead.- substep "falling back to source build"- _NEED_LLAMA_SOURCE_BUILD=true+ # A working GPU prebuilt beats any source build: keep it and retry next time.+ if _LLAMA_KEPT_GPU_PREBUILT="$(_gpu_prebuilt_to_keep_over_cpu_build "$LLAMA_CPP_DIR")"; then+ step "llama.cpp" "update failed ($_LLAMA_UPDATE_FAIL_REASON); keeping the installed $_LLAMA_KEPT_GPU_PREBUILT prebuilt, the next update will retry" "$C_WARN"+ else+ substep "falling back to source build"+ _NEED_LLAMA_SOURCE_BUILD=true+ fielsestep "llama.cpp" "prebuilt helper failed unexpectedly" "$C_ERR"print_llama_error_log "$_PREBUILT_LOG"@@ -3981,7 +4073,14 @@ else_BUILD_DESC="building (CPU)"fi- substep "$_BUILD_DESC..."+ # Decided before the compile: a CPU build adds nothing to a kept GPU prebuilt.+ if [ -z "$GPU_BACKEND" ] && [ "$_IS_MACOS_ARM64" != true ] \+ && _LLAMA_KEPT_GPU_PREBUILT="$(_gpu_prebuilt_to_keep_over_cpu_build "$LLAMA_CPP_DIR")"; then+ step "llama.cpp" "keeping the installed $_LLAMA_KEPT_GPU_PREBUILT prebuilt: the source fallback could only build for the CPU" "$C_WARN"+ BUILD_OK=false+ else+ substep "$_BUILD_DESC..."+ fiNCPU=$(_llama_build_jobs)verbose_substep "parallel jobs: $NCPU (RAM-capped; UNSLOTH_LLAMA_BUILD_JOBS overrides)"@@ -4000,7 +4099,7 @@ elsefi}- if ! run_quiet_no_exit "cmake llama.cpp" cmake $CMAKE_GENERATOR_ARGS -S "$_BUILD_TMP" -B "$_BUILD_TMP/build" $CMAKE_ARGS; then+ if [ "$BUILD_OK" = true ] && ! run_quiet_no_exit "cmake llama.cpp" cmake $CMAKE_GENERATOR_ARGS -S "$_BUILD_TMP" -B "$_BUILD_TMP/build" $CMAKE_ARGS; then_FB_LABEL="$(_gpu_fallback_label)"if [ -n "$_FB_LABEL" ]; then_TRY_METAL_CPU_FALLBACK=false@@ -4085,6 +4184,16 @@ elsefifi+ # A GPU build that fell back to CPU on the way is caught here, after the fact.+ if [ "$BUILD_OK" = true ] && [ -z "$GPU_BACKEND" ] && [ "$_TRY_METAL_CPU_FALLBACK" != true ]; then+ if _LLAMA_KEPT_GPU_PREBUILT="$(_gpu_prebuilt_to_keep_over_cpu_build "$LLAMA_CPP_DIR")"; then+ step "llama.cpp" "keeping the installed $_LLAMA_KEPT_GPU_PREBUILT prebuilt: the source build fell back to the CPU" "$C_WARN"+ BUILD_OK=false+ elif [ "$_setup_nvidia_physical" = true ] || [ "$_setup_amd_detected" = true ] \+ || _setup_has_intel_gpu; then+ _LLAMA_CPU_ONLY_ON_GPU_HOST=true+ fi+ fi# Swap only after build succeeds -- preserves existing install on failureif [ "$BUILD_OK" = true ]; then_assert_studio_owned_or_absent "$LLAMA_CPP_DIR" "llama.cpp install"@@ -4122,6 +4231,9 @@ elseelif [ "$BUILD_OK" = true ]; thenstep "llama.cpp" "binary not found after build" "$C_WARN"_LLAMA_CPP_DEGRADED=true+ elif [ -n "$_LLAMA_KEPT_GPU_PREBUILT" ]; then+ # Not a failure: the kept prebuilt is a root-level llama-server, not $LLAMA_SERVER_BIN.+ print_installed_llama_prebuilt_release "$LLAMA_CPP_DIR"elsestep "llama.cpp" "build failed" "$C_ERR"[ -f "$LLAMA_SERVER_BIN" ] || _LLAMA_CPP_DEGRADED=true@@ -4154,6 +4266,9 @@ if [ "$_LLAMA_CPP_DEGRADED" = true ] \if run_quiet_no_exit "arm64 CPU prebuilt" "${_ARM64_CPU_CMD[@]}"; thenstep "llama.cpp" "arm64 CPU prebuilt installed (GPU build unavailable)" "$C_WARN"_LLAMA_CPP_DEGRADED=false+ if [ "$_setup_nvidia_physical" = true ] || [ "$_setup_amd_detected" = true ]; then+ _LLAMA_CPU_ONLY_ON_GPU_HOST=true+ fiprint_installed_llama_prebuilt_release "$LLAMA_CPP_DIR"fifi@@ -4265,6 +4380,17 @@ PYfifi+# Named in the footer: every path to a lost GPU exits 0, and a mid-log line is what #9255's reporters scrolled past.+_print_llama_gpu_notes() {+ if [ -n "$_LLAMA_KEPT_GPU_PREBUILT" ]; then+ printf " ${C_WARN}%-15s%s${C_RST}\n" "llama.cpp" "update failed (${_LLAMA_UPDATE_FAIL_REASON:-the source fallback could only build for the CPU}); the installed $_LLAMA_KEPT_GPU_PREBUILT prebuilt was kept and the next update will retry"+ fi+ if [ "$_LLAMA_CPU_ONLY_ON_GPU_HOST" = true ]; then+ printf " ${C_WARN}%-15s%s${C_RST}\n" "warning" "GPU acceleration is unavailable: the prebuilt install failed and the source fallback could only build for the CPU (no GPU toolkit, or the GPU build failed above), so GGUF inference will run on the CPU"+ printf " ${C_WARN}%-15s%s${C_RST}\n" "" "fix the cause named above, then re-run this installer to restore the GPU"+ fi+}+# ── Footer ──if [ "$_LLAMA_ONLY" = "1" ]; thenecho ""@@ -4275,6 +4401,7 @@ if [ "$_LLAMA_ONLY" = "1" ]; thenprintf " ${C_TITLE}%s${C_RST}\n" "llama.cpp update finished"fiprintf " ${C_DIM}%s${C_RST}\n" "$RULE"+ _print_llama_gpu_noteselif [ "$IS_COLAB" = true ]; thenecho ""printf " ${C_DIM}%s${C_RST}\n" "$RULE"@@ -4284,6 +4411,7 @@ elif [ "$IS_COLAB" = true ]; thenprintf " ${C_TITLE}%s${C_RST}\n" "Unsloth Studio Setup Complete"fiprintf " ${C_DIM}%s${C_RST}\n" "$RULE"+ _print_llama_gpu_notessubstep "from colab import start"substep "start()"else@@ -4294,6 +4422,7 @@ elseprintf " ${C_TITLE}%s${C_RST}\n" "Unsloth Studio Installed"fiprintf " ${C_DIM}%s${C_RST}\n" "$RULE"+ _print_llama_gpu_notesif [ "$_LLAMA_CPP_DEGRADED" = true ]; thenprintf " ${C_DIM}%-15s${C_WARN}%s${C_RST}\n" "launch" "unsloth studio -p 8888"elsediff --git a/tests/studio/install/test_setup_keeps_gpu_prebuilt_over_cpu_source_fallback.py b/tests/studio/install/test_setup_keeps_gpu_prebuilt_over_cpu_source_fallback.pynew file mode 100644index 00000000000..da10ccb88a4--- /dev/null+++ b/tests/studio/install/test_setup_keeps_gpu_prebuilt_over_cpu_source_fallback.py@@ -0,0 +1,459 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""setup.sh must not replace a working GPU llama.cpp prebuilt with a CPU source build (#9255).++A prebuilt update that fails (network, a GitHub limit, a bad release) restores the existing+install and then source-builds. Without nvcc that build is CPU-only, and the swap replaced+the restored CUDA prebuilt for good while the installer reported "built". Part one drives+the keep decision, sliced out of setup.sh, against real markers. Part two pins the wiring:+the decision runs before the compile and again at the swap, and the footer names the outcome.+"""++from __future__ import annotations++import json+import os+import shutil+import subprocess+import sys+from pathlib import Path++import pytest+++PACKAGE_ROOT = Path(__file__).resolve().parents[3]+SETUP_SH = PACKAGE_ROOT / "studio" / "setup.sh"+SETUP_TEXT = SETUP_SH.read_text(encoding = "utf-8")++BASH = shutil.which("bash")+requires_bash = pytest.mark.skipif(BASH is None, reason = "a working bash is required")++_FUNCTIONS = (+ "_has_local_llama_server() {",+ "_installed_prebuilt_backend() {",+ "_gpu_prebuilt_to_keep_over_cpu_build() {",+)++_HARNESS = """+set -u+. "$1"+# Stubbed: the real ones read this host's /sys/class/drm and start llama-server.+_setup_has_intel_gpu() { [ "${_setup_intel_gpu:-false}" = true ]; }+_installed_prebuilt_runs() { [ "${_setup_prebuilt_runs:-true}" = true ]; }+if _kept="$(_gpu_prebuilt_to_keep_over_cpu_build "$2")"; then+ printf 'KEEP %s' "$_kept"+else+ printf 'REPLACE'+fi+"""+++def _sliced_functions(tmp_path):+ """The three helpers, sliced out: setup.sh runs install steps at load."""+ body = ""+ for name in _FUNCTIONS:+ start = SETUP_TEXT.index(name)+ end = SETUP_TEXT.index("\n}\n", start) + len("\n}\n")+ body += SETUP_TEXT[start:end] + "\n"+ path = tmp_path / "keep_fns.sh"+ path.write_text(body, encoding = "utf-8")+ return path+++def _install(+ tmp_path,+ marker,+ *,+ server = True,+):+ install_dir = tmp_path / "llama.cpp"+ install_dir.mkdir(exist_ok = True)+ if server:+ exe = install_dir / "llama-server"+ exe.write_text("#!/bin/sh\n", encoding = "utf-8")+ exe.chmod(0o755)+ if marker is not None:+ text = marker if isinstance(marker, str) else json.dumps(marker)+ (install_dir / "UNSLOTH_PREBUILT_INFO.json").write_text(text, encoding = "utf-8")+ return install_dir+++def _decide(tmp_path, install_dir, **env):+ stub_bin = tmp_path / "bin"+ stub_bin.mkdir(exist_ok = True)+ shim = stub_bin / "python"+ shim.write_text(f'#!/bin/sh\nexec "{sys.executable}" "$@"\n', encoding = "utf-8")+ shim.chmod(0o755)+ run_env = {+ **os.environ,+ "PATH": f"{stub_bin}{os.pathsep}{os.environ.get('PATH', '')}",+ "_LLAMA_FORCE_COMPILE": "0",+ "_LLAMA_PR": "",+ "_setup_nvidia_physical": "false",+ "_setup_amd_detected": "false",+ }+ run_env.update(env)+ result = subprocess.run(+ [BASH, "-c", _HARNESS, "harness", str(_sliced_functions(tmp_path)), str(install_dir)],+ env = run_env,+ stdout = subprocess.PIPE,+ stderr = subprocess.PIPE,+ text = True,+ timeout = 120,+ )+ assert result.returncode == 0, result.stderr+ return result.stdout+++# ── part one: the keep decision ──+++@requires_bash+class TestTheKeepDecision:+ def test_a_cuda_prebuilt_on_an_nvidia_host_is_kept(self, tmp_path):+ install_dir = _install(tmp_path, {"backend": "cuda"})+ assert _decide(tmp_path, install_dir, _setup_nvidia_physical = "true") == "KEEP cuda"++ @pytest.mark.parametrize("backend", ["rocm", "vulkan"])+ def test_an_amd_prebuilt_on_an_amd_host_is_kept(self, tmp_path, backend):+ install_dir = _install(tmp_path, {"backend": backend})+ assert _decide(tmp_path, install_dir, _setup_amd_detected = "true") == f"KEEP {backend}"++ def test_a_rocm_prebuilt_needs_the_amd_gpu_not_just_any_gpu(self, tmp_path):+ # An AMD-to-NVIDIA swap: the ROCm binary cannot run here, so the CPU build wins.+ install_dir = _install(tmp_path, {"backend": "rocm"})+ assert _decide(tmp_path, install_dir, _setup_nvidia_physical = "true") == "REPLACE"++ def test_a_vulkan_prebuilt_is_kept_for_every_vendor(self, tmp_path):+ # The Intel-only host is the one the Vulkan route exists for.+ install_dir = _install(tmp_path, {"backend": "vulkan"})+ assert _decide(tmp_path, install_dir, _setup_intel_gpu = "true") == "KEEP vulkan"+ assert _decide(tmp_path, install_dir, _setup_nvidia_physical = "true") == "KEEP vulkan"+ assert _decide(tmp_path, install_dir) == "REPLACE"++ def test_the_marker_backend_is_read_case_insensitively(self, tmp_path):+ install_dir = _install(tmp_path, {"backend": " CUDA "})+ assert _decide(tmp_path, install_dir, _setup_nvidia_physical = "true") == "KEEP cuda"++ def test_a_cuda_prebuilt_is_replaced_once_the_gpu_is_gone(self, tmp_path):+ # The GPU the marker names left the machine: a CPU build is the honest install now.+ install_dir = _install(tmp_path, {"backend": "cuda"})+ assert _decide(tmp_path, install_dir) == "REPLACE"+ assert _decide(tmp_path, install_dir, _setup_amd_detected = "true") == "REPLACE"++ def test_an_explicit_version_pin_is_not_satisfied_by_the_old_install(self, tmp_path):+ install_dir = _install(tmp_path, {"backend": "cuda"})+ nvidia = {"_setup_nvidia_physical": "true"}+ assert _decide(tmp_path, install_dir, UNSLOTH_LLAMA_TAG = "b7000", **nvidia) == "REPLACE"+ assert (+ _decide(tmp_path, install_dir, UNSLOTH_LLAMA_RELEASE_TAG = "b7000-mix", **nvidia)+ == "REPLACE"+ )+ assert _decide(tmp_path, install_dir, UNSLOTH_LLAMA_TAG = "latest", **nvidia) == "KEEP cuda"++ def test_a_cpu_prebuilt_is_not_worth_keeping(self, tmp_path):+ install_dir = _install(tmp_path, {"backend": "cpu"})+ assert _decide(tmp_path, install_dir, _setup_nvidia_physical = "true") == "REPLACE"++ @pytest.mark.parametrize(+ "marker",+ [None, "{not json", "[1, 2]", {"asset": "x"}, {"backend": None}, {"backend": 3}],+ ids = ["absent", "malformed", "not-a-dict", "no-backend", "null", "non-string"],+ )+ def test_an_unreadable_marker_does_not_keep(self, tmp_path, marker):+ install_dir = _install(tmp_path, marker)+ assert _decide(tmp_path, install_dir, _setup_nvidia_physical = "true") == "REPLACE"++ @pytest.mark.parametrize(+ ("marker", "backend"),+ [+ (+ {"llama_backend": "vulkan", "asset": "llama-b7001-bin-ubuntu-vulkan-x64.tar.gz"},+ "vulkan",+ ),+ ({"llama_backend": "hip", "asset": "app-b9001-linux-x64-rocm-gfx110X.tar.gz"}, "rocm"),+ ({"asset": "app-b6210-linux-x64-cuda12.tar.gz"}, "cuda"),+ ({"asset": "app-b9001-linux-x64-rocm-gfx110X.tar.gz"}, "rocm"),+ ({"llama_backend": "auto", "asset": "app-b1-linux-x64-cuda13-newer.tar.gz"}, "cuda"),+ ],+ ids = ["llama_backend", "hip-spelling", "asset-cuda", "asset-rocm", "auto-request"],+ )+ def test_a_legacy_marker_names_its_backend_elsewhere(self, tmp_path, marker, backend):+ # Shapes from before #8520 (tests/studio/install/test_keep_install_backcompat_9979.py).+ install_dir = _install(tmp_path, marker)+ both = {"_setup_nvidia_physical": "true", "_setup_amd_detected": "true"}+ assert _decide(tmp_path, install_dir, **both) == f"KEEP {backend}"++ def test_a_legacy_cpu_marker_is_replaced(self, tmp_path):+ install_dir = _install(tmp_path, {"asset": "llama-b6099-bin-ubuntu-x64.tar.gz"})+ assert _decide(tmp_path, install_dir, _setup_nvidia_physical = "true") == "REPLACE"+ install_dir = _install(+ tmp_path, {"backend": "sycl", "asset": "app-b1-linux-x64-cuda12.tar.gz"}+ )+ assert _decide(tmp_path, install_dir, _setup_nvidia_physical = "true") == "REPLACE"++ def test_a_prebuilt_that_no_longer_runs_is_replaced(self, tmp_path):+ # A quarantined library leaves the marker and the executable behind.+ install_dir = _install(tmp_path, {"backend": "cuda"})+ assert (+ _decide(+ tmp_path, install_dir, _setup_nvidia_physical = "true", _setup_prebuilt_runs = "false"+ )+ == "REPLACE"+ )++ def test_a_tree_without_a_server_is_not_worth_keeping(self, tmp_path):+ install_dir = _install(tmp_path, {"backend": "cuda"}, server = False)+ assert _decide(tmp_path, install_dir, _setup_nvidia_physical = "true") == "REPLACE"++ def test_a_build_asked_for_by_hand_still_runs(self, tmp_path):+ install_dir = _install(tmp_path, {"backend": "cuda"})+ nvidia = {"_setup_nvidia_physical": "true"}+ assert _decide(tmp_path, install_dir, _LLAMA_FORCE_COMPILE = "1", **nvidia) == "REPLACE"+ assert _decide(tmp_path, install_dir, _LLAMA_PR = "12345", **nvidia) == "REPLACE"+++# ── part two: the wiring ──+++def _between(start_marker, end_marker):+ start = SETUP_TEXT.index(start_marker)+ return SETUP_TEXT[start : SETUP_TEXT.index(end_marker, start)]+++def test_a_failed_update_keeps_the_gpu_prebuilt_before_any_source_build():+ # The first decision is at the failed update itself: no source build is started.+ window = _between('[ "$_PREBUILT_STATUS" -eq 2 ]', "_NEED_LLAMA_SOURCE_BUILD=true")+ assert (+ '_LLAMA_KEPT_GPU_PREBUILT="$(_gpu_prebuilt_to_keep_over_cpu_build "$LLAMA_CPP_DIR")"'+ in window+ )+ assert "the next update will retry" in window+ # The reason is read before the helper's log is deleted.+ assert window.index('_llama_update_fail_reason "$_PREBUILT_LOG"') < window.index(+ 'rm -f "$_PREBUILT_LOG"'+ )+++@requires_bash+ ("log", "reason"),+ [+ ("HTTP Error 429: Too Many Requests", "GitHub rate limit"),+ ("API rate limit exceeded for 1.2.3.4", "GitHub rate limit"),+ ("urlopen error timed out", "network error"),+ ("Temporary failure in name resolution", "network error"),+ ("HTTP Error 503: Service Unavailable", "network error"),+ ("checksum mismatch for app-b1-linux-x64-cuda12.tar.gz", "download failed"),+ ("", "download failed"),+ ],+)+def test_the_failure_reason_is_a_few_words(tmp_path, log, reason):+ fn = _between("_llama_update_fail_reason() {", "\n}\n") + "\n}\n"+ path = tmp_path / "prebuilt.log"+ path.write_text(log, encoding = "utf-8")+ result = subprocess.run(+ [BASH, "-c", fn + '\n_llama_update_fail_reason "$1"', "reason", str(path)],+ stdout = subprocess.PIPE,+ stderr = subprocess.PIPE,+ text = True,+ timeout = 60,+ )+ assert result.stdout.strip() == reason, result.stderr+++def test_the_decision_runs_before_the_compile():+ # Deciding after a 20 minute compile would be correct and pointless.+ window = _between('_BUILD_DESC="building (CPU)"', 'run_quiet_no_exit "cmake llama.cpp"')+ assert (+ '_LLAMA_KEPT_GPU_PREBUILT="$(_gpu_prebuilt_to_keep_over_cpu_build "$LLAMA_CPP_DIR")"'+ in window+ )+ assert "BUILD_OK=false" in window+ # The configure must honour that verdict: it sat in the same BUILD_OK block.+ assert '[ "$BUILD_OK" = true ] && ! run_quiet_no_exit "cmake llama.cpp"' in SETUP_TEXT+++def test_the_decision_runs_again_at_the_swap():+ # A CUDA build that fell back to CPU on the way only shows at the swap.+ window = _between("caught here, after the fact", "# Swap only after build succeeds")+ assert '[ -z "$GPU_BACKEND" ] && [ "$_TRY_METAL_CPU_FALLBACK" != true ]' in window+ assert '_gpu_prebuilt_to_keep_over_cpu_build "$LLAMA_CPP_DIR"' in window+ assert "_LLAMA_CPU_ONLY_ON_GPU_HOST=true" in window+++def test_the_kept_tree_is_checked_offline_the_way_the_updater_checks_it():+ keep = _between("_gpu_prebuilt_to_keep_over_cpu_build() {", "\n}\n")+ assert '_installed_prebuilt_runs "$install_dir" || return 1' in keep+ runs = _between("_installed_prebuilt_runs() {", "\n}\n")+ # Not --validate-install: that downloads its probe model, and the update just failed+ # for want of a download.+ assert '--check-installed "$1"' in runs and "--validate-install" not in runs+++def _load_ilp():+ import importlib.util++ spec = importlib.util.spec_from_file_location(+ "keep_check_ilp", PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"+ )+ ilp = importlib.util.module_from_spec(spec)+ sys.modules[spec.name] = ilp+ spec.loader.exec_module(ilp)+ return ilp+++def _linux_host(ilp, **fields):+ base = dict(+ system = "Linux",+ machine = "x86_64",+ is_windows = False,+ is_linux = True,+ is_macos = False,+ is_x86_64 = True,+ is_arm64 = False,+ nvidia_smi = None,+ driver_cuda_version = None,+ compute_caps = [],+ visible_cuda_devices = None,+ has_physical_nvidia = False,+ has_usable_nvidia = False,+ )+ base.update(fields)+ return ilp.HostInfo(**base)+++class TestTheKeptBundleMustStillCoverTheCard:+ """A same-vendor card swap passes the vendor check and --version; the marker does not."""++ def test_a_cuda_bundle_is_kept_only_for_the_sms_it_was_built_for(self):+ ilp = _load_ilp()+ marker = {"backend": "cuda", "supported_sms": ["7.5", "8.6", "8.9"]}+ assert ilp._kept_install_covers_host(marker, _linux_host(ilp, compute_caps = ["8.9"]))+ assert not ilp._kept_install_covers_host(marker, _linux_host(ilp, compute_caps = ["12.0"]))+ # Two cards: every one must be covered.+ assert not ilp._kept_install_covers_host(+ marker, _linux_host(ilp, compute_caps = ["8.9", "12.0"])+ )++ def test_a_masked_card_is_checked_by_its_physical_sms(self):+ ilp = _load_ilp()+ marker = {"backend": "cuda", "supported_sms": ["8.9"]}+ masked = _linux_host(ilp, compute_caps = [], physical_compute_caps = ["12.0"])+ assert not ilp._kept_install_covers_host(marker, masked)+ assert ilp._kept_install_covers_host(+ marker, _linux_host(ilp, compute_caps = [], physical_compute_caps = ["8.9"])+ )++ def test_a_cuda_bundle_is_kept_only_while_the_driver_runs_its_runtime(self):+ ilp = _load_ilp()+ marker = {"backend": "cuda", "runtime_line": "cuda13", "supported_sms": ["8.9"]}+ host = lambda v: _linux_host(ilp, compute_caps = ["8.9"], driver_cuda_version = v)+ assert ilp._kept_install_covers_host(marker, host((13, 1)))+ assert not ilp._kept_install_covers_host(marker, host((12, 8)))+ # cuda12 runs on a 13 driver; an unknown driver cannot tell.+ assert ilp._kept_install_covers_host({**marker, "runtime_line": "cuda12"}, host((13, 1)))+ assert ilp._kept_install_covers_host(marker, host(None))++ def test_a_rocm_bundle_is_kept_for_its_mapped_targets_or_family(self):+ ilp = _load_ilp()+ marker = {+ "backend": "rocm",+ "gfx_target": "gfx110X",+ "mapped_targets": ["gfx1100", "gfx1101", "gfx1102"],+ }+ for gfx in ("gfx1100", "GFX1101", "gfx110X"):+ assert ilp._kept_install_covers_host(marker, _linux_host(ilp, rocm_gfx_target = gfx))+ assert not ilp._kept_install_covers_host(+ marker, _linux_host(ilp, rocm_gfx_target = "gfx1201")+ )++ def test_a_marker_without_coverage_cannot_tell_and_passes(self):+ ilp = _load_ilp()+ host = _linux_host(ilp, compute_caps = ["12.0"], rocm_gfx_target = "gfx1201")+ for marker in (+ None,+ {"backend": "cuda"},+ {"backend": "rocm", "mapped_targets": []},+ {"backend": "vulkan"},+ {"llama_backend": "cpu"},+ ):+ assert ilp._kept_install_covers_host(marker, host)+ # An unknown host SM (masked) cannot be checked either.+ assert ilp._kept_install_covers_host(+ {"backend": "cuda", "supported_sms": ["8.9"]}, _linux_host(ilp)+ )++ def test_check_installed_refuses_a_bundle_that_no_longer_covers_the_card(+ self, tmp_path, monkeypatch+ ):+ ilp = _load_ilp()+ monkeypatch.setattr(ilp, "detect_host", lambda **k: _linux_host(ilp, compute_caps = ["12.0"]))+ monkeypatch.setattr(ilp, "_existing_install_runs", lambda d, h: True)+ monkeypatch.setattr(+ ilp,+ "load_prebuilt_metadata",+ lambda d: {"backend": "cuda", "supported_sms": ["8.9"]},+ )+ monkeypatch.setattr(+ sys, "argv", ["install_llama_prebuilt.py", "--check-installed", str(tmp_path)]+ )+ assert ilp.main() == 2+++@requires_bash+def test_check_installed_answers_with_the_updaters_own_check(tmp_path, monkeypatch):+ ilp = _load_ilp()+ seen = {}+ monkeypatch.setattr(ilp, "detect_host", lambda **k: "host")++ def runs(install_dir, host):+ seen["args"] = (install_dir, host)+ return seen["answer"]++ monkeypatch.setattr(ilp, "_existing_install_runs", runs)+ monkeypatch.setattr(+ sys, "argv", ["install_llama_prebuilt.py", "--check-installed", str(tmp_path)]+ )+ seen["answer"] = True+ assert ilp.main() == 0+ assert seen["args"] == (tmp_path, "host")+ seen["answer"] = False+ assert ilp.main() == 2+ # Nothing about a check may download: no fetch helper is reached.+ monkeypatch.setattr(ilp, "download_file", lambda *a, **k: pytest.fail("downloaded"))+ monkeypatch.setattr(+ ilp, "_existing_install_runs", lambda d, h: (_ for _ in ()).throw(OSError("x"))+ )+ assert ilp.main() == 2+++def test_an_intel_host_on_cpu_is_named_too():+ window = _between("caught here, after the fact", "# Swap only after build succeeds")+ assert "_setup_has_intel_gpu" in window+++def test_the_arm64_cpu_prebuilt_fallback_is_named_in_the_footer_too():+ window = _between('step "llama.cpp" "arm64 CPU prebuilt installed', "_STUDIO_OWNED_MARKER")+ assert "_LLAMA_CPU_ONLY_ON_GPU_HOST=true" in window+++def test_a_kept_prebuilt_is_not_reported_as_a_failed_build():+ window = _between(+ 'step "llama.cpp" "binary not found after build"', 'step "llama.cpp" "build failed"'+ )+ assert 'elif [ -n "$_LLAMA_KEPT_GPU_PREBUILT" ]' in window+++def test_every_footer_names_the_outcome():+ assert (+ SETUP_TEXT.count("_print_llama_gpu_notes\n") == 3+ ), "llama-only, Colab and the default footer"+ notes = _between("_print_llama_gpu_notes() {", "\n}\n")+ assert "_LLAMA_KEPT_GPU_PREBUILT" in notes and "_LLAMA_CPU_ONLY_ON_GPU_HOST" in notes+++def test_the_flags_are_initialised_for_set_u():+ assert '_LLAMA_KEPT_GPU_PREBUILT=""' in SETUP_TEXT+ assert "_LLAMA_CPU_ONLY_ON_GPU_HOST=false" in SETUP_TEXT