PTQ-Level Efficiency, QAT-Level Accuracy | 训练后量化的效率,量化感知训练的精度
# Copyright (c) 2026 Intel Corporation
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""FLUX model mapping for runtime-loadable SVDQuant Nunchaku artifacts."""
from __future__ import annotations
import json
import os
import re
from collections.abc import Iterable, Mapping
from dataclasses import dataclass
from typing import Any
import torch
from auto_round.export.svdquant_nunchaku import SourceLinearRecord, SVDQuantExportRecord
from auto_round.export.svdquant_w4a16 import quantize_adanorm_w4a16_rtn
_BLOCK_RE = re.compile(r"^(transformer_blocks|single_transformer_blocks)\.(\d+)\.(.+)$")
_DOUBLE_DIRECT = {
"attn.to_out.0": "out_proj",
"attn.to_add_out": "out_proj_context",
"ff.net.0.proj": "mlp_fc1",
"ff.net.2": "mlp_fc2",
"ff.net.2.linear": "mlp_fc2",
"ff_context.net.0.proj": "mlp_context_fc1",
"ff_context.net.2": "mlp_context_fc2",
"ff_context.net.2.linear": "mlp_context_fc2",
}
_DOUBLE_FUSED = {
"qkv_proj": ("attn.to_q", "attn.to_k", "attn.to_v"),
"qkv_proj_context": ("attn.add_q_proj", "attn.add_k_proj", "attn.add_v_proj"),
}
_SINGLE_FUSED = {"qkv_proj": ("attn.to_q", "attn.to_k", "attn.to_v")}
_RMS_MAP = {
"attn.norm_q": "norm_q",
"attn.norm_k": "norm_k",
"attn.norm_added_q": "norm_added_q",
"attn.norm_added_k": "norm_added_k",
}
_TOP_LEVEL_PREFIXES = ("x_embedder.", "context_embedder.", "time_text_embed.", "norm_out.linear.", "proj_out.")
FLUX_SVDQUANT_TARGET_MODULES = (
"attn.to_q",
"attn.to_k",
"attn.to_v",
"attn.add_q_proj",
"attn.add_k_proj",
"attn.add_v_proj",
"attn.to_out.0",
"attn.to_add_out",
"ff.net.0.proj",
"ff.net.2",
"ff_context.net.0.proj",
"ff_context.net.2",
"proj_mlp",
"proj_out",
)
FLUX_TOP_LEVEL_TENSOR_KEYS = frozenset(
{
"x_embedder.weight",
"x_embedder.bias",
"context_embedder.weight",
"context_embedder.bias",
"norm_out.linear.weight",
"norm_out.linear.bias",
"proj_out.weight",
"proj_out.bias",
*(
f"time_text_embed.{embedder}_embedder.linear_{linear}.{parameter}"
for embedder in ("timestep", "text", "guidance")
for linear in (1, 2)
for parameter in ("weight", "bias")
),
}
)
def flux_onefile_tensor_count(
num_layers: int, num_single_layers: int, top_level_tensors: int = len(FLUX_TOP_LEVEL_TENSOR_KEYS)
) -> int:
"""Return the key count without constructing model-sized tensors."""
return num_layers * (8 * 7 + 2 * 4 + 4) + num_single_layers * (4 * 7 + 4 + 2) + top_level_tensors
def _config_dict(value: Any) -> dict[str, Any]:
if isinstance(value, Mapping):
return dict(value)
to_dict = getattr(value, "to_dict", None)
if callable(to_dict):
result = to_dict()
if isinstance(result, Mapping):
return dict(result)
if hasattr(value, "__dict__"):
return {key: item for key, item in vars(value).items() if not key.startswith("_")}
raise ValueError("FLUX config must be a mapping or serialize to a JSON object")
def _normalize_config_paths(value: Any) -> Any:
if isinstance(value, os.PathLike):
return os.fspath(value)
if isinstance(value, Mapping):
return {key: _normalize_config_paths(item) for key, item in value.items()}
if isinstance(value, list):
return [_normalize_config_paths(item) for item in value]
if isinstance(value, tuple):
return tuple(_normalize_config_paths(item) for item in value)
return value
def _effective_weight(source: SourceLinearRecord, device: torch.device) -> torch.Tensor:
if source.residual_weight.ndim != 2 or source.lora_down.ndim != 2 or source.lora_up.ndim != 2:
raise ValueError(f"{source.name} residual and low-rank weights must be 2D")
out_features, in_features = source.residual_weight.shape
rank = source.lora_down.shape[0]
if (
source.lora_down.shape != (rank, in_features)
or source.lora_up.shape != (out_features, rank)
or source.smooth.shape != (in_features,)
):
raise ValueError(f"{source.name} source dimensions are inconsistent")
residual = source.residual_weight.detach().to(device=device, dtype=torch.float32)
up = source.lora_up.detach().to(device=device, dtype=torch.float32)
down = source.lora_down.detach().to(device=device, dtype=torch.float32)
smooth = source.smooth.detach().to(device=device, dtype=torch.float32)
return (residual + up @ down) * smooth.reshape(1, -1)
def _has_shared_input_decomposition(sources: tuple[SourceLinearRecord, ...]) -> bool:
first = sources[0]
return all(
source.scheme == first.scheme
and torch.equal(source.lora_down, first.lora_down)
and torch.equal(source.smooth, first.smooth)
and torch.equal(source.smooth_orig, first.smooth_orig)
for source in sources[1:]
)
def _concatenate_shared_sources(
prefix: str,
sources: tuple[SourceLinearRecord, ...],
) -> SVDQuantExportRecord:
first = sources[0]
biases = [source.bias for source in sources]
if any(bias is None for bias in biases) and not all(bias is None for bias in biases):
raise ValueError(f"{prefix} fused sources must either all have bias or all omit bias")
bias = None if biases[0] is None else torch.cat(biases).detach().cpu().contiguous()
return SVDQuantExportRecord(
prefix=prefix,
residual_weight=torch.cat([source.residual_weight for source in sources]).detach().cpu().contiguous(),
lora_down=first.lora_down.detach().cpu().contiguous(),
lora_up=torch.cat([source.lora_up for source in sources]).detach().cpu().contiguous(),
smooth=first.smooth.detach().cpu().contiguous(),
smooth_orig=first.smooth_orig.detach().cpu().contiguous(),
bias=bias,
scheme=first.scheme,
sources=sources,
)
def _decompose(
weight: torch.Tensor,
*,
rank: int,
template: SourceLinearRecord,
prefix: str,
sources: tuple[SourceLinearRecord, ...],
bias: torch.Tensor | None,
) -> SVDQuantExportRecord:
if rank > min(weight.shape):
raise ValueError(f"{prefix} configured rank={rank} exceeds fused dimensions {tuple(weight.shape)}")
if not bool(torch.isfinite(weight).all()):
raise ValueError(f"{prefix} effective weight contains non-finite values")
u, singular_values, vh = torch.linalg.svd(weight, full_matrices=False)
up = u[:, :rank] * singular_values[:rank]
down = vh[:rank]
residual = weight - up @ down
weight_dtype = template.residual_weight.dtype
low_rank_dtype = template.lora_down.dtype
in_features = weight.shape[1]
record = SVDQuantExportRecord(
prefix=prefix,
residual_weight=residual.to(dtype=weight_dtype).cpu().contiguous(),
lora_down=down.to(dtype=low_rank_dtype).cpu().contiguous(),
lora_up=up.to(dtype=template.lora_up.dtype).cpu().contiguous(),
smooth=torch.ones(in_features, dtype=template.smooth.dtype).cpu(),
smooth_orig=torch.ones(in_features, dtype=template.smooth_orig.dtype).cpu(),
bias=None if bias is None else bias.detach().to(dtype=weight_dtype).cpu().contiguous(),
scheme=template.scheme,
sources=sources,
)
del u, singular_values, vh, up, down, residual, weight
return record
@dataclass
class FluxSVDQuantNunchakuAdapter:
"""Map Diffusers FLUX modules to the Nunchaku one-file tensor schema."""
config: Mapping[str, Any] | None = None
decomposition_device: str | torch.device = "cpu"
require_complete_model: bool = True
def __post_init__(self) -> None:
try:
self.decomposition_device = torch.device(self.decomposition_device)
except (RuntimeError, TypeError) as exc:
raise ValueError(f"invalid FLUX decomposition_device {self.decomposition_device!r}") from exc
if self.decomposition_device.type not in ("cpu", "cuda"):
raise ValueError("FLUX decomposition_device must be CPU or CUDA")
if self.decomposition_device.type == "cuda":
if not torch.cuda.is_available():
raise ValueError("FLUX decomposition_device requests CUDA, but CUDA is not available")
device_count = torch.cuda.device_count()
index = self.decomposition_device.index
if index is not None and (index < 0 or index >= device_count):
raise ValueError(
f"FLUX decomposition_device index {index} is invalid for CUDA device_count={device_count}"
)
if self.config is not None:
self.config = _config_dict(self.config)
if not isinstance(self.require_complete_model, bool):
raise ValueError("require_complete_model must be a bool")
def _resolved_config(self, model: torch.nn.Module) -> dict[str, Any]:
value = self.config if self.config is not None else getattr(model, "config", None)
if value is None:
raise ValueError("FLUX export requires explicit config or model.config")
config = _normalize_config_paths(_config_dict(value))
try:
json.dumps(config)
except (TypeError, ValueError) as exc:
raise ValueError("FLUX config must be JSON serializable") from exc
return config
def metadata(self, model: torch.nn.Module, rank: int) -> Mapping[str, str]:
return {
"model_class": "NunchakuFluxTransformer2dModel",
"config": json.dumps(self._resolved_config(model), sort_keys=True),
"format": "pt",
"comfy_config": "{}",
}
@staticmethod
def _direct(source: SourceLinearRecord, prefix: str) -> SVDQuantExportRecord:
return SVDQuantExportRecord(
prefix=prefix,
residual_weight=source.residual_weight,
lora_down=source.lora_down,
lora_up=source.lora_up,
smooth=source.smooth,
smooth_orig=source.smooth_orig,
bias=source.bias,
scheme=source.scheme,
sources=(source,),
)
def _fuse(self, prefix: str, sources: tuple[SourceLinearRecord, ...], rank: int) -> SVDQuantExportRecord:
def operation() -> SVDQuantExportRecord:
if _has_shared_input_decomposition(sources):
return _concatenate_shared_sources(prefix, sources)
effective = [_effective_weight(source, self.decomposition_device) for source in sources]
input_dims = {weight.shape[1] for weight in effective}
if len(input_dims) != 1:
raise ValueError(f"{prefix} fused sources have incompatible input dimensions {sorted(input_dims)}")
weight = torch.cat(effective, dim=0)
biases = [source.bias for source in sources]
if any(bias is None for bias in biases) and not all(bias is None for bias in biases):
raise ValueError(f"{prefix} fused sources must either all have bias or all omit bias")
bias = None if biases[0] is None else torch.cat([item.to(self.decomposition_device) for item in biases])
return _decompose(weight, rank=rank, template=sources[0], prefix=prefix, sources=sources, bias=bias)
try:
return operation()
finally:
self._clear_decomposition_cache()
def _split_single_proj_out(
self, model: torch.nn.Module, block_prefix: str, source: SourceLinearRecord, rank: int
) -> tuple[SVDQuantExportRecord, SVDQuantExportRecord]:
def operation() -> tuple[SVDQuantExportRecord, SVDQuantExportRecord]:
config = self._resolved_config(model)
heads, head_dim = config.get("num_attention_heads"), config.get("attention_head_dim")
in_features = source.residual_weight.shape[1]
inner_dim = (
heads * head_dim
if isinstance(heads, int) and isinstance(head_dim, int)
else source.residual_weight.shape[0]
)
if inner_dim <= 0 or inner_dim >= in_features:
raise ValueError(
f"{block_prefix}.proj_out cannot split input columns at inner_dim={inner_dim} "
f"for shape {tuple(source.residual_weight.shape)}"
)
out_proj = SVDQuantExportRecord(
prefix=f"{block_prefix}.out_proj",
residual_weight=source.residual_weight[:, :inner_dim].contiguous(),
lora_down=source.lora_down[:, :inner_dim].contiguous(),
lora_up=source.lora_up,
smooth=source.smooth[:inner_dim].contiguous(),
smooth_orig=source.smooth_orig[:inner_dim].contiguous(),
bias=None,
scheme=source.scheme,
sources=(source,),
)
mlp_fc2 = SVDQuantExportRecord(
prefix=f"{block_prefix}.mlp_fc2",
residual_weight=source.residual_weight[:, inner_dim:].contiguous(),
lora_down=source.lora_down[:, inner_dim:].contiguous(),
lora_up=source.lora_up,
smooth=source.smooth[inner_dim:].contiguous(),
smooth_orig=source.smooth_orig[inner_dim:].contiguous(),
bias=source.bias,
scheme=source.scheme,
sources=(source,),
)
return out_proj, mlp_fc2
try:
return operation()
finally:
self._clear_decomposition_cache()
def _clear_decomposition_cache(self) -> None:
if self.decomposition_device.type == "cuda":
torch.cuda.empty_cache()
def map_modules(
self, model: torch.nn.Module, records: Iterable[SourceLinearRecord]
) -> Iterable[SVDQuantExportRecord]:
records = tuple(records)
by_block: dict[tuple[str, int], dict[str, SourceLinearRecord]] = {}
for record in records:
match = _BLOCK_RE.match(record.name)
if match is None:
raise ValueError(f"unrecognized FLUX SVDQuant source {record.name!r}")
family, index, local_name = match.groups()
local = by_block.setdefault((family, int(index)), {})
if local_name in local:
raise ValueError(f"duplicate FLUX source {record.name!r}")
local[local_name] = record
if self.require_complete_model:
config = self._resolved_config(model)
try:
expected_indices = {
"transformer_blocks": set(range(int(config["num_layers"]))),
"single_transformer_blocks": set(range(int(config["num_single_layers"]))),
}
except (KeyError, TypeError, ValueError) as exc:
raise ValueError("complete FLUX export requires integer num_layers and num_single_layers") from exc
for family, expected in expected_indices.items():
actual = {index for candidate, index in by_block if candidate == family}
if actual != expected:
raise ValueError(
f"complete FLUX export {family} indices mismatch: expected {sorted(expected)}, "
f"got {sorted(actual)}"
)
double_fixed = {name for names in _DOUBLE_FUSED.values() for name in names} | {
"attn.to_out.0",
"attn.to_add_out",
"ff.net.0.proj",
"ff_context.net.0.proj",
}
for (family, index), local in by_block.items():
names = set(local)
if family == "single_transformer_blocks":
required = {"attn.to_q", "attn.to_k", "attn.to_v", "proj_mlp", "proj_out"}
missing, extra = required - names, names - required
else:
missing = double_fixed - names
extra = (
names
- set(_DOUBLE_DIRECT)
- {name for fused_names in _DOUBLE_FUSED.values() for name in fused_names}
)
for stem in ("ff.net.2", "ff_context.net.2"):
variants = {stem, f"{stem}.linear"}
present = names & variants
if len(present) != 1:
missing.add(f"exactly one of {sorted(variants)}")
if missing or extra:
raise ValueError(
f"complete FLUX export rejects {family}.{index} coverage: "
f"missing={sorted(missing)}, extras={sorted(extra)}"
)
output: list[SVDQuantExportRecord] = []
for (family, index), local in sorted(by_block.items()):
block_prefix = f"{family}.{index}"
rank = next(iter(local.values())).lora_down.shape[0]
if family == "transformer_blocks":
for target, names in _DOUBLE_FUSED.items():
present = tuple(local[name] for name in names if name in local)
if present and len(present) != len(names):
missing = [name for name in names if name not in local]
raise ValueError(f"{block_prefix}.{target} missing fused sources {missing}")
if present:
output.append(self._fuse(f"{block_prefix}.{target}", present, rank))
for source_name, target in _DOUBLE_DIRECT.items():
if source_name in local:
output.append(self._direct(local[source_name], f"{block_prefix}.{target}"))
else:
names = _SINGLE_FUSED["qkv_proj"]
present = tuple(local[name] for name in names if name in local)
if present and len(present) != len(names):
missing = [name for name in names if name not in local]
raise ValueError(f"{block_prefix}.qkv_proj missing fused sources {missing}")
if present:
output.append(self._fuse(f"{block_prefix}.qkv_proj", present, rank))
if "proj_mlp" in local:
output.append(self._direct(local["proj_mlp"], f"{block_prefix}.mlp_fc1"))
if "proj_out" in local:
source = local["proj_out"]
output.extend(self._split_single_proj_out(model, block_prefix, source, rank))
return output
def validate_records(
self, sources: tuple[SourceLinearRecord, ...], records: tuple[SVDQuantExportRecord, ...]
) -> None:
ranks = {source.lora_down.shape[0] for source in sources}
if len(ranks) != 1:
raise ValueError(f"FLUX source ranks must agree, got {sorted(ranks)}")
if self.require_complete_model:
# Config was already resolved during mapping for single blocks; retain model-independent
# structural checks here and perform exact source coverage in map_modules via cached names.
families: dict[str, set[int]] = {"transformer_blocks": set(), "single_transformer_blocks": set()}
for source in sources:
match = _BLOCK_RE.match(source.name)
assert match is not None
families[match.group(1)].add(int(match.group(2)))
for family, indices in families.items():
if indices and indices != set(range(max(indices) + 1)):
raise ValueError(f"complete FLUX export rejects gaps in {family}: {sorted(indices)}")
prefixes = [record.prefix for record in records]
if len(prefixes) != len(set(prefixes)):
raise ValueError("FLUX adapter produced duplicate logical record prefixes")
@staticmethod
def _module_map(model: torch.nn.Module) -> dict[str, torch.nn.Module]:
return dict(model.named_modules())
def extra_tensors(self, model: torch.nn.Module) -> Mapping[str, torch.Tensor]:
modules = self._module_map(model)
tensors: dict[str, torch.Tensor] = {}
block_indices: dict[str, set[int]] = {"transformer_blocks": set(), "single_transformer_blocks": set()}
for name in modules:
match = _BLOCK_RE.match(name)
if match:
block_indices[match.group(1)].add(int(match.group(2)))
if self.require_complete_model:
config = self._resolved_config(model)
for family, config_name in (
("transformer_blocks", "num_layers"),
("single_transformer_blocks", "num_single_layers"),
):
expected = set(range(int(config[config_name])))
if block_indices[family] != expected:
raise ValueError(
f"complete FLUX extras {family} indices mismatch: expected {sorted(expected)}, "
f"got {sorted(block_indices[family])}"
)
for family, indices in block_indices.items():
for index in sorted(indices):
block = f"{family}.{index}"
adanorms = (
(("norm1.linear", 6), ("norm1_context.linear", 6))
if family == "transformer_blocks"
else (("norm.linear", 3),)
)
for local_name, splits in adanorms:
module = modules.get(f"{block}.{local_name}")
if module is None:
if self.require_complete_model:
raise ValueError(f"complete FLUX export missing {block}.{local_name}")
continue
weight = getattr(module, "weight", None)
bias = getattr(module, "bias", None)
if not isinstance(weight, torch.Tensor):
raise ValueError(f"{block}.{local_name}.weight must be a tensor")
packed = quantize_adanorm_w4a16_rtn(
weight.detach().to(device="cpu", dtype=torch.bfloat16),
bias=None if bias is None else bias.detach().to(device="cpu", dtype=torch.bfloat16),
splits=splits,
group_size=64,
)
prefix = f"{block}.{local_name}"
tensors.update(
{
f"{prefix}.qweight": packed.qweight,
f"{prefix}.wscales": packed.wscales,
f"{prefix}.wzeros": packed.wzeros,
f"{prefix}.bias": packed.bias,
}
)
for source_name, target_name in _RMS_MAP.items():
module = modules.get(f"{block}.{source_name}")
weight = None if module is None else getattr(module, "weight", None)
if weight is None:
required_rms = family == "transformer_blocks" or source_name in ("attn.norm_q", "attn.norm_k")
if self.require_complete_model and required_rms:
raise ValueError(f"complete FLUX export missing {block}.{source_name}.weight")
continue
tensors[f"{block}.{target_name}.weight"] = weight.detach().to(torch.bfloat16).cpu()
passthrough = {
name: parameter for name, parameter in model.named_parameters() if name.startswith(_TOP_LEVEL_PREFIXES)
}
if self.require_complete_model:
missing_top_level = FLUX_TOP_LEVEL_TENSOR_KEYS - passthrough.keys()
if missing_top_level:
raise ValueError(f"complete FLUX model is missing top-level parameters: {sorted(missing_top_level)}")
extra_top_level = passthrough.keys() - FLUX_TOP_LEVEL_TENSOR_KEYS
if extra_top_level:
raise ValueError(f"complete FLUX model has unexpected top-level parameters: {sorted(extra_top_level)}")
for name in FLUX_TOP_LEVEL_TENSOR_KEYS & passthrough.keys():
tensors[name] = passthrough[name].detach().to(torch.bfloat16).cpu()
return {key: value.contiguous() for key, value in tensors.items()}
def validate(self, tensors: Mapping[str, torch.Tensor], metadata: Mapping[str, str]) -> None:
if metadata.get("model_class") != "NunchakuFluxTransformer2dModel":
raise ValueError("FLUX metadata has incorrect model_class")
if metadata.get("format") != "pt" or metadata.get("comfy_config") != "{}":
raise ValueError("FLUX metadata requires format='pt' and empty comfy_config")
try:
config = json.loads(metadata["config"])
except (KeyError, json.JSONDecodeError) as exc:
raise ValueError("FLUX metadata config must be a JSON object") from exc
if not isinstance(config, dict):
raise ValueError("FLUX metadata config must be a JSON object")
required: set[str] = set()
if self.require_complete_model:
try:
num_layers = int(config["num_layers"])
num_single_layers = int(config["num_single_layers"])
except (KeyError, TypeError, ValueError) as exc:
raise ValueError("complete FLUX metadata requires layer counts") from exc
top_level_keys = {
key for key in tensors if not key.startswith(("transformer_blocks.", "single_transformer_blocks."))
}
missing_top_level = FLUX_TOP_LEVEL_TENSOR_KEYS - top_level_keys
if missing_top_level:
raise ValueError(f"complete FLUX artifact is missing top-level tensors: {sorted(missing_top_level)}")
extra_top_level = top_level_keys - FLUX_TOP_LEVEL_TENSOR_KEYS
if extra_top_level:
raise ValueError(f"complete FLUX artifact has unexpected top-level tensors: {sorted(extra_top_level)}")
linear_suffixes = ("qweight", "wscales", "smooth", "smooth_orig", "lora_down", "lora_up", "bias")
for index in range(num_layers):
block = f"transformer_blocks.{index}"
for linear in (
"qkv_proj",
"qkv_proj_context",
"out_proj",
"out_proj_context",
"mlp_fc1",
"mlp_fc2",
"mlp_context_fc1",
"mlp_context_fc2",
):
required.update(f"{block}.{linear}.{suffix}" for suffix in linear_suffixes)
for norm in ("norm1.linear", "norm1_context.linear"):
required.update(f"{block}.{norm}.{suffix}" for suffix in ("qweight", "wscales", "wzeros", "bias"))
required.update(
f"{block}.{norm}.weight" for norm in ("norm_q", "norm_k", "norm_added_q", "norm_added_k")
)
for index in range(num_single_layers):
block = f"single_transformer_blocks.{index}"
for linear in ("qkv_proj", "out_proj", "mlp_fc1", "mlp_fc2"):
required.update(f"{block}.{linear}.{suffix}" for suffix in linear_suffixes)
required.update(f"{block}.norm.linear.{suffix}" for suffix in ("qweight", "wscales", "wzeros", "bias"))
required.update(f"{block}.{norm}.weight" for norm in ("norm_q", "norm_k"))
missing = required - tensors.keys()
if missing:
raise ValueError(f"complete FLUX artifact is missing expected tensors: {sorted(missing)[:5]}")
if num_layers == 19 and num_single_layers == 38 and len(tensors) != flux_onefile_tensor_count(19, 38):
raise ValueError(f"standard FLUX one-file artifact must contain 2604 tensors, got {len(tensors)}")
for key, tensor in tensors.items():
if tensor.device.type != "cpu" or not tensor.is_contiguous():
raise ValueError(f"FLUX tensor {key!r} must be contiguous on CPU")
if tensor.is_floating_point() and not bool(torch.isfinite(tensor).all()):
raise ValueError(f"FLUX tensor {key!r} must be finite")
if not key.startswith(("transformer_blocks.", "single_transformer_blocks.")):
if not key.startswith(_TOP_LEVEL_PREFIXES) or tensor.dtype != torch.bfloat16:
raise ValueError(f"FLUX passthrough tensor {key!r} must be in an allowed top-level BF16 family")
is_adanorm = ".norm" in key and any(
marker in key for marker in (".norm.linear.", ".norm1.linear.", ".norm1_context.linear.")
)
if key.endswith(".qweight"):
expected_dtype = torch.int32 if is_adanorm else torch.int8
if tensor.dtype != expected_dtype or tensor.ndim != 2:
raise ValueError(f"FLUX qweight {key!r} must be 2D {expected_dtype}")
elif key.endswith(".wscales"):
expected_dtype = torch.bfloat16 if is_adanorm else torch.uint8
if tensor.dtype != expected_dtype or tensor.ndim != 2:
raise ValueError(f"FLUX wscales {key!r} must be 2D {expected_dtype}")
elif key.endswith(".wzeros"):
if not is_adanorm or tensor.dtype != torch.bfloat16 or tensor.ndim != 2:
raise ValueError(f"FLUX wzeros {key!r} must be a 2D AdaNorm BF16 tensor")
elif key.endswith((".lora_down", ".lora_up")):
if tensor.dtype != torch.bfloat16 or tensor.ndim != 2:
raise ValueError(f"FLUX low-rank tensor {key!r} must be 2D BF16")
elif key.endswith((".smooth", ".smooth_orig", ".bias")):
if tensor.dtype != torch.bfloat16 or tensor.ndim != 1:
raise ValueError(f"FLUX vector tensor {key!r} must be 1D BF16")
elif key.endswith(".weight") and key.startswith(("transformer_blocks.", "single_transformer_blocks.")):
if tensor.dtype != torch.bfloat16 or tensor.ndim != 1:
raise ValueError(f"FLUX RMSNorm tensor {key!r} must be 1D BF16")
__all__ = ["FLUX_TOP_LEVEL_TENSOR_KEYS", "FluxSVDQuantNunchakuAdapter", "flux_onefile_tensor_count"]