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: FLUX.3 Image Klein (distilled and base), with INT8 / FP8 / GGUF support (#13933)

Daniel Han5019141cf547
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 82d5db085c5..42b90988391 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -32,7 +32,7 @@ import time
import traceback
from dataclasses import dataclass, replace
from pathlib import Path
-from typing import Any, Callable, Optional, Sequence
+from typing import Any, Callable, Mapping, Optional, Sequence
from core._torchao_stub import (
alias_torchao_fqn_to_config,
@@ -66,6 +66,7 @@ from .diffusion_families import (
local_pipeline_components_are_complete,
_family_override_resolved,
assert_flux2_gguf_matches_base,
+ assert_flux3_checkpoint_matches_family,
assert_pipeline_class_available,
_is_local_path,
canonical_base,
@@ -86,8 +87,10 @@ from .diffusion_families import (
)
from .diffusion_compat import (
assert_flux2_pick_compatible,
+ assert_flux3_pick_compatible,
assert_pick_is_not_speech,
flux2_pick_mismatch,
+ flux3_pick_mismatch,
speech_pick_refusal,
)
from .diffusion_device import (
@@ -119,6 +122,14 @@ from .diffusion_hidream import (
hidream_te4_kwargs,
)
from .diffusion_krea2 import KREA2_FAMILY_NAME, load_krea2_pipeline
+from .diffusion_flux3 import (
+ FLUX3_COMPONENTS,
+ FLUX3_COMPONENT_FOLDERS,
+ FLUX3_INDEX,
+ is_flux3_family,
+ load_flux3_pipeline,
+)
+from .diffusion_flux3 import REFERENCE_AREA as FLUX3_REFERENCE_AREA
from .diffusion_small_host import (
INT8_DENOISER_NAMES,
decide_small_host,
@@ -595,7 +606,7 @@ def _baked_lora_names(pipe: Any) -> list:
def resolve_local_single_file(model_path: str) -> Optional[str]:
"""The sole single-file checkpoint basename in a local ``model_path`` directory that is NOT a
- diffusers pipeline (no ``model_index.json``) and holds exactly one ``.safetensors`` file, else
+ diffusers pipeline (no ``model_index.json`` or FLUX.3 ``modular_model_index.json``) and holds exactly one ``.safetensors`` file, else
None.
The On-Device scanner advertises a bare single-file safetensors directory as a text-to-image
@@ -607,7 +618,9 @@ def resolve_local_single_file(model_path: str) -> Optional[str]:
"""
try:
root = Path(model_path).expanduser()
- if not root.is_dir() or (root / "model_index.json").is_file():
+ if not root.is_dir() or any(
+ (root / index).is_file() for index in ("model_index.json", FLUX3_INDEX)
+ ):
return None
# A PEFT adapter folder is not a base checkpoint; skip it so validation 400s before eviction
if (root / "adapter_config.json").is_file():
@@ -860,8 +873,10 @@ def _assert_local_base_is_pipeline(
base_repo: str,
*,
allow_modular: bool = False,
+ modular_only: bool = False,
excluded_components: Sequence[str] = (),
config_only_model_components: bool = False,
+ fixed_component_folders: Optional[Mapping[str, tuple[str, str, str]]] = None,
) -> None:
"""A companion ``base_repo`` fed to ``from_pretrained(base)`` (or ``config=base``) must be a
diffusers PIPELINE directory (has ``model_index.json``). ``_is_trusted_diffusion_repo`` accepts
@@ -874,7 +889,8 @@ def _assert_local_base_is_pipeline(
``allow_modular`` accepts ``modular_model_index.json`` as well, for a caller whose loader is
``ModularPipeline.from_pretrained``: that IS the valid on-disk layout for a Modular Diffusers
pipeline (MiniMax-H3 ships no ``model_index.json`` at all). Off by default: a conventional
- ``DiffusionPipeline`` load still needs the conventional index.
+ ``DiffusionPipeline`` load still needs the conventional index. ``modular_only`` accepts nothing else, for a
+ loader that reads only the modular index (FLUX.3).
``excluded_components`` are supplied by the caller (the checkpoint's denoiser), not the base;
``config_only_model_components`` means the base only supplies component configs."""
@@ -888,8 +904,8 @@ def _assert_local_base_is_pipeline(
return # invalid path characters -> a remote id, not a local path
if not exists:
return
- indexes = ["model_index.json"]
- if allow_modular:
+ indexes = [] if modular_only else ["model_index.json"]
+ if allow_modular or modular_only:
indexes.append("modular_model_index.json")
if not root.is_dir() or not any(
local_pipeline_components_are_complete(
@@ -897,6 +913,7 @@ def _assert_local_base_is_pipeline(
name,
excluded_components = excluded_components,
config_only_model_components = config_only_model_components,
+ fixed_component_folders = fixed_component_folders,
)
for name in indexes
):
@@ -1130,6 +1147,27 @@ def _with_supplied_components(load: Callable[..., dict]) -> Callable[..., dict]:
return wrapper
+def _generation_chunks(
+ family: Any,
+ jobs: list,
+ batch_size: int,
+ *,
+ layer_count: Any = None,
+) -> list:
+ """Per-forward chunks of ``(prompt, seed)`` jobs. Layered: one input per forward. FLUX.3 runs one image per
+ modular call, so each image is its own chunk: every one then gets its own encode, denoise and decode phase, and
+ the text-encoder release that comes with entering denoise (one chunk of several images would release it once,
+ and the next image's encode would bring it back for the rest of the chunk)."""
+ if layer_count or is_flux3_family(family):
+ return [[job] for job in jobs]
+ return chunk_jobs(jobs, batch_size)
+
+
+def _base_manifest_name(fam: Any) -> str:
+ """The pipeline index a base repo carries: FLUX.3 ships only ``modular_model_index.json``."""
+ return FLUX3_INDEX if is_flux3_family(fam) else "model_index.json"
+
+
def _te_quant_for_supplied_encoders(requested: Optional[str]) -> Optional[str]:
"""Unset / auto never re-casts a supplied encoder (it would fetch the hosted encoder the file replaces)."""
if requested is None or str(requested).strip().lower() in ("", "auto"):
@@ -1564,13 +1602,23 @@ def _generation_defaults_for(
gguf_filename: Optional[str],
base_repo: Optional[str],
grid: Optional[tuple[float, ...]] = None,
+ family: Any = None,
) -> Optional[dict[str, float]]:
"""The (steps, guidance) the OpenAI route renders this load with, header variant before base (FLUX.1's base is
schnell), so the Images form can match it."""
try:
- steps, guidance = generation_params_with_grid(
- grid, gguf_filename, content_variant_hint(repo_id, gguf_filename), repo_id, base_repo
+ # FLUX.3 first: the variant check has matched the checkpoint to the family, while the names cannot tell the
+ # variants apart (BFL's ComfyUI base files are flux3_image_klein_*.safetensors, no "base", and a base file can
+ # sit on the distilled repo's companions).
+ identifiers = (
+ gguf_filename,
+ content_variant_hint(repo_id, gguf_filename),
+ repo_id,
+ base_repo,
)
+ if is_flux3_family(family):
+ identifiers = (family.name,) + identifiers
+ steps, guidance = generation_params_with_grid(grid, *identifiers)
except Exception: # noqa: BLE001 - status must not fail on a recipe lookup
return None
return {"steps": int(steps), "guidance": float(guidance)}
@@ -1926,8 +1974,11 @@ def _calibrated_activation(fam: Any, target: Any) -> Any:
if getattr(target, "backend", None) != "cuda" or getattr(target, "vendor", None) != "nvidia":
return None
# Measured without input images: references the guard cannot size (no reference_resolutions) would overflow.
- if getattr(fam, "reference", False) and not tuple(
- getattr(fam, "reference_resolutions", ()) or ()
+ # FLUX.3 can: every reference is resized to 1 MP and the request guard charges those pixels on top.
+ if (
+ getattr(fam, "reference", False)
+ and not tuple(getattr(fam, "reference_resolutions", ()) or ())
+ and not is_flux3_family(fam)
):
return None
# Measured at 16-bit only; fp32-promoted families (Z-Image pre-Ampere) do not qualify.
@@ -2912,6 +2963,12 @@ class DiffusionBackend:
# torchao. Refusing on the raw int8 rejected loads the runtime would run and report as fell_back.
te_effective = effective_te_quant(te_mode, getattr(fam, "name", None))
te_reason = None
+ if te_mode == "int8" and te_effective != te_mode:
+ from .diffusion_te_prequant import hosted_int8_convrot_te_runs_on
+ if hosted_int8_convrot_te_runs_on(fam, target):
+ # The family's hosted int8 ConvRot encoder (FLUX.3, Qwen-Image-2.1) is plain tensors and runs where the
+ # runtime-cast rewrite to fp8 does not (Apple Silicon): judge the file, not the downgrade.
+ te_effective = None
if te_quant_needs_resident_weights(te_effective) and not torchao_quantize_importable():
# The casters import torchao only after the pipeline is downloaded and built, so a broken or absent
# install failed through load-progress instead of this 409.
@@ -3290,10 +3347,12 @@ class DiffusionBackend:
fetch_base: Optional[str] = None,
base_local_dir: Optional[str] = None,
local_files_only: bool = False,
+ manifest: str = "model_index.json",
) -> Optional[str]:
"""Stage the shards a seeded plan left out of the pull; returns the snapshot dir to assemble
from, or None for the hub id. ``from_pretrained`` treats a local dir as terminal, so a
- failed seed has nothing."""
+ failed seed has nothing. ``manifest`` is the base's pipeline index (FLUX.3's is the modular one), fetched
+ with the shards so the top-up resolves the same snapshot."""
files = [name for name in (skipped or ()) if name]
if not files:
return base_local_dir
@@ -3306,7 +3365,7 @@ class DiffusionBackend:
repo_id,
None,
base,
- [*files, "model_index.json"],
+ [*files, manifest],
hf_token,
fetch_base = fetch_base,
local_files_only = local_files_only,
@@ -3413,7 +3472,8 @@ class DiffusionBackend:
except (IndexError, ValueError, OSError):
root = ""
roots.add(root)
- if rfilename == "model_index.json":
+ # FLUX.3's manifest is the modular one; either marks the snapshot the companions were staged into.
+ if rfilename in ("model_index.json", FLUX3_INDEX):
snapshot_root = root or None
# Only hand back a snapshot the whole set lives in; otherwise the hub id resolves each file through its own
# root as before.
@@ -3437,6 +3497,14 @@ class DiffusionBackend:
"text_encoder_file / vae_file load beside a single-file or GGUF transformer; a full pipeline "
"(or a whole-pipeline single file) already carries its own text encoders and VAE."
)
+ if is_flux3_family(fam):
+ # The supplied-component loader resolves classes from a model_index.json, which FLUX.3 does not ship, and
+ # its encoder is a Qwen3-VL with its processor in the same folder: refuse up front rather than load the
+ # official encoder and VAE in place of the files the user picked.
+ raise ValueError(
+ f"separate text encoder / VAE files are not supported for '{fam.name}' yet; omit "
+ "text_encoder_files and vae_file (the base repo's encoder and VAE are used)."
+ )
if vae_file and fam.name == KREA2_FAMILY_NAME:
raise ValueError(
f"a separate VAE file is not supported for '{fam.name}' yet; omit vae_file."
@@ -3701,7 +3769,13 @@ class DiffusionBackend:
(fam.denoiser_attr,) if kind in ("gguf", "single_file") and not whole_file else ()
)
_assert_local_base_is_pipeline(
- base_repo, excluded_components = excluded, config_only_model_components = whole_file
+ base_repo,
+ # FLUX.3 companions come from a Modular Diffusers base, and its loader reads only modular_model_index.json.
+ modular_only = is_flux3_family(fam),
+ excluded_components = excluded,
+ config_only_model_components = whole_file,
+ # The FLUX.3 assembler reads each component from its own folder here, never from a spec's source repo.
+ fixed_component_folders = FLUX3_COMPONENT_FOLDERS if is_flux3_family(fam) else None,
)
local_root = Path(repo_id).expanduser()
# Path-shaped: "."/".." prefix, a backslash (never in "org/name"), or an absolute path.
@@ -3733,9 +3807,17 @@ class DiffusionBackend:
"a 'pipeline' load takes a full diffusers repo, not a single-file name."
)
if local_root.exists():
- if not local_pipeline_components_are_complete(local_root, "model_index.json"):
+ # FLUX.3 is a Modular Diffusers layout: its manifest is modular_model_index.json.
+ index_name = FLUX3_INDEX if is_flux3_family(fam) else "model_index.json"
+ if not local_pipeline_components_are_complete(
+ local_root,
+ index_name,
+ fixed_component_folders = (
+ FLUX3_COMPONENT_FOLDERS if is_flux3_family(fam) else None
+ ),
+ ):
raise FileNotFoundError(
- f"Local pipeline directory has no complete valid model_index.json: {repo_id}"
+ f"Local pipeline directory has no complete valid {index_name}: {repo_id}"
)
elif path_shaped:
raise FileNotFoundError(f"Local model path does not exist: {repo_id}")
@@ -3776,12 +3858,16 @@ class DiffusionBackend:
# Probe the repo the load will FETCH from: refusing the upstream id would reject the gated picks the ungated
# mirror rescues, and the swap is pure, so it decides the same here as on the load thread. Only the raise
# matters; _run_load recomputes the excused snapshot.
- _assert_base_repo_accessible(prefer_ungated_mirror(base, hf_token), hf_token)
+ _assert_base_repo_accessible(
+ prefer_ungated_mirror(base, hf_token), hf_token, _base_manifest_name(fam)
+ )
# Same reasoning for the FLUX.2 size pairing, and this is the only place it can be caught before a teardown:
# the loader's own guard opens the downloaded checkpoint, so it fires after ~19 GB of base shards AND after
# the resident pipeline was freed. Metadata only, and fails open on anything it cannot read. The UPSTREAM
# base, not the mirror: the size tables key on vendor ids.
assert_flux2_pick_compatible(fam, repo_id, gguf_filename, base, hf_token)
+ # FLUX.3's variant check (distilled vs base, BFL quantized packages) off the header, for the same reason.
+ assert_flux3_pick_compatible(fam, repo_id, gguf_filename, hf_token)
# No media backend decodes a speech GGUF, and detect_family_for_pick answers from the folder name, so a csm
# file beside a denoiser reaches this loader as one of its own. Cache-only for a load nobody asked for: this
# probe would otherwise spend a revision HEAD, or a range request, on the one path that promised to stay off
@@ -4073,6 +4159,8 @@ class DiffusionBackend:
kind = kind,
pipeline_components = _explicit_pipeline_components(fam),
single_file_is_pipeline = bool(fam and fam.single_file_is_pipeline),
+ companion_components = FLUX3_COMPONENTS if is_flux3_family(fam) else None,
+ base_manifest = _base_manifest_name(fam),
include_transformer = (
(
lambda companions, transformer_files: self._dense_quant_prefetch_needed(
@@ -4147,7 +4235,10 @@ class DiffusionBackend:
# metadata, so no byte has moved yet. Returns a snapshot dir when it excused the base off a copy only the
# import-time root holds.
base_snapshot = _assert_base_repo_accessible(
- fetch_base, kwargs.get("hf_token"), local_files_only = local_files_only
+ fetch_base,
+ kwargs.get("hf_token"),
+ _base_manifest_name(fam),
+ local_files_only = local_files_only,
)
# And the same size-pairing preflight the plan and the route run, here because a direct begin_load (a
# saved config, the deploy path) reaches neither. Still metadata only, so it lands before _prefetch_files
@@ -4155,6 +4246,13 @@ class DiffusionBackend:
assert_flux2_pick_compatible(
fam, kwargs["repo_id"], kwargs.get("gguf_filename"), base, kwargs.get("hf_token")
)
+ assert_flux3_pick_compatible(
+ fam,
+ kwargs["repo_id"],
+ kwargs.get("gguf_filename"),
+ kwargs.get("hf_token"),
+ allow_network = not local_files_only,
+ )
# Same verdict here, so a direct begin_load is covered too.
assert_pick_is_not_speech(
kwargs["repo_id"],
@@ -4894,6 +4992,8 @@ class DiffusionBackend:
pipeline_components: Optional[Sequence[str]] = None,
single_file_is_pipeline: bool = False,
include_transformer: "bool | Callable[[Sequence[str], Sequence[str]], bool]" = False,
+ companion_components: Optional[Sequence[str]] = None,
+ base_manifest: str = "model_index.json",
sizes_out: Optional[dict[str, int]] = None,
file_sizes_out: Optional[dict[str, dict[str, int]]] = None,
resident_file_sizes_out: Optional[list[tuple[str, int]]] = None,
@@ -4995,9 +5095,9 @@ class DiffusionBackend:
skipped_files_out[:] = [s.rfilename for s in seeded]
return info, components, picked
- metadata_repo = prefer_ungated_mirror(
- repo_id, hf_token, files = ("model_index.json",)
- )
+ # The family's own index: FLUX.3 ships only modular_model_index.json, so probing
+ # model_index.json would never find a cached upstream and restage the mirror.
+ metadata_repo = prefer_ungated_mirror(repo_id, hf_token, files = (base_manifest,))
info, components, picked = _pipeline_listing(metadata_repo)
base_files = [s.rfilename for s in picked]
fetch_repo = prefer_ungated_mirror(repo_id, hf_token, files = base_files)
@@ -5039,20 +5139,48 @@ class DiffusionBackend:
else:
def base_filter(rfilename: str) -> bool:
- return _base_file_downloaded(rfilename, include_transformer = include_transformer)
+ # ``companion_components``: an assembler that opens only these folders (FLUX.3), so the rest of
+ # the base (BFL's variants/ packages) is never staged; transformer/ still follows the quant path.
+ if (
+ companion_components is not None
+ and "/" in rfilename
+ and rfilename.split("/", 1)[0] not in companion_components
+ ):
+ return False
+ return _base_file_downloaded(
+ rfilename, include_transformer = include_transformer, manifest = base_manifest
+ )
- base_info = api.model_info(base_repo, files_metadata = True, token = hf_token)
- _record_revision(revisions_out, base_repo, base_info)
+ # FLUX.3's mirror is its FP8 repo, whose companion folders are BFL's byte for byte and whose extra root
+ # files base_filter never stages, so the listing comes from the repo the prefetch pulls: an anonymous
+ # load then never asks the gated vendor repo anything. Its revision is the mirror's, recorded under it.
+ listing_repo = (
+ prefer_ungated_mirror(base_repo, hf_token)
+ if companion_components is not None
+ else base_repo
+ )
+ base_info = api.model_info(listing_repo, files_metadata = True, token = hf_token)
+ _record_revision(revisions_out, listing_repo, base_info)
if callable(include_transformer):
kept = [s.rfilename for s in base_info.siblings if not _dense_te_shard(s.rfilename)]
companions = tuple(
- f for f in kept if _base_file_downloaded(f, include_transformer = False)
+ f
+ for f in kept
+ if _base_file_downloaded(f, include_transformer = False, manifest = base_manifest)
+ and (
+ companion_components is None
+ or "/" not in f
+ or f.split("/", 1)[0] in companion_components
+ )
)
skip = set(companions)
transformer_files = tuple(
f
for f in kept
- if f not in skip and _base_file_downloaded(f, include_transformer = True)
+ if f not in skip
+ and _base_file_downloaded(f, include_transformer = True, manifest = base_manifest)
+ # A scoped assembler's dense loader opens only transformer/, not BFL's variants/ packages.
+ and (companion_components is None or f.split("/", 1)[0] == "transformer")
)
# Rebinding before base_filter is ever CALLED, so the loop below reads the answer.
include_transformer = bool(include_transformer(companions, transformer_files))
@@ -5075,7 +5203,7 @@ class DiffusionBackend:
sizes_out[base_repo] = sizes_out.get(base_repo, 0) + base_bytes
if file_sizes_out is not None:
file_sizes_out.setdefault(base_repo, {}).update(base_sizes)
- _record_revision(revisions_out, base_repo, base_info)
+ _record_revision(revisions_out, listing_repo, base_info)
except Exception as exc: # noqa: BLE001 - estimate is best-effort
logger.warning("diffusion.size_estimate_failed: %s", exc)
# Recorded so a caller that must not guess (media auto-switch refuses rather than download) can tell a
@@ -5135,9 +5263,12 @@ class DiffusionBackend:
# SELECTION time. Metadata only, and None whenever nothing is known to be wrong. The speech verdict belongs
# here too, not only on the load preflight: the Images page stages and downloads before it calls load, so a
# later refusal arrives after the bytes.
- incompatible = flux2_pick_mismatch(
- fam, repo_id, gguf_filename, base, hf_token
- ) or speech_pick_refusal(repo_id, gguf_filename, hf_token)
+ incompatible = (
+ flux2_pick_mismatch(fam, repo_id, gguf_filename, base, hf_token)
+ # The FLUX.3 variant / BFL-package verdict, off the header or the manifest, for the same reason.
+ or flux3_pick_mismatch(fam, repo_id, gguf_filename, hf_token)
+ or speech_pick_refusal(repo_id, gguf_filename, hf_token)
+ )
component_overrides = None
if (
discover_text_encoders
@@ -5252,6 +5383,8 @@ class DiffusionBackend:
kind = kind,
pipeline_components = _explicit_pipeline_components(fam),
single_file_is_pipeline = bool(fam and fam.single_file_is_pipeline),
+ companion_components = FLUX3_COMPONENTS if is_flux3_family(fam) else None,
+ base_manifest = _base_manifest_name(fam),
# The RESOLVED base, as the load passes it: a variant base picks its own pre-quant repo. Deferred exactly
# as _run_load defers it. Called eagerly this runs before the base listing exists, so the cache gate sees
# no transformer shards, always declines, and the plan scopes narrower than the load: the registry then
@@ -5290,7 +5423,7 @@ class DiffusionBackend:
fetch_base = fetch_repos.get(base) or prefer_ungated_mirror(
base, hf_token, files = base_files
)
- _assert_base_repo_accessible(fetch_base, hf_token)
+ _assert_base_repo_accessible(fetch_base, hf_token, _base_manifest_name(fam))
entries: list[dict[str, Any]] = []
checkpoint_bytes = 0
if gguf_filename:
@@ -5827,8 +5960,10 @@ class DiffusionBackend:
continue
if exclude_transformer and rel.parts and rel.parts[0] == "transformer":
continue
+ # from_pretrained reads <component>/<file> only: a deeper tree (FLUX.3's variants/fp8r, variants/nvfp4
+ # quantised packages) is never loaded and must not be priced.
if load_itemsize is not None and (
- len(rel.parts) < 2 or not _pipeline_default_variant_file(rel.as_posix())
+ len(rel.parts) != 2 or not _pipeline_default_variant_file(rel.as_posix())
):
continue
try:
@@ -6118,12 +6253,12 @@ class DiffusionBackend:
Uncached checkpoints are priced from the family table (``exact=False``). Never raises."""
try:
from .diffusion_te_prequant import (
- TE_INT8_CONVROT_BUDGET_SCALE,
TE_PREQUANT_BUDGET_SCALE,
TE_PREQUANT_COMPONENTS,
int8_convrot_te_runs_on,
te_candidate_filenames,
te_candidate_is_readable,
+ te_int8_convrot_budget_scale,
te_prequant_sources_for_base,
)
@@ -6205,7 +6340,7 @@ class DiffusionBackend:
share = table_priced / max(1, len(sources))
# MPS only takes the int8 ConvRot file, smaller than the fp8 one.
scale = (
- TE_INT8_CONVROT_BUDGET_SCALE
+ te_int8_convrot_budget_scale(fam)
if int8_convrot_te_runs_on(target)
else TE_PREQUANT_BUDGET_SCALE
)
@@ -6479,6 +6614,7 @@ class DiffusionBackend:
# Admitted per file: prove it is a safetensors container before any probe or loader opens it.
assert_safetensors_file(single_file_path)
assert_flux2_gguf_matches_base(fam, base, single_file_path)
+ assert_flux3_checkpoint_matches_family(fam, single_file_path)
# A ComfyUI-quantized file loads through its own path below; a format it cannot run is refused here,
# from the header, before planning or reading a weight, rather than loaded with its scales dropped.
comfy_scan = refuse_comfy_quant(single_file_path) if kind == "single_file" else None
@@ -7510,6 +7646,12 @@ class DiffusionBackend:
else _base_local_dir
)
or (fetch_base if local_files_only else None),
+ # the config from the dir assembly reads, the id for checkpoint compatibility
+ config_source = (
+ None
+ if fam.name == KREA2_FAMILY_NAME
+ else _base_local_dir
+ ),
)
)
if pipeline_seed_scheme is not None:
@@ -7591,6 +7733,7 @@ class DiffusionBackend:
fetch_base = fetch_base,
base_local_dir = _base_local_dir,
local_files_only = local_files_only,
+ manifest = _base_manifest_name(fam),
)
# A pipeline plan prices CACHED bytes, and the plan above saw companions only
# (transformer/ was skipped). Re-plan now the dense shards are back, else an
@@ -7612,7 +7755,25 @@ class DiffusionBackend:
bf16_pipeline_plan = plan
self._raise_if_load_cancelled(_load_token)
small_host = None
- if fam.name == KREA2_FAMILY_NAME:
+ if is_flux3_family(fam):
+ # FLUX.3 ships modular blocks only: assemble per component behind the classic
+ # face (diffusion_flux3), from the staged dir when there is one.
+ try:
+ pipe = load_flux3_pipeline(
+ _base_local_dir or fetch_base,
+ dtype,
+ hf_token = hf_token,
+ check_cancelled = lambda: self._raise_if_load_cancelled(
+ _load_token
+ ),
+ local_files_only = local_files_only,
+ text_encoder = pipe_kwargs.get("text_encoder"),
+ transformer = pipe_kwargs.get("transformer"),
+ family_name = fam.name,
+ )
+ finally:
+ self._stop_load_prefetch()
+ elif fam.name == KREA2_FAMILY_NAME:
# krea's transformers-5.x configs break the 4.x line: assemble per component from
# pipe_kwargs (pre-cast TE, seeded denoiser or None = dense shards).
try:
@@ -7702,7 +7863,11 @@ class DiffusionBackend:
# Transformer-only single file; VAE/text-encoder/scheduler come from the base repo.
sf_kwargs: dict[str, Any] = {
"torch_dtype": dtype,
- "config": fetch_base,
+ # FLUX.3 reads the config from the staged companions, as its assembly below does: the
+ # validated base holds transformer/config.json, and fetch_base would re-resolve it.
+ "config": (_base_local_dir or fetch_base)
+ if is_flux3_family(fam)
+ else fetch_base,
"subfolder": "transformer",
"token": hf_token,
"cache_dir": hub_cache_dir(),
@@ -7780,7 +7945,35 @@ class DiffusionBackend:
_dequantize_gguf_outside_linears(transformer, dtype, logger)
self._raise_if_load_cancelled(_load_token)
- if fam.name == KREA2_FAMILY_NAME:
+ if is_flux3_family(fam):
+ # The single file / GGUF is the denoiser; the modular companions come from the base.
+ # From the staged dir when the prefetch resolved one, as every other assembly does: a plan
+ # that found the companions under another cache root must not re-resolve them here.
+ pipe = load_flux3_pipeline(
+ _base_local_dir or fetch_base,
+ dtype,
+ hf_token = hf_token,
+ check_cancelled = lambda: self._raise_if_load_cancelled(
+ _load_token
+ ),
+ transformer = transformer,
+ local_files_only = local_files_only,
+ text_encoder = te_prequant_pipe_kwargs(
+ fam,
+ fetch_base,
+ te_quant_mode = text_encoder_quant,
+ target = target,
+ dtype = dtype,
+ hf_token = hf_token,
+ logger = logger,
+ local_files_only = local_files_only,
+ dense_source = _base_local_dir
+ or (fetch_base if local_files_only else None),
+ config_source = _base_local_dir,
+ ).get("text_encoder"),
+ family_name = fam.name,
+ )
+ elif fam.name == KREA2_FAMILY_NAME:
pipe = load_krea2_pipeline(
fetch_base,
dtype,
@@ -7846,6 +8039,7 @@ class DiffusionBackend:
local_files_only = local_files_only,
dense_source = _base_local_dir
or (fetch_base if local_files_only else None),
+ config_source = _base_local_dir,
)
)
self._raise_if_load_cancelled(_load_token)
@@ -8165,6 +8359,8 @@ class DiffusionBackend:
static_plan: Optional[dict] = None
if cache_auto:
default_steps, _ = default_generation_params(
+ # FLUX.3's family names its variant; its file names may not (see _generation_defaults_for).
+ *((fam.name,) if is_flux3_family(fam) else ()),
gguf_filename,
content_variant_hint(repo_id, gguf_filename),
repo_id,
@@ -9311,6 +9507,36 @@ class DiffusionBackend:
check_cancelled = check_cancelled or (lambda: None)
check_cancelled()
base = fetch_base or prefer_ungated_mirror(base, hf_token)
+ if is_flux3_family(fam):
+ # FLUX.3 ships modular blocks only, so from_pretrained has no model_index.json to read.
+ flux3_te = None
+ if target is not None:
+ flux3_te = te_prequant_pipe_kwargs(
+ fam,
+ base,
+ te_quant_mode = te_quant_mode,
+ target = target,
+ dtype = dtype,
+ hf_token = hf_token,
+ logger = logger,
+ local_files_only = local_files_only,
+ dense_source = base_local_dir or (base if local_files_only else None),
+ config_source = base_local_dir,
+ ).get("text_encoder")
+ check_cancelled()
+ pipe = load_flux3_pipeline(
+ base_local_dir or base,
+ dtype,
+ hf_token = hf_token,
+ transformer = transformer,
+ text_encoder = flux3_te,
+ check_cancelled = check_cancelled,
+ local_files_only = local_files_only,
+ family_name = getattr(fam, "name", None),
+ )
+ check_cancelled()
+ pipe.to(device)
+ return pipe
if getattr(fam, "name", None) == KREA2_FAMILY_NAME:
# krea ships transformers-5.x configs and no top-level tokenizer files, so assemble per-component.
krea_te = None
@@ -9325,6 +9551,7 @@ class DiffusionBackend:
logger = logger,
local_files_only = local_files_only,
dense_source = base_local_dir or (base if local_files_only else None),
+ config_source = base_local_dir,
).get("text_encoder")
check_cancelled()
pipe = load_krea2_pipeline(
@@ -9373,6 +9600,7 @@ class DiffusionBackend:
logger = logger,
local_files_only = local_files_only,
dense_source = base_local_dir or (base if local_files_only else None),
+ config_source = base_local_dir,
)
)
check_cancelled()
@@ -11313,7 +11541,7 @@ class DiffusionBackend:
# Per-forward chunks: the whole job list in ONE forward by default, bounded by an explicit batch_size
# cap; the OOM backoff below halves a failed chunk. Layered: one input per forward (the pipeline's
# per-prompt layer stride is only right for one).
- chunks = [[job] for job in jobs] if layer_count else chunk_jobs(jobs, batch_size)
+ chunks = _generation_chunks(state.family, jobs, batch_size, layer_count = layer_count)
guard_width = guard_height = guard_target = None
guard_batch = 1
@@ -11334,7 +11562,16 @@ class DiffusionBackend:
* getattr(fam, "condition_pixel_weight", 1.0)
)
if ref_resolution is not None
- else 0
+ # FLUX.3 resizes every condition image to 1 MP itself (diffusion_flux3.resize_reference).
+ else (
+ int(
+ (1 + len(ref_extra))
+ * FLUX3_REFERENCE_AREA
+ * getattr(fam, "condition_pixel_weight", 1.0)
+ )
+ if is_flux3_family(fam) and init_pil is not None
+ else 0
+ )
)
if layer_count:
# layers + 1 extra canvas-sized frames beside the output-sized one.
@@ -12126,7 +12363,11 @@ class DiffusionBackend:
"transformer_cache_stats": static_skip_stats(state.pipe),
"resolved": resolved,
"generation_defaults": _generation_defaults_for(
- state.repo_id, state.gguf_filename, state.base_repo, pipe_sample_sigmas(state.pipe)
+ state.repo_id,
+ state.gguf_filename,
+ state.base_repo,
+ pipe_sample_sigmas(state.pipe),
+ family = state.family,
),
# Workflows the loaded family supports, so the UI can gate its tabs.
"workflows": _family_workflows(state.family),
@@ -12296,13 +12537,18 @@ def _offload_controlnet_module(cn_model: Any, device: str, logger: Any) -> bool:
return False
-def _base_file_downloaded(rfilename: str, *, include_transformer: bool = False) -> bool:
+def _base_file_downloaded(
+ rfilename: str,
+ *,
+ include_transformer: bool = False,
+ manifest: str = "model_index.json",
+) -> bool:
"""True for base-repo files ``from_pretrained`` actually fetches. The transformer is supplied by
the GGUF, and repo docs (``assets/``, the top-level README/PDF/images) are never downloaded:
counting them would peg the progress estimate above what lands on disk, so the bar would sit
short of 100% for the whole pipeline-load phase. ``include_transformer`` admits the
``transformer/`` shards for loads where the dense transformer-quant path will fetch them
- anyway."""
+ anyway. ``manifest`` is the base's pipeline index (FLUX.3's is ``modular_model_index.json``)."""
if rfilename == "transformer/config.json":
# The one transformer/ file that is ALWAYS needed, shards or not: from_single_file(config = <repo id>,
# subfolder = "transformer") resolves it through the Hub, so a load that promised to download nothing cannot
@@ -12313,7 +12559,7 @@ def _base_file_downloaded(rfilename: str, *, include_transformer: bool = False)
if rfilename.startswith("transformer/"):
return include_transformer
if "/" not in rfilename: # top-level: only the pipeline manifest is fetched
- return rfilename == "model_index.json"
+ return rfilename == manifest
return not rfilename.startswith("assets/")
@@ -12349,9 +12595,9 @@ def _pipeline_file_downloaded(rfilename: str) -> bool:
``transformer/`` subfolder is kept. Top-level docs and ``assets/`` are skipped, and so are
artifacts the torch loader never touches (ONNX / OpenVINO / Flax exports and dtype-variant
twins), so an official repo that ships many formats does not prefetch tens of GB it will not
- load."""
+ load. A Modular Diffusers repo (FLUX.3) has ``modular_model_index.json`` as its manifest."""
if "/" not in rfilename: # top-level: only the pipeline manifest is fetched
- return rfilename == "model_index.json"
+ return rfilename in ("model_index.json", FLUX3_INDEX)
lower = rfilename.lower()
if lower.startswith(("assets/", "onnx/", "openvino/")):
return False
@@ -12385,6 +12631,8 @@ _PIPELINE_WEIGHT_PREFIX_RE = re.compile(
def _explicit_pipeline_components(fam: Any) -> Optional[tuple[str, ...]]:
"""Component folders opened by image pipelines assembled outside generic Diffusers."""
name = getattr(fam, "name", None)
+ if is_flux3_family(fam):
+ return FLUX3_COMPONENTS
if name == KREA2_FAMILY_NAME:
return ("scheduler", "text_encoder", "tokenizer", "transformer", "vae")
if name == IDEOGRAM4_FAMILY_NAME:
@@ -12413,7 +12661,11 @@ def _pipeline_components_from_index(
try:
from huggingface_hub import hf_hub_download
- if not any(s.rfilename == "model_index.json" for s in (info.siblings or ())):
+ siblings = {s.rfilename for s in (info.siblings or ())}
+ if "model_index.json" not in siblings:
+ if explicit_components is not None and FLUX3_INDEX in siblings:
+ # A modular repo (FLUX.3) whose assembler names its own folders: nothing else to read.
+ return frozenset(str(name) for name in explicit_components), frozenset()
raise FileNotFoundError(f"{repo_id} has no model_index.json")
path = hf_hub_download(
repo_id,
@@ -12462,7 +12714,7 @@ def _pipeline_selected_file(
components, ignored = selection
if rfilename in ignored:
return False
- if rfilename == "model_index.json":
+ if rfilename in ("model_index.json", FLUX3_INDEX):
return True
if "/" not in rfilename or rfilename.split("/", 1)[0] not in components:
return False
diff --git a/studio/backend/core/inference/diffusion_auto_policy.py b/studio/backend/core/inference/diffusion_auto_policy.py
index 4de4407e550..435a4136194 100644
--- a/studio/backend/core/inference/diffusion_auto_policy.py
+++ b/studio/backend/core/inference/diffusion_auto_policy.py
@@ -68,6 +68,10 @@ _FAMILY_BF16_GB: dict[str, tuple[float, float, float]] = {
"flux.1": (23.8, 9.8, 0.2),
"flux.1-kontext": (23.8, 9.8, 0.2),
"flux.2-klein": (7.8, 8.0, 0.2),
+ # FLUX.3 Image Klein: 5.55B DiT (11.1 GB bf16) + Qwen3-VL-4B (8.9 GB) + the FLUX.2 VAE (stored fp32, 0.17 GB
+ # bf16). From the black-forest-labs/flux-3-image-klein component folders; the base shares the architecture.
+ "flux.3-klein": (11.1, 8.9, 0.2),
+ "flux.3-klein-base": (11.1, 8.9, 0.2),
"flux.2-dev": (64.5, 48.0, 0.4),
"qwen-image": (40.9, 16.6, 0.3),
"qwen-image-edit": (40.9, 16.6, 0.3),
diff --git a/studio/backend/core/inference/diffusion_comfy_quant.py b/studio/backend/core/inference/diffusion_comfy_quant.py
index e51e430cecb..ca9322ceda6 100644
--- a/studio/backend/core/inference/diffusion_comfy_quant.py
+++ b/studio/backend/core/inference/diffusion_comfy_quant.py
@@ -626,9 +626,36 @@ def _mapping(transformer_cls: Any) -> tuple[Any, Any]:
entry = sfm.SINGLE_FILE_LOADABLE_CLASSES.get(name or "")
if not entry:
raise ValueError(f"{transformer_cls.__name__} has no single-file converter")
+ if getattr(transformer_cls, "__name__", "") == "Flux3Transformer2DModel":
+ return _flux3_split_fused_qkv(entry["checkpoint_mapping_fn"]), sfm
return entry["checkpoint_mapping_fn"], sfm
+def _flux3_split_fused_qkv(mapping_fn: Any) -> Any:
+ """``mapping_fn`` after splitting ComfyUI's fused FLUX.3 attention: BFL's ComfyUI int8 files
+ (black-forest-labs/flux-3-image-klein-comfy) store ``<block>.qkv.weight`` where the BFL layout diffusers converts
+ has ``q_proj`` / ``k_proj`` / ``v_proj`` (24 heads x 128 each, no GQA, so equal thirds). Rows only: per-row int8
+ scales and the ConvRot column rotation split with them, and the row tags the loader decodes stay exact. A file in
+ the BFL layout passes through unchanged."""
+ import functools
+
+ @functools.wraps(mapping_fn)
+ def convert(checkpoint, **kwargs):
+ for key in [k for k in checkpoint if k.endswith(".qkv.weight")]:
+ value = checkpoint.pop(key)
+ rows = value.shape[0] // 3
+ if rows * 3 != value.shape[0]:
+ raise ValueError(f"{key}: {value.shape[0]} rows do not split into q, k and v")
+ stem = key[: -len("qkv.weight")]
+ for index, part in enumerate(("q_proj", "k_proj", "v_proj")):
+ checkpoint[f"{stem}{part}.weight"] = value[index * rows : (index + 1) * rows]
+ for key in [k for k in checkpoint if k.endswith(".comfy_attention.config")]:
+ del checkpoint[key] # ComfyUI's attention-backend hint, not a weight
+ return mapping_fn(checkpoint, **kwargs)
+
+ return convert
+
+
def _decode_rows(
name: str,
tagged: Any,
diff --git a/studio/backend/core/inference/diffusion_compat.py b/studio/backend/core/inference/diffusion_compat.py
index dc5b27d86f9..b012dd8b1be 100644
--- a/studio/backend/core/inference/diffusion_compat.py
+++ b/studio/backend/core/inference/diffusion_compat.py
@@ -656,6 +656,119 @@ def assert_flux2_pick_compatible(
raise ValueError(reason)
+def _flux3_pipeline_index(
+ repo_id: str, token: Optional[str], allow_network: bool
+) -> Optional[dict]:
+ """A FLUX.3 pipeline's ``modular_model_index.json``: the local folder's, the cached copy, or (when allowed) a
+ fetch of that one small file. None on anything unreadable."""
+ import json
+
+ from .diffusion_flux3 import FLUX3_INDEX
+
+ try:
+ root = Path(repo_id).expanduser()
+ if root.is_dir():
+ return json.loads((root / FLUX3_INDEX).read_text(encoding = "utf-8-sig"))
+ except (OSError, RuntimeError, ValueError):
+ return None
+ try:
+ # The gated vendor repo's manifest is read from its byte-identical unsloth mirror (pure table lookup), so a
+ # load that fetches everything from the mirror does not also probe, and 401 on, the vendor repo.
+ from core.inference.diffusion_families import prefer_ungated_mirror
+
+ source = prefer_ungated_mirror(repo_id, token, files = (FLUX3_INDEX,))
+ local = _local_gguf_path(repo_id, FLUX3_INDEX)
+ if local is None and source != repo_id:
+ local = _local_gguf_path(source, FLUX3_INDEX)
+ if local is None and allow_network:
+ from huggingface_hub import hf_hub_download
+ from utils.hf_cache_settings import active_hf_hub_cache
+ local = hf_hub_download(
+ source, FLUX3_INDEX, token = token, cache_dir = active_hf_hub_cache()
+ )
+ if local is None:
+ return None
+ payload = json.loads(Path(local).read_text(encoding = "utf-8-sig"))
+ return payload if isinstance(payload, dict) else None
+ except Exception: # noqa: BLE001 -- offline, gated or odd: the loader's own check still runs
+ return None
+
+
+def _flux3_pick_tensor_names(
+ repo_id: str, filename: str, token: Optional[str], allow_network: bool
+) -> tuple[Optional[list[str]], bool]:
+ """Tensor names of a FLUX.3 single file / GGUF pick without reading a weight, and whether it declares ComfyUI
+ quantization: the file on disk, else a GGUF header range read or the safetensors header from the Hub. None
+ names on anything unreadable."""
+ from .diffusion_families import (
+ _checkpoint_comfy_declared,
+ _checkpoint_tensor_names,
+ flux3_comfy_declared,
+ gguf_tensor_names_from_header,
+ )
+
+ local = _local_gguf_path(repo_id, filename)
+ if local is not None:
+ return _checkpoint_tensor_names(local), _checkpoint_comfy_declared(local)
+ if not allow_network:
+ return None, False
+ try:
+ if filename.lower().endswith(".gguf"):
+ return gguf_tensor_names_from_header(
+ _shared_gguf_header(repo_id, filename, token, None)
+ ), False
+ from huggingface_hub import HfApi
+
+ meta = HfApi().parse_safetensors_file_metadata(repo_id, filename, token = token)
+ names = list(meta.tensors)
+ return names, flux3_comfy_declared(names, getattr(meta, "metadata", None))
+ except Exception: # noqa: BLE001 -- offline, gated or odd: the loader's own check still runs
+ return None, False
+
+
+def flux3_pick_mismatch(
+ fam: Any,
+ repo_id: str,
+ gguf_filename: Optional[str],
+ hf_token: Optional[str] = None,
+ allow_network: bool = True,
+) -> Optional[str]:
+ """Why a FLUX.3 pick cannot load under ``fam``, or None when nothing is known to be wrong: a single file /
+ GGUF of the other variant (or a BFL quantized package) from its tensor names, a full pipeline of the other
+ variant from its manifest. Headers and the manifest only; None on anything unreadable."""
+ name = str(getattr(fam, "name", ""))
+ if not name.startswith("flux.3"):
+ return None
+ if not gguf_filename:
+ from .diffusion_flux3 import flux3_family_blocks_mismatch, flux3_index_family
+ declared = flux3_index_family(
+ _flux3_pipeline_index(repo_id, normalize_token(hf_token), allow_network)
+ )
+ return flux3_family_blocks_mismatch(name, declared, repo_id)
+ from .diffusion_families import flux3_variant_mismatch_reason
+
+ names, comfy_declared = _flux3_pick_tensor_names(
+ repo_id, gguf_filename, normalize_token(hf_token), allow_network
+ )
+ return flux3_variant_mismatch_reason(
+ name, Path(str(gguf_filename)).name, names, comfy_declared = comfy_declared
+ )
+
+
+def assert_flux3_pick_compatible(
+ fam: Any,
+ repo_id: str,
+ gguf_filename: Optional[str],
+ hf_token: Optional[str] = None,
+ allow_network: bool = True,
+) -> None:
+ """Refuse a FLUX.3 pick of the other variant before anything is downloaded or unloaded
+ (``flux3_pick_mismatch``). The loader's own checks run after the resident pipeline is gone."""
+ reason = flux3_pick_mismatch(fam, repo_id, gguf_filename, hf_token, allow_network)
+ if reason is not None:
+ raise ValueError(reason)
+
+
def _reset_inner_dim_cache() -> None:
"""Drop the memoised header probes. Tests only."""
with _CACHE_LOCK:
diff --git a/studio/backend/core/inference/diffusion_engine_router.py b/studio/backend/core/inference/diffusion_engine_router.py
index 22527bcee08..7a75d4d4684 100644
--- a/studio/backend/core/inference/diffusion_engine_router.py
+++ b/studio/backend/core/inference/diffusion_engine_router.py
@@ -45,6 +45,7 @@ from core.inference.diffusion_families import (
family_mlx_supported,
family_pipeline_available,
family_sd_cpp_supported,
+ modular_image_family_names,
pipeline_available_family_names,
)
from core.inference.sd_cpp_backend import (
@@ -930,6 +931,8 @@ def annotate_status(status: dict[str, Any]) -> dict[str, Any]:
out["fallback_reason"] = _fallback_reason
out["mlx_fallback_reason"] = _mlx_fallback_reason
out["supported_families"] = list(_supported_family_capabilities())
+ # The family override picker classes an opaque folder as a modular pipeline only for these (FLUX.3).
+ out["modular_families"] = list(modular_image_family_names(_supported_family_capabilities()))
return out
diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.py
index d14237c76c3..22eb86f4f4e 100644
--- a/studio/backend/core/inference/diffusion_families.py
+++ b/studio/backend/core/inference/diffusion_families.py
@@ -18,7 +18,7 @@ import sys
import tempfile
from dataclasses import dataclass, field
from pathlib import Path, PurePosixPath
-from typing import Any, NamedTuple, Optional, Sequence
+from typing import Any, Iterable, Mapping, NamedTuple, Optional, Sequence
from utils.paths.path_utils import is_appledouble_metadata
from .diffusion_flow_shift import flux_mu_shift
@@ -269,6 +269,14 @@ _QWENIMAGE_INT8_EXCLUDES = (
# pre-floor plain fp8 at LPIPS 0.712 with SSIM 0.016 and mean luma 0. Keeping the deny cost real speed: it pinned qwen
# to int8 at 1.10x bf16 when compiled fp8 measures 1.21x.
_QWENIMAGE_SCHEME_DENY = frozenset({"mxfp8", "nvfp4"})
+# FLUX.3 Klein transformer-quant keep-list, every scheme (FamilyProfile.quant_exclude_tokens).
+_FLUX3_QUANT_KEEP = (
+ "modulation",
+ "timestep_embed",
+ "norm_out",
+ "txt_mode_blocks",
+ "context_embedder",
+)
# Schemes denied for TRAINING on top of the inference deny. Training holds a stricter bar because the evidence above is
# rendering evidence: it says a frozen fp8 forward reconstructs the bf16 image, not that a LoRA converges when its
# frozen linears are fp8. Nobody has run that, so qwen fp8 stays out of the Train UI until someone does. Delete the
@@ -418,6 +426,90 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
),
),
),
+ # FLUX.3 Image Klein: a 5.6B flow-map DiT with a Qwen3-VL-4B encoder (layers 4..32 stacked) and the FLUX.2 VAE.
+ # Diffusers ships it only as modular blocks, so diffusion_flux3 assembles it per component behind a classic
+ # pipeline face (no model_index.json in the repo). The distilled checkpoint runs 16 steps without CFG and edits
+ # with up to 10 reference images through the same text-to-image call. Base and distilled are separate entries:
+ # they run different block graphs (the base adds a CFG guider and a negative prompt). Base first in the table only
+ # for reading order; the longest-alias match is what keeps "...-klein-base" off the distilled entry.
+ DiffusionFamily(
+ name = "flux.3-klein-base",
+ label = "FLUX.3 Klein Base",
+ profile = FamilyProfile(
+ # 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
+ # and nvfp4 crash at the first step (the modulation inputs are a stride-0 ``temb.expand``). Spelled out
+ # in full because the generic int8 "_mod" token only matches txt_mode_blocks by accident.
+ quant_exclude_tokens = _FLUX3_QUANT_KEEP,
+ # Every keep-set measured 0.09-0.12 LPIPS against bf16 on NVFP4, as did BFL's own nvfp4 package. A passing
+ # NVFP4 gate record for a base still lifts it.
+ scheme_deny = frozenset({"nvfp4"}),
+ ),
+ pipeline_class = "Flux3ModularPipeline",
+ # Same layout as the distilled repo. The INT8 file is BFL's own ComfyUI int8_convrot denoiser
+ # (black-forest-labs/flux-3-image-klein-comfy, byte-identical), which scored better than an INT8 built with
+ # the keep-list, so the prequant loader reads it through the ComfyUI quant path. The FP8 file is Studio's own.
+ prequant_repos = (
+ ("int8", "unsloth/flux-3-image-klein-base-FP8"),
+ ("fp8", "unsloth/flux-3-image-klein-base-FP8"),
+ ),
+ transformer_class = "Flux3Transformer2DModel",
+ # Qwen3-VL-4B pre-cast fp8, the int8 ConvRot encoder's fallback (diffusion_te_prequant.TE_INT8_CONVROT_FILES).
+ # Byte-identical to the distilled repo's: the two bases ship the same text_encoder/ shards.
+ te_prequant_repos = (("fp8", "text_encoder", "unsloth/flux-3-image-klein-base-FP8"),),
+ # int8 ConvRot by default, as BFL's ComfyUI templates load qwen3vl_4b_int8_convrot (4 of 5 workflows in
+ # black-forest-labs/flux-3-image-klein-comfy). Against the bf16 encoder (bf16 DiT, 19 cases, 25 steps CFG 3.5,
+ # B200, same-GPU A/A bit-identical) the hosted file scores LPIPS-alex mean 0.023 / max 0.121, SSIM 0.973;
+ # layerwise fp8, the fallback when the file cannot be loaded, 0.035 / 0.132, SSIM 0.960. Resident encoder
+ # 8.27 -> 4.89 GiB, load 18.4 -> 1.8 s.
+ te_quant_auto = "int8",
+ base_repo = "black-forest-labs/flux-3-image-klein-base",
+ aliases = ("flux-3-image-klein-base", "flux3-image-klein-base", "flux3-klein-base"),
+ reference = True,
+ max_condition_images = 10,
+ # Two DiT patch grids (VAE /8, patch 2): sizes snap to 16 like FLUX.2.
+ dimension_multiple = 16,
+ # Each reference (resized to 1 MP) adds about 700 MiB of denoise activations in bf16 and 900 MiB with an int8 /
+ # fp8 denoiser, measured on B200, against the estimator's 8192 MiB per megapixel: 0.11 covers the quantised
+ # figure.
+ condition_pixel_weight = 0.11,
+ ),
+ DiffusionFamily(
+ name = "flux.3-klein",
+ label = "FLUX.3 Klein",
+ profile = FamilyProfile(
+ # 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
+ # and nvfp4 crash at the first step (the modulation inputs are a stride-0 ``temb.expand``). Spelled out
+ # in full because the generic int8 "_mod" token only matches txt_mode_blocks by accident.
+ quant_exclude_tokens = _FLUX3_QUANT_KEEP,
+ # Every keep-set measured 0.09-0.12 LPIPS against bf16 on NVFP4, as did BFL's own nvfp4 package. A passing
+ # NVFP4 gate record for a base still lifts it.
+ scheme_deny = frozenset({"nvfp4"}),
+ ),
+ pipeline_class = "Flux3DistilledModularPipeline",
+ # Pre-quantized distilled denoisers (both schemes in one repo, as FLUX.2 klein), built with the keep-list above;
+ # the loader checks the stored exclude set against it. The base has its own repo.
+ prequant_repos = (
+ ("int8", "unsloth/flux-3-image-klein-FP8"),
+ ("fp8", "unsloth/flux-3-image-klein-FP8"),
+ ),
+ uses_negative_prompt = False,
+ transformer_class = "Flux3Transformer2DModel",
+ # Qwen3-VL-4B pre-cast fp8, the int8 ConvRot encoder's fallback (diffusion_te_prequant.TE_INT8_CONVROT_FILES).
+ te_prequant_repos = (("fp8", "text_encoder", "unsloth/flux-3-image-klein-FP8"),),
+ # int8 ConvRot by default, as on the base and in BFL's ComfyUI templates: 0.017 / 0.098 LPIPS-alex, SSIM 0.974,
+ # fp8 fallback 0.038 / 0.220, SSIM 0.945 against the bf16 encoder (19 cases, 16 steps).
+ te_quant_auto = "int8",
+ base_repo = "black-forest-labs/flux-3-image-klein",
+ aliases = ("flux-3-image-klein", "flux3-image-klein", "flux3-klein"),
+ reference = True,
+ max_condition_images = 10,
+ dimension_multiple = 16,
+ condition_pixel_weight = 0.11,
+ ),
# FLUX.2-dev: full (non-distilled) FLUX.2 on the Mistral Flux2Pipeline, so its own entry. Gated base,
# text-to-image only; sd-cli takes the Mistral encoder from unsloth/FLUX.2-dev-ComfyUI and the VAE from
# unsloth/FLUX.2-VAE.
@@ -1008,6 +1100,12 @@ def excluded_model_reason(repo_id: str) -> Optional[str]:
# Editing / inpaint checkpoints share an arch keyword but need a different pipeline + input image. "layered" rejects a
# layered checkpoint of any family without a layered entry of its own; Qwen-Image-Layered has one, so it matches that.
_EDIT_KEYWORDS = ("edit", "kontext", "inpaint", "layered")
+# Repos named after a family that are not image models: FLUX.3's prompt upsampler (``flux-3-image-klein-pup``) is a
+# Qwen3.5 LLM, not a checkpoint any pipeline loads.
+_NON_IMAGE_SIBLING_KEYWORDS: dict[str, tuple[str, ...]] = {
+ "flux.3-klein": ("pup",),
+ "flux.3-klein-base": ("pup",),
+}
def _token_in_needle(token: str, needle: str) -> bool:
@@ -1055,6 +1153,10 @@ def detect_family(repo_id: str, override: Optional[str] = None) -> Optional[Diff
for kw in _EDIT_KEYWORDS
):
return None
+ if any(
+ _token_in_needle(kw, basename) for kw in _NON_IMAGE_SIBLING_KEYWORDS.get(match.name, ())
+ ):
+ return None
return match
return None
@@ -1222,6 +1324,10 @@ _GATED_MIRROR_PAIRS: tuple[tuple[str, str], ...] = (
("black-forest-labs/FLUX.2-dev", "unsloth/FLUX.2-dev"),
("black-forest-labs/FLUX.2-klein-9B", "unsloth/FLUX.2-klein-9B"),
("black-forest-labs/FLUX.2-klein-base-9B", "unsloth/FLUX.2-klein-base-9B"),
+ # FLUX.3 keeps the upstream diffusers folders (modular manifest, text_encoder, transformer, vae; byte-identical)
+ # inside its FP8 repo beside the pre-quantized files, so no separate mirror repo is needed.
+ ("black-forest-labs/flux-3-image-klein", "unsloth/flux-3-image-klein-FP8"),
+ ("black-forest-labs/flux-3-image-klein-base", "unsloth/flux-3-image-klein-base-FP8"),
("krea/Krea-2-Turbo", "unsloth/Krea-2-Turbo"),
("krea/Krea-2-Raw", "unsloth/Krea-2-Raw"),
("ideogram-ai/ideogram-4-fp8", "unsloth/ideogram-4-fp8"),
@@ -1538,6 +1644,19 @@ _GENERATION_DEFAULTS: tuple[tuple[str, int, float], ...] = (
("kontext", 20, 2.5), # editing: before the generic flux.1
("flux.1", 20, 3.5),
("flux1", 20, 3.5),
+ # FLUX.3 Image Klein, ComfyUI's templates (Comfy-Org/workflow_templates 0.11.87): the base t2i and edit templates
+ # run 50 steps at CFG 3.5 (euler / simple), raised from the launch templates' 25, which is also the BFL reference
+ # setting (diffusers' FLUX.3 pipeline defaults: 50 steps, guidance 3.5). Both distilled templates run 16 steps at
+ # CFG 1, as does the BFL reference. Base first.
+ # Every registered alias plus the canonical family names (an opaque path resolves through the family).
+ ("flux.3-klein-base", 50, 3.5),
+ ("flux-3-image-klein-base", 50, 3.5),
+ ("flux3-image-klein-base", 50, 3.5),
+ ("flux3-klein-base", 50, 3.5),
+ ("flux.3-klein", 16, 1.0),
+ ("flux-3-image-klein", 16, 1.0),
+ ("flux3-image-klein", 16, 1.0),
+ ("flux3-klein", 16, 1.0),
# Undistilled base runs real CFG; keep before the generic distilled key.
("flux.2-klein-base", 20, 5.0),
("flux.2-klein", 4, 1.0),
@@ -1597,9 +1716,20 @@ def comfy_flow_shift_for(fam: Any, *identifiers: Optional[str]) -> Optional[floa
return row[1] if row else getattr(fam, "comfy_flow_shift", None)
+# FLUX.3 single files / GGUFs take their transformer config from the companion repo, which may be the other
+# variant's (the TE and VAE are shared, and the base repo is gated). The variant check has already matched the
+# checkpoint to the family, so the family sets flow_map: a base file on the distilled config would otherwise build the
+# target-time embedder the file has no weights for and fail on meta tensors, and the reverse would drop its weights.
+_FLUX3_FLOW_MAP = {"flux.3-klein": True, "flux.3-klein-base": False}
+
+
def transformer_config_overrides_for(fam: Any, *identifiers: Optional[str]) -> dict[str, Any]:
row = _first_variant(getattr(fam, "transformer_config_variants", ()), identifiers)
- return dict(row[1]) if row else {}
+ overrides = dict(row[1]) if row else {}
+ flow_map = _FLUX3_FLOW_MAP.get(getattr(fam, "name", None))
+ if flow_map is not None:
+ overrides["flow_map"] = flow_map
+ return overrides
def _first_checkpoint_variant(
@@ -1774,6 +1904,11 @@ _PIPELINE_MIN_DIFFUSERS: dict[str, str] = {
# the first release that can carry it. ``_version_tuple`` stops at the first non-numeric part,
# so a 0.41.0.dev0 build from main reads as (0, 41, 0) and satisfies this too.
"QwenImage21Pipeline": "0.41.0",
+ # FLUX.3 Image Klein (huggingface/diffusers#15046) is in no release yet, so the first one that can carry it is
+ # 0.42.0. Main and the PR branch both report 0.41.0.dev0, which reads as the 0.41.0 release that lacks it, so the
+ # listing probes the module file instead (``_PIPELINE_PROBE_FILES``).
+ "Flux3ModularPipeline": "0.42.0",
+ "Flux3DistilledModularPipeline": "0.42.0",
"Krea2Pipeline": "0.39.0",
# Older than the 0.35 baseline, but listed anyway: the packaging leaves an UNCONSTRAINED diffusers installable
# below 3.10, so an already-present ancient one satisfies the pin, and quoting the 0.39 floor at a family that has
@@ -1925,8 +2060,16 @@ def local_pipeline_components_are_complete(
*,
excluded_components: Sequence[str] = (),
config_only_model_components: bool = False,
+ fixed_component_folders: Optional[Mapping[str, tuple[str, str, str]]] = None,
) -> bool:
- """Check local component presence and known Diffusers/Transformers serialization layouts."""
+ """Check local component presence and known Diffusers/Transformers serialization layouts.
+
+ ``fixed_component_folders`` (``{component: (folder, library, class)}``) is for a loader that reads a fixed set
+ of components from fixed folders of this root whatever the manifest lists (FLUX.3's assembler). Exactly those
+ are checked, each at ``root/<folder>``, whether or not the manifest names them, ``excluded_components`` for their
+ config only;
+ every other manifest entry and every spec source is ignored, since none of it is loaded (FLUX.3's optional
+ prompt upsampler lives in another repo). The manifest still has to be readable and name a pipeline class."""
if filename not in {"model_index.json", "modular_model_index.json"}:
return False
base = Path(root).expanduser()
@@ -1934,6 +2077,22 @@ def local_pipeline_components_are_complete(
class_name = payload.get("_class_name")
if not isinstance(class_name, str) or not class_name.strip():
return False
+ if fixed_component_folders is not None:
+ # An excluded component's WEIGHTS come from elsewhere (a GGUF / single file), but the loader still reads its
+ # config from this folder (FLUX.3 builds the denoiser with config=<base>, subfolder="transformer"), so it is
+ # checked config-only rather than skipped.
+ try:
+ return bool(fixed_component_folders) and all(
+ _local_pipeline_component_is_complete(
+ base / folder,
+ library,
+ cls,
+ config_only_model_components or name in excluded_components,
+ )
+ for name, (folder, library, cls) in fixed_component_folders.items()
+ )
+ except OSError:
+ return False
caller_supplied = _CALLER_SUPPLIED_COMPONENTS.get(class_name, frozenset())
declared = False
try:
@@ -1988,7 +2147,34 @@ def local_pipeline_components_are_complete(
# Studio installs the pinned main build for exactly these classes (studio/backend/requirements/
# diffusers-main.txt), so the remedy is to put that back, not to chase a release. Delete an entry
# here the moment its version ships, which is the same moment diffusers-pin.txt moves to it.
-_UNRELEASED_MIN_DIFFUSERS: frozenset = frozenset()
+_UNRELEASED_MIN_DIFFUSERS: frozenset = frozenset({"0.42.0"})
+# The pinned main build's requires-python (the installer's DIFFUSERS_MAIN_MIN_PYTHON).
+_DIFFUSERS_MAIN_MIN_PYTHON = (3, 11)
+
+# Classes whose presence a version number cannot answer: an unreleased model on a diffusers main build that reports
+# the same x.y.0.dev0 as the release without it. The listing checks the file that defines the class, relative to the
+# installed diffusers package, which needs no import. Delete an entry once its release is the pin.
+_PIPELINE_PROBE_FILES: dict[str, str] = {
+ "Flux3ModularPipeline": "modular_pipelines/flux3/modular_pipeline.py",
+ "Flux3DistilledModularPipeline": "modular_pipelines/flux3/modular_pipeline.py",
+}
+
+
+def _diffusers_package_has_file(relative: str) -> Optional[bool]:
+ """Whether the installed diffusers package contains ``relative``; None when it cannot be located."""
+ try:
+ import importlib.util
+
+ module = sys.modules.get("diffusers")
+ spec = getattr(module, "__spec__", None) if module is not None else None
+ if spec is None:
+ spec = importlib.util.find_spec("diffusers")
+ locations = list(getattr(spec, "submodule_search_locations", None) or ())
+ except Exception: # noqa: BLE001 -- an unlocatable package answers nothing
+ return None
+ if not locations:
+ return None
+ return any((Path(location) / relative).is_file() for location in locations)
_DIFFUSERS_MAIN_PIN = Path(__file__).resolve().parents[2] / "requirements" / "diffusers-main.txt"
@@ -2061,6 +2247,16 @@ def _too_old_message(pipeline_class: str, family_name: str, installed: str) -> s
f"diffusers {installed}. {DIFFUSERS_UPDATE_REMEDY} On a plain pip install: "
"pip install -U diffusers."
)
+ if minimum in _UNRELEASED_MIN_DIFFUSERS and sys.version_info[:2] < _DIFFUSERS_MAIN_MIN_PYTHON:
+ # The installer never tries the main build here (it declares requires-python >= 3.11), so no
+ # reinstall or archive can help: only a newer interpreter, or the release that carries it.
+ return (
+ f"'{family_name}' needs diffusers >= {minimum} ({pipeline_class}), which has not been "
+ f"released yet; this environment has diffusers {installed}. Unsloth installs a pinned "
+ "build of diffusers main for this, and that build needs Python 3.11 or newer; this "
+ f"is Python {sys.version_info[0]}.{sys.version_info[1]}. Reinstall Unsloth on Python "
+ "3.11+, or wait for the diffusers release that includes it."
+ )
if minimum in _UNRELEASED_MIN_DIFFUSERS:
remedy = _diffusers_main_archive_remedy()
return (
@@ -2278,6 +2474,11 @@ def family_pipeline_available(fam: Optional[DiffusionFamily]) -> bool:
# is False -- which would hide the model.
if not name:
return True
+ probe_file = _PIPELINE_PROBE_FILES.get(name)
+ if probe_file is not None:
+ has_file = _diffusers_package_has_file(probe_file)
+ if has_file is not None:
+ return has_file
if "diffusers" in sys.modules:
module = sys.modules["diffusers"]
# A None entry blocks imports, so preserve the existing fail-open behavior.
@@ -2316,6 +2517,17 @@ def family_selectable(fam) -> bool:
return module is not None and family_pipeline_available(fam)
+def modular_image_family_names(names: Iterable[str]) -> tuple[str, ...]:
+ """Of ``names``, the families whose repos are Modular Diffusers pipelines (``modular_model_index.json``), so an
+ opaque folder picked under an explicit family override is classed ``diffusers_modular_pipeline`` (FLUX.3)."""
+ by_name = {f.name: f for f in _FAMILIES}
+ return tuple(
+ n
+ for n in names
+ if str(getattr(by_name.get(n), "pipeline_class", "")).endswith("ModularPipeline")
+ )
+
+
def pipeline_available_family_names() -> tuple[str, ...]:
return tuple(fam.name for fam in _FAMILIES if family_selectable(fam))
@@ -2544,7 +2756,20 @@ def gguf_flux2_inner_dim(path) -> Optional[int]:
def gguf_flux2_inner_dim_from_header(header: bytes) -> Optional[int]:
- """``inner_dim`` read from the leading bytes of a FLUX.2 GGUF, or None.
+ """``inner_dim`` from the leading bytes of a FLUX.2 GGUF, or None (see ``_gguf_header_tensors``)."""
+ tensors = _gguf_header_tensors(header)
+ return None if tensors is None else _flux2_inner_dim_from_tensors(tensors)
+
+
+def gguf_tensor_names_from_header(header: bytes) -> Optional[list[str]]:
+ """Every tensor name in the table at the start of a GGUF, or None when the prefix does not hold the whole
+ table (so a missing name is never read as absent)."""
+ tensors = _gguf_header_tensors(header)
+ return None if tensors is None else [str(t.name) for t in tensors]
+
+
+def _gguf_header_tensors(header: bytes) -> Optional[list]:
+ """The tensor table (name and dims of every tensor) read from the leading bytes of a GGUF, or None.
Lets the selection-time preflight range-read a few hundred KiB over HTTP instead of pulling the
whole multi-GB checkpoint: the tensor table it needs sits in the first ~15 KiB. Same parser as
@@ -2598,7 +2823,7 @@ def gguf_flux2_inner_dim_from_header(header: bytes) -> Optional[int]:
# padding was never written.
if reader.data_offset > len(header) + min(int(reader.alignment), 4096):
return None
- return _flux2_inner_dim_from_tensors(reader.tensors)
+ return list(reader.tensors)
except Exception: # noqa: BLE001 - an unreadable header is not a verdict
return None
finally:
@@ -2653,6 +2878,102 @@ def assert_flux2_gguf_matches_base(fam, base_repo: str, gguf_path) -> None:
raise ValueError(reason)
+_FLUX3_FLOW_MAP_KEYS = ("ref_time_in.", "target_timestep_embedder.")
+
+
+def _checkpoint_tensor_names(path) -> Optional[list[str]]:
+ """Tensor names of a GGUF or safetensors file without loading any tensor; None when unreadable."""
+ try:
+ name = str(path)
+ if name.lower().endswith(".gguf"):
+ from gguf import GGUFReader
+ return [t.name for t in GGUFReader(name, "r").tensors]
+ from safetensors import safe_open
+
+ with safe_open(name, "pt") as handle:
+ return list(handle.keys())
+ except Exception: # noqa: BLE001 -- fail open: the loader reports its own error
+ return None
+
+
+def flux3_comfy_declared(names: Optional[list[str]], metadata: Optional[dict]) -> bool:
+ """Whether a safetensors file declares ComfyUI quantization (per-layer ``.comfy_quant`` tensors or the
+ ``_quantization_metadata`` header table): BFL's own ComfyUI int8 / nvfp4 files do, its ``variants/`` packages
+ do not. Matches what diffusion_comfy_quant.scan_comfy_quant reads as a declaration."""
+ if any(str(n).endswith(".comfy_quant") for n in names or ()):
+ return True
+ return isinstance(metadata, dict) and bool(metadata.get("_quantization_metadata"))
+
+
+def _checkpoint_comfy_declared(path) -> bool:
+ """:func:`flux3_comfy_declared` for a local safetensors file; False when unreadable or not safetensors."""
+ name = str(path)
+ if not name.lower().endswith(".safetensors"):
+ return False
+ try:
+ from safetensors import safe_open
+ with safe_open(name, "pt") as handle:
+ return flux3_comfy_declared(list(handle.keys()), handle.metadata())
+ except Exception: # noqa: BLE001 -- fail open: the loader reports its own error
+ return False
+
+
+def flux3_variant_mismatch_reason(
+ family_name: str,
+ filename: str,
+ names: Optional[list[str]],
+ comfy_declared: bool = False,
+) -> Optional[str]:
+ """Why a FLUX.3 single file / GGUF cannot run under ``family_name``, or None. The distilled checkpoint is a flow
+ map (it carries the target-time embedder ``ref_time_in``) and runs the 16-step distilled graph; the base has none
+ and runs CFG. Same shapes otherwise, so a mix-up would load and render garbage instead of failing.
+ ``comfy_declared`` (:func:`flux3_comfy_declared`): the scales belong to a ComfyUI quantized file, which the
+ ComfyUI loader reads from its own per-layer declarations, so only BFL's undeclared packages are refused."""
+ if not names or family_name not in ("flux.3-klein", "flux.3-klein-base"):
+ return None
+ stripped = [n.split("model.diffusion_model.", 1)[-1] for n in names]
+ bfl_native = any(n.startswith(("emb_in.", "txt_in.")) for n in stripped)
+ if (
+ bfl_native
+ and not comfy_declared
+ and any(n.endswith((".weight_scale", ".weight_scale_2", ".input_scale")) for n in stripped)
+ ):
+ # BFL's variants/fp8r and variants/nvfp4: row-major scales in BFL's own layout. The NVFP4 one has the same
+ # tensor sizes as a ComfyUI NVFP4 file whose scales are 128x4 tiles, so the ComfyUI loader would decode it
+ # silently wrong; refuse instead.
+ return (
+ f"'{filename}' is one of BFL's quantized FLUX.3 packages (variants/fp8r or variants/nvfp4), whose scale "
+ "layout Unsloth does not load. Load the bf16 checkpoint and pick a transformer precision instead."
+ )
+ flow_map = any(n.startswith(_FLUX3_FLOW_MAP_KEYS) for n in stripped)
+ if flow_map and family_name == "flux.3-klein-base":
+ return (
+ f"'{filename}' is the distilled FLUX.3 Klein checkpoint (it has the flow-map target-time embedder), "
+ "but it was loaded as flux.3-klein-base. Load it with family flux.3-klein."
+ )
+ if not flow_map and family_name == "flux.3-klein":
+ return (
+ f"'{filename}' is the FLUX.3 Klein base checkpoint (no flow-map target-time embedder), but it was "
+ "loaded as the distilled flux.3-klein. Load it with family flux.3-klein-base."
+ )
+ return None
+
+
+def assert_flux3_checkpoint_matches_family(fam, checkpoint_path) -> None:
+ """Refuse a FLUX.3 single file / GGUF of the other variant before any pipeline is built. Fail-open."""
+ name = str(getattr(fam, "name", ""))
+ if checkpoint_path is None or not name.startswith("flux.3"):
+ return
+ reason = flux3_variant_mismatch_reason(
+ name,
+ Path(str(checkpoint_path)).name,
+ _checkpoint_tensor_names(checkpoint_path),
+ comfy_declared = _checkpoint_comfy_declared(checkpoint_path),
+ )
+ if reason is not None:
+ raise ValueError(reason)
+
+
def resolve_local_gguf_child(repo_root: Path, gguf_filename: str) -> Path:
"""Resolve ``gguf_filename`` (user-supplied) to a file under ``repo_root``, rejecting absolute
paths and ``..`` escapes."""
diff --git a/studio/backend/core/inference/diffusion_flux3.py b/studio/backend/core/inference/diffusion_flux3.py
new file mode 100644
index 00000000000..8bd71fb491f
--- /dev/null
+++ b/studio/backend/core/inference/diffusion_flux3.py
@@ -0,0 +1,572 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""FLUX.3 Image Klein: a classic pipeline face over Diffusers' modular FLUX.3 blocks.
+
+Diffusers ships FLUX.3 only as a Modular Diffusers workflow (``Flux3DistilledAutoBlocks`` for the
+16-step flow-map checkpoint, ``Flux3AutoBlocks`` for the undistilled base), and the repos carry a
+``modular_model_index.json`` instead of a ``model_index.json``. The image backend drives every
+other family through a ``DiffusionPipeline``: placement (``to`` / model and group offload), the
+step callback (progress, cancel), the decode-phase hook and the scheduler swap all address
+``pipe.<component>``. ``Flux3KleinPipeline`` is that face: it registers the same component
+objects the blocks run, so offload hooks, compiled or quantised replacements and a swapped
+scheduler reach the blocks unchanged, and its ``__call__`` takes the keywords the generate path
+passes.
+
+The component objects are loaded per subfolder (``text_encoder`` also carries the Qwen3-VL
+processor), so only ``transformer/``, ``text_encoder/`` and ``vae/`` are ever read; the repo-root
+BFL single file and ``ae.safetensors`` and the ``variants/`` quantised packages are not.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from loggers import get_logger
+
+logger = get_logger(__name__)
+
+FLUX3_KLEIN_FAMILY_NAME = "flux.3-klein"
+FLUX3_KLEIN_BASE_FAMILY_NAME = "flux.3-klein-base"
+FLUX3_FAMILY_NAMES = (FLUX3_KLEIN_FAMILY_NAME, FLUX3_KLEIN_BASE_FAMILY_NAME)
+
+# The class every FLUX.3 load needs from diffusers; its absence is what an unreleased diffusers looks like.
+FLUX3_TRANSFORMER_CLASS = "Flux3Transformer2DModel"
+FLUX3_DISTILLED_BLOCKS = "Flux3DistilledAutoBlocks"
+FLUX3_BASE_BLOCKS = "Flux3AutoBlocks"
+# Folders a load reads. The tokenizer / processor files live in text_encoder/.
+FLUX3_COMPONENTS = ("text_encoder", "transformer", "vae")
+FLUX3_INDEX = "modular_model_index.json"
+# The manifest components load_flux3_pipeline reads, and the folder of this repo each comes from (the processor
+# lives with the encoder), whatever source a modular spec names. Nothing else in the manifest is loaded: since
+# 2026-10-16 the official manifests also list the optional prompt upsampler (``prompt_upsampler`` /
+# ``prompt_upsampler_processor``, from the separate ~19 GB flux-3-image-klein-pup repo), which an image load never
+# needs. Validation and the locality checks read this map, so they require exactly what will load: every one of
+# these folders (the loader opens all of them, listed in the manifest or not), and nothing else.
+FLUX3_COMPONENT_FOLDERS = {
+ "text_encoder": ("text_encoder", "transformers", "Qwen3VLForConditionalGeneration"),
+ "tokenizer": ("text_encoder", "transformers", "Qwen3VLProcessor"),
+ "transformer": ("transformer", "diffusers", "Flux3Transformer2DModel"),
+ "vae": ("vae", "diffusers", "AutoencoderKLFlux2"),
+}
+
+
+# The prompt upsampler step Diffusers main puts first in both auto block graphs since huggingface/diffusers#15058
+# (2026-10-16). It needs the separate ~19 GB Qwen3.5-9B upsampler, which Studio never loads, and would otherwise run
+# on every call (its text-to-image branch has no trigger input), so it is dropped, as its docstring prescribes.
+FLUX3_PROMPT_UPSAMPLER_STEP = "prompt_upsampler"
+
+
+def flux3_blocks(blocks_class_name: str) -> Any:
+ """The named FLUX.3 auto blocks without the prompt upsampler step (absent before diffusers#15058)."""
+ import diffusers
+
+ blocks = getattr(diffusers, blocks_class_name)()
+ sub_blocks = getattr(blocks, "sub_blocks", None)
+ if sub_blocks is not None and FLUX3_PROMPT_UPSAMPLER_STEP in sub_blocks:
+ sub_blocks.pop(FLUX3_PROMPT_UPSAMPLER_STEP)
+ return blocks
+
+
+def is_flux3_family(fam: Any) -> bool:
+ return getattr(fam, "name", None) in FLUX3_FAMILY_NAMES
+
+
+def flux3_available() -> bool:
+ """Whether the installed diffusers can build FLUX.3 at all (imports diffusers)."""
+ try:
+ import diffusers
+ return all(
+ hasattr(diffusers, name)
+ for name in (FLUX3_TRANSFORMER_CLASS, FLUX3_DISTILLED_BLOCKS, FLUX3_BASE_BLOCKS)
+ )
+ except Exception: # noqa: BLE001 -- unimportable diffusers cannot build it either
+ return False
+
+
+def _live_cache_dir() -> str:
+ """The live hub cache root (see diffusion_krea2._live_cache_dir for why it is pinned)."""
+ from utils.hf_cache_settings import active_hf_hub_cache
+ return active_hf_hub_cache()
+
+
+def _read_index(repo_id: str, hf_token: Optional[str], local_files_only: bool) -> dict:
+ try:
+ root = Path(repo_id).expanduser()
+ if root.is_dir():
+ path = root / FLUX3_INDEX
+ if not path.is_file():
+ raise FileNotFoundError(f"{FLUX3_INDEX} not found in local model dir {repo_id}")
+ payload = json.loads(path.read_text(encoding = "utf-8-sig"))
+ return payload if isinstance(payload, dict) else {}
+ except OSError:
+ pass
+ from huggingface_hub import hf_hub_download
+
+ path = hf_hub_download(
+ repo_id,
+ FLUX3_INDEX,
+ token = hf_token or None,
+ local_files_only = local_files_only,
+ cache_dir = _live_cache_dir(),
+ )
+ payload = json.loads(Path(path).read_text(encoding = "utf-8-sig"))
+ return payload if isinstance(payload, dict) else {}
+
+
+FLUX3_FAMILY_BLOCKS = {
+ FLUX3_KLEIN_FAMILY_NAME: FLUX3_DISTILLED_BLOCKS,
+ FLUX3_KLEIN_BASE_FAMILY_NAME: FLUX3_BASE_BLOCKS,
+}
+_BLOCKS_FAMILY = {blocks: family for family, blocks in FLUX3_FAMILY_BLOCKS.items()}
+# A manifest's ``_class_name`` names the pipeline; either it or ``_blocks_class_name`` identifies the variant.
+_PIPELINE_FAMILY = {
+ "Flux3DistilledModularPipeline": FLUX3_KLEIN_FAMILY_NAME,
+ "Flux3ModularPipeline": FLUX3_KLEIN_BASE_FAMILY_NAME,
+}
+
+
+def flux3_index_family(index: Optional[dict]) -> Optional[str]:
+ """The FLUX.3 family a ``modular_model_index.json`` declares, or None when it says nothing recognisable."""
+ if not isinstance(index, dict):
+ return None
+ blocks = index.get("_blocks_class_name")
+ if isinstance(blocks, str) and blocks in _BLOCKS_FAMILY:
+ return _BLOCKS_FAMILY[blocks]
+ name = index.get("_class_name")
+ return _PIPELINE_FAMILY.get(name) if isinstance(name, str) else None
+
+
+def flux3_family_blocks_mismatch(
+ family_name: Optional[str], declared: Optional[str], source: str
+) -> Optional[str]:
+ """Why ``source`` (declaring the FLUX.3 family or block class ``declared``) cannot load as ``family_name``."""
+ declared = _BLOCKS_FAMILY.get(declared, declared) if declared else None
+ if (
+ family_name not in FLUX3_FAMILY_BLOCKS
+ or declared not in FLUX3_FAMILY_BLOCKS
+ or declared == family_name
+ ):
+ return None
+ what = "distilled FLUX.3 Klein" if declared == FLUX3_KLEIN_FAMILY_NAME else "FLUX.3 Klein base"
+ return (
+ f"'{source}' is the {what} pipeline, but it was loaded as {family_name}. Load it with family {declared} "
+ "(or leave the family on auto)."
+ )
+
+
+def flux3_blocks_class(index: dict, transformer: Any = None) -> str:
+ """The block graph a checkpoint runs. The loaded denoiser decides first: a flow-map DiT (it has the target-time
+ embedder) runs the distilled graph, a CFG DiT the base graph, whatever repo supplied the companions (a single
+ file or GGUF of one variant may sit on the other variant's base). Else the index names it."""
+ flow_map = None
+ if transformer is not None:
+ if hasattr(transformer, "target_timestep_embedder"):
+ flow_map = getattr(transformer, "target_timestep_embedder") is not None
+ else:
+ flow_map = getattr(getattr(transformer, "config", None), "flow_map", None)
+ if flow_map is not None:
+ return FLUX3_DISTILLED_BLOCKS if flow_map else FLUX3_BASE_BLOCKS
+ named = index.get("_blocks_class_name") if isinstance(index, dict) else None
+ if named in (FLUX3_DISTILLED_BLOCKS, FLUX3_BASE_BLOCKS):
+ return named
+ return FLUX3_DISTILLED_BLOCKS
+
+
+@dataclass
+class Flux3PipelineOutput:
+ """``.images``, the one field the generate path reads (``ImagePipelineOutput``'s shape)."""
+
+ images: list
+
+
+class _Flux3Interrupted(Exception):
+ """Raised out of the denoise loop when the step callback set ``_interrupt``."""
+
+
+# Each reference is scaled to this area before the VAE, aspect kept, Lanczos: ComfyUI's
+# ``ReferenceMultiLatent`` with the templates' ``["resize", 1]`` (1.0 megapixels), and the BFL
+# reference's multi-reference rule (each <= 1 MiP). Diffusers alone only downsizes above 16 MiP, so
+# a phone photo would otherwise be encoded at full size. The 16-px grid crop stays with the blocks.
+REFERENCE_AREA = 1024 * 1024
+
+
+def resize_reference(image: Any) -> Any:
+ """``image`` at ~1 MiP, aspect kept (ComfyUI: ``round(side * sqrt(area / (w * h)))``, Lanczos)."""
+ import math
+
+ from PIL import Image
+
+ width, height = image.size
+ scale = math.sqrt(REFERENCE_AREA / float(max(1, width * height)))
+ size = (max(1, round(width * scale)), max(1, round(height * scale)))
+ if size == (width, height):
+ return image
+ return image.resize(size, Image.LANCZOS)
+
+
+def reference_noise(seed: int, height: int, width: int):
+ """The BFL reference's initial noise as the blocks' (1, 128, h, w) latent.
+
+ The reference draws ``randn((h * w, 128))`` row-major on a CPU generator and rounds it to bf16;
+ diffusers draws ``(B, 128, h, w)`` on the request's generator. Same seed, different image. This
+ makes a Studio seed render what the BFL CLI renders for that seed (verified against its outputs),
+ on any device."""
+ import torch
+
+ h, w = height // 16, width // 16
+ tokens = torch.randn((h * w, 128), generator = torch.Generator().manual_seed(int(seed)))
+ return tokens.to(torch.bfloat16).reshape(h, w, 128).permute(2, 0, 1)[None].contiguous()
+
+
+def _generator_seed(generator: Any) -> Optional[int]:
+ initial_seed = getattr(generator, "initial_seed", None)
+ if not callable(initial_seed):
+ return None
+ try:
+ return int(initial_seed())
+ except Exception: # noqa: BLE001 -- a generator without a readable seed keeps diffusers' draw
+ return None
+
+
+_PIPELINE_CLASS: Optional[type] = None
+
+
+def flux3_pipeline_class() -> type:
+ """``Flux3KleinPipeline``, built on first use so importing this module never imports diffusers."""
+ global _PIPELINE_CLASS
+ if _PIPELINE_CLASS is None:
+ from diffusers import DiffusionPipeline
+
+ # The pinned build's FLUX.3 LoRA loader (transformer-only, like the FLUX.2 one): load_lora_weights,
+ # set_adapters and unload_lora_weights act on self.transformer, the same module the blocks run.
+ try:
+ from diffusers.loaders import Flux3LoraLoaderMixin as lora
+ except ImportError:
+ lora = None
+ bases = (
+ (_Flux3KleinPipelineMixin,)
+ + ((lora,) if lora is not None else ())
+ + (DiffusionPipeline,)
+ )
+ _PIPELINE_CLASS = type("Flux3KleinPipeline", bases, {})
+ return _PIPELINE_CLASS
+
+
+class _Flux3KleinPipelineMixin:
+ """FLUX.3 Klein (distilled or base) as a ``DiffusionPipeline``; the denoise runs in the modular blocks."""
+
+ model_cpu_offload_seq = "text_encoder->transformer->vae"
+ _optional_components: list = []
+ _callback_tensor_inputs = ["latents"]
+
+ def __init__(
+ self,
+ transformer,
+ vae,
+ text_encoder,
+ tokenizer,
+ scheduler,
+ blocks_class_name: str = FLUX3_DISTILLED_BLOCKS,
+ ):
+ super().__init__()
+ self.register_modules(
+ transformer = transformer,
+ vae = vae,
+ text_encoder = text_encoder,
+ tokenizer = tokenizer,
+ scheduler = scheduler,
+ )
+ self.register_to_config(blocks_class_name = blocks_class_name)
+ self._modular = None
+ self._interrupt = False
+
+ @property
+ def is_distilled(self) -> bool:
+ return self.config.blocks_class_name == FLUX3_DISTILLED_BLOCKS
+
+ @property
+ def interrupt(self) -> bool:
+ return self._interrupt
+
+ def modular_pipeline(self):
+ """The modular pipeline over THIS pipeline's current component objects."""
+ import diffusers
+
+ if self._modular is None:
+ self._modular = flux3_blocks(self.config.blocks_class_name).init_pipeline()
+ mp = self._modular
+ updates = {}
+ for name in ("transformer", "vae", "text_encoder", "tokenizer", "scheduler"):
+ current = getattr(self, name, None)
+ if current is not None and getattr(mp, name, None) is not current:
+ updates[name] = current
+ if updates:
+ mp.update_components(**updates)
+ return mp
+
+ def _set_guidance(self, mp, guidance_scale: Optional[float]) -> None:
+ guider = getattr(mp, "guider", None)
+ if guider is None or guidance_scale is None:
+ return
+ if float(getattr(guider.config, "guidance_scale", -1.0)) == float(guidance_scale):
+ return
+ from diffusers import ClassifierFreeGuidance
+
+ mp.update_components(guider = ClassifierFreeGuidance(guidance_scale = float(guidance_scale)))
+
+ def __call__(
+ self,
+ prompt = None,
+ image = None,
+ height: Optional[int] = None,
+ width: Optional[int] = None,
+ num_inference_steps: int = 16,
+ guidance_scale: Optional[float] = None,
+ negative_prompt: Optional[str] = None,
+ num_images_per_prompt: int = 1,
+ generator = None,
+ latents = None,
+ max_sequence_length: int = 8192,
+ output_type: str = "pil",
+ return_dict: bool = True,
+ callback_on_step_end: Optional[Callable] = None,
+ callback_on_step_end_tensor_inputs = ("latents",),
+ ):
+ self._interrupt = False
+ mp = self.modular_pipeline()
+ self._set_guidance(mp, guidance_scale)
+
+ prompts = prompt if isinstance(prompt, (list, tuple)) else [prompt]
+ if any(not isinstance(p, str) for p in prompts):
+ raise ValueError("FLUX.3 takes a text prompt (str) per image.")
+ generators = generator if isinstance(generator, (list, tuple)) else None
+ negatives = list(negative_prompt) if isinstance(negative_prompt, (list, tuple)) else None
+ # The text encoder sizes its window per prompt, so the blocks take ONE prompt per call. A batch of
+ # distinct prompts, or one prompt with a generator per image, runs as one call per image.
+ if len(prompts) > 1 or generators is not None:
+ count = max(len(prompts), len(generators or ()))
+ if len(prompts) == 1:
+ prompts = prompts * count
+ if generators is not None and len(generators) != count:
+ raise ValueError(
+ f"Got {len(generators)} generators for {count} images; pass one per image."
+ )
+ if negatives is not None and len(negatives) not in (1, count):
+ raise ValueError(
+ f"Got {len(negatives)} negative prompts for {count} images; pass one, or one per image."
+ )
+ calls = [
+ (prompts[i], generators[i] if generators is not None else generator, 1)
+ for i in range(count)
+ ]
+ else:
+ calls = [(prompts[0], generator, int(num_images_per_prompt or 1))]
+
+ images: list = []
+ try:
+ for call_index, (one_prompt, one_generator, per_prompt) in enumerate(calls):
+ kwargs: dict[str, Any] = {
+ "prompt": one_prompt,
+ "num_inference_steps": int(num_inference_steps),
+ "num_images_per_prompt": per_prompt,
+ "max_sequence_length": int(max_sequence_length),
+ "output_type": output_type,
+ }
+ if one_generator is not None:
+ kwargs["generator"] = one_generator
+ if image is not None:
+ refs = list(image) if isinstance(image, (list, tuple)) else [image]
+ refs = [resize_reference(ref) for ref in refs]
+ kwargs["image"] = refs if len(refs) > 1 else refs[0]
+ if height is not None:
+ kwargs["height"] = int(height)
+ if width is not None:
+ kwargs["width"] = int(width)
+ if latents is not None:
+ kwargs["latents"] = latents
+ elif per_prompt == 1 and height is not None and width is not None:
+ seed = _generator_seed(one_generator)
+ if seed is not None:
+ kwargs["latents"] = reference_noise(seed, int(height), int(width))
+ if negative_prompt is not None and not self.is_distilled:
+ # A per-image list pairs entry i with call i (the blocks take one prompt per call).
+ kwargs["negative_prompt"] = (
+ negative_prompt
+ if negatives is None
+ else negatives[call_index if len(negatives) > 1 else 0]
+ )
+ with self._step_hooks(
+ mp,
+ callback_on_step_end,
+ num_inference_steps = int(num_inference_steps),
+ first_call = call_index == 0,
+ ):
+ out = mp(**kwargs, output = "images")
+ images.extend(out if isinstance(out, list) else [out])
+ except _Flux3Interrupted:
+ images = []
+ if not return_dict:
+ return (images,)
+ return Flux3PipelineOutput(images = images)
+
+ def _step_hooks(
+ self, mp, callback: Optional[Callable], *, num_inference_steps: int, first_call: bool
+ ):
+ """Fire ``callback_on_step_end`` after every scheduler step, and open ``self.progress_bar`` at
+ the first denoiser forward, which is where every classic pipeline opens its loop (the
+ generate path's denoise-phase hook watches it)."""
+ import contextlib
+
+ pipe = self
+
+ @contextlib.contextmanager
+ def _hooks():
+ scheduler = mp.scheduler
+ had_own_step = "step" in scheduler.__dict__
+ original_step = scheduler.step
+ counter = {"i": 0}
+
+ def _step(*args, **kwargs):
+ result = original_step(*args, **kwargs)
+ i = counter["i"]
+ counter["i"] += 1
+ if callback is not None:
+ latents = result[0] if isinstance(result, tuple) else result.prev_sample
+ timestep = args[1] if len(args) > 1 else kwargs.get("timestep")
+ callback(pipe, i, timestep, {"latents": latents})
+ if pipe._interrupt:
+ raise _Flux3Interrupted()
+ return result
+
+ handle = None
+ transformer = getattr(mp, "transformer", None)
+ if (
+ first_call
+ and transformer is not None
+ and hasattr(transformer, "register_forward_pre_hook")
+ ):
+ fired = {"done": False}
+
+ def _pre_hook(_module, _args):
+ if not fired["done"]:
+ fired["done"] = True
+ try:
+ bar = pipe.progress_bar(total = num_inference_steps)
+ close = getattr(bar, "close", None)
+ if callable(close):
+ close()
+ except Exception: # noqa: BLE001 -- a phase label must never fail a render
+ pass
+
+ handle = transformer.register_forward_pre_hook(_pre_hook)
+ scheduler.step = _step
+ try:
+ yield
+ finally:
+ if had_own_step:
+ scheduler.step = original_step
+ else:
+ try:
+ del scheduler.step
+ except AttributeError:
+ pass
+ if handle is not None:
+ handle.remove()
+
+ return _hooks()
+
+
+def _pin_compute_dtype(transformer: Any, dtype: Any) -> None:
+ """Make ``transformer.dtype`` answer the compute dtype for a GGUF denoiser.
+
+ The FLUX.3 denoise block casts the latents to ``components.transformer.dtype``. diffusers reads that as the first
+ floating parameter outside ``_keep_in_fp32_modules``; in a GGUF FLUX.3 every 2-D weight is packed uint8 and the
+ only float tensors are the fp32-kept QK norms, so it falls through to uint8 and the first Linear refuses a uint8
+ input. A float buffer is what it reads next, so one empty non-persistent buffer at ``dtype`` fixes the answer
+ without touching any weight."""
+ try:
+ import torch
+
+ if getattr(transformer, "dtype", None) in (None, dtype) or not isinstance(
+ transformer, torch.nn.Module
+ ):
+ return
+ if getattr(transformer, "dtype").is_floating_point:
+ return
+ transformer.register_buffer(
+ "_unsloth_compute_dtype", torch.empty(0, dtype = dtype), persistent = False
+ )
+ except Exception as exc: # noqa: BLE001 -- the denoise raises its own clear error if this did not take
+ logger.warning("diffusion.flux3: could not pin the GGUF compute dtype (%s)", exc)
+
+
+def load_flux3_pipeline(
+ repo_id: str,
+ dtype,
+ hf_token: Optional[str] = None,
+ transformer = None,
+ text_encoder = None,
+ local_files_only: bool = False,
+ check_cancelled: Optional[Callable[[], None]] = None,
+ family_name: Optional[str] = None,
+) -> Any:
+ """A ready ``Flux3KleinPipeline`` for ``repo_id`` (on CPU; the caller places it).
+
+ ``family_name`` (the family the load resolved) must agree with the block graph the checkpoint runs: a base
+ pipeline loaded as the distilled family would run CFG while Studio suppresses its negative prompt, and the
+ reverse. The pre-eviction preflight refuses that from the manifest; this is the backstop.
+
+ ``transformer`` / ``text_encoder`` let a quantised or pre-cast build hand in a component;
+ the rest load from the repo's own subfolders. ``local_files_only`` keeps a load that was
+ cleared as fully local from reaching the Hub (see diffusion_krea2.load_krea2_pipeline)."""
+ check_cancelled = check_cancelled or (lambda: None)
+ check_cancelled()
+ if not flux3_available():
+ from .diffusion_families import assert_pipeline_class_available
+ assert_pipeline_class_available(FLUX3_TRANSFORMER_CLASS, FLUX3_KLEIN_FAMILY_NAME)
+ raise RuntimeError("FLUX.3 needs a diffusers build with the FLUX.3 modular blocks.")
+ import diffusers
+ from transformers import AutoProcessor, Qwen3VLForConditionalGeneration
+
+ token = hf_token or None
+ common: dict[str, Any] = {"local_files_only": local_files_only, "cache_dir": _live_cache_dir()}
+ if token:
+ common["token"] = token
+ index = _read_index(repo_id, token, local_files_only)
+ check_cancelled()
+ tokenizer = AutoProcessor.from_pretrained(repo_id, subfolder = "text_encoder", **common)
+ check_cancelled()
+ if text_encoder is None:
+ text_encoder = Qwen3VLForConditionalGeneration.from_pretrained(
+ repo_id, subfolder = "text_encoder", dtype = dtype, **common
+ )
+ text_encoder.eval()
+ check_cancelled()
+ if transformer is None:
+ transformer = diffusers.Flux3Transformer2DModel.from_pretrained(
+ repo_id, subfolder = "transformer", torch_dtype = dtype, **common
+ )
+ check_cancelled()
+ vae = diffusers.AutoencoderKLFlux2.from_pretrained(
+ repo_id, subfolder = "vae", torch_dtype = dtype, **common
+ )
+ check_cancelled()
+ _pin_compute_dtype(transformer, dtype)
+ blocks = flux3_blocks_class(index, transformer)
+ reason = flux3_family_blocks_mismatch(family_name, blocks, repo_id)
+ if reason is not None:
+ raise ValueError(reason)
+ # The scheduler is the block graph's own (shift 6.93, the reference timestep shift); the repos ship none.
+ scheduler = flux3_blocks(blocks).init_pipeline().scheduler
+ return flux3_pipeline_class()(
+ transformer = transformer,
+ vae = vae,
+ text_encoder = text_encoder,
+ tokenizer = tokenizer,
+ scheduler = scheduler,
+ blocks_class_name = blocks,
+ )
diff --git a/studio/backend/core/inference/diffusion_memory.py b/studio/backend/core/inference/diffusion_memory.py
index 28de185be7a..74e3079362e 100644
--- a/studio/backend/core/inference/diffusion_memory.py
+++ b/studio/backend/core/inference/diffusion_memory.py
@@ -1080,6 +1080,14 @@ _MEASURED_IMAGE_ACTIVATION_MIB: dict[
"qwen-image-2.1": ((1_849, 666, 7_648, 1_697, 2_479), (1_849, 2_489, 7_648, 1_697, 9_602)),
"flux.1": ((288, 892, 2_666, 2_456, 2_674), (288, 892, 2_666, 2_456, 2_674)),
"flux.2-klein": ((1_516, 1_160, 2_645, 2_456, 3_876), (1_516, 1_205, 2_677, 2_456, 3_924)),
+ # FLUX.3 Klein (distilled, no CFG), measured B200 bf16, 1024^2 t2i: TE 301 MiB at a ~560-token window, denoise eager
+ # 594 bf16 / 901 int8 / 850 fp8, compiled 543-676 (int8 / fp8, regional dynamic=True), untiled AutoencoderKLFlux2
+ # decode 2_437. Tiled decode is unmeasured (flux.2-klein's same VAE reads 2_456): capped at the untiled figure, which
+ # a tiled decode cannot exceed. The compiled tier keeps the eager 901 rather than its measured 543-676, since the
+ # table's tiers may only grow with speed. The 2048^2 column is max(denoise eager fp8 3_359, tiled decode) since the
+ # untiled 2048 decode is 9_738. References are charged through ``condition_pixel_weight``. The base (CFG) is
+ # unmeasured and keeps the flat estimate.
+ "flux.3-klein": ((301, 901, 2_437, 2_437, 3_359), (301, 901, 2_437, 2_437, 3_359)),
"z-image": ((744, 1_199, 2_666, 2_456, 4_327), (744, 1_271, 2_669, 2_456, 4_327)),
}
@@ -2265,6 +2273,8 @@ _MEASURED_PEAK_ROUND_MIB = 256
MEASURED_ACTIVATION_DENSE_ENV = "UNSLOTH_DIFFUSION_MEASURED_ACTIVATION_DENSE"
_MEASURED_DENSE_EAGER_PEAK_MIB: dict[str, tuple[int, int]] = {
"flux.2-klein": (2455, 7800),
+ # FLUX.3 Klein: worst phase is the untiled VAE decode (2_437 MiB @1024^2, bf16); DiT 10_583 MiB bf16.
+ "flux.3-klein": (2437, 10600),
"flux.1": (2448, 23800),
"qwen-image": (4248, 40900),
}
diff --git a/studio/backend/core/inference/diffusion_qwenimage21.py b/studio/backend/core/inference/diffusion_qwenimage21.py
index 92558b8bb63..e8883c78e07 100644
--- a/studio/backend/core/inference/diffusion_qwenimage21.py
+++ b/studio/backend/core/inference/diffusion_qwenimage21.py
@@ -23,10 +23,13 @@ COMPACT_KV_ENV = "UNSLOTH_DIFFUSION_Q21_COMPACT_KV"
_MODULE = "diffusers.models.transformers.transformer_qwenimage21"
_CLASS = "QwenImage21Transformer2DModel"
-# Stock diffusers sources the fast forward relies on; any drift keeps the stock forward.
+# Stock diffusers sources the fast forward relies on; any drift keeps the stock forward. Each set lists every
+# known-equivalent source, oldest first.
_FINGERPRINTS: dict[str, frozenset] = {
"forward": frozenset({"7c1fd48f75efbe41"}),
- "build_token_metadata": frozenset({"51818c1674e0d406"}),
+ # 0.41.0; main d42ebf9c builds the same int64 block ids from a Python list instead of a tensor-repeats
+ # repeat_interleave (Neuron lowering), so the ids are equal element for element.
+ "build_token_metadata": frozenset({"51818c1674e0d406", "9282e4c4803957f8"}),
"rope_forward": frozenset({"f9e064940341e3ee"}),
"prefix_segments": frozenset({"27729cffc22b0aa5"}),
}
diff --git a/studio/backend/core/inference/diffusion_qwenimage21_fused.py b/studio/backend/core/inference/diffusion_qwenimage21_fused.py
index 45d457ad80e..8b9d6917d04 100644
--- a/studio/backend/core/inference/diffusion_qwenimage21_fused.py
+++ b/studio/backend/core/inference/diffusion_qwenimage21_fused.py
@@ -110,9 +110,11 @@ def _make_prepare(stock: Any, mod: Any) -> Any:
# stock body below the projections, op for op (fingerprinted at install)
query, key, value = int8_linear(fused, hidden_states).chunk(3, dim = -1)
- query = query.unflatten(-1, (attn.heads, -1))
- key = key.unflatten(-1, (attn.heads, -1))
- value = value.unflatten(-1, (attn.heads, -1))
+ # main's split (by head_dim); equal to 0.41.0's ``(attn.heads, -1)`` when every head is local
+ head_dim = attn.inner_dim // attn.heads
+ query = query.unflatten(-1, (-1, head_dim))
+ key = key.unflatten(-1, (-1, head_dim))
+ value = value.unflatten(-1, (-1, head_dim))
query = attn.norm_q(query).to(value.dtype)
key = attn.norm_k(key).to(value.dtype)
diff --git a/studio/backend/core/inference/diffusion_qwenimage21_rope.py b/studio/backend/core/inference/diffusion_qwenimage21_rope.py
index 9fb8ba8e3d9..982e7cdcdcf 100644
--- a/studio/backend/core/inference/diffusion_qwenimage21_rope.py
+++ b/studio/backend/core/inference/diffusion_qwenimage21_rope.py
@@ -24,7 +24,9 @@ _MODULE = "diffusers.models.transformers.transformer_qwenimage21"
_FINGERPRINTS: dict[str, frozenset] = {
"apply_rotary_emb_qwen": frozenset({"ba81dd3fc907c23a"}),
- "_qwenimage21_prepare_qkv": frozenset({"574bacc8f355456d"}),
+ # 0.41.0 splits heads by ``attn.heads``; main d42ebf9c by ``attn.inner_dim // attn.heads`` (tensor parallel),
+ # the same split whenever the projections hold every head, which is all Studio runs.
+ "_qwenimage21_prepare_qkv": frozenset({"574bacc8f355456d", "4c3830595aef56a0"}),
}
_LOCK = threading.Lock()
diff --git a/studio/backend/core/inference/diffusion_qwenimage_rope.py b/studio/backend/core/inference/diffusion_qwenimage_rope.py
index 41a53a309d7..93473b4c7c0 100644
--- a/studio/backend/core/inference/diffusion_qwenimage_rope.py
+++ b/studio/backend/core/inference/diffusion_qwenimage_rope.py
@@ -1,9 +1,12 @@
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-"""Qwen-Image RoPE in real arithmetic (Inductor cannot lower the complex multiply): points
-``ROPE_PER_DEVICE["cuda"]`` at ``diffusion_qwenimage21_rope``'s probed fma wrapper, bit-identical to the complex product.
-Kill switch: ``UNSLOTH_DIFFUSION_QWEN_REAL_ROPE=0`` (``UNSLOTH_DIFFUSION_Q21_REAL_ROPE=0`` also disables it).
+"""Qwen-Image RoPE in real arithmetic (Inductor cannot lower the complex multiply): points the stock RoPE at
+``diffusion_qwenimage21_rope``'s probed fma wrapper, bit-identical to the complex product. Two stock forms:
+diffusers 0.41.0 routes through ``ROPE_PER_DEVICE["cuda"]`` (its entry is swapped); main d42ebf9c dropped the table
+and the attention processor calls the module global ``apply_rotary_emb_qwen`` (the global is swapped, only while the
+processor matches a known source). Kill switch: ``UNSLOTH_DIFFUSION_QWEN_REAL_ROPE=0``
+(``UNSLOTH_DIFFUSION_Q21_REAL_ROPE=0`` also disables it).
"""
from __future__ import annotations
@@ -16,8 +19,13 @@ from typing import Any
QWEN_REAL_ROPE_ENV = "UNSLOTH_DIFFUSION_QWEN_REAL_ROPE"
_MODULE = "diffusers.models.transformers.transformer_qwenimage"
_FINGERPRINT = frozenset({"ba81dd3fc907c23a"}) # apply_rotary_emb_qwen, shared with Qwen-Image-2.1
+# QwenDoubleStreamAttnProcessor2_0.__call__ sources that call the module global apply_rotary_emb_qwen(..., use_real=False)
+# directly (no ROPE_PER_DEVICE table): main d42ebf9c.
+_PROCESSOR_FINGERPRINT = frozenset({"98406ca5a85151f8"})
+_PROCESSOR = "QwenDoubleStreamAttnProcessor2_0"
_LOCK = threading.Lock()
_STOCK: dict = {}
+_STOCK_GLOBAL: dict = {} # id(module) -> (module, stock apply_rotary_emb_qwen), the table-less form
def disabled() -> bool:
@@ -41,6 +49,8 @@ def _patch_table(index: int, logger: Any = None) -> bool:
return False
mod = importlib.import_module(_MODULE)
table = getattr(mod, "ROPE_PER_DEVICE", None)
+ if table is None:
+ return _patch_global(mod, index, logger)
entry = table.get("cuda") if isinstance(table, dict) else None
if entry is None:
return False
@@ -75,6 +85,59 @@ def _patch_table(index: int, logger: Any = None) -> bool:
return True
+def _probe(index: int) -> bool:
+ import torch
+
+ from . import diffusion_qwenimage21_rope as q21
+
+ # Per device, even once patched: the wrapper keeps the complex path on an unprobed index.
+ if index not in q21._FUSION:
+ q21._FUSION[index] = q21.probe_fusion(torch.device("cuda", index))
+ return q21._FUSION[index] is not None
+
+
+def _patch_global(
+ mod: Any,
+ index: int,
+ logger: Any = None,
+) -> bool:
+ """No table (main d42ebf9c): swap the module global the attention processor calls."""
+ from . import diffusion_qwenimage21_rope as q21
+
+ with _LOCK:
+ current = getattr(mod, "apply_rotary_emb_qwen", None)
+ patched = getattr(current, "__unsloth_real_rope__", False)
+ if not patched:
+ processor = getattr(mod, _PROCESSOR, None)
+ call = vars(processor).get("__call__") if isinstance(processor, type) else None
+ if (
+ current is None
+ or q21._digest(current) not in _FINGERPRINT
+ or call is None
+ or q21._digest(call) not in _PROCESSOR_FINGERPRINT
+ ):
+ if logger is not None:
+ logger.info(
+ "diffusion.qwenimage_rope: complex RoPE kept: RoPE call site differs"
+ )
+ return False
+ if not _probe(index):
+ return False
+ if patched:
+ return True
+ q21._NEEDS_EMULATE[0] = q21._addcmul_lowering()[1]
+ wrapper = q21._WRAPPERS.get(current)
+ if wrapper is None:
+ wrapper = q21._WRAPPERS[current] = q21._make_rope(current)
+ _STOCK_GLOBAL[id(mod)] = (mod, current)
+ mod.apply_rotary_emb_qwen = wrapper
+ if logger is not None:
+ logger.info(
+ "diffusion.qwenimage_rope: RoPE runs in real arithmetic inside the compiled blocks"
+ )
+ return True
+
+
def install(transformer: Any, logger: Any = None) -> bool:
"""Before the first compile; patches at the first forward if the DiT is not yet on the GPU."""
if disabled():
@@ -109,3 +172,6 @@ def uninstall(transformer: Any = None) -> None:
for table, entry in list(_STOCK.values()):
table["cuda"] = entry
_STOCK.clear()
+ for mod, stock in list(_STOCK_GLOBAL.values()):
+ mod.apply_rotary_emb_qwen = stock
+ _STOCK_GLOBAL.clear()
diff --git a/studio/backend/core/inference/diffusion_te_prequant.py b/studio/backend/core/inference/diffusion_te_prequant.py
index 10811d336c1..cfff60b79b7 100644
--- a/studio/backend/core/inference/diffusion_te_prequant.py
+++ b/studio/backend/core/inference/diffusion_te_prequant.py
@@ -55,6 +55,20 @@ TE_INT8_CONVROT_FILES: dict[str, dict[str, tuple[str, str]]] = {
"Qwen-Image-2.1-text_encoder-INT8-ConvRot.safetensors",
),
},
+ # Qwen3-VL-4B, the same build as BFL's qwen3vl_4b_int8_convrot except that embed_tokens stays bf16: every int8
+ # projection matches BFL's byte for byte. The base and distilled repos carry the same bytes (one encoder).
+ "flux.3-klein": {
+ "text_encoder": (
+ "unsloth/flux-3-image-klein-FP8",
+ "flux-3-image-klein-text_encoder-INT8-ConvRot.safetensors",
+ ),
+ },
+ "flux.3-klein-base": {
+ "text_encoder": (
+ "unsloth/flux-3-image-klein-base-FP8",
+ "flux-3-image-klein-base-text_encoder-INT8-ConvRot.safetensors",
+ ),
+ },
}
# The scheme the loaded FILE carried ("fp8" / "int8"), so quantize_text_encoders never re-casts an int8 encoder.
@@ -132,6 +146,15 @@ TE_PREQUANT_BUDGET_SCALE = 0.65
# The int8 ConvRot encoder alone (no fp8 fallback to cover): Qwen-Image-2.1's is 9,349,769,248 bytes against
# 17,534,339,488 for the dense encoder, 0.533, rounded up.
TE_INT8_CONVROT_BUDGET_SCALE = 0.56
+# Per family where the default under-states: FLUX.3's Qwen3-VL-4B file is 5,247,076,320 bytes against 8,875,719,344
+# dense, 0.591 (its bf16 embedding table is a larger share of a 4B encoder), rounded up.
+_TE_INT8_CONVROT_BUDGET_SCALES = {"flux.3-klein": 0.60, "flux.3-klein-base": 0.60}
+
+
+def te_int8_convrot_budget_scale(fam: Any) -> float:
+ """Fraction of the bf16 encoder the family's int8 ConvRot file occupies, for memory budgeting."""
+ name = str(getattr(fam, "name", fam) or "").strip().lower()
+ return _TE_INT8_CONVROT_BUDGET_SCALES.get(name, TE_INT8_CONVROT_BUDGET_SCALE)
def te_prequant_budget_scale(
@@ -166,7 +189,7 @@ def te_prequant_budget_scale(
if not sources:
return 1.0
if _int8_convrot_only(te_quant_mode, target):
- return TE_INT8_CONVROT_BUDGET_SCALE
+ return te_int8_convrot_budget_scale(fam)
return TE_PREQUANT_BUDGET_SCALE
@@ -204,6 +227,13 @@ _TE_EQUIVALENT_BASES: tuple[frozenset[str], ...] = (
"qwen/qwen-image-2.1-turbo",
}
),
+ # Qwen3-VL-4B: the FLUX.3 Klein distilled and base text_encoder/ shards carry identical sha256 (2026-10-16)
+ frozenset(
+ {
+ "black-forest-labs/flux-3-image-klein",
+ "black-forest-labs/flux-3-image-klein-base",
+ }
+ ),
# Qwen3-4B: identical sha256 across the Krea-2 pair (compared 2026-08-25)
frozenset(
{
@@ -262,6 +292,25 @@ def int8_convrot_te_runs_on(target: Any) -> bool:
return getattr(target, "device", None) == "mps"
+def hosted_int8_convrot_te_runs_on(fam: Any, target: Any) -> bool:
+ """Whether an explicit int8 encoder request on ``fam`` loads the hosted int8 ConvRot file on ``target`` without the
+ fp8 fallback: the family hosts the file (and the lm_head trim it needs is on) and the device runs it as plain
+ tensors. Pure: no IO."""
+ try:
+ if not int8_convrot_te_runs_on(target):
+ return False
+ hosted = family_te_int8_convrot(fam, "text_encoder")
+ source = resolve_te_prequant_source(fam, "text_encoder", "int8")
+ return (
+ hosted is not None
+ and source is not None
+ and source.kind == "repo"
+ and source.filename == hosted[1]
+ )
+ except Exception: # noqa: BLE001 -- unresolvable means the runtime-cast rules apply
+ return False
+
+
def _is_fp8_te_name(name: Optional[str]) -> bool:
return bool(name) and "fp8" in str(name).lower()
@@ -519,6 +568,7 @@ def load_prequant_text_encoder(
local_files_only: bool = False,
trim_lm_head: bool = False,
failures: Optional[list] = None,
+ config_source: Optional[str] = None,
) -> Optional[Any]:
"""Load the pre-cast text encoder described by ``source`` (on CPU, for pipeline
assembly to place), with the layerwise upcast hooks already installed.
@@ -533,7 +583,10 @@ def load_prequant_text_encoder(
the pipeline's assembly normally passes to ``from_pretrained`` (forward-behaviour
flags only; the state dict is unaffected by them).
``trim_lm_head`` builds the encoder without its untied ``lm_head`` and never reads that tensor
- (``diffusion_text_encoder_trim``). ``failures`` collects the error text of a load that raised."""
+ (``diffusion_text_encoder_trim``). ``failures`` collects the error text of a load that raised.
+ ``config_source`` is where the encoder config is read when it is not ``base``: the staged directory the
+ pipeline itself assembles from, which a cache-only load may have resolved under another cache root. ``base``
+ stays the canonical id the checkpoint is validated against."""
try:
if source.kind == "path" and not _local_prequant_path_allowed(source.location):
_warn(
@@ -620,7 +673,7 @@ def load_prequant_text_encoder(
}
if subfolder:
config_kwargs["subfolder"] = subfolder
- config = transformers.AutoConfig.from_pretrained(base, **config_kwargs)
+ config = transformers.AutoConfig.from_pretrained(config_source or base, **config_kwargs)
# Krea-2 ships transformers-5.x configs whose rope lives under rope_parameters; the runtime component loader
# remaps it for a 4.x runtime, and the meta-init here must match or the rebuilt encoder forwards with a broken
# rope.
@@ -749,6 +802,7 @@ def te_prequant_pipe_kwargs(
logger: Any = None,
local_files_only: bool = False,
dense_source: Optional[str] = None,
+ config_source: Optional[str] = None,
) -> dict[str, Any]:
supplied = supplied_component_pipe_kwargs(
base,
@@ -769,6 +823,7 @@ def te_prequant_pipe_kwargs(
local_files_only = local_files_only,
skip_components = tuple(supplied),
dense_source = dense_source,
+ config_source = config_source,
)
injected.update(supplied)
return injected
@@ -786,6 +841,7 @@ def _te_prequant_pipe_kwargs(
local_files_only: bool = False,
skip_components: tuple = (),
dense_source: Optional[str] = None,
+ config_source: Optional[str] = None,
) -> dict[str, Any]:
"""Component overrides for pipeline assembly: ``{<component>: <pre-cast encoder>}``
for every ``TE_PREQUANT_COMPONENTS`` attr the family hosts a pre-cast checkpoint for
@@ -834,6 +890,7 @@ def _te_prequant_pipe_kwargs(
local_files_only = local_files_only,
trim_lm_head = trim,
failures = failures,
+ config_source = config_source,
)
fp8_names = tuple(
n for n in te_candidate_filenames(source) if n != getattr(source, "filename", None)
@@ -863,6 +920,7 @@ def _te_prequant_pipe_kwargs(
local_files_only = local_files_only,
trim_lm_head = trim,
failures = failures,
+ config_source = config_source,
)
if encoder is not None:
injected[component] = encoder
@@ -921,7 +979,13 @@ def _build_int8_convrot_encoder(
import torch
from accelerate import init_empty_weights
- from .diffusion_text_encoder_trim import LM_HEAD_KEY, trim_text_encoder
+ from .diffusion_text_encoder_trim import (
+ LM_HEAD_KEY,
+ _no_logits_head_class,
+ config_ties_lm_head,
+ is_trimmed,
+ trim_text_encoder,
+ )
from .video_minimax_h3_te import (
H3_TE_CONVROT_GROUP,
_int8_convrot_linear_class,
@@ -942,6 +1006,11 @@ def _build_int8_convrot_encoder(
with init_empty_weights(include_buffers = False):
encoder = encoder_cls(config)
trim_text_encoder(encoder)
+ if not is_trimmed(encoder) and config_ties_lm_head(config):
+ # A tied head (FLUX.3's Qwen3-VL-4B) is kept by the trim, but this file has no lm_head key for it and the
+ # family reads hidden states only, so drop it here: a meta head would fail the strict load below.
+ head = encoder.lm_head
+ encoder.lm_head = _no_logits_head_class()(head.in_features, head.out_features)
linear_cls = _int8_convrot_linear_class()
for prefix in quantized:
blob = state_dict.pop(prefix + quant_suffix, None)
diff --git a/studio/backend/core/inference/diffusion_text_encoder_trim.py b/studio/backend/core/inference/diffusion_text_encoder_trim.py
index 61bb8cff794..9b741845d99 100644
--- a/studio/backend/core/inference/diffusion_text_encoder_trim.py
+++ b/studio/backend/core/inference/diffusion_text_encoder_trim.py
@@ -19,7 +19,8 @@ KEEP_LM_HEAD_ENV = "UNSLOTH_TE_KEEP_LM_HEAD"
# By class name so this module never imports transformers.
_HIDDEN_STATE_ONLY_CLASSES = frozenset({"Qwen3VLForConditionalGeneration"})
-_HIDDEN_STATE_ONLY_FAMILIES = frozenset({"qwen-image-2.1"})
+# FLUX.3 Klein stacks hidden_states[4..32] (diffusers Flux3TextEncoderStep) and never reads logits.
+_HIDDEN_STATE_ONLY_FAMILIES = frozenset({"qwen-image-2.1", "flux.3-klein", "flux.3-klein-base"})
LM_HEAD_KEY = "lm_head.weight"
diff --git a/studio/backend/core/inference/diffusion_transformer_quant.py b/studio/backend/core/inference/diffusion_transformer_quant.py
index eb92dd9a75b..05e9025bc4b 100644
--- a/studio/backend/core/inference/diffusion_transformer_quant.py
+++ b/studio/backend/core/inference/diffusion_transformer_quant.py
@@ -91,6 +91,13 @@ _INT8_FAMILY_EXCLUDE_NAME_TOKENS: dict[str, tuple[str, ...]] = _profile_table(
_QWENIMAGE_INT8_EXCLUDES = _INT8_FAMILY_EXCLUDE_NAME_TOKENS["qwen-image"]
+# ALL-scheme PER-FAMILY exclusions (``FamilyProfile.quant_exclude_tokens``): unlike the int8 table above, these also
+# apply to fp8 / mxfp8 / nvfp4, whose scaled_mm paths otherwise quantise every eligible Linear.
+_FAMILY_QUANT_EXCLUDE_NAME_TOKENS: dict[str, tuple[str, ...]] = _profile_table(
+ "quant_exclude_tokens", quant = True
+)
+
+
# Int8 PER-FAMILY row PADDING (``FamilyProfile.int8_pad_tokens``), the alternative to excluding a small-M Linear.
# ``_int_mm``'s floor is a GEMM shape constraint, not a numerical one: padding the activation up to 32 rows, running
# the matmul and slicing the result back returns the caller's rows BITWISE unchanged (torchao's int8 dynamic path
@@ -290,6 +297,46 @@ def zero_row_tokens_for_scheme(scheme: str, family: Optional[str] = None) -> tup
return _NVFP4_FAMILY_ZERO_ROW_NAME_TOKENS.get(str(family or "").strip().lower(), ())
+# Weight subclasses whose activation quantiser asserts a contiguous input (torchao ``to_mx`` "unsupported",
+# ``nvfp4_quantize`` "Only support contiguous data for now"), and whose dispatch has no op for a stride-0 view.
+_CONTIGUOUS_INPUT_WEIGHTS = frozenset({"MXTensor", "NVFP4Tensor"})
+
+
+def _contiguous_input_pre_hook(module: Any, args: tuple) -> Optional[tuple]:
+ if args and hasattr(args[0], "is_contiguous") and not args[0].is_contiguous():
+ return (args[0].contiguous(), *args[1:])
+ return None
+
+
+def guard_contiguous_activations(module: Any, *, logger: Any = None) -> int:
+ """Hand MX / NVFP4 Linears a contiguous activation. A broadcast input such as ``temb.expand(B, S, D)`` (FLUX.3's
+ per-token modulation, any adaLN fed an expanded embedding) is a stride-0 view; torchao's MX and NVFP4 activation
+ quantisers assert contiguity and crash at the first denoise step. ``contiguous()`` is a no-op for the contiguous
+ inputs every other call passes, and dynamo traces the pre-hook into the compiled graph. Idempotent; returns how
+ many Linears it hooked."""
+ named = getattr(module, "named_modules", None)
+ if not callable(named):
+ return 0
+ hooked = 0
+ for _name, sub in named():
+ weight = getattr(sub, "weight", None)
+ if type(weight).__name__ not in _CONTIGUOUS_INPUT_WEIGHTS or getattr(
+ sub, "_unsloth_contig_hook", False
+ ):
+ continue
+ try:
+ sub.register_forward_pre_hook(_contiguous_input_pre_hook)
+ sub._unsloth_contig_hook = True
+ hooked += 1
+ except Exception: # noqa: BLE001 - a module refusing hooks keeps its old behaviour
+ continue
+ if hooked and logger is not None:
+ logger.info(
+ "diffusion.transformer_quant: contiguous-input guard on %d MX/NVFP4 linears", hooked
+ )
+ return hooked
+
+
def apply_zero_row_guard(
transformer: Any,
scheme: str,
@@ -297,7 +344,9 @@ def apply_zero_row_guard(
*,
logger: Any = None,
) -> tuple[str, ...]:
- """Guard zero-row-reachable quantized Linears; call AFTER quantization (else the first t2v render crashes)."""
+ """Guard zero-row-reachable quantized Linears; call AFTER quantization (else the first t2v render crashes). Every
+ post-quantisation site calls this, so it also installs the contiguous-input guard for MX / NVFP4 weights."""
+ guard_contiguous_activations(transformer, logger = logger)
tokens = zero_row_tokens_for_scheme(scheme, family)
if not tokens:
return ()
@@ -321,12 +370,15 @@ def exclude_tokens_for_scheme(scheme: str, family: Optional[str] = None) -> tupl
(_INT8_FAMILY_EXCLUDE_NAME_TOKENS); other schemes (scaled_mm) exclude nothing.
``family=None`` preserves the historical behaviour. Shared by the runtime path and the
offline prequant builder so they never drift (else an int8 checkpoint bakes the small-M
- projections and crashes at the first denoise on Flux / Qwen)."""
+ projections and crashes at the first denoise on Flux / Qwen). ``FamilyProfile.quant_exclude_tokens`` applies
+ to every scheme."""
+ key = str(family or "").strip().lower()
+ every_scheme = _FAMILY_QUANT_EXCLUDE_NAME_TOKENS.get(key, ())
if scheme == TQ_INT8:
- return _INT8_EXCLUDE_NAME_TOKENS + _INT8_FAMILY_EXCLUDE_NAME_TOKENS.get(
- str(family or "").strip().lower(), ()
+ return (
+ _INT8_EXCLUDE_NAME_TOKENS + _INT8_FAMILY_EXCLUDE_NAME_TOKENS.get(key, ()) + every_scheme
)
- return ()
+ return every_scheme
_SCHEME_DIVISIBLE: dict[str, int] = {TQ_FP8: 16, TQ_NVFP4: 16, TQ_MXFP8: 32}
diff --git a/studio/backend/core/inference/family_profile.py b/studio/backend/core/inference/family_profile.py
index 2e6f93c6007..73227f23230 100644
--- a/studio/backend/core/inference/family_profile.py
+++ b/studio/backend/core/inference/family_profile.py
@@ -70,6 +70,10 @@ class FamilyProfile:
# int8 name tokens left dense on top of the generic M = 1 tokens (``_int_mm`` needs M > 16, or a measured quality
# lever). Baked into published int8 artifacts.
int8_exclude_tokens: tuple[str, ...] = ()
+ # Name tokens left dense for EVERY transformer-quant scheme (int8 / fp8 / mxfp8 / nvfp4), on top of the int8
+ # tokens above. For layers whose quantisation error is measured to dominate the image delta regardless of the
+ # scheme (FLUX.3: per-token modulations, the 20480-wide text projection, the text-stream per-mode blocks).
+ quant_exclude_tokens: tuple[str, ...] = ()
# int8 name tokens whose small-M Linears get activation rows PADDED to the ``_int_mm`` floor instead of excluded.
int8_pad_tokens: tuple[str, ...] = ()
int8_convrot: Optional[ConvRotSpec] = None
diff --git a/studio/backend/core/inference/media_auto_switch.py b/studio/backend/core/inference/media_auto_switch.py
index 520d1f4028c..292089967b5 100644
--- a/studio/backend/core/inference/media_auto_switch.py
+++ b/studio/backend/core/inference/media_auto_switch.py
@@ -232,14 +232,27 @@ async def _start_load(
"""Run the load its own route would run, as an API load rather than a user one."""
partition = expected_partition(pick)
if owner == DIFFUSION:
+ from core.inference.media_locality import flux3_seeded_cache_repo, seeded_family_override
from models.inference import DiffusionLoadRequest
from routes.inference import load_diffusion_model_gated
+
+ # A seeded FLUX.3 snapshot loads by its repo id (an API load is cache only), so the load plans the
+ # cached seed the locality check approved instead of opening dense shards the snapshot never held.
+ model_path = pick.model_path
+ family_override = None
+ seeded_repo = None if pick.gguf_filename else flux3_seeded_cache_repo(pick.model_path)
+ if seeded_repo:
+ model_path = seeded_repo
+ # The listing named the family from the snapshot's modular_model_index.json; an opaquely named repo id
+ # carries no such evidence, so the load is told the family the manifest declared.
+ family_override = seeded_family_override(pick.model_path, seeded_repo)
await load_diffusion_model_gated(
DiffusionLoadRequest(
- model_path = pick.model_path,
+ model_path = model_path,
display_repo_id = pick.model_id,
gguf_filename = pick.gguf_filename,
model_kind = pick.model_kind,
+ family_override = family_override,
hf_token = hf_token,
),
current_subject,
diff --git a/studio/backend/core/inference/media_locality.py b/studio/backend/core/inference/media_locality.py
index 62ed50952ed..f3227fc06fd 100644
--- a/studio/backend/core/inference/media_locality.py
+++ b/studio/backend/core/inference/media_locality.py
@@ -332,6 +332,18 @@ def _pipeline_components_present(root: Path) -> bool:
return False
if not isinstance(index, dict):
return False
+ if name == "modular_model_index.json" and _is_flux3_manifest(index):
+ # FLUX.3 loads a fixed set of components from fixed folders of this root and never follows a spec's
+ # source, so judge it on exactly those: the optional prompt upsampler the manifests list since
+ # 2026-10-16 lives in another (~19 GB) repo an image load never reads.
+ from core.inference.diffusion_families import local_pipeline_components_are_complete
+ from core.inference.diffusion_flux3 import FLUX3_COMPONENT_FOLDERS
+
+ if not local_pipeline_components_are_complete(
+ root, name, fixed_component_folders = FLUX3_COMPONENT_FOLDERS
+ ):
+ return False
+ continue
for component, entry in index.items():
if component.startswith("_") or not isinstance(entry, (list, tuple)):
continue
@@ -350,6 +362,58 @@ def _pipeline_components_present(root: Path) -> bool:
return True
+def flux3_seeded_cache_repo(path: Any) -> Optional[str]:
+ """The Hub repo id of a FLUX.3 snapshot in the HF cache (the one refs/main names) whose only gaps are the dense
+ transformer and text-encoder weights (what a download planned around a hosted pre-quantized seed leaves: the int8
+ ConvRot encoder is the default, so a normally staged snapshot holds no dense encoder shards either), or None.
+ Everything else the loader opens, both configs and the tokenizer included, must be there; whether the seeds or
+ the dense shards the load will open are cached is the download planner's question, asked of the repo id."""
+ import json
+ try:
+ snapshot = Path(path)
+ repo_dir = snapshot.parent.parent
+ if snapshot.parent.name != "snapshots" or not repo_dir.name.startswith("models--"):
+ return None
+ # A load by repo id resolves refs/main, so only the snapshot main names may be rewritten: another (or a
+ # commit-pinned) snapshot would be swapped for a different one.
+ if (repo_dir / "refs" / "main").read_text(encoding = "utf-8").strip() != snapshot.name:
+ return None
+ index = json.loads((snapshot / "modular_model_index.json").read_text(encoding = "utf-8-sig"))
+ if not isinstance(index, dict) or not _is_flux3_manifest(index):
+ return None
+ from core.inference.diffusion_families import local_pipeline_components_are_complete
+ from core.inference.diffusion_flux3 import FLUX3_COMPONENT_FOLDERS
+
+ if not local_pipeline_components_are_complete(
+ snapshot,
+ "modular_model_index.json",
+ excluded_components = ("transformer", "text_encoder"),
+ fixed_component_folders = FLUX3_COMPONENT_FOLDERS,
+ ):
+ return None
+ owner, _, name = repo_dir.name[len("models--") :].partition("--")
+ return f"{owner}/{name}" if owner and name else None
+ except (OSError, ValueError):
+ return None
+
+
+def seeded_family_override(local_path: Any, repo_id: str) -> Optional[str]:
+ """The family a seeded snapshot's modular_model_index.json declares, when its repo id alone would not name it
+ (an opaquely named repo), else None. Planning and loading by the repo id both need it."""
+ from core.inference.diffusion_families import detect_family_for_pick
+
+ local = detect_family_for_pick(str(local_path))
+ by_repo = detect_family_for_pick(repo_id)
+ if local is not None and (by_repo is None or by_repo.name != local.name):
+ return local.name
+ return None
+
+
+def _is_flux3_manifest(index: dict) -> bool:
+ from core.inference.diffusion_flux3 import flux3_index_family
+ return flux3_index_family(index) is not None
+
+
def _hosted_source(spec: Any) -> Optional[tuple[str, str, str, str]]:
"""What a modular index entry asks the loader for: repo, subfolder, revision and variant.
@@ -523,9 +587,18 @@ def missing_download_bytes(
would allow exactly the download this exists to prevent, so the switch refuses instead.
"""
target = normalized_pick(pick)
+ family_override = None
local_pipeline = not target.gguf_filename and Path(target.model_path).is_dir()
if local_pipeline and not _pipeline_components_present(Path(target.model_path)):
- return UNSIZED_MISSING
+ repo = flux3_seeded_cache_repo(target.model_path) if owner == DIFFUSION else None
+ if repo is None:
+ return UNSIZED_MISSING
+ # A FLUX.3 snapshot Studio staged for a pre-quantized seed holds no dense transformer shards: whether the seed
+ # is cached and is what the load picks is the planner's question, so ask it of the repo, which is also what
+ # the switch loads (cache only), instead of requiring dense weights the load never opens.
+ family_override = seeded_family_override(target.model_path, repo)
+ target = replace(target, model_path = repo)
+ local_pipeline = False
if owner == DIFFUSION:
# asked of every image pick, not only local pipelines: a single-file HiDream checkpoint plans clean and its
# assembly still loads the encoder repo unconditionally
@@ -547,6 +620,7 @@ def missing_download_bytes(
# SAME files the load will fetch. Clearing the probe drops the pre-cast encoder and the GGUF
# dense-transformer widening, which is how a "fully downloaded" answer goes wrong.
memory_verdict = False,
+ **({"family_override": family_override} if family_override else {}),
)
or {}
for planner in planners_for(owner, target)
@@ -573,6 +647,8 @@ __all__ = [
"encoder_repo_complete",
"hidden_ltx23_extras",
"is_edit_only",
+ "flux3_seeded_cache_repo",
+ "seeded_family_override",
"missing_download_bytes",
"normalized_pick",
"pin_planned_gpu_ordinal",
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 85655c2f62e..2d663a3394d 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -5347,6 +5347,9 @@ class DiffusionStatusResponse(BaseModel):
display_repo_id: Optional[str] = Field(None, description = "Logical Hub id of a local snapshot")
family: Optional[str] = Field(None, description = "Detected diffusion family")
supported_families: List[str] = Field(default_factory = list, description = "Loadable families")
+ modular_families: List[str] = Field(
+ default_factory = list, description = "Loadable families shipped as Modular Diffusers pipelines"
+ )
base_repo: Optional[str] = Field(None, description = "Companion diffusers base repo")
device: Optional[str] = Field(None, description = "Device the pipeline is on")
dtype: Optional[str] = Field(None, description = "Compute dtype")
diff --git a/studio/backend/requirements/diffusers-main.txt b/studio/backend/requirements/diffusers-main.txt
index e06a47fbeaf..896852bf09d 100644
--- a/studio/backend/requirements/diffusers-main.txt
+++ b/studio/backend/requirements/diffusers-main.txt
@@ -1,7 +1,9 @@
-# DISABLED while diffusers-pin.txt's release carries every family: the requirement line is commented
-# out and every step of the git route does nothing. To re-enable for an unreleased model, uncomment it
-# with the new commit + archive-sha256 and add the minimum to _UNRELEASED_MIN_DIFFUSERS
-# (diffusion_families.py). When active it installs by default; UNSLOTH_DIFFUSERS_MAIN=0 opts out.
+# INSTALLED BY DEFAULT, on top of diffusers-pin.txt. Set UNSLOTH_DIFFUSERS_MAIN=0 to opt out.
+# Today that is FLUX.3 Image Klein: Diffusers support merged as huggingface/diffusers#15046 on 2026-10-15 and is
+# in no release yet. The commit below is main as of 2026-10-16 (d42ebf9c, the FLUX.3 prompt upsampler block,
+# huggingface/diffusers#15058), which carries that merge; past it only FLUX.3 files changed. Studio drops the
+# upsampler step from the blocks (diffusion_flux3.flux3_blocks). Comment the line out again (and empty
+# _UNRELEASED_MIN_DIFFUSERS) once a release carries it.
#
# A pinned commit of Diffusers main, for models whose support has merged upstream but has not
# reached a release yet. The last one was Qwen-Image-2.1: it merged on 2026-09-18, four weeks after
@@ -24,8 +26,8 @@
# ``_direct_reference_is_installed`` compares what is recorded in direct_url.json and needs no
# network, while a branch ref costs a git ls-remote on every pass.
#
-# This exact commit is the tree the Qwen-Image-2.1 FP8 and INT8 artifacts were built and measured
-# against, so what a user gets is what was tested, not "whatever main was that day".
+# This exact commit is the tree FLUX.3 Klein was rendered and compared against in Studio, so what a
+# user gets is what was tested, not "whatever the branch was that day".
#
# Why the URL still says git+ when most hosts have no git. It is the requirement, not the transport:
# a host with no working git installs the same commit from
@@ -37,7 +39,7 @@
# Unlike a clone, an archive's bytes are not checked against the commit, so pip and uv verify this
# SHA-256 before building; no digest line means no zip route. Bump it with the commit:
# curl -sL https://github.com/huggingface/diffusers/archive/<commit>.zip | sha256sum
-# archive-sha256: 7b0d00b5b44f5ca1745d477ae4a0c2da125d58b89cff8470c422d3181a797a09
+# archive-sha256: c46925a12c1b64340272dbd4c5d72a4298ecd4c96cad2c9d549b85a99ffb491f
#
# Retiring a pin: bump diffusers-pin.txt to the release and comment the line out (done for 0.41.0).
-# diffusers @ git+https://github.com/huggingface/diffusers.git@80c7ed262aeffbeb43ef13ae04baeb9b84515a69
+diffusers @ git+https://github.com/huggingface/diffusers.git@d42ebf9c6e0b46103b74283f5324357a67acaa04
diff --git a/studio/backend/tests/fixtures/diffusion_autoopt_parity.json b/studio/backend/tests/fixtures/diffusion_autoopt_parity.json
index 86056a11033..0dc592cb74b 100644
--- a/studio/backend/tests/fixtures/diffusion_autoopt_parity.json
+++ b/studio/backend/tests/fixtures/diffusion_autoopt_parity.json
@@ -1,5 +1,5 @@
{
- "meta": {"base": "origin/main 5f38afbc2d (before diffusion_autoopt)", "dtypes": ["bfloat16", "float16"], "families": ["image|flux.1", "image|flux.1-kontext", "image|flux.2-dev", "image|flux.2-klein", "image|hidream-i1", "image|hunyuanimage-2.1", "image|ideogram-4", "image|krea-2", "image|lumina-2", "image|qwen-image", "image|qwen-image-2.1", "image|qwen-image-edit", "image|qwen-image-layered", "image|sdxl", "image|z-image", "video|hunyuanvideo-1.5", "video|hunyuanvideo-1.5-720p", "video|ltx-2", "video|ltx-2.5", "video|minimax-h3", "video|wan2.1-t2v-1.3b", "video|wan2.1-t2v-14b", "video|wan2.2-t2v-a14b", "video|wan2.2-ti2v-5b"], "speeds": ["off", "eager", "default", "max"]},
+ "meta": {"base": "origin/main 5f38afbc2d (before diffusion_autoopt)", "dtypes": ["bfloat16", "float16"], "families": ["image|flux.1", "image|flux.1-kontext", "image|flux.2-dev", "image|flux.2-klein", "image|flux.3-klein", "image|flux.3-klein-base", "image|hidream-i1", "image|hunyuanimage-2.1", "image|ideogram-4", "image|krea-2", "image|lumina-2", "image|qwen-image", "image|qwen-image-2.1", "image|qwen-image-edit", "image|qwen-image-layered", "image|sdxl", "image|z-image", "video|hunyuanvideo-1.5", "video|hunyuanvideo-1.5-720p", "video|ltx-2", "video|ltx-2.5", "video|minimax-h3", "video|wan2.1-t2v-1.3b", "video|wan2.1-t2v-14b", "video|wan2.2-t2v-a14b", "video|wan2.2-ti2v-5b"], "speeds": ["off", "eager", "default", "max"]},
"cases": {
"image|flux.1-kontext|default|bfloat16|offload=0|gguf=0": {"applied":[["compiled","cuda_graph","cudnn_benchmark","fp16_accum"]],"graph_after_placement":false,"graph_reason":"eligible","keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"modules":{"transformer":{"auto_dynamic":false,"compile_calls":[{"dynamic":true,"fullgraph":true}],"int8_gemm":false,"static":false}},"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false}},
"image|flux.1-kontext|default|bfloat16|offload=0|gguf=1": {"applied":[["compiled_dequant","cuda_graph","cudnn_benchmark","fp16_accum"]],"graph_after_placement":false,"graph_reason":"eligible","keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"modules":{"transformer":{"auto_dynamic":null,"compile_calls":[],"int8_gemm":false,"static":false}},"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false}},
@@ -129,6 +129,70 @@
"image|flux.2-klein|off|float16|offload=0|gguf=1": {"applied":[[]],"graph_after_placement":false,"graph_reason":null,"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"modules":{"transformer":{"auto_dynamic":null,"compile_calls":[],"int8_gemm":false,"static":false}},"patches":{"flux2_rope":true,"qwenimage21_fast_step":false,"rocm_fused":false}},
"image|flux.2-klein|off|float16|offload=1|gguf=0": {"applied":[[]],"graph_after_placement":false,"graph_reason":null,"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"modules":{"transformer":{"auto_dynamic":null,"compile_calls":[],"int8_gemm":false,"static":false}},"patches":{"flux2_rope":true,"qwenimage21_fast_step":false,"rocm_fused":false}},
"image|flux.2-klein|off|float16|offload=1|gguf=1": {"applied":[[]],"graph_after_placement":false,"graph_reason":null,"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"modules":{"transformer":{"auto_dynamic":null,"compile_calls":[],"int8_gemm":false,"static":false}},"patches":{"flux2_rope":true,"qwenimage21_fast_step":false,"rocm_fused":false}},
+ "image|flux.3-klein-base|default|bfloat16|offload=0|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cuda_graph","cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[{"fullgraph":true,"dynamic":true}],"static":false,"auto_dynamic":false,"int8_gemm":false}}},
+ "image|flux.3-klein-base|default|bfloat16|offload=0|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled_dequant","cuda_graph","cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|default|bfloat16|offload=1|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[{"fullgraph":false,"dynamic":true}],"static":false,"auto_dynamic":false,"int8_gemm":false}}},
+ "image|flux.3-klein-base|default|bfloat16|offload=1|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled_dequant","cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|default|float16|offload=0|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cuda_graph","cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[{"fullgraph":true,"dynamic":true}],"static":false,"auto_dynamic":false,"int8_gemm":false}}},
+ "image|flux.3-klein-base|default|float16|offload=0|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled_dequant","cuda_graph","cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|default|float16|offload=1|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[{"fullgraph":false,"dynamic":true}],"static":false,"auto_dynamic":false,"int8_gemm":false}}},
+ "image|flux.3-klein-base|default|float16|offload=1|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled_dequant","cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|eager|bfloat16|offload=0|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|eager|bfloat16|offload=0|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|eager|bfloat16|offload=1|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|eager|bfloat16|offload=1|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|eager|float16|offload=0|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|eager|float16|offload=0|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|eager|float16|offload=1|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|eager|float16|offload=1|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|max|bfloat16|offload=0|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cuda_graph","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[{"fullgraph":true,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein-base|max|bfloat16|offload=0|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cuda_graph","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[{"fullgraph":true,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein-base|max|bfloat16|offload=1|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[{"fullgraph":false,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein-base|max|bfloat16|offload=1|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[{"fullgraph":false,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein-base|max|float16|offload=0|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cuda_graph","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[{"fullgraph":true,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein-base|max|float16|offload=0|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cuda_graph","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[{"fullgraph":true,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein-base|max|float16|offload=1|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[{"fullgraph":false,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein-base|max|float16|offload=1|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[{"fullgraph":false,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein-base|off|bfloat16|offload=0|gguf=0": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|off|bfloat16|offload=0|gguf=1": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|off|bfloat16|offload=1|gguf=0": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|off|bfloat16|offload=1|gguf=1": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|off|float16|offload=0|gguf=0": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|off|float16|offload=0|gguf=1": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|off|float16|offload=1|gguf=0": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein-base|off|float16|offload=1|gguf=1": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|default|bfloat16|offload=0|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cuda_graph","cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[{"fullgraph":true,"dynamic":true}],"static":false,"auto_dynamic":false,"int8_gemm":false}}},
+ "image|flux.3-klein|default|bfloat16|offload=0|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled_dequant","cuda_graph","cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|default|bfloat16|offload=1|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[{"fullgraph":false,"dynamic":true}],"static":false,"auto_dynamic":false,"int8_gemm":false}}},
+ "image|flux.3-klein|default|bfloat16|offload=1|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled_dequant","cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|default|float16|offload=0|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cuda_graph","cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[{"fullgraph":true,"dynamic":true}],"static":false,"auto_dynamic":false,"int8_gemm":false}}},
+ "image|flux.3-klein|default|float16|offload=0|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled_dequant","cuda_graph","cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|default|float16|offload=1|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[{"fullgraph":false,"dynamic":true}],"static":false,"auto_dynamic":false,"int8_gemm":false}}},
+ "image|flux.3-klein|default|float16|offload=1|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled_dequant","cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|eager|bfloat16|offload=0|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|eager|bfloat16|offload=0|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|eager|bfloat16|offload=1|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|eager|bfloat16|offload=1|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark","fp16_accum"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|eager|float16|offload=0|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|eager|float16|offload=0|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|eager|float16|offload=1|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|eager|float16|offload=1|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["cudnn_benchmark"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|max|bfloat16|offload=0|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cuda_graph","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[{"fullgraph":true,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein|max|bfloat16|offload=0|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cuda_graph","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[{"fullgraph":true,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein|max|bfloat16|offload=1|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[{"fullgraph":false,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein|max|bfloat16|offload=1|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[{"fullgraph":false,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein|max|float16|offload=0|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cuda_graph","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[{"fullgraph":true,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein|max|float16|offload=0|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cuda_graph","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"eligible","graph_after_placement":false,"modules":{"transformer":{"compile_calls":[{"fullgraph":true,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein|max|float16|offload=1|gguf=0": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[{"fullgraph":false,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein|max|float16|offload=1|gguf=1": {"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[["compiled","cudnn_benchmark","fp16_accum","tf32"]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":"armed after placement","graph_after_placement":true,"modules":{"transformer":{"compile_calls":[{"fullgraph":false,"dynamic":null,"mode":"max-autotune-no-cudagraphs"}],"static":false,"auto_dynamic":true,"int8_gemm":false}}},
+ "image|flux.3-klein|off|bfloat16|offload=0|gguf=0": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|off|bfloat16|offload=0|gguf=1": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|off|bfloat16|offload=1|gguf=0": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|off|bfloat16|offload=1|gguf=1": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|off|float16|offload=0|gguf=0": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|off|float16|offload=0|gguf=1": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|off|float16|offload=1|gguf=0": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
+ "image|flux.3-klein|off|float16|offload=1|gguf=1": {"patches":{"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false},"applied":[[]],"keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"graph_reason":null,"graph_after_placement":false,"modules":{"transformer":{"compile_calls":[],"static":false,"auto_dynamic":null,"int8_gemm":false}}},
"image|hidream-i1|default|bfloat16|offload=0|gguf=0": {"applied":[["cuda_graph","cudnn_benchmark","fp16_accum"]],"graph_after_placement":false,"graph_reason":"eligible","keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"modules":{"transformer":{"auto_dynamic":false,"compile_calls":[],"int8_gemm":false,"static":false}},"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false}},
"image|hidream-i1|default|bfloat16|offload=0|gguf=1": {"applied":[["compiled_dequant","cuda_graph","cudnn_benchmark","fp16_accum"]],"graph_after_placement":false,"graph_reason":"eligible","keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"modules":{"transformer":{"auto_dynamic":null,"compile_calls":[],"int8_gemm":false,"static":false}},"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false}},
"image|hidream-i1|default|bfloat16|offload=1|gguf=0": {"applied":[["cudnn_benchmark","fp16_accum"]],"graph_after_placement":true,"graph_reason":"armed after placement","keys":[["channels_last","compiled","compiled_dequant","compiled_vae_decode","cuda_graph","cudnn_benchmark","fp16_accum","fused_qkv","int8_gemm","rocm_query_chunks","tf32","vae_fp16_decode","vae_fused","vae_single_frame"]],"modules":{"transformer":{"auto_dynamic":false,"compile_calls":[],"int8_gemm":false,"static":false}},"patches":{"arch_fusions":true,"eager_fusions":true,"flux2_rope":false,"qwenimage21_fast_step":false,"rocm_fused":false}},
diff --git a/studio/backend/tests/fixtures/diffusion_family_data_freeze.json b/studio/backend/tests/fixtures/diffusion_family_data_freeze.json
index 1644164d485..9f337e94cf4 100644
--- a/studio/backend/tests/fixtures/diffusion_family_data_freeze.json
+++ b/studio/backend/tests/fixtures/diffusion_family_data_freeze.json
@@ -19,6 +19,12 @@
},
"black-forest-labs/FLUX.2-klein-base-9B": null
},
+ "flux.3-klein": {
+ "black-forest-labs/flux-3-image-klein": null
+ },
+ "flux.3-klein-base": {
+ "black-forest-labs/flux-3-image-klein-base": null
+ },
"hidream-i1": {
"HiDream-ai/HiDream-I1-Full": null
},
@@ -119,6 +125,14 @@
4,
1.0
],
+ "flux.3-klein": [
+ 16,
+ 1.0
+ ],
+ "flux.3-klein-base": [
+ 50,
+ 3.5
+ ],
"hidream-i1": [
50,
5.0
@@ -301,6 +315,16 @@
"filter_reduction_configs": false,
"filter_reduction_configs_archs": []
},
+ "flux.3-klein": {
+ "cudnn_benchmark": true,
+ "filter_reduction_configs": false,
+ "filter_reduction_configs_archs": []
+ },
+ "flux.3-klein-base": {
+ "cudnn_benchmark": true,
+ "filter_reduction_configs": false,
+ "filter_reduction_configs_archs": []
+ },
"hidream-i1": {
"cudnn_benchmark": true,
"filter_reduction_configs": false,
@@ -1148,6 +1172,252 @@
"preview_key": "flux2",
"te_int8_effective": "fp8"
},
+ "flux.3-klein": {
+ "auto": {
+ "convrot_filename": null,
+ "convrot_repo": null,
+ "convrot_spec": [
+ 0,
+ []
+ ],
+ "convrot_variant_repos": [],
+ "exclude": [
+ "modulation",
+ "timestep_embed",
+ "norm_out",
+ "txt_mode_blocks",
+ "context_embedder"
+ ],
+ "pad": [],
+ "zero_row": []
+ },
+ "auto_bf16_when_resident": null,
+ "bf16": {
+ "convrot_filename": null,
+ "convrot_repo": null,
+ "convrot_spec": [
+ 0,
+ []
+ ],
+ "convrot_variant_repos": [],
+ "exclude": [
+ "modulation",
+ "timestep_embed",
+ "norm_out",
+ "txt_mode_blocks",
+ "context_embedder"
+ ],
+ "pad": [],
+ "zero_row": []
+ },
+ "convrot_default_on": false,
+ "fp8": {
+ "convrot_filename": null,
+ "convrot_repo": null,
+ "convrot_spec": [
+ 0,
+ []
+ ],
+ "convrot_variant_repos": [],
+ "exclude": [
+ "modulation",
+ "timestep_embed",
+ "norm_out",
+ "txt_mode_blocks",
+ "context_embedder"
+ ],
+ "pad": [],
+ "zero_row": []
+ },
+ "int8": {
+ "convrot_filename": null,
+ "convrot_repo": null,
+ "convrot_spec": [
+ 0,
+ []
+ ],
+ "convrot_variant_repos": [],
+ "exclude": [
+ "norm",
+ "_mod",
+ "modulation",
+ "timestep_embed",
+ "guidance_embed",
+ "time_text_embed",
+ "pooled",
+ "time_embed",
+ "modulation",
+ "timestep_embed",
+ "norm_out",
+ "txt_mode_blocks",
+ "context_embedder"
+ ],
+ "pad": [],
+ "zero_row": []
+ },
+ "mxfp8": {
+ "convrot_filename": null,
+ "convrot_repo": null,
+ "convrot_spec": [
+ 0,
+ []
+ ],
+ "convrot_variant_repos": [],
+ "exclude": [
+ "modulation",
+ "timestep_embed",
+ "norm_out",
+ "txt_mode_blocks",
+ "context_embedder"
+ ],
+ "pad": [],
+ "zero_row": []
+ },
+ "nvfp4": {
+ "convrot_filename": null,
+ "convrot_repo": null,
+ "convrot_spec": [
+ 0,
+ []
+ ],
+ "convrot_variant_repos": [],
+ "exclude": [
+ "modulation",
+ "timestep_embed",
+ "norm_out",
+ "txt_mode_blocks",
+ "context_embedder"
+ ],
+ "pad": [],
+ "zero_row": []
+ },
+ "page": "image",
+ "preview_key": null,
+ "te_int8_effective": "fp8"
+ },
+ "flux.3-klein-base": {
+ "auto": {
+ "convrot_filename": null,
+ "convrot_repo": null,
+ "convrot_spec": [
+ 0,
+ []
+ ],
+ "convrot_variant_repos": [],
+ "exclude": [
+ "modulation",
+ "timestep_embed",
+ "norm_out",
+ "txt_mode_blocks",
+ "context_embedder"
+ ],
+ "pad": [],
+ "zero_row": []
+ },
+ "auto_bf16_when_resident": null,
+ "bf16": {
+ "convrot_filename": null,
+ "convrot_repo": null,
+ "convrot_spec": [
+ 0,
+ []
+ ],
+ "convrot_variant_repos": [],
+ "exclude": [
+ "modulation",
+ "timestep_embed",
+ "norm_out",
+ "txt_mode_blocks",
+ "context_embedder"
+ ],
+ "pad": [],
+ "zero_row": []
+ },
+ "convrot_default_on": false,
+ "fp8": {
+ "convrot_filename": null,
+ "convrot_repo": null,
+ "convrot_spec": [
+ 0,
+ []
+ ],
+ "convrot_variant_repos": [],
+ "exclude": [
+ "modulation",
+ "timestep_embed",
+ "norm_out",
+ "txt_mode_blocks",
+ "context_embedder"
+ ],
+ "pad": [],
+ "zero_row": []
+ },
+ "int8": {
+ "convrot_filename": null,
+ "convrot_repo": null,
+ "convrot_spec": [
+ 0,
+ []
+ ],
+ "convrot_variant_repos": [],
+ "exclude": [
+ "norm",
+ "_mod",
+ "modulation",
+ "timestep_embed",
+ "guidance_embed",
+ "time_text_embed",
+ "pooled",
+ "time_embed",
+ "modulation",
+ "timestep_embed",
+ "norm_out",
+ "txt_mode_blocks",
+ "context_embedder"
+ ],
+ "pad": [],
+ "zero_row": []
+ },
+ "mxfp8": {
+ "convrot_filename": null,
+ "convrot_repo": null,
+ "convrot_spec": [
+ 0,
+ []
+ ],
+ "convrot_variant_repos": [],
+ "exclude": [
+ "modulation",
+ "timestep_embed",
+ "norm_out",
+ "txt_mode_blocks",
+ "context_embedder"
+ ],
+ "pad": [],
+ "zero_row": []
+ },
+ "nvfp4": {
+ "convrot_filename": null,
+ "convrot_repo": null,
+ "convrot_spec": [
+ 0,
+ []
+ ],
+ "convrot_variant_repos": [],
+ "exclude": [
+ "modulation",
+ "timestep_embed",
+ "norm_out",
+ "txt_mode_blocks",
+ "context_embedder"
+ ],
+ "pad": [],
+ "zero_row": []
+ },
+ "page": "image",
+ "preview_key": null,
+ "te_int8_effective": "fp8"
+ },
"hidream-i1": {
"auto": {
"convrot_filename": null,
@@ -3205,6 +3475,12 @@
}
},
"family_scheme_deny": {
+ "flux.3-klein": [
+ "nvfp4"
+ ],
+ "flux.3-klein-base": [
+ "nvfp4"
+ ],
"qwen-image": [
"mxfp8",
"nvfp4"
@@ -3407,6 +3683,8 @@
"flux.1": "FLUX.1-dev",
"flux.2-dev": "FLUX.2-dev",
"flux.2-klein": "FLUX.2 Klein",
+ "flux.3-klein": "FLUX.3 Klein",
+ "flux.3-klein-base": "FLUX.3 Klein Base",
"krea-2": "Krea 2",
"ltx-2": "LTX-2",
"minimax-h3": "MiniMax-H3",
@@ -3422,6 +3700,8 @@
],
"trusted_image_repos": [
"alpha-vllm/lumina-image-2.0",
+ "black-forest-labs/flux-3-image-klein",
+ "black-forest-labs/flux-3-image-klein-base",
"black-forest-labs/flux.1-dev",
"black-forest-labs/flux.1-kontext-dev",
"black-forest-labs/flux.1-krea-dev",
diff --git a/studio/backend/tests/fixtures/vae_tile_configs.json b/studio/backend/tests/fixtures/vae_tile_configs.json
index ef2d0c7f4f8..0b7330b8df9 100644
--- a/studio/backend/tests/fixtures/vae_tile_configs.json
+++ b/studio/backend/tests/fixtures/vae_tile_configs.json
@@ -132,6 +132,96 @@
"use_quant_conv": true
}
},
+ "flux.3-klein": {
+ "kind": "image",
+ "repo": "unsloth/flux-3-image-klein-FP8",
+ "revision": "0e7c103d8ffafb0d4ccd8d82122375c878cdaf4d",
+ "config": {
+ "_class_name": "AutoencoderKLFlux2",
+ "_diffusers_version": "0.41.0.dev0",
+ "act_fn": "silu",
+ "batch_norm_eps": 0.0001,
+ "batch_norm_momentum": 0.1,
+ "block_out_channels": [
+ 128,
+ 256,
+ 512,
+ 512
+ ],
+ "decoder_block_out_channels": null,
+ "down_block_types": [
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D"
+ ],
+ "force_upcast": true,
+ "in_channels": 3,
+ "latent_channels": 32,
+ "layers_per_block": 2,
+ "mid_block_add_attention": true,
+ "norm_num_groups": 32,
+ "out_channels": 3,
+ "patch_size": [
+ 2,
+ 2
+ ],
+ "sample_size": 1024,
+ "up_block_types": [
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D"
+ ],
+ "use_post_quant_conv": true,
+ "use_quant_conv": true
+ }
+ },
+ "flux.3-klein-base": {
+ "kind": "image",
+ "repo": "unsloth/flux-3-image-klein-base-FP8",
+ "revision": "b96dfc4e77c3f4412183348f90fd9fd4901102a3",
+ "config": {
+ "_class_name": "AutoencoderKLFlux2",
+ "_diffusers_version": "0.41.0.dev0",
+ "act_fn": "silu",
+ "batch_norm_eps": 0.0001,
+ "batch_norm_momentum": 0.1,
+ "block_out_channels": [
+ 128,
+ 256,
+ 512,
+ 512
+ ],
+ "decoder_block_out_channels": null,
+ "down_block_types": [
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D",
+ "DownEncoderBlock2D"
+ ],
+ "force_upcast": true,
+ "in_channels": 3,
+ "latent_channels": 32,
+ "layers_per_block": 2,
+ "mid_block_add_attention": true,
+ "norm_num_groups": 32,
+ "out_channels": 3,
+ "patch_size": [
+ 2,
+ 2
+ ],
+ "sample_size": 1024,
+ "up_block_types": [
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D",
+ "UpDecoderBlock2D"
+ ],
+ "use_post_quant_conv": true,
+ "use_quant_conv": true
+ }
+ },
"flux.1-kontext": {
"kind": "image",
"repo": "unsloth/FLUX.1-Kontext-dev",
diff --git a/studio/backend/tests/test_diffusers_repair.py b/studio/backend/tests/test_diffusers_repair.py
index f412bee71f9..cfb86d6c89f 100644
--- a/studio/backend/tests/test_diffusers_repair.py
+++ b/studio/backend/tests/test_diffusers_repair.py
@@ -322,7 +322,7 @@ def _manifest(monkeypatch, manifest):
@pytest.mark.parametrize(
"min_python, manifest",
[
- ((99, 0), {}), # Python 3.9 against the real (3, 10) floor
+ ((99, 0), {}), # an interpreter below the floor (3.9 / 3.10 against the real (3, 11))
((3, 0), {"diffusers_main_repair": "failed"}),
((3, 0), {"step_results": {"diffusers-main.txt": "failed"}}),
],
@@ -445,7 +445,8 @@ def test_the_installer_exposes_the_repair_flag():
def _release_mode(monkeypatch, installed):
import importlib.metadata
- monkeypatch.setattr(dr, "_main_pin_active", _REAL_MAIN_PIN_ACTIVE)
+ # Release mode is a commented-out main pin, whichever state the shipped file is in.
+ monkeypatch.setattr(dr, "_main_pin_active", lambda: False)
monkeypatch.setattr(dr, "_installer_would_skip", _REAL_INSTALLER_WOULD_SKIP)
real_version = importlib.metadata.version
monkeypatch.setattr(
@@ -456,8 +457,9 @@ def _release_mode(monkeypatch, installed):
_installed_diffusers(monkeypatch, None) # an index install, whatever the host has
-def test_the_shipped_main_pin_is_inactive():
- assert _REAL_MAIN_PIN_ACTIVE() is False
+def test_the_shipped_main_pin_is_active():
+ # FLUX.3 Klein needs the pinned build (huggingface/diffusers#15046 merged but is unreleased).
+ assert _REAL_MAIN_PIN_ACTIVE() is True
@pytest.mark.parametrize("installed", ["0.41.0", "0.41.0.post1"])
diff --git a/studio/backend/tests/test_diffusion_autoopt_parity.py b/studio/backend/tests/test_diffusion_autoopt_parity.py
index 17ddad59a0c..5ea15a38a12 100644
--- a/studio/backend/tests/test_diffusion_autoopt_parity.py
+++ b/studio/backend/tests/test_diffusion_autoopt_parity.py
@@ -517,6 +517,17 @@ def test_fixture_covers_every_registered_family(captured):
), "a registry family was added / removed: regenerate the fixture"
+def _uncomparable(want: dict) -> set:
+ """Cases of families whose denoiser class the installed diffusers lacks (FLUX.3 before its diffusers pin): their
+ stub cannot carry the real ``_repeated_blocks`` the fixture was captured with, and such a family cannot load here."""
+ missing = {
+ f"{b}|{f.name}"
+ for b, f in _families()
+ if getattr(f, "transformer_class", None) and _real_class(f.transformer_class) is None
+ }
+ return {case for case in want if "|".join(case.split("|")[:2]) in missing}
+
+
def test_autoopt_resolves_the_same_optimizations_as_before(captured):
# The fixture was captured with diffusers installed; without it nothing compiles and the diffusers patches
# self-disable, so every case differs. Backend CI has no diffusers.
@@ -524,7 +535,8 @@ def test_autoopt_resolves_the_same_optimizations_as_before(captured):
got = snapshot(autoopt_entry)
want = captured["cases"]
assert set(got) == set(want)
- diffs = [case for case in want if got[case] != want[case]]
+ skip = _uncomparable(want)
+ diffs = [case for case in want if case not in skip and got[case] != want[case]]
assert not diffs, {case: {"before": want[case], "after": got[case]} for case in diffs[:5]}
@@ -533,7 +545,8 @@ def test_legacy_sequence_still_matches_fixture(captured):
pytest.importorskip("diffusers") # see test_autoopt_resolves_the_same_optimizations_as_before
got = snapshot(legacy_entry)
want = captured["cases"]
- diffs = [case for case in want if got.get(case) != want[case]]
+ skip = _uncomparable(want)
+ diffs = [case for case in want if case not in skip and got.get(case) != want[case]]
assert not diffs, {case: {"before": want[case], "now": got.get(case)} for case in diffs[:5]}
diff --git a/studio/backend/tests/test_diffusion_backend.py b/studio/backend/tests/test_diffusion_backend.py
index 1135f164add..0638d9d6691 100644
--- a/studio/backend/tests/test_diffusion_backend.py
+++ b/studio/backend/tests/test_diffusion_backend.py
@@ -229,7 +229,7 @@ def _all_cached(monkeypatch):
def test_gated_mirror_table_round_trips():
"""Both directions, exact case: canonical_base must hand back a real repo id."""
- assert len(_MIRROR_PAIRS) == 25
+ assert len(_MIRROR_PAIRS) == 27
for upstream, mirror in _MIRROR_PAIRS:
assert mirror_repo(upstream) == mirror
assert canonical_base(mirror) == upstream
@@ -251,7 +251,7 @@ def test_only_the_genuinely_gated_half_reads_as_gated():
exists". Klein base-4B is the one that makes this concrete: a default trainable base, which
is mirrored, and which the Hub serves anonymously.
"""
- assert len(_GATED_MIRROR_PAIRS) == 12
+ assert len(_GATED_MIRROR_PAIRS) == 14
assert len(_UNGATED_MIRROR_PAIRS) == 13
for upstream, _mirror in _GATED_MIRROR_PAIRS:
assert upstream_is_gated(upstream), upstream
diff --git a/studio/backend/tests/test_diffusion_flux3.py b/studio/backend/tests/test_diffusion_flux3.py
new file mode 100644
index 00000000000..482875c29f4
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_flux3.py
@@ -0,0 +1,2181 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""FLUX.3 Image Klein: family registration, the unreleased-diffusers gate, the modular-repo download
+plan, and the classic-pipeline face over the modular blocks. CPU only, no network, no FLUX.3 diffusers."""
+
+import json
+import sys
+import types
+from types import SimpleNamespace
+
+import pytest
+
+from core.inference import diffusion_families as families
+from core.inference.diffusion import (
+ _explicit_pipeline_components,
+ _is_trusted_diffusion_repo,
+ _pipeline_components_from_index,
+ _pipeline_file_downloaded,
+ _pipeline_selected_file,
+)
+from core.inference.diffusion_auto_policy import family_bf16_components_gb
+from core.inference.diffusion_families import (
+ default_generation_params,
+ detect_family,
+ detect_family_by_pipeline_class,
+ detect_family_by_pipeline_index,
+ family_pipeline_available,
+ pipeline_class_requirement,
+)
+from core.inference.diffusion_flux3 import (
+ FLUX3_BASE_BLOCKS,
+ FLUX3_COMPONENTS,
+ FLUX3_DISTILLED_BLOCKS,
+ FLUX3_KLEIN_BASE_FAMILY_NAME,
+ FLUX3_KLEIN_FAMILY_NAME,
+ _Flux3KleinPipelineMixin,
+ flux3_blocks_class,
+ is_flux3_family,
+)
+
+DISTILLED = "black-forest-labs/flux-3-image-klein"
+BASE = "black-forest-labs/flux-3-image-klein-base"
+
+
+# ── detection ────────────────────────────────────────────────────────────────
+ "repo_id, name",
+ [
+ (DISTILLED, FLUX3_KLEIN_FAMILY_NAME),
+ (BASE, FLUX3_KLEIN_BASE_FAMILY_NAME),
+ ("someone/flux3-klein-finetune", FLUX3_KLEIN_FAMILY_NAME),
+ ("someone/flux3-klein-base-lora-merge", FLUX3_KLEIN_BASE_FAMILY_NAME),
+ ("/models/FLUX-3-Image-Klein", FLUX3_KLEIN_FAMILY_NAME),
+ ],
+)
+def test_detect_family_flux3(repo_id, name):
+ fam = detect_family(repo_id)
+ assert fam is not None and fam.name == name
+ assert is_flux3_family(fam)
+ assert fam.transformer_class == "Flux3Transformer2DModel"
+
+
+def test_the_prompt_upsampler_is_not_an_image_model():
+ # flux-3-image-klein-pup is a Qwen3.5 LLM: matching it to the image family would try to build a DiT from it.
+ assert detect_family("black-forest-labs/flux-3-image-klein-pup") is None
+
+
+def test_flux2_and_flux1_detection_unchanged():
+ assert detect_family("black-forest-labs/FLUX.2-klein-4B").name == "flux.2-klein"
+ assert detect_family("black-forest-labs/FLUX.2-klein-base-9B").name == "flux.2-klein"
+ assert detect_family("black-forest-labs/FLUX.1-dev").name == "flux.1"
+
+
+def test_override_names():
+ assert detect_family("x", "flux.3-klein").name == FLUX3_KLEIN_FAMILY_NAME
+ assert detect_family("x", "flux.3-klein-base").name == FLUX3_KLEIN_BASE_FAMILY_NAME
+ assert FLUX3_KLEIN_FAMILY_NAME in families.supported_family_names()
+ assert FLUX3_KLEIN_BASE_FAMILY_NAME in families.supported_family_names()
+
+
+def test_family_records():
+ distilled = detect_family(DISTILLED)
+ base = detect_family(BASE)
+ for fam in (distilled, base):
+ # One text-to-image call takes up to 10 reference images (the BFL reference's MAX_REFERENCES).
+ assert fam.reference and fam.max_condition_images == 10
+ assert not fam.edit and not fam.unified_edit
+ assert fam.dimension_multiple == 16
+ # A single file / GGUF denoiser assembles around the base's modular companions.
+ assert not fam.pipeline_only
+ assert fam.supports_torch_compile
+ assert fam.condition_pixel_weight == 0.11
+ assert fam.img2img_pipeline_class is None and fam.inpaint_pipeline_class is None
+ # The flow-map checkpoint samples without CFG; the base runs CFG with a negative prompt.
+ assert distilled.uses_negative_prompt is False
+ assert base.uses_negative_prompt is True
+
+
+def test_modular_index_class_names_identify_the_family(tmp_path):
+ assert (
+ detect_family_by_pipeline_class("Flux3DistilledModularPipeline").name
+ == FLUX3_KLEIN_FAMILY_NAME
+ )
+ assert (
+ detect_family_by_pipeline_class("Flux3ModularPipeline").name == FLUX3_KLEIN_BASE_FAMILY_NAME
+ )
+ # An HF-cache snapshot leaf is a commit hash: the modular index is the only evidence.
+ (tmp_path / "modular_model_index.json").write_text(
+ json.dumps(
+ {
+ "_class_name": "Flux3DistilledModularPipeline",
+ "_blocks_class_name": FLUX3_DISTILLED_BLOCKS,
+ }
+ )
+ )
+ assert detect_family_by_pipeline_index(str(tmp_path)).name == FLUX3_KLEIN_FAMILY_NAME
+
+
+def test_official_repos_are_trusted():
+ assert _is_trusted_diffusion_repo(DISTILLED)
+ assert _is_trusted_diffusion_repo(BASE)
+
+
+def test_generation_defaults():
+ # ComfyUI's templates and the BFL reference: distilled 16 steps CFG 1, base 50 at 3.5.
+ assert default_generation_params(DISTILLED) == (16, 1.0)
+ assert default_generation_params(BASE) == (50, 3.5)
+ assert default_generation_params("flux3_klein_base_bf16.safetensors") == (50, 3.5)
+ assert default_generation_params("black-forest-labs/FLUX.2-klein-4B") == (4, 1.0)
+
+
+def test_bf16_component_table():
+ for repo in (DISTILLED, BASE):
+ transformer_gb, encoders_gb, vae_gb = family_bf16_components_gb(detect_family(repo))
+ assert 10.5 <= transformer_gb <= 11.5 # 5.55B params
+ assert 8.5 <= encoders_gb <= 9.5 # Qwen3-VL-4B
+ assert vae_gb <= 0.5
+
+
+# ── unreleased diffusers gate ────────────────────────────────────────────────
+def test_minimum_is_the_unreleased_next_release():
+ for cls in ("Flux3ModularPipeline", "Flux3DistilledModularPipeline"):
+ minimum, _ = pipeline_class_requirement(cls)
+ assert minimum == "0.42.0"
+ assert minimum in families._UNRELEASED_MIN_DIFFUSERS
+ message = families._too_old_message("Flux3DistilledModularPipeline", "flux.3-klein", "0.41.0")
+ assert "has not been released yet" in message
+
+
+def _fake_diffusers(monkeypatch, root, version):
+ module = types.ModuleType("diffusers")
+ module.__version__ = version
+ module.__spec__ = SimpleNamespace(submodule_search_locations = [str(root)])
+ monkeypatch.setitem(sys.modules, "diffusers", module)
+
+
+def test_listing_probes_the_module_file_not_the_version(tmp_path, monkeypatch):
+ # Main and the FLUX.3 branch both report 0.41.0.dev0, exactly what the 0.41.0 release without it reads as.
+ fam = detect_family(DISTILLED)
+ _fake_diffusers(monkeypatch, tmp_path, "0.41.0.dev0")
+ assert family_pipeline_available(fam) is False
+ target = tmp_path / "modular_pipelines" / "flux3" / "modular_pipeline.py"
+ target.parent.mkdir(parents = True)
+ target.write_text("")
+ assert family_pipeline_available(fam) is True
+ assert family_pipeline_available(detect_family(BASE)) is True
+
+
+def test_listing_falls_back_to_the_version_when_the_package_cannot_be_located(monkeypatch):
+ monkeypatch.setattr(families, "_diffusers_package_has_file", lambda relative: None)
+ monkeypatch.setattr(families, "_installed_diffusers_version", lambda: "0.42.0")
+ monkeypatch.delitem(sys.modules, "diffusers", raising = False)
+ assert family_pipeline_available(detect_family(DISTILLED)) is True
+ monkeypatch.setattr(families, "_installed_diffusers_version", lambda: "0.41.0")
+ assert family_pipeline_available(detect_family(DISTILLED)) is False
+
+
+# ── download plan for a modular repo ─────────────────────────────────────────
+_REPO_FILES = (
+ "modular_model_index.json",
+ "config.json",
+ "manifest.json",
+ "model.safetensors", # the BFL single file, 11 GB: never fetched
+ "ae.safetensors", # the BFL autoencoder: never fetched
+ "README.md",
+ "transformer/config.json",
+ "transformer/diffusion_pytorch_model-00001-of-00002.safetensors",
+ "transformer/diffusion_pytorch_model-00002-of-00002.safetensors",
+ "transformer/diffusion_pytorch_model.safetensors.index.json",
+ "text_encoder/config.json",
+ "text_encoder/model-00001-of-00002.safetensors",
+ "text_encoder/tokenizer.json",
+ "vae/config.json",
+ "vae/diffusion_pytorch_model.safetensors",
+ "variants/fp8r/model.safetensors",
+ "variants/nvfp4/model.safetensors",
+)
+
+
+def test_modular_repo_download_plan_reads_only_the_component_folders(monkeypatch):
+ fam = detect_family(DISTILLED)
+ assert _explicit_pipeline_components(fam) == FLUX3_COMPONENTS
+ info = SimpleNamespace(siblings = [SimpleNamespace(rfilename = f) for f in _REPO_FILES], sha = "x")
+ selection = _pipeline_components_from_index(
+ DISTILLED, info, None, explicit_components = _explicit_pipeline_components(fam)
+ )
+ assert selection == (frozenset(FLUX3_COMPONENTS), frozenset())
+ picked = {
+ f
+ for f in _REPO_FILES
+ if _pipeline_file_downloaded(f) and _pipeline_selected_file(f, selection)
+ }
+ assert "modular_model_index.json" in picked
+ assert not picked & {
+ "model.safetensors",
+ "ae.safetensors",
+ "config.json",
+ "manifest.json",
+ "README.md",
+ }
+ assert not any(f.startswith("variants/") for f in picked)
+ assert {f.split("/", 1)[0] for f in picked if "/" in f} == set(FLUX3_COMPONENTS)
+
+
+def test_a_conventional_repo_without_any_index_still_refuses():
+ info = SimpleNamespace(siblings = [SimpleNamespace(rfilename = "transformer/config.json")], sha = "x")
+ failures = []
+ assert (
+ _pipeline_components_from_index(
+ "a/b", info, None, explicit_components = None, failures_out = failures
+ )
+ is None
+ )
+ assert failures
+ # Without an assembler naming its folders, a modular index alone is not enough either.
+ info = SimpleNamespace(
+ siblings = [SimpleNamespace(rfilename = "modular_model_index.json")], sha = "x"
+ )
+ assert _pipeline_components_from_index("a/b", info, None, explicit_components = None) is None
+
+
+# ── the classic pipeline face ────────────────────────────────────────────────
+def test_blocks_class_from_index_or_flow_map():
+ assert flux3_blocks_class({"_blocks_class_name": FLUX3_BASE_BLOCKS}) == FLUX3_BASE_BLOCKS
+ assert (
+ flux3_blocks_class({"_blocks_class_name": FLUX3_DISTILLED_BLOCKS}) == FLUX3_DISTILLED_BLOCKS
+ )
+ flow_map = SimpleNamespace(config = SimpleNamespace(flow_map = True))
+ cfg = SimpleNamespace(config = SimpleNamespace(flow_map = False))
+ assert flux3_blocks_class({}, flow_map) == FLUX3_DISTILLED_BLOCKS
+ assert flux3_blocks_class({}, cfg) == FLUX3_BASE_BLOCKS
+
+
+class _FakeScheduler:
+ def step(
+ self,
+ noise_pred,
+ t,
+ latents,
+ return_dict = False,
+ ):
+ return (latents + 1,)
+
+
+class _FakeModular:
+ """Records each call and drives scheduler.step once per denoise step, like the FLUX.3 loop."""
+
+ def __init__(self):
+ self.scheduler = _FakeScheduler()
+ self.transformer = None
+ self.calls = []
+
+ def __call__(
+ self,
+ output = None,
+ **kwargs,
+ ):
+ self.calls.append(kwargs)
+ latents = 0
+ for i in range(kwargs["num_inference_steps"]):
+ latents = self.scheduler.step(None, 1000 - i, latents)[0]
+ return [f"img:{kwargs['prompt']}"] * kwargs["num_images_per_prompt"]
+
+
+class _Face(_Flux3KleinPipelineMixin):
+ def __init__(self, distilled = True):
+ self.config = SimpleNamespace(
+ blocks_class_name = FLUX3_DISTILLED_BLOCKS if distilled else FLUX3_BASE_BLOCKS
+ )
+ self._interrupt = False
+ self.mp = _FakeModular()
+ self.guidance = []
+
+ def modular_pipeline(self):
+ return self.mp
+
+ def _set_guidance(self, mp, guidance_scale):
+ self.guidance.append(guidance_scale)
+
+ def progress_bar(self, total = None):
+ return SimpleNamespace(close = lambda: None)
+
+
+def test_one_prompt_many_images_is_one_call():
+ face = _Face()
+ out = face(prompt = "a", num_images_per_prompt = 3, num_inference_steps = 2, negative_prompt = "x")
+ assert out.images == ["img:a"] * 3
+ assert len(face.mp.calls) == 1
+ # The distilled blocks take no negative prompt.
+ assert "negative_prompt" not in face.mp.calls[0]
+
+
+def test_prompt_and_generator_lists_split_into_single_prompt_calls():
+ face = _Face(distilled = False)
+ out = face(
+ prompt = ["a", "b"], generator = ["g1", "g2"], num_inference_steps = 1, negative_prompt = "n"
+ )
+ assert out.images == ["img:a", "img:b"]
+ assert [c["generator"] for c in face.mp.calls] == ["g1", "g2"]
+ assert all(
+ c["num_images_per_prompt"] == 1 and c["negative_prompt"] == "n" for c in face.mp.calls
+ )
+ out = face(prompt = "same", generator = ["g1", "g2", "g3"], num_inference_steps = 1)
+ assert out.images == ["img:same"] * 3
+ with pytest.raises(ValueError):
+ face(prompt = ["a", "b"], generator = ["g1"], num_inference_steps = 1)
+
+
+def test_step_callback_and_interrupt():
+ face = _Face()
+ seen = []
+
+ def _cb(pipe, i, t, kwargs):
+ seen.append((i, kwargs["latents"]))
+ return kwargs
+
+ face(prompt = "a", num_inference_steps = 3, callback_on_step_end = _cb, guidance_scale = 2.0)
+ assert seen == [(0, 1), (1, 2), (2, 3)]
+ assert face.guidance == [2.0]
+ # The wrapper is gone after the call: the scheduler's own step is back.
+ assert "step" not in face.mp.scheduler.__dict__
+
+ def _cancel(pipe, i, t, kwargs):
+ pipe._interrupt = True
+ return kwargs
+
+ out = face(prompt = "a", num_inference_steps = 5, callback_on_step_end = _cancel)
+ assert out.images == []
+ assert "step" not in face.mp.scheduler.__dict__
+
+
+def test_a_prompt_must_be_text():
+ with pytest.raises(ValueError):
+ _Face()(prompt = None, num_inference_steps = 1)
+
+
+def test_the_memory_plan_prices_component_folders_only(tmp_path):
+ # The FLUX.3 repo also carries variants/fp8r and variants/nvfp4 transformer packages (6.3 + 5.3 GB) that no
+ # from_pretrained reads; pricing them planned 31.7 GB for a 19.8 GB pipeline.
+ torch = pytest.importorskip("torch")
+ from safetensors.torch import save_file
+
+ from core.inference.diffusion import DiffusionBackend
+
+ for rel in ("transformer", "variants/fp8r", "variants/nvfp4"):
+ (tmp_path / rel).mkdir(parents = True)
+ save_file(
+ {"w": torch.zeros(100, dtype = torch.float32)},
+ str(tmp_path / "transformer" / "diffusion_pytorch_model.safetensors"),
+ )
+ save_file(
+ {"w": torch.zeros(100, dtype = torch.bfloat16)},
+ str(tmp_path / "variants" / "fp8r" / "model.safetensors"),
+ )
+ save_file(
+ {"w": torch.zeros(100, dtype = torch.bfloat16)},
+ str(tmp_path / "variants" / "nvfp4" / "model.safetensors"),
+ )
+ save_file({"w": torch.zeros(100, dtype = torch.bfloat16)}, str(tmp_path / "model.safetensors"))
+ sizes = DiffusionBackend._local_dir_weight_sizes(
+ tmp_path, exclude_transformer = False, load_dtype = torch.bfloat16
+ )
+ assert sizes == {"transformer/diffusion_pytorch_model.safetensors": 200}
+
+
+def test_references_are_resized_to_one_megapixel_like_comfyui():
+ from PIL import Image
+
+ from core.inference.diffusion_flux3 import resize_reference
+
+ # ComfyUI ReferenceMultiLatent ["resize", 1]: round(side * sqrt(2**20 / (w * h))), up or down.
+ assert resize_reference(Image.new("RGB", (4000, 3000))).size == (1182, 887)
+ assert resize_reference(Image.new("RGB", (512, 512))).size == (1024, 1024)
+ same = Image.new("RGB", (1024, 1024))
+ assert resize_reference(same) is same
+
+
+def test_reference_noise_is_the_bfl_layout():
+ torch = pytest.importorskip("torch")
+ from core.inference.diffusion_flux3 import reference_noise
+
+ noise = reference_noise(7, 64, 96)
+ assert noise.shape == (1, 128, 4, 6) and noise.dtype == torch.bfloat16
+ tokens = torch.randn((4 * 6, 128), generator = torch.Generator().manual_seed(7)).to(
+ torch.bfloat16
+ )
+ # Token (row r, col c) is channel vector noise[0, :, r, c].
+ assert torch.equal(noise[0, :, 1, 2], tokens[1 * 6 + 2])
+
+
+def test_a_seeded_sized_call_gets_reference_noise_and_resized_references():
+ torch = pytest.importorskip("torch")
+ from PIL import Image
+
+ face = _Face()
+ gen = torch.Generator().manual_seed(5)
+ face(
+ prompt = "a",
+ height = 64,
+ width = 32,
+ generator = gen,
+ num_inference_steps = 1,
+ image = [Image.new("RGB", (2048, 2048)), Image.new("RGB", (256, 128))],
+ )
+ call = face.mp.calls[-1]
+ assert call["latents"].shape == (1, 128, 4, 2)
+ assert [im.size for im in call["image"]] == [(1024, 1024), (1448, 724)]
+ # No size (the blocks pick it) or several images per generator: diffusers draws the noise.
+ face(prompt = "a", generator = gen, num_inference_steps = 1)
+ assert "latents" not in face.mp.calls[-1]
+ face(
+ prompt = "a",
+ height = 64,
+ width = 32,
+ generator = gen,
+ num_images_per_prompt = 2,
+ num_inference_steps = 1,
+ )
+ assert "latents" not in face.mp.calls[-1]
+
+
+# ── quantisation keep-list, memory rows, single file / GGUF checks ───────────
+_KEEP = ("modulation", "timestep_embed", "norm_out", "txt_mode_blocks", "context_embedder")
+
+
[email protected]("scheme", ["int8", "fp8", "mxfp8", "nvfp4"])
[email protected]("family", [FLUX3_KLEIN_FAMILY_NAME, FLUX3_KLEIN_BASE_FAMILY_NAME])
+def test_keep_list_applies_to_every_scheme(scheme, family):
+ from core.inference.diffusion_transformer_quant import exclude_tokens_for_scheme
+ tokens = exclude_tokens_for_scheme(scheme, family)
+ assert set(_KEEP) <= set(tokens)
+
+
+def test_other_families_scheme_exclusions_unchanged():
+ from core.inference.diffusion_transformer_quant import exclude_tokens_for_scheme
+ for family in ("flux.1", "flux.2-klein", "qwen-image", "z-image", None):
+ for scheme in ("fp8", "mxfp8", "nvfp4"):
+ assert exclude_tokens_for_scheme(scheme, family) == ()
+
+
+def test_keep_list_hits_the_measured_layers_only():
+ from core.inference.diffusion_transformer_quant import exclude_tokens_for_scheme
+
+ tokens = exclude_tokens_for_scheme("fp8", FLUX3_KLEIN_FAMILY_NAME)
+ kept = [
+ "early_stream_modulations.image.linear",
+ "single_stream_modulations.txt.linear",
+ "timestep_embedder.linear_1",
+ "target_timestep_embedder.linear_2",
+ "norm_out.linear",
+ "txt_mode_blocks.3.attn.to_q",
+ "context_embedder",
+ ]
+ quantised = [
+ "mode_blocks.image.0.attn.to_q",
+ "mode_blocks.image_cond.4.ff.linear_in",
+ "single_transformer_blocks.27.attn.to_out.0",
+ "single_transformer_blocks.0.ff.linear_out",
+ ]
+ assert all(any(t in name for t in tokens) for name in kept)
+ assert not any(any(t in name for t in tokens) for name in quantised)
+
+
+def test_measured_memory_rows():
+ from core.inference import diffusion_memory as mem
+
+ assert mem._MEASURED_IMAGE_ACTIVATION_MIB["flux.3-klein"] == (
+ (301, 901, 2_437, 2_437, 3_359),
+ (301, 901, 2_437, 2_437, 3_359),
+ )
+ assert mem._MEASURED_DENSE_EAGER_PEAK_MIB["flux.3-klein"] == (2437, 10600)
+ # The base runs CFG and is unmeasured: flat estimate.
+ assert "flux.3-klein-base" not in mem._MEASURED_IMAGE_ACTIVATION_MIB
+
+
+def test_variant_mismatch_and_bfl_quant_packages_are_refused():
+ from core.inference.diffusion_families import flux3_variant_mismatch_reason as why
+
+ distilled = [
+ "emb_in.image.weight",
+ "ref_time_in.in_layer.weight",
+ "single_blocks.0.q_proj.weight",
+ ]
+ base = ["emb_in.image.weight", "time_in.in_layer.weight", "single_blocks.0.q_proj.weight"]
+ assert why("flux.3-klein", "d.gguf", distilled) is None
+ assert why("flux.3-klein-base", "b.gguf", base) is None
+ assert "flux.3-klein-base" in why("flux.3-klein", "b.gguf", base)
+ assert "flux.3-klein" in why("flux.3-klein-base", "d.gguf", distilled)
+ # diffusers key names and a ComfyUI prefix are read the same way.
+ assert (
+ why("flux.3-klein", "x.safetensors", ["target_timestep_embedder.linear_1.weight"]) is None
+ )
+ assert (
+ why("flux.3-klein", "x.safetensors", ["model.diffusion_model.ref_time_in.in_layer.weight"])
+ is None
+ )
+ bfl_nvfp4 = distilled + [
+ "single_blocks.0.q_proj.weight_scale",
+ "single_blocks.0.q_proj.weight_scale_2",
+ ]
+ assert "variants/fp8r or variants/nvfp4" in why("flux.3-klein", "model.safetensors", bfl_nvfp4)
+ # BFL's ComfyUI files (flux-3-image-klein-comfy) declare their quantization; the ComfyUI loader reads them.
+ assert (
+ why(
+ "flux.3-klein", "flux3_image_klein_sd_nvfp4.safetensors", bfl_nvfp4, comfy_declared = True
+ )
+ is None
+ )
+ # ... but the variant still has to match.
+ assert "flux.3-klein" in why(
+ "flux.3-klein-base", "sd_int8.safetensors", bfl_nvfp4, comfy_declared = True
+ )
+ # Unreadable file or another family: fail open.
+ assert why("flux.3-klein", "x.gguf", None) is None
+ assert why("flux.2-klein", "x.gguf", base) is None
+
+
+def test_gguf_denoiser_reports_its_compute_dtype():
+ torch = pytest.importorskip("torch")
+ from core.inference.diffusion_flux3 import _pin_compute_dtype
+
+ class _Packed(torch.nn.Module):
+ def __init__(self):
+ super().__init__()
+ self.w = torch.nn.Parameter(torch.zeros(4, dtype = torch.uint8), requires_grad = False)
+
+ @property
+ def dtype(
+ self,
+ ): # diffusers' get_parameter_dtype: first float param, else first float buffer, else last
+ for p in self.parameters():
+ if p.is_floating_point():
+ return p.dtype
+ for b in self.buffers():
+ if b.is_floating_point():
+ return b.dtype
+ return torch.uint8
+
+ m = _Packed()
+ assert m.dtype == torch.uint8
+ _pin_compute_dtype(m, torch.bfloat16)
+ assert m.dtype == torch.bfloat16
+ assert "_unsloth_compute_dtype" not in m.state_dict()
+
+
+def test_nvfp4_is_denied_for_flux3_only():
+ from core.inference import diffusion_transformer_quant as tq
+
+ assert "nvfp4" in tq._FAMILY_SCHEME_DENY[FLUX3_KLEIN_FAMILY_NAME]
+ assert "nvfp4" in tq._FAMILY_SCHEME_DENY[FLUX3_KLEIN_BASE_FAMILY_NAME]
+ assert "flux.2-klein" not in tq._FAMILY_SCHEME_DENY
+
+
+def _mx_linear(torch):
+ """A Linear whose weight class is named like torchao's MXTensor and whose forward asserts a contiguous input,
+ the way ``to_mx`` does."""
+
+ class MXTensor(torch.Tensor):
+ pass
+
+ class _Lin(torch.nn.Linear):
+ def forward(self, x):
+ assert x.is_contiguous(), "unsupported"
+ return super().forward(x)
+
+ lin = _Lin(8, 8, bias = False)
+ lin.weight = torch.nn.Parameter(lin.weight.detach().as_subclass(MXTensor), requires_grad = False)
+ return lin
+
+
+def test_contiguous_guard_feeds_mx_linears_a_contiguous_activation():
+ torch = pytest.importorskip("torch")
+ from core.inference.diffusion_transformer_quant import (
+ apply_zero_row_guard,
+ guard_contiguous_activations,
+ )
+
+ lin = _mx_linear(torch)
+ broadcast = torch.randn(1, 1, 8).expand(2, 4, 8)
+ with pytest.raises(AssertionError):
+ lin(broadcast)
+ model = torch.nn.Sequential(lin, torch.nn.Linear(8, 8))
+ # Installed by the shared post-quantisation hook every path calls; only the MX Linear is hooked, once.
+ apply_zero_row_guard(model, "mxfp8", "flux.3-klein")
+ assert guard_contiguous_activations(model) == 0
+ out = lin(broadcast)
+ assert torch.allclose(out, lin(broadcast.contiguous()))
+ assert not getattr(model[1], "_unsloth_contig_hook", False)
+
+
+def test_python_310_gets_a_reason_it_can_act_on(monkeypatch):
+ # Diffusers main (and so the pinned FLUX.3 build) needs Python 3.11; the installer skips it below that, so the
+ # refusal must not send a 3.10 user to reinstall or fetch an archive that cannot install.
+ monkeypatch.setattr(families.sys, "version_info", (3, 10, 14, "final", 0))
+ message = families._too_old_message("Flux3DistilledModularPipeline", "flux.3-klein", "0.41.0")
+ assert "Python 3.11" in message and "3.10" in message
+ assert "archive" not in message
+ monkeypatch.setattr(families.sys, "version_info", (3, 12, 1, "final", 0))
+ message = families._too_old_message("Flux3DistilledModularPipeline", "flux.3-klein", "0.41.0")
+ assert "Python 3.11" not in message and "has not been released yet" in message
+
+
+# ── hosted artifacts ─────────────────────────────────────────────────────────
+def _family(name):
+ return next(f for f in families._FAMILIES if f.name == name)
+
+
+def test_prequant_repos_point_each_variant_at_its_own_fp8_repo():
+ distilled = _family(FLUX3_KLEIN_FAMILY_NAME)
+ base = _family(FLUX3_KLEIN_BASE_FAMILY_NAME)
+ for scheme in ("int8", "fp8"):
+ assert (
+ families.family_prequant_repo(distilled, scheme, DISTILLED)
+ == "unsloth/flux-3-image-klein-FP8"
+ )
+ assert (
+ families.family_prequant_repo(base, scheme, BASE)
+ == "unsloth/flux-3-image-klein-base-FP8"
+ )
+ # nvfp4 is denied for both families
+ assert families.family_prequant_repo(distilled, "nvfp4", DISTILLED) is None
+ assert families.family_prequant_repo(base, "nvfp4", BASE) is None
+
+
[email protected]("variant", ["distilled", "base"])
[email protected]("scheme, stem", [("int8", "INT8"), ("fp8", "FP8")])
+def test_prequant_filenames_resolve_to_the_built_safetensors(scheme, stem, variant):
+ 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]
+ 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)
+ wanted = f"{model}-{stem}.safetensors"
+ # first after any ComfyUI twin (int8 tries a "-ComfyUI" name first, which neither repo hosts)
+ assert [n for n in names if "-ComfyUI" not in n][0] == wanted
+ # The safetensors artifact is tried before the legacy pickle name.
+ assert names.index(wanted) < names.index(f"{model}-{stem}.pt")
+
+
+def _comfy_int8_file(path):
+ """A minimal ComfyUI int8_convrot file: one quantised Linear, no Studio metadata (BFL's own layout)."""
+ import torch
+ from safetensors.torch import save_file
+
+ conf = json.dumps({"format": "int8_tensorwise", "convrot": True, "convrot_groupsize": 16})
+ save_file(
+ {
+ "blocks.0.qkv.weight": torch.zeros(48, 16, dtype = torch.int8),
+ "blocks.0.qkv.weight_scale": torch.ones(48, 1),
+ "blocks.0.qkv.comfy_quant": torch.tensor(list(conf.encode()), dtype = torch.uint8),
+ },
+ str(path),
+ )
+ return str(path)
+
+
+def test_the_base_int8_slot_holds_a_comfy_file_and_is_read_through_the_comfy_loader(
+ tmp_path, monkeypatch
+):
+ """The base repo's INT8 file is BFL's ComfyUI int8_convrot denoiser, not a Studio checkpoint: the header
+ probe must not refuse it for lacking Studio metadata, and the loader must hand it to the ComfyUI quant
+ loader with the base family (which picks the layers and splits the fused q/k/v)."""
+ import torch
+
+ from core.inference import diffusion_comfy_quant as cq
+ from core.inference import diffusion_prequant as pq
+
+ hub = tmp_path / "hub"
+ snap = hub / "models--unsloth--flux-3-image-klein-base-FP8" / "snapshots" / "abc"
+ snap.mkdir(parents = True)
+ (hub / "models--unsloth--flux-3-image-klein-base-FP8" / "refs").mkdir()
+ (hub / "models--unsloth--flux-3-image-klein-base-FP8" / "refs" / "main").write_text("abc")
+ path = _comfy_int8_file(snap / "flux-3-image-klein-base-INT8.safetensors")
+ assert cq.scan_comfy_quant(path) is not None
+
+ source = pq.resolve_prequant_source(
+ _family(FLUX3_KLEIN_BASE_FAMILY_NAME), "int8", base_repo = BASE
+ )
+ assert (
+ pq.hosted_prequant_refusal(
+ source, "int8", base = BASE, cache_dir = str(hub), local_files_only = True
+ )
+ is None
+ )
+
+ seen = {}
+
+ def _comfy_load(cls, file, **kw):
+ seen.update(kw, path = file)
+ return torch.nn.Linear(16, 16)
+
+ monkeypatch.setattr(cq, "load_comfy_prequant", _comfy_load)
+ monkeypatch.setattr(pq, "hosted_prequant_refusal", lambda *a, **k: None)
+ model = pq.load_prequantized_transformer(
+ object,
+ BASE,
+ source,
+ device = "cpu",
+ dtype = torch.bfloat16,
+ scheme = "int8",
+ cache_dir = str(hub),
+ local_files_only = True,
+ family = FLUX3_KLEIN_BASE_FAMILY_NAME,
+ )
+ assert model is not None, pq.last_prequant_failure()
+ assert seen["path"] == path
+ assert seen["family"] == FLUX3_KLEIN_BASE_FAMILY_NAME and seen["scheme"] == "int8"
+
+
+def test_operator_mirror_serves_the_hosted_name(tmp_path, monkeypatch):
+ from core.inference import diffusion_prequant as dp
+
+ folder = tmp_path / "unsloth" / "flux-3-image-klein-FP8"
+ folder.mkdir(parents = True)
+ (folder / "flux-3-image-klein-INT8.safetensors").write_bytes(b"x")
+ monkeypatch.setenv(dp.PREQUANT_MIRROR_ENV, str(tmp_path))
+ found = dp.prequant_mirror_path(
+ "unsloth/flux-3-image-klein-FP8",
+ "flux-3-image-klein-INT8.safetensors",
+ readable = lambda n: True,
+ )
+ assert found == str(folder / "flux-3-image-klein-INT8.safetensors")
+
+
+def test_quantized_gguf_pick_assembles_through_the_modular_loader(monkeypatch):
+ # A GGUF pick with a transformer quant builds through _assemble_pipe; FLUX.3 has no model_index.json, so
+ # from_pretrained would fail there and the load would fall back to the GGUF.
+ from core.inference import diffusion as d
+
+ calls = {}
+
+ class _Pipe:
+ def to(self, device):
+ calls["device"] = device
+ return self
+
+ def fake_load(repo, dtype, **kw):
+ calls.update(repo = repo, **kw)
+ return _Pipe()
+
+ class _NoFromPretrained:
+ @classmethod
+ def from_pretrained(cls, *a, **k):
+ raise AssertionError("FLUX.3 must not assemble via from_pretrained")
+
+ monkeypatch.setattr(d, "load_flux3_pipeline", fake_load)
+ sentinel = object()
+ pipe = d.DiffusionBackend._assemble_pipe(
+ _NoFromPretrained,
+ DISTILLED,
+ sentinel,
+ "bf16",
+ None,
+ "cuda",
+ base_local_dir = "/staged/klein",
+ fam = _family(FLUX3_KLEIN_FAMILY_NAME),
+ fetch_base = DISTILLED,
+ )
+ assert isinstance(pipe, _Pipe)
+ assert calls["repo"] == "/staged/klein" and calls["transformer"] is sentinel
+ assert calls["device"] == "cuda"
+
+
+# ── generation splitting and local file checks ───────────────────────────────
+def test_split_calls_pair_each_prompt_with_its_own_negative():
+ face = _Face(distilled = False)
+ face(
+ prompt = ["a", "b"],
+ generator = ["g1", "g2"],
+ num_inference_steps = 1,
+ negative_prompt = ["na", "nb"],
+ )
+ assert [c["negative_prompt"] for c in face.mp.calls] == ["na", "nb"]
+ face = _Face(distilled = False)
+ face(prompt = "same", generator = ["g1", "g2"], num_inference_steps = 1, negative_prompt = ["n"])
+ assert [c["negative_prompt"] for c in face.mp.calls] == ["n", "n"]
+ with pytest.raises(ValueError):
+ _Face(distilled = False)(
+ prompt = ["a", "b", "c"],
+ generator = ["g1", "g2", "g3"],
+ num_inference_steps = 1,
+ negative_prompt = ["x", "y"],
+ )
+
+
+def test_every_flux3_image_is_its_own_generation_chunk():
+ # One chunk per image, so each image gets its own encode / denoise phase and text-encoder release.
+ from core.inference.diffusion import _generation_chunks
+
+ jobs = [("a", 1), ("a", 2), ("b", 3)]
+ for name in (FLUX3_KLEIN_FAMILY_NAME, FLUX3_KLEIN_BASE_FAMILY_NAME):
+ assert _generation_chunks(_family(name), jobs, 1) == [[j] for j in jobs]
+ # Other families keep one forward for the whole list.
+ other = next(f for f in families._FAMILIES if f.name == "flux.2-klein")
+ assert _generation_chunks(other, jobs, 1) == [jobs]
+
+
+def _modular_base(tmp_path):
+ root = tmp_path / "klein"
+ index = {
+ "_class_name": "Flux3DistilledModularPipeline",
+ "_blocks_class_name": FLUX3_DISTILLED_BLOCKS,
+ }
+ for component, lib, cls in (
+ ("text_encoder", "transformers", "Qwen3VLForConditionalGeneration"),
+ ("transformer", "diffusers", "Flux3Transformer2DModel"),
+ ("vae", "diffusers", "AutoencoderKLFlux2"),
+ ):
+ folder = root / component
+ folder.mkdir(parents = True)
+ (folder / "config.json").write_text("{}")
+ (folder / "model.safetensors").write_bytes(b"\0" * 16)
+ index[component] = [lib, cls, {"subfolder": component, "type_hint": [lib, cls]}]
+ # The processor the loader reads from text_encoder/, as in the official repos.
+ for asset in ("tokenizer.json", "tokenizer_config.json", "preprocessor_config.json"):
+ (root / "text_encoder" / asset).write_text("{}")
+ (root / "modular_model_index.json").write_text(json.dumps(index))
+ return root
+
+
+def _flux3_installed(monkeypatch):
+ # The CPU suite runs on a released diffusers without the FLUX.3 blocks; the checks below come after that gate.
+ from core.inference import diffusion as d
+ monkeypatch.setattr(d, "assert_pipeline_class_available", lambda *a, **k: None)
+
+
+def test_a_local_modular_base_is_accepted_for_a_gguf_denoiser(tmp_path, monkeypatch):
+ from core.inference.diffusion import DiffusionBackend
+
+ _flux3_installed(monkeypatch)
+ base = _modular_base(tmp_path)
+ ggufs = tmp_path / "ggufs"
+ ggufs.mkdir()
+ (ggufs / "flux-3-image-klein-Q4_K_M.gguf").write_bytes(b"GGUF")
+ fam = DiffusionBackend().validate_load_request(
+ str(ggufs),
+ gguf_filename = "flux-3-image-klein-Q4_K_M.gguf",
+ family_override = FLUX3_KLEIN_FAMILY_NAME,
+ model_kind = "gguf",
+ base_repo = str(base),
+ )
+ assert fam.name == FLUX3_KLEIN_FAMILY_NAME
+
+
+def test_supplied_encoder_or_vae_files_are_refused_for_flux3(tmp_path, monkeypatch):
+ from core.inference.diffusion import DiffusionBackend
+
+ _flux3_installed(monkeypatch)
+ ggufs = tmp_path / "ggufs"
+ ggufs.mkdir()
+ (ggufs / "flux-3-image-klein-Q4_K_M.gguf").write_bytes(b"GGUF")
+ (ggufs / "vae.safetensors").write_bytes(b"\0" * 16)
+ for extra in ({"vae_file": "vae.safetensors"}, {"text_encoder_files": ["vae.safetensors"]}):
+ with pytest.raises(ValueError, match = "not supported for 'flux.3-klein'"):
+ DiffusionBackend().validate_load_request(
+ str(ggufs),
+ gguf_filename = "flux-3-image-klein-Q4_K_M.gguf",
+ family_override = FLUX3_KLEIN_FAMILY_NAME,
+ model_kind = "gguf",
+ **extra,
+ )
+
+
+# ── LoRA loader ──────────────────────────────────────────────────────────────
+def test_the_face_carries_the_flux3_lora_loader(monkeypatch):
+ # Studio's LoRA path calls load_lora_weights / set_adapters / unload_lora_weights on the pipe; the pinned
+ # Diffusers build ships them for FLUX.3 as Flux3LoraLoaderMixin (transformer-only). Fake modules, so the
+ # test does not depend on which diffusers this environment has.
+ from core.inference import diffusion_flux3 as f3
+
+ class DiffusionPipeline:
+ pass
+
+ class Flux3LoraLoaderMixin:
+ _lora_loadable_modules = ["transformer"]
+
+ def load_lora_weights(self, *a, **k):
+ return "loaded"
+
+ def set_adapters(self, *a, **k):
+ return "set"
+
+ def unload_lora_weights(self):
+ return "unloaded"
+
+ fake = types.ModuleType("diffusers")
+ fake.DiffusionPipeline = DiffusionPipeline
+ loaders = types.ModuleType("diffusers.loaders")
+ loaders.Flux3LoraLoaderMixin = Flux3LoraLoaderMixin
+ fake.loaders = loaders
+ monkeypatch.setitem(sys.modules, "diffusers", fake)
+ monkeypatch.setitem(sys.modules, "diffusers.loaders", loaders)
+ monkeypatch.setattr(f3, "_PIPELINE_CLASS", None)
+ cls = f3.flux3_pipeline_class()
+ assert issubclass(cls, Flux3LoraLoaderMixin) and issubclass(cls, DiffusionPipeline)
+ for name in ("load_lora_weights", "set_adapters", "unload_lora_weights"):
+ assert callable(getattr(cls, name, None)), name
+ # The face's own __call__ still wins over anything a loader mixin defines.
+ assert cls.__call__ is f3._Flux3KleinPipelineMixin.__call__
+ # A build without the loader still assembles (no LoRA methods, as before).
+ del loaders.Flux3LoraLoaderMixin
+ monkeypatch.setattr(f3, "_PIPELINE_CLASS", None)
+ assert not hasattr(f3.flux3_pipeline_class(), "load_lora_weights")
+
+
+# ── local validation and variant refusal ─────────────────────────────────────
+def test_local_flux3_base_needs_the_modular_index(tmp_path, monkeypatch):
+ # load_flux3_pipeline reads only modular_model_index.json, so a base holding just model_index.json must be refused
+ # before the resident model is evicted, not after.
+ from core.inference.diffusion import DiffusionBackend
+
+ _flux3_installed(monkeypatch)
+ base = _modular_base(tmp_path)
+ (base / "modular_model_index.json").rename(base / "model_index.json")
+ ggufs = tmp_path / "ggufs"
+ ggufs.mkdir()
+ (ggufs / "flux-3-image-klein-Q4_K_M.gguf").write_bytes(b"GGUF")
+ with pytest.raises(ValueError, match = "no valid modular_model_index.json"):
+ DiffusionBackend().validate_load_request(
+ str(ggufs),
+ gguf_filename = "flux-3-image-klein-Q4_K_M.gguf",
+ family_override = FLUX3_KLEIN_FAMILY_NAME,
+ model_kind = "gguf",
+ base_repo = str(base),
+ )
+
+
+def test_local_validation_checks_the_folders_the_flux3_loader_reads(tmp_path, monkeypatch):
+ # A spec naming another source (repo / folder) is ignored by load_flux3_pipeline, which reads
+ # <root>/text_encoder, /transformer and /vae; validation must check those folders, not the named source.
+ from core.inference.diffusion import DiffusionBackend
+
+ _flux3_installed(monkeypatch)
+ base = _modular_base(tmp_path)
+ elsewhere = tmp_path / "elsewhere" / "text_encoder"
+ elsewhere.mkdir(parents = True)
+ (elsewhere / "config.json").write_text("{}")
+ (elsewhere / "model.safetensors").write_bytes(b"\0" * 16)
+ index = json.loads((base / "modular_model_index.json").read_text())
+ index["text_encoder"][2].update(pretrained_model_name_or_path = str(tmp_path / "elsewhere"))
+ (base / "modular_model_index.json").write_text(json.dumps(index))
+ for f in (base / "text_encoder").iterdir():
+ f.unlink()
+ (base / "text_encoder").rmdir()
+ with pytest.raises(FileNotFoundError, match = "no complete valid"):
+ DiffusionBackend().validate_load_request(
+ str(base), family_override = FLUX3_KLEIN_FAMILY_NAME, model_kind = "pipeline"
+ )
+ ggufs = tmp_path / "ggufs"
+ ggufs.mkdir()
+ (ggufs / "flux-3-image-klein-Q4_K_M.gguf").write_bytes(b"GGUF")
+ with pytest.raises(ValueError, match = "not a diffusers pipeline directory"):
+ DiffusionBackend().validate_load_request(
+ str(ggufs),
+ gguf_filename = "flux-3-image-klein-Q4_K_M.gguf",
+ family_override = FLUX3_KLEIN_FAMILY_NAME,
+ model_kind = "gguf",
+ base_repo = str(base),
+ )
+
+
+def test_the_variant_is_refused_before_the_resident_model_is_unloaded(tmp_path, monkeypatch):
+ # The route preflight (before it takes the GPU) reads the header, so a base checkpoint under the distilled
+ # family is refused while the current pipeline is still loaded.
+ from safetensors.torch import save_file
+ import torch
+ from core.inference.diffusion import DiffusionBackend
+
+ _flux3_installed(monkeypatch)
+ base = _modular_base(tmp_path)
+ picks = tmp_path / "picks"
+ picks.mkdir()
+ save_file({"time_in.in_layer.weight": torch.zeros(2, 2)}, str(picks / "klein-base.safetensors"))
+ save_file({"ref_time_in.in_layer.weight": torch.zeros(2, 2)}, str(picks / "klein.safetensors"))
+ be = DiffusionBackend()
+ fam = _family(FLUX3_KLEIN_FAMILY_NAME)
+ with pytest.raises(ValueError, match = "flux.3-klein-base"):
+ be.preflight_base_access(
+ str(picks),
+ fam,
+ gguf_filename = "klein-base.safetensors",
+ model_kind = "single_file",
+ base_repo = str(base),
+ allow_network = False,
+ )
+ be.preflight_base_access(
+ str(picks),
+ fam,
+ gguf_filename = "klein.safetensors",
+ model_kind = "single_file",
+ base_repo = str(base),
+ allow_network = False,
+ )
+
+
+def test_gguf_header_tensor_names(tmp_path):
+ gguf = pytest.importorskip("gguf")
+ import numpy as np
+ from core.inference.diffusion_families import gguf_tensor_names_from_header
+
+ path = tmp_path / "t.gguf"
+ writer = gguf.GGUFWriter(str(path), "flux")
+ writer.add_tensor("ref_time_in.in_layer.weight", np.zeros((4, 4), dtype = np.float32))
+ writer.add_tensor("emb_in.image.weight", np.zeros((4, 4), dtype = np.float32))
+ writer.write_header_to_file()
+ writer.write_kv_data_to_file()
+ writer.write_tensors_to_file()
+ writer.close()
+ assert gguf_tensor_names_from_header(path.read_bytes()[:4096]) == [
+ "ref_time_in.in_layer.weight",
+ "emb_in.image.weight",
+ ]
+ assert gguf_tensor_names_from_header(b"") is None
+
+
+# ── staged dirs and family routing ───────────────────────────────────────────
+def test_every_flux3_assembly_reads_the_staged_dir_and_names_the_family():
+ # Each FLUX.3 assembly in the loader takes the staged companion dir first (a plan that found the companions under
+ # another cache root must not re-resolve them) and hands the family to the variant backstop.
+ import ast
+ import inspect
+ from core.inference import diffusion as d
+
+ tree = ast.parse(inspect.getsource(d))
+ calls = [
+ n
+ for n in ast.walk(tree)
+ if isinstance(n, ast.Call) and getattr(n.func, "id", None) == "load_flux3_pipeline"
+ ]
+ assert len(calls) == 3
+ for call in calls:
+ assert "base_local_dir" in ast.unparse(call.args[0]), ast.unparse(call.args[0])
+ assert "family_name" in {k.arg for k in call.keywords}
+
+
+ "family, index_blocks, refused",
+ [
+ (FLUX3_KLEIN_FAMILY_NAME, FLUX3_DISTILLED_BLOCKS, False),
+ (FLUX3_KLEIN_FAMILY_NAME, FLUX3_BASE_BLOCKS, True),
+ (FLUX3_KLEIN_BASE_FAMILY_NAME, FLUX3_BASE_BLOCKS, False),
+ (FLUX3_KLEIN_BASE_FAMILY_NAME, FLUX3_DISTILLED_BLOCKS, True),
+ ],
+)
+def test_a_pipeline_of_the_other_variant_is_refused_before_eviction(
+ tmp_path, monkeypatch, family, index_blocks, refused
+):
+ from core.inference.diffusion import DiffusionBackend
+
+ _flux3_installed(monkeypatch)
+ root = _modular_base(tmp_path)
+ index = json.loads((root / "modular_model_index.json").read_text())
+ index["_blocks_class_name"] = index_blocks
+ index["_class_name"] = (
+ "Flux3DistilledModularPipeline"
+ if index_blocks == FLUX3_DISTILLED_BLOCKS
+ else "Flux3ModularPipeline"
+ )
+ (root / "modular_model_index.json").write_text(json.dumps(index))
+ run = lambda: DiffusionBackend().preflight_base_access( # noqa: E731
+ str(root), _family(family), model_kind = "pipeline", allow_network = False
+ )
+ if refused:
+ with pytest.raises(ValueError, match = "Load it with family"):
+ run()
+ else:
+ run()
+
+
+def test_the_loader_backstop_refuses_a_block_graph_of_the_other_family():
+ from core.inference.diffusion_flux3 import flux3_family_blocks_mismatch, flux3_index_family
+
+ assert (
+ flux3_family_blocks_mismatch(FLUX3_KLEIN_FAMILY_NAME, FLUX3_DISTILLED_BLOCKS, "r") is None
+ )
+ assert "flux.3-klein-base" in flux3_family_blocks_mismatch(
+ FLUX3_KLEIN_FAMILY_NAME, FLUX3_BASE_BLOCKS, "r"
+ )
+ assert flux3_family_blocks_mismatch(None, FLUX3_BASE_BLOCKS, "r") is None
+ assert (
+ flux3_index_family({"_class_name": "Flux3ModularPipeline"}) == FLUX3_KLEIN_BASE_FAMILY_NAME
+ )
+ assert (
+ flux3_index_family({"_blocks_class_name": FLUX3_DISTILLED_BLOCKS})
+ == FLUX3_KLEIN_FAMILY_NAME
+ )
+ assert flux3_index_family({}) is None
+
+
+def test_canonical_family_names_get_the_flux3_recipe():
+ from core.inference.diffusion import _generation_defaults_for
+
+ assert default_generation_params("flux.3-klein") == (16, 1.0)
+ assert default_generation_params("flux.3-klein-base") == (50, 3.5)
+ # An opaque local pipeline names no variant; the resident recipe falls back to the family.
+ for name, want in (
+ (FLUX3_KLEIN_FAMILY_NAME, (16, 1.0)),
+ (FLUX3_KLEIN_BASE_FAMILY_NAME, (50, 3.5)),
+ ):
+ got = _generation_defaults_for(
+ "/models/my-model", None, "/models/my-model", family = _family(name)
+ )
+ assert (got["steps"], got["guidance"]) == want
+
+
+def test_status_lists_flux3_as_a_modular_image_family(monkeypatch):
+ from core.inference import diffusion_engine_router as router
+ from models.inference import DiffusionStatusResponse
+
+ monkeypatch.setattr(
+ router,
+ "_supported_family_capabilities",
+ lambda: ("flux.2-klein", FLUX3_KLEIN_FAMILY_NAME, FLUX3_KLEIN_BASE_FAMILY_NAME),
+ )
+ out = router.annotate_status({"loaded": False, "repo_id": None})
+ assert out["modular_families"] == [FLUX3_KLEIN_FAMILY_NAME, FLUX3_KLEIN_BASE_FAMILY_NAME]
+ # The response model keeps it (a dropped field reaches the UI as no modular families at all).
+ assert DiffusionStatusResponse(**out).modular_families == out["modular_families"]
+
+
+# ── upstream manifest change (2026-10-16): the official manifests list the optional prompt upsampler ─────────────
+def _official_manifest(variant, with_upsampler):
+ """The official modular_model_index.json before (2026-10-15) and after (2026-10-16) BFL added the prompt
+ upsampler components; same shape, abridged to what the checks read."""
+ repo = DISTILLED if variant == "distilled" else BASE
+ index = {
+ "_blocks_class_name": FLUX3_DISTILLED_BLOCKS
+ if variant == "distilled"
+ else FLUX3_BASE_BLOCKS,
+ "_class_name": "Flux3DistilledModularPipeline"
+ if variant == "distilled"
+ else "Flux3ModularPipeline",
+ "_diffusers_version": "0.41.0.dev0",
+ }
+
+ def entry(lib, cls, source, subfolder):
+ return [
+ lib,
+ cls,
+ {
+ "pretrained_model_name_or_path": source,
+ "revision": None,
+ "subfolder": subfolder,
+ "type_hint": [lib, cls],
+ "variant": None,
+ },
+ ]
+
+ index["text_encoder"] = entry(
+ "transformers", "Qwen3VLForConditionalGeneration", repo, "text_encoder"
+ )
+ index["tokenizer"] = entry("transformers", "Qwen3VLProcessor", repo, "text_encoder")
+ index["transformer"] = entry("diffusers", "Flux3Transformer2DModel", repo, "transformer")
+ index["vae"] = entry("diffusers", "AutoencoderKLFlux2", repo, "vae")
+ if with_upsampler:
+ pup = "black-forest-labs/flux-3-image-klein-pup"
+ index["prompt_upsampler"] = entry(
+ "transformers", "Qwen3_5ForConditionalGeneration", pup, ""
+ )
+ index["prompt_upsampler_processor"] = entry("transformers", "AutoProcessor", pup, "")
+ return index
+
+
+def _official_layout(tmp_path, variant, with_upsampler):
+ """A local copy of the official repo: the three component folders and the manifest, no upsampler (it lives in
+ another repo)."""
+ root = tmp_path / f"{variant}-{with_upsampler}"
+ for component in ("text_encoder", "transformer", "vae"):
+ folder = root / component
+ folder.mkdir(parents = True)
+ (folder / "config.json").write_text("{}")
+ (folder / "model.safetensors").write_bytes(b"\0" * 16)
+ (root / "text_encoder" / "tokenizer.json").write_text("{}")
+ (root / "text_encoder" / "tokenizer_config.json").write_text("{}")
+ (root / "text_encoder" / "preprocessor_config.json").write_text("{}")
+ (root / "modular_model_index.json").write_text(
+ json.dumps(_official_manifest(variant, with_upsampler))
+ )
+ return root
+
+
+_MANIFEST_CASES = [(v, u) for v in ("distilled", "base") for u in (False, True)]
+
+
[email protected]("variant, with_upsampler", _MANIFEST_CASES)
+def test_local_validation_ignores_the_optional_prompt_upsampler(
+ tmp_path, monkeypatch, variant, with_upsampler
+):
+ from core.inference.diffusion import DiffusionBackend
+ from core.inference.diffusion_families import local_pipeline_components_are_complete
+ from core.inference.diffusion_flux3 import FLUX3_COMPONENT_FOLDERS
+
+ _flux3_installed(monkeypatch)
+ family = FLUX3_KLEIN_FAMILY_NAME if variant == "distilled" else FLUX3_KLEIN_BASE_FAMILY_NAME
+ root = _official_layout(tmp_path, variant, with_upsampler)
+ assert local_pipeline_components_are_complete(
+ root, "modular_model_index.json", fixed_component_folders = FLUX3_COMPONENT_FOLDERS
+ )
+ # A full pipeline pick, and the same folder as the companion base of a GGUF.
+ DiffusionBackend().validate_load_request(
+ str(root), family_override = family, model_kind = "pipeline"
+ )
+ ggufs = tmp_path / f"ggufs-{variant}-{with_upsampler}"
+ ggufs.mkdir()
+ (ggufs / "klein.gguf").write_bytes(b"GGUF")
+ DiffusionBackend().validate_load_request(
+ str(ggufs),
+ gguf_filename = "klein.gguf",
+ family_override = family,
+ model_kind = "gguf",
+ base_repo = str(root),
+ )
+ # The variant read off the manifest is unchanged by the extra entries.
+ DiffusionBackend().preflight_base_access(
+ str(root), _family(family), model_kind = "pipeline", allow_network = False
+ )
+ # A component the loader DOES read is still required.
+ for f in (root / "vae").iterdir():
+ f.unlink()
+ assert not local_pipeline_components_are_complete(
+ root, "modular_model_index.json", fixed_component_folders = FLUX3_COMPONENT_FOLDERS
+ )
+
+
[email protected]("variant, with_upsampler", _MANIFEST_CASES)
+def test_locality_does_not_require_the_upsampler_repo(tmp_path, variant, with_upsampler):
+ # The media auto-switch / cached-snapshot check: an official snapshot is ready without the ~19 GB pup repo.
+ from core.inference.media_locality import _pipeline_components_present
+
+ root = _official_layout(tmp_path, variant, with_upsampler)
+ assert _pipeline_components_present(root)
+ for f in (root / "transformer").iterdir():
+ f.unlink()
+ assert not _pipeline_components_present(root)
+
+
[email protected]("with_upsampler", [False, True])
+def test_the_download_plan_never_selects_the_upsampler(with_upsampler):
+ info = SimpleNamespace(
+ siblings = [
+ SimpleNamespace(rfilename = n)
+ for n in (
+ "modular_model_index.json",
+ "text_encoder/config.json",
+ "transformer/config.json",
+ "vae/config.json",
+ )
+ ],
+ sha = "x",
+ )
+ selected, _ignored = _pipeline_components_from_index(
+ DISTILLED,
+ info,
+ None,
+ explicit_components = _explicit_pipeline_components(_family(FLUX3_KLEIN_FAMILY_NAME)),
+ )
+ assert selected == frozenset(FLUX3_COMPONENTS)
+
+
+# ── review round 5 ───────────────────────────────────────────────────────────
[email protected]("missing", ["text_encoder", "vae", "transformer", "tokenizer"])
+def test_every_fixed_folder_is_required_even_when_the_manifest_omits_it(tmp_path, missing):
+ # load_flux3_pipeline opens text_encoder/ (encoder and processor), transformer/ and vae/ whatever the manifest
+ # lists, so a manifest that drops an entry must not let its missing folder through.
+ from core.inference.diffusion_families import local_pipeline_components_are_complete
+ from core.inference.diffusion_flux3 import FLUX3_COMPONENT_FOLDERS
+
+ root = _official_layout(tmp_path, "distilled", True)
+ index = json.loads((root / "modular_model_index.json").read_text())
+ index.pop(missing)
+ (root / "modular_model_index.json").write_text(json.dumps(index))
+ check = lambda **kw: local_pipeline_components_are_complete( # noqa: E731
+ root, "modular_model_index.json", fixed_component_folders = FLUX3_COMPONENT_FOLDERS, **kw
+ )
+ assert check() # the folders are all there: an omitted entry alone is fine
+ folder = FLUX3_COMPONENT_FOLDERS[missing][0]
+ if missing == "transformer":
+ # A GGUF supplies the denoiser's weights, but not its config.
+ (root / folder / "model.safetensors").unlink()
+ assert not check()
+ assert check(excluded_components = ("transformer",))
+ for f in (root / folder).iterdir():
+ f.unlink()
+ assert not check()
+ assert not check(excluded_components = ("transformer",))
+
+
+def test_the_base_access_probe_reads_the_modular_manifest(tmp_path, monkeypatch):
+ # A cached gated FLUX.3 base with no usable token: the probe must recognise the cached snapshot by the manifest
+ # FLUX.3 actually ships, or the load is refused although every file is local.
+ import huggingface_hub
+ from huggingface_hub.errors import GatedRepoError
+ from core.inference import diffusion as d
+
+ cache = tmp_path / "hub"
+ snap = cache / "models--black-forest-labs--flux-3-image-klein" / "snapshots" / "abc"
+ snap.mkdir(parents = True)
+ (snap / "modular_model_index.json").write_text("{}")
+ (cache / "models--black-forest-labs--flux-3-image-klein" / "refs").mkdir()
+ (cache / "models--black-forest-labs--flux-3-image-klein" / "refs" / "main").write_text("abc")
+ monkeypatch.setattr(d, "hub_cache_dir", lambda: str(cache))
+
+ class _Api:
+ def model_info(self, *a, **k):
+ raise GatedRepoError(
+ "gated", response = SimpleNamespace(status_code = 401, headers = {}, request = None)
+ )
+
+ monkeypatch.setattr(huggingface_hub, "HfApi", _Api)
+ assert d._base_manifest_name(_family(FLUX3_KLEIN_FAMILY_NAME)) == "modular_model_index.json"
+ assert d._base_manifest_name(_family("flux.2-klein")) == "model_index.json"
+ d._assert_base_repo_accessible(
+ DISTILLED, None, d._base_manifest_name(_family(FLUX3_KLEIN_FAMILY_NAME))
+ )
+ # Every call site in the loader names the manifest instead of the conventional default.
+ import ast
+ import inspect
+
+ calls = [
+ n
+ for n in ast.walk(ast.parse(inspect.getsource(d.DiffusionBackend)))
+ if isinstance(n, ast.Call) and getattr(n.func, "id", None) == "_assert_base_repo_accessible"
+ ]
+ assert len(calls) == 3
+ for call in calls:
+ assert len(call.args) >= 3 and "_base_manifest_name" in ast.unparse(call.args[2])
+
+
+def test_restoring_skipped_shards_fetches_the_modular_manifest(monkeypatch, tmp_path):
+ from core.inference.diffusion import DiffusionBackend
+
+ seen = {}
+ be = DiffusionBackend()
+
+ def fake_prefetch(repo_id, gguf, base, files, token, **kw):
+ seen["files"] = list(files)
+ return str(tmp_path)
+
+ monkeypatch.setattr(be, "_prefetch_files", fake_prefetch)
+ out = be._restore_skipped_transformer_shards(
+ DISTILLED,
+ DISTILLED,
+ ["transformer/diffusion_pytorch_model-00001-of-00002.safetensors"],
+ None,
+ base_local_dir = str(tmp_path),
+ manifest = "modular_model_index.json",
+ )
+ assert out == str(tmp_path)
+ assert (
+ seen["files"][-1] == "modular_model_index.json" and "model_index.json" not in seen["files"]
+ )
+
+
+def test_the_prefetch_hands_back_the_snapshot_of_a_modular_manifest(monkeypatch, tmp_path):
+ # The staged dir is recognised by FLUX.3's own manifest, so the restore and the assemblies can load off it.
+ import utils.hf_xet_fallback as xf
+ from core.inference.diffusion import DiffusionBackend
+
+ snap = tmp_path / "snapshots" / "abc"
+
+ def fake_download(repo, name, token, **kw):
+ path = snap / name
+ path.parent.mkdir(parents = True, exist_ok = True)
+ path.write_text("{}")
+ return str(path)
+
+ monkeypatch.setattr(xf, "hf_hub_download_with_xet_fallback", fake_download)
+ be = DiffusionBackend()
+ root = be._prefetch_files(
+ DISTILLED,
+ None,
+ DISTILLED,
+ ["modular_model_index.json", "vae/config.json", "text_encoder/config.json"],
+ None,
+ fetch_base = DISTILLED,
+ )
+ assert root == str(snap)
+
+
+# ── review round 6: the download plan for FLUX.3 companions ─────────────────────
+_OFFICIAL_LISTING = (
+ "LICENSE.md",
+ "README.md",
+ "config.json",
+ "manifest.json",
+ "model.safetensors",
+ "modular_model_index.json",
+ "text_encoder/config.json",
+ "text_encoder/model-00001-of-00002.safetensors",
+ "text_encoder/tokenizer.json",
+ "transformer/config.json",
+ "transformer/diffusion_pytorch_model-00001-of-00002.safetensors",
+ "vae/config.json",
+ "vae/diffusion_pytorch_model.safetensors",
+ "variants/fp8r/model.safetensors",
+ "variants/nvfp4/model.safetensors",
+)
+
+
+def _fake_hub(monkeypatch, repo_files):
+ import huggingface_hub
+ from core.inference.diffusion_families import mirror_repo
+
+ # A gated BFL base is fetched from its byte-identical unsloth mirror, which the Hub lists the same way.
+ repo_files = {
+ **{mirror_repo(r): f for r, f in repo_files.items() if mirror_repo(r)},
+ **repo_files,
+ }
+
+ class _Api:
+ def __init__(self, *a, **k):
+ pass
+
+ def model_info(self, repo, *a, **k):
+ if repo not in repo_files:
+ from huggingface_hub.errors import RepositoryNotFoundError
+ raise RepositoryNotFoundError(
+ repo, response = SimpleNamespace(status_code = 404, headers = {}, request = None)
+ )
+ return SimpleNamespace(
+ siblings = [SimpleNamespace(rfilename = f, size = 10) for f in repo_files[repo]],
+ sha = "abc",
+ gated = False,
+ private = False,
+ )
+
+ monkeypatch.setattr(huggingface_hub, "HfApi", _Api)
+
+
+ "kind, name", [("gguf", "klein.gguf"), ("single_file", "klein.safetensors")]
+)
+def test_companion_staging_is_scoped_to_the_folders_flux3_loads(tmp_path, monkeypatch, kind, name):
+ # A GGUF / single file stages the official repo's text encoder, VAE, transformer config and the modular manifest
+ # (the staged-snapshot marker), never BFL's variants/ packages or the root single file.
+ from safetensors.torch import save_file
+ import torch
+ from core.inference import diffusion as d
+
+ _flux3_installed(monkeypatch)
+ _fake_hub(monkeypatch, {DISTILLED: _OFFICIAL_LISTING})
+ monkeypatch.setattr(d, "hub_cache_dir", lambda: str(tmp_path / "cold"))
+ picks = tmp_path / "picks"
+ picks.mkdir()
+ if kind == "gguf":
+ (picks / name).write_bytes(b"GGUF")
+ else:
+ save_file({"ref_time_in.in_layer.weight": torch.zeros(2, 2)}, str(picks / name))
+ plan = d.DiffusionBackend().download_plan(
+ str(picks),
+ gguf_filename = name,
+ base_repo = DISTILLED,
+ model_kind = kind,
+ family_override = FLUX3_KLEIN_FAMILY_NAME,
+ allow_device_probe = False,
+ memory_verdict = False,
+ discover_text_encoders = False,
+ )
+ # Staged from the ungated unsloth mirror of the gated BFL repo, never from BFL itself.
+ assert {e["repo_id"] for e in plan["entries"]} & {
+ DISTILLED,
+ "unsloth/flux-3-image-klein-FP8",
+ } == {"unsloth/flux-3-image-klein-FP8"}
+ files = sorted(
+ f
+ for e in plan["entries"]
+ if e["repo_id"] == "unsloth/flux-3-image-klein-FP8"
+ for f in e["files"]
+ )
+ assert files == [
+ "modular_model_index.json",
+ "text_encoder/config.json",
+ "text_encoder/model-00001-of-00002.safetensors",
+ "text_encoder/tokenizer.json",
+ "transformer/config.json",
+ "vae/config.json",
+ "vae/diffusion_pytorch_model.safetensors",
+ ]
+
+
+def test_a_cold_gguf_plan_never_asks_the_gated_vendor_repo(tmp_path, monkeypatch):
+ # The companions are staged from unsloth/flux-3-image-klein-FP8, so their listing comes from there too: an
+ # anonymous cold load asks black-forest-labs/* nothing, not even model_info.
+ import huggingface_hub
+ from core.inference import diffusion as d
+
+ _flux3_installed(monkeypatch)
+ _fake_hub(monkeypatch, {DISTILLED: _OFFICIAL_LISTING})
+ asked = []
+ listing = huggingface_hub.HfApi.model_info
+
+ def model_info(self, repo, *a, **k):
+ asked.append(repo)
+ return listing(self, repo, *a, **k)
+
+ monkeypatch.setattr(huggingface_hub.HfApi, "model_info", model_info)
+ monkeypatch.setattr(d, "hub_cache_dir", lambda: str(tmp_path / "cold"))
+ picks = tmp_path / "picks"
+ picks.mkdir()
+ (picks / "klein.gguf").write_bytes(b"GGUF")
+ plan = d.DiffusionBackend().download_plan(
+ str(picks),
+ gguf_filename = "klein.gguf",
+ base_repo = DISTILLED,
+ model_kind = "gguf",
+ family_override = FLUX3_KLEIN_FAMILY_NAME,
+ allow_device_probe = False,
+ memory_verdict = False,
+ discover_text_encoders = False,
+ )
+ assert "unsloth/flux-3-image-klein-FP8" in asked
+ assert not [r for r in asked if r.startswith("black-forest-labs/")]
+ assert "text_encoder/config.json" in next(
+ e["files"] for e in plan["entries"] if e["repo_id"] == "unsloth/flux-3-image-klein-FP8"
+ )
+
+
+def test_the_flux3_manifest_check_reads_the_mirror_not_the_gated_repo(tmp_path, monkeypatch):
+ import huggingface_hub
+ from core.inference import diffusion_compat as compat
+
+ asked = []
+ manifest = tmp_path / "modular_model_index.json"
+ manifest.write_text(json.dumps(_official_manifest("distilled", False)))
+
+ def hf_hub_download(repo, filename, **k):
+ asked.append(repo)
+ return str(manifest)
+
+ monkeypatch.setattr(huggingface_hub, "hf_hub_download", hf_hub_download)
+ monkeypatch.setattr(compat, "_local_gguf_path", lambda *a: None)
+ assert compat._flux3_pipeline_index(DISTILLED, None, True) is not None
+ assert asked == ["unsloth/flux-3-image-klein-FP8"]
+
+
+def test_the_dense_cache_probe_sees_only_the_flux3_transformer_folder(tmp_path, monkeypatch):
+ # The AUTO dense fast path asks whether the base transformer is cached; BFL's variants/ packages are not part of
+ # it, or a cached dense transformer would read as missing and the GGUF would be kept.
+ import torch
+ from core.inference import diffusion as d
+
+ _flux3_installed(monkeypatch)
+ _fake_hub(monkeypatch, {DISTILLED: _OFFICIAL_LISTING})
+ monkeypatch.setattr(d, "hub_cache_dir", lambda: str(tmp_path / "cold"))
+ seen = []
+
+ def _needed(
+ self,
+ fam,
+ kwargs,
+ *,
+ companion_files = None,
+ transformer_files = None,
+ **_,
+ ):
+ seen.append(tuple(transformer_files or ()))
+ return False
+
+ monkeypatch.setattr(d.DiffusionBackend, "_dense_quant_prefetch_needed", _needed)
+ picks = tmp_path / "picks"
+ picks.mkdir()
+ (picks / "klein.gguf").write_bytes(b"GGUF")
+ d.DiffusionBackend().download_plan(
+ str(picks),
+ gguf_filename = "klein.gguf",
+ base_repo = DISTILLED,
+ model_kind = "gguf",
+ family_override = FLUX3_KLEIN_FAMILY_NAME,
+ allow_device_probe = True,
+ memory_verdict = False,
+ discover_text_encoders = False,
+ )
+ assert seen, "the dense prefetch gate was never asked"
+ for files in seen:
+ assert files == ("transformer/diffusion_pytorch_model-00001-of-00002.safetensors",)
+
+
+def test_the_flux3_single_file_transformer_config_comes_from_the_staged_base():
+ # The transformer config is read from the staged companions, like the assembly after it, not re-resolved
+ # through fetch_base (an offline load from another cache root would fail there).
+ import inspect
+ from core.inference import diffusion as d
+
+ src = inspect.getsource(d.DiffusionBackend)
+ assert '"config": (_base_local_dir or fetch_base)\n' in src
+ assert (
+ "if is_flux3_family(fam)\n"
+ in src.split('"config": (_base_local_dir or fetch_base)', 1)[1][:200]
+ )
+
+
+def test_the_download_plan_reports_a_flux3_pick_of_the_other_variant(tmp_path, monkeypatch):
+ # The Images page stages the plan before it calls load, so the plan carries the same verdict as the load.
+ from safetensors.torch import save_file
+ import torch
+ from core.inference import diffusion as d
+
+ _flux3_installed(monkeypatch)
+ _fake_hub(monkeypatch, {BASE: _OFFICIAL_LISTING})
+ monkeypatch.setattr(d, "hub_cache_dir", lambda: str(tmp_path / "cold"))
+ picks = tmp_path / "picks"
+ picks.mkdir()
+ save_file({"ref_time_in.in_layer.weight": torch.zeros(2, 2)}, str(picks / "klein.safetensors"))
+ plan = d.DiffusionBackend().download_plan(
+ str(picks),
+ gguf_filename = "klein.safetensors",
+ base_repo = BASE,
+ model_kind = "single_file",
+ family_override = FLUX3_KLEIN_BASE_FAMILY_NAME,
+ allow_device_probe = False,
+ memory_verdict = False,
+ discover_text_encoders = False,
+ )
+ assert "Load it with family flux.3-klein" in (plan["incompatible_reason"] or "")
+
+
+def test_single_file_config_flow_map_follows_family():
+ # A base single file on distilled companions (the gated base repo's TE / VAE are the distilled ones) must not
+ # inherit flow_map=True from the companion config, and a distilled file on base companions must keep it.
+ from core.inference.diffusion_families import transformer_config_overrides_for
+
+ base_file = "diffusion_models/flux3_image_klein_bf16.safetensors"
+ assert transformer_config_overrides_for(detect_family(BASE), base_file, DISTILLED) == {
+ "flow_map": False
+ }
+ assert transformer_config_overrides_for(detect_family(DISTILLED), base_file, BASE) == {
+ "flow_map": True
+ }
+ assert "flow_map" not in transformer_config_overrides_for(
+ detect_family("black-forest-labs/FLUX.2-klein-4B"), "flux-2-klein-4b-Q4_K_M.gguf"
+ )
+
+
+def test_single_file_base_checkpoint_loads_on_distilled_config(tmp_path):
+ # End to end through diffusers' from_single_file: a base checkpoint (no target-time embedder) with a distilled
+ # config dir. Without the override the target-time embedder stays on meta and the load dies.
+ diffusers = pytest.importorskip("diffusers")
+ if not hasattr(diffusers, "Flux3Transformer2DModel"):
+ pytest.skip("diffusers without FLUX.3")
+ import torch
+ from safetensors.torch import save_file
+
+ from core.inference.diffusion_families import transformer_config_overrides_for
+
+ cls = diffusers.Flux3Transformer2DModel
+ cfg = dict(
+ attention_head_dim = 16,
+ axes_dims_rope = [4, 4, 4, 4],
+ cond_in_channels = 8,
+ in_channels = 8,
+ joint_attention_dim = 32,
+ mlp_ratio = 2.0,
+ num_attention_heads = 2,
+ num_layers = 1,
+ num_single_layers = 1,
+ timestep_channels = 16,
+ )
+ cfg_dir = tmp_path / "distilled" / "transformer"
+ cls.from_config({**cfg, "flow_map": True}).save_config(cfg_dir)
+ base_model = cls.from_config({**cfg, "flow_map": False})
+ assert getattr(base_model, "target_timestep_embedder", None) is None
+ ckpt = tmp_path / "base.safetensors"
+ save_file({k: v.contiguous() for k, v in base_model.state_dict().items()}, str(ckpt))
+ kwargs = {
+ "config": str(tmp_path / "distilled"),
+ "subfolder": "transformer",
+ "torch_dtype": torch.float32,
+ **transformer_config_overrides_for(
+ detect_family(BASE), "flux3_image_klein_bf16.safetensors"
+ ),
+ }
+ loaded = cls.from_single_file(str(ckpt), **kwargs)
+ assert loaded.config.flow_map is False
+ assert not any(p.is_meta for p in loaded.parameters())
+
+
+def test_comfy_declared_quant_files_pass_the_variant_check(tmp_path):
+ # BFL ships its ComfyUI int8 files with per-layer .comfy_quant tensors and its NVFP4 files with a
+ # _quantization_metadata header; its variants/ packages have neither and stay refused.
+ torch = pytest.importorskip("torch")
+ from safetensors.torch import save_file
+
+ from core.inference.diffusion_families import (
+ assert_flux3_checkpoint_matches_family,
+ flux3_comfy_declared,
+ )
+
+ base = {"emb_in.image.weight": torch.zeros(2, 2), "time_in.in_layer.weight": torch.zeros(2, 2)}
+ scales = {
+ "single_blocks.0.qkv.weight": torch.zeros(4, 4, dtype = torch.int8),
+ "single_blocks.0.qkv.weight_scale": torch.ones(4, 1),
+ }
+ int8 = tmp_path / "flux3_image_klein_int8_convrot.safetensors"
+ save_file(
+ {
+ **base,
+ **scales,
+ "single_blocks.0.qkv.comfy_quant": torch.tensor(
+ list(b'{"format":"int8_tensorwise"}'), dtype = torch.uint8
+ ),
+ },
+ str(int8),
+ )
+ nvfp4 = tmp_path / "flux3_image_klein_nvfp4.safetensors"
+ save_file({**base, **scales}, str(nvfp4), metadata = {"_quantization_metadata": '{"layers": {}}'})
+ package = tmp_path / "model.safetensors"
+ save_file({**base, **scales}, str(package), metadata = {"quantization": "nvfp4"})
+
+ fam = detect_family("x", "flux.3-klein-base")
+ assert_flux3_checkpoint_matches_family(fam, int8)
+ assert_flux3_checkpoint_matches_family(fam, nvfp4)
+ with pytest.raises(ValueError, match = "variants/fp8r or variants/nvfp4"):
+ assert_flux3_checkpoint_matches_family(fam, package)
+ with pytest.raises(ValueError, match = "flux.3-klein-base"):
+ assert_flux3_checkpoint_matches_family(detect_family("x", "flux.3-klein"), int8)
+ assert flux3_comfy_declared(["a.weight"], {"_quantization_metadata": "{}"})
+ assert not flux3_comfy_declared(["a.weight", "a.weight_scale"], {"quantization": "fp8r"})
+
+
+def test_pick_check_reads_comfy_declaration_from_hub_header(monkeypatch):
+ # The pre-eviction check reads a remote pick's header: the metadata table must reach the variant check.
+ from types import SimpleNamespace as NS
+
+ import huggingface_hub
+
+ from core.inference import diffusion_compat as compat
+
+ names = [
+ "emb_in.image.weight",
+ "time_in.in_layer.weight",
+ "single_blocks.0.q_proj.weight",
+ "single_blocks.0.q_proj.weight_scale",
+ "single_blocks.0.q_proj.weight_scale_2",
+ ]
+
+ class _Api:
+ def __init__(self, *a, **k):
+ pass
+
+ def parse_safetensors_file_metadata(
+ self,
+ repo_id,
+ filename,
+ token = None,
+ ):
+ md = (
+ {"_quantization_metadata": "{}"}
+ if repo_id.endswith("-comfy")
+ else {"quantization": "nvfp4"}
+ )
+ return NS(tensors = {n: None for n in names}, metadata = md)
+
+ monkeypatch.setattr(huggingface_hub, "HfApi", _Api)
+ monkeypatch.setattr(compat, "_local_gguf_path", lambda *a, **k: None)
+ fam = detect_family("x", "flux.3-klein-base")
+ compat.assert_flux3_pick_compatible(
+ fam,
+ "black-forest-labs/flux-3-image-klein-comfy",
+ "diffusion_models/flux3_image_klein_nvfp4.safetensors",
+ )
+ with pytest.raises(ValueError, match = "variants/fp8r or variants/nvfp4"):
+ compat.assert_flux3_pick_compatible(
+ fam, "black-forest-labs/flux-3-image-klein", "variants/nvfp4/model.safetensors"
+ )
+
+
+def test_comfy_fused_qkv_is_split_into_bfl_projections():
+ # BFL's ComfyUI int8 FLUX.3 files fuse q/k/v ("<block>.qkv.weight"); the loader converts row tags, so the split
+ # must hand each projection exactly its third of the rows, and drop the comfy_attention.config hint.
+ torch = pytest.importorskip("torch")
+ diffusers = pytest.importorskip("diffusers")
+ if not hasattr(diffusers, "Flux3Transformer2DModel"):
+ pytest.skip("diffusers without FLUX.3")
+ from core.inference.diffusion_comfy_quant import _mapping
+
+ fn, _sfm = _mapping(diffusers.Flux3Transformer2DModel)
+ tags = torch.arange(12, dtype = torch.float64).view(-1, 1).expand(12, 4)
+ out = fn(
+ checkpoint = {
+ "single_blocks.0.qkv.weight": tags.clone(),
+ "single_blocks.0.comfy_attention.config": torch.zeros(3, dtype = torch.uint8),
+ "content_mode_blocks.image.1.q_proj.weight": torch.ones(2, 2),
+ }
+ )
+ pre = "single_transformer_blocks.0.attn."
+ assert out[pre + "to_q.weight"][:, 0].tolist() == [0, 1, 2, 3]
+ assert out[pre + "to_k.weight"][:, 0].tolist() == [4, 5, 6, 7]
+ assert out[pre + "to_v.weight"][:, 0].tolist() == [8, 9, 10, 11]
+ assert "mode_blocks.image.1.attn.to_q.weight" in out
+ assert not any("comfy_attention" in k or "qkv" in k for k in out)
+
+
+def test_flux3_family_decides_generation_defaults_over_file_names():
+ # BFL's ComfyUI base files (flux3_image_klein_{bf16,int8_convrot,nvfp4}.safetensors) name no variant that reads as
+ # base; under the base family (which the variant check has matched to the checkpoint) they get the base recipe.
+ from core.inference.diffusion import _generation_defaults_for
+
+ base, dist = detect_family("x", "flux.3-klein-base"), detect_family("x", "flux.3-klein")
+ comfy = "black-forest-labs/flux-3-image-klein-comfy"
+ for name in ("bf16", "int8_convrot", "nvfp4"):
+ f = f"diffusion_models/flux3_image_klein_{name}.safetensors"
+ assert _generation_defaults_for(comfy, f, BASE, None, base) == {
+ "steps": 50,
+ "guidance": 3.5,
+ }
+ assert _generation_defaults_for("/local/dir", f, DISTILLED, None, base) == {
+ "steps": 50,
+ "guidance": 3.5,
+ }
+ sd = "diffusion_models/flux3_image_klein_sd_bf16.safetensors"
+ assert _generation_defaults_for(comfy, sd, DISTILLED, None, dist) == {
+ "steps": 16,
+ "guidance": 1.0,
+ }
+ # Not FLUX.3: names still lead (FLUX.1's base is schnell, a dev file keeps dev).
+ flux1 = detect_family("black-forest-labs/FLUX.1-dev")
+ assert (
+ _generation_defaults_for(
+ "x", "flux1-dev-Q4_K_M.gguf", "black-forest-labs/FLUX.1-schnell", None, flux1
+ )["steps"]
+ == 20
+ )
+
+
+def _seeded_snapshot(
+ tmp_path,
+ repo = "black-forest-labs/flux-3-image-klein",
+ variant = "distilled",
+):
+ """What a download planned around a hosted pre-quantized seed leaves in the HF cache: the official layout with
+ only the transformer config, no dense transformer shards."""
+ snapshot = tmp_path / "hub" / f"models--{repo.replace('/', '--')}" / "snapshots" / "abc123"
+ snapshot.parent.mkdir(parents = True)
+ _official_layout(tmp_path, variant, True).rename(snapshot)
+ (snapshot / "transformer" / "model.safetensors").unlink()
+ (snapshot.parent.parent / "refs").mkdir()
+ (snapshot.parent.parent / "refs" / "main").write_text("abc123")
+ return snapshot
+
+
+def test_only_the_snapshot_main_names_is_loaded_by_repo_id(tmp_path):
+ # A load by repo id resolves refs/main: a commit-pinned snapshot (no refs/main) or one main no longer names keeps
+ # its path, or the switch would load a different snapshot than the one the picker chose.
+ from core.inference.media_locality import flux3_seeded_cache_repo
+
+ snapshot = _seeded_snapshot(tmp_path)
+ assert flux3_seeded_cache_repo(snapshot) == "black-forest-labs/flux-3-image-klein"
+ (snapshot.parent.parent / "refs" / "main").write_text("def456")
+ assert flux3_seeded_cache_repo(snapshot) is None
+ (snapshot.parent.parent / "refs" / "main").unlink()
+ assert flux3_seeded_cache_repo(snapshot) is None
+
+
+def test_a_seeded_flux3_snapshot_is_planned_against_its_repo(tmp_path, monkeypatch):
+ from core.inference import gpu_arbiter as arb
+ from core.inference import media_locality as locality
+ from core.inference.media_model_index import MediaModelPick
+
+ snapshot = _seeded_snapshot(tmp_path)
+ seen = []
+
+ class _Planner:
+ def __init__(self, entries):
+ self.entries = entries
+
+ def download_plan(self, model_path, **kwargs):
+ seen.append(model_path)
+ return {"total_bytes": 0 if not self.entries else 5, "entries": self.entries}
+
+ monkeypatch.setattr(locality, "plan_gpu_ordinal", lambda: None)
+ pick = MediaModelPick("black-forest-labs/flux-3-image-klein", str(snapshot))
+ # seed cached: nothing to fetch, and the planner was asked about the repo the switch loads, not the folder
+ monkeypatch.setattr(locality, "planners_for", lambda owner, p: [_Planner([])])
+ assert locality.missing_download_bytes(arb.DIFFUSION, pick) == 0
+ assert seen == ["black-forest-labs/flux-3-image-klein"]
+ # seed not cached: sized like any hub pick instead of refused unsized
+ monkeypatch.setattr(
+ locality, "planners_for", lambda owner, p: [_Planner([{"repo_id": "unsloth/x"}])]
+ )
+ assert locality.missing_download_bytes(arb.DIFFUSION, pick) == 5
+ assert locality.flux3_seeded_cache_repo(snapshot) == "black-forest-labs/flux-3-image-klein"
+
+
+ "repo, family",
+ [
+ ("someone/opaque-image-model", "flux.3-klein"),
+ ("black-forest-labs/flux-3-image-klein", None),
+ ],
+)
+def test_a_seeded_snapshot_is_planned_with_its_manifest_family(tmp_path, monkeypatch, repo, family):
+ # Planned by repo id like the load, so an opaquely named repo needs the family its manifest declares, or the
+ # planner cannot pick the FLUX.3 seeds and reports the omitted dense shards as missing.
+ from core.inference import gpu_arbiter as arb
+ from core.inference import media_locality as locality
+ from core.inference.media_model_index import MediaModelPick
+
+ snapshot = _seeded_snapshot(tmp_path, repo = repo)
+ seen = []
+
+ class _Planner:
+ def download_plan(self, model_path, **kwargs):
+ seen.append((model_path, kwargs.get("family_override")))
+ return {"total_bytes": 0, "entries": []}
+
+ monkeypatch.setattr(locality, "plan_gpu_ordinal", lambda: None)
+ monkeypatch.setattr(locality, "planners_for", lambda owner, p: [_Planner()])
+ assert locality.missing_download_bytes(arb.DIFFUSION, MediaModelPick(repo, str(snapshot))) == 0
+ assert seen == [(repo, family)]
+
+
+def test_only_a_seeded_flux3_snapshot_is_mapped_to_its_repo(tmp_path):
+ from core.inference.media_locality import flux3_seeded_cache_repo
+
+ snapshot = _seeded_snapshot(tmp_path)
+ # a plain folder (not a cache snapshot) has no repo to load from
+ plain = tmp_path / "plain"
+ _official_layout(tmp_path, "base", False).rename(plain)
+ (plain / "transformer" / "model.safetensors").unlink()
+ assert flux3_seeded_cache_repo(plain) is None
+ # the transformer config is still read from the snapshot, so it must be there
+ (snapshot / "transformer" / "config.json").unlink()
+ assert flux3_seeded_cache_repo(snapshot) is None
+ other = _seeded_snapshot(tmp_path / "o")
+ (other / "vae" / "model.safetensors").unlink()
+ assert flux3_seeded_cache_repo(other) is None
+ manifest = _seeded_snapshot(tmp_path / "m")
+ (manifest / "modular_model_index.json").write_text(
+ json.dumps({"_class_name": "QwenImagePipeline"})
+ )
+ assert flux3_seeded_cache_repo(manifest) is None
+
+
+def test_a_snapshot_staged_for_the_int8_encoder_seed_is_still_a_seeded_snapshot(
+ tmp_path, monkeypatch
+):
+ # te_quant_auto is int8 ConvRot on both families, so a normally staged snapshot holds neither the dense
+ # transformer shards nor the dense text-encoder shards. Rejecting it read as UNSIZED_MISSING and blocked the
+ # media auto-switch; the planner, asked of the repo, decides whether the encoder seed is cached.
+ from core.inference import gpu_arbiter as arb
+ from core.inference import media_locality as locality
+ from core.inference.media_model_index import MediaModelPick
+
+ snapshot = _seeded_snapshot(tmp_path)
+ (snapshot / "text_encoder" / "model.safetensors").unlink()
+ assert locality.flux3_seeded_cache_repo(snapshot) == "black-forest-labs/flux-3-image-klein"
+ seen = []
+
+ class _Planner:
+ def download_plan(self, model_path, **kwargs):
+ seen.append(model_path)
+ return {"total_bytes": 0, "entries": []}
+
+ monkeypatch.setattr(locality, "plan_gpu_ordinal", lambda: None)
+ monkeypatch.setattr(locality, "planners_for", lambda owner, p: [_Planner()])
+ pick = MediaModelPick("black-forest-labs/flux-3-image-klein", str(snapshot))
+ assert locality.missing_download_bytes(arb.DIFFUSION, pick) == 0
+ assert seen == ["black-forest-labs/flux-3-image-klein"]
+ # the encoder config and the tokenizer are still read from the snapshot
+ (snapshot / "text_encoder" / "tokenizer.json").unlink()
+ assert locality.flux3_seeded_cache_repo(snapshot) is None
+ other = _seeded_snapshot(tmp_path / "c")
+ (other / "text_encoder" / "model.safetensors").unlink()
+ (other / "text_encoder" / "config.json").unlink()
+ assert locality.flux3_seeded_cache_repo(other) is None
+
+
+def test_the_auto_switch_loads_a_seeded_flux3_snapshot_by_repo(tmp_path, monkeypatch):
+ import asyncio
+
+ import routes.inference as route
+ from core.inference import gpu_arbiter as arb
+ from core.inference import media_auto_switch as mas
+ from core.inference.media_model_index import MediaModelPick
+
+ seen = []
+
+ async def _load(
+ request,
+ subject,
+ user_initiated = True,
+ ):
+ seen.append((request.model_path, request.display_repo_id, user_initiated))
+
+ monkeypatch.setattr(route, "load_diffusion_model_gated", _load)
+ snapshot = _seeded_snapshot(tmp_path)
+ full = tmp_path / "full"
+ _official_layout(tmp_path, "base", False).rename(full)
+ repo = "black-forest-labs/flux-3-image-klein"
+ asyncio.run(mas._start_load(arb.DIFFUSION, MediaModelPick(repo, str(snapshot)), "s"))
+ asyncio.run(mas._start_load(arb.DIFFUSION, MediaModelPick("local/full", str(full)), "s"))
+ assert seen == [(repo, repo, False), (str(full), "local/full", False)]
+
+
+ "variant, family",
+ [("distilled", FLUX3_KLEIN_FAMILY_NAME), ("base", FLUX3_KLEIN_BASE_FAMILY_NAME)],
+)
+def test_the_auto_switch_keeps_the_manifest_family_of_an_opaque_seeded_repo(
+ tmp_path, monkeypatch, variant, family
+):
+ # The scanner names an opaquely named snapshot's family from its modular_model_index.json; the repo id the switch
+ # loads by carries no such evidence, so the load must be told the family the manifest declared.
+ import asyncio
+
+ import routes.inference as route
+ from core.inference import gpu_arbiter as arb
+ from core.inference import media_auto_switch as mas
+ from core.inference.diffusion_families import detect_family_for_pick
+ from core.inference.media_model_index import MediaModelPick
+
+ seen = []
+
+ async def _load(
+ request,
+ subject,
+ user_initiated = True,
+ ):
+ seen.append(request)
+
+ monkeypatch.setattr(route, "load_diffusion_model_gated", _load)
+ repo = "someone/opaque-image-model"
+ snapshot = _seeded_snapshot(tmp_path, repo = repo, variant = variant)
+ assert detect_family_for_pick(str(snapshot)).name == family
+ assert detect_family_for_pick(repo) is None
+ asyncio.run(mas._start_load(arb.DIFFUSION, MediaModelPick(repo, str(snapshot)), "s"))
+ (request,) = seen
+ assert request.model_path == repo
+ assert request.family_override == family
+ assert detect_family_for_pick(request.model_path, None, request.family_override).name == family
+
+
+def test_the_auto_switch_adds_no_family_to_a_named_seeded_repo(tmp_path, monkeypatch):
+ # A repo id that already names the family the manifest declares loads exactly as before (detected, not requested).
+ import asyncio
+
+ import routes.inference as route
+ from core.inference import gpu_arbiter as arb
+ from core.inference import media_auto_switch as mas
+ from core.inference.media_model_index import MediaModelPick
+
+ seen = []
+
+ async def _load(
+ request,
+ subject,
+ user_initiated = True,
+ ):
+ seen.append(request)
+
+ monkeypatch.setattr(route, "load_diffusion_model_gated", _load)
+ repo = "black-forest-labs/flux-3-image-klein"
+ snapshot = _seeded_snapshot(tmp_path, repo = repo)
+ asyncio.run(mas._start_load(arb.DIFFUSION, MediaModelPick(repo, str(snapshot)), "s"))
+ assert [(r.model_path, r.family_override) for r in seen] == [(repo, None)]
+
+
+def test_flux3_reference_edits_use_the_measured_activations(monkeypatch):
+ import torch
+
+ from core.inference import diffusion as d
+
+ monkeypatch.setattr(d, "sdpa_subquadratic_confirmed", lambda target: True)
+ nvidia = SimpleNamespace(backend = "cuda", vendor = "nvidia", dtype = torch.bfloat16)
+ distilled = _family("flux.3-klein")
+ assert distilled.reference and not tuple(getattr(distilled, "reference_resolutions", ()) or ())
+ act = d._calibrated_activation(distilled, nvidia)
+ assert act is not None and act == d.calibrated_image_activation("flux.3-klein", max_speed = True)
+ # the base runs CFG (two denoiser batches) and has no measured row: it keeps the flat estimate
+ assert d._calibrated_activation(_family("flux.3-klein-base"), nvidia) is None
+
+
[email protected]("with_upsampler", [False, True])
+def test_the_block_graph_drops_the_prompt_upsampler_step(monkeypatch, with_upsampler):
+ # diffusers#15058 puts a prompt upsampler step first in both auto block graphs; its text-to-image branch has no
+ # trigger input, so it would run on every call and need the ~19 GB upsampler Studio never loads.
+ # flux3_blocks only looks the class up on the diffusers module, so a stub module stands in for it and the
+ # check runs on installs without diffusers too.
+ from core.inference.diffusion_flux3 import FLUX3_DISTILLED_BLOCKS, flux3_blocks
+
+ diffusers = types.ModuleType("diffusers")
+ monkeypatch.setitem(sys.modules, "diffusers", diffusers)
+
+ class _Blocks:
+ def __init__(self):
+ steps = ["text_encoder", "vae_encoder", "denoise", "decode"]
+ self.sub_blocks = dict.fromkeys(
+ (["prompt_upsampler"] if with_upsampler else []) + steps
+ )
+
+ setattr(diffusers, FLUX3_DISTILLED_BLOCKS, _Blocks)
+ assert list(flux3_blocks(FLUX3_DISTILLED_BLOCKS).sub_blocks) == [
+ "text_encoder",
+ "vae_encoder",
+ "denoise",
+ "decode",
+ ]
+
+
+def test_a_modular_flux3_dir_with_one_root_checkpoint_stays_a_pipeline(tmp_path):
+ # FLUX.3 ships modular_model_index.json, not model_index.json: a lone root .safetensors must not turn
+ # the directory into a single-file load before the modular validation sees it.
+ from core.inference.diffusion import resolve_local_single_file
+ from core.inference.diffusion_flux3 import FLUX3_INDEX
+
+ d = tmp_path / "flux3-klein"
+ d.mkdir()
+ (d / "model.safetensors").write_bytes(b"w")
+ assert resolve_local_single_file(str(d)) == "model.safetensors"
+ (d / FLUX3_INDEX).write_text("{}")
+ assert resolve_local_single_file(str(d)) is None
+
+
+def test_the_pipeline_estimate_probes_the_flux3_index_for_a_cached_upstream(monkeypatch):
+ # The mirror probe must ask for the index the family ships; asking for model_index.json never finds the
+ # cached upstream FLUX.3 snapshot and stages the same pipeline again under the mirror.
+ import types
+
+ from core.inference import diffusion as dmod
+ from core.inference.diffusion import DiffusionBackend
+ from core.inference.diffusion_flux3 import FLUX3_INDEX
+
+ upstream, mirror = "black-forest-labs/FLUX.3-klein", "unsloth/FLUX.3-klein"
+ names = (FLUX3_INDEX, "vae/config.json", "transformer/diffusion_pytorch_model.safetensors")
+ siblings = [types.SimpleNamespace(rfilename = name, size = 1) for name in names]
+
+ class _Api:
+ def model_info(self, repo_id, **kw):
+ return types.SimpleNamespace(siblings = siblings, sha = "abc")
+
+ monkeypatch.setattr("huggingface_hub.HfApi", _Api)
+ probes: list = []
+
+ def _prefer(
+ repo_id,
+ hf_token = None,
+ files = None,
+ **kw,
+ ):
+ probes.append(tuple(files or ()))
+ # The upstream snapshot is cached: keep it when every probed file is there, else the mirror.
+ return repo_id if files and set(files) <= set(names) else mirror
+
+ monkeypatch.setattr(dmod, "prefer_ungated_mirror", _prefer)
+ fetch_repos: dict = {}
+ DiffusionBackend._estimate_download_bytes(
+ upstream,
+ None,
+ upstream,
+ None,
+ kind = "pipeline",
+ base_manifest = FLUX3_INDEX,
+ fetch_repos_out = fetch_repos,
+ )
+ assert probes[0] == (FLUX3_INDEX,)
+ assert fetch_repos[upstream] == upstream
diff --git a/studio/backend/tests/test_diffusion_flux3_te_prequant.py b/studio/backend/tests/test_diffusion_flux3_te_prequant.py
new file mode 100644
index 00000000000..833c332f036
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_flux3_te_prequant.py
@@ -0,0 +1,422 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""FLUX.3 Klein's hosted pre-quantized Qwen3-VL-4B text encoders: fp8 layerwise and int8 ConvRot, both variants."""
+
+from __future__ import annotations
+
+import json
+import types
+
+import pytest
+
+torch = pytest.importorskip("torch")
+pytest.importorskip("transformers.models.qwen3_vl")
+pytest.importorskip("accelerate")
+
+import core.inference.diffusion_te_prequant as tpq # noqa: E402
+import core.inference.prequant_safetensors as ps # noqa: E402
+from core.inference.diffusion_families import detect_family # noqa: E402
+from core.inference.diffusion_text_encoder_trim import family_trims_lm_head, is_trimmed # noqa: E402
+
+GROUP = 256
+HIDDEN, VOCAB = 256, 64
+CUDA_BF16 = types.SimpleNamespace(device = "cuda", dtype = torch.bfloat16)
+MPS_BF16 = types.SimpleNamespace(device = "mps", dtype = torch.bfloat16)
+DISTILLED, BASE = (
+ "black-forest-labs/flux-3-image-klein",
+ "black-forest-labs/flux-3-image-klein-base",
+)
+VARIANTS = {
+ "flux.3-klein": (DISTILLED, "unsloth/flux-3-image-klein-FP8", "flux-3-image-klein"),
+ "flux.3-klein-base": (BASE, "unsloth/flux-3-image-klein-base-FP8", "flux-3-image-klein-base"),
+}
+
+
+def _names(stem):
+ return (
+ f"{stem}-text_encoder-INT8-ConvRot.safetensors",
+ f"{stem}-text_encoder-FP8.safetensors",
+ f"{stem}-text_encoder-FP8.pt",
+ )
+
+
+def _config():
+ """A tiny Qwen3-VL with the real 4B's TIED embedding (tie_word_embeddings: true in text_encoder/config.json)."""
+ from transformers.models.qwen3_vl.configuration_qwen3_vl import (
+ Qwen3VLConfig,
+ Qwen3VLTextConfig,
+ Qwen3VLVisionConfig,
+ )
+
+ config = Qwen3VLConfig(
+ vision_config = Qwen3VLVisionConfig(
+ depth = 1,
+ hidden_size = 32,
+ intermediate_size = 64,
+ num_heads = 4,
+ out_hidden_size = HIDDEN,
+ deepstack_visual_indexes = [],
+ ).to_dict(),
+ text_config = Qwen3VLTextConfig(
+ hidden_size = HIDDEN,
+ intermediate_size = 512,
+ num_hidden_layers = 2,
+ num_attention_heads = 4,
+ num_key_value_heads = 2,
+ head_dim = 64,
+ vocab_size = VOCAB,
+ tie_word_embeddings = True,
+ rope_scaling = {
+ "rope_type": "default",
+ "mrope_section": [16, 8, 8],
+ "mrope_interleaved": True,
+ },
+ ).to_dict(),
+ tie_word_embeddings = True,
+ )
+ config._attn_implementation = "sdpa"
+ return config
+
+
+def _encoder(seed = 0):
+ from transformers import Qwen3VLForConditionalGeneration
+ torch.manual_seed(seed)
+ return Qwen3VLForConditionalGeneration(_config()).eval()
+
+
+def _hidden(encoder, ids):
+ with torch.no_grad():
+ out = encoder(input_ids = ids, attention_mask = torch.ones_like(ids), output_hidden_states = True)
+ return out.hidden_states
+
+
+def _write(
+ path,
+ state,
+ fmt,
+ scheme,
+ base = DISTILLED,
+):
+ from safetensors.torch import save_file
+
+ meta = {
+ ps.UNSLOTH_FORMAT_KEY: fmt,
+ ps.UNSLOTH_METADATA_KEY: json.dumps(
+ {
+ "scheme": scheme,
+ "component": "text_encoder",
+ "base_model_id": base,
+ "te_class": "Qwen3VLForConditionalGeneration",
+ }
+ ),
+ "tensor_names": json.dumps(sorted(state)),
+ **{n: json.dumps({"_type": "Tensor"}) for n in state},
+ }
+ path.parent.mkdir(parents = True, exist_ok = True)
+ save_file(
+ {k: v.detach().clone().contiguous() for k, v in state.items()}, str(path), metadata = meta
+ )
+ return path
+
+
+def _int8_state(encoder):
+ """scripts/build_te_int8_convrot_checkpoint.py's layout: projections int8 + scale + comfy_quant, no lm_head."""
+ import re
+
+ lin = re.compile(
+ r"^model\.language_model\.layers\.\d+\.(self_attn\.[qkvo]_proj|mlp\.(gate|up|down)_proj)\.weight$"
+ )
+ blob = torch.tensor(
+ list(
+ json.dumps(
+ {"format": "int8_tensorwise", "convrot": True, "convrot_groupsize": GROUP}
+ ).encode()
+ ),
+ dtype = torch.uint8,
+ )
+ state = {}
+ for k, v in encoder.state_dict().items():
+ if k == "lm_head.weight":
+ continue
+ if lin.match(k):
+ q, s = tpq.quantize_int8_convrot_weight(v, GROUP)
+ state[k], state[k[:-7] + ".weight_scale"], state[k[:-7] + ".comfy_quant"] = (
+ q,
+ s,
+ blob.clone(),
+ )
+ else:
+ state[k] = v
+ return state
+
+
+def _fp8_state(encoder):
+ # _cast_fp8 is diffusers' layerwise casting; the fp8 file it writes is what the loader is checked against.
+ pytest.importorskip("diffusers.hooks")
+ from core.inference.diffusion_precision import _cast_fp8
+
+ _cast_fp8(encoder, types.SimpleNamespace(dtype = torch.float32))
+ return dict(encoder.state_dict())
+
+
+def mirror(tmp_path, monkeypatch):
+ """Both variants' files in a local mirror (one encoder, so the same bytes under each repo's names)."""
+ monkeypatch.setattr(ps, "_torchao_helpers", lambda: None)
+ import transformers
+
+ monkeypatch.setattr(transformers.AutoConfig, "from_pretrained", lambda *_a, **_k: _config())
+ import huggingface_hub
+
+ monkeypatch.setattr(
+ huggingface_hub, "hf_hub_download", lambda *a, **k: pytest.fail("the Hub was asked")
+ )
+ root = tmp_path / "mirror"
+ int8 = _int8_state(_encoder(seed = 3))
+ fp8 = _fp8_state(_encoder(seed = 3))
+ for _base, repo, stem in VARIANTS.values():
+ int8_name, fp8_name, _pt = _names(stem)
+ _write(root / repo / int8_name, int8, tpq.TE_PREQUANT_FORMAT_INT8_CONVROT, "int8")
+ _write(root / repo / fp8_name, fp8, tpq.TE_PREQUANT_FORMAT, "fp8")
+ monkeypatch.setenv(tpq.TE_PREQUANT_MIRROR_ENV, str(root))
+ return root
+
+
+class _Log:
+ def __init__(self):
+ self.lines = []
+
+ def __getattr__(self, _name):
+ return lambda msg, *a, **_k: self.lines.append(str(msg) % a if a else str(msg))
+
+
+def _pipe_kwargs(
+ family,
+ mode,
+ target = CUDA_BF16,
+ logger = None,
+):
+ fam = detect_family("", override = family)
+ return tpq.te_prequant_pipe_kwargs(
+ fam,
+ fam.base_repo,
+ te_quant_mode = mode,
+ target = target,
+ dtype = torch.float32,
+ local_files_only = True,
+ logger = logger,
+ )
+
+
[email protected]("family", sorted(VARIANTS))
+def test_both_variants_host_fp8_and_int8_convrot_encoders(family):
+ _base, repo, stem = VARIANTS[family]
+ fam = detect_family("", override = family)
+ assert fam.te_prequant_repos == (("fp8", "text_encoder", repo),)
+ assert tpq.family_te_int8_convrot(fam, "text_encoder") == (repo, _names(stem)[0])
+ # The int8 file has no lm_head, so the family must read hidden states only or the resolver drops to fp8.
+ assert family_trims_lm_head(family)
+
+
[email protected]("family", sorted(VARIANTS))
+def test_filenames_follow_the_qwen_image_2_1_pattern_per_variant(family):
+ base, repo, stem = VARIANTS[family]
+ fam = detect_family("", override = family)
+ int8 = tpq.te_prequant_sources_for_base(fam, base, te_quant_mode = "int8", target = CUDA_BF16)
+ assert (int8["text_encoder"].kind, int8["text_encoder"].location) == ("repo", repo)
+ assert tpq.te_candidate_filenames(int8["text_encoder"]) == _names(stem)
+ fp8 = tpq.te_prequant_sources_for_base(fam, base, te_quant_mode = "fp8", target = CUDA_BF16)
+ assert tpq.te_candidate_filenames(fp8["text_encoder"]) == _names(stem)[1:]
+ # The ungated unsloth mirror of the base resolves the same artifact.
+ mirror_id = base.replace("black-forest-labs/", "unsloth/")
+ assert (
+ tpq.te_prequant_sources_for_base(fam, mirror_id, te_quant_mode = "int8", target = CUDA_BF16)
+ == int8
+ )
+ # MPS takes the int8 file alone and budgets it at its own measured share.
+ mps = tpq.te_prequant_sources_for_base(fam, base, te_quant_mode = "int8", target = MPS_BF16)
+ assert tpq.te_candidate_filenames(mps["text_encoder"]) == _names(stem)[:1]
+ assert tpq.te_int8_convrot_budget_scale(fam) >= 5_247_076_320 / 8_875_719_344
+
+
+def test_one_encoder_serves_both_variants():
+ # The distilled and base text_encoder/ shards are byte-identical, so either base id validates the other's file.
+ assert tpq.te_base_equivalent(DISTILLED, BASE)
+ assert tpq.te_base_equivalent("unsloth/flux-3-image-klein-FP8", BASE)
+ assert not tpq.te_base_equivalent(DISTILLED, "Qwen/Qwen-Image-2.1")
+
+
[email protected]("family", sorted(VARIANTS))
+def test_int8_convrot_encoder_loads_with_the_int8_format(mirror, family):
+ from core.inference.video_minimax_h3_te import _int8_convrot_linear_class
+
+ log = _Log()
+ encoder = _pipe_kwargs(family, "int8", logger = log)["text_encoder"]
+ assert getattr(encoder, tpq.TE_PREQUANT_SCHEME_ATTR) == "int8"
+ assert any("int8 ConvRot" in line for line in log.lines)
+ # The tied head has no key in the file: dropped, never loaded random or left on meta.
+ assert is_trimmed(encoder)
+ cls = _int8_convrot_linear_class()
+ layers = encoder.model.language_model.layers
+ assert sum(isinstance(m, cls) for m in layers.modules()) == 2 * 7
+ assert not any(isinstance(m, torch.nn.Linear) for m in layers.modules())
+ # Every hidden state FLUX.3 stacks stays close to the dense encoder's.
+ ids = torch.randint(0, VOCAB, (1, 9))
+ dense, got = _hidden(_encoder(seed = 3), ids), _hidden(encoder, ids)
+ assert len(dense) == len(got)
+ for a, b in zip(dense[1:], got[1:]):
+ assert torch.nn.functional.cosine_similarity(a.flatten(), b.flatten(), dim = 0) > 0.99
+
+
[email protected]("family", sorted(VARIANTS))
+def test_fp8_request_loads_the_fp8_file(mirror, family):
+ encoder = _pipe_kwargs(family, "fp8")["text_encoder"]
+ assert getattr(encoder, tpq.TE_PREQUANT_SCHEME_ATTR) == "fp8"
+ assert encoder.lm_head.weight is encoder.model.language_model.embed_tokens.weight
+
+
+def test_fp8_request_refuses_an_int8_file_and_int8_never_reports_an_fp8_file(mirror, monkeypatch):
+ _base, repo, stem = VARIANTS["flux.3-klein"]
+ int8_name, fp8_name, _pt = _names(stem)
+ # Swap the two files: the int8 bytes under the fp8 name, the fp8 bytes under the int8 name.
+ a, b = mirror / repo / int8_name, mirror / repo / fp8_name
+ tmp = a.with_suffix(".swap")
+ a.rename(tmp)
+ b.rename(a)
+ tmp.rename(b)
+ log = _Log()
+ assert _pipe_kwargs("flux.3-klein", "fp8", logger = log) == {}
+ assert any("checkpoint scheme 'int8' != 'fp8'" in line for line in log.lines)
+ # An int8 request reads the int8-named file by its format tag: fp8 bytes load as fp8 and are labelled fp8.
+ encoder = _pipe_kwargs("flux.3-klein", "int8")["text_encoder"]
+ assert getattr(encoder, tpq.TE_PREQUANT_SCHEME_ATTR) == "fp8"
+
+
[email protected]("family", sorted(VARIANTS))
+def test_an_invisible_repo_falls_back_to_the_dense_encoder(tmp_path, monkeypatch, family):
+ from huggingface_hub.errors import RepositoryNotFoundError
+
+ monkeypatch.delenv(tpq.TE_PREQUANT_MIRROR_ENV, raising = False)
+ _base, repo, stem = VARIANTS[family]
+ asked: list = []
+
+ def invisible(repo_id, filename, **_k):
+ asked.append((repo_id, filename))
+ raise RepositoryNotFoundError(f"404 {repo_id}")
+
+ import huggingface_hub
+
+ monkeypatch.setattr(huggingface_hub, "hf_hub_download", invisible)
+ # The load asked the hosted repo for the int8 file, then handed back nothing, so assembly loads the dense bf16
+ # encoder (an unknown repo ends the name chain: no fp8 name can be there either).
+ assert _pipe_kwargs(family, "int8") == {}
+ assert asked and asked[0] == (repo, _names(stem)[0])
+ assert {r for r, _n in asked} == {repo}
+
+ class Invisible:
+ def model_info(self, *a, **k):
+ raise RepositoryNotFoundError("404")
+
+ fam = detect_family("", override = family)
+ sources = tpq.te_prequant_sources_for_base(
+ fam, fam.base_repo, te_quant_mode = "int8", target = CUDA_BF16
+ )
+ assert sources
+ # Nothing resolves on the Hub, so the plan keeps the dense text_encoder/ shards.
+ assert tpq.te_prequant_hub_files(sources, Invisible()) == {}
+
+
+def test_both_flux3_families_default_to_the_hosted_int8_convrot_encoder():
+ # BFL's ComfyUI templates load qwen3vl_4b_int8_convrot, so an unset request gets the hosted int8 file; "none"
+ # still reaches the released bf16 encoder.
+ from core.inference.diffusion_families import _FAMILIES as FAMILIES
+ from core.inference.diffusion_precision import resolve_te_quant_request
+ for name in ("flux.3-klein", "flux.3-klein-base"):
+ fam = next(f for f in FAMILIES if f.name == name)
+ assert fam.te_quant_auto == "int8", name
+ assert resolve_te_quant_request(None, fam.te_quant_auto) == ("int8", True)
+ assert resolve_te_quant_request("none", fam.te_quant_auto)[0] is None
+
+
+def _staged_only_config(tmp_path, monkeypatch):
+ """A staged companion dir (as a cache-only load resolves under a fallback cache root) holding the encoder config
+ but no dense shards; AutoConfig finds the config only there, never under the canonical base id."""
+ import transformers
+
+ staged = tmp_path / "fallback_root" / "snapshot"
+ (staged / "text_encoder").mkdir(parents = True)
+ (staged / "text_encoder" / "config.json").write_text("{}")
+ asked = []
+
+ def from_pretrained(source, *a, **k):
+ asked.append(str(source))
+ if str(source) != str(staged):
+ raise OSError(f"{source} is not in the active cache")
+ return _config()
+
+ monkeypatch.setattr(transformers.AutoConfig, "from_pretrained", from_pretrained)
+ return staged, asked
+
+
[email protected]("family", sorted(VARIANTS))
+def test_the_prequant_encoder_reads_its_config_from_the_staged_base(
+ mirror, tmp_path, monkeypatch, family
+):
+ staged, asked = _staged_only_config(tmp_path, monkeypatch)
+ fam = detect_family("", override = family)
+ kwargs = dict(
+ te_quant_mode = "int8", target = CUDA_BF16, dtype = torch.float32, local_files_only = True
+ )
+ # without a config source the canonical id misses the config, and the dense fallback is refused
+ with pytest.raises(RuntimeError, match = "could not be loaded"):
+ tpq.te_prequant_pipe_kwargs(fam, fam.base_repo, dense_source = str(staged), **kwargs)
+ asked.clear()
+ encoder = tpq.te_prequant_pipe_kwargs(
+ fam, fam.base_repo, dense_source = str(staged), config_source = str(staged), **kwargs
+ )["text_encoder"]
+ assert getattr(encoder, tpq.TE_PREQUANT_SCHEME_ATTR) == "int8"
+ assert asked == [str(staged)]
+
+
+def test_flux3_assembly_hands_the_staged_dir_to_the_prequant_encoder(tmp_path, monkeypatch):
+ import core.inference.diffusion as d
+
+ seen = {}
+
+ def te_kwargs(fam, base, **k):
+ seen["base"], seen["config_source"] = base, k.get("config_source")
+ return {"text_encoder": "enc"}
+
+ class _Pipe:
+ def to(self, device):
+ return self
+
+ monkeypatch.setattr(d, "te_prequant_pipe_kwargs", te_kwargs)
+ monkeypatch.setattr(
+ d,
+ "load_flux3_pipeline",
+ lambda root, *a, **k: seen.update(root = root, te = k["text_encoder"]) or _Pipe(),
+ )
+ staged = str(tmp_path / "staged")
+ d.DiffusionBackend._assemble_pipe(
+ None,
+ DISTILLED,
+ object(),
+ torch.float32,
+ None,
+ "cpu",
+ base_local_dir = staged,
+ fam = detect_family("", override = "flux.3-klein"),
+ te_quant_mode = "int8",
+ target = CUDA_BF16,
+ fetch_base = "unsloth/flux-3-image-klein-FP8",
+ local_files_only = True,
+ )
+ # the canonical fetch id for checkpoint compatibility, the staged dir for the config, as the pipeline itself
+ assert seen == {
+ "base": "unsloth/flux-3-image-klein-FP8",
+ "config_source": staged,
+ "root": staged,
+ "te": "enc",
+ }
diff --git a/studio/backend/tests/test_diffusion_qwenimage21.py b/studio/backend/tests/test_diffusion_qwenimage21.py
index 77db17fd76a..7b02fc0048b 100644
--- a/studio/backend/tests/test_diffusion_qwenimage21.py
+++ b/studio/backend/tests/test_diffusion_qwenimage21.py
@@ -385,3 +385,20 @@ def test_an_autocast_change_between_steps_matches_the_stock_forward(prefill, dec
got = render()
for a, b in zip(ref, got):
assert torch.equal(a, b)
+
+
+def test_an_unknown_build_token_metadata_keeps_the_stock_forward():
+ """Both known sources (0.41.0, main d42ebf9c) are accepted; any other edit still falls back."""
+ assert q._FINGERPRINTS["build_token_metadata"] == frozenset(
+ {"51818c1674e0d406", "9282e4c4803957f8"}
+ )
+ fake = types.SimpleNamespace(**vars(qmod))
+
+ class QwenImage21Transformer2DModel(qmod.QwenImage21Transformer2DModel):
+ forward = qmod.QwenImage21Transformer2DModel.forward
+
+ def build_token_metadata(self, image_pad_mask, img_shapes):
+ return None, None
+
+ fake.QwenImage21Transformer2DModel = QwenImage21Transformer2DModel
+ assert "build_token_metadata differs" in q.why_unsupported(fake)
diff --git a/studio/backend/tests/test_diffusion_qwenimage_rope.py b/studio/backend/tests/test_diffusion_qwenimage_rope.py
index ff766fb4d8a..40255b0bfe9 100644
--- a/studio/backend/tests/test_diffusion_qwenimage_rope.py
+++ b/studio/backend/tests/test_diffusion_qwenimage_rope.py
@@ -1,7 +1,8 @@
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-"""Tests for ``diffusion_qwenimage_rope.py``: the Qwen-Image RoPE table entry swap."""
+"""Tests for ``diffusion_qwenimage_rope.py``: the Qwen-Image RoPE swap, table entry (diffusers 0.41.0) or module
+global (main d42ebf9c, no table)."""
from __future__ import annotations
@@ -23,6 +24,18 @@ needs_cuda = pytest.mark.skipif(
)
+HAS_TABLE = hasattr(qmod, "ROPE_PER_DEVICE")
+
+
+def _rope():
+ """What the attention processor calls on CUDA, in either stock form."""
+ return qmod.ROPE_PER_DEVICE["cuda"] if HAS_TABLE else qmod.apply_rotary_emb_qwen
+
+
+def _call(fn, x, freqs):
+ return fn(x, freqs) if HAS_TABLE else fn(x, freqs, use_real = False)
+
+
@pytest.fixture(autouse = True)
def _restore(monkeypatch):
monkeypatch.delenv(qr.QWEN_REAL_ROPE_ENV, raising = False)
@@ -31,9 +44,25 @@ def _restore(monkeypatch):
def test_stock_entry_fingerprint_matches():
- entry = qmod.ROPE_PER_DEVICE["cuda"]
- assert q21._digest(entry.func) in qr._FINGERPRINT
- assert entry.keywords == {"use_real": False}
+ if HAS_TABLE:
+ entry = qmod.ROPE_PER_DEVICE["cuda"]
+ assert q21._digest(entry.func) in qr._FINGERPRINT
+ assert entry.keywords == {"use_real": False}
+ else:
+ assert q21._digest(qmod.apply_rotary_emb_qwen) in qr._FINGERPRINT
+ call = vars(getattr(qmod, qr._PROCESSOR))["__call__"]
+ assert q21._digest(call) in qr._PROCESSOR_FINGERPRINT
+
+
+def test_an_unknown_call_site_keeps_the_complex_rope(monkeypatch):
+ _fake_probe(monkeypatch)
+ stock = _rope()
+ if HAS_TABLE:
+ monkeypatch.setattr(q21, "_digest", lambda fn: "0000000000000000")
+ else:
+ monkeypatch.setattr(qr, "_PROCESSOR_FINGERPRINT", frozenset({"0000000000000000"}))
+ assert qr._patch_table(0) is False
+ assert _rope() is stock
def test_disabled_and_other_models_are_noops(monkeypatch):
@@ -45,22 +74,22 @@ def test_disabled_and_other_models_are_noops(monkeypatch):
@needs_cuda
def test_compiled_rope_bit_identical_to_complex_product():
index = torch.cuda.current_device()
- stock = qmod.ROPE_PER_DEVICE["cuda"]
+ stock = _rope()
assert qr._patch_table(index)
- patched = qmod.ROPE_PER_DEVICE["cuda"]
+ patched = _rope()
assert patched is not stock
g = torch.Generator(device = "cpu").manual_seed(0)
x = torch.randn(2, 300, 24, 128, generator = g).cuda().to(torch.bfloat16)
ang = torch.rand(300, 64, generator = g) * 6.28
freqs = torch.polar(torch.ones_like(ang), ang).to(torch.complex64).cuda()
- ref = stock(x, freqs)
+ ref = _call(stock, x, freqs)
torch._dynamo.reset()
- out = torch.compile(lambda a, f: qmod.ROPE_PER_DEVICE["cuda"](a, f))(x, freqs)
+ out = torch.compile(lambda a, f: _call(_rope(), a, f))(x, freqs)
assert torch.equal(out, ref)
# Eager calls keep the stock complex path.
- assert torch.equal(patched(x, freqs), ref)
+ assert torch.equal(_call(patched, x, freqs), ref)
qr.uninstall()
- assert qmod.ROPE_PER_DEVICE["cuda"] is stock
+ assert _rope() is stock
def _fake_probe(monkeypatch):
@@ -89,9 +118,9 @@ class QwenImageTransformer2DModel(torch.nn.Module):
@pytest.mark.parametrize("env", [qr.QWEN_REAL_ROPE_ENV, q21.REAL_ROPE_ENV])
def test_kill_switch_on_a_later_load_restores_the_table(monkeypatch, env):
_fake_probe(monkeypatch)
- stock = qmod.ROPE_PER_DEVICE["cuda"]
+ stock = _rope()
assert qr._patch_table(0)
- assert qmod.ROPE_PER_DEVICE["cuda"] is not stock
+ assert _rope() is not stock
monkeypatch.setenv(env, "0")
assert qr.install(QwenImageTransformer2DModel()) is False
- assert qmod.ROPE_PER_DEVICE["cuda"] is stock
+ assert _rope() is stock
diff --git a/studio/backend/tests/test_diffusion_te_int8_convrot.py b/studio/backend/tests/test_diffusion_te_int8_convrot.py
index b5cb2e94fcc..a9d2e9abab5 100644
--- a/studio/backend/tests/test_diffusion_te_int8_convrot.py
+++ b/studio/backend/tests/test_diffusion_te_int8_convrot.py
@@ -487,3 +487,56 @@ def test_keep_lm_head_reason_names_the_switch(monkeypatch):
_pipe(torch.nn.Linear(2, 2)), CUDA_BF16, mode = "int8", family = "qwen-image-2.1"
)
assert out.mode == "fp8" and KEEP_LM_HEAD_ENV in out.reason
+
+
+def _te_gate_mps(monkeypatch, family, te_mode):
+ import core.inference.diffusion as d
+ from core.inference.diffusion_families import _FAMILIES
+
+ monkeypatch.delenv("UNSLOTH_TE_KEEP_LM_HEAD", raising = False)
+ fam = next(f for f in _FAMILIES if f.name == family)
+ d.DiffusionBackend._assert_precision_for_target(
+ None,
+ fam,
+ types.SimpleNamespace(device = "mps", dtype = torch.bfloat16),
+ model_kind = "pipeline",
+ pinned = None,
+ te_mode = te_mode,
+ memory_mode = None,
+ cpu_offload = False,
+ )
+
+
[email protected]("family", ["flux.3-klein", "flux.3-klein-base", "qwen-image-2.1"])
+def test_preflight_admits_the_hosted_int8_encoder_on_mps(monkeypatch, family):
+ # effective_te_quant rewrites int8 to fp8 on a family with no keep-bf16 schedule, and MPS has no fp8, but these
+ # families host a plain-tensor int8 ConvRot file that int8_convrot_te_runs_on enables there.
+ _te_gate_mps(monkeypatch, family, "int8")
+
+
+def test_preflight_still_refuses_int8_on_mps_without_a_hosted_file(monkeypatch):
+ with pytest.raises(RuntimeError, match = "text_encoder_quant"):
+ _te_gate_mps(monkeypatch, "flux.2-klein", "int8")
+ with pytest.raises(RuntimeError, match = "text_encoder_quant"):
+ _te_gate_mps(monkeypatch, "flux.3-klein", "fp8")
+
+
+def test_preflight_refuses_int8_on_mps_when_the_lm_head_is_kept(monkeypatch):
+ # UNSLOTH_TE_KEEP_LM_HEAD resolves int8 to the fp8 file, which MPS cannot run.
+ import core.inference.diffusion as d
+ from core.inference.diffusion_families import _FAMILIES
+ from core.inference.diffusion_text_encoder_trim import KEEP_LM_HEAD_ENV
+
+ monkeypatch.setenv(KEEP_LM_HEAD_ENV, "1")
+ fam = next(f for f in _FAMILIES if f.name == "flux.3-klein")
+ with pytest.raises(RuntimeError, match = "text_encoder_quant"):
+ d.DiffusionBackend._assert_precision_for_target(
+ None,
+ fam,
+ types.SimpleNamespace(device = "mps", dtype = torch.bfloat16),
+ model_kind = "pipeline",
+ pinned = None,
+ te_mode = "int8",
+ memory_mode = None,
+ cpu_offload = False,
+ )
diff --git a/studio/backend/utils/diffusers_repair.py b/studio/backend/utils/diffusers_repair.py
index 5a08fdf5238..85e17633cc9 100644
--- a/studio/backend/utils/diffusers_repair.py
+++ b/studio/backend/utils/diffusers_repair.py
@@ -33,8 +33,8 @@ _REPAIR_TIMEOUT_S = 120
_INSTALL_MIN_TIMEOUT_S = 30
# The installer's exit codes for --repair-diffusers-main.
_INSTALLED, _NOTHING_TO_DO = 0, 1
-# The installer's DIFFUSERS_MAIN_MIN_PYTHON: diffusers main needs 3.10, and 3.9 stays supported.
-_MAIN_MIN_PYTHON = (3, 10)
+# The installer's DIFFUSERS_MAIN_MIN_PYTHON: diffusers main needs 3.11, and 3.9 / 3.10 stay supported.
+_MAIN_MIN_PYTHON = (3, 11)
# Unattended, so secrets and index redirects stay out, as in mlx_repair. The Windows names are what
# Python, git and uv need to start at all there; UV_OFFLINE is the operator's no-network switch.
diff --git a/studio/frontend/src/features/images/api.ts b/studio/frontend/src/features/images/api.ts
index db38e6ecdb1..cd6a6f4da10 100644
--- a/studio/frontend/src/features/images/api.ts
+++ b/studio/frontend/src/features/images/api.ts
@@ -34,6 +34,8 @@ export interface DiffusionStatus {
display_repo_id?: string | null;
family: string | null;
supported_families?: string[];
+ // Of those, the families shipped as Modular Diffusers pipelines (the family override classes an opaque folder).
+ modular_families?: string[];
base_repo: string | null;
device: string | null;
dtype: string | null;
diff --git a/studio/frontend/src/features/images/image-generation-defaults.ts b/studio/frontend/src/features/images/image-generation-defaults.ts
index 836ccc43239..a5c218a0a5b 100644
--- a/studio/frontend/src/features/images/image-generation-defaults.ts
+++ b/studio/frontend/src/features/images/image-generation-defaults.ts
@@ -20,6 +20,17 @@ const MODEL_DEFAULTS: Array<{
{ match: "kontext", steps: 20, guidance: 2.5 },
{ match: "flux.1-krea", steps: 20, guidance: 3.5 },
{ match: "flux.1", steps: 20, guidance: 3.5 },
+ // FLUX.3 Image Klein (ComfyUI templates, the BFL reference): base 50 steps at CFG 3.5, distilled 16 steps without CFG. Base first.
+ // Every alias the backend registers for the two families, and the canonical family names (an opaque path
+ // resolves through the explicit family).
+ { match: "flux.3-klein-base", steps: 50, guidance: 3.5 },
+ { match: "flux-3-image-klein-base", steps: 50, guidance: 3.5 },
+ { match: "flux3-image-klein-base", steps: 50, guidance: 3.5 },
+ { match: "flux3-klein-base", steps: 50, guidance: 3.5 },
+ { match: "flux.3-klein", steps: 16, guidance: 1 },
+ { match: "flux-3-image-klein", steps: 16, guidance: 1 },
+ { match: "flux3-image-klein", steps: 16, guidance: 1 },
+ { match: "flux3-klein", steps: 16, guidance: 1 },
// Klein base is undistilled. The generic key below covers both distilled sizes.
{ match: "flux.2-klein-base", steps: 20, guidance: 5 },
{ match: "flux.2-klein", steps: 4, guidance: 1 },
@@ -69,9 +80,15 @@ export function defaultsFor(repoId: string): {
: DEFAULT_GEN;
}
+// Families whose explicit choice outranks the name: FLUX.3 base and distilled share names (BFL's ComfyUI base
+// files are flux3_image_klein_*.safetensors), and the backend refuses a checkpoint of the other variant.
+const FAMILY_NAMES_THE_VARIANT = new Set(["flux.3-klein", "flux.3-klein-base"]);
+
/** A recognizable variant (Schnell vs Dev) keeps its own key; an explicit family keys only an opaque path. */
export function defaultsKeyFor(repoId: string, familyOverride: unknown): string {
- return defaultsFor(repoId) !== DEFAULT_GEN ? repoId : (explicitFamily(familyOverride) ?? repoId);
+ const family = explicitFamily(familyOverride);
+ if (family && FAMILY_NAMES_THE_VARIANT.has(family)) return family;
+ return defaultsFor(repoId) !== DEFAULT_GEN ? repoId : (family ?? repoId);
}
/** The loaded model's recipe for a pick that got the fallback (its name named no family), else null. */
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/family-override.ts b/studio/frontend/src/features/model-picker/components/model-selector/family-override.ts
index 965966ff5ae..669e4dcaaa3 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/family-override.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/family-override.ts
@@ -9,6 +9,8 @@ const LABELS: Readonly<Record<string, string>> = {
"flux.1": "FLUX.1",
"flux.2-klein": "FLUX.2 Klein",
"flux.2-dev": "FLUX.2 Dev",
+ "flux.3-klein": "FLUX.3 Klein",
+ "flux.3-klein-base": "FLUX.3 Klein Base",
"flux.1-kontext": "FLUX.1 Kontext",
"qwen-image": "Qwen Image",
"qwen-image-2.1": "Qwen Image 2.1",
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts
index 9c4958376ea..96a95df3fcc 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts
@@ -296,6 +296,8 @@ for (const id of [
"unsloth/FLUX.1-dev-GGUF",
"unsloth/FLUX.2-klein-4B-GGUF",
"unsloth/FLUX.2-klein-9B-GGUF",
+ "unsloth/flux-3-image-klein-GGUF",
+ "unsloth/flux-3-image-klein-base-GGUF",
"unsloth/Qwen-Image-Edit-2511-GGUF",
"unsloth/FLUX.1-Kontext-dev-GGUF",
...Object.keys(OLD_SAFETENSORS_MODELS),
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
index a9a0e28f2e3..d810ac3aa20 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
@@ -358,6 +358,23 @@ export const IMAGE_CATALOG: CatalogGroup[] = [
scope: "image",
artifacts: [gguf("unsloth/FLUX.2-klein-9B-GGUF")],
},
+ {
+ // FLUX.3 Image Klein (distilled): text to image and up to 10 reference images. The GGUFs pair with the
+ // official repo for the Qwen3-VL text encoder and the FLUX.2 VAE.
+ canonicalId: "black-forest-labs/flux-3-image-klein",
+ displayName: "FLUX.3 Image Klein",
+ description: "Text-to-image and image editing",
+ scope: "image",
+ artifacts: [gguf("unsloth/flux-3-image-klein-GGUF")],
+ },
+ {
+ // The undistilled checkpoint (CFG, more steps); same companions from its own official repo.
+ canonicalId: "black-forest-labs/flux-3-image-klein-base",
+ displayName: "FLUX.3 Image Klein Base",
+ description: "Text-to-image and image editing",
+ scope: "image",
+ artifacts: [gguf("unsloth/flux-3-image-klein-base-GGUF")],
+ },
{
canonicalId: "unsloth/Qwen-Image-Edit-2511",
displayName: "Qwen-Image-Edit 2511",
diff --git a/studio/frontend/tests/image-generation-defaults.test.ts b/studio/frontend/tests/image-generation-defaults.test.ts
index 73924ff0031..94de56502d9 100644
--- a/studio/frontend/tests/image-generation-defaults.test.ts
+++ b/studio/frontend/tests/image-generation-defaults.test.ts
@@ -255,3 +255,51 @@ test("the Images page seeds Default from the resident recipe and drops the pick
const revert = src.slice(src.indexOf("const revertPick = useCallback"), src.indexOf("}, []);", src.indexOf("const revertPick = useCallback")));
assert.match(revert, /pickDefaults\.current = null/);
});
+
+test("every FLUX.3 Klein alias the backend registers gets its family recipe", () => {
+ for (const id of [
+ "black-forest-labs/flux-3-image-klein-base",
+ "someone/flux3-image-klein-base-finetune",
+ "someone/flux3_image_klein_base",
+ "someone/flux3-klein-base-merge",
+ "flux.3-klein-base",
+ ]) {
+ assert.deepEqual(defaultsFor(id), { steps: 50, guidance: 3.5 }, id);
+ }
+ for (const id of [
+ "black-forest-labs/flux-3-image-klein",
+ "someone/flux3-image-klein-finetune",
+ "someone/flux3_image_klein",
+ "someone/flux3-klein-lora-merge",
+ "flux.3-klein",
+ ]) {
+ assert.deepEqual(defaultsFor(id), { steps: 16, guidance: 1 }, id);
+ }
+});
+
+test("an opaque FLUX.3 path keys its defaults by the explicit family", () => {
+ for (const [family, want] of [
+ ["flux.3-klein", { steps: 16, guidance: 1 }],
+ ["flux.3-klein-base", { steps: 50, guidance: 3.5 }],
+ ] as const) {
+ const key = defaultsKeyFor("/models/my-model", family);
+ assert.equal(key, family);
+ assert.deepEqual(defaultsFor(key), want);
+ }
+});
+
+test("an explicit FLUX.3 family decides the recipe over a name that reads as the other variant", () => {
+ // BFL's ComfyUI base file has no "base" in its name; the backend checks it against the family.
+ const comfyBase = "black-forest-labs/flux-3-image-klein-comfy";
+ assert.equal(defaultsKeyFor(comfyBase, "flux.3-klein-base"), "flux.3-klein-base");
+ assert.deepEqual(defaultsFor(defaultsKeyFor(comfyBase, "flux.3-klein-base")), { steps: 50, guidance: 3.5 });
+ assert.deepEqual(defaultsFor(defaultsKeyFor(comfyBase, "flux.3-klein")), { steps: 16, guidance: 1 });
+ assert.deepEqual(defaultsFor(defaultsKeyFor(comfyBase, "auto")), { steps: 16, guidance: 1 });
+ assert.equal(
+ residentDefaultsKey("/models/flux3_image_klein_bf16.safetensors", "black-forest-labs/flux-3-image-klein", {
+ value: "flux.3-klein-base",
+ source: "explicit",
+ }),
+ "flux.3-klein-base",
+ );
+});
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index d0b4e6f4932..40470e75d54 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -11682,9 +11682,10 @@ def _triton_kernels_step() -> None:
DIFFUSERS_MAIN_ENV = "UNSLOTH_DIFFUSERS_MAIN"
-# Diffusers main declares requires-python >= 3.10 while the release pin file still names 0.36.0
-# for anything older, so 3.9 is a supported install this step can never satisfy.
-DIFFUSERS_MAIN_MIN_PYTHON = (3, 10)
+# Diffusers main declares requires-python >= 3.11 (huggingface/diffusers#15030) while the release
+# pin covers 3.10 (0.41.0) and 3.9 (0.36.0), so both are supported installs this step can never
+# satisfy. They keep the release and only a model that needs the main build is unavailable.
+DIFFUSERS_MAIN_MIN_PYTHON = (3, 11)
def _diffusers_main_requested() -> bool:
@@ -12027,11 +12028,11 @@ def _diffusers_main_step() -> None:
_progress("diffusers main (opted out, skipped)")
return
if sys.version_info < DIFFUSERS_MAIN_MIN_PYTHON:
- # Diffusers main needs 3.10, and the release pin file still carries a 0.36.0 line for
- # older interpreters, so 3.9 is a supported path this can never satisfy. Unmarked, pip would
- # clone the repository and only then reject its requires-python, and since the build can
- # never become resident that clone repeats on every install and update forever.
- _progress("diffusers main (skipped, needs python 3.10)")
+ # Diffusers main needs 3.11, and the release pin covers 3.10 and 3.9, so those are supported
+ # paths this can never satisfy. Unmarked, pip would clone the repository and only then reject
+ # its requires-python, and since the build can never become resident that clone repeats on
+ # every install and update forever.
+ _progress("diffusers main (skipped, needs python 3.11)")
return
req = REQ_ROOT / "diffusers-main.txt"
if not req.is_file():
diff --git a/tests/sh/test_clean_machine_notools_pinned_git.sh b/tests/sh/test_clean_machine_notools_pinned_git.sh
index 37b66a04ac5..f49c7cfd348 100755
--- a/tests/sh/test_clean_machine_notools_pinned_git.sh
+++ b/tests/sh/test_clean_machine_notools_pinned_git.sh
@@ -11,8 +11,8 @@ ASSERT_SH="$REPO_ROOT/.github/scripts/clean-machine-assert.sh"
SHIPPED_PIN="$REPO_ROOT/studio/backend/requirements/diffusers-main.txt"
ROOT=$(mktemp -d)
trap 'rm -rf "$ROOT"' EXIT
-# The shipped pin is commented out while a Diffusers release carries every family, so the
-# allowance is exercised on the same file with its requirement line uncommented.
+# The shipped pin is commented out whenever a Diffusers release carries every family, so the
+# allowance is exercised on the same file with its requirement line uncommented (a no-op when active).
PIN="$ROOT/diffusers-main.txt"
sed 's/^# diffusers @ git+/diffusers @ git+/' "$SHIPPED_PIN" > "$PIN"
PASS=0
@@ -70,7 +70,9 @@ expect_rc "uv cloning the pinned Diffusers build passes" 0 "$PIN" "$UV_CLONE"
expect_rc "the same trace fails with no allowance, as before" 1 "" "$UV_CLONE"
expect_rc "an allowance file that does not exist allows nothing" 1 "$ROOT/missing.txt" "$UV_CLONE"
expect_rc "the installer's git --version probe alone passes" 0 "$PIN" "git\t--version\n"
-expect_rc "the shipped, commented-out pin allows no clone" 1 "$SHIPPED_PIN" "$UV_CLONE"
+COMMENTED_PIN="$ROOT/commented-diffusers-main.txt"
+sed 's/^diffusers @ git+/# diffusers @ git+/' "$SHIPPED_PIN" > "$COMMENTED_PIN"
+expect_rc "a commented-out pin allows no clone" 1 "$COMMENTED_PIN" "$UV_CLONE"
# An overlay-free leg installs the released wheel, which can pin an older commit than this
# checkout's file; uv's checkout is named after the commit it installs.
OLDER=1111111111111111111111111111111111111111
diff --git a/tests/studio/install/test_diffusers_pin.py b/tests/studio/install/test_diffusers_pin.py
index e242386e656..35ef3a05ca5 100644
--- a/tests/studio/install/test_diffusers_pin.py
+++ b/tests/studio/install/test_diffusers_pin.py
@@ -36,7 +36,15 @@ def _active_req_root(tmp_path_factory):
main = root / "diffusers-main.txt"
text = main.read_text(encoding = "utf-8")
main.write_text(text.replace("\n# diffusers @ git+", "\ndiffusers @ git+"), encoding = "utf-8")
- _ACTIVE_REQ_ROOT[:] = [root]
+ # Release-mode tests run on a copy with the commit line commented out, whichever state ships.
+ inactive = tmp_path_factory.mktemp("inactive_main") / "requirements"
+ shutil.copytree(REQ_ROOT, inactive)
+ off = inactive / "diffusers-main.txt"
+ off.write_text(
+ off.read_text(encoding = "utf-8").replace("\ndiffusers @ git+", "\n# diffusers @ git+"),
+ encoding = "utf-8",
+ )
+ _ACTIVE_REQ_ROOT[:] = [root, inactive]
yield root
@@ -132,26 +140,57 @@ def test_the_main_build_pins_a_commit_and_runs_after_the_release():
assert source.index(call) > source.rindex('req = REQ_ROOT / "diffusers-pin.txt"')
-def test_the_shipped_main_build_is_commented_out_but_keeps_its_commit():
- """0.41.0 is on PyPI: nothing installs from git, and re-enabling is one uncomment away."""
- assert _requirements(MAIN_FILE) == []
+def test_the_shipped_main_build_is_active_with_a_digest():
+ """FLUX.3 Klein (huggingface/diffusers#15046, merged 2026-10-15) is in no release, so the pinned build ships active."""
+ lines = _requirements(MAIN_FILE)
+ assert len(lines) == 1 and re.fullmatch(
+ r"diffusers @ git\+https://\S+@[0-9a-f]{40}", lines[0]
+ ), lines
text = MAIN_FILE.read_text(encoding = "utf-8")
- assert re.search(r"^# diffusers @ git\+https://\S+@[0-9a-f]{40}$", text, re.M), text
- assert re.search(r"^# archive-sha256: [0-9a-f]{64}$", text, re.M)
- module = _probe_module("install_python_stack_probe_shipped", active = False)
+ assert len(re.findall(r"^# archive-sha256: [0-9a-f]{64}$", text, re.M)) == 1
+ module = _probe_module("install_python_stack_probe_shipped", shipped = True)
+ assert module._diffusers_main_active() is True
+
+
+def test_the_flux3_pin_is_main_with_the_merged_flux3_support():
+ """huggingface/diffusers#15046 merged on 2026-10-15 (7ecb1e1b4); the pin is main at d42ebf9c (2026-10-16, the
+ prompt upsampler block #15058), which carries it, with that commit's archive digest, not the PR branch head."""
+ text = MAIN_FILE.read_text(encoding = "utf-8")
+ (line,) = _requirements(MAIN_FILE)
+ assert line.endswith("@d42ebf9c6e0b46103b74283f5324357a67acaa04"), line
+ assert "ec288418a5efa32e9fd49eb7b193babce920a106" not in line
+ assert re.search(
+ r"^# archive-sha256: c46925a12c1b64340272dbd4c5d72a4298ecd4c96cad2c9d549b85a99ffb491f$",
+ text,
+ re.M,
+ )
+
+
+def test_the_release_mode_copy_is_commented_out_but_keeps_its_commit():
+ """Release mode (the state after a pin retires) is one comment away, and the probes read it as off."""
+ off = _ACTIVE_REQ_ROOT[1] / "diffusers-main.txt"
+ assert _requirements(off) == []
+ assert re.search(
+ r"^# diffusers @ git\+https://\S+@[0-9a-f]{40}$", off.read_text(encoding = "utf-8"), re.M
+ )
+ module = _probe_module("install_python_stack_probe_inactive", active = False)
assert module._diffusers_main_active() is False
assert module._diffusers_main_resident() is False
assert module._diffusers_main_supersedes_release() is False
-def _probe_module(name: str, active: bool = True):
+def _probe_module(
+ name: str,
+ active: bool = True,
+ shipped: bool = False,
+):
import importlib.util
spec = importlib.util.spec_from_file_location(name, STACK)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
- if active:
- module.REQ_ROOT = _ACTIVE_REQ_ROOT[0]
+ if not shipped:
+ module.REQ_ROOT = _ACTIVE_REQ_ROOT[0] if active else _ACTIVE_REQ_ROOT[1]
return module
@@ -589,14 +628,17 @@ def test_a_damaged_main_build_is_repaired_rather_than_believed(monkeypatch):
assert attempted and attempted[0].name == "diffusers-main.txt"
-def test_python_39_does_not_clone_a_build_it_can_never_install(monkeypatch):
- """diffusers-pin.txt still names 0.36.0 below 3.10, so 3.9 is a supported install, and main
- declares requires-python >= 3.10. Unmarked, pip clones the repository and only then rejects
[email protected]("old_python", [(3, 9, 21), (3, 10, 14)])
+def test_python_below_311_does_not_clone_a_build_it_can_never_install(monkeypatch, old_python):
+ """diffusers-pin.txt covers 3.9 (0.36.0) and 3.10 (0.41.0), and main declares requires-python
+ >= 3.11 (huggingface/diffusers#15030). Unmarked, pip clones the repository and only then rejects
it, and since the build can never become resident that clone repeats on every update."""
module = _probe_module("install_python_stack_probe8")
monkeypatch.delenv("UNSLOTH_DIFFUSERS_MAIN", raising = False)
monkeypatch.setattr(
- module, "pip_install_try", lambda *a, **k: pytest.fail("cloned main on python 3.9")
+ module,
+ "pip_install_try",
+ lambda *a, **k: pytest.fail(f"cloned main on python {old_python}"),
)
monkeypatch.setattr(module, "_has_working_git", lambda: True)
monkeypatch.setattr(module, "_note", lambda *a, **k: None)
@@ -604,17 +646,17 @@ def test_python_39_does_not_clone_a_build_it_can_never_install(monkeypatch):
class _V(tuple):
pass
- monkeypatch.setattr(module.sys, "version_info", _V((3, 9, 21)))
+ monkeypatch.setattr(module.sys, "version_info", _V(old_python))
progressed: list = []
monkeypatch.setattr(module, "_progress", lambda label, *a, **k: progressed.append(label))
module._diffusers_main_step()
- assert len(progressed) == 1 and "python 3.10" in progressed[0], progressed
+ assert len(progressed) == 1 and "python 3.11" in progressed[0], progressed
monkeypatch.setattr(module, "_direct_reference_is_installed", lambda *a, **k: False)
assert not (module._diffusers_main_requested() and module._diffusers_main_resident())
attempted: list = []
- monkeypatch.setattr(module.sys, "version_info", _V((3, 10, 0)))
+ monkeypatch.setattr(module.sys, "version_info", _V((3, 11, 0)))
monkeypatch.setattr(module, "_payload_recorded_intact", lambda *a, **k: False)
monkeypatch.setattr(
module, "pip_install_try", lambda *a, req = None, **k: (attempted.append(req), True)[1]