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: 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.pyindex 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 weinative - 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 sageattnif 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_fndef _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_fakedef _(query, key, value, is_causal, scale):return query.new_empty((*query.shape[:-1], value.shape[-1]))- _SAGE_OP["op"] = _op+ slot["op"] = _opexcept 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) -> Optif spec is None:return Nonemodule, 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 fallbackif 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 Noneif 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 Nonediff --git a/studio/backend/core/inference/diffusion_cuda_graph.py b/studio/backend/core/inference/diffusion_cuda_graph.pyindex 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.pyindex 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:+ passsize_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.txtindex 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.pyindex 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.utilmonkeypatch.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) == 1cmd = 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.utilmonkeypatch.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 silentABI 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 skippedassert 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.utilmonkeypatch.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.pynew file mode 100644index 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.pyindex 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._backendssaved = 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.pyindex 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.pyindex 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 = backendok, 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.pyindex 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, reasonassert env.dists["packaging"] == "26.0", reasonassert 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 pinsdiff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsxindex 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({/><AdvancedSelectlabel="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.tsxindex 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({)}<AdvancedSelectlabel="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.tsindex 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 | nullif (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();