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: skip the Xet probe's GPU-init-off zoo retry on GPU hosts (#12478)

Srijan Keshri33515a2cd2ad
diff --git a/studio/backend/tests/test_hf_xet_fallback.py b/studio/backend/tests/test_hf_xet_fallback.py
index 04115c01982..6c4ca66696e 100644
--- a/studio/backend/tests/test_hf_xet_fallback.py
+++ b/studio/backend/tests/test_hf_xet_fallback.py
@@ -385,6 +385,131 @@ def test_no_light_gpu_init_retry_on_an_accelerator_host(monkeypatch):
sys.modules["utils.hf_xet_fallback"] = saved_shim
[email protected]("backend, expected", [("cuda", True), ("xpu", True), ("mps", False)])
+def test_gpu_present_ignores_mps(monkeypatch, backend, expected):
+ """An MPS-only Mac without MLX has no real triton to shadow and needs the light-init retry."""
+ probe = lambda name: _types.SimpleNamespace(is_available = lambda: name == backend)
+ fake_torch = _types.ModuleType("torch")
+ fake_torch.cuda, fake_torch.xpu = probe("cuda"), probe("xpu")
+ fake_torch.backends = _types.SimpleNamespace(mps = probe("mps"))
+ monkeypatch.setitem(sys.modules, "torch", fake_torch)
+ assert shim._gpu_present() is expected
+
+
+def test_optional_loader_does_not_retry_under_light_gpu_init_on_an_accelerator_host(monkeypatch):
+ """xet_health()'s retry under UNSLOTH_ZOO_DISABLE_GPU_INIT=1 leaves zoo's pass-through triton stub in sys.modules,
+ breaking xformers ("'function' object has no attribute 'fn'"); like _load_shared it must not retry on a GPU host."""
+ monkeypatch.delenv("UNSLOTH_ZOO_DISABLE_GPU_INIT", raising = False)
+ real_triton = _types.ModuleType("triton")
+ monkeypatch.setitem(sys.modules, "triton", real_triton)
+ monkeypatch.setattr(shim, "_gpu_present", lambda: True)
+ monkeypatch.delitem(sys.modules, "unsloth_zoo.hf_xet_health", raising = False)
+ shim._reset_optional_module_cache()
+ attempts = []
+
+ def _fake_import(name):
+ attempts.append(os.environ.get("UNSLOTH_ZOO_DISABLE_GPU_INIT"))
+ if os.environ.get("UNSLOTH_ZOO_DISABLE_GPU_INIT") == "1":
+ sys.modules["triton"] = _types.ModuleType("unsloth_zoo_triton_stub")
+ return _types.ModuleType(name)
+ raise NotImplementedError("Unsloth cannot find any torch accelerator")
+
+ monkeypatch.setattr(importlib, "import_module", _fake_import)
+ try:
+ assert shim.xet_health() is None
+ assert shim.xet_health() is None
+ assert attempts == [None], attempts
+ assert sys.modules["triton"] is real_triton
+ assert os.environ.get("UNSLOTH_ZOO_DISABLE_GPU_INIT") is None
+ finally:
+ shim._reset_optional_module_cache()
+
+
+def test_optional_loader_keeps_a_submodule_a_late_zoo_init_failure_left_loaded(monkeypatch):
+ """A late zoo __init__ failure leaves hf_xet_tuning loaded: reuse it; a submodule it never reached stays None."""
+ monkeypatch.delenv("UNSLOTH_ZOO_DISABLE_GPU_INIT", raising = False)
+ monkeypatch.setattr(shim, "_gpu_present", lambda: True)
+ monkeypatch.delitem(sys.modules, "unsloth_zoo.hf_xet_health", raising = False)
+ survivor = _types.ModuleType("unsloth_zoo.hf_xet_tuning")
+ shim._reset_optional_module_cache()
+ attempts = []
+
+ def _late_failure(name):
+ attempts.append((name, os.environ.get("UNSLOTH_ZOO_DISABLE_GPU_INIT")))
+ sys.modules["unsloth_zoo.hf_xet_tuning"] = survivor
+ raise RuntimeError("unsloth_zoo GPU init failed after importing hf_xet_tuning")
+
+ # setitem + delitem: start absent; teardown restores the original (or nothing) over the survivor.
+ monkeypatch.setitem(sys.modules, "unsloth_zoo.hf_xet_tuning", None)
+ monkeypatch.delitem(sys.modules, "unsloth_zoo.hf_xet_tuning")
+ monkeypatch.setattr(importlib, "import_module", _late_failure)
+ try:
+ assert shim._load_optional("unsloth_zoo.hf_xet_tuning") is survivor
+ assert shim._load_optional("unsloth_zoo.hf_xet_tuning") is survivor
+ assert shim._load_optional("unsloth_zoo.hf_xet_health") is None
+ assert attempts == [
+ ("unsloth_zoo.hf_xet_tuning", None),
+ ("unsloth_zoo.hf_xet_health", None),
+ ], attempts
+ assert os.environ.get("UNSLOTH_ZOO_DISABLE_GPU_INIT") is None
+ shim._reset_optional_module_cache()
+ survivor.__spec__ = importlib.machinery.ModuleSpec("unsloth_zoo.hf_xet_tuning", None)
+ survivor.__spec__._initializing = True
+ assert shim._load_optional("unsloth_zoo.hf_xet_tuning") is None
+ finally:
+ shim._reset_optional_module_cache()
+
+
+_XET_ENV_SWITCHES = (
+ "UNSLOTH_DISABLE_XET",
+ "UNSLOTH_STABLE_DOWNLOADS",
+ "HF_HUB_DISABLE_XET",
+ "UNSLOTH_FORCE_XET",
+)
+
+
+ "env",
+ [
+ {},
+ {"HF_HUB_DISABLE_XET": "1"},
+ {"UNSLOTH_DISABLE_XET": "true"},
+ {"UNSLOTH_STABLE_DOWNLOADS": "on"},
+ {"UNSLOTH_FORCE_XET": "1"},
+ {"UNSLOTH_FORCE_XET": "1", "HF_HUB_DISABLE_XET": "yes"},
+ {"HF_HUB_DISABLE_XET": "0"},
+ ],
+)
+def test_operator_xet_switches_survive_a_missing_health_module(monkeypatch, env):
+ """With hf_xet_health unloadable, the operator's env switches still decide (else the worker gets HF_HUB_DISABLE_XET=0)."""
+ for name in _XET_ENV_SWITCHES:
+ monkeypatch.delenv(name, raising = False)
+ for name, value in env.items():
+ monkeypatch.setenv(name, value)
+ monkeypatch.setattr(shim, "_load_optional", lambda name: None)
+ monkeypatch.setitem(shim._optional_modules, "unsloth_zoo.hf_xet_health", None)
+ got, cached = shim.xet_health(), shim.cached_xet_health()
+ switched = any(value.lower() in ("1", "true", "yes", "on") for value in env.values())
+ assert (got is not None) is switched and (cached is not None) is switched
+
+ # Expected verdicts come from the installed zoo, not restated here.
+ real = pytest.importorskip("unsloth_zoo.hf_xet_health")
+ if not hasattr(real, "XetHealth"):
+ pytest.skip("installed unsloth_zoo predates XetHealth")
+ expected = real.xet_health(probe = False)
+ if expected.source != "forced":
+ assert got is None and cached is None
+ return
+ for verdict in (got, cached):
+ assert (verdict.use_xet, verdict.reason, verdict.source) == (
+ expected.use_xet,
+ expected.reason,
+ expected.source,
+ )
+ assert bool(verdict) is bool(expected)
+ assert shim.xet_health_is_forced(verdict)
+
+
def test_retries_under_light_gpu_init_when_import_fails(monkeypatch):
"""GPU detection in unsloth_zoo's __init__ raises NotImplementedError on a GPU-less host. The shim
retries under UNSLOTH_ZOO_DISABLE_GPU_INIT=1, restores the env, and degrades if the retry fails.
diff --git a/studio/backend/tests/test_hub_download_transport_auto.py b/studio/backend/tests/test_hub_download_transport_auto.py
index 90d89b532e8..7bfc1f1288c 100644
--- a/studio/backend/tests/test_hub_download_transport_auto.py
+++ b/studio/backend/tests/test_hub_download_transport_auto.py
@@ -415,6 +415,7 @@ def test_optional_loader_retries_with_gpu_init_disabled(monkeypatch):
monkeypatch.setattr(importlib, "import_module", _fake_import)
monkeypatch.delenv("UNSLOTH_ZOO_DISABLE_GPU_INIT", raising = False)
+ monkeypatch.setattr(shim, "_gpu_present", lambda: False)
assert shim._load_optional("unsloth_zoo.hf_xet_tuning") is sentinel
assert attempts == [None, "1"]
@@ -428,6 +429,8 @@ def test_optional_loader_returns_none_when_truly_absent(monkeypatch):
raise ModuleNotFoundError(name)
monkeypatch.setattr(importlib, "import_module", _always_fail)
+ for name in ("unsloth_zoo.hf_xet_tuning", "unsloth_zoo.hf_xet_health"):
+ monkeypatch.delitem(sys.modules, name, raising = False)
assert shim._load_optional("unsloth_zoo.hf_xet_tuning") is None
# A missing module means "no opinion", never a hard failure.
assert shim.xet_env_overrides() == {}
@@ -508,6 +511,7 @@ def test_gpu_init_override_is_serialized(monkeypatch):
raise ModuleNotFoundError(name)
monkeypatch.setattr(importlib, "import_module", _always_fail)
+ monkeypatch.setattr(shim, "_gpu_present", lambda: False)
threads = [
threading.Thread(target = shim._load_optional, args = ("unsloth_zoo.hf_xet_tuning",))
diff --git a/studio/backend/utils/hf_xet_fallback.py b/studio/backend/utils/hf_xet_fallback.py
index 0daa72fac5f..e899b51c221 100644
--- a/studio/backend/utils/hf_xet_fallback.py
+++ b/studio/backend/utils/hf_xet_fallback.py
@@ -23,6 +23,7 @@ from __future__ import annotations
import os
import threading
import time
+from dataclasses import dataclass
from functools import partial
from pathlib import Path
from typing import Any, Callable, Optional
@@ -56,6 +57,7 @@ def _gpu_present() -> bool:
Only torch is consulted (already imported by the time any download helper runs), and any
failure answers False so a genuinely torch-less host keeps the light-init retry below.
+ MPS does not count: unsloth_zoo's full init rejects it, so the light path is the only one there.
"""
try:
import torch
@@ -63,7 +65,6 @@ def _gpu_present() -> bool:
return False
for probe in (
lambda: torch.cuda.is_available(),
- lambda: torch.backends.mps.is_available(),
lambda: torch.xpu.is_available(),
):
try:
@@ -108,7 +109,7 @@ def _load_shared() -> bool:
_shared_import_error = exc
import os as _os
- # ...but ONLY on a host that really has no accelerator. That flag makes unsloth_zoo take its MLX/CPU path,
+ # ...but NOT on a CUDA/XPU host (see _gpu_present). That flag makes unsloth_zoo take its MLX/CPU path,
# injecting triton and bitsandbytes STUBS into sys.modules for the process. On a working GPU box those stubs
# raise from the first CUDA-only kernel, turning a healthy GPU into 500s.
if _gpu_present():
@@ -201,6 +202,25 @@ def _load_optional(module_name: str) -> Any:
cached = _optional_modules.get(module_name, _UNTRIED)
if cached is not _UNTRIED:
return cached
+ # Same rule as _load_shared: the retry's triton/bitsandbytes stubs stay in sys.modules for good.
+ if _gpu_present():
+ import sys as _sys
+
+ # A zoo __init__ failing late leaves the submodules it already ran (hf_xet_tuning) in sys.modules.
+ module = _sys.modules.get(module_name)
+ # Still executing in another thread: never memoise a half-built module.
+ if getattr(getattr(module, "__spec__", None), "_initializing", False):
+ module = None
+ if module is None:
+ import logging as _logging
+ _logging.getLogger(__name__).warning(
+ "%s unavailable (%s); not retrying under UNSLOTH_ZOO_DISABLE_GPU_INIT because this host has an "
+ "accelerator and that path would stub out triton/bitsandbytes for the whole process.",
+ module_name,
+ first_error,
+ )
+ _optional_modules[module_name] = module
+ return module
global _gpu_init_override_depth
previous = _os.environ.get("UNSLOTH_ZOO_DISABLE_GPU_INIT")
ours = previous != "1"
@@ -227,9 +247,33 @@ def _load_optional(module_name: str) -> Any:
return module
+@dataclass(frozen = True)
+class _EnvXetHealth:
+ use_xet: bool
+ reason: str
+ source: str = "forced"
+
+ def __bool__(self) -> bool:
+ return self.use_xet
+
+
+def _env_xet_health() -> Any:
+ """The env checks atop ``unsloth_zoo.hf_xet_health.xet_health``, for when that module cannot load: without
+ them Auto picks Xet and the worker gets ``HF_HUB_DISABLE_XET=0`` over the operator's ``1``."""
+
+ def _on(name: str) -> bool:
+ return os.environ.get(name, "").strip().lower() in ("1", "true", "yes", "on")
+
+ if _on("UNSLOTH_DISABLE_XET") or _on("UNSLOTH_STABLE_DOWNLOADS") or _on("HF_HUB_DISABLE_XET"):
+ return _EnvXetHealth(False, "Xet disabled by environment")
+ if _on("UNSLOTH_FORCE_XET"):
+ return _EnvXetHealth(True, "Xet forced by environment")
+ return None
+
+
def _xet_health_from(module: Any, **kwargs: Any) -> Any:
if module is None:
- return None
+ return _env_xet_health()
try:
return module.xet_health(**kwargs)
except Exception as exc: # noqa: BLE001