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.
"""SpinQuant / QuaRot rotation — ``BaseRotation`` + ``SerializerMixin``.
Registers ``"spinquant"`` in the :class:`BaseRotation` registry so that
the unified ``apply_rotation(model, config)`` entry point can dispatch to
the SpinQuant preprocessing pipeline automatically.
Also implements :class:`SerializerMixin` so that the generic dispatch
functions (``inject_rotation_buffers_on_layer``, etc.) route to SpinQuant
serialization logic without export files ever naming "spinquant".
Usage via the unified entry point::
from auto_round.algorithms.transforms import apply_rotation
from auto_round.algorithms.transforms.spinquant import SpinQuantConfig
config = SpinQuantConfig(r1=True, r2=True, r3=False, r4=False,
trainable_rotation=False)
model = apply_rotation(model, config)
Usage via AutoRound pipeline::
from auto_round import AutoRound
from auto_round.algorithms.transforms.spinquant import SpinQuantConfig
AutoRound(
alg_configs=[SignRoundConfig(iters=200), SpinQuantConfig(r1=True, r2=True)],
model=model,
scheme="W4A16",
)
"""
from __future__ import annotations
import logging
from typing import Any
import torch
import torch.nn as nn
from auto_round.algorithms.transforms.base import BaseRotation, SerializerMixin
logger = logging.getLogger("autoround")
@BaseRotation.register("spinquant")
class SpinQuantRotation(BaseRotation, SerializerMixin):
"""QuaRot / SpinQuant rotation registered as ``"spinquant"`` in
:class:`BaseRotation`.
Delegates to :class:`SpinQuantPreprocessor` for the actual rotation
pipeline (RMSNorm fusion → rotation matrix init → optional training →
weight fusion → online hook registration).
Implements :class:`SerializerMixin` for save/load support — all
serialization calls are delegated to the existing ``serialize.py``
functions.
For QuaRot mode (``trainable_rotation=False``), no ``dataloader`` is
needed. For SpinQuant mode (``trainable_rotation=True``, ⚠️ experimental),
pass ``dataloader=`` via ``**kwargs``.
"""
# ------------------------------------------------------------------
# Preprocessing (existing, unchanged)
# ------------------------------------------------------------------
def apply_to_model(
self,
model: torch.nn.Module,
data_type: str = "mx_fp",
**kwargs: Any,
) -> torch.nn.Module:
"""Apply SpinQuant / QuaRot rotation to *model*.
Args:
model: The model to transform (modified in-place).
data_type: Quantization data type (informational; SpinQuant does
not change behavior based on this).
**kwargs: Extra arguments. ``dataloader`` is forwarded to
:meth:`SpinQuantPreprocessor.preprocess` when the config
has ``trainable_rotation=True``.
Returns:
The transformed model.
"""
# Lazy import to avoid circular dependencies — SpinQuantPreprocessor
# imports from this package's __init__ which imports this module.
from auto_round.algorithms.transforms.spinquant.preprocessor import (
SpinQuantPreprocessor,
)
dataloader = kwargs.get("dataloader")
preprocessor = SpinQuantPreprocessor(model, self.config)
return preprocessor.preprocess(dataloader)
# ------------------------------------------------------------------
# Layer-wise rotation interface (block-wise quantization)
# ------------------------------------------------------------------
@property
def supports_layerwise(self) -> bool:
"""SpinQuant supports layer-wise rotation (Online R1 + R2/R3/R4)."""
return True
def prepare_layerwise(
self,
model: torch.nn.Module,
data_type: str = "mx_fp",
**kwargs: Any,
) -> SpinQuantRotation:
"""Prepare for layer-wise rotation: init R matrices only.
Creates a :class:`SpinQuantPreprocessor`, calls its
:meth:`~SpinQuantPreprocessor.prepare` method (which initialises
rotation matrices without modifying weights), and stores the
preprocessor for later :meth:`rotate_layer` calls.
Args:
model: The model to prepare (weights not modified).
data_type: Quantization data type (informational).
**kwargs: ``dataloader`` forwarded when ``trainable_rotation=True``.
Returns:
``self``, for chaining.
"""
from auto_round.algorithms.transforms.spinquant.preprocessor import (
SpinQuantPreprocessor,
)
dataloader = kwargs.get("dataloader")
self._preprocessor = SpinQuantPreprocessor(model, self.config)
self._preprocessor.prepare(dataloader)
return self
def rotate_layer(
self,
layer: torch.nn.Module,
layer_idx: int,
**kwargs: Any,
) -> None:
"""Apply rotation to a single decoder layer.
Delegates to :meth:`SpinQuantPreprocessor.rotate_layer`.
"""
if not hasattr(self, "_preprocessor"):
raise RuntimeError(
"prepare_layerwise() must be called before rotate_layer(). "
"The preprocessor has not been initialised."
)
self._preprocessor.rotate_layer(layer, layer_idx)
def finalize_layerwise(self, model: torch.nn.Module) -> None:
"""Cleanup after all layers have been rotated."""
if hasattr(self, "_preprocessor"):
self._preprocessor.finalize()
# ------------------------------------------------------------------
# SerializerMixin — Save side
# ------------------------------------------------------------------
def inject_buffers_on_layer(
self,
layer_name: str,
qlayer: nn.Module,
model: nn.Module,
) -> None:
"""Inject SpinQuant rotation buffers onto a single QuantLinear."""
config = self._get_model_config(model)
if config is None:
return
try:
from auto_round.algorithms.transforms.spinquant.serialize import (
_R1_PREFIX,
_R4_PREFIX,
_get_hidden_size,
_get_intermediate_size,
_get_stored_rotation,
_inject_rotation_buffers,
)
short_name = layer_name.split(".")[-1]
r1_proj_names = ("q_proj", "k_proj", "v_proj", "gate_proj", "up_proj")
r4_proj_names = ("down_proj",)
if config.r1 and config.online_r1_rotation and short_name in r1_proj_names:
hidden_size = _get_hidden_size(model)
r1_size = config.rotation_size or hidden_size
_inject_rotation_buffers(
qlayer,
_R1_PREFIX,
r1_size,
random=config.random_r1,
is_trained=False,
rotation_matrix=_get_stored_rotation(model, "spinquant_R1"),
)
if config.r4 and short_name in r4_proj_names:
intermediate_size = _get_intermediate_size(model)
r4_size = config.rotation_size or intermediate_size
_inject_rotation_buffers(
qlayer,
_R4_PREFIX,
r4_size,
random=config.random_r4,
is_trained=False,
rotation_matrix=_get_stored_rotation(model, "spinquant_R4_matrix") if config.random_r4 else None,
)
except Exception as e:
logger.warning(f"Failed to inject SpinQuant buffers on {layer_name}: {e}")
def inject_buffers_bulk(
self,
model: nn.Module,
quantization_config: dict,
) -> None:
"""Inject SpinQuant rotation buffers on all QuantLinear modules."""
config = self._get_model_config(model)
if config is None:
return
try:
from auto_round.algorithms.transforms.spinquant.serialize import (
_config_to_serializable,
inject_spinquant_buffers,
)
n = inject_spinquant_buffers(model, config)
if n > 0:
cfg_dict = _config_to_serializable(config, model)
cfg_dict["algorithm"] = "spinquant"
# Use "spinquant_config" key (not "rotation_config" —
# that key is used by the Hadamard rotation system).
quantization_config["spinquant_config"] = cfg_dict
except Exception as e:
logger.warning(f"Failed to inject SpinQuant buffers: {e}")
def save_config(self, model: nn.Module, save_dir: str) -> None:
"""Save SpinQuant config to config.json."""
config = self._get_model_config(model)
if config is None:
return
try:
from auto_round.algorithms.transforms.spinquant.serialize import (
save_spinquant_config,
)
save_spinquant_config(model, save_dir, config)
except Exception as e:
logger.warning(f"Failed to save SpinQuant config: {e}")
# ------------------------------------------------------------------
# SerializerMixin — Load side
# ------------------------------------------------------------------
def preregister_buffers(
self,
model: nn.Module,
config_dict: dict,
) -> int:
"""Pre-register empty SpinQuant buffers for state_dict loading."""
from auto_round.algorithms.transforms.spinquant.serialize import (
preregister_spinquant_buffers,
)
return preregister_spinquant_buffers(model, config_dict)
def rebuild_online(self, model: nn.Module) -> nn.Module:
"""Rebuild online SpinQuant rotations (forward patch + R3 hook)."""
from auto_round.algorithms.transforms.spinquant.serialize import (
rebuild_spinquant_online,
)
return rebuild_spinquant_online(model)
def has_rotation_buffers(self, module: nn.Module) -> bool:
"""Check for spinquant-specific buffer prefixes."""
return hasattr(module, "spinquant_r1_type") or hasattr(module, "spinquant_r4_type")
@classmethod
def config_key(cls) -> str:
return "spinquant_config"
# ------------------------------------------------------------------
# Private helper
# ------------------------------------------------------------------
@staticmethod
def _get_model_config(model: nn.Module):
"""Get rotation config from model, with legacy fallback."""
config = getattr(model, "_rotation_config", None)
if config is None:
config = getattr(model, "_spinquant_config", None)
return config