[Ti-Tai Wang (titaiwangms)]

Describe your changes

Add native PyTorch INT3 weight quantization for Olive's RTN, KQuant, and GPTQ passes, including explicit mixed-precision overrides and checkpoint save/reload.

• Encode unsigned 3-bit codes as row-independent, LSB-first packed byte streams. Eight codes occupy three bytes; partial rows have zero padding in unused high bits.
• Share packed-buffer sizing between quantization and checkpoint placeholders, including asymmetric zero points. Preserve existing INT2/INT4/INT8 encodings and leave default search candidates unchanged.
• Allow INT3 in AutoClip's floating-weight clipping simulation.
• Reject native INT3 at ONNX conversion, ModelBuilder, and MobiusBuilder boundaries until compatible operator/runtime support is available. External quantization backends do not implicitly gain INT3 support.
• Add independent byte-oracle, dequantization, native-pass, mixed-precision, checkpoint, and export-boundary tests, plus format and limitation documentation.

This is Torch checkpoint support, not an INT3 ONNX export or accelerated-kernel implementation. No real-model accuracy or performance qualification is claimed. Quantized fused-MoE forward execution currently requires eager experts.

Validation

Validated on an isolated branch based on upstream main at ba856b69ec21a3080319c7affce62dc1546b94e2.

HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 timeout 300 python -m pytest test/common/quant/test_utils.py test/common/quant/test_tensor.py test/common/quant/test_hf_utils.py test/common/quant/test_state_dict.py test/common/hf/test_quant.py test/passes/pytorch/test_int3.py test/passes/onnx/test_mobius_model_builder.py -q --disable-warnings --maxfail=3

Result: 712 passed.

HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 timeout 180 python -m pytest test/common/quant/test_forward_parity.py test/passes/onnx/test_model_builder.py test/passes/pytorch/test_kquant.py -k 'not real_hf and (forward_parity or onnx_export_parity or export_rejected or rejects_int3 or find_qparams or saved_test_model_path or config_only_test_dir or single_file_fallback or multi_file_output or prechecks_extra_options or structured_config or cpu_embedding or active_loader)' -q --disable-warnings --maxfail=3

Result: 42 passed, 43 deselected.

After removing a redundant test import:

HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 timeout 120 python -m pytest test/passes/onnx/test_model_builder.py -k 'rejects_int3' -q --disable-warnings

Result: 3 passed, 24 deselected.

timeout 300 lintrunner -a
timeout 300 lintrunner --take PYLINT --output oneline
ruff check --ignore CPY001 $(git diff --cached --name-only -- '*.py')
ruff format --check $(git diff --cached --name-only -- '*.py')
git diff --cached --check

Result: All commands exited successfully; Ruff checked/formatted all 21 changed Python files.

timeout 300 lintrunner --output oneline

Result: Failed only with 21 RUFF/CPY001 copyright-notice findings. This rule also flags existing unchanged files with the repository's copyright headers. No unrelated headers or lint configuration were changed; the same finding also affects the new test file.

The full test suite, hardware-specific kernels, and real-model download-dependent tests were not run.

Checklist before requesting a review

• Add unit tests for this change.
• Make sure all tests can pass.
• Update documents if necessary.
• Lint and apply fixes to your code by running lintrunner -a
• Is this a user-facing change? If yes, give a description of this change to be included in the release notes.

Release notes: Native PyTorch RTN, KQuant, and GPTQ now support INT3 weight checkpoints and explicit mixed-precision INT3 overrides. INT3 uses tightly packed storage and supports save/reload and eager dequantized execution; ONNX export and accelerated INT3 inference are not yet supported.

(Optional) Issue link

Related runtime design discussion: microsoft/onnxruntime#32657. This change does not depend on or implement that runtime proposal.

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation is internally consistent and includes focused coverage for packing, persistence, mixed precision, and unsupported export boundaries.

Review effort: Balanced
Findings: None

What changed in this PR

Adds native INT3 checkpoint quantization for PyTorch RTN, KQuant, and GPTQ while explicitly blocking unsupported export paths.

Changes:

• Implements row-local, LSB-first INT3 packing, unpacking, placeholders, and reload support.
• Enables INT3 in native passes, mixed precision, and AutoClip.
• Adds export guards, documentation, and comprehensive tests.

File	Description
olive/​constants.py	Adds the 3-bit precision enum.
olive/​common/​quant/​utils.py	Implements INT3 packing and unpacking.
olive/​common/​quant/​hf_utils.py	Supports INT3 checkpoint loading and export validation.
olive/​common/​hf/​quant.py	Rejects INT3 ONNX export.
olive/​passes/​pytorch/​quant_utils.py	Exposes INT3 to native quantization passes.
olive/​passes/​pytorch/​kquant.py	Documents KQuant INT3 support.
olive/​passes/​pytorch/​autoclip.py	Allows INT3 clipping simulation.
olive/​passes/​pytorch/​autogptq.py	Rejects INT3 in AutoGPTQ.
olive/​passes/​pytorch/​gptqmodel.py	Rejects INT3 in GptqModel.
olive/​passes/​pytorch/​autoawq.py	Rejects INT3 in AutoAWQ.
olive/​passes/​onnx/​model_builder.py	Blocks native INT3 model building.
olive/​passes/​onnx/​mobius_model_builder.py	Blocks native INT3 Mobius builds.
olive/​passes/​onnx/​inc_quantization.py	Rejects INT3 in INC weight-only quantization.
test/​common/​quant/​test_utils.py	Tests packed INT3 byte layout and round trips.
test/​common/​quant/​test_tensor.py	Tests INT3 dequantization and tensor operations.
test/​common/​quant/​test_hf_utils.py	Tests placeholders and export validation.
test/​common/​hf/​test_quant.py	Tests INT3 export rejection.
test/​passes/​pytorch/​test_int3.py	Covers passes, checkpoints, MoE, and mixed precision.
test/​passes/​pytorch/​test_kquant.py	Extends KQuant parameter tests to INT3.
test/​passes/​onnx/​test_model_builder.py	Tests ModelBuilder rejection.
test/​passes/​onnx/​test_mobius_model_builder.py	Tests Mobius rejection.
docs/​source/​features/​quantization.md	Documents format, usage, and limitations.
skills/​olive/​references/​quantization-onboarding.md	Updates quantization onboarding guidance.

---

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

[Ti-Tai Wang (titaiwangms)]

Superseded by #2716, which uses a branch pushed directly to microsoft/Olive instead of the fork.