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: keep an AMD dGPU and a Vulkan choice through install and update (#11442)

Daniel Han6770853221a3
diff --git a/studio/backend/tests/test_llama_backend_selection.py b/studio/backend/tests/test_llama_backend_selection.py
index c6daf28e5f5..330fe1de7bd 100644
--- a/studio/backend/tests/test_llama_backend_selection.py
+++ b/studio/backend/tests/test_llama_backend_selection.py
@@ -208,15 +208,38 @@ def test_an_unknown_environment_value_falls_through_to_the_install(monkeypatch,
("cpu", "linux-cpu", "cpu"),
("auto", "linux-cuda", "auto"),
(None, "linux-cuda", "auto"),
- # macOS cannot persist requests that all resolve to its universal Metal build.
+ # An unhonourable request is KEPT, not erased to "auto" (#11143), so a later update
+ # can retry it.
+ ("vulkan", "linux-cpu", "vulkan"),
+ # Except where no release could ever honour it: macOS ships one universal Metal
+ # bundle and the picker offers only "auto", so a preserved "cpu" is unappliable.
("cpu", "macos-arm64", "auto"),
- ("vulkan", "linux-cpu", "auto"),
+ ("vulkan", "macos-x64", "auto"),
],
)
-def test_only_a_request_the_install_honours_is_recorded(request_backend, kind, expected):
+def test_the_request_is_recorded_verbatim(request_backend, kind, expected):
assert ilp.persisted_marker_backend_request(request_backend, _choice(kind)) == expected
+ "request_backend, kind, satisfied",
+ [
+ ("vulkan", "linux-vulkan", True),
+ ("cpu", "linux-cpu", True),
+ ("auto", "linux-cuda", True),
+ (None, "linux-cuda", True),
+ # A single-build platform cannot owe a request: nothing could ever serve it.
+ ("cpu", "macos-arm64", True),
+ # Concrete requests the bundle that landed contradicts.
+ ("vulkan", "linux-cpu", False),
+ ],
+)
+def test_a_request_the_install_could_not_honour_is_flagged(request_backend, kind, satisfied):
+ """The other half of the pair: the request is preserved, so something has to say it
+ is not what runs, or every reader would treat it as the installed backend."""
+ assert ilp.marker_backend_request_was_satisfied(request_backend, _choice(kind)) is satisfied
+
+
def test_macos_backend_resolver_only_offers_automatic_metal(monkeypatch):
host = ilp.HostInfo(
system = "Darwin",
@@ -571,7 +594,10 @@ def test_a_recorded_choice_this_host_cannot_serve_falls_back_to_detection(monkey
assert seen == ["rocm", "auto"]
marker = json.loads((tmp_path / "UNSLOTH_PREBUILT_INFO.json").read_text())
- assert marker["backend_request"] == "auto"
+ # The CHOICE survives the re-detect, flagged as not what landed. Erasing it to "auto"
+ # here is what made a configured Vulkan install keep coming back as ROCm (#11143).
+ assert marker["backend_request"] == "rocm"
+ assert marker["backend_request_unsatisfied"] is True
def test_a_named_backend_this_host_cannot_serve_fails_instead(monkeypatch, tmp_path):
diff --git a/studio/backend/utils/llama_cpp_update.py b/studio/backend/utils/llama_cpp_update.py
index 1c53958ec26..f6835e79a15 100644
--- a/studio/backend/utils/llama_cpp_update.py
+++ b/studio/backend/utils/llama_cpp_update.py
@@ -518,9 +518,9 @@ def _backend_options(resolved: Optional[dict], assets: Optional[dict] = None) ->
def _selection_applied(
backend_request: str, installed_backend: Optional[str], options: list[dict]
) -> bool:
- """Whether the recorded choice still describes the installed backend. A concrete choice is applied by definition: the installer records it only on an install that honoured it. ``auto`` is the one that drifts (a GPU or driver appearing after an automatic CPU install makes detection resolve elsewhere) and re-applying it is offered exactly then."""
+ """Whether the recorded choice still describes the installed backend. A concrete choice used to be applied by definition, since the installer recorded it only on an install that honoured it; it now PRESERVES a request the install could not honour (#11143: a Vulkan choice that landed the ROCm bundle used to be erased to "auto", which destroyed the setting and made every later update re-detect), so a concrete choice is applied only when it is the backend that actually landed. Unknown installed backend contradicts nothing and stays applied. ``auto`` is the one that drifts (a GPU or driver appearing after an automatic CPU install makes detection resolve elsewhere) and re-applying it is offered exactly then."""
if backend_request != "auto":
- return True
+ return installed_backend is None or installed_backend == backend_request
auto = next((option for option in options if option["backend"] == "auto"), None)
if not auto or not auto.get("available"):
return True
diff --git a/studio/backend/utils/prebuilt/llama_backend.py b/studio/backend/utils/prebuilt/llama_backend.py
index 4b7ac5aae36..3ce655f8b2b 100644
--- a/studio/backend/utils/prebuilt/llama_backend.py
+++ b/studio/backend/utils/prebuilt/llama_backend.py
@@ -159,9 +159,18 @@ def marker_backend_was_chosen(marker: Optional[Mapping[str, Any]]) -> bool:
crash stays repairable, while an update keeps the bundle rather than swapping
backends behind the user. They part ways on a corrupt value too -- recovery
keeps its hands off it, an update re-detects.
+
+ ``backend_request_unsatisfied`` is the third parting: the installer now PRESERVES a
+ concrete request that the install could not honour (so a later update can retry it)
+ instead of erasing it to "auto", and the bundle on disk is then the one DETECTION
+ picked. This asks about the installed bundle, so such a marker stays "detected",
+ exactly as it read before the request was preserved. Absent -- every marker written
+ before the field -- means satisfied.
"""
if not marker:
return False
+ if marker.get("backend_request_unsatisfied"):
+ return False
recorded = marker.get("backend_request")
if isinstance(recorded, str) and recorded.strip():
return recorded.strip().lower() != "auto"
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index e008df6d6ab..222b7a404eb 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -2625,6 +2625,13 @@ def _pick_rocm_gfx_target(out: str) -> str | None:
A bare first-match picked the wrong device on mixed APU + dGPU hosts (Strix Halo gfx1151
+ RX 7900 gfx1100), so honour HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES /
CUDA_VISIBLE_DEVICES; no env var means the first GPU, empty / "-1" means none (None).
+
+ Unmasked, the first GPU is the wrong one when an integrated GPU leads enumeration (#7776,
+ #11143: gfx1036 ahead of an RX 9060 XT gfx1200), since one arch picks the bundle for the
+ whole host. So prefer the first arch neither in SHADOWING_INTEGRATED_GFX nor gfx906, the
+ same rule and gfx906 exclusion as _amd_prefer_discrete_gfx in install.sh / studio/setup.sh;
+ an all-integrated host keeps its own arch. A mask is never second-guessed at ANY value,
+ including one this cannot resolve: HIP_VISIBLE_DEVICES=N is the #7624 / #7669 workaround.
"""
_tokens = _list_rocm_gfx_targets(out)
if not _tokens:
@@ -2649,7 +2656,18 @@ def _pick_rocm_gfx_target(out: str) -> str | None:
return _tokens[_idx]
except ValueError:
pass
- return _tokens[0]
+ # An explicit selection this function cannot resolve: device 0, as before.
+ return _tokens[0]
+
+ _pick = _tokens[0]
+ if _pick not in SHADOWING_INTEGRATED_GFX:
+ return _pick
+ for _candidate in _tokens:
+ if _candidate in SHADOWING_INTEGRATED_GFX or _candidate == "gfx906":
+ continue
+ return _candidate
+ # Every device is an integrated arch (or gfx906): keep the leading one, never None.
+ return _pick
# Display-adapter device class: one NNNN subkey per installed display driver
@@ -3119,9 +3137,9 @@ def _apply_host_overrides(
)
gfx = _normalize_forwarded_gfx(override_rocm_gfx)
if gfx:
- # setup.ps1 resolves all three masks via Resolve-VisibleGpuIndex, but also applies the
- # shadowing-iGPU preference (#7776) that _pick_rocm_gfx_target() does not, so the two
- # can name different GPUs on a mixed APU + dGPU host.
+ # setup.ps1 and _pick_rocm_gfx_target() both apply the shadowing-iGPU preference
+ # (#7776) yet can still disagree: the shells also require a wheel/bundle route, and an
+ # older setup forwards a pick made without the preference at all.
# So keep a probed active arch when the forward is only advisory, else
# _should_auto_vulkan_for_amd_windows() reads a HIP-supported GPU the user masked
# off and installs an unusable HIP bundle instead of Vulkan. Advisory means:
@@ -3137,9 +3155,9 @@ def _apply_host_overrides(
_active = _active_rocm_gfx_target(host)
_advisory = gfx in _physical or gfx in WINDOWS_ROCM_FAMILY_GFX_LABELS
# Except when setup deliberately skipped a shadowing APU for the discrete card (#7776):
- # unmasked, _pick_rocm_gfx_target() still reads that APU as device 0, so discarding the
- # forward would give torch the dGPU and llama.cpp the iGPU bundle. Unmasked only, since
- # the repick must never override a pin.
+ # when the probe here reads that APU as active anyway (only the iGPU enumerates under
+ # HIP), dropping the forward gives torch the dGPU and llama.cpp the iGPU bundle.
+ # Unmasked only: the repick must never override a pin.
if (
_advisory
and _active in SHADOWING_INTEGRATED_GFX
@@ -7116,22 +7134,55 @@ def persisted_llama_backend(llama_backend: str | None, choice: AssetChoice) -> s
def persisted_marker_backend_request(backend_request: str | None, choice: AssetChoice) -> str:
"""The backend choice to record for an install that landed ``choice``.
- Same rule as persisted_llama_backend, generalized: record the request only when
- the install actually honours it. A request that ended somewhere else -- cpu or
- vulkan on macOS, where the universal Metal bundle is the only build -- is stored
- as automatic, so the next update re-detects instead of re-asserting a choice
- this host never applied. "auto" is stored explicitly rather than omitted: absent
- means "written before this field existed", which reads back as the derived
- legacy choice, not as detection.
+ The request VERBATIM, "auto" only when that is what was asked. "auto" is stored
+ explicitly rather than omitted: absent means "written before this field existed",
+ which reads back as the derived legacy choice, not as detection.
+
+ It used to store "auto" whenever the request and the bundle disagreed, which erased
+ the choice permanently: every later update re-detected, and on AMD that means ROCm, so
+ a configured Vulkan kept coming back as "automatic" (#11143). The miss is now recorded
+ alongside by marker_backend_request_was_satisfied instead.
"""
- effective = backend_for_install_kind(choice.install_kind)
if backend_request in (None, "auto"):
return "auto"
- if effective is not None and effective != backend_request:
+ # A single-build platform can never apply a named backend, so record detection, as before.
+ effective = backend_for_install_kind(choice.install_kind)
+ if effective is not None and not is_requestable_backend(effective):
return "auto"
return backend_request
+def marker_backend_request_was_satisfied(backend_request: str | None, choice: AssetChoice) -> bool:
+ """Whether the request this marker records is the backend that actually landed.
+
+ A bundle whose kind maps to no backend cannot contradict the request, so it counts as
+ satisfied: the same "None cannot disagree" rule the erasing version used.
+ """
+ if backend_request in (None, "auto"):
+ return True
+ effective = backend_for_install_kind(choice.install_kind)
+ if effective is None:
+ return True
+ # A platform publishing exactly ONE build can never honour a named backend, which is why
+ # "metal" is out of REQUESTABLE_BACKENDS. Counting macOS unsatisfied owed a retry no
+ # release could serve, and Settings rendered an option resolve_backends_payload never offers.
+ if not is_requestable_backend(effective):
+ return True
+ return effective == backend_request
+
+
+# Marker field: the recorded backend_request is a choice still owed, not a description of the
+# install. Absent means satisfied, which is how every marker written before this field reads.
+MARKER_BACKEND_REQUEST_UNSATISFIED = "backend_request_unsatisfied"
+
+
+def marker_records_unsatisfied_backend_request(marker: "dict[str, Any] | None") -> bool:
+ """Whether ``marker`` says its recorded request was not the backend installed."""
+ if not marker:
+ return False
+ return bool(marker.get(MARKER_BACKEND_REQUEST_UNSATISFIED))
+
+
def host_profile(host: HostInfo) -> dict[str, Any]:
"""The hardware facts the backend routing reads, in a shape a marker can hold.
@@ -7259,6 +7310,12 @@ def write_prebuilt_metadata(
"backend": backend_for_install_kind(choice.install_kind),
# What future updates should preserve. "auto" re-detects.
"backend_request": persisted_marker_backend_request(backend_request, choice),
+ # Present only when the request is NOT what landed, so old markers read satisfied.
+ **(
+ {}
+ if marker_backend_request_was_satisfied(backend_request, choice)
+ else {MARKER_BACKEND_REQUEST_UNSATISFIED: True}
+ ),
# The AMD gfx an AUTOMATIC route was decided on. A Vulkan asset name carries
# no arch, and the Windows driver-only hosts that reach Vulkan automatically
# have no probe (hipinfo/amd-smi absent), so the updater would re-detect a
@@ -7434,6 +7491,13 @@ def _marker_selection_patch(
recorded_request = persisted_marker_backend_request(backend_request, choice)
if marker.get("backend_request") != recorded_request:
patch["backend_request"] = recorded_request
+ # None pops the key, keeping absence the only spelling of satisfied; the `in marker` half
+ # canonicalises away an explicit false some build may already have written.
+ unsatisfied = not marker_backend_request_was_satisfied(backend_request, choice)
+ if bool(marker.get(MARKER_BACKEND_REQUEST_UNSATISFIED)) != unsatisfied or (
+ not unsatisfied and MARKER_BACKEND_REQUEST_UNSATISFIED in marker
+ ):
+ patch[MARKER_BACKEND_REQUEST_UNSATISFIED] = True if unsatisfied else None
# Unlike the fields above, None here means "this release declares none"
# (upstream ggml-org tags), not "clear it".
if ggml_tree and marker.get("ggml_tree") != ggml_tree:
@@ -7541,7 +7605,11 @@ def sync_marker_selection(
if not patch:
return
for key, value in patch.items():
- if value is None and key in ("llama_backend", *_core.WALK_BACK_KEYS):
+ if value is None and key in (
+ "llama_backend",
+ MARKER_BACKEND_REQUEST_UNSATISFIED,
+ *_core.WALK_BACK_KEYS,
+ ):
marker.pop(key, None)
else:
marker[key] = value
@@ -8475,11 +8543,11 @@ def _marker_backend_fits_host(marker: "dict[str, Any]", host: HostInfo) -> bool:
Two assertions, both cheap and both about the MARKER rather than the disk:
- * self-consistency. write_prebuilt_metadata records backend_request through
- persisted_marker_backend_request, which stores "auto" whenever the request and
- the bundle that landed disagree. So a marker naming a concrete request must name
- the same backend, or it was not written by this installer -- and the rest of this
- check reads those two fields to decide it need do no work.
+ * self-consistency. A marker naming a concrete request must name the same backend,
+ or it was not written by this installer -- and the rest of this check reads those
+ two fields to decide it need do no work. Except when this installer recorded the
+ disagreement on purpose (#11143): then the disagreement IS the record. Without
+ that flag it is still a marker from somewhere else.
* platform fit. backend_for_install_kind maps kinds to backends; a backend with no
kind on this platform (a "cuda" marker on macOS, a copied install directory)
cannot describe a bundle this run would produce, and _kept_install_payload_is_healthy
@@ -8493,6 +8561,7 @@ def _marker_backend_fits_host(marker: "dict[str, Any]", host: HostInfo) -> bool:
isinstance(recorded_request, str)
and recorded_request not in ("", "auto")
and recorded_request != recorded_backend
+ and not marker_records_unsatisfied_backend_request(marker)
):
return False
platform_prefix = "windows-" if host.is_windows else "macos-" if host.is_macos else "linux-"
@@ -8512,6 +8581,7 @@ def existing_install_current_without_plan(
override_has_rocm: bool = False,
override_rocm_gfx: str | None = None,
route: "BackendRoute | None" = None,
+ backend_request_mandatory: bool = False,
) -> bool:
"""Whether the install on disk is already the one this run would produce.
@@ -8536,6 +8606,9 @@ def existing_install_current_without_plan(
compared against the profile the install recorded. A marker with no host_profile --
every one written before this existed -- cannot answer and takes the full path.
+ *backend_request_mandatory* says the request was named by THIS run rather than read back
+ off the marker; it only matters for a request the install could not honour, see below.
+
See _expected_release_tag_without_plan for the one thing this deliberately does NOT
close: the documented "latest" pointer lag.
"""
@@ -8551,6 +8624,16 @@ def existing_install_current_without_plan(
recorded_request = marker.get("backend_request")
if not isinstance(recorded_request, str) or recorded_request != backend_request:
return False
+ # An unhonoured request is preserved now (#11143), so "recorded == requested" no longer
+ # implies the bundle runs it; it is owed a RETRY. Named by THIS run, re-assert at once;
+ # read off the marker, retry only once something moved, which is what the checks below
+ # test -- retrying unconditionally costs the full listing plus re-validation (13-63 s on
+ # macOS) on every update of a host that cannot serve the choice. So judge a marker-read
+ # install as the AUTOMATIC one it is: routing the unsatisfied request rewrites the host
+ # (a Vulkan route drops has_rocm and the AMD arch) and can never match the marker.
+ unsatisfied = marker_records_unsatisfied_backend_request(marker)
+ if unsatisfied and backend_request_mandatory:
+ return False
if bool(marker.get("force_cpu")) != bool(force_cpu):
return False
# A fallback bundle is a stopgap: its marker keeps taking the full path, which retries the preferred.
@@ -8558,6 +8641,16 @@ def existing_install_current_without_plan(
log("kept install rejected: it is a fallback bundle; the preferred one is retried")
return False
# (2) the hardware. Local probes only, and the caller's route, so they run once per update.
+ if unsatisfied and (route is None or route.backend != "auto"):
+ # The caller's route was computed for the request, which this install does not run.
+ route = route_backend_request(
+ backend = "auto",
+ published_repo = published_repo,
+ published_release_tag = published_release_tag,
+ override_has_rocm = override_has_rocm,
+ override_rocm_gfx = override_rocm_gfx,
+ cpu_mechanism = force_cpu,
+ )
if route is None:
route = route_backend_request(
backend = backend_request,
@@ -10490,9 +10583,19 @@ def install_prebuilt(
# another is a request to CHANGE the install.
backend_request = backend,
force_cpu = force_cpu,
+ # The SAME forwarded detection initial_route was built from: without these,
+ # the "auto" re-derivation inside rebuilds the profile from a bare probe, which
+ # on any host whose AMD identity arrives as --rocm-gfx can never match.
+ override_has_rocm = override_has_rocm,
+ override_rocm_gfx = override_rocm_gfx,
route = initial_route,
+ # Only an explicit name re-asserts a request the last install could not
+ # honour; a request read back off the marker retries when something moves.
+ backend_request_mandatory = backend_mandatory,
):
return
+ # A request detection had to replace; kept so the marker records the CHOICE.
+ unhonoured_request: str | None = None
try:
selection = _select(backend, initial_route)
except BackendUnavailable:
@@ -10505,6 +10608,7 @@ def install_prebuilt(
f"the {backend} backend recorded by this install is not available here; "
"falling back to hardware detection"
)
+ unhonoured_request = backend
backend = "auto"
# Restore caller flags before detection chooses a replacement.
force_cpu, persist_force_cpu = caller_force_cpu, caller_persist_force_cpu
@@ -10516,7 +10620,10 @@ def install_prebuilt(
release_plans = selection.release_plans
persist_llama_backend = selection.persist_llama_backend
persist_rocm_gfx = selection.persist_rocm_gfx
- persist_backend_request = backend
+ # The CHOICE, not the replacement detection made for it: "auto" here is what
+ # destroyed a Vulkan choice permanently on AMD, where every detect means ROCm
+ # (#11143). The miss is flagged separately, so this is never read as installed.
+ persist_backend_request = unhonoured_request or backend
def _record_reused_selection(
plan: InstallReleasePlan, reused: AssetChoice, used_fallback: bool
diff --git a/tests/studio/install/test_amd_hybrid_igpu_routing_11143.py b/tests/studio/install/test_amd_hybrid_igpu_routing_11143.py
new file mode 100644
index 00000000000..89e63b3c9ef
--- /dev/null
+++ b/tests/studio/install/test_amd_hybrid_igpu_routing_11143.py
@@ -0,0 +1,293 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team.
+"""#11143: a Fedora box whose AMD iGPU drives the desktop and whose discrete Radeon RX 9060
+XT (RDNA4, gfx1200) does the work kept being installed for the iGPU and kept coming back on
+ROCm after the user had configured Vulkan.
+
+Two defects, both in studio/install_llama_prebuilt.py:
+
+ * ``_pick_rocm_gfx_target`` ended ``return _tokens[0]``, so the arch that decides the
+ bundle for the whole host was the one that happened to enumerate first -- the APU.
+ * ``persisted_marker_backend_request`` erased a request the install could not honour to
+ "auto", so the Vulkan choice was destroyed permanently and every later update
+ re-detected, which on an AMD host means ROCm.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[3]
+MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
+_SPEC = importlib.util.spec_from_file_location("studio_install_llama_prebuilt_11143", MODULE_PATH)
+assert _SPEC is not None and _SPEC.loader is not None
+ILP = importlib.util.module_from_spec(_SPEC)
+sys.modules[_SPEC.name] = ILP
+_SPEC.loader.exec_module(ILP)
+
+_VISIBILITY_ENV = ("HIP_VISIBLE_DEVICES", "ROCR_VISIBLE_DEVICES", "CUDA_VISIBLE_DEVICES")
+
+
+def _rocminfo(*arches: str) -> str:
+ """rocminfo as the real tool prints it: one agent section per GPU, arch repeated."""
+ return "".join(
+ f"***\nAgent {index}\n***\n Name: {arch}\n ISA: amdgcn-amd-amdhsa--{arch}\n"
+ for index, arch in enumerate(arches, start = 1)
+ )
+
+
+def unmasked(monkeypatch):
+ for name in _VISIBILITY_ENV:
+ monkeypatch.delenv(name, raising = False)
+ return monkeypatch
+
+
+def test_a_leading_igpu_does_not_strand_the_discrete_card(unmasked):
+ """The reported host: Raphael gfx1036 driving the display enumerates ahead of the
+ RX 9060 XT. One arch picks the bundle, so the discrete card must win."""
+ assert ILP._pick_rocm_gfx_target(_rocminfo("gfx1036", "gfx1200")) == "gfx1200"
+
+
+def test_every_shadowing_arch_defers_to_a_discrete_card(unmasked):
+ """The table is the contract, not the one arch from the report."""
+ for igpu in sorted(ILP.SHADOWING_INTEGRATED_GFX):
+ assert ILP._pick_rocm_gfx_target(_rocminfo(igpu, "gfx1100")) == "gfx1100", igpu
+
+
+def test_a_non_shadowing_first_arch_is_untouched(unmasked):
+ """A discrete card that enumerates first already decided; the preference must not
+ reorder a host it has no business reordering."""
+ assert ILP._pick_rocm_gfx_target(_rocminfo("gfx1100", "gfx1036")) == "gfx1100"
+ assert ILP._pick_rocm_gfx_target(_rocminfo("gfx1200")) == "gfx1200"
+
+
+def test_an_all_integrated_host_keeps_its_own_arch(unmasked):
+ """Nothing to prefer. The old code returned the first token here and still must:
+ returning None would drop a host that has a perfectly good APU bundle."""
+ assert ILP._pick_rocm_gfx_target(_rocminfo("gfx1036", "gfx1103")) == "gfx1036"
+ assert ILP._pick_rocm_gfx_target(_rocminfo("gfx1036")) == "gfx1036"
+
+
+def test_gfx906_is_never_the_repick(unmasked):
+ """install.sh excludes it because naming it on a mixed host strands BOTH cards."""
+ assert ILP._pick_rocm_gfx_target(_rocminfo("gfx1036", "gfx906", "gfx1200")) == "gfx1200"
+ # Nothing else to move to: the iGPU stays, rather than gfx906 being chosen.
+ assert ILP._pick_rocm_gfx_target(_rocminfo("gfx1036", "gfx906")) == "gfx1036"
+
+
[email protected]("env", _VISIBILITY_ENV)
+def test_an_explicit_visibility_mask_still_wins(monkeypatch, env):
+ """HIP_VISIBLE_DEVICES=0 on the hybrid host selects the iGPU on purpose -- it is the
+ documented workaround for #7624 / #7669 -- and the preference must not undo it."""
+ for name in _VISIBILITY_ENV:
+ monkeypatch.delenv(name, raising = False)
+ monkeypatch.setenv(env, "0")
+ assert ILP._pick_rocm_gfx_target(_rocminfo("gfx1036", "gfx1200")) == "gfx1036"
+ monkeypatch.setenv(env, "1")
+ assert ILP._pick_rocm_gfx_target(_rocminfo("gfx1036", "gfx1200")) == "gfx1200"
+
+
[email protected]("value", ["", "-1"])
+def test_a_mask_selecting_no_device_still_means_no_gpu(unmasked, value):
+ unmasked.setenv("HIP_VISIBLE_DEVICES", value)
+ assert ILP._pick_rocm_gfx_target(_rocminfo("gfx1036", "gfx1200")) is None
+
+
[email protected]("value", ["GPU-abc123", "7"])
+def test_a_mask_this_resolver_cannot_read_is_still_an_explicit_choice(unmasked, value):
+ """UUID-style and out-of-range masks fell through to device 0 before, and must keep
+ doing so: the user selected a device, so this is not the place to second-guess it."""
+ unmasked.setenv("HIP_VISIBLE_DEVICES", value)
+ assert ILP._pick_rocm_gfx_target(_rocminfo("gfx1036", "gfx1200")) == "gfx1036"
+
+
+def _choice(install_kind: str) -> "ILP.AssetChoice":
+ return ILP.AssetChoice(
+ repo = "unslothai/llama.cpp",
+ tag = "b9925",
+ name = "bundle.tar.gz",
+ url = "https://example/bundle",
+ source_label = "published",
+ install_kind = install_kind,
+ )
+
+
+def test_a_vulkan_request_that_landed_rocm_keeps_the_request():
+ """The reported symptom: "settings were already configured for Vulkan" and ROCm kept
+ coming back. Recording "auto" destroyed the choice, so every later update re-detected."""
+ landed = _choice("linux-rocm")
+ assert ILP.persisted_marker_backend_request("vulkan", landed) == "vulkan"
+ assert ILP.marker_backend_request_was_satisfied("vulkan", landed) is False
+
+
+def test_a_request_the_bundle_honours_is_not_flagged():
+ landed = _choice("linux-vulkan")
+ assert ILP.persisted_marker_backend_request("vulkan", landed) == "vulkan"
+ assert ILP.marker_backend_request_was_satisfied("vulkan", landed) is True
+
+
[email protected]("request_backend", [None, "auto"])
+def test_detection_is_never_flagged_unsatisfied(request_backend):
+ """ "auto" asks for whatever the host resolves to, so nothing can contradict it."""
+ landed = _choice("linux-rocm")
+ assert ILP.persisted_marker_backend_request(request_backend, landed) == "auto"
+ assert ILP.marker_backend_request_was_satisfied(request_backend, landed) is True
+
+
+def test_an_old_marker_without_the_field_reads_as_satisfied():
+ """Back-compat is the whole reason the flag is absent-means-satisfied: every marker
+ ever written lacks it, and each one described an install that honoured its request."""
+ assert ILP.marker_records_unsatisfied_backend_request(None) is False
+ assert ILP.marker_records_unsatisfied_backend_request({}) is False
+ assert (
+ ILP.marker_records_unsatisfied_backend_request(
+ {"backend_request": "vulkan", "backend": "vulkan"}
+ )
+ is False
+ )
+ assert (
+ ILP.marker_records_unsatisfied_backend_request(
+ {"backend_request": "vulkan", "backend": "rocm", "backend_request_unsatisfied": True}
+ )
+ is True
+ )
+
+
+def _linux_host() -> "ILP.HostInfo":
+ return ILP.HostInfo(
+ system = "Linux",
+ machine = "x86_64",
+ is_windows = False,
+ is_macos = False,
+ is_linux = True,
+ 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,
+ )
+
+
+def test_only_a_flagged_marker_may_disagree_with_its_own_backend():
+ """_marker_backend_fits_host reads the pair as self-consistency evidence. A
+ disagreement the installer recorded on purpose is consistent; one with no flag is
+ still a marker this installer did not write, and keeps taking the full path."""
+ host = _linux_host()
+ honest = {"backend_request": "vulkan", "backend": "vulkan"}
+ unflagged = {"backend_request": "vulkan", "backend": "rocm"}
+ flagged = dict(unflagged, backend_request_unsatisfied = True)
+ assert ILP._marker_backend_fits_host(honest, host) is True
+ assert ILP._marker_backend_fits_host(unflagged, host) is False
+ assert ILP._marker_backend_fits_host(flagged, host) is True
+
+
+def test_an_unserved_preferred_arch_source_builds_rather_than_using_the_igpus_bundle():
+ """The trade-off the preference accepts, pinned so changing it is deliberate.
+
+ Among the shadowing arches only gfx1103 is served (by the gfx110X family), so a
+ gfx1103 APU beside a discrete card this release does not build -- RDNA1 gfx1010 to
+ gfx1012 -- now resolves to the discrete arch, finds no bundle, and source builds,
+ where before the preference it silently ran on the iGPU.
+
+ That is the intended direction, not a regression to paper over: running the iGPU
+ while a discrete card sits idle IS the complaint in #11143, and
+ test_rdna1_unsupported_message_8529 records that CPU is the correct outcome on
+ RDNA1 rather than a working-looking install on the wrong device. A fallback to the
+ iGPU's bundle was tried and reverted: it selected a bundle for a device the user
+ may have masked off, and left _kept_install_covers_host rejecting the very bundle
+ it had just installed, because that check reads only host.rocm_gfx_target.
+ """
+ assert ILP._pick_rocm_gfx_target(_rocminfo("gfx1103", "gfx1010")) == "gfx1010"
+
+
+def test_the_fast_path_keeps_the_callers_forwarded_rocm_detection():
+ """An unsatisfied recorded request re-derives the route as "auto" inside
+ existing_install_current_without_plan. It has to re-derive it from the SAME
+ forwarded detection, or on every Linux AMD host -- setup.sh always forwards
+ --rocm-gfx -- the rebuilt host profile cannot match the recorded one, the fast path
+ fails, and each update pays the full listing plus re-validation.
+
+ Asserted on the call site because the cost is a missing keyword argument, and a
+ behavioural test would have to stand up a whole install tree to observe it.
+ """
+ import ast
+ import inspect
+
+ tree = ast.parse(inspect.getsource(ILP.install_prebuilt))
+ for node in ast.walk(tree):
+ if (
+ isinstance(node, ast.Call)
+ and getattr(node.func, "id", None) == "existing_install_current_without_plan"
+ ):
+ passed = {kw.arg for kw in node.keywords}
+ missing = {"override_has_rocm", "override_rocm_gfx", "route"} - passed
+ assert not missing, (
+ f"install_prebuilt calls existing_install_current_without_plan without "
+ f"{sorted(missing)}, so its re-derived route describes a different host"
+ )
+ return
+ raise AssertionError("no existing_install_current_without_plan call found")
+
+
+def test_an_explicit_false_flag_is_canonicalised_away_on_reuse():
+ """Absent is the only spelling of satisfied. A marker already carrying an explicit
+ false has to lose the key, or readers get two spellings of one state."""
+ marker = {
+ "backend_request": "vulkan",
+ "backend": "vulkan",
+ ILP.MARKER_BACKEND_REQUEST_UNSATISFIED: False,
+ }
+ patch = ILP._marker_selection_patch(
+ marker,
+ choice = _choice("linux-vulkan"),
+ backend_request = "vulkan",
+ persist_force_cpu = False,
+ persist_llama_backend = None,
+ ggml_tree = None,
+ rocm_gfx = None,
+ )
+ assert ILP.MARKER_BACKEND_REQUEST_UNSATISFIED in patch
+ assert patch[ILP.MARKER_BACKEND_REQUEST_UNSATISFIED] is None
+
+
+def test_a_satisfied_marker_without_the_flag_is_left_alone():
+ """The negative control for the above: no key, nothing to canonicalise."""
+ patch = ILP._marker_selection_patch(
+ {"backend_request": "vulkan", "backend": "vulkan"},
+ choice = _choice("linux-vulkan"),
+ backend_request = "vulkan",
+ persist_force_cpu = False,
+ persist_llama_backend = None,
+ ggml_tree = None,
+ rocm_gfx = None,
+ )
+ assert ILP.MARKER_BACKEND_REQUEST_UNSATISFIED not in patch
+
+
+def test_a_single_build_platform_never_records_an_unfulfillable_request():
+ """macOS ships one universal Metal bundle, and `metal` is kept out of
+ REQUESTABLE_BACKENDS for that reason, so `cpu` or `vulkan` there can never become the
+ installed backend. Preserving the request left Settings with a stored selection the
+ picker has no option for -- resolve_backends_payload offers only "auto" on macOS -- and
+ an Apply that always answered backend_unavailable. Record detection instead, and keep
+ preservation for the multi-build platforms it exists for.
+ """
+ mac = _choice("macos-arm64")
+ for request in ("cpu", "vulkan", "rocm", "cuda"):
+ assert ILP.persisted_marker_backend_request(request, mac) == "auto"
+ assert ILP.marker_backend_request_was_satisfied(request, mac) is True
+ # The reason it is safe: the landed backend is not one a user can ask for.
+ assert ILP.backend_for_install_kind("macos-arm64") == "metal"
+ assert "metal" not in ILP.REQUESTABLE_BACKENDS
+ # Unchanged where a later release COULD serve the request.
+ assert ILP.persisted_marker_backend_request("vulkan", _choice("linux-rocm")) == "vulkan"
+ assert ILP.marker_backend_request_was_satisfied("vulkan", _choice("linux-rocm")) is False
diff --git a/tests/studio/install/test_install_llama_prebuilt_logic.py b/tests/studio/install/test_install_llama_prebuilt_logic.py
index 9bebda1f0b0..71d74a2c38b 100644
--- a/tests/studio/install/test_install_llama_prebuilt_logic.py
+++ b/tests/studio/install/test_install_llama_prebuilt_logic.py
@@ -6412,13 +6412,59 @@ def test_a_marker_naming_a_backend_this_platform_cannot_hold_is_not_current(tmp_
def test_a_marker_whose_request_and_backend_disagree_is_not_current(tmp_path, monkeypatch):
- """persisted_marker_backend_request stores "auto" whenever the request and the
- bundle that landed disagree, so a concrete request must name the bundle's own
- backend. Anything else was not written by this installer."""
+ """A concrete request must name the bundle's own backend, or say outright that it is
+ a request the install could not honour (the test below). A bare disagreement with no
+ such flag was not written by this installer."""
install_dir = _current_install(tmp_path, monkeypatch, backend_request = "vulkan")
assert _check(install_dir, backend_request = "vulkan") is False
+# A request the install could not honour is PRESERVED now (#11143), so the fast path holds two
+# lines at once: retry the choice when something moved, and do not pay the full listing plus
+# re-validation on every update of a host that simply cannot serve it.
+_UNSATISFIED = dict(backend_request = "vulkan", backend_request_unsatisfied = True)
+
+
+def test_an_unsatisfied_choice_read_off_the_marker_does_not_reinstall_every_update(
+ tmp_path, monkeypatch
+):
+ """Nothing moved, so the install on disk is still the one this run would produce. The
+ request stays recorded, owed a retry, not retried here."""
+ install_dir = _current_install(tmp_path, monkeypatch, **_UNSATISFIED)
+ assert _check(install_dir, backend_request = "vulkan") is True
+ marker = json.loads((install_dir / "UNSLOTH_PREBUILT_INFO.json").read_text(encoding = "utf-8"))
+ assert marker["backend_request"] == "vulkan"
+
+
+def test_an_unsatisfied_choice_named_by_this_run_is_re_asserted(tmp_path, monkeypatch):
+ """--llama-backend vulkan (or Settings, which passes it) is someone asking again by
+ hand: take the full path, where the request is re-asserted and, if it still cannot be
+ served, fails loudly instead of silently keeping the bundle it did not ask for."""
+ install_dir = _current_install(tmp_path, monkeypatch, **_UNSATISFIED)
+ assert _check(install_dir, backend_request = "vulkan", backend_request_mandatory = True) is False
+
+
+def test_an_unsatisfied_choice_is_retried_when_the_release_moves(tmp_path, monkeypatch):
+ """The "something changed" half: a new release republishes the bundles, so the choice
+ gets another go. Same for new hardware, which the host_profile check already covers."""
+ install_dir = _current_install(tmp_path, monkeypatch, **_UNSATISFIED)
+ monkeypatch.setattr(
+ INSTALL_LLAMA_PREBUILT, "_download_host_latest_release_tag", lambda _repo: "release-2"
+ )
+ assert _check(install_dir, backend_request = "vulkan") is False
+
+
+def test_an_old_marker_is_read_as_a_satisfied_choice(tmp_path, monkeypatch):
+ """No flag means satisfied, so every install made before the field behaves exactly as
+ it did: a recorded choice that names the installed backend stays current."""
+ install_dir = _current_install(tmp_path, monkeypatch, backend_request = "cpu", backend = "cpu")
+ marker = json.loads((install_dir / "UNSLOTH_PREBUILT_INFO.json").read_text(encoding = "utf-8"))
+ assert "backend_request_unsatisfied" not in marker
+ assert _check(install_dir, backend_request = "cpu") is True
+ # And the mandatory flag changes nothing for it: there is no unmet request to re-assert.
+ assert _check(install_dir, backend_request = "cpu", backend_request_mandatory = True) is True
+
+
def test_a_truncated_shared_library_is_not_current(tmp_path, monkeypatch):
"""The payload scan only globs for existence, so a half-written libggml-*.so keeps
its name and passes it. Most of a CUDA bundle's bytes live in those libraries, and a
diff --git a/tests/studio/install/test_rocm_arch_table_parity.py b/tests/studio/install/test_rocm_arch_table_parity.py
index 2141c136cb9..541e3d73eb8 100644
--- a/tests/studio/install/test_rocm_arch_table_parity.py
+++ b/tests/studio/install/test_rocm_arch_table_parity.py
@@ -838,6 +838,20 @@ class TestShadowingPreferenceIsApplied:
"so that consumer still receives the iGPU's arch"
)
+ def test_pick_rocm_gfx_target_consults_the_shadowing_table(self):
+ """install_llama_prebuilt.py holds the table; this is the function that has
+ to read it. It ended `return _tokens[0]` with no preference at all."""
+ tree = ast.parse(_PREBUILT_PY.read_text(encoding = "utf-8"))
+ for node in ast.walk(tree):
+ if isinstance(node, ast.FunctionDef) and node.name == "_pick_rocm_gfx_target":
+ names = {n.id for n in ast.walk(node) if isinstance(n, ast.Name)}
+ assert "SHADOWING_INTEGRATED_GFX" in names, (
+ "_pick_rocm_gfx_target does not consult SHADOWING_INTEGRATED_GFX, so a "
+ "leading iGPU still wins on a hybrid host (#11143)"
+ )
+ return
+ raise AssertionError("_pick_rocm_gfx_target not found in install_llama_prebuilt.py")
+
@pytest.mark.parametrize("rel", _SHELL_RESOLVERS)
def test_an_explicit_visibility_mask_is_honoured_by_each_shell_copy(self, rel):
"""`HIP_VISIBLE_DEVICES=1` is the documented #7624 / #7669 workaround; a repick