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: int8 ConvRot by default for FLUX.2 klein and FLUX.3 klein (LPIPS 0.10 to 0.04) (#17209)

Daniel Han4a45dbd03e5f
diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.py
index 792f2efcf30..278bb6b0303 100644
--- a/studio/backend/core/inference/diffusion_families.py
+++ b/studio/backend/core/inference/diffusion_families.py
@@ -443,6 +443,33 @@ _MOSS_IMAGE_CONVROT_SUFFIXES = (
"proj.ffn_down",
)
+# All 101 int8 Linear widths are 256-divisible.
+_FLUX2_KLEIN_CONVROT_SUFFIXES = (
+ "context_embedder",
+ "attn.to_q",
+ "attn.to_k",
+ "attn.to_v",
+ "attn.to_out.0",
+ "attn.add_q_proj",
+ "attn.add_k_proj",
+ "attn.add_v_proj",
+ "attn.to_add_out",
+ "ff.linear_in",
+ "ff.linear_out",
+ "ff_context.linear_in",
+ "ff_context.linear_out",
+ "attn.to_qkv_mlp_proj",
+ "attn.to_out",
+)
+_FLUX3_CONVROT_SUFFIXES = (
+ "attn.to_q",
+ "attn.to_k",
+ "attn.to_v",
+ "attn.to_out.0",
+ "ff.linear_in",
+ "ff.linear_out",
+)
+
_FAMILIES: tuple[DiffusionFamily, ...] = (
DiffusionFamily(
name = "flux.1",
@@ -520,6 +547,15 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
label = "FLUX.2 Klein",
profile = FamilyProfile(
auto_bf16_when_resident = SMALL_DIT_BF16_WHEN_RESIDENT,
+ # LPIPS vs fp16 (4B, T4 W8A8, 16 renders): plain 0.103 -> ConvRot 0.037; A100 0.092 -> 0.034.
+ int8_convrot = ConvRotSpec(
+ group = 256,
+ suffixes = _FLUX2_KLEIN_CONVROT_SUFFIXES,
+ filename = "FLUX.2-klein-4B-INT8-ConvRot.safetensors",
+ repo = "unsloth/FLUX.2-klein-4B-FP8",
+ default_on = True,
+ hosted_plain = True,
+ ),
preview_factors = "flux2",
auto_static_skip = (
(
@@ -612,6 +648,7 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
label = "FLUX.3 Klein Base",
profile = FamilyProfile(
auto_bf16_when_resident = SMALL_DIT_BF16_WHEN_RESIDENT,
+ int8_convrot = ConvRotSpec(group = 256, suffixes = _FLUX3_CONVROT_SUFFIXES, default_on = True),
# Left dense for EVERY transformer-quant scheme: per-token modulations, timestep embedders, norm_out, the
# text-stream per-mode blocks and the 20480-wide text projection. Measured on B200 against bf16 (11-case
# recipe set, LPIPS mean): int8 0.097 -> 0.027, fp8 0.063 -> 0.033, mxfp8 0.024 with it; without it mxfp8
@@ -670,6 +707,14 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
label = "FLUX.3 Klein",
profile = FamilyProfile(
auto_bf16_when_resident = SMALL_DIT_BF16_WHEN_RESIDENT,
+ int8_convrot = ConvRotSpec(
+ group = 256,
+ suffixes = _FLUX3_CONVROT_SUFFIXES,
+ filename = "flux-3-image-klein-INT8-ConvRot.safetensors",
+ repo = "unsloth/flux-3-image-klein-FP8",
+ default_on = True,
+ hosted_plain = True,
+ ),
# Left dense for EVERY transformer-quant scheme: per-token modulations, timestep embedders, norm_out, the
# text-stream per-mode blocks and the 20480-wide text projection. Measured on B200 against bf16 (11-case
# recipe set, LPIPS mean): int8 0.097 -> 0.027, fp8 0.063 -> 0.033, mxfp8 0.024 with it; without it mxfp8
diff --git a/studio/backend/core/inference/diffusion_prequant.py b/studio/backend/core/inference/diffusion_prequant.py
index 3cffe613ade..793f9dffdd3 100644
--- a/studio/backend/core/inference/diffusion_prequant.py
+++ b/studio/backend/core/inference/diffusion_prequant.py
@@ -1038,19 +1038,28 @@ def resolve_prequant_source(
for name in declared + derived:
if name and name not in names:
names.append(name)
+ from .diffusion_transformer_quant import convrot_drops_plain_hosted
+
+ if rotated and convrot_drops_plain_hosted(scheme, fam_name):
+ # Hosted plain int8 files are unrotated: rotated file or rotate at load.
+ names = (
+ [rotated] if str(repo_id).strip().lower() == str(rotated_repo or "").lower() else []
+ )
+ declared = tuple(names)
names = with_declared_safetensors_twins(names, declared, scheme = scheme)
if comfy_prequant_enabled() and _comfy_prequant_family(fam):
names = with_comfy_twins(names, lead = scheme in COMFY_TWIN_LEADS)
names = without_nvfp4_pickles(scheme, names)
- if not names:
+ if names:
+ return PrequantSource(
+ kind = "repo",
+ location = repo_id,
+ filename = names[0],
+ fallback_filenames = tuple(names[1:]),
+ declared_filenames = declared,
+ )
+ if not (rotated and convrot_drops_plain_hosted(scheme, fam_name)):
return None
- return PrequantSource(
- kind = "repo",
- location = repo_id,
- filename = names[0],
- fallback_filenames = tuple(names[1:]),
- declared_filenames = declared,
- )
# Nothing hosted: try this machine's cache of an earlier build; task names the component (MoE transformer_2).
try:
from .diffusion_prequant_cache import lookup
diff --git a/studio/backend/core/inference/diffusion_transformer_quant.py b/studio/backend/core/inference/diffusion_transformer_quant.py
index 5156afa46a2..c26395d13f3 100644
--- a/studio/backend/core/inference/diffusion_transformer_quant.py
+++ b/studio/backend/core/inference/diffusion_transformer_quant.py
@@ -381,6 +381,10 @@ _INT8_FAMILY_CONVROT_DEFAULT_ON: frozenset[str] = frozenset(
name for name, spec in _INT8_FAMILY_CONVROT_SPECS.items() if spec.default_on
)
+_INT8_FAMILY_CONVROT_HOSTED_PLAIN: frozenset[str] = frozenset(
+ name for name, spec in _INT8_FAMILY_CONVROT_SPECS.items() if spec.hosted_plain
+)
+
INT8_CONVROT_ENV = "UNSLOTH_DIFFUSION_INT8_CONVROT"
@@ -395,6 +399,14 @@ def int8_convrot_enabled(family: Optional[str] = None) -> bool:
return str(family or "").strip().lower() in _INT8_FAMILY_CONVROT_DEFAULT_ON
+def convrot_drops_plain_hosted(scheme: str, family: Optional[str] = None) -> bool:
+ """True when an int8 load must skip the family's unrotated hosted files (``ConvRotSpec.hosted_plain``)."""
+ if scheme != TQ_INT8:
+ return False
+ key = str(family or "").strip().lower()
+ return key in _INT8_FAMILY_CONVROT_HOSTED_PLAIN and int8_convrot_enabled(key)
+
+
def convrot_spec_for_scheme(
scheme: str, family: Optional[str] = None
) -> tuple[int, tuple[str, ...]]:
diff --git a/studio/backend/core/inference/family_profile.py b/studio/backend/core/inference/family_profile.py
index a4ec5a6df9e..3c785deea6f 100644
--- a/studio/backend/core/inference/family_profile.py
+++ b/studio/backend/core/inference/family_profile.py
@@ -29,7 +29,8 @@ class ConvRotSpec:
artifacts still validate. ``filename`` / ``repo`` name the hosted rotated build (only ``repo`` gets the rotated
name prepended), ``variant_repos`` the variant repos that host one under their own name, ``default_on`` whether
int8 rotates unless ``UNSLOTH_DIFFUSION_INT8_CONVROT`` turns it off (the rest are opt-in with ``=1``). ``group`` 0
- means no runtime rotation: the entry only names a hosted build whose rotation is baked into the file."""
+ means no runtime rotation: the entry only names a hosted build whose rotation is baked into the file.
+ ``hosted_plain``: older hosted int8 files are unrotated, so with ConvRot on only ``filename`` is read."""
group: int
suffixes: tuple[str, ...]
@@ -37,6 +38,7 @@ class ConvRotSpec:
repo: Optional[str] = None
variant_repos: tuple[str, ...] = ()
default_on: bool = False
+ hosted_plain: bool = False
@dataclass(frozen = True)
diff --git a/studio/backend/tests/fixtures/diffusion_family_data_freeze.json b/studio/backend/tests/fixtures/diffusion_family_data_freeze.json
index a27e7dea59c..070f935d5f3 100644
--- a/studio/backend/tests/fixtures/diffusion_family_data_freeze.json
+++ b/studio/backend/tests/fixtures/diffusion_family_data_freeze.json
@@ -1732,7 +1732,7 @@
"streamed_weight_only": [],
"zero_row": []
},
- "convrot_default_on": false,
+ "convrot_default_on": true,
"fp8": {
"convrot_filename": null,
"convrot_repo": null,
@@ -1748,11 +1748,27 @@
"zero_row": []
},
"int8": {
- "convrot_filename": null,
- "convrot_repo": null,
+ "convrot_filename": "FLUX.2-klein-4B-INT8-ConvRot.safetensors",
+ "convrot_repo": "unsloth/FLUX.2-klein-4B-FP8",
"convrot_spec": [
- 0,
- []
+ 256,
+ [
+ "context_embedder",
+ "attn.to_q",
+ "attn.to_k",
+ "attn.to_v",
+ "attn.to_out.0",
+ "attn.add_q_proj",
+ "attn.add_k_proj",
+ "attn.add_v_proj",
+ "attn.to_add_out",
+ "ff.linear_in",
+ "ff.linear_out",
+ "ff_context.linear_in",
+ "ff_context.linear_out",
+ "attn.to_qkv_mlp_proj",
+ "attn.to_out"
+ ]
],
"convrot_variant_repos": [],
"exclude": [
@@ -1844,7 +1860,7 @@
"streamed_weight_only": [],
"zero_row": []
},
- "convrot_default_on": false,
+ "convrot_default_on": true,
"fp8": {
"convrot_filename": null,
"convrot_repo": null,
@@ -1866,11 +1882,18 @@
"zero_row": []
},
"int8": {
- "convrot_filename": null,
- "convrot_repo": null,
+ "convrot_filename": "flux-3-image-klein-INT8-ConvRot.safetensors",
+ "convrot_repo": "unsloth/flux-3-image-klein-FP8",
"convrot_spec": [
- 0,
- []
+ 256,
+ [
+ "attn.to_q",
+ "attn.to_k",
+ "attn.to_v",
+ "attn.to_out.0",
+ "ff.linear_in",
+ "ff.linear_out"
+ ]
],
"convrot_variant_repos": [],
"exclude": [
@@ -1979,7 +2002,7 @@
"streamed_weight_only": [],
"zero_row": []
},
- "convrot_default_on": false,
+ "convrot_default_on": true,
"fp8": {
"convrot_filename": null,
"convrot_repo": null,
@@ -2004,8 +2027,15 @@
"convrot_filename": null,
"convrot_repo": null,
"convrot_spec": [
- 0,
- []
+ 256,
+ [
+ "attn.to_q",
+ "attn.to_k",
+ "attn.to_v",
+ "attn.to_out.0",
+ "ff.linear_in",
+ "ff.linear_out"
+ ]
],
"convrot_variant_repos": [],
"exclude": [
@@ -4592,6 +4622,48 @@
"time_embed"
],
"int8_family_convrot": {
+ "flux.2-klein": [
+ 256,
+ [
+ "context_embedder",
+ "attn.to_q",
+ "attn.to_k",
+ "attn.to_v",
+ "attn.to_out.0",
+ "attn.add_q_proj",
+ "attn.add_k_proj",
+ "attn.add_v_proj",
+ "attn.to_add_out",
+ "ff.linear_in",
+ "ff.linear_out",
+ "ff_context.linear_in",
+ "ff_context.linear_out",
+ "attn.to_qkv_mlp_proj",
+ "attn.to_out"
+ ]
+ ],
+ "flux.3-klein": [
+ 256,
+ [
+ "attn.to_q",
+ "attn.to_k",
+ "attn.to_v",
+ "attn.to_out.0",
+ "ff.linear_in",
+ "ff.linear_out"
+ ]
+ ],
+ "flux.3-klein-base": [
+ 256,
+ [
+ "attn.to_q",
+ "attn.to_k",
+ "attn.to_v",
+ "attn.to_out.0",
+ "ff.linear_in",
+ "ff.linear_out"
+ ]
+ ],
"moss-image": [
256,
[
@@ -4641,6 +4713,9 @@
]
},
"int8_family_convrot_default_on": [
+ "flux.2-klein",
+ "flux.3-klein",
+ "flux.3-klein-base",
"ltx-2.5",
"moss-image",
"moss-image-base",
@@ -4648,12 +4723,16 @@
"z-image"
],
"int8_family_convrot_filename": {
+ "flux.2-klein": "FLUX.2-klein-4B-INT8-ConvRot.safetensors",
+ "flux.3-klein": "flux-3-image-klein-INT8-ConvRot.safetensors",
"moss-image": "MOSS-Image-SFT-INT8-ConvRot.safetensors",
"moss-image-base": "MOSS-Image-SFT-INT8-ConvRot.safetensors",
"qwen-image-2.1": "Qwen-Image-2.1-INT8-ConvRot.safetensors",
"z-image": "Z-Image-Turbo-INT8-ConvRot.safetensors"
},
"int8_family_convrot_repo": {
+ "flux.2-klein": "unsloth/FLUX.2-klein-4B-FP8",
+ "flux.3-klein": "unsloth/flux-3-image-klein-FP8",
"moss-image": "unsloth/MOSS-Image-SFT-FP8",
"moss-image-base": "unsloth/MOSS-Image-SFT-FP8",
"qwen-image-2.1": "unsloth/Qwen-Image-2.1-FP8",
diff --git a/studio/backend/tests/test_diffusion_flux3.py b/studio/backend/tests/test_diffusion_flux3.py
index 67572011b41..69d36822ce6 100644
--- a/studio/backend/tests/test_diffusion_flux3.py
+++ b/studio/backend/tests/test_diffusion_flux3.py
@@ -686,13 +686,16 @@ def test_prequant_repos_point_each_variant_at_its_own_fp8_repo():
@pytest.mark.parametrize("variant", ["distilled", "base"])
@pytest.mark.parametrize("scheme, stem", [("int8", "INT8"), ("fp8", "FP8")])
-def test_prequant_filenames_resolve_to_the_built_safetensors(scheme, stem, variant):
+def test_prequant_filenames_resolve_to_the_built_safetensors(scheme, stem, variant, monkeypatch):
from core.inference.diffusion_prequant import candidate_filenames_of, resolve_prequant_source
name, base, model = {
"distilled": (FLUX3_KLEIN_FAMILY_NAME, DISTILLED, "flux-3-image-klein"),
"base": (FLUX3_KLEIN_BASE_FAMILY_NAME, BASE, "flux-3-image-klein-base"),
}[variant]
+ if variant == "distilled" and scheme == "int8":
+ # The hosted distilled int8 file is unrotated: read only with the ConvRot kill switch.
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_INT8_CONVROT", "0")
source = resolve_prequant_source(_family(name), scheme, base_repo = base)
assert source.kind == "repo" and source.location == f"unsloth/{model}-FP8"
names = candidate_filenames_of(source)
diff --git a/studio/backend/tests/test_diffusion_int8_runtime_convrot.py b/studio/backend/tests/test_diffusion_int8_runtime_convrot.py
index c1e3e15d663..69c4e559983 100644
--- a/studio/backend/tests/test_diffusion_int8_runtime_convrot.py
+++ b/studio/backend/tests/test_diffusion_int8_runtime_convrot.py
@@ -611,7 +611,6 @@ def test_qwen_image_21_offline_default_still_loads_the_cached_plain_artifact(mon
def test_qwen_image_21_rotated_set_is_exactly_the_int8_quantized_set(monkeypatch):
- # an int8-quantized but unrotated Linear would be a silent accuracy hole
monkeypatch.delenv(tq.INT8_CONVROT_ENV)
diffusers = pytest.importorskip("diffusers")
cls = getattr(diffusers, "QwenImage21Transformer2DModel", None)
@@ -628,3 +627,225 @@ def test_qwen_image_21_rotated_set_is_exactly_the_int8_quantized_set(monkeypatch
group, suffixes = tq.convrot_spec_for_scheme(tq.TQ_INT8, "qwen-image-2.1")
rotated = set(tq.convrot_fqns(model, filt, group, suffixes))
assert quantized and rotated == quantized
+
+
+# FLUX.2 klein (4B) and FLUX.3 klein Linear layouts (fqn, in, out), from the published diffusers checkpoints.
+_FLUX2_KLEIN_LINEARS = (
+ [("context_embedder", 7680, 3072), ("x_embedder", 128, 3072), ("proj_out", 3072, 128)]
+ + [("norm_out.linear", 3072, 6144), ("double_stream_modulation_img.linear", 3072, 18432)]
+ + [
+ ("double_stream_modulation_txt.linear", 3072, 18432),
+ ("single_stream_modulation.linear", 3072, 9216),
+ ]
+ + [("time_guidance_embed.timestep_embedder.linear_1", 256, 3072)]
+ + [("time_guidance_embed.timestep_embedder.linear_2", 3072, 3072)]
+ + [
+ (f"transformer_blocks.{i}.{n}", k, o)
+ for i in range(5)
+ for n, k, o in (
+ ("attn.to_q", 3072, 3072),
+ ("attn.to_k", 3072, 3072),
+ ("attn.to_v", 3072, 3072),
+ ("attn.to_out.0", 3072, 3072),
+ ("attn.add_q_proj", 3072, 3072),
+ ("attn.add_k_proj", 3072, 3072),
+ ("attn.add_v_proj", 3072, 3072),
+ ("attn.to_add_out", 3072, 3072),
+ ("ff.linear_in", 3072, 18432),
+ ("ff.linear_out", 9216, 3072),
+ ("ff_context.linear_in", 3072, 18432),
+ ("ff_context.linear_out", 9216, 3072),
+ )
+ ]
+ + [
+ (f"single_transformer_blocks.{i}.{n}", k, o)
+ for i in range(20)
+ for n, k, o in (("attn.to_qkv_mlp_proj", 3072, 27648), ("attn.to_out", 12288, 3072))
+ ]
+)
+_FLUX3_BLOCK = (
+ ("attn.to_q", 3072, 3072),
+ ("attn.to_k", 3072, 3072),
+ ("attn.to_v", 3072, 3072),
+ ("attn.to_out.0", 3072, 3072),
+ ("ff.linear_in", 3072, 18432),
+ ("ff.linear_out", 9216, 3072),
+)
+_FLUX3_LINEARS = (
+ [("context_embedder", 20480, 3072), ("proj_out", 3072, 128), ("norm_out.linear", 3072, 6144)]
+ + [("x_embedders.image", 128, 3072), ("x_embedders.image_cond", 128, 3072)]
+ + [("timestep_embedder.linear_1", 256, 3072), ("timestep_embedder.linear_2", 3072, 3072)]
+ + [
+ (f"{s}_stream_modulations.{m}.linear", 3072, 9216)
+ for s in ("early", "single")
+ for m in ("image", "image_cond", "txt")
+ ]
+ + [
+ (f"mode_blocks.{m}.{i}.{n}", k, o)
+ for m in ("image", "image_cond")
+ for i in range(5)
+ for n, k, o in _FLUX3_BLOCK
+ ]
+ + [(f"txt_mode_blocks.{i}.{n}", k, o) for i in range(5) for n, k, o in _FLUX3_BLOCK]
+ + [(f"single_transformer_blocks.{i}.{n}", k, o) for i in range(28) for n, k, o in _FLUX3_BLOCK]
+)
+
+
+def _skeleton(linears):
+ """Meta-device module tree with exactly these Linear fqns and shapes."""
+ root = nn.Module()
+ for fqn, k, o in linears:
+ parent = root
+ *path, leaf = fqn.split(".")
+ for part in path:
+ if not hasattr(parent, part):
+ parent.add_module(part, nn.Module())
+ parent = getattr(parent, part)
+ parent.add_module(leaf, nn.Linear(k, o, bias = True, device = "meta"))
+ return root
+
+
+ "family, linears, expect",
+ [
+ ("flux.2-klein", _FLUX2_KLEIN_LINEARS, 101),
+ ("flux.3-klein", _FLUX3_LINEARS, 228),
+ ("flux.3-klein-base", _FLUX3_LINEARS, 228),
+ ],
+)
+def test_flux_rotated_set_is_exactly_the_int8_quantized_set(monkeypatch, family, linears, expect):
+ monkeypatch.delenv(tq.INT8_CONVROT_ENV)
+ model = _skeleton(linears)
+ filt = _filter(family)
+ quantized = {n for n, m in model.named_modules() if isinstance(m, nn.Linear) and filt(m, n)}
+ group, suffixes = tq.convrot_spec_for_scheme(tq.TQ_INT8, family)
+ assert group == 256
+ rotated = set(tq.convrot_fqns(model, filt, group, suffixes))
+ assert len(quantized) == expect
+ assert rotated == quantized
+ # FLUX.3's keep-list (text-stream blocks, modulations, context_embedder) stays dense and unrotated
+ assert (
+ not any(n.startswith(("txt_mode_blocks.", "context_embedder")) for n in rotated)
+ or family == "flux.2-klein"
+ )
+
+
[email protected]("family", ["flux.2-klein", "flux.3-klein", "flux.3-klein-base"])
+def test_flux_convrot_is_default_on_and_the_env_is_its_kill_switch(monkeypatch, family):
+ monkeypatch.delenv(tq.INT8_CONVROT_ENV)
+ assert tq.int8_convrot_enabled(family)
+ for off in ("0", "off", "false", "no"):
+ monkeypatch.setenv(tq.INT8_CONVROT_ENV, off)
+ assert not tq.int8_convrot_enabled(family)
+ model = _skeleton(_FLUX2_KLEIN_LINEARS if family == "flux.2-klein" else _FLUX3_LINEARS)
+ assert tq.apply_runtime_convrot(model, tq.TQ_INT8, family, _filter(family)) == ()
+ monkeypatch.delenv(tq.INT8_CONVROT_ENV)
+ for other in ("flux.2-dev", "flux.1", "flux.1-kontext"):
+ assert tq.convrot_spec_for_scheme(tq.TQ_INT8, other) == (0, ())
+ assert not tq.int8_convrot_enabled(other)
+
+
+ "repo, hosted, rotated",
+ [
+ (
+ "black-forest-labs/FLUX.2-klein-4B",
+ "unsloth/FLUX.2-klein-4B-FP8",
+ "FLUX.2-klein-4B-INT8-ConvRot.safetensors",
+ ),
+ (
+ "black-forest-labs/flux-3-image-klein",
+ "unsloth/flux-3-image-klein-FP8",
+ "flux-3-image-klein-INT8-ConvRot.safetensors",
+ ),
+ ],
+)
+def test_flux_int8_reads_only_the_rotated_hosted_file_unless_killed(
+ monkeypatch, repo, hosted, rotated
+):
+ # Default names only the rotated file; the kill switch names only the unrotated one.
+ from core.inference import diffusion_prequant as pq
+ from core.inference import diffusion_prequant_cache as pqc
+ from core.inference.diffusion_families import detect_family
+
+ monkeypatch.setattr(pqc, "lookup", lambda *a, **k: None)
+ fam = detect_family(repo)
+ monkeypatch.delenv(tq.INT8_CONVROT_ENV)
+ assert tq.convrot_drops_plain_hosted(tq.TQ_INT8, fam.name)
+ assert not tq.convrot_drops_plain_hosted(tq.TQ_FP8, fam.name)
+ source = pq.resolve_prequant_source(fam, "int8")
+ assert source.kind == "repo" and source.location == hosted
+ assert candidate_filenames_of(source) == (rotated,)
+ monkeypatch.setenv(tq.INT8_CONVROT_ENV, "0")
+ plain = pq.resolve_prequant_source(fam, "int8")
+ assert plain.kind == "repo" and plain.location == hosted
+ names = candidate_filenames_of(plain)
+ assert names and not any("ConvRot" in n for n in names)
+ for env in ("0", "1"):
+ monkeypatch.setenv(tq.INT8_CONVROT_ENV, env)
+ fp8 = pq.resolve_prequant_source(fam, "fp8")
+ assert fp8.kind == "repo" and not any("ConvRot" in n for n in candidate_filenames_of(fp8))
+
+
+def test_flux_missing_rotated_file_falls_back_to_the_rotated_load_time_build(monkeypatch, tmp_path):
+ # Before the rotated file is published: the hub 404s, the plain file is never fetched, the load quantizes.
+ from huggingface_hub.errors import EntryNotFoundError
+
+ from core.inference import diffusion_prequant as pq
+ from core.inference.diffusion_families import detect_family
+
+ monkeypatch.delenv(tq.INT8_CONVROT_ENV)
+ monkeypatch.setattr(pq, "restricted_prequant_load_supported", lambda *a, **k: True)
+ monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
+ asked = []
+
+ def _dl(
+ repo_id,
+ filename,
+ token = None,
+ cache_dir = None,
+ local_files_only = False,
+ ):
+ asked.append(filename)
+ raise EntryNotFoundError("404")
+
+ monkeypatch.setattr("huggingface_hub.hf_hub_download", _dl)
+ source = pq.resolve_prequant_source(detect_family("black-forest-labs/FLUX.2-klein-4B"), "int8")
+ with pytest.raises(EntryNotFoundError):
+ pq._resolve_checkpoint_path(source, None, None)
+ assert asked and all("ConvRot" in n for n in asked)
+
+
+def test_flux3_base_keeps_its_hosted_rotated_int8(monkeypatch):
+ # BFL's hosted int8_convrot denoiser is already rotated: still read by default
+ from core.inference import diffusion_prequant as pq
+ from core.inference.diffusion_families import detect_family
+
+ monkeypatch.delenv(tq.INT8_CONVROT_ENV)
+ fam = detect_family("black-forest-labs/flux-3-image-klein-base")
+ assert fam.name == "flux.3-klein-base"
+ assert not tq.convrot_drops_plain_hosted(tq.TQ_INT8, fam.name)
+ source = pq.resolve_prequant_source(fam, "int8")
+ assert source is not None and source.kind == "repo"
+ assert "flux-3-image-klein-base-INT8.safetensors" in candidate_filenames_of(source)
+
+
+def test_hosted_plain_skip_is_only_on_the_flux_klein_families():
+ assert tq._INT8_FAMILY_CONVROT_HOSTED_PLAIN == frozenset({"flux.2-klein", "flux.3-klein"})
+
+
+def test_flux_klein_runtime_int8_rotates_by_default(monkeypatch):
+ monkeypatch.delenv(tq.INT8_CONVROT_ENV)
+ seen = []
+ _stub_torchao(monkeypatch, seen)
+ monkeypatch.setattr(
+ tq, "select_transformer_quant_scheme", lambda target, mode, family = None, **_: tq.TQ_INT8
+ )
+ small = [
+ (n, 512 if k >= 512 else k, 512 if o >= 512 else o) for n, k, o in _FLUX2_KLEIN_LINEARS
+ ]
+ model = _skeleton(small).to_empty(device = "cpu")
+ pipe = types.SimpleNamespace(transformer = model)
+ assert tq.quantize_transformer(pipe, object(), mode = "int8", family = "flux.2-klein") == tq.TQ_INT8
+ assert len(seen) == 1 and len(seen[0]) == 101
+ assert getattr(model, CONVROT_ATTR)["linears"] == 101