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: explicit XPU GPU ids on single-tile Intel hosts (#13540)

Daniel Hanb16b1390b811
diff --git a/studio/backend/tests/test_xpu_single_tile_host.py b/studio/backend/tests/test_xpu_single_tile_host.py
new file mode 100644
index 00000000000..179e17cc999
--- /dev/null
+++ b/studio/backend/tests/test_xpu_single_tile_host.py
@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Explicit XPU GPU ids at the driver's default hierarchy: Arc / Flex cards and Intel iGPUs have one
+tile per root, so FLAT and COMPOSITE enumerate the same devices. Fake sysfs trees only."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import pytest
+
+import utils.hardware.hardware as hw
+
+
+def _card(drm, pci, n, vendor, device):
+ dev = pci / f"0000:{n}"
+ dev.mkdir(parents = True)
+ if vendor is not None:
+ (dev / "vendor").write_text(vendor + "\n")
+ (dev / "device").write_text(device + "\n")
+ card = drm / f"card{len(os.listdir(drm))}"
+ card.mkdir()
+ (card / "device").symlink_to(dev)
+
+
+def sysfs(tmp_path, monkeypatch):
+ monkeypatch.setattr(hw.sys, "platform", "linux")
+ drm, pci = tmp_path / "drm", tmp_path / "pci"
+ drm.mkdir()
+ pci.mkdir()
+
+ def _add(
+ n,
+ vendor,
+ device = "0x0000",
+ ):
+ _card(drm, pci, n, vendor, device)
+ return str(drm)
+
+ return _add, str(drm)
+
+
+ ("cards", "single_tile"),
+ [
+ ([("03:00.0", "0x8086", "0xe20b"), ("04:00.0", "0x8086", "0xe20b")], True), # 2x B580
+ (
+ [("00:02.0", "0x8086", "0xa780"), ("03:00.0", "0x8086", "0xe211")],
+ True,
+ ), # UHD 770 + Pro B60
+ ([("03:00.0", "0x8086", "0x56a0"), ("01:00.0", "0x10de", "0x2684")], True), # A770 + NVIDIA
+ (
+ [("00:03.0", None, None), ("03:00.0", "0x8086", "0x56c0")],
+ True,
+ ), # framebuffer + Flex 170
+ ([("03:00.0", "0x8086", "0x0bd5"), ("04:00.0", "0x8086", "0x0bd5")], False), # Max 1550
+ ([("03:00.0", "0x8086", "0x4905")], False), # DG1: not an allowlisted part
+ ([("01:00.0", "0x10de", "0x2684")], False), # no Intel card
+ ([], False),
+ ],
+)
[email protected](sys.platform == "win32", reason = "fake sysfs needs ':' in paths and symlinks")
+def test_single_tile_host(sysfs, cards, single_tile):
+ add, drm = sysfs
+ for pci, vendor, device in cards:
+ add(pci, vendor, device)
+ assert hw._intel_xpu_single_tile_host(drm) is single_tile
+
+
+def test_non_linux_hosts_keep_the_flat_assumption(monkeypatch):
+ monkeypatch.setattr(hw.sys, "platform", "win32")
+ assert hw._intel_xpu_single_tile_host() is False
+
+
+ ("hierarchy", "single_tile", "composite"),
+ [
+ (None, True, True),
+ (None, False, False),
+ ("COMPOSITE", False, True),
+ ("FLAT", True, False),
+ ("COMBINED", True, False),
+ ],
+)
+def test_hierarchy(monkeypatch, hierarchy, single_tile, composite):
+ for var in hw._SYCL_DEVICE_FILTER_VARS:
+ monkeypatch.delenv(var, raising = False)
+ if hierarchy is None:
+ monkeypatch.delenv("ZE_FLAT_DEVICE_HIERARCHY", raising = False)
+ else:
+ monkeypatch.setenv("ZE_FLAT_DEVICE_HIERARCHY", hierarchy)
+ monkeypatch.setattr(hw, "_intel_xpu_single_tile_host", lambda: single_tile)
+ assert hw._xpu_hierarchy_is_composite() is composite
+
+
+def test_multi_tile_ids_are_allowlisted_pvc():
+ assert hw._INTEL_MULTI_TILE_PCI_IDS <= hw._INTEL_XPU_PCI_IDS
+
+
+ "var", ["ONEAPI_DEVICE_SELECTOR", "SYCL_DEVICE_FILTER", "SYCL_DEVICE_ALLOWLIST"]
+)
+def test_a_sycl_device_filter_keeps_ordinals_relative(monkeypatch, var):
+ """The filter re-indexes torch's devices, so ordinal 0 need not be root 0."""
+ monkeypatch.delenv("ZE_FLAT_DEVICE_HIERARCHY", raising = False)
+ monkeypatch.setattr(hw, "_intel_xpu_single_tile_host", lambda: True)
+ monkeypatch.setenv(var, "level_zero:1")
+ assert hw._xpu_hierarchy_is_composite() is False
+ monkeypatch.setenv("ZE_FLAT_DEVICE_HIERARCHY", "COMPOSITE")
+ assert hw._xpu_hierarchy_is_composite() is True
diff --git a/studio/backend/utils/hardware/hardware.py b/studio/backend/utils/hardware/hardware.py
index 9db3a07f414..575e077d1b1 100644
--- a/studio/backend/utils/hardware/hardware.py
+++ b/studio/backend/utils/hardware/hardware.py
@@ -2663,10 +2663,56 @@ def _torch_get_per_device_info(device_indices: list[int]) -> list[Dict[str, Any]
return devices
+# Multi-tile Intel GPUs (Data Center GPU Max): under FLAT each tile is its own device.
+_INTEL_MULTI_TILE_PCI_IDS = frozenset((
+ 0x0BD0, 0x0BD4, 0x0BD5, 0x0BD6, 0x0BD7, 0x0BD8, 0x0BD9, 0x0BDA, 0x0BDB, 0x0B69, 0x0B6E,
+)) # fmt: skip
+
+
+_SYCL_DEVICE_FILTER_VARS = ("ONEAPI_DEVICE_SELECTOR", "SYCL_DEVICE_FILTER", "SYCL_DEVICE_ALLOWLIST")
+
+
+def _intel_xpu_single_tile_host(root: str = "/sys/class/drm") -> bool:
+ """Whether every Intel GPU this Linux host has is known to be single-tile: an allowlisted Arc / Flex part that is not a Data Center GPU Max, or the integrated GPU at PCI 00:02.0. False with no Intel card, an unknown discrete part, or no sysfs (non-Linux)."""
+ if not sys.platform.startswith("linux"):
+ return False
+ try:
+ entries = sorted(os.listdir(root))
+ except OSError:
+ return False
+ found = False
+ for entry in entries:
+ if not re.fullmatch(r"card\d+", entry):
+ continue
+ device = os.path.join(root, entry, "device")
+ try:
+ with open(os.path.join(device, "vendor"), encoding = "utf-8") as fh:
+ if fh.read().strip().lower() != "0x8086":
+ continue
+ with open(os.path.join(device, "device"), encoding = "utf-8") as fh:
+ device_id = int(fh.read().strip(), 16)
+ except FileNotFoundError:
+ continue
+ except (OSError, ValueError):
+ return False
+ integrated = os.path.realpath(device).endswith(":00:02.0")
+ if device_id in _INTEL_MULTI_TILE_PCI_IDS:
+ return False
+ if not (integrated or _intel_pci_device_is_xpu_class(device)):
+ return False
+ found = True
+ return found
+
+
def _xpu_hierarchy_is_composite() -> bool:
- """True iff Level Zero runs in COMPOSITE device hierarchy, where numeric ZE_AFFINITY_MASK entries address root GPU IDs (tiles use N.M). Under FLAT, the oneAPI default and the assumption when ZE_FLAT_DEVICE_HIERARCHY is unset, entries address tile handles and mapping them back to root IDs is unsafe."""
- hierarchy = (os.environ.get("ZE_FLAT_DEVICE_HIERARCHY") or "FLAT").strip().upper()
- return hierarchy == "COMPOSITE"
+ """True iff numeric ZE_AFFINITY_MASK entries address root GPU IDs (tiles use N.M): COMPOSITE hierarchy, or the hierarchy left at the driver default on a host whose Intel GPUs are all single-tile, where the default is COMPOSITE and FLAT would be identical anyway (one tile per root). Otherwise, as on a Data Center GPU Max under FLAT, entries address tile handles and mapping them back to root IDs is unsafe."""
+ hierarchy = (os.environ.get("ZE_FLAT_DEVICE_HIERARCHY") or "").strip().upper()
+ if hierarchy == "COMPOSITE":
+ return True
+ # A SYCL device filter re-indexes torch's devices, so ordinals stop naming roots.
+ if any(os.environ.get(var) for var in _SYCL_DEVICE_FILTER_VARS):
+ return False
+ return hierarchy == "" and _intel_xpu_single_tile_host()
# The prefix C stoul(entry, nullptr, 0) consumes: sign, then hex, binary (C23 strtoul, which current
@@ -4823,7 +4869,7 @@ def _get_parent_visible_gpu_spec() -> Dict[str, Any]:
"numeric_ids": list(range(get_physical_gpu_count())),
"supports_explicit_gpu_ids": True,
}
- # FLAT (oneAPI default): ordinals are tile/device handles, not physical GPU IDs, so numeric_ids=None and telemetry uses relative ordinals; explicit selection needs ZE_FLAT_DEVICE_HIERARCHY=COMPOSITE.
+ # FLAT with a multi-tile or unknown part: ordinals are tile/device handles, not physical GPU IDs, so numeric_ids=None and telemetry uses relative ordinals; explicit selection needs ZE_FLAT_DEVICE_HIERARCHY=COMPOSITE.
return {
"raw": None,
"numeric_ids": None,
diff --git a/tests/studio/test_xpu_spoof_pipeline.py b/tests/studio/test_xpu_spoof_pipeline.py
index 6d28f015b07..25918e3996c 100644
--- a/tests/studio/test_xpu_spoof_pipeline.py
+++ b/tests/studio/test_xpu_spoof_pipeline.py
@@ -141,6 +141,8 @@ def spoof_xpu(monkeypatch):
hw = _import_studio_hardware_module()
hw._visible_gpu_count = None
+ # Host-independent: no sysfs single-tile widening unless a test asks for it.
+ monkeypatch.setattr(hw, "_intel_xpu_single_tile_host", lambda: False)
return hw, calls
return _apply
@@ -432,6 +434,21 @@ def test_composite_numeric_mask_reports_physical_ids(spoof_xpu, monkeypatch):
assert [device["index"] for device in result["devices"]] == [4, 7]
+def test_unset_hierarchy_on_single_tile_cards_reports_physical_ids(spoof_xpu, monkeypatch):
+ """Arc / Flex cards have one tile, so the driver's default hierarchy addresses root GPUs."""
+ hw, _ = spoof_xpu(ze_mask = None, device_count = 2)
+ monkeypatch.setattr(hw, "_intel_xpu_single_tile_host", lambda: True)
+ hw.detect_hardware()
+ monkeypatch.setattr(hw, "get_physical_gpu_count", lambda: 2)
+
+ spec = hw._get_parent_visible_gpu_spec()
+ assert spec["numeric_ids"] == [0, 1]
+ assert spec["supports_explicit_gpu_ids"] is True
+
+ monkeypatch.setenv("ZE_FLAT_DEVICE_HIERARCHY", "FLAT")
+ assert hw._get_parent_visible_gpu_spec()["supports_explicit_gpu_ids"] is False
+
+
def test_get_device_map_multi_is_balanced(spoof_xpu):
hw, _ = spoof_xpu(ze_mask = "0,1", device_count = 2)
hw.detect_hardware()