Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: 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.pyindex 82d5db085c5..42b90988391 100644--- a/studio/backend/core/inference/diffusion.py+++ b/studio/backend/core/inference/diffusion.py@@ -32,7 +32,7 @@ import timeimport tracebackfrom dataclasses import dataclass, replacefrom pathlib import Path-from typing import Any, Callable, Optional, Sequence+from typing import Any, Callable, Mapping, Optional, Sequencefrom 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_AREAfrom .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, elseNone.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 evictionif (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 adiffusers 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 Diffuserspipeline (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 pathif 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 isschnell), 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 lookupreturn Nonereturn {"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 = Noneif 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 assemblefrom, 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(ffor 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_bytesif 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-effortlogger.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 = Noneif (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 = 0if gguf_filename:@@ -5827,8 +5960,10 @@ class DiffusionBackend:continueif 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())):continuetry:@@ -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 = planself._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_diror (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] = Noneif 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 pipeif 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 = Noneguard_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 bythe 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 sitshort 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_transformerif "/" not in rfilename: # top-level: only the pipeline manifest is fetched- return rfilename == "model_index.json"+ return rfilename == manifestreturn 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 areartifacts the torch loader never touches (ONNX / OpenVINO / Flax exports and dtype-varianttwins), 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_COMPONENTSif 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 = selectionif rfilename in ignored:return False- if rfilename == "model_index.json":+ if rfilename in ("model_index.json", FLUX3_INDEX):return Trueif "/" not in rfilename or rfilename.split("/", 1)[0] not in components:return Falsediff --git a/studio/backend/core/inference/diffusion_auto_policy.py b/studio/backend/core/inference/diffusion_auto_policy.pyindex 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.pyindex 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"]), sfmreturn 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.pyindex 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.pyindex 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_reasonout["mlx_fallback_reason"] = _mlx_fallback_reasonout["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 outdiff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.pyindex d14237c76c3..22eb86f4f4e 100644--- a/studio/backend/core/inference/diffusion_families.py+++ b/studio/backend/core/inference/diffusion_families.py@@ -18,7 +18,7 @@ import sysimport tempfilefrom dataclasses import dataclass, fieldfrom pathlib import Path, PurePosixPath-from typing import Any, NamedTuple, Optional, Sequence+from typing import Any, Iterable, Mapping, NamedTuple, Optional, Sequencefrom utils.paths.path_utils import is_appledouble_metadatafrom .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[Difffor kw in _EDIT_KEYWORDS):return None+ if any(+ _token_in_needle(kw, basename) for kw in _NON_IMAGE_SIBLING_KEYWORDS.get(match.name, ())+ ):+ return Nonereturn matchreturn 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[floareturn 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 overridesdef _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 Falsebase = 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 Falsecaller_supplied = _CALLER_SUPPLIED_COMPONENTS.get(class_name, frozenset())declared = Falsetry:@@ -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) -> sf"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_fileif "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 thewhole 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 verdictreturn Nonefinally:@@ -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 absolutepaths and ``..`` escapes."""diff --git a/studio/backend/core/inference/diffusion_flux3.py b/studio/backend/core/inference/diffusion_flux3.pynew file mode 100644index 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.pyindex 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 = 256MEASURED_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.pyindex 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.pyindex 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.pyindex 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.pyindex 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 AnyQWEN_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 formdef disabled() -> bool:@@ -41,6 +49,8 @@ def _patch_table(index: int, logger: Any = None) -> bool:return Falsemod = 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 Noneif 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.pyindex 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.0if _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 pipelineassembly 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-behaviourflags 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 torchfrom 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.pyindex 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.pyindex 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) -> tupreturn _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 theoffline 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.pyindex 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] = Nonediff --git a/studio/backend/core/inference/media_auto_switch.py b/studio/backend/core/inference/media_auto_switch.pyindex 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_overridefrom models.inference import DiffusionLoadRequestfrom 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.pyindex 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 Falseif 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+ continuefor 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 = Nonelocal_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 = Falseif 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.pyindex 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.txtindex 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@d42ebf9c6e0b46103b74283f5324357a67acaa04diff --git a/studio/backend/tests/fixtures/diffusion_autoopt_parity.json b/studio/backend/tests/fixtures/diffusion_autoopt_parity.jsonindex 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.jsonindex 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.jsonindex 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.pyindex 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.versionmonkeypatch.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.pyindex 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_beforegot = 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.pyindex 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) == 27for upstream, mirror in _MIRROR_PAIRS:assert mirror_repo(upstream) == mirrorassert 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, whichis mirrored, and which the Hub serves anonymously."""- assert len(_GATED_MIRROR_PAIRS) == 12+ assert len(_GATED_MIRROR_PAIRS) == 14assert len(_UNGATED_MIRROR_PAIRS) == 13for upstream, _mirror in _GATED_MIRROR_PAIRS:assert upstream_is_gated(upstream), upstreamdiff --git a/studio/backend/tests/test_diffusion_flux3.py b/studio/backend/tests/test_diffusion_flux3.pynew file mode 100644index 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] == upstreamdiff --git a/studio/backend/tests/test_diffusion_flux3_te_prequant.py b/studio/backend/tests/test_diffusion_flux3_te_prequant.pynew file mode 100644index 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.pyindex 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, decgot = 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.pyindex 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 stockdef test_disabled_and_other_models_are_noops(monkeypatch):@@ -45,22 +74,22 @@ def test_disabled_and_other_models_are_noops(monkeypatch):@needs_cudadef 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 stockg = 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.28freqs = 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 stockdef _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 stockmonkeypatch.setenv(env, "0")assert qr.install(QwenImageTransformer2DModel()) is False- assert qmod.ROPE_PER_DEVICE["cuda"] is stock+ assert _rope() is stockdiff --git a/studio/backend/tests/test_diffusion_te_int8_convrot.py b/studio/backend/tests/test_diffusion_te_int8_convrot.pyindex 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.pyindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 pickconst 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.pyindex 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)")returnif 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)")returnreq = 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.shindex 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=1111111111111111111111111111111111111111diff --git a/tests/studio/install/test_diffusers_pin.py b/tests/studio/install/test_diffusers_pin.pyindex 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]+ ), linestext = 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 Falseassert module._diffusers_main_resident() is Falseassert 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.utilspec = 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 rejectsit, 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], progressedmonkeypatch.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]