feat(heretic2-nvfp4): WORKING modelopt NVFP4+MTP seat + full recipe runbook

The fast char-rp-reasoning seat works: ~77 tok/s (vs GGUF ~59.5, base NVFP4 ~53),
MTP draft-acceptance 32-40%, mean acceptance length 2.19. Same Heretic2/NEO-CODE
model, NVFP4 + native qwen3_5_mtp spec-decode.

Full end-to-end recipe + the four landmines in docs/runbooks/heretic2-nvfp4-mtp-seat.md:
(1) load as AutoModelForImageTextToText not AutoModelForCausalLM (namespace/gibberish);
(2) modelopt format not compressed-tensors (compressed-tensors MTP = 0% accept);
(3) modelopt 0.45 <-> transformers 5.12.1 FusedMoE crash (guarded in quant_modelopt.py);
(4) vLLM 0.24.0 does NOT propagate modelopt exclude_modules to the spec-decode draft
model -> BF16 mtp head gets quantized -> shape crash; no checkpoint config fixes it
(is_layer_skipped is exact-membership not glob) -> fix is a mounted sitecustomize that
force-skips mtp.* in is_layer_skipped (upstream vLLM bug to report).

Scripts: quant_modelopt.py (FusedMoE guard + single-shard export + multimodal load),
finalize_modelopt_mtp.py (splice bf16 mtp), serve_modelopt_mtp.sh, run_quant_modelopt.sh,
sitecustomize-mtp-workaround.py.

services/heretic2-nvfp4-quant/quant_modelopt.py

@@ -93,6 +93,22 @@ def main() -> int:
     import modelopt.torch.quantization as mtq
     from modelopt.torch.export import export_hf_checkpoint
 
+    # modelopt 0.45 + transformers 5.12.1 compat guard. transformers 5.x exposes `FusedMoE` as a
+    # FUNCTION, but modelopt registers it in QuantModuleRegistry expecting an nn.Module class, so the
+    # registry scan (register_fused_experts_on_the_fly -> _get_registered_nn_class) does
+    # `issubclass(nn_cls, <function FusedMoE>)` and dies with "arg 2 must be a class". Our model is
+    # DENSE (no FusedMoE) so skipping non-class registry entries is safe. Guard the scan:
+    from modelopt.torch.opt import dynamic as _mo_dyn
+
+    def _grnc_safe(self, nn_cls):
+        for nn_cls_ in self._registry:
+            if (isinstance(nn_cls_, type) and issubclass(nn_cls, nn_cls_)
+                    and nn_cls.forward is nn_cls_.forward):
+                return nn_cls_
+        return None
+
+    _mo_dyn._DMRegistryCls._get_registered_nn_class = _grnc_safe
+
     print(f"loading grafted model (multimodal ConditionalGeneration): {args.model}", flush=True)
     model = AutoModelForImageTextToText.from_pretrained(
         args.model, torch_dtype="auto", device_map="auto", trust_remote_code=True,
@@ -120,7 +136,9 @@ def main() -> int:
     mtq.quantize(model, cfg, forward_loop=forward_loop)
 
     print(f"exporting modelopt HF checkpoint -> {args.out}", flush=True)
-    export_hf_checkpoint(model, export_dir=args.out)
+    # Force a SINGLE shard (default max_shard_size 10GB would split the ~14GB output into 3 shards,
+    # but splice_mtp.py expects a single <out>/model.safetensors to add the bf16 mtp.* into).
+    export_hf_checkpoint(model, export_dir=args.out, max_shard_size="1TB")
     tok.save_pretrained(args.out)
     print("DONE. Next: splice_mtp.py <out> <graft>  then serve "
           "--quantization modelopt --speculative-config "