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: 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.pynew file mode 100644index 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 Truediff --git a/studio/backend/utils/hardware/hardware.py b/studio/backend/utils/hardware/hardware.pyindex 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.pyindex 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, callsreturn _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()