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.
"""Rotation/transform configuration (canonical, unified).
This module is the **single source of truth** for the ``RotationConfig``
schema.
Two implementation backends share this one schema (method B):
* ``backend="inplace"`` – QuaRot-style residual-stream rotation, implemented
under :mod:`auto_round.algorithms.transforms.hadamard.inplace`. Works for any
weight/activation dtype and can optionally fuse the online Hadamard into
weights (``fuse_online_to_weight=True``).
* ``backend="transform"`` – Per-Linear weight + activation Hadamard with a
fused triton kernel, implemented under
:mod:`auto_round.algorithms.transforms.hadamard.apply`. Supports only
MXFP4 / NVFP4 and cannot fuse online to weight.
* ``backend="auto"`` – dispatcher picks inplace when a fused online rotation
is requested, transform when the data_type is MX/NV-FP, inplace otherwise.
"""
from __future__ import annotations
from typing import Any, ClassVar
from pydantic import BaseModel, Field, field_validator
from auto_round.algorithms.config import AlgorithmConfig, AlgorithmParameterRegistry
from auto_round.algorithms.registry import register_algorithm
from auto_round.algorithms.transforms.base import BaseRotationConfig
from auto_round.compressors.utils import is_mx_fp, is_nv_fp
from auto_round.utils import logger
__all__ = [
"RotationConfig",
"dump_group_size_to_rotation_config",
"normalize_rotation_config",
"to_dict_rotation_config",
]
# Supported Hadamard transform types (also used by HadamardTransform registry).
HADAMARD_TYPES: frozenset[str] = frozenset(
{"hadamard", "random_hadamard", "inplace_quarot_hadamard", "inplace_hadamard", "inplace_random"}
)
_SUPPORTED_BACKENDS: frozenset[str] = frozenset({"auto", "inplace", "transform"})
class RotationConfig(AlgorithmConfig, BaseModel, BaseRotationConfig):
"""Unified configuration for Hadamard rotation/transform applied to a model.
See the module docstring for a description of the three backends.
Notes:
* ``block_size`` is the group/block size for grouped Hadamard.
For ``backend="inplace"`` it is forwarded as ``group_size``
(``None`` / ``-1`` means full-dimension Hadamard).
"""
# Registry key consumed by BaseRotation.from_config (kept for API parity
# with other BaseRotationConfig subclasses).
algorithm: str = Field(default="hadamard", frozen=True)
# ---- shared ----
backend: str = Field(default="auto")
block_size: int | None = Field(default=None)
hadamard_type: str = Field(default="hadamard")
# Apply the Hadamard rotation per decoder block, in lock-step with block-wise
# quantization, instead of rotating the whole model up-front. Honoured by the
# per-Linear transform backend; unsupported cases fall back to full-model
# rotation (see ``RotationPreprocessor.rotate_model``).
layerwise: bool = Field(default=False)
# ---- inplace-only ----
fuse_online_to_weight: bool | None = Field(default=None)
allow_online_rotation: bool = Field(default=True)
# for random hadamard (transform path)
random_seed: bool = Field(default=False, exclude=True)
cli_include_common_args: ClassVar[bool] = False
@classmethod
def register_args(cls, registry: AlgorithmParameterRegistry) -> None:
registry.add_argument(
"--rotation_type",
"--rotation-hadamard-type",
field="hadamard_type",
dest="rotation_hadamard_type",
default=None,
fallback="hadamard",
choices=["hadamard", "random_hadamard", "quarot_hadamard"],
help="Hadamard transform variant.",
)
registry.add_argument(
"--rotation_backend",
field="backend",
dest="rotation_backend",
default="auto",
choices=["auto", "inplace", "transform"],
help="Rotation backend to use.",
)
registry.add_argument(
"--rotation_block_size",
field="block_size",
dest="rotation_block_size",
default=None,
type=int,
help="Grouped Hadamard block size.",
)
registry.add_argument(
"--fuse_online_to_weight",
field="fuse_online_to_weight",
default=None,
action="boolean_optional",
help="Fuse online Hadamard rotation into weights.",
)
registry.add_argument(
"--allow_online_rotation",
field="allow_online_rotation",
default=True,
action="boolean_optional",
help="Allow online activation rotation.",
)
model_config = {"arbitrary_types_allowed": True}
def __init__(self, **data: Any) -> None:
"""Initialize a Hadamard rotation configuration.
Args:
algorithm: Canonical algorithm name used for registry lookup.
backend: Rotation backend to use. ``auto`` lets AutoRound pick
an implementation, ``inplace`` uses QuaRot-style online
rotation, and ``transform`` uses the transform backend.
block_size: Grouped Hadamard block size. None keeps the backend
default behavior.
hadamard_type: Hadamard transform variant, such as
``hadamard``, ``random_hadamard``, or ``quarot_hadamard``.
fuse_online_to_weight: Whether online Hadamard rotation should
be fused into the weights when supported.
allow_online_rotation: Whether online activation rotation is
allowed.
random_seed: Internal flag used by random Hadamard paths.
**data: Additional Pydantic field values forwarded to BaseModel.
"""
super().__init__(**data)
def can_compile_block_forward(self) -> bool:
"""Hadamard may install online hooks that are not Dynamo compatible."""
return False
@field_validator("backend")
@classmethod
def _validate_backend(cls, v: str) -> str:
if v not in _SUPPORTED_BACKENDS:
raise ValueError(f"Unsupported backend: {v}. Supported values: {sorted(_SUPPORTED_BACKENDS)}")
return v
@field_validator("hadamard_type")
@classmethod
def _validate_hadamard_type(cls, v: str) -> str:
if v not in HADAMARD_TYPES:
raise ValueError(f"Unsupported hadamard_type: {v!r}. Supported values: {sorted(HADAMARD_TYPES)}")
return v
# ---------------------------------------------------------------------------
# Helpers (free functions – match the old experimental/utils.py API)
# ---------------------------------------------------------------------------
def to_dict_rotation_config(rotation_config: str | dict | RotationConfig | None) -> dict[str, Any]:
"""Convert any supported config form to a plain ``dict`` (no data-type logic).
Accepts:
* ``None`` → ``{}``
* :class:`RotationConfig` → ``model_dump()``
* ``dict`` → shallow-copied
* ``str`` → ``{"hadamard_type": key}`` (``"default"`` ⇒ plain default)
"""
if rotation_config is None:
return {}
if isinstance(rotation_config, str):
key = rotation_config.strip()
if not key:
return {}
if key == "default":
return {"hadamard_type": "hadamard"}
return {"hadamard_type": key}
if isinstance(rotation_config, RotationConfig):
return rotation_config.model_dump()
return dict(rotation_config)
def dump_group_size_to_rotation_config(rotation_config: str | dict | RotationConfig, group_size: int) -> dict[str, Any]:
"""Return *rotation_config* as a dict with ``block_size`` populated from *group_size* (if unset)."""
rotation_dict = to_dict_rotation_config(rotation_config)
if rotation_dict.get("block_size", None) is None:
rotation_dict["block_size"] = group_size
return rotation_dict
def normalize_rotation_config(
rotation_config: str | dict | RotationConfig | None,
data_type: str = "mx_fp",
) -> dict[str, Any]:
"""Normalise *rotation_config* to a validated ``dict`` ready for ``RotationConfig(**)``.
Behaviour:
* ``None`` → ``{}``
* If ``block_size`` is not set:
- ``mx_fp`` → default 32
- ``nv_fp`` → default 16
- other data types → emit a warning (no default)
* If ``block_size`` mismatches the data-type recommendation, emit a warning.
Raises:
ValueError: If the resulting config is invalid.
"""
def _apply_data_type_block_size(cfg_dict: dict[str, Any], block_size_explicitly_set: bool) -> dict[str, Any]:
block_size = cfg_dict.get("block_size")
if not block_size_explicitly_set or block_size is None:
if is_mx_fp(data_type):
cfg_dict["block_size"] = 32
elif is_nv_fp(data_type):
cfg_dict["block_size"] = 16
logger.warning("block_size is not set for data_type 'nv_fp'; defaulting to 16.")
else:
logger.warning(
f"block_size is not set and cannot be inferred for data_type {data_type!r}; "
"please set block_size explicitly in rotation_config if needed."
)
else:
if is_mx_fp(data_type) and block_size != 32:
logger.warning(f"data_type is 'mx_fp' but block_size={block_size}; recommended value is 32.")
elif is_nv_fp(data_type) and block_size != 16:
logger.warning(f"data_type is 'nv_fp' but block_size={block_size}; recommended value is 16.")
return cfg_dict
if rotation_config is None:
return {}
rotation_dict = to_dict_rotation_config(rotation_config)
block_size_explicitly_set = "block_size" in rotation_dict
cfg_dict = _apply_data_type_block_size(rotation_dict, block_size_explicitly_set)
try:
return RotationConfig.model_validate(cfg_dict).model_dump()
except Exception as exc:
raise ValueError(f"Invalid RotationConfig: {exc}") from exc
register_algorithm(
"hadamard",
aliases=("hadamard", "random_hadamard", "quarot_hadamard"),
config_factory=RotationConfig,
summary="Hadamard rotation/transform applied before quantization.",
alias_factories={
"random_hadamard": lambda: RotationConfig(hadamard_type="random_hadamard"),
"quarot_hadamard": lambda: RotationConfig(hadamard_type="quarot_hadamard"),
},
)