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: SageAttention 2 from the kernels hub, and FlashAttention 4 dependencies that load on a fresh install (#12654)

Daniel Han766a7ca4e90f
diff --git a/studio/backend/core/inference/diffusion_attention.py b/studio/backend/core/inference/diffusion_attention.py
index e3361b21e03..b0ca92cd697 100644
--- a/studio/backend/core/inference/diffusion_attention.py
+++ b/studio/backend/core/inference/diffusion_attention.py
@@ -21,7 +21,8 @@ Attention is bandwidth-bound, so a better kernel is a real win orthogonal to wei
native - force the default SDPA (bit-identical reference).
cudnn - cuDNN fused attention (exact; NVIDIA).
flash / flash3 / flash4 - FlashAttention 2 / 3 (Hopper) / 4 (SM100); exact, kernel-gated.
- sage - SageAttention (INT8 QK); quantized, small quality cost, consumer-friendly.
+ sage - SageAttention 2 (INT8 QK); quantized, small quality cost. A pip SageAttention 2 when installed, else the
+ kernels-community build from the Hugging Face kernels hub (``sage_hub``, Ampere / Ada / Hopper).
xformers / aiter - memory-efficient (NVIDIA) / AITER (AMD ROCm).
Best-effort: an unavailable backend falls back to the diffusers default. torch/diffusers lazy.
@@ -299,12 +300,16 @@ def _run_sage_probe(
device: str,
dtype: Any,
head_dim: int = 128,
+ sageattn: Any = None,
) -> str:
"""Empty when ``sageattn`` matches fp32 SDPA at ``head_dim``, else why not. Raises when unaskable (import, OOM).
- Random inputs with a per-channel K offset like real keys: a zero tensor proves the launch, not the numbers."""
+ ``sageattn`` defaults to the pip package's. Random inputs with a per-channel K offset like real keys: a zero tensor
+ proves the launch, not the numbers."""
import torch
- from sageattention import sageattn
+
+ if sageattn is None:
+ from sageattention import sageattn
if dtype not in (torch.float16, torch.bfloat16):
dtype = torch.float16
@@ -467,23 +472,26 @@ def _note_sage_reroute(reason: str) -> None:
# sageattn() reads the arch via torch.cuda calls Dynamo cannot trace, so a fullgraph compile failed and the load ran
# eager. An opaque custom op keeps the block compiled.
_SAGE_OP_NAME = "unsloth_studio::sage_attention_nhd"
-_SAGE_OP: dict[str, Any] = {}
+# Own op for the hub build, so a pip SageAttention 2 installed later never runs through it.
+_SAGE_HUB_OP_NAME = "unsloth_studio::sage_hub_attention_nhd"
+_SAGE_OPS: dict[str, dict[str, Any]] = {}
_SAGE_OP_LOCK = threading.Lock()
-def _sage_custom_op(sage_fn: Any) -> Optional[Any]:
+def _sage_custom_op(sage_fn: Any, op_name: str = _SAGE_OP_NAME) -> Optional[Any]:
"""An opaque ``torch.library`` op around diffusers' sage function (NHD), or None."""
with _SAGE_OP_LOCK:
- if "op" in _SAGE_OP:
- _SAGE_OP["fn"] = sage_fn
- return _SAGE_OP["op"]
+ slot = _SAGE_OPS.setdefault(op_name, {})
+ if "op" in slot:
+ slot["fn"] = sage_fn
+ return slot["op"]
try:
import torch
- _SAGE_OP["fn"] = sage_fn
+ slot["fn"] = sage_fn
def _impl(query, key, value, is_causal, scale):
- out = _SAGE_OP["fn"](
+ out = slot["fn"](
query = query, key = key, value = value, is_causal = is_causal, scale = scale
)
# Head dims under 64 come back as a padded slice; the fake describes a contiguous tensor.
@@ -498,16 +506,16 @@ def _sage_custom_op(sage_fn: Any) -> Optional[Any]:
"scale": Optional[float],
"return": torch.Tensor,
}
- _op = torch.library.custom_op(_SAGE_OP_NAME, mutates_args = ())(_impl)
+ _op = torch.library.custom_op(op_name, mutates_args = ())(_impl)
@_op.register_fake
def _(query, key, value, is_causal, scale):
return query.new_empty((*query.shape[:-1], value.shape[-1]))
- _SAGE_OP["op"] = _op
+ slot["op"] = _op
except Exception: # noqa: BLE001 - old torch: call the function directly
- _SAGE_OP["op"] = None
- return _SAGE_OP["op"]
+ slot["op"] = None
+ return slot["op"]
def _install_dispatch_guard(
@@ -769,10 +777,377 @@ def _sage_usable(
return True
+# PyPI has no SageAttention 2 (only 1.0.6, which diffusers refuses), so ``sage`` without a pip SageAttention 2 runs the
+# kernels-hub build (sm80 / 89 / 90) via diffusers' ``sage_hub``. diffusers 0.40 asks for version 1 builds, which stop
+# at torch 2.10, so version 2 (torch 2.9 to 2.12) is fetched first.
+SAGE_HUB_BACKEND = "sage_hub"
+_SAGE_HUB_REPO = "kernels-community/sage-attention"
+_SAGE_HUB_VERSIONS = (2, 1)
+_SAGE_HUB_PROBE_CACHE: dict[tuple[str, str, int], str] = {}
+_SAGE_HUB_LOCK = threading.Lock()
+# A failed fetch, remembered so the in-lock apply does not repeat it. Cleared by a restart, like _INSTALL_ATTEMPTED.
+_SAGE_HUB_FAILED: list[str] = []
+SAGE_SOURCE_HINT = (
+ "SageAttention 2 is not published on PyPI (pip only has SageAttention 1.0.6), so on this platform it needs a "
+ "source build or a community wheel"
+)
+
+
+def _pip_sage2_installed() -> bool:
+ try:
+ from importlib.metadata import PackageNotFoundError, version
+ try:
+ installed = version("sageattention")
+ except PackageNotFoundError:
+ return False
+ except Exception: # noqa: BLE001
+ return False
+ return bool(_version_tuple(installed)) and _sage_version_too_old() is None
+
+
+def _load_sage_hub_kernel() -> tuple[Any, str]:
+ """``(sageattn, "")`` from the hub build, set in diffusers' ``sage_hub`` slot, or ``(None, why)``. Never raises."""
+ with _SAGE_HUB_LOCK:
+ try:
+ from diffusers.models.attention_dispatch import (
+ _HUB_KERNELS_REGISTRY,
+ AttentionBackendName,
+ )
+ config = _HUB_KERNELS_REGISTRY[AttentionBackendName(SAGE_HUB_BACKEND)]
+ except Exception as exc: # noqa: BLE001
+ return None, f"this diffusers build has no sage_hub backend ({type(exc).__name__})"
+ if callable(getattr(config, "kernel_fn", None)):
+ return config.kernel_fn, ""
+ if _SAGE_HUB_FAILED:
+ return None, _SAGE_HUB_FAILED[0]
+ try:
+ from kernels import get_kernel
+ except Exception as exc: # noqa: BLE001
+ return None, f"the kernels package is not importable ({type(exc).__name__}: {exc})"
+ errors = []
+ versions = list(_SAGE_HUB_VERSIONS)
+ default = getattr(config, "version", None)
+ if isinstance(default, int) and default not in versions:
+ versions.append(default)
+ for ver in versions:
+ try:
+ fn = getattr(get_kernel(_SAGE_HUB_REPO, version = ver), "sageattn", None)
+ except Exception as exc: # noqa: BLE001
+ errors.append(f"version {ver}: {type(exc).__name__}: {str(exc)[:200]}")
+ continue
+ if callable(fn):
+ config.kernel_fn = fn
+ return fn, ""
+ errors.append(f"version {ver}: no sageattn in the build")
+ _SAGE_HUB_FAILED.append(f"no {_SAGE_HUB_REPO} build loads here ({'; '.join(errors)})")
+ return None, _SAGE_HUB_FAILED[0]
+
+
+def _sage_hub_kernel_runs(
+ target: Any,
+ sageattn: Any,
+ head_dims: Any = None,
+) -> tuple[Optional[bool], str]:
+ """``(True, "")`` when the hub ``sageattn`` passed at every head dim, ``(False, why)``, or ``(None, "")`` unaskable."""
+ device = str(getattr(target, "torch_device", None) or getattr(target, "device", None) or "")
+ if not device.startswith("cuda"):
+ return None, ""
+ device = _indexed_cuda_device(device)
+ dtype = getattr(target, "dtype", None)
+ for head_dim in _sage_probe_head_dims(head_dims):
+ key = (device, str(dtype), head_dim)
+ error = _SAGE_HUB_PROBE_CACHE.get(key)
+ if error is None:
+ try:
+ error = _run_sage_probe(device, dtype, head_dim, sageattn = sageattn)
+ except Exception: # noqa: BLE001
+ return None, ""
+ error = _SAGE_HUB_PROBE_CACHE.setdefault(key, error)
+ if error:
+ return False, error
+ return True, ""
+
+
+def _install_sage_hub_dispatch_guard() -> bool:
+ return _install_dispatch_guard(
+ SAGE_HUB_BACKEND,
+ lambda *a: _sage_reroute_reason(*a),
+ _note_sage_reroute,
+ lambda fn: _sage_custom_op(fn, _SAGE_HUB_OP_NAME),
+ )
+
+
+def _sage_hub_backend(
+ pipe: Any,
+ target: Any,
+ logger: Any = None,
+) -> Optional[str]:
+ """``sage_hub`` when the hub build passes its self-check here (before any DiT is switched), else None, logged."""
+
+ def _decline(why: str) -> None:
+ if logger is not None:
+ logger.warning(
+ "diffusion.attention: SageAttention unavailable: %s. %s. Using the default backend",
+ why,
+ SAGE_SOURCE_HINT,
+ )
+
+ if target is not None and _runs_in_float32(target):
+ if logger is not None:
+ logger.warning(
+ "diffusion.attention: SageAttention needs fp16 or bf16 and this pipeline runs in float32; "
+ "using the default backend"
+ )
+ return None
+ head_dims = _dit_head_dims(pipe)
+ if head_dims and min(head_dims) > _SAGE_MAX_HEAD_DIM:
+ if logger is not None:
+ logger.warning(
+ "diffusion.attention: SageAttention serves head_dim <= %d and this model uses %s; "
+ "using the default backend",
+ _SAGE_MAX_HEAD_DIM,
+ ",".join(str(d) for d in sorted(head_dims)),
+ )
+ return None
+ sageattn, why = _load_sage_hub_kernel()
+ if sageattn is None:
+ _decline(f"the Hugging Face kernels-hub build could not be loaded ({why})")
+ return None
+ if target is not None:
+ runs, why = _sage_hub_kernel_runs(target, sageattn, head_dims)
+ if runs is False:
+ _decline(
+ f"the Hugging Face kernels-hub build does not run correctly on this GPU ({why})"
+ )
+ return None
+ if not _install_sage_hub_dispatch_guard():
+ if logger is not None:
+ logger.warning(
+ "diffusion.attention: this diffusers build does not expose the sage_hub backend the way Unsloth "
+ "expects, so masked attention calls could not be routed around it; using the default backend"
+ )
+ return None
+ if logger is not None:
+ logger.info(
+ "diffusion.attention: SageAttention 2 from the Hugging Face kernels hub (%s) passed its self-check",
+ _SAGE_HUB_REPO,
+ )
+ return SAGE_HUB_BACKEND
+
+
+# Only cutlass-dsl 4.4 / 4.5 load the hub FA4 build (4.6+ lacks cute.core.ThrMma, 4.3 PipelineClcFetchAsync).
+FA4_CUTLASS_DSL_MIN = (4, 4)
+FA4_CUTLASS_DSL_MAX_EXCL = (4, 6)
+FA4_CUTLASS_DSL_SPEC = "nvidia-cutlass-dsl>=4.4,<4.6"
+FA4_TVM_FFI_SPEC = "apache-tvm-ffi>=0.1.6,<0.2,!=0.1.8,!=0.1.8.post0"
+FA4_KERNELS_MIN = (0, 12, 3)
+FA4_KERNELS_SPEC = "kernels==0.12.3"
+
+
+def _dist_version(name: str) -> Optional[str]:
+ try:
+ from importlib.metadata import PackageNotFoundError, version
+ try:
+ return version(name)
+ except PackageNotFoundError:
+ return None
+ except Exception: # noqa: BLE001
+ return None
+
+
+def fa4_cutlass_dsl_ok(installed: Optional[str]) -> bool:
+ have = _version_tuple(installed or "")[:2]
+ return bool(have) and FA4_CUTLASS_DSL_MIN <= have < FA4_CUTLASS_DSL_MAX_EXCL
+
+
+def _cutlass_dsl_dependents() -> list[str]:
+ found = []
+ try:
+ from importlib.metadata import distributions
+ for dist in distributions():
+ for req in dist.requires or ():
+ head = (
+ re.split(r"[\s;\[<>=!~]", req.strip(), maxsplit = 1)[0].lower().replace("_", "-")
+ )
+ if head == "nvidia-cutlass-dsl" and "extra ==" not in req:
+ found.append(
+ f"{dist.metadata['Name']} {dist.version} ({req.split(';')[0].strip()})"
+ )
+ break
+ except Exception: # noqa: BLE001
+ pass
+ return sorted(set(found))
+
+
+def _fa4_python_deps_plan() -> tuple[list[str], Optional[str]]:
+ """``(requirements, refusal)`` for the hub FA4 build. An out-of-range cutlass-dsl is never replaced (a user's quack
+ or a newer FlashInfer may need it): the request is refused instead."""
+ reqs: list[str] = []
+ kernels = _dist_version("kernels")
+ if (
+ kernels is not None
+ and _version_tuple(kernels)
+ and _version_tuple(kernels) < FA4_KERNELS_MIN
+ ):
+ # Same dependencies as 0.12.1, so --no-deps is safe.
+ reqs.append(FA4_KERNELS_SPEC)
+ cutlass = _dist_version("nvidia-cutlass-dsl")
+ if cutlass is None:
+ reqs.append(FA4_CUTLASS_DSL_SPEC)
+ elif not fa4_cutlass_dsl_ok(cutlass):
+ users = [d for d in _cutlass_dsl_dependents() if not d.lower().startswith("flash-attn")]
+ return [], (
+ f"FlashAttention 4 from the kernels hub loads only with nvidia-cutlass-dsl 4.4.x or 4.5.x and {cutlass} is "
+ "installed"
+ + (f" (required by {', '.join(users)})" if users else "")
+ + "; Unsloth does not replace it"
+ )
+ if _dist_version("apache-tvm-ffi") is None:
+ reqs.append(FA4_TVM_FFI_SPEC)
+ if _dist_version("einops") is None:
+ reqs.append("einops")
+ return reqs, None
+
+
+def _pinned_constraints_file() -> Optional[str]:
+ """Every installed distribution pinned, so a dependency install cannot move anything."""
+ try:
+ from .diffusion_nvfp4_install import _write_constraints, installed_distributions
+ return _write_constraints(installed_distributions())
+ except Exception: # noqa: BLE001
+ return None
+
+
+def _refresh_diffusers_kernels_version(logger: Any = None) -> None:
+ """diffusers reads the kernels version once at import and gates flash_4_hub on it: refresh it after an upgrade, only
+ while ``kernels`` is not imported yet (an imported old version runs until a restart)."""
+ import sys
+
+ if "kernels" in sys.modules:
+ if logger is not None:
+ logger.warning(
+ "diffusion.attention: kernels was upgraded to %s for FlashAttention 4 and takes effect after Studio "
+ "restarts; this load uses the default backend",
+ FA4_KERNELS_SPEC.split("==", 1)[1],
+ )
+ return
+ try:
+ from diffusers.utils import import_utils
+ installed = _dist_version("kernels")
+ if installed and getattr(import_utils, "_kernels_version", None) not in (None, installed):
+ import_utils._kernels_version = installed
+ import_utils._kernels_available = True
+ # diffusers memoizes is_kernels_version, so a check made before the upgrade would still answer False.
+ cache_clear = getattr(
+ getattr(import_utils, "is_kernels_version", None), "cache_clear", None
+ )
+ if callable(cache_clear):
+ cache_clear()
+ except Exception: # noqa: BLE001
+ pass
+
+
+# cutlass-dsl reaches sys.path through a .pth file (libs-base in 4.4 / 4.5, the main dist in 4.6+).
+_PTH_DISTRIBUTIONS = ("nvidia-cutlass-dsl-libs-base", "nvidia-cutlass-dsl")
+
+
+def _activate_installed_pth_files(names: tuple[str, ...] = _PTH_DISTRIBUTIONS) -> None:
+ """Run the .pth files of ``names`` now: the interpreter reads them only at startup."""
+ try:
+ import site
+ import sys
+ from importlib.metadata import PackageNotFoundError, distribution
+ except Exception: # noqa: BLE001
+ return
+ for name in names:
+ try:
+ dist = distribution(name)
+ except PackageNotFoundError:
+ continue
+ except Exception: # noqa: BLE001
+ continue
+ for entry in dist.files or ():
+ if not str(entry).endswith(".pth") or "/" in str(entry).replace("\\", "/"):
+ continue
+ try:
+ path = os.fspath(dist.locate_file(entry))
+ site.addpackage(os.path.dirname(path), os.path.basename(path), set(sys.path))
+ except Exception: # noqa: BLE001
+ continue
+
+
+def _ensure_fa4_python_deps(logger: Any = None) -> Optional[str]:
+ """Install the hub FA4 build's imports at versions it loads with. Returns the refusal reason, or None."""
+ import importlib
+ import subprocess
+ import sys
+
+ reqs, refusal = _fa4_python_deps_plan()
+ if refusal is not None:
+ if logger is not None:
+ logger.warning("diffusion.attention: %s; using the default backend", refusal)
+ return refusal
+ if not reqs:
+ # An NVFP4 FlashInfer install earlier in this process may have added cutlass-dsl without running its .pth.
+ _activate_installed_pth_files()
+ return None
+ key = "fa4-deps:" + ",".join(reqs)
+ if key in _INSTALL_ATTEMPTED:
+ return None
+ _INSTALL_ATTEMPTED.add(key)
+ kernels_upgrade = [r for r in reqs if r == FA4_KERNELS_SPEC]
+ deps = [r for r in reqs if r != FA4_KERNELS_SPEC]
+ if logger is not None:
+ logger.info(
+ "diffusion.attention: installing %s for backend=flash_4_hub (wheel-only)",
+ ", ".join(reqs),
+ )
+ base = [
+ sys.executable,
+ "-m",
+ "pip",
+ "install",
+ "--disable-pip-version-check",
+ "--only-binary",
+ ":all:",
+ ]
+ constraints = _pinned_constraints_file() if deps else None
+ try:
+ if kernels_upgrade:
+ subprocess.run(
+ base + ["--no-deps", *kernels_upgrade], capture_output = True, timeout = 600, check = True
+ )
+ _refresh_diffusers_kernels_version(logger)
+ if deps:
+ # Resolved (cutlass-dsl needs its libs and cuda-python); the constraints add only new packages.
+ cmd = base + (["-c", constraints] if constraints else []) + deps
+ subprocess.run(cmd, capture_output = True, timeout = 600, check = True)
+ importlib.invalidate_caches()
+ _activate_installed_pth_files()
+ except Exception as exc: # noqa: BLE001 - FA4 then falls back at set time
+ if logger is not None:
+ stderr = getattr(exc, "stderr", None)
+ if isinstance(stderr, bytes):
+ stderr = stderr.decode("utf-8", errors = "replace")
+ logger.warning(
+ "diffusion.attention: could not install %s for FlashAttention 4: %s",
+ ", ".join(reqs),
+ _redacted_for_log((stderr or "").strip()[-1500:]) or _redacted_for_log(str(exc)),
+ )
+ finally:
+ if constraints:
+ try:
+ os.unlink(constraints)
+ except OSError:
+ pass
+ return None
+
+
# Optional kernels installable on demand: dispatcher name -> (probe module, pip package). Wheels only
# (--only-binary=:all:), since a source build needs a CUDA toolchain the host may lack.
_INSTALLABLE_BACKENDS: dict[str, tuple[str, str]] = {
- "sage": ("sageattention", "sageattention>=2.1.1"),
+ # Never ``sageattention`` from PyPI (only SageAttention 1 there): the hub build is the installable one.
+ "sage": ("kernels", "kernels"),
"flash": ("flash_attn", "flash-attn"),
"_flash_3_hub": ("kernels", "kernels"), # FA3/FA4 from the HF kernels hub
"flash_4_hub": ("kernels", "kernels"),
@@ -873,25 +1248,6 @@ def _xformers_wheel_target() -> tuple[Optional[str], Optional[str]]:
return target
-def _pip_requirement(backend: str, package: str) -> str:
- """Requirement to hand pip, carrying any floor the dispatcher enforces at set time.
-
- PyPI's newest ``sageattention`` wheel is 1.0.6 while diffusers refuses anything below
- ``_REQUIRED_SAGE_VERSION`` (2.1.1) — an unpinned install therefore always "succeeds", writes
- an unusable 1.0.6 into the running venv, and is then rejected with "the version is too old".
- Pinning makes pip resolve nothing instead of installing something we will not use. Re-read the
- floor from diffusers so a future bump tracks automatically."""
- if backend != "sage":
- return package
- try:
- from diffusers.models.attention_dispatch import _REQUIRED_SAGE_VERSION as floor
- if isinstance(floor, str) and floor.strip():
- return f"sageattention>={floor.strip()}"
- except Exception: # noqa: BLE001 - older/newer diffusers may not expose it; keep the static pin
- pass
- return package
-
-
# The huggingface_hub floor the current `kernels` wheels declare (kernels >= 0.14.1 requires huggingface-hub >= 1.10.0).
# A (major, minor) pair, compared against the resident hub below.
_KERNELS_HUB_FLOOR = (1, 10)
@@ -926,6 +1282,34 @@ def _kernels_hub_compatible() -> bool:
def _ensure_attention_backend_installed(backend: str, logger: Any = None) -> Optional[str]:
+ """Best-effort install of ``backend``'s package, plus the hub FA4 build's dependencies for ``flash_4_hub``. Returns
+ the refusal reason, or None; see ``_ensure_backend_package``."""
+ if backend == "sage" and _pip_sage2_installed():
+ return None
+ reason = _ensure_backend_package(backend, logger)
+ if reason is not None or backend not in ("flash_4_hub", "sage"):
+ return reason
+ if os.environ.get(_ATTENTION_INSTALL_ENV, "auto").strip().lower() in (
+ "0",
+ "false",
+ "no",
+ "off",
+ ):
+ return None
+ try:
+ import importlib.util
+ if importlib.util.find_spec("kernels") is None:
+ return None
+ except Exception: # noqa: BLE001
+ return None
+ if backend == "sage":
+ # Fetched here, outside the loader's locks; apply finds it in diffusers' registry.
+ _load_sage_hub_kernel()
+ return None
+ return _ensure_fa4_python_deps(logger)
+
+
+def _ensure_backend_package(backend: str, logger: Any = None) -> Optional[str]:
"""Best-effort wheel-only install of the package ``backend`` needs, when allowed.
Called after arch gating, so only for a backend that could work here. Failure is swallowed: the
@@ -945,7 +1329,6 @@ def _ensure_attention_backend_installed(backend: str, logger: Any = None) -> Opt
if spec is None:
return None
module, package = spec
- package = _pip_requirement(backend, package)
gate = os.environ.get(_ATTENTION_INSTALL_ENV, "auto").strip().lower()
if gate in ("0", "false", "no", "off"):
return None
@@ -962,8 +1345,8 @@ def _ensure_attention_backend_installed(backend: str, logger: Any = None) -> Opt
)
return reason
# Refusing is a POLICY decision, not a failed attempt, so it is checked before the _INSTALL_ATTEMPTED memo below and
- # records nothing: a later request on a fixed environment must still be able to install. Scoped to kernels; the sage
- # / flash-attn / xformers wheels do not import huggingface_hub at module scope.
+ # records nothing: a later request on a fixed environment must still be able to install. Scoped to kernels (which
+ # sage and flash3 / flash4 install); the flash-attn / xformers wheels do not import huggingface_hub at module scope.
if package == "kernels" and not _kernels_hub_compatible():
if logger is not None:
logger.warning(
@@ -1043,6 +1426,8 @@ def _ensure_attention_backend_installed(backend: str, logger: Any = None) -> Opt
# The import system caches directory listings, so invalidate the finder caches or the next find_spec can miss
# the new wheel.
importlib.invalidate_caches()
+ if package == "kernels":
+ _refresh_diffusers_kernels_version(logger)
except Exception as exc: # noqa: BLE001 - no wheel / no network -> native fallback
if logger is not None:
# CalledProcessError.str() shows only the exit code; surface stderr so the fallback is diagnosable.
@@ -1217,8 +1602,15 @@ def apply_attention_backend(
return None
if backend is not None:
_ensure_attention_backend_installed(backend, logger)
- if backend == "sage" and not _sage_usable(pipe, target, logger):
- backend = None
+ if backend == "sage":
+ if _pip_sage2_installed():
+ if not _sage_usable(pipe, target, logger):
+ backend = None
+ else:
+ too_old = _sage_version_too_old()
+ if too_old and logger is not None:
+ logger.info("diffusion.attention: ignoring %s", too_old)
+ backend = _sage_hub_backend(pipe, target, logger)
if (
backend == "_native_cudnn"
and target is not None
diff --git a/studio/backend/core/inference/diffusion_cuda_graph.py b/studio/backend/core/inference/diffusion_cuda_graph.py
index 94db1fece10..dd45ad299a5 100644
--- a/studio/backend/core/inference/diffusion_cuda_graph.py
+++ b/studio/backend/core/inference/diffusion_cuda_graph.py
@@ -672,8 +672,11 @@ def graph_eligible(
if not _denoiser_dits(pipe) and _denoiser_unet(pipe) is None:
return False, "no denoiser transformer"
- # Sage under a replayed graph renders noise (FLUX.1-schnell, A100), while the ungraphed render is correct.
- if any(getattr(m, "_unsloth_attention_backend", None) == "sage" for m in _denoiser_dits(pipe)):
+ # Sage (pip or hub build) under a replayed graph renders noise (FLUX.1-schnell, A100); ungraphed is correct.
+ if any(
+ getattr(m, "_unsloth_attention_backend", None) in ("sage", "sage_hub")
+ for m in _denoiser_dits(pipe)
+ ):
return False, "SageAttention is not CUDA-graph safe"
try:
diff --git a/studio/backend/core/inference/diffusion_nvfp4_install.py b/studio/backend/core/inference/diffusion_nvfp4_install.py
index a626dd25711..9c51c1c07eb 100644
--- a/studio/backend/core/inference/diffusion_nvfp4_install.py
+++ b/studio/backend/core/inference/diffusion_nvfp4_install.py
@@ -659,6 +659,11 @@ def _pinnable(dists: dict[str, str]) -> dict[str, str]:
return pins
+# An unconstrained FlashInfer resolve lands cutlass-dsl 4.8, which the hub FA4 build cannot load: hold a fresh install to
+# the range both load with.
+_CUTLASS_DSL_CONSTRAINT = "nvidia-cutlass-dsl>=4.4,<4.6"
+
+
def _write_constraints(pins: dict[str, str]) -> str:
"""Every installed distribution at its exact version (see ``_pinnable``)."""
lines = [f"{name}=={version}\n" for name, version in sorted(_pinnable(pins).items())]
@@ -918,6 +923,12 @@ def _install(
before = installed_distributions()
constraints = _write_constraints(before)
+ if "nvidia-cutlass-dsl" not in before:
+ try:
+ with open(constraints, "a", encoding = "utf-8") as fh:
+ fh.write(_CUTLASS_DSL_CONSTRAINT + "\n")
+ except OSError:
+ pass
size_hint = " (about 1.5 GB of prebuilt kernels)" if tag else ""
_emit(
logger,
diff --git a/studio/backend/requirements/extras-no-deps.txt b/studio/backend/requirements/extras-no-deps.txt
index 1b61721f43e..9cfe8645710 100644
--- a/studio/backend/requirements/extras-no-deps.txt
+++ b/studio/backend/requirements/extras-no-deps.txt
@@ -41,7 +41,8 @@ transformers==4.57.6; python_version < "3.10"
# this file is written to avoid. The cap keeps the resolver's fallback while
# bounding it at the newest audited release.
pytorch_tokenizers<=1.4.1; sys_platform != "darwin" or platform_machine == "arm64"
-kernels==0.12.1
+# 0.12.3: diffusers flash_4_hub refuses older kernels; same dependencies as 0.12.1.
+kernels==0.12.3
# kernels<3.11 imports tomli as its tomllib fallback; --no-deps skips its own
# marker dep, so list it here (no-op on the 3.12/3.13 default installs).
tomli==2.4.1; python_version < "3.11"
diff --git a/studio/backend/tests/test_diffusion_attention.py b/studio/backend/tests/test_diffusion_attention.py
index 41192ee0751..ce4bc63a446 100644
--- a/studio/backend/tests/test_diffusion_attention.py
+++ b/studio/backend/tests/test_diffusion_attention.py
@@ -208,6 +208,7 @@ def test_apply_failed_kernel_restores_native_when_polluted(monkeypatch):
monkeypatch.setattr(att, "_active_attention_backend", lambda: "_native_cudnn")
# The set itself must be what fails here, not the sageattention version floor in front of it.
monkeypatch.setattr(att, "_sage_version_too_old", lambda: None)
+ monkeypatch.setattr(att, "_pip_sage2_installed", lambda: True)
monkeypatch.setattr(att, "_install_sage_dispatch_guard", lambda: True)
class _FailOnceTransformer:
@@ -293,6 +294,8 @@ def test_install_skipped_when_module_present(monkeypatch):
monkeypatch.setattr(
importlib.util, "find_spec", lambda name: object() if name == "sageattention" else None
)
+ # A pip SageAttention 2 serves "sage": nothing is installed.
+ monkeypatch.setattr(att, "_pip_sage2_installed", lambda: True)
run = _Recorder()
_stub_subprocess(monkeypatch, run)
att._ensure_attention_backend_installed("sage")
@@ -304,29 +307,29 @@ def test_install_runs_wheel_only_for_missing_kernel(monkeypatch):
import importlib.util
monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
+ monkeypatch.setattr(att, "_pip_sage2_installed", lambda: False)
+ monkeypatch.setattr(att, "_kernels_hub_compatible", lambda: True)
run = _Recorder()
_stub_subprocess(monkeypatch, run)
att._ensure_attention_backend_installed("sage")
assert len(run.calls) == 1
cmd = run.calls[0]
assert "--only-binary" in cmd and ":all:" in cmd
- assert any(a.startswith("sageattention") for a in cmd)
-def test_sage_install_carries_the_dispatcher_version_floor(monkeypatch):
- # PyPI's newest sageattention wheel is 1.0.6 but diffusers refuses anything below 2.1.1, so an unpinned install "succeeds",
- # writes an unusable 1.0.6 into the user's venv and is then rejected. The requirement carries the floor so pip resolves nothing.
+def test_sage_install_never_asks_pypi_for_sageattention(monkeypatch):
+ # PyPI has only SageAttention 1, so "sage" installs the kernels package for the hub build.
monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
import importlib.util
monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
+ monkeypatch.setattr(att, "_pip_sage2_installed", lambda: False)
+ monkeypatch.setattr(att, "_kernels_hub_compatible", lambda: True)
run = _Recorder()
_stub_subprocess(monkeypatch, run)
att._ensure_attention_backend_installed("sage")
- req = next(a for a in run.calls[0] if a.startswith("sageattention"))
- assert req == "sageattention>=2.1.1", req
- # Unversioned kernels are unaffected.
- assert att._pip_requirement("xformers", "xformers") == "xformers"
+ assert run.calls and not any("sageattention" in part for cmd in run.calls for part in cmd)
+ assert run.calls[0][-1] == "kernels"
_XFORMERS_WHEEL = "https://download.pytorch.org/whl/cu130/xformers-0.0.34-cp39-abi3-win_amd64.whl"
@@ -547,7 +550,7 @@ def test_xformers_resolution_skipped_when_already_installed(monkeypatch):
def test_matched_wheel_path_does_not_touch_other_backends(monkeypatch):
- """sage / flash / kernels still go to pip by name -- only xFormers has the silent
+ """sage (via kernels) / flash / kernels still go to pip by name -- only xFormers has the silent
ABI failure that forces URL resolution."""
assert att._MATCHED_WHEEL_BACKENDS == frozenset({"xformers"})
monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
@@ -559,9 +562,11 @@ def test_matched_wheel_path_does_not_touch_other_backends(monkeypatch):
)
run = _Recorder()
_stub_subprocess(monkeypatch, run)
+ monkeypatch.setattr(att, "_pip_sage2_installed", lambda: False)
+ monkeypatch.setattr(att, "_kernels_hub_compatible", lambda: True)
att._ensure_attention_backend_installed("sage")
assert len(run.calls) == 1
- assert "sageattention>=2.1.1" in run.calls[0]
+ assert run.calls[0][-1] == "kernels"
def test_failed_install_not_retried_in_same_process(monkeypatch):
@@ -580,8 +585,8 @@ def test_failed_install_not_retried_in_same_process(monkeypatch):
raise sp.CalledProcessError(returncode = 1, cmd = cmd)
_stub_subprocess(monkeypatch, _boom)
- att._ensure_attention_backend_installed("sage") # pre-install attempt (outside lock)
- att._ensure_attention_backend_installed("sage") # in-lock retry -> must be skipped
+ att._ensure_attention_backend_installed("flash") # pre-install attempt (outside lock)
+ att._ensure_attention_backend_installed("flash") # in-lock retry -> must be skipped
assert len(calls) == 1
@@ -595,7 +600,7 @@ def test_install_invalidates_import_caches_on_success(monkeypatch):
_stub_subprocess(monkeypatch, _Recorder())
invalidated = []
monkeypatch.setattr(importlib, "invalidate_caches", lambda: invalidated.append(True))
- att._ensure_attention_backend_installed("sage")
+ att._ensure_attention_backend_installed("flash")
assert invalidated == [True]
@@ -651,7 +656,7 @@ def test_install_failure_logs_pip_stderr(monkeypatch):
def warning(self, msg, *args):
warnings.append(msg % args if args else msg)
- att._ensure_attention_backend_installed("sage", _Logger())
+ att._ensure_attention_backend_installed("flash", _Logger())
assert warnings and "No matching distribution found" in warnings[-1]
@@ -706,18 +711,19 @@ def test_kernels_install_allowed_on_supported_hub(monkeypatch):
assert len(run.calls) == 1 and "kernels" in run.calls[0]
-def test_kernels_gate_only_applies_to_kernels_package(monkeypatch):
- # sage / xformers / flash-attn wheels do not import huggingface_hub at module scope, so the
- # hub gate must not block them.
+def test_kernels_gate_also_covers_sage(monkeypatch):
monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
import importlib.util
monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
monkeypatch.setattr(att, "_kernels_hub_compatible", lambda: False)
+ monkeypatch.setattr(att, "_pip_sage2_installed", lambda: False)
run = _Recorder()
_stub_subprocess(monkeypatch, run)
- att._ensure_attention_backend_installed("sage")
- assert len(run.calls) == 1 and any("sageattention" in part for part in run.calls[0])
+ assert att._ensure_attention_backend_installed("sage") is not None
+ assert run.calls == []
+ att._ensure_attention_backend_installed("flash")
+ assert len(run.calls) == 1 and any("flash-attn" in part for part in run.calls[0])
def test_kernels_hub_compatible_reads_hub_version(monkeypatch):
diff --git a/studio/backend/tests/test_diffusion_attention_install.py b/studio/backend/tests/test_diffusion_attention_install.py
new file mode 100644
index 00000000000..75bd7b3e7c0
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_attention_install.py
@@ -0,0 +1,438 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""What Studio installs for the on-demand attention kernels, and what it engages.
+
+SageAttention 2 is not on PyPI (only SageAttention 1.0.6), so ``sage`` without a local SageAttention 2 runs the
+kernels-community build through diffusers' ``sage_hub``, self-checked first, or keeps the default backend with a reason.
+FlashAttention 4 from the kernels hub imports nvidia-cutlass-dsl, which loads only at 4.4.x / 4.5.x."""
+
+from __future__ import annotations
+
+import pathlib
+import sys
+import types
+
+import pytest
+
+import core.inference.diffusion_attention as att
+from core.inference.diffusion_attention import apply_attention_backend
+
+torch = pytest.importorskip("torch")
+dispatch = pytest.importorskip("diffusers.models.attention_dispatch")
+
+_HUB = getattr(dispatch.AttentionBackendName, "SAGE_HUB", None)
+needs_sage_hub = pytest.mark.skipif(_HUB is None, reason = "this diffusers has no sage_hub backend")
+
+
+class _Transformer:
+ def __init__(self, head_dim = 128):
+ self.calls: list = []
+ self.config = {"attention_head_dim": head_dim}
+
+ def set_attention_backend(self, name):
+ self.calls.append(name)
+
+
+class _Logger:
+ def __init__(self):
+ self.warnings: list = []
+ self.infos: list = []
+
+ def warning(self, msg, *args):
+ self.warnings.append(msg % args if args else msg)
+
+ def info(self, msg, *args):
+ self.infos.append(msg % args if args else msg)
+
+
+def _target(dtype = "bf16"):
+ return types.SimpleNamespace(device = "cuda", dtype = dtype, torch_device = "cuda")
+
+
+def _exact_sageattn(
+ q,
+ k,
+ v,
+ tensor_layout = "NHD",
+ **_kw,
+):
+ return (
+ torch.nn.functional.scaled_dot_product_attention(
+ *(t.float().transpose(1, 2) for t in (q, k, v))
+ )
+ .transpose(1, 2)
+ .to(q.dtype)
+ )
+
+
[email protected](autouse = True)
+def _isolated(monkeypatch):
+ monkeypatch.setattr(att, "_SAGE_PROBE_CACHE", {})
+ monkeypatch.setattr(att, "_SAGE_HUB_PROBE_CACHE", {}, raising = False)
+ monkeypatch.setattr(att, "_SAGE_HUB_FAILED", [], raising = False)
+ monkeypatch.setattr(att, "_INSTALL_ATTEMPTED", set())
+ monkeypatch.setattr(att, "_ensure_attention_backend_installed", lambda *a, **k: None)
+ monkeypatch.setattr(att, "_active_attention_backend", lambda: "native")
+ monkeypatch.setattr(att, "warn_if_sdpa_math_only", lambda *a, **k: False)
+ monkeypatch.setattr(att, "_indexed_cuda_device", lambda device: device)
+ monkeypatch.setattr(att, "_pip_sage2_installed", lambda: False, raising = False)
+ backends = dispatch._AttentionBackendRegistry._backends
+ saved = dict(backends)
+ hub_cfg = dispatch._HUB_KERNELS_REGISTRY.get(_HUB) if _HUB is not None else None
+ saved_fn = getattr(hub_cfg, "kernel_fn", None)
+ yield
+ backends.clear()
+ backends.update(saved)
+ if hub_cfg is not None:
+ hub_cfg.kernel_fn = saved_fn
+
+
+def _engage(monkeypatch, probe_error = ""):
+ monkeypatch.setattr(att, "_load_sage_hub_kernel", lambda: (_exact_sageattn, ""))
+ monkeypatch.setattr(att, "_run_sage_probe", lambda d, dt, hd = 128, sageattn = None: probe_error)
+ t, log = _Transformer(), _Logger()
+ engaged = apply_attention_backend(
+ types.SimpleNamespace(transformer = t), "sage", logger = log, target = _target()
+ )
+ return engaged, t, log
+
+
+@needs_sage_hub
+def test_sage_without_sageattention2_engages_the_kernels_hub_build(monkeypatch):
+ engaged, t, log = _engage(monkeypatch)
+ assert engaged == "sage_hub"
+ assert t.calls == ["sage_hub"]
+ assert getattr(t, att.ATTENTION_BACKEND_ATTR) == "sage_hub"
+
+
+@needs_sage_hub
+def test_sage_hub_probe_failure_keeps_the_default_and_says_why(monkeypatch):
+ engaged, t, log = _engage(
+ monkeypatch, probe_error = "ValueError: Unsupported CUDA architecture: sm100"
+ )
+ assert engaged is None and "sage_hub" not in t.calls
+ assert any(
+ "sm100" in w and "source build or a community wheel" in w for w in log.warnings
+ ), log.warnings
+
+
+@needs_sage_hub
+def test_sage_hub_unloadable_keeps_the_default_and_says_why(monkeypatch):
+ monkeypatch.setattr(att, "_load_sage_hub_kernel", lambda: (None, "no build for torch 2.13"))
+ t, log = _Transformer(), _Logger()
+ assert (
+ apply_attention_backend(
+ types.SimpleNamespace(transformer = t), "sage", logger = log, target = _target()
+ )
+ is None
+ )
+ assert t.calls == [] or t.calls == ["native"]
+ assert any("no build for torch 2.13" in w and "PyPI" in w for w in log.warnings), log.warnings
+
+
+@needs_sage_hub
+def test_sage_hub_refuses_float32_and_large_head_dims(monkeypatch):
+ monkeypatch.setattr(att, "_load_sage_hub_kernel", lambda: pytest.fail("must not fetch"))
+ log = _Logger()
+ pipe = types.SimpleNamespace(transformer = _Transformer())
+ assert apply_attention_backend(pipe, "sage", logger = log, target = _target("float32")) is None
+ pipe = types.SimpleNamespace(transformer = _Transformer(head_dim = 256))
+ assert apply_attention_backend(pipe, "sage", logger = log, target = _target()) is None
+
+
+@needs_sage_hub
+def test_sage_hub_masked_call_runs_native(monkeypatch):
+ engaged, _t, _log = _engage(monkeypatch)
+ assert engaged == "sage_hub"
+ fn = dispatch._AttentionBackendRegistry._backends[_HUB]
+ q = torch.randn(1, 16, 2, 64)
+ mask = torch.ones(1, 1, 16, 16, dtype = torch.bool)
+ native = dispatch._AttentionBackendRegistry._backends[dispatch.AttentionBackendName.NATIVE]
+ torch.testing.assert_close(fn(q, q, q, attn_mask = mask), native(q, q, q, attn_mask = mask))
+
+
+@needs_sage_hub
+def test_sage_hub_loader_prefers_the_version_2_builds(monkeypatch):
+ # diffusers 0.40 asks for version 1, whose builds stop at torch 2.10; version 2 covers torch 2.9 to 2.12.
+ asked: list = []
+
+ def _get_kernel(
+ repo,
+ version = None,
+ **_kw,
+ ):
+ asked.append((repo, version))
+ if version == 2:
+ raise FileNotFoundError("Cannot install kernel")
+ return types.SimpleNamespace(sageattn = _exact_sageattn)
+
+ monkeypatch.setitem(sys.modules, "kernels", types.SimpleNamespace(get_kernel = _get_kernel))
+ dispatch._HUB_KERNELS_REGISTRY[_HUB].kernel_fn = None
+ fn, why = att._load_sage_hub_kernel()
+ assert fn is _exact_sageattn and why == ""
+ assert asked == [
+ ("kernels-community/sage-attention", 2),
+ ("kernels-community/sage-attention", 1),
+ ]
+ assert dispatch._HUB_KERNELS_REGISTRY[_HUB].kernel_fn is _exact_sageattn
+ asked.clear()
+ assert att._load_sage_hub_kernel()[0] is _exact_sageattn and asked == []
+
+
+@needs_sage_hub
+def test_sage_hub_loader_reports_every_failed_version(monkeypatch):
+ def _get_kernel(
+ repo,
+ version = None,
+ **_kw,
+ ):
+ raise FileNotFoundError(f"no variant v{version}")
+
+ monkeypatch.setitem(sys.modules, "kernels", types.SimpleNamespace(get_kernel = _get_kernel))
+ dispatch._HUB_KERNELS_REGISTRY[_HUB].kernel_fn = None
+ fn, why = att._load_sage_hub_kernel()
+ assert fn is None and "no variant v2" in why and "no variant v1" in why
+ # Remembered: the in-lock apply does not fetch again after the pre-install step failed.
+ monkeypatch.setitem(
+ sys.modules,
+ "kernels",
+ types.SimpleNamespace(get_kernel = lambda *a, **k: pytest.fail("refetch")),
+ )
+ assert att._load_sage_hub_kernel() == (None, why)
+
+
+def test_a_pip_sageattention2_keeps_the_pip_path(monkeypatch):
+ monkeypatch.setattr(att, "_pip_sage2_installed", lambda: True)
+ monkeypatch.setattr(att, "_sage_version_too_old", lambda: None)
+ monkeypatch.setattr(att, "_install_sage_dispatch_guard", lambda: True)
+ monkeypatch.setattr(att, "_run_sage_probe", lambda d, dt, hd = 128, sageattn = None: "")
+ monkeypatch.setattr(
+ att, "_load_sage_hub_kernel", lambda: pytest.fail("the hub build is only the fallback")
+ )
+ t = _Transformer()
+ assert (
+ apply_attention_backend(types.SimpleNamespace(transformer = t), "sage", target = _target())
+ == "sage"
+ )
+
+
+class _Run:
+ def __init__(self):
+ self.calls: list = []
+
+ def __call__(self, cmd, **kwargs):
+ self.calls.append([str(c) for c in cmd])
+ return types.SimpleNamespace(returncode = 0, stdout = b"", stderr = b"")
+
+
+def real_install(monkeypatch):
+ """The real installer with a recorded subprocess and a stubbed distribution table."""
+ import importlib
+ import subprocess
+
+ monkeypatch.undo() # drop the autouse no-op installer
+ monkeypatch.setattr(att, "_INSTALL_ATTEMPTED", set())
+ monkeypatch.setattr(att, "_SAGE_HUB_FAILED", [])
+ monkeypatch.setattr(att, "_load_sage_hub_kernel", lambda: (None, "stubbed"))
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
+ run = _Run()
+ monkeypatch.setattr(subprocess, "run", run)
+ monkeypatch.setattr(importlib, "invalidate_caches", lambda: None)
+ monkeypatch.setattr(att, "_kernels_hub_compatible", lambda: True)
+ monkeypatch.setattr(att, "_pinned_constraints_file", lambda: None)
+ dists: dict = {"einops": "0.8.2"}
+ monkeypatch.setattr(att, "_dist_version", lambda name: dists.get(name))
+ monkeypatch.setattr(att, "_cutlass_dsl_dependents", lambda: [])
+ return run, dists
+
+
+def test_sage_install_never_asks_pypi_for_sageattention(real_install, monkeypatch):
+ run, _dists = real_install
+ import importlib.util
+
+ monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
+ monkeypatch.setattr(att, "_pip_sage2_installed", lambda: False)
+ att._ensure_attention_backend_installed("sage")
+ assert run.calls and run.calls[0][-1] == "kernels"
+ assert not any("sageattention" in part for cmd in run.calls for part in cmd)
+
+
+def test_sage_preinstall_fetches_the_hub_build_outside_the_lock(real_install, monkeypatch):
+ run, _dists = real_install
+ import importlib.util
+
+ fetched = []
+ monkeypatch.setattr(importlib.util, "find_spec", lambda name: object())
+ monkeypatch.setattr(att, "_pip_sage2_installed", lambda: False)
+ monkeypatch.setattr(att, "_load_sage_hub_kernel", lambda: fetched.append(1) or (None, "x"))
+ assert att._ensure_attention_backend_installed("sage") is None
+ assert fetched == [1] and run.calls == []
+
+
+def test_flash4_installs_its_python_deps_with_cutlass_dsl_held_to_the_working_range(
+ real_install, monkeypatch
+):
+ run, dists = real_install
+ import importlib.util
+
+ dists["kernels"] = "0.12.1"
+ monkeypatch.setattr(
+ importlib.util, "find_spec", lambda name: object() if name == "kernels" else None
+ )
+ att._ensure_attention_backend_installed("flash_4_hub")
+ flat = [part for cmd in run.calls for part in cmd]
+ assert "nvidia-cutlass-dsl>=4.4,<4.6" in flat
+ assert att.FA4_TVM_FFI_SPEC in flat
+ kernels_cmd = next(cmd for cmd in run.calls if "kernels==0.12.3" in cmd)
+ assert "--no-deps" in kernels_cmd and "--only-binary" in kernels_cmd
+ deps_cmd = next(cmd for cmd in run.calls if "nvidia-cutlass-dsl>=4.4,<4.6" in cmd)
+ assert "--no-deps" not in deps_cmd # cutlass-dsl needs its libs and cuda-python
+ # Once per process: the in-lock re-resolve must not run pip again.
+ n = len(run.calls)
+ att._ensure_attention_backend_installed("flash_4_hub")
+ assert len(run.calls) == n
+
+
+def test_flash4_deps_already_satisfied_install_nothing(real_install, monkeypatch):
+ run, dists = real_install
+ import importlib.util
+
+ dists.update(
+ {"kernels": "0.12.3", "nvidia-cutlass-dsl": "4.5.3", "apache-tvm-ffi": "0.1.14.post1"}
+ )
+ monkeypatch.setattr(importlib.util, "find_spec", lambda name: object())
+ assert att._ensure_attention_backend_installed("flash_4_hub") is None
+ assert run.calls == []
+
+
+def test_flash4_refuses_to_replace_an_out_of_range_cutlass_dsl(real_install, monkeypatch):
+ run, dists = real_install
+ import importlib.util
+
+ dists.update(
+ {"kernels": "0.16.0", "nvidia-cutlass-dsl": "4.8.0", "apache-tvm-ffi": "0.1.14.post1"}
+ )
+ monkeypatch.setattr(
+ att, "_cutlass_dsl_dependents", lambda: ["quack-kernels 0.6.5 (nvidia-cutlass-dsl>=4.7)"]
+ )
+ monkeypatch.setattr(importlib.util, "find_spec", lambda name: object())
+ log = _Logger()
+ reason = att._ensure_attention_backend_installed("flash_4_hub", log)
+ assert reason and "4.8.0" in reason and "quack-kernels" in reason
+ assert run.calls == []
+ assert any("4.4.x or 4.5.x" in w for w in log.warnings)
+
+
+def test_flash4_install_respects_the_off_switch(real_install, monkeypatch):
+ run, dists = real_install
+ import importlib.util
+
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "0")
+ monkeypatch.setattr(importlib.util, "find_spec", lambda name: object())
+ att._ensure_attention_backend_installed("flash_4_hub")
+ assert run.calls == []
+
+
+ "version, ok",
+ [
+ ("4.3.5", False),
+ ("4.4.0", True),
+ ("4.4.2", True),
+ ("4.5.3", True),
+ ("4.6.0", False),
+ ("4.8.0", False),
+ (None, False),
+ ],
+)
+def test_flash4_cutlass_dsl_range(version, ok):
+ # Measured on a B200 (torch 2.11 / 2.12): 4.4.0 to 4.5.3 load; 4.6.3 to 4.8.0 lack cute.core.ThrMma.
+ assert att.fa4_cutlass_dsl_ok(version) is ok
+
+
+def test_studio_pins_a_kernels_release_diffusers_accepts_for_flash4():
+ # diffusers' flash_4_hub raises below kernels 0.12.3.
+ req = pathlib.Path(att.__file__).resolve().parents[2] / "requirements" / "extras-no-deps.txt"
+ pins = [
+ line.split("==", 1)[1].strip()
+ for line in req.read_text(encoding = "utf-8").splitlines()
+ if line.startswith("kernels==")
+ ]
+ assert pins and all(att._version_tuple(v) >= att.FA4_KERNELS_MIN for v in pins), pins
+
+
+def test_a_kernels_upgrade_is_visible_to_diffusers_in_the_same_process(monkeypatch):
+ # Without the refresh the first load after the upgrade still fell back (fresh venv, torch 2.11 / 2.12).
+ from diffusers.utils import import_utils
+
+ monkeypatch.setattr(import_utils, "_kernels_version", "0.12.1")
+ monkeypatch.setattr(import_utils, "_kernels_available", True)
+ monkeypatch.delitem(sys.modules, "kernels", raising = False)
+ monkeypatch.setattr(att, "_dist_version", lambda name: "0.12.3" if name == "kernels" else None)
+ att._refresh_diffusers_kernels_version()
+ assert import_utils.is_kernels_version(">=", "0.12.3")
+
+
+def test_refresh_drops_a_memoized_pre_upgrade_check(monkeypatch):
+ from diffusers.utils import import_utils
+
+ monkeypatch.setattr(import_utils, "_kernels_version", "0.12.1")
+ monkeypatch.setattr(import_utils, "_kernels_available", True)
+ monkeypatch.delitem(sys.modules, "kernels", raising = False)
+ clear = getattr(import_utils.is_kernels_version, "cache_clear", None)
+ if clear is not None:
+ clear()
+ assert not import_utils.is_kernels_version(">=", "0.12.3")
+ monkeypatch.setattr(att, "_dist_version", lambda name: "0.12.3" if name == "kernels" else None)
+ att._refresh_diffusers_kernels_version()
+ assert import_utils.is_kernels_version(">=", "0.12.3")
+ if clear is not None:
+ clear()
+
+
+def test_an_imported_old_kernels_is_not_papered_over(monkeypatch):
+ from diffusers.utils import import_utils
+
+ monkeypatch.setattr(import_utils, "_kernels_version", "0.12.1")
+ monkeypatch.setitem(sys.modules, "kernels", types.SimpleNamespace())
+ monkeypatch.setattr(att, "_dist_version", lambda name: "0.12.3" if name == "kernels" else None)
+ log = _Logger()
+ att._refresh_diffusers_kernels_version(log)
+ assert import_utils._kernels_version == "0.12.1"
+ assert any("after Studio restarts" in w for w in log.warnings)
+
+
+def test_a_pth_installed_mid_process_is_activated(monkeypatch, tmp_path):
+ # Without running the .pth the first load after the install reported cutlass-dsl missing (fresh venv, B200).
+ import importlib.metadata as md
+
+ pkg_dir = tmp_path / "dsl_packages"
+ pkg_dir.mkdir()
+ (tmp_path / "nvidia_cutlass_dsl_packages.pth").write_text(
+ f"import sys; sys.path.insert(0, {str(pkg_dir)!r})\n"
+ )
+
+ class _Dist:
+ files = [
+ pathlib.PurePosixPath("nvidia_cutlass_dsl_packages.pth"),
+ pathlib.PurePosixPath("pkg/__init__.py"),
+ ]
+
+ def locate_file(self, entry):
+ return tmp_path / entry
+
+ monkeypatch.setattr(md, "distribution", lambda name: _Dist())
+ monkeypatch.setattr(sys, "path", list(sys.path))
+ att._activate_installed_pth_files()
+ assert str(pkg_dir) in sys.path
+
+
+def test_nothing_to_install_still_activates_cutlass_pth(monkeypatch):
+ # An NVFP4 load installs cutlass-dsl through FlashInfer without running its .pth; a later flash4 must still see it.
+ calls = []
+ monkeypatch.setattr(att, "_fa4_python_deps_plan", lambda: ([], None))
+ monkeypatch.setattr(att, "_activate_installed_pth_files", lambda *a: calls.append(a))
+ assert att._ensure_fa4_python_deps() is None
+ assert calls == [()]
diff --git a/studio/backend/tests/test_diffusion_attention_sage_gate.py b/studio/backend/tests/test_diffusion_attention_sage_gate.py
index 4abe5fbb802..b3d508b1ca9 100644
--- a/studio/backend/tests/test_diffusion_attention_sage_gate.py
+++ b/studio/backend/tests/test_diffusion_attention_sage_gate.py
@@ -51,6 +51,8 @@ def _isolated(monkeypatch):
monkeypatch.setattr(att, "warn_if_sdpa_math_only", lambda *a, **k: False)
monkeypatch.setattr(att, "_indexed_cuda_device", lambda device: device)
monkeypatch.setattr(att, "_sage_version_too_old", lambda: None, raising = False)
+ # The pip SageAttention 2 path; the hub path is in test_diffusion_attention_install.py.
+ monkeypatch.setattr(att, "_pip_sage2_installed", lambda: True, raising = False)
backends = dispatch._AttentionBackendRegistry._backends
saved = backends[dispatch.AttentionBackendName.SAGE]
saved_fa4 = backends[dispatch.AttentionBackendName.FLASH_4_HUB]
@@ -448,15 +450,18 @@ def test_sage_version_floor(monkeypatch, installed, refused):
assert f"sageattention {installed} is older than 2.1.1" in reason
-def test_old_sageattention_falls_back_with_a_reason(monkeypatch):
+def test_old_sageattention_is_ignored_for_the_hub_build(monkeypatch):
+ # sageattention 1.0.6 is never probed; with no hub build the load keeps the default backend and says why.
seen: list = []
- monkeypatch.setattr(att, "_run_sage_probe", lambda d, dt, hd = 128: seen.append(hd) or "")
+ monkeypatch.setattr(att, "_run_sage_probe", lambda d, dt, hd = 128, **k: seen.append(hd) or "")
+ monkeypatch.setattr(att, "_pip_sage2_installed", lambda: False)
monkeypatch.setattr(
att,
"_sage_version_too_old",
lambda: "sageattention 1.0.6 is older than 2.1.1, the "
"SageAttention 2 release diffusers needs",
)
+ monkeypatch.setattr(att, "_load_sage_hub_kernel", lambda: (None, "no build for this torch"))
t, log = _Transformer(128), _Logger()
assert (
apply_attention_backend(
@@ -464,8 +469,11 @@ def test_old_sageattention_falls_back_with_a_reason(monkeypatch):
)
is None
)
- assert "sage" not in t.calls and seen == []
- assert any("1.0.6 is older than 2.1.1" in w for w in log.warnings)
+ assert "sage" not in t.calls and "sage_hub" not in t.calls and seen == []
+ assert any(
+ "no build for this torch" in w and "source build or a community wheel" in w
+ for w in log.warnings
+ )
def test_sm100_explicit_sage_falls_back_and_auto_never_picks_it(monkeypatch):
diff --git a/studio/backend/tests/test_diffusion_attention_sage_probe.py b/studio/backend/tests/test_diffusion_attention_sage_probe.py
index 6f5ab38316b..3dc11e4f71b 100644
--- a/studio/backend/tests/test_diffusion_attention_sage_probe.py
+++ b/studio/backend/tests/test_diffusion_attention_sage_probe.py
@@ -51,6 +51,8 @@ def _isolated(monkeypatch):
monkeypatch.setattr(att, "_indexed_cuda_device", lambda device: device)
monkeypatch.setattr(att, "_install_sage_dispatch_guard", lambda: True)
monkeypatch.setattr(att, "_sage_version_too_old", lambda: None)
+ # The pip SageAttention 2 path; the hub path is in test_diffusion_attention_install.py.
+ monkeypatch.setattr(att, "_pip_sage2_installed", lambda: True, raising = False)
monkeypatch.setattr(att, "_install_fa4_dispatch_guard", lambda: True)
monkeypatch.setattr(att, "_fa4_kernel_runs", lambda *a, **k: True)
diff --git a/studio/backend/tests/test_diffusion_cuda_graph.py b/studio/backend/tests/test_diffusion_cuda_graph.py
index 65e0302bdd1..b7165271e21 100644
--- a/studio/backend/tests/test_diffusion_cuda_graph.py
+++ b/studio/backend/tests/test_diffusion_cuda_graph.py
@@ -1136,10 +1136,12 @@ def test_real_cuda_compiled_module_capture_matches_the_compiled_call():
assert unet._compiled_call_impl is compiled
-def test_graph_eligible_declines_a_sage_denoiser(stub_torch, monkeypatch):
- """SageAttention under a replayed graph renders noise (FLUX.1-schnell, A100), so a Sage load stays ungraphed."""
[email protected]("backend", ["sage", "sage_hub"])
+def test_graph_eligible_declines_a_sage_denoiser(stub_torch, monkeypatch, backend):
+ """SageAttention under a replayed graph renders noise (FLUX.1-schnell, A100), so a Sage load stays ungraphed; the
+ kernels-hub build (sage_hub) is the same kernel."""
dit = _FakeDiT()
- dit._unsloth_attention_backend = "sage"
+ dit._unsloth_attention_backend = backend
ok, reason = _eligible(monkeypatch, pipe = types.SimpleNamespace(transformer = dit))
assert (ok, reason) == (False, "SageAttention is not CUDA-graph safe")
diff --git a/studio/backend/tests/test_diffusion_nvfp4_install.py b/studio/backend/tests/test_diffusion_nvfp4_install.py
index 5a149c010ce..9de6f816538 100644
--- a/studio/backend/tests/test_diffusion_nvfp4_install.py
+++ b/studio/backend/tests/test_diffusion_nvfp4_install.py
@@ -1515,3 +1515,18 @@ def test_an_unreported_failure_does_not_revert_a_concurrent_upgrade(env):
assert "flashinfer-python" not in env.dists, reason
assert env.dists["packaging"] == "26.0", reason
assert not [c for c in env.commands if "packaging==25.0" in c]
+
+
+def test_cutlass_dsl_is_held_to_the_flash4_range_when_absent(env):
+ # An unconstrained resolve lands cutlass-dsl 4.8.0, which the hub FA4 build cannot load.
+ ok, reason = _ensure(env)
+ assert ok, reason
+ assert "nvidia-cutlass-dsl>=4.4,<4.6" in env.constraints_seen[0].splitlines()
+
+
+def test_an_installed_cutlass_dsl_is_pinned_not_ranged(env):
+ env.dists["nvidia-cutlass-dsl"] = "4.4.2"
+ ok, reason = _ensure(env)
+ assert ok, reason
+ pins = env.constraints_seen[0].splitlines()
+ assert "nvidia-cutlass-dsl==4.4.2" in pins and "nvidia-cutlass-dsl>=4.4,<4.6" not in pins
diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsx
index f837e24b2cb..989ddf51fe4 100644
--- a/studio/frontend/src/features/images/images-page.tsx
+++ b/studio/frontend/src/features/images/images-page.tsx
@@ -4612,7 +4612,7 @@ export function ImagesPage({
/>
<AdvancedSelect
label="Attention"
- hint="Attention kernel. Auto upgrades to cuDNN fused attention on NVIDIA when a speed profile is active. sage is INT8 attention: fast (10-40%) but can black-frame some families (Qwen, Wan), so it never engages automatically."
+ hint="Attention kernel. Auto upgrades to cuDNN fused attention on NVIDIA when a speed profile is active. sage is INT8 attention (SageAttention 2; without a local install Studio fetches the Hugging Face kernels-hub build, which runs on Ampere, Ada and Hopper GPUs, and any other GPU keeps the default): fast (10-40%) but can black-frame some families (Qwen, Wan), so it never engages automatically."
badge={<ResolvedBadge status={status} controlKey="attention_backend" />}
value={attentionBackend}
onValueChange={(v) => setAttentionBackend(v as typeof attentionBackend)}
diff --git a/studio/frontend/src/features/video/video-page.tsx b/studio/frontend/src/features/video/video-page.tsx
index 190e46467b2..74f5263ecbb 100644
--- a/studio/frontend/src/features/video/video-page.tsx
+++ b/studio/frontend/src/features/video/video-page.tsx
@@ -3586,7 +3586,7 @@ function VideoGenerator({
)}
<AdvancedSelect
label="Attention"
- hint="Attention kernel. Auto upgrades to cuDNN fused attention on NVIDIA when a speed profile is active. sage is INT8 attention: fast (10-40%) but can black-frame some families (Qwen, Wan), so it never engages automatically."
+ hint="Attention kernel. Auto upgrades to cuDNN fused attention on NVIDIA when a speed profile is active. sage is INT8 attention (SageAttention 2; without a local install Studio fetches the Hugging Face kernels-hub build, which runs on Ampere, Ada and Hopper GPUs, and any other GPU keeps the default): fast (10-40%) but can black-frame some families (Qwen, Wan), so it never engages automatically."
badge={<ResolvedBadge status={status} controlKey="attention_backend" />}
value={attentionBackend}
onValueChange={(v) => setAttentionBackend(v as typeof attentionBackend)}
diff --git a/studio/frontend/src/lib/resolved-precision.ts b/studio/frontend/src/lib/resolved-precision.ts
index 9bf3fbb3aba..869539a6474 100644
--- a/studio/frontend/src/lib/resolved-precision.ts
+++ b/studio/frontend/src/lib/resolved-precision.ts
@@ -70,6 +70,8 @@ export function formatResolvedValue(key: string, value: string | boolean | null
if (value === null || value === undefined || value === "") return "Off";
if (typeof value === "boolean") return value ? "On" : "Off";
if (value === "_native_cudnn" || value.toLowerCase() === "cudnn") return "cuDNN";
+ // The kernels-hub build of the "sage" option.
+ if (value === "sage_hub") return "SAGE";
// Deferred speed auto: the dense pipe stays exact/eager and compiles on the 3rd image (the tooltip carries the full reason).
if (value === "deferred") return "On from 3rd image";
return value.toUpperCase();