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.
from collections.abc import Callable
from auto_round.algorithms.config import AlgorithmParameterRegistry
from auto_round.algorithms.quantization.config import QuantizationConfig
from auto_round.algorithms.registry import register_algorithm
from auto_round.logger import logger
class SignRoundConfig(QuantizationConfig):
"""Configuration for SignRound-style block quantization."""
# Whether to emit the generic `enable_qad` experimental warning (subclasses
# with their own warning, e.g. QADConfig, disable it).
_warn_enable_qad = True
@classmethod
def register_args(cls, registry: AlgorithmParameterRegistry) -> None:
registry.add_argument(
"--iters",
"--iter",
field="iters",
default=None,
type=int,
help="Number of optimization iterations per block.",
)
registry.add_argument(
"--lr", field="lr", default=None, type=float, help="Learning rate for rounding optimization."
)
registry.add_argument(
"--minmax_lr", field="minmax_lr", default=None, type=float, help="Learning rate for min-max tuning."
)
registry.add_argument(
"--momentum", field="momentum", default=0.0, type=float, help="Momentum factor for the optimizer."
)
registry.add_argument(
"--nblocks", field="nblocks", default=1, type=int, help="Number of blocks to optimize together."
)
minmax = registry.add_mutually_exclusive_group()
minmax.add_argument(
"--enable_minmax_tuning",
field="enable_minmax_tuning",
default=True,
dest="enable_minmax_tuning",
action="store_true",
help="Tune weight min/max ranges.",
)
minmax.add_argument(
"--no-enable_minmax_tuning",
"--disable_minmax_tuning",
field="enable_minmax_tuning",
dest="enable_minmax_tuning",
action="store_false",
help="Disable weight min/max tuning.",
)
registry.add_argument(
"--enable_norm_bias_tuning",
field="enable_norm_bias_tuning",
default=False,
action="boolean_optional",
help="Tune normalization and bias terms.",
)
registry.add_argument(
"--gradient_accumulate_steps",
field="gradient_accumulate_steps",
default=1,
type=int,
help="Gradient accumulation steps per update.",
)
registry.add_argument(
"--enable_alg_ext",
field="enable_alg_ext",
default=False,
action="boolean_optional",
help="(Deprecated) Enable the experimental SignRound algorithm extension. "
"Use `--algorithm auto_round_v2` instead.",
)
registry.add_argument(
"--not_use_best_mse",
field="not_use_best_mse",
default=False,
action="boolean_optional",
help="Skip restoring best-MSE checkpoint.",
)
quanted_input = registry.add_mutually_exclusive_group()
quanted_input.add_argument(
"--enable_quanted_input",
field="enable_quanted_input",
default=True,
dest="enable_quanted_input",
action="store_true",
help="Consume quantized output of previous blocks.",
)
quanted_input.add_argument(
"--no-enable_quanted_input",
"--disable_quanted_input",
field="enable_quanted_input",
dest="enable_quanted_input",
action="store_false",
help="Disable quantized-input propagation across blocks.",
)
registry.add_argument(
"--enable_adam",
field="enable_adam",
default=False,
action="boolean_optional",
help="Use the Adam-based SignRound variant.",
)
registry.add_argument(
"--enable_lfq",
field="enable_lfq",
default=False,
action="boolean_optional",
help="Enable last-block LM cross-entropy (LFQ) loss for the final transformer block (experimental).",
)
registry.add_argument(
"--lfq_loss",
field="lfq_loss",
default="tk",
choices=["ce", "dtk", "rkl", "tk"],
help=(
"LFQ loss type for the final transformer block. 'ce' uses next-token cross-entropy "
"against the ground-truth labels; 'dtk' uses the Decoupled Tempered Top-K forward-KL "
"knowledge distillation loss (KL(p_T || p_S)); 'rkl' uses the same decoupled Top-K "
"objective with the reverse KL (KL(p_S || p_T)); 'tk' only aligns the Top-K-normalized "
"conditional distributions (tempered conditional KL within the teacher Top-K, without "
"the binary mass term). 'dtk'/'rkl'/'tk' distill the FP (teacher) block output into the "
"quantized (student) block output (experimental)."
),
)
registry.add_argument(
"--lfq_top_k",
field="lfq_top_k",
default=32,
type=int,
help="Number of top teacher logits used by the 'dtk' LFQ loss.",
)
registry.add_argument(
"--lfq_temperature",
field="lfq_temperature",
default=1.0,
type=float,
help="Temperature applied to the within-Top-K conditional KL term of the 'dtk' LFQ loss.",
)
registry.add_argument(
"--lfq_num_blocks",
field="lfq_num_blocks",
default=1,
type=int,
help=(
"Number of final text-decoder blocks the LFQ loss is applied to (default 1 = last "
"block only). Increase to propagate the logit-aware signal to deeper blocks."
),
)
registry.add_argument(
"--lfq_mse_weight",
field="lfq_mse_weight",
default=0.0,
type=float,
help=(
"Weight of the MSE block-reconstruction term added to the LFQ (KD) loss: "
"loss = kd_loss + lfq_mse_weight * mse_loss. 0.0 (default) replaces the MSE loss "
"entirely with the KD loss (original behavior); >0 combines both so the block keeps "
"its reconstruction fidelity while adding logit alignment."
),
)
registry.add_argument(
"--enable_qad",
field="enable_qad",
default=False,
action="boolean_optional",
help=(
"Enable QAD (quantization-aware distillation): fuse all text-decoder blocks into a "
"single jointly-optimized group (whole-network training, not block-by-block) and tune "
"them against the final-output LM loss (`--lfq_loss`, default 'ce'). No intermediate "
"block MSE is used. Implies --enable_lfq. Set --nblocks N to train in joint chunks of "
"N blocks instead of the whole network at once (experimental)."
),
)
registry.add_argument(
"--enable_neuqi",
field="enable_neuqi",
action="store_true",
help=(
"Enable the NeUQI grid search (arXiv 2505.17595): the tuning grid is anchored to "
"the searched (scale, zero-point) result once at layer init and frozen during "
"tuning (joint search for asym layers, two-stage scale search for sym layers)."
),
)
def __init__(
self,
*,
iters: int = 200,
lr: float | None = None,
minmax_lr: float | None = None,
lr_scheduler: Callable | None = None,
momentum: float = 0.0,
nblocks: int = 1,
enable_minmax_tuning: bool = True,
enable_norm_bias_tuning: bool = False,
gradient_accumulate_steps: int = 1,
enable_alg_ext: bool = False,
not_use_best_mse: bool = False,
dynamic_max_gap: int = -1,
enable_quanted_input: bool = True,
optimizer: str | None = None, # TODO later wenhuach delete this
enable_adam: bool = False, # TODO later wenhuach delete this
enable_lfq: bool = False,
lfq_loss: str = "tk",
lfq_top_k: int = 32,
lfq_temperature: float = 1.0,
lfq_num_blocks: int = 1,
lfq_mse_weight: float = 0.0,
enable_qad: bool = False,
enable_neuqi: bool = False,
**kwargs,
) -> None:
"""Initialize a SignRound configuration.
Args:
iters: Number of optimization iterations for each quantized
block.
lr: Learning rate used by the main rounding optimization.
If None, a heuristic based on ``iters`` is used.
minmax_lr: Learning rate used by min-max tuning. If None, it
falls back to ``lr``.
lr_scheduler: Optional learning-rate scheduler name or
scheduler object used by the optimizer.
momentum: Momentum factor used by the optimizer.
nblocks: Number of blocks to optimize together.
enable_minmax_tuning: Whether to tune weight min/max ranges.
enable_norm_bias_tuning: Whether to tune normalization and
bias terms.
gradient_accumulate_steps: Number of gradient accumulation
steps used per optimization update.
enable_alg_ext: Deprecated. Whether to enable the experimental
SignRound extension implementation. Selecting the
``auto_round_v2`` algorithm is the supported way to turn it on;
this switch is kept for backward compatibility and is
normalized to :class:`SignRoundV2Config`.
not_use_best_mse: Whether to skip restoring the best-MSE
checkpoint during tuning.
dynamic_max_gap: Maximum dynamic gap used by adaptive tuning
logic.
enable_quanted_input: Whether each block should consume the
quantized output of previous blocks during calibration.
optimizer: Optional optimizer name override.
enable_adam: Whether to use the Adam-based SignRound variant.
enable_lfq: Enable the last-block LM loss (LFQ) for the final
transformer block (experimental).
lfq_loss: LFQ loss type, ``"ce"`` (next-token cross-entropy),
``"dtk"`` (Decoupled Tempered Top-K forward-KL distillation,
``KL(p_T || p_S)``), ``"rkl"`` (same decoupled Top-K objective
with the reverse KL ``KL(p_S || p_T)``) or ``"tk"`` (only align
the Top-K-normalized conditional distributions, without the
binary mass term). ``"dtk"``/``"rkl"``/``"tk"`` distill the FP
teacher block output into the quantized student.
lfq_top_k: Number of top teacher logits used by the ``"dtk"`` LFQ loss.
lfq_temperature: Temperature applied to the within-Top-K conditional
KL term of the ``"dtk"`` LFQ loss.
lfq_num_blocks: Number of final text-decoder blocks the LFQ loss is
applied to (default 1 = last block only).
lfq_mse_weight: Weight of the MSE block-reconstruction term added to
the KD loss (``loss = kd_loss + lfq_mse_weight * mse_loss``). 0.0
replaces MSE with the KD loss (original behavior); >0 combines
both.
enable_qad: Enable QAD (quantization-aware distillation): fuse all
text-decoder blocks into a single jointly-optimized group and
tune them against the final-output LM loss (``lfq_loss``, default
``"ce"``), with no intermediate block MSE. Implies
``enable_lfq``. ``nblocks`` > 1 trains in joint chunks instead of
the whole network at once.
enable_neuqi: Opt into the NeUQI grid search (arXiv 2505.17595):
the joint (scale, integer zero-point) search runs once at
layer init and anchors the tuning grid to the winner, frozen
during tuning (the two-stage symmetric scale search for sym
layers). The search grid sizes are tunable via
``AR_NEUQI_COARSE`` and ``AR_NEUQI_FINE``.
**kwargs: Common quantization arguments forwarded to
QuantizationConfig, such as bits, group_size, sym,
data_type, and activation quantization fields.
"""
super().__init__(**kwargs)
self.enable_neuqi = enable_neuqi
self.gradient_accumulate_steps = gradient_accumulate_steps
self.iters = iters
if self.iters < 0:
logger.warning("`iters` must be non-negative, reset it to 200")
self.iters = 200
# lr/minmax_lr depend on `bits`, which may still be unresolved here
# (e.g. only `scheme=` was given) -- finalize_scheme() fills them in.
self.lr = lr
self.minmax_lr = minmax_lr
# Whether lr/minmax_lr are auto-derived; set properly in finalize_scheme().
# Used to enable per-layer (mixed-bit) lr selection during tuning.
self.lr_is_auto = lr is None
self.minmax_lr_is_auto = minmax_lr is None
self.lr_scheduler = lr_scheduler
self.nblocks = nblocks
self.momentum = momentum
self.enable_alg_ext = enable_alg_ext
self.enable_minmax_tuning = enable_minmax_tuning
self.enable_norm_bias_tuning = enable_norm_bias_tuning
if self.enable_norm_bias_tuning:
logger.warning("the `enable_norm_bias_tuning` feature is experimental and currently has limited support.")
self.not_use_best_mse = not_use_best_mse
self.dynamic_max_gap = dynamic_max_gap
self.enable_quanted_input = enable_quanted_input
self.optimizer = optimizer
self.enable_adam = enable_adam
self.enable_lfq = enable_lfq
if self.enable_lfq:
logger.warning_once("the `enable_lfq` feature is experimental and currently has limited model support.")
self.lfq_loss = lfq_loss
if self.lfq_loss not in ("ce", "dtk", "rkl", "tk"):
raise ValueError(f"`lfq_loss` must be one of 'ce', 'dtk', 'rkl' or 'tk', got {self.lfq_loss!r}")
self.lfq_top_k = lfq_top_k
if self.lfq_top_k <= 0:
raise ValueError("`lfq_top_k` must be positive")
self.lfq_temperature = lfq_temperature
if self.lfq_temperature <= 0:
raise ValueError("`lfq_temperature` must be positive")
self.lfq_num_blocks = lfq_num_blocks
if self.lfq_num_blocks <= 0:
raise ValueError("`lfq_num_blocks` must be positive")
self.lfq_mse_weight = lfq_mse_weight
if self.lfq_mse_weight < 0:
raise ValueError("`lfq_mse_weight` must be non-negative")
# Legacy QAD flag: configuration normalization routes this to QADConfig
# and its whole-model quantizer, independently of block-wise nblocks.
self.enable_qad = enable_qad
if self.enable_qad:
self.enable_lfq = True
# QADConfig emits its own (more specific) warning, so skip the generic one there.
if self.enable_qad and self._warn_enable_qad:
logger.warning_once(
"the `enable_qad` (quantization-aware distillation) mode is experimental: all "
"text-decoder blocks are tuned jointly with a whole-model forward."
)
def _lr_for_bits(self, bits: int | None) -> float | None:
"""Return the auto lr heuristic for a given bit-width.
Low-bit schemes (<=3 bits) use a higher lr for better accuracy.
Returns None when lr cannot be derived (e.g. ``iters == 0``).
"""
if self.iters <= 0:
return None
# TODO need to check 4 bits lr setting for auto-round-best, 3bits only validate on small models
if self.iters >= 1000 and bits is not None and bits <= 3:
return 2.0 / self.iters
return 1.0 / self.iters
def compute_lr(self, bits: int | None) -> float | None:
"""Resolve the rounding lr for a specific layer bit-width.
When the user supplied an explicit ``lr`` it is used for every layer;
otherwise the auto heuristic is applied per-layer so that mixed-bit
configs (e.g. a 4-bit model with a few 2-bit layers) get an
appropriate lr for each layer.
"""
if not self.lr_is_auto:
return self.lr
return self._lr_for_bits(bits)
def compute_minmax_lr(self, bits: int | None) -> float | None:
"""Resolve the min-max tuning lr for a specific layer bit-width."""
if not self.minmax_lr_is_auto:
return self.minmax_lr
# minmax_lr falls back to lr when not explicitly set
return self.compute_lr(bits)
def finalize_scheme(self) -> None:
"""Resolve lr/minmax_lr once `bits` is known (low-bit schemes use a higher lr).
The scalar ``lr``/``minmax_lr`` values resolved here are derived from the
global ``bits`` and serve as defaults/fallbacks. For mixed-bit configs the
per-layer values are computed later via ``compute_lr``/``compute_minmax_lr``.
"""
# Track whether the values are auto-derived so per-layer bit widths can
# be honored during optimization (see compute_lr/compute_minmax_lr).
self.lr_is_auto = self.lr is None and self.iters > 0
self.minmax_lr_is_auto = self.minmax_lr is None
if self.lr_is_auto:
self.lr = self._lr_for_bits(self.bits)
self.minmax_lr = self.minmax_lr or self.lr
def check_configs(self) -> None:
"""Checks if the configurations are valid.
Raises:
ValueError, TypeError: If any of the configurations are invalid.
"""
super().check_config()
if self.iters < 0:
raise ValueError("`iters` must be non-negative")
if self.nblocks <= 0:
raise ValueError("`nblocks` must be positive")
if self.gradient_accumulate_steps <= 0:
raise ValueError("`gradient_accumulate_steps` must be positive")
class AdamRoundConfig(SignRoundConfig):
pass
class SignRoundV2Config(SignRoundConfig):
"""SignRound with the algorithm extension (the former ``enable_alg_ext``) enabled.
The extension is intrinsic to this config, so ``enable_alg_ext`` reads as
``True`` no matter how the config was built — including the ``__class__``
rewrite performed by :func:`normalize_algorithm_config` and direct attribute
assignment, both of which bypass ``__init__``. Select this config with
``--algorithm auto_round_v2`` (CLI) or ``alg_configs="auto_round_v2"``
(Python API); the deprecated ``--enable_alg_ext`` switch is not redeclared
for it on the CLI.
"""
@classmethod
def get_registered_args(cls) -> AlgorithmParameterRegistry:
"""Declare the SignRound flags, minus the deprecated ``--enable_alg_ext`` switch."""
registry = super().get_registered_args()
registry.parameters = [parameter for parameter in registry.parameters if parameter.field != "enable_alg_ext"]
return registry
@property
def enable_alg_ext(self) -> bool:
"""Always ``True``: the algorithm extension cannot be disabled for this config."""
return True
@enable_alg_ext.setter
def enable_alg_ext(self, value: bool) -> None:
# The extension is not optional here, so the assigned value is dropped.
pass
register_algorithm(
"auto_round",
aliases=("auto_round", "autoround", "sign_round", "signround"),
config_factory=SignRoundConfig,
summary="SignRound-style iterative block quantization.",
)
register_algorithm(
"auto_round_v2",
aliases=("auto_round_v2", "auto_roundv2", "sign_round_v2", "signroundv2"),
config_factory=SignRoundV2Config,
summary="SignRound with the algorithm extension (the former `enable_alg_ext`) enabled.",
)