Support SVDQuant

[changwangss]

Description

Please briefly describe your main changes, the motivation.

Type of Change

new feature

Related Issues

Fixes or relates to #

Checklist Before Submitting

• My code has been tested locally.
• Documentation has been updated as needed.
• New or updated tests are included where applicable.
• The CUDA CI has passed. You can trigger it by commenting /azp run Unit-Test-CUDA-AutoRound.

[AutoRoundBot]

/azp run Unit-Test-CUDA-AutoRound

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[AutoRoundBot]

/azp run Unit-Test-CUDA-AutoRound

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[AutoRoundBot]

/azp run Unit-Test-CUDA-AutoRound

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[Copilot]

Pull request overview

Adds experimental SVDQuant support to AutoRound, including a new CLI algorithm stage, smooth-search + residual-iteration implementation, and a runtime-loadable Nunchaku export path targeting Diffusers FLUX + MXFP4.

Changes:

• Introduces the SVDQuant transform pipeline (config, smooth search adapters, residual iteration, wrapper module) and registers it in the algorithm registry + CLI.
• Adds svdquant_nunchaku export format, plus Nunchaku-compatible tensor codecs/adapters (MXFP4 residual packing, W4A16 AdaNorm packing, FLUX adapter + metadata validation).
• Updates diffusion calibration/save flows and expands CPU unit tests to cover CLI behavior, diffusion device placement, SVDQuant transform behavior, and export schemas.

Reviewed changes

Copilot reviewed 37 out of 37 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/unit/test_cpu/utils/test_cli_usage.py	Adds CLI parsing/composition tests for svdquant (hyphenated options, defaults, composition ordering).
test/unit/test_cpu/models/test_diffusion.py	Adds unit tests for diffusion calibration device placement/offload behavior.
test/unit/test_cpu/export/test_svdquant_w4a16.py	Adds tests for W4A16 AdaNorm packing/RTN quantization roundtrips.
test/unit/test_cpu/export/test_svdquant_nunchaku_format.py	Adds tests for the new svdquant_nunchaku output format and diffusion save behavior.
test/unit/test_cpu/export/test_svdquant_nunchaku_export.py	Adds extensive tests for SVDQuant Nunchaku tensor collection/serialization/metadata validation.
test/unit/test_cpu/export/test_svdquant_mxfp4.py	Adds tests for low-rank packing and MXFP4 residual packing/unpacking parity.
test/unit/test_cpu/export/test_svdquant_flux_adapter.py	Adds tests for FLUX adapter mapping, schema validation, CUDA/CPU decomposition behavior, and metadata.
test/unit/test_cpu/algorithms/test_svdquant.py	Adds unit tests for SVDQuant transform composition and FLUX targeting behavior.
test/unit/test_cpu/algorithms/test_svdquant_smooth.py	Adds unit tests for smooth candidate generation, scale validation, and bounded calibration reservoir behavior.
test/unit/test_cpu/algorithms/test_svdquant_smooth_adapters.py	Adds tests for FLUX smooth-group discovery and grouping correctness.
test/unit/test_cpu/algorithms/test_svdquant_residual.py	Adds tests for residual QDQ correctness and residual-iteration selection/early-stop behavior.
test/unit/test_cpu/algorithms/test_block_runner.py	Adds tests for indexed single-sample diffusion/regular output batch-dimension preservation.
docs/svdquant_details.md	Adds experimental SVDQuant design/usage/export documentation.
auto_round/utils/common.py	Registers svdquant_nunchaku in supported format list.
auto_round/export/svdquant_w4a16.py	Implements W4A16 AdaNorm RTN quantization and packing/unpacking/dequantization utilities.
auto_round/export/svdquant_nunchaku.py	Implements SVDQuant tensor collection, adapter protocol, residual packing, and safetensors serialization + metadata validation.
auto_round/export/svdquant_mxfp4.py	Implements MXFP4 codecs plus Nunchaku-compatible residual packing and low-rank tensor packing.
auto_round/export/svdquant_adapters/flux.py	Implements FLUX adapter mapping, extra tensor export (AdaNorm/RMS/top-level), and full-schema validation.
auto_round/export/svdquant_adapters/init.py	Adds adapter resolution (auto/flux/identity) and exports adapter utilities.
auto_round/export/formats/base.py	Adds requires_full_model_export flag to output-format base.
auto_round/export/formats/backends/svdquant_nunchaku.py	Adds new svdquant_nunchaku output format backend with strict scheme validation and runtime-adapter enforcement.
auto_round/export/formats/backends/init.py	Registers and exports the new SVDQuantNunchakuFormat.
auto_round/compressors/diffusion_mixin.py	Updates diffusion save flow (format defaulting) and rewrites model_index.json entries for Nunchaku runtime loading; removes accelerate hooks after model offload calibration.
auto_round/compressors/base.py	Disables immediate packing/saving for formats that require full-model export; updates immediate packing guard.
auto_round/cli/algorithms.py	Registers svdquant CLI handler and algorithm factory; adds CLI args -> SVDQuantConfig mapping.
auto_round/calibration/diffusion.py	Adds _prepare_pipeline_for_calibration helper to support low-GPU-mem calibration via model CPU offload.
auto_round/algorithms/transforms/svdquant/wrapper.py	Adds SVDQuantLinear wrapper module combining residual + low-rank branches with optional activation QDQ.
auto_round/algorithms/transforms/svdquant/smooth.py	Adds smooth-search candidate generation, scale building/validation/stats, and best-candidate selection.
auto_round/algorithms/transforms/svdquant/smooth_adapters/flux.py	Adds FLUX-specific smooth group discovery and evaluation module routing.
auto_round/algorithms/transforms/svdquant/smooth_adapters/base.py	Adds generic smooth-group abstraction, output normalization, and module path resolution helpers.
auto_round/algorithms/transforms/svdquant/smooth_adapters/init.py	Wires smooth-group discovery for FLUX vs generic modules.
auto_round/algorithms/transforms/svdquant/residual.py	Adds deployable RTN QDQ helpers and residual-iteration (alternating decomposition/QDQ) utilities.
auto_round/algorithms/transforms/svdquant/config.py	Adds SVDQuantConfig with validation and CLI-friendly normalization.
auto_round/algorithms/transforms/svdquant/apply.py	Implements SVDQuantTransform pipeline member (grouping, smoothing, decomposition, replacement of nn.Linear).
auto_round/algorithms/transforms/svdquant/init.py	Exposes SVDQuant public transform/config/wrapper symbols.
auto_round/algorithms/registry.py	Ensures SVDQuant pipeline member module is imported/registered.
auto_round/algorithms/block_runner.py	Adjusts block runner behavior for batch-size=1 indexed execution (removes special unsqueeze path).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[AutoRoundBot]

/azp run Unit-Test-CUDA-AutoRound

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[n1ck-guo]

LGTM.
My personal suggestion is to simplify the unit tests, some of them seem not necessary.

[changwangss]

LGTM. My personal suggestion is to simplify the unit tests, some of them seem not necessary.

Addressed in 4c67105. The four real smoke combinations are covered by the parameterized test at test_svdquant.py:70-144, while redundant implementation-detail tests were removed.

[AutoRoundBot]

/azp run Unit-Test-CUDA-AutoRound

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[AutoRoundBot]

/azp run Unit-Test-CUDA-AutoRound

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).