MiniMax-M3 mixed MXFP8-base + NVFP4-experts PTQ export

CHANGELOG.rst

@@ -49,6 +49,7 @@ Changelog
 - Add ``rotate.mode`` to torch quantizer configs. The default ``"rotate"`` keeps the existing rotate-before-quantize behavior; ``"rotate_back"`` enables fake-quant rotate → quantize → rotate-back for TensorQuantizer.
 - Add a ``constant_amax`` ``QuantizerAttributeConfig`` field that pins a quantizer's ``amax`` to a fixed value and skips activation calibration (no forward statistics collected). Unlike ``use_constant_amax`` (which hardcodes 448.0 for KV-cache cast math and registers no buffer), ``constant_amax`` stores the constant on the ``_amax`` buffer so it is used by both the fake-quant forward and the exported scaling factor. For NVFP4 activations the exported ``input_scale`` equals ``amax / (E2M1_MAX * E4M3_MAX)``, so ``constant_amax: 2688.0`` yields ``input_scale == 1.0``. Ships a new recipe ``modelopt_recipes/general/ptq/nvfp4_experts_only_input_scale1-kv_fp8_cast.yaml`` that applies this to the MoE expert activation quantizers.
 - Add ``MaxCalibConfig.skip_forward_without_activation_calib`` (opt-in, default ``False``): when enabled, max calibration skips the ``forward_loop`` if no enabled quantizer needs data-driven activation statistics — e.g. an experts-only recipe whose activation quantizers all use ``constant_amax`` / ``use_constant_amax``, or dynamic / MX (MXFP4/MXFP8) quantization (and none has a static ``bias_calibrator``). Weight calibration still runs on the weight tensors directly, so the quantized weights are unchanged; only the wasted forward is avoided. It is opt-in because the ``forward_loop`` can carry caller-side effects (notably materializing sharded parameters under DeepSpeed ZeRO-3). The advanced algorithms that always need activations (MSE, local Hessian, SmoothQuant, SVDQuant, GPTQ) call ``max_calibrate`` directly and are unaffected. The ``nvfp4_experts_only_input_scale1-kv_fp8_cast`` recipe enables it.
+- Add ``examples/minimax_m3/hf_ptq_mixed_mxfp8_nvfp4.py`` for streaming MiniMax-M3 export and a model-specific ``hf_ptq.py`` recipe that produces an MXFP8 language-model base with MSE-calibrated NVFP4 routed experts directly from BF16. The NVFP4 expert ``input_scale`` is fixed to 1.0.
 
 **Bug Fixes**
 

docs/source/guides/10_recipes.rst

@@ -533,6 +533,8 @@ for the layout convention and recipe-lookup order.
      - Description
    * - ``huggingface/step3p5/Step3.5-Flash/ptq/nvfp4-mlp-only``
      - NVFP4 MLP-only for Step 3.5 Flash MoE model
+   * - ``huggingface/minimax_m3_vl/ptq/mxfp8_nvfp4_experts``
+     - MXFP8 language-model base with MSE-calibrated NVFP4 routed experts for MiniMax-M3
 
 
 Loading recipes

examples/minimax_m3/README.md

@@ -0,0 +1,37 @@
+# MiniMax-M3 mixed MXFP8 and NVFP4 quantization
+
+This example produces a MiniMax-M3 checkpoint with an MXFP8 base and NVFP4
+routed experts. It copies non-routed-expert tensors from the vendor MXFP8
+checkpoint and quantizes routed-expert weights from the BF16 checkpoint one MoE
+layer at a time, without loading the complete model.
+
+The vision branch, routers, shared experts, `lm_head`, and KV cache retain their
+vendor checkpoint formats. Routed-expert activation `input_scale` is fixed to
+1.0.
+
+## Setup
+
+Install ModelOpt with its Hugging Face dependencies:
+
+```bash
+pip install -e ".[hf]"
+```
+
+The script requires local vendor MXFP8 and BF16 checkpoints. It quantizes one
+BF16 MoE layer at a time and copies the vendor MXFP8 base one shard at a time,
+so it never loads either complete model.
+
+## Usage
+
+```bash
+python examples/minimax_m3/hf_ptq_mixed_mxfp8_nvfp4.py \
+    --mxfp8_ckpt /models/minimax-m3-mxfp8 \
+    --bf16_ckpt /models/minimax-m3-bf16 \
+    --recipe huggingface/minimax_m3_vl/ptq/nvfp4_experts_only \
+    --output_ckpt /models/minimax-m3-mxfp8-nvfp4 \
+    --device cuda
+```
+
+The script writes a Hugging Face checkpoint with standard safetensor shard
+names and mixed-precision metadata in `config.json` and
+`hf_quant_config.json`. This workflow was tested with PyTorch 26.05.