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
Docker Studio: keep the base image's CUDA llama.cpp instead of the CPU prebuilt (#10495)
Daniel Han0d5743c4ec3f
diff --git a/docker/Dockerfile.studio b/docker/Dockerfile.studioindex 11e49b8deb6..05570927a1e 100644--- a/docker/Dockerfile.studio+++ b/docker/Dockerfile.studio@@ -79,6 +79,7 @@ RUN apt-get update \# The llama.cpp symlink BEFORE install.sh points Studio's prebuilt dir at the# base's baked bundle so the installer skips a second ~400MB download; the# .unsloth-studio-owned marker satisfies setup.sh's ownership assertion.+# UNSLOTH_LLAMA_KEEP_PREBUILT=1 keeps it: no GPU is visible here, so setup.sh's detection would install the CPU bundle over it.## UNSLOTH_TORCH_INDEX_FAMILY pins the Studio venv's torch index (no nvidia-smi at# build time would land on cpu/cu126). cu128 on both arches, mirroring the base.@@ -105,6 +106,7 @@ RUN set -eux \UNSLOTH_TORCH_INDEX_FAMILY="${TORCH_FAMILY}" \UNSLOTH_ZOO_REF="${UNSLOTH_STUDIO_ZOO_REF}" \UNSLOTH_LLAMA_TAG="${LLAMA_PREBUILT_TAG}" \+ UNSLOTH_LLAMA_KEEP_PREBUILT=1 \UNSLOTH_PYTHON=3.12 \bash install.sh --local \# Fail loud unless the Studio venv torch EXACTLY matches the base (version AND@@ -115,6 +117,15 @@ RUN set -eux \# setup.sh may relink llama-quantize into build/bin; prove it still resolves its# libraries. Content check, not rc: --help exits nonzero but prints usage.&& { "${UNSLOTH_STUDIO_HOME}/llama.cpp/llama-quantize" --help 2>&1 || true; } | grep -q "usage" \+ # The base baked a CUDA llama.cpp; fail the build if install.sh left a CPU-only tree behind.+ && for CUDA_SO in /opt/unsloth/llama.cpp/libggml-cuda.so /opt/unsloth/llama.cpp/build/bin/libggml-cuda.so; do \+ [ -f "$CUDA_SO" ] || { \+ echo "ERROR: $CUDA_SO is missing after install.sh; GGUF inference would silently run on the CPU"; \+ cat /opt/unsloth/llama.cpp/UNSLOTH_PREBUILT_INFO.json || true; \+ exit 1; \+ }; \+ done \+ && echo "OK: Studio kept the base image's CUDA llama.cpp bundle" \&& rm -rf "${UNSLOTH_STUDIO_HOME}/src/.git" \"${UNSLOTH_STUDIO_HOME}/src/studio/frontend/node_modules" \/root/.cache \diff --git a/studio/setup.sh b/studio/setup.shindex 5b054b382c6..a76557472f3 100755--- a/studio/setup.sh+++ b/studio/setup.sh@@ -2570,6 +2570,7 @@ LLAMA_SERVER_BIN="$LLAMA_CPP_DIR/build/bin/llama-server"_NEED_LLAMA_SOURCE_BUILD=false_LLAMA_CPP_DEGRADED=false_LLAMA_CPP_NO_SPACE=false+_LLAMA_KEEP_PREBUILT_ACTIVE=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)"@@ -2660,6 +2661,71 @@ _has_local_llama_server() {[ -x "$1/llama-server" ] || [ -x "$1/build/bin/llama-server" ]}+# 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() {+ local install_dir=$1 requested_tag=$2 repo=$3 release_pin=${4:-}+ case "$(printf '%s' "${UNSLOTH_LLAMA_KEEP_PREBUILT:-}" | awk '{$1=$1; print tolower($0)}')" in+ 1|true|yes|on) ;;+ *) return 1 ;;+ esac+ # An explicitly requested backend must still be installed, or fail loudly, never kept over.+ [ -z "${_explicit_llama_source_backend:-}" ] || return 1+ _has_local_llama_server "$install_dir" || return 1+ [ -f "$install_dir/UNSLOTH_PREBUILT_INFO.json" ] || return 1+ python - "$install_dir/UNSLOTH_PREBUILT_INFO.json" "$requested_tag" "$repo" "$release_pin" <<'PY' 2>/dev/null+import json+import re+import sys+from pathlib import Path++try:+ payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))+except Exception:+ raise SystemExit(1)+if not isinstance(payload, dict):+ raise SystemExit(1)++requested = sys.argv[2].strip()+repo = sys.argv[3].strip()+release_pin = sys.argv[4].strip() if len(sys.argv) > 4 else ""+GPU_TOKENS = ("cuda", "rocm", "hip", "vulkan", "metal")+# Fork bundles record only "platform"; install_llama_prebuilt.py also records "backend". Accept either.+backend = str(payload.get("backend") or "").strip().lower()+platform_kind = str(payload.get("platform") or payload.get("install_kind") or "").strip().lower()+if payload.get("force_cpu") is True:+ raise SystemExit(1)+if backend not in GPU_TOKENS and not any(token in platform_kind for token in GPU_TOKENS):+ raise SystemExit(1)+if repo and str(payload.get("published_repo") or "").strip() != repo:+ raise SystemExit(1)+++def base_build(tag: str) -> str:+ """b10840 out of b10840-mix-d5c17a0, so the marker's normalized "tag" still matches."""+ match = re.match(r"b(\d+)", tag.strip())+ return f"b{match.group(1)}" if match else tag.strip()+++recorded = {str(payload.get(key) or "").strip() for key in ("release_tag", "tag", "upstream_tag")}+recorded.discard("")+if not recorded:+ raise SystemExit(1)+# UNSLOTH_LLAMA_RELEASE_TAG names one published release, so only that exact release_tag can be kept.+if release_pin and str(payload.get("release_tag") or "").strip() != release_pin:+ raise SystemExit(1)+if requested and requested.lower() != "latest":+ if re.fullmatch(r"b\d+", requested):+ # A bare base build pin is satisfied by any mix release cut from that build.+ if requested not in {base_build(t) for t in recorded}:+ raise SystemExit(1)+ elif requested not in recorded:+ # b10840-mix-new and b10840-mix-old share a base build but are different bundles.+ raise SystemExit(1)+raise SystemExit(0)+PY+}+_LOCAL_LLAMA_CPP_LINKED=falseif [ -n "${UNSLOTH_LOCAL_LLAMA_CPP_DIR:-}" ]; thenif [ ! -d "$UNSLOTH_LOCAL_LLAMA_CPP_DIR" ]; then@@ -2767,6 +2833,10 @@ elif [ "$_LLAMA_FORCE_COMPILE" = "1" ]; then_NEED_LLAMA_SOURCE_BUILD=trueelif [ "${_SKIP_PREBUILT_INSTALL:-false}" = true ]; thensubstep "prebuilt install skipped -- falling back to source build"+elif _keep_installed_gpu_prebuilt "$LLAMA_CPP_DIR" "$_REQUESTED_LLAMA_TAG" "$_HELPER_RELEASE_REPO" "${UNSLOTH_LLAMA_RELEASE_TAG:-}"; then+ step "llama.cpp" "keeping the installed GPU prebuilt (UNSLOTH_LLAMA_KEEP_PREBUILT=1)"+ print_installed_llama_prebuilt_release "$LLAMA_CPP_DIR"+ _LLAMA_KEEP_PREBUILT_ACTIVE=trueelsesubstep "installing prebuilt llama.cpp..."if [ -d "$LLAMA_CPP_DIR" ]; then@@ -3499,6 +3569,7 @@ fi # end _SKIP_GGUF_BUILD check# on a full disk: the retry fails the same way and buries the hint.if [ "$_LLAMA_CPP_DEGRADED" = true ] \&& [ "$_LLAMA_CPP_NO_SPACE" != true ] \+ && [ "$_LLAMA_KEEP_PREBUILT_ACTIVE" != true ] \&& [ "$_HOST_SYSTEM" = "Linux" ] \&& { [ "$_HOST_MACHINE" = "aarch64" ] || [ "$_HOST_MACHINE" = "arm64" ]; }; thensubstep "GPU source build unavailable; trying arm64 CPU prebuilt..."diff --git a/tests/studio/install/test_docker_studio_keep_cuda_prebuilt.py b/tests/studio/install/test_docker_studio_keep_cuda_prebuilt.pynew file mode 100644index 00000000000..31fd2a10ca7--- /dev/null+++ b/tests/studio/install/test_docker_studio_keep_cuda_prebuilt.py@@ -0,0 +1,488 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""The Docker Studio layer must keep the base image's CUDA llama.cpp bundle.++docker/Dockerfile.studio symlinks Studio's llama.cpp dir at the base's baked CUDA bundle+and then runs install.sh --local. No GPU is visible during an image build, so setup.sh's+hardware detection resolves the CPU bundle for the host arch and installs it over the CUDA+one: the published unsloth/unsloth:latest carries whiteouts for libggml-cuda.so on BOTH+arm64 and amd64, and its UNSLOTH_PREBUILT_INFO.json reads backend: cpu.++Part one pins that root cause on both arches with the real selector. Part two drives the+fix, setup.sh's _keep_installed_gpu_prebuilt, against real markers on a stubbed aarch64+host with no working nvidia-smi. Part three pins the wiring that turns the knob on.+"""++from __future__ import annotations++import importlib.util+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"+DOCKERFILE_STUDIO = PACKAGE_ROOT / "docker" / "Dockerfile.studio"+MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"++SPEC = importlib.util.spec_from_file_location("studio_install_llama_prebuilt", MODULE_PATH)+assert SPEC is not None and SPEC.loader is not None+INSTALL_LLAMA_PREBUILT = importlib.util.module_from_spec(SPEC)+sys.modules[SPEC.name] = INSTALL_LLAMA_PREBUILT+SPEC.loader.exec_module(INSTALL_LLAMA_PREBUILT)++HostInfo = INSTALL_LLAMA_PREBUILT.HostInfo+PublishedLlamaArtifact = INSTALL_LLAMA_PREBUILT.PublishedLlamaArtifact+PublishedReleaseBundle = INSTALL_LLAMA_PREBUILT.PublishedReleaseBundle+_linux_published_attempts = INSTALL_LLAMA_PREBUILT._linux_published_attempts++RELEASE_TAG = "b10840-mix-d5c17a0"+LLAMA_TAG = "b10840"+FORK = "unslothai/llama.cpp"+++def _usable_bash():+ exe = shutil.which("bash")+ if exe is None:+ return None+ try:+ probe = subprocess.run(+ [exe, "-c", "printf ok"],+ stdout = subprocess.PIPE,+ stderr = subprocess.DEVNULL,+ text = True,+ errors = "replace",+ timeout = 60,+ )+ except (OSError, subprocess.TimeoutExpired):+ return None+ return exe if probe.stdout.strip() == "ok" else None+++BASH = _usable_bash()+requires_bash = pytest.mark.skipif(BASH is None, reason = "a working bash is required")+++# ── part one: why the CUDA bundle is replaced, on both arches ──+++def _host(machine):+ return HostInfo(+ system = "Linux",+ machine = machine,+ is_windows = False,+ is_linux = True,+ is_macos = False,+ is_x86_64 = machine == "x86_64",+ is_arm64 = machine == "aarch64",+ nvidia_smi = None,+ driver_cuda_version = None,+ compute_caps = [],+ visible_cuda_devices = None,+ has_physical_nvidia = False,+ has_usable_nvidia = False,+ )+++def _artifact(asset_name, install_kind, **overrides):+ defaults = dict(+ asset_name = asset_name,+ install_kind = install_kind,+ runtime_line = None,+ coverage_class = None,+ supported_sms = [],+ min_sm = None,+ max_sm = None,+ bundle_profile = None,+ rank = 100,+ )+ defaults.update(overrides)+ return PublishedLlamaArtifact(**defaults)+++def _release(artifacts):+ return PublishedReleaseBundle(+ repo = FORK,+ release_tag = RELEASE_TAG,+ upstream_tag = RELEASE_TAG,+ assets = {a.asset_name: f"https://example.invalid/{a.asset_name}" for a in artifacts},+ artifacts = artifacts,+ )+++# (arch, the CUDA bundle the base image bakes, the CPU bundle detection lands on)+_ARCH_CASES = [+ (+ "aarch64",+ _artifact(+ f"app-{RELEASE_TAG}-linux-arm64-cuda13-portable.tar.gz",+ "linux-arm64-cuda",+ runtime_line = "cuda13",+ coverage_class = "portable",+ bundle_profile = "cuda13-portable",+ supported_sms = ["90", "100", "103", "120", "121"],+ min_sm = 90,+ max_sm = 121,+ rank = 60,+ ),+ _artifact(f"app-{RELEASE_TAG}-linux-arm64-cpu.tar.gz", "linux-arm64"),+ ),+ (+ "x86_64",+ _artifact(+ f"app-{RELEASE_TAG}-linux-x64-cuda12-portable.tar.gz",+ "linux-cuda",+ runtime_line = "cuda12",+ coverage_class = "portable",+ bundle_profile = "cuda12-portable",+ supported_sms = ["70", "75", "80", "86", "89", "90", "100", "103", "120"],+ min_sm = 70,+ max_sm = 120,+ rank = 60,+ ),+ _artifact(f"app-{RELEASE_TAG}-linux-x64-cpu.tar.gz", "linux-cpu"),+ ),+]+++ ("machine", "cuda_artifact", "cpu_artifact"), _ARCH_CASES, ids = ["arm64", "amd64"]+)+def test_a_gpuless_build_host_resolves_the_cpu_bundle(machine, cuda_artifact, cpu_artifact):+ """The defect: with no GPU visible the selector picks CPU even though CUDA is published.++ This is what install.sh --local runs inside the Docker build, and it is why the CUDA+ bundle the base baked is overwritten. amd64 is NOT exempt.+ """+ attempts = _linux_published_attempts(_host(machine), _release([cuda_artifact, cpu_artifact]))+ assert [choice.name for choice in attempts] == [cpu_artifact.asset_name]+ assert [choice.install_kind for choice in attempts] == [cpu_artifact.install_kind]+++# ── part two: the fix, driven out of setup.sh ──++_BASE_IMAGE_MARKER = {+ "upstream_tag": RELEASE_TAG,+ "source_repo": FORK,+ "platform": "linux-arm64-cuda",+ "bundle_profile": "cuda13-portable",+ "runtime_line": "cuda13",+ "coverage_class": "portable",+ "supported_sms": ["90", "100", "103", "120", "121"],+ "tag": LLAMA_TAG,+ "release_tag": RELEASE_TAG,+ "published_repo": FORK,+}++_INSTALLER_CUDA_MARKER = {+ "requested_tag": RELEASE_TAG,+ "tag": LLAMA_TAG,+ "release_tag": RELEASE_TAG,+ "published_repo": FORK,+ "asset": f"app-{RELEASE_TAG}-linux-arm64-cuda13-portable.tar.gz",+ "force_cpu": False,+ "backend": "cuda",+}++_SHIPPED_CPU_MARKER = {+ "requested_tag": RELEASE_TAG,+ "tag": LLAMA_TAG,+ "release_tag": RELEASE_TAG,+ "published_repo": FORK,+ "asset": f"app-{RELEASE_TAG}-linux-arm64-cpu.tar.gz",+ "force_cpu": False,+ "backend": "cpu",+ "supported_sms": [],+}+++OTHER_MIX = "b10840-mix-0000000"+++def _marker(**overrides):+ payload = dict(_BASE_IMAGE_MARKER)+ payload.update(overrides)+ return payload+++_SH_HARNESS = """+set -u+_FN_FILE="$1"+_INSTALL_DIR="$2"+_REQUESTED_TAG="$3"+_REPO="$4"+. "$_FN_FILE"+if _keep_installed_gpu_prebuilt "$_INSTALL_DIR" "$_REQUESTED_TAG" "$_REPO" "${UNSLOTH_LLAMA_RELEASE_TAG:-}"; then+ printf 'KEEP'+else+ printf 'REPLACE'+fi+"""+++def _sliced_sh_functions(tmp_path):+ """_has_local_llama_server + _keep_installed_gpu_prebuilt, sliced out of setup.sh.++ setup.sh runs install steps at load, so the functions are sliced rather than sourced.+ """+ text = SETUP_SH.read_text(encoding = "utf-8")+ body = ""+ for name in ("_has_local_llama_server() {", "_keep_installed_gpu_prebuilt() {"):+ start = text.index(name)+ end = text.index("\n}\n", start) + len("\n}\n")+ body += text[start:end] + "\n"+ assert "UNSLOTH_LLAMA_KEEP_PREBUILT" in body, "sliced the wrong block out of setup.sh"+ assert body.count("<<'PY'") == 1, "expected exactly one heredoc in the sliced block"+ path = tmp_path / "keep_prebuilt_fn.sh"+ path.write_text(body, encoding = "utf-8")+ return path+++def _stub_bin(tmp_path):+ """A GPU-less aarch64 build host: uname says aarch64 and nvidia-smi cannot answer."""+ stub_dir = tmp_path / "stubbin"+ stub_dir.mkdir(exist_ok = True)+ python_shim = stub_dir / "python"+ python_shim.write_text(f'#!/bin/sh\nexec "{sys.executable}" "$@"\n', encoding = "utf-8")+ (stub_dir / "uname").write_text(+ '#!/bin/sh\nif [ "$1" = "-m" ]; then echo aarch64; else echo Linux; fi\n',+ encoding = "utf-8",+ )+ (stub_dir / "nvidia-smi").write_text(+ '#!/bin/sh\necho "NVIDIA-SMI has failed because no NVIDIA driver is running." >&2\n'+ "exit 9\n",+ encoding = "utf-8",+ )+ for entry in stub_dir.iterdir():+ entry.chmod(0o755)+ return stub_dir+++def _run_keep_decision(+ tmp_path,+ *,+ marker,+ server,+ requested_tag,+ repo = FORK,+ env = None,+):+ install_dir = tmp_path / "llama.cpp"+ (install_dir / "build" / "bin").mkdir(parents = True, exist_ok = True)+ if marker is not None:+ (install_dir / "UNSLOTH_PREBUILT_INFO.json").write_text(+ json.dumps(marker), encoding = "utf-8"+ )+ if server:+ for path in (install_dir / "llama-server", install_dir / "build" / "bin" / "llama-server"):+ path.write_text("#!/bin/sh\nexit 0\n", encoding = "utf-8")+ path.chmod(0o755)+ script = tmp_path / "drive.sh"+ script.write_text(_SH_HARNESS, encoding = "utf-8")+ stub_dir = _stub_bin(tmp_path)+ run_env = dict(os.environ)+ run_env.pop("UNSLOTH_LLAMA_KEEP_PREBUILT", None)+ run_env.pop("UNSLOTH_LLAMA_RELEASE_TAG", None)+ run_env["PATH"] = f"{stub_dir}{os.pathsep}{run_env.get('PATH', '')}"+ run_env.update(env or {})+ proc = subprocess.run(+ [+ BASH,+ str(script),+ str(_sliced_sh_functions(tmp_path)),+ str(install_dir),+ requested_tag,+ repo,+ ],+ stdout = subprocess.PIPE,+ stderr = subprocess.PIPE,+ text = True,+ encoding = "utf-8",+ errors = "replace",+ env = run_env,+ timeout = 120,+ )+ assert proc.returncode == 0, proc.stderr+ return proc.stdout+++ON = {"UNSLOTH_LLAMA_KEEP_PREBUILT": "1"}++# (id, marker, llama-server present, requested tag, extra env, expected verdict)+_KEEP_CASES = [+ ("base_image_cuda_marker_pinned_tag", _BASE_IMAGE_MARKER, True, RELEASE_TAG, ON, "KEEP"),+ ("base_image_cuda_marker_base_build", _BASE_IMAGE_MARKER, True, LLAMA_TAG, ON, "KEEP"),+ ("base_image_cuda_marker_latest", _BASE_IMAGE_MARKER, True, "latest", ON, "KEEP"),+ ("installer_written_cuda_marker", _INSTALLER_CUDA_MARKER, True, RELEASE_TAG, ON, "KEEP"),+ (+ "knob_true",+ _BASE_IMAGE_MARKER,+ True,+ RELEASE_TAG,+ {"UNSLOTH_LLAMA_KEEP_PREBUILT": "true"},+ "KEEP",+ ),+ ("rocm_bundle", _marker(platform = "linux-rocm"), True, RELEASE_TAG, ON, "KEEP"),+ # a full mix pin names one bundle: only that exact mix may be kept+ ("full_mix_pin_exact_match", _BASE_IMAGE_MARKER, True, RELEASE_TAG, ON, "KEEP"),+ ("full_mix_pin_other_mix_same_base", _BASE_IMAGE_MARKER, True, OTHER_MIX, ON, "REPLACE"),+ (+ "full_mix_pin_marker_holds_other_mix",+ _marker(release_tag = OTHER_MIX, upstream_tag = OTHER_MIX),+ True,+ RELEASE_TAG,+ ON,+ "REPLACE",+ ),+ # a bare base build pin still accepts any mix cut from that build+ (+ "bare_base_pin_accepts_any_mix",+ _marker(release_tag = OTHER_MIX, upstream_tag = OTHER_MIX),+ True,+ LLAMA_TAG,+ ON,+ "KEEP",+ ),+ # UNSLOTH_LLAMA_RELEASE_TAG is checked against the marker's release_tag on its own+ (+ "release_tag_pin_match",+ _BASE_IMAGE_MARKER,+ True,+ LLAMA_TAG,+ {**ON, "UNSLOTH_LLAMA_RELEASE_TAG": RELEASE_TAG},+ "KEEP",+ ),+ (+ "release_tag_pin_mismatch",+ _BASE_IMAGE_MARKER,+ True,+ LLAMA_TAG,+ {**ON, "UNSLOTH_LLAMA_RELEASE_TAG": OTHER_MIX},+ "REPLACE",+ ),+ (+ "release_tag_pin_but_marker_records_none",+ _marker(release_tag = None),+ True,+ LLAMA_TAG,+ {**ON, "UNSLOTH_LLAMA_RELEASE_TAG": RELEASE_TAG},+ "REPLACE",+ ),+ # the shipped defect: a CPU bundle must still be replaced+ ("shipped_cpu_marker", _SHIPPED_CPU_MARKER, True, RELEASE_TAG, ON, "REPLACE"),+ (+ "cpu_platform_no_backend_key",+ _marker(platform = "linux-arm64"),+ True,+ RELEASE_TAG,+ ON,+ "REPLACE",+ ),+ ("deliberate_force_cpu", _marker(force_cpu = True), True, RELEASE_TAG, ON, "REPLACE"),+ # stale trees must still be replaced+ (+ "stale_release_tag",+ _marker(tag = "b10700", release_tag = "b10700-mix-aaaaaaa", upstream_tag = "b10700-mix-aaaaaaa"),+ True,+ RELEASE_TAG,+ ON,+ "REPLACE",+ ),+ (+ "other_fork",+ _marker(published_repo = "someone-else/llama.cpp"),+ True,+ RELEASE_TAG,+ ON,+ "REPLACE",+ ),+ ("no_marker_at_all", None, True, RELEASE_TAG, ON, "REPLACE"),+ ("marker_is_not_json", "not json", True, RELEASE_TAG, ON, "REPLACE"),+ ("no_llama_server_binary", _BASE_IMAGE_MARKER, False, RELEASE_TAG, ON, "REPLACE"),+ # the knob is opt-in, and an explicit backend request still wins+ ("knob_unset", _BASE_IMAGE_MARKER, True, RELEASE_TAG, {}, "REPLACE"),+ (+ "knob_zero",+ _BASE_IMAGE_MARKER,+ True,+ RELEASE_TAG,+ {"UNSLOTH_LLAMA_KEEP_PREBUILT": "0"},+ "REPLACE",+ ),+ (+ "explicit_backend_request",+ _BASE_IMAGE_MARKER,+ True,+ RELEASE_TAG,+ {**ON, "_explicit_llama_source_backend": "vulkan"},+ "REPLACE",+ ),+]+++@requires_bash+ ("marker", "server", "requested_tag", "env", "expected"),+ [case[1:] for case in _KEEP_CASES],+ ids = [case[0] for case in _KEEP_CASES],+)+def test_keep_decision(tmp_path, marker, server, requested_tag, env, expected):+ if marker == "not json":+ install_dir = tmp_path / "llama.cpp"+ install_dir.mkdir(parents = True, exist_ok = True)+ (install_dir / "UNSLOTH_PREBUILT_INFO.json").write_text("{ broken", encoding = "utf-8")+ marker = None+ verdict = _run_keep_decision(+ tmp_path, marker = marker, server = server, requested_tag = requested_tag, env = env+ )+ assert verdict == expected+++# ── part three: the wiring that turns the knob on ──+++def test_setup_sh_keeps_the_bundle_instead_of_installing_a_prebuilt():+ text = SETUP_SH.read_text(encoding = "utf-8")+ skip = text.index('elif [ "${_SKIP_PREBUILT_INSTALL:-false}" = true ]; then')+ keep = text.index('elif _keep_installed_gpu_prebuilt "$LLAMA_CPP_DIR"')+ install = text.index(' substep "installing prebuilt llama.cpp..."')+ assert skip < keep < install, (+ "the keep branch must sit after the local-dir / force-compile / PR branches "+ "and before the prebuilt install, or it would hijack an explicit request"+ )+ assert "_LLAMA_KEEP_PREBUILT_ACTIVE=true" in text+ call = text[keep : text.index("\n", keep)]+ assert "${UNSLOTH_LLAMA_RELEASE_TAG:-}" in call, (+ "an explicit published release pin must reach the keep decision"+ )+++def test_the_arm64_cpu_last_resort_cannot_undo_a_kept_bundle():+ text = SETUP_SH.read_text(encoding = "utf-8")+ start = text.index("# ── arm64 Linux GPU: CPU prebuilt as a last resort ──")+ block = text[start : text.index("_ARM64_CPU_CMD=(", start)]+ assert '[ "$_LLAMA_KEEP_PREBUILT_ACTIVE" != true ]' in block, (+ "the arm64 CPU last resort must not install app-<tag>-linux-arm64-cpu.tar.gz "+ "over a bundle the keep branch deliberately preserved"+ )+++def test_dockerfile_studio_sets_the_knob_and_asserts_the_cuda_backend():+ text = DOCKERFILE_STUDIO.read_text(encoding = "utf-8")+ knob = text.index("UNSLOTH_LLAMA_KEEP_PREBUILT=1 \\")+ install = text.index("bash install.sh --local")+ assert knob < install, "the knob must be in install.sh's environment"+ assert "/opt/unsloth/llama.cpp/libggml-cuda.so" in text+ assert "/opt/unsloth/llama.cpp/build/bin/libggml-cuda.so" in text+ assertion = text.index("/opt/unsloth/llama.cpp/libggml-cuda.so")+ assert install < assertion, "the CUDA backend assertion must run AFTER install.sh"+ assert (+ "exit 1" in text[assertion : assertion + 600]+ ), "a missing CUDA backend library must fail the build, not just print"