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 diffusion: protect the first and last NVFP4 steps by default on sm_100-class cards (W4A16 auto) (#16759)

Daniel Hane79f756c9cae
diff --git a/studio/backend/core/inference/diffusion_compile_cache.py b/studio/backend/core/inference/diffusion_compile_cache.py
index b8a1b9e38fa..4c4a912797d 100644
--- a/studio/backend/core/inference/diffusion_compile_cache.py
+++ b/studio/backend/core/inference/diffusion_compile_cache.py
@@ -245,8 +245,8 @@ _GRAPH_SWITCHES = {
"UNSLOTH_DIFFUSION_FP8_UNIT_SCALE": "auto",
"UNSLOTH_DIFFUSION_TF32": "on",
"UNSLOTH_DIFFUSION_FP8_UNIT_SCALE_MIN_ROWS": "rows:256",
- # Unset is off; "auto" protects the head + last step, so "auto" is NOT the default here.
- "UNSLOTH_NVFP4_PROTECT_STEPS": "raw",
+ # Keyed against the card's unset default (auto on sm_100-class, else off); a bare "0" protects step 0, not off.
+ "UNSLOTH_NVFP4_PROTECT_STEPS": "protect",
}
_OFF_WORDS = ("0", "off", "false", "no", "none")
_ON_WORDS = ("1", "on", "true", "yes", "force")
@@ -270,6 +270,10 @@ def _switch_value(name: str, default: str) -> Optional[str]:
except ValueError:
return None
return None if count == default.partition(":")[2] else count
+ if default == "protect":
+ from .diffusion_nvfp4_protect import default_model_spec, protect_steps_env
+ value = protect_steps_env() or "off"
+ return None if value == (default_model_spec() or "off") else value
if default.startswith("raw"):
return None if raw in _OFF_WORDS or raw == default.partition(":")[2] else raw
value = "off" if raw in _OFF_WORDS else "on" if raw in _ON_WORDS else None
diff --git a/studio/backend/core/inference/diffusion_nvfp4_protect.py b/studio/backend/core/inference/diffusion_nvfp4_protect.py
index d4d8aa4105b..b48a58be206 100644
--- a/studio/backend/core/inference/diffusion_nvfp4_protect.py
+++ b/studio/backend/core/inference/diffusion_nvfp4_protect.py
@@ -1,7 +1,7 @@
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-"""Denoise steps that run W4A16 instead of W4A4; set must be measured per model, so off unless named."""
+"""Denoise steps that run W4A16 instead of W4A4; NVFP4 models default to ``auto`` on sm_100-class cards, else off."""
from __future__ import annotations
@@ -15,6 +15,10 @@ PROTECT_STEPS_ENV = "UNSLOTH_NVFP4_PROTECT_STEPS"
AUTO = "auto"
AUTO_HEAD_FRACTION = 0.08
+# Only per-model controllers get it: the global one stays unarmed so non-NVFP4 graph keys and logs are unchanged.
+DEFAULT_MODEL_SPEC = AUTO
+# B200 measured auto accuracy-positive for +0.7-2.6% time; sm_120 cost +2.5-17% with no LPIPS interval clear of zero.
+DEFAULT_CAPABILITY_MAJOR = 10
ALL = "all"
@@ -26,6 +30,41 @@ def protect_steps_env() -> str:
return "" if raw in _OFF_TOKENS else raw
+def protect_steps_explicit() -> bool:
+ return bool(os.environ.get(PROTECT_STEPS_ENV, "").strip())
+
+
+def default_model_spec(device: Any = None) -> str:
+ try:
+ import torch
+ if not torch.cuda.is_available():
+ return ""
+ major = int(torch.cuda.get_device_capability(device)[0])
+ except Exception: # noqa: BLE001 - an unreadable card keeps the old default, off
+ return ""
+ return DEFAULT_MODEL_SPEC if major == DEFAULT_CAPABILITY_MAJOR else ""
+
+
+def _module_cuda_device(module: Any) -> Any:
+ try:
+ for tensors in (module.parameters(), module.buffers()):
+ for tensor in tensors:
+ if tensor.device.type == "cuda":
+ return tensor.device
+ except Exception: # noqa: BLE001 - no readable tensor: the current device decides
+ pass
+ return None
+
+
+def model_protect_spec(module: Any = None) -> str:
+ if protect_steps_explicit():
+ return protect_steps_env()
+ spec = protect_controller().spec
+ if spec:
+ return spec
+ return default_model_spec(_module_cuda_device(module) if module is not None else None)
+
+
def parse_protect_steps(spec: Any, total_steps: int) -> tuple:
"""``spec`` resolved against ``total_steps``, sorted; out-of-range drops, a non-integer token raises."""
total = int(total_steps)
@@ -282,7 +321,7 @@ def attach_controller(module: Any, controller: NVFP4StepController) -> int:
def attach_own_controller(module: Any) -> Optional[NVFP4StepController]:
"""Per-model controller, so concurrent image and video renders never move each other's steps."""
- ctl = NVFP4StepController(protect_controller().spec)
+ ctl = NVFP4StepController(model_protect_spec(module))
return ctl if attach_controller(module, ctl) else None
diff --git a/studio/backend/tests/test_diffusion_compile_cache_variant.py b/studio/backend/tests/test_diffusion_compile_cache_variant.py
index 86cebcc75be..0b6d12dba7b 100644
--- a/studio/backend/tests/test_diffusion_compile_cache_variant.py
+++ b/studio/backend/tests/test_diffusion_compile_cache_variant.py
@@ -123,6 +123,11 @@ def test_an_instance_forward_swap_keys_apart():
@pytest.mark.parametrize("name,default", sorted(cc._GRAPH_SWITCHES.items()))
@pytest.mark.parametrize("quant", ["int8", None])
def test_graph_switches_key_apart_only_off_their_default(monkeypatch, name, default, quant):
+ if default == "protect":
+ from core.inference import diffusion_nvfp4_protect as pr
+
+ # an sm_100-class card, whose unset default is auto
+ monkeypatch.setattr(pr, "default_model_spec", lambda device = None: "auto")
m = _int8() if quant else _model()
k0 = _key(m, quant)
rows = default.partition(":")[2] if default.startswith(("rows:", "count:")) else None
@@ -140,9 +145,14 @@ def test_graph_switches_key_apart_only_off_their_default(monkeypatch, name, defa
elif rows:
flipped = "1"
else:
- flipped = {"on": "0", "off": "1", "auto": "0", "raw": "torchao", "raw:auto": "torchao"}[
- default
- ]
+ flipped = {
+ "on": "0",
+ "off": "1",
+ "auto": "0",
+ "raw": "torchao",
+ "raw:auto": "torchao",
+ "protect": "all",
+ }[default]
monkeypatch.setenv(name, flipped)
assert _key(m, quant) != k0
assert name in cc.model_fingerprint(transformer = m, quant = quant, **_FP_KW)["switches"]
@@ -212,13 +222,23 @@ def test_a_bundle_saved_for_one_variant_is_a_miss_for_the_other(monkeypatch, tmp
cc.restore(again)
-def test_protect_steps_auto_is_not_its_default(monkeypatch):
[email protected]("default", ["auto", ""])
+def test_protect_steps_key_apart_only_off_the_cards_default(monkeypatch, default):
+ """sm_100-class cards default to auto, others to off: the unset run shares its card's default bundle."""
+ from core.inference import diffusion_nvfp4_protect as pr
+
+ monkeypatch.setattr(pr, "default_model_spec", lambda device = None: default)
m = _int8()
k0 = _key(m)
- monkeypatch.setenv("UNSLOTH_NVFP4_PROTECT_STEPS", "auto")
- assert _key(m) != k0
monkeypatch.setenv("UNSLOTH_NVFP4_BACKEND", "auto")
- assert cc.graph_switches() == {"UNSLOTH_NVFP4_PROTECT_STEPS": "auto"}
+ keys = {}
+ for value in ("auto", "off", "0"):
+ monkeypatch.setenv("UNSLOTH_NVFP4_PROTECT_STEPS", value)
+ keys[value] = _key(m)
+ same = value == (default or "off")
+ assert (keys[value] == k0) is same, value
+ assert cc.graph_switches() == ({} if same else {"UNSLOTH_NVFP4_PROTECT_STEPS": value})
+ assert len(set(keys.values())) == 3
def test_a_dequantizing_weight_property_is_never_read():
diff --git a/studio/backend/tests/test_diffusion_nvfp4_protect_image.py b/studio/backend/tests/test_diffusion_nvfp4_protect_image.py
index 7b1b0b91727..9a151f33a69 100644
--- a/studio/backend/tests/test_diffusion_nvfp4_protect_image.py
+++ b/studio/backend/tests/test_diffusion_nvfp4_protect_image.py
@@ -304,9 +304,10 @@ def test_an_unarmed_load_keeps_its_graph_cap(monkeypatch):
torch = pytest.importorskip("torch")
from core.inference import diffusion_cuda_graph as cg
- monkeypatch.delenv(pr.PROTECT_STEPS_ENV, raising = False)
+ monkeypatch.setenv(pr.PROTECT_STEPS_ENV, "off")
pr.reset_protect_controller()
tree, _layer = _cpu_nvfp4_tree(torch)
+ assert pr.attach_own_controller(tree).armed is False
block = _BlockHolding(tree).eval()
handle = cg.GraphedForward(block, max_graphs = 4).install().enable()
block(hidden_states = torch.zeros(2, 64), return_dict = False)
@@ -315,6 +316,56 @@ def test_an_unarmed_load_keeps_its_graph_cap(monkeypatch):
cg.uninstall_all([handle])
[email protected]("capability", [(10, 0), (10, 3), (12, 0), (9, 0), None])
+ "env,spec,steps",
+ [
+ (None, "auto", (0, 8)),
+ ("", "auto", (0, 8)),
+ ("off", "", ()),
+ ("0", "0", (0,)),
+ ("all", "all", tuple(range(9))),
+ ],
+)
+def test_a_model_with_nvfp4_layers_defaults_to_auto_on_sm100_only(
+ monkeypatch, env, spec, steps, capability
+):
+ """Unset is auto on sm_100-class cards only (sm_120 measured slower with no LPIPS gain); explicit values hold."""
+ torch = pytest.importorskip("torch")
+ monkeypatch.setattr(torch.cuda, "is_available", lambda: capability is not None)
+ monkeypatch.setattr(torch.cuda, "get_device_capability", lambda device = None: capability)
+ if not env and capability is not None and capability[0] != 10 or not env and capability is None:
+ spec, steps = "", ()
+ if env is None:
+ monkeypatch.delenv(pr.PROTECT_STEPS_ENV, raising = False)
+ else:
+ monkeypatch.setenv(pr.PROTECT_STEPS_ENV, env)
+ pr.reset_protect_controller()
+ try:
+ tree, layer = _cpu_nvfp4_tree(torch)
+ ctl = pr.attach_own_controller(tree)
+ assert ctl is not None and layer.protect is ctl
+ assert ctl.spec == spec and ctl.armed is bool(spec)
+ assert ctl.begin(9) == steps
+ finally:
+ monkeypatch.delenv(pr.PROTECT_STEPS_ENV, raising = False)
+ pr.reset_protect_controller()
+
+
+def test_the_default_leaves_models_without_nvfp4_layers_unarmed(monkeypatch):
+ torch = pytest.importorskip("torch")
+ import torch.nn as nn
+
+ monkeypatch.delenv(pr.PROTECT_STEPS_ENV, raising = False)
+ ctl = pr.reset_protect_controller()
+ plain = nn.Sequential(nn.Linear(8, 8))
+ assert ctl.armed is False
+ assert pr.attach_own_controller(plain) is None
+ assert pr.module_controller(plain) is ctl
+ assert pr.protect_graph_key(module = plain) == ()
+ assert pr.pipeline_controllers(types.SimpleNamespace(transformer = plain)) == [ctl]
+
+
def _cuda_or_skip():
from core.inference import diffusion_nvfp4_ops as ops