项目简介
NVIDIA 推出的统一模型优化库，集成量化、剪枝、蒸馏、神经架构搜索、投机解码等技术。支持 Hugging Face、PyTorch、ONNX 模型输入，可导出压缩后的检查点，无缝部署到 TensorRT-LLM、TensorRT、vLLM、SGLang 等推理框架。
README 预览
\n\n\n\n# NVIDIA Model Optimizer\n\n[](https://nvidia.github.io/Model-Optimizer)\n[](https://pypi.org/project/nvidia-modelopt/)\n[](./LICENSE)\n\n[Documentation](https://nvidia.github.io/Model-Optimizer) |\n[Roadmap](https://github.com/NVIDIA/Model-Optimizer/issues/1699) |\n[Announcement Blogs](https://nvidia.github.io/Model-Optimizer/#announcements)\n\n\n\n______________________________________________________________________\n\n**NVIDIA Model Optimizer** (referred to as **Model Optimizer**, or **ModelOpt**) is a library comprising state-of-the-art model optimization [techniques](#techniques) including quantization, pruning, Neural Architecture Search (NAS), distillation, speculative decoding and sparsity to accelerate models.\n\n**[Input]** Model Optimizer currently supports inputs of a [Hugging Face](https://huggingface.co/), [PyTorch](https://github.com/pytorch/pytorch) or [ONNX](https://github.com/onnx/onnx) model.\n\n**[Optimize]** Model Optimizer provides Python APIs for users to easily compose the above model optimization techniques and export an optimized quantized checkpoint.\nModel Optimizer is also integrated with [NVIDIA Megatron-Bridge](https://github.com/NVIDIA-NeMo/Megatron-Bridge), [Megatron-LM](https://github.com/NVIDIA/Megatron-LM) and [Hugging Face Accelerate](https://github.com/huggingface/accelerate) for training required inference optimization techniques.\n\n**[Export for deployment]** Seamlessly integrated within the NVIDIA AI software ecosystem, the quantized checkpoint generated from Model Optimizer is ready for deployment in downstream inference frameworks like [SGLang](https://github.com/sgl-project/sglang), [TensorRT-LLM](https://github.com/NVIDIA/TensorRT-LLM/tree/main/examples/quantization), [TensorRT](https://github.com/NVIDIA/TensorRT), or [vLLM](https://github.com/vllm-project/vllm). The unified Hugging Face export API now supports both transformers and diffusers models.\n\n## Latest News\n\n- [2026/09/16] [**End-to-end W4A4 NVFP4 +
常见问题 (5)
故障排除为什么当 enable_kv_cache=False 时，megatron_generate 会对 VLM 模型生成缺乏视觉依据的输出，以及如何解决？
根本原因：在 ModelOpt 的 modelopt.torch.utils.plugins.megatron_generate.megatron_generate 中（影响 0.46.0rc1 和 main），视觉输入 pixel_values、image_grid_thw 和 image_sizes 仅由 step == 0 门控。当 enable_kv_cache=False 时，每个解码步骤都会重新计算不断增长的完整 token 前缀，但第 1 步及之后的步骤运行时没有视觉嵌入，因此图像占位符 token 永远不会被替换，生成会静默地失去视觉依据（不会抛出任何错误）。当 model.config.sequence_parallel=True 时也会触发此问题，因为此时 megatron_generate 会自动回退到无缓存解码。
修复：将三个视觉张量的门控条件从 step == 0 修改为：
replay_vision_inputs = inference_context is None or step == 0将此条件应用于 pixel_values、image_grid_thw 和 image_sizes，使得在不存在推理上下文（KV cache）时，每次完整前缀重新计算都会传入视觉输入；而在 KV cache 启用时，仅在 prefill 阶段传入。
验证结果：应用补丁后，前缀 logits 不随步骤变化（max|diff| = 0.0，argmax 一致率为 1.000，而未打补丁版本为 0.529），Qwen3-VL-8B-Instruct 能够正确描述图像，而不再幻觉出无关内容。
无法打补丁时的变通方案：(1) 启用 KV cache（enable_kv_cache=True），使视觉张量仅在 prefill 阶段需要——但在使用 sequence_parallel 时不可行；或 (2) 在调用生成器函数之前，在内存中用修正后的门控条件对其进行 monkey-patch。
故障排除如何修复在具有绑定嵌入（tied embeddings）的 Megatron 模型上调用 mtq.fold_weight 时出现的 "AttributeError: 'NoneType' object has no attribute 'data'" 错误？
此崩溃发生在启用了 share_embeddings_and_output_weights=True 的 Megatron-Core 模型上（例如 Qwen3-0.6B GPTModel），原因是 output_layer 存储的 weight = None（在前向传播时借用嵌入层的权重），而 mtq.fold_weight 在解引用存储的权重时没有 None 保护。修复方法：将 TensorRT-Model-Optimizer 升级到包含 PR #2140 的版本，该 PR 使 fold_weight 跳过权重不是张量的配对。跳过是正确的做法，因为借用的张量属于嵌入模块，会在那里被折叠。临时解决方案（修复前）：不调用 mtq.fold_weight，而是手动重新实现逐对的权重折叠并加上 None 保护，即当 getattr(module, weight_name) 不是 torch.Tensor 时跳过——这正是 NeMo-RL PR #3441 中采用的方法。请注意，正常的 QAT 前向传播不会触发此 bug，因为 Megatron 插件量化的是传递给线性函数的权重参数，而不是存储的 module.weight；只有 fold_weight 会读取存储的属性。
故障排除为什么 NVIDIA ModelOpt Puzzletron 会错误估算 Mistral-Small-24B、gpt-oss-20b 或 Gemma-3 模型的 KV-cache 内存？
Puzzletron 在 modelopt/torch/puzzletron/utils/misc.py 中的 calculate_kv_dim 使用 head_size = n_embd // n_head 进行计算，而不是从模型配置中读取 head_dim。对于 head_dim != hidden_size / num_attention_heads 的模型，每个注意力层的 KV-cache 开销都是错误的：Mistral-Small-24B（head_dim 为 128，而计算值为 160）被高估了 25%，gpt-oss-20b（head_dim 为 64，而计算值为 45）被低估了 30%，Gemma-3-12B（256 对比 240）也受到影响。在 target_memory 约束下，这会使求解器倾向于错误地剪枝注意力块。修复（PR #2484）：按以下优先级解析 head 维度：qk_head_dim（如果已设置）→ 模型配置的 head_dim → 回退到 n_embd // n_head，例如 head_dim = getattr(config, 'head_dim', n_embd // n_head)，然后 kv_dim = 2 * num_kv_heads * head_dim。同时将解析后的 head 维度应用于 calculate_additive_metrics 中的注意力 FLOP 估算（此前使用 qk_head_dim or (n_embd // n_head)）。Llama-3.x、Qwen2.5-7B 和 Qwen3-8B 不受影响，因为它们的 head_dim 等于 hidden_size/num_attention_heads。
故障排除为什么 QAD（Quantization-Aware Distillation）训练在 NVIDIA Model Optimizer 中无法恢复准确率，以及什么样的训练配置可以复现 arXiv:2601.20088 的结果？
QAD 精度恢复效果不佳的最常见原因是全局批大小（global batch size）过小以及序列长度过短（例如 gbs=16、seq_len=8192 时几乎看不到改进）。根据 NVIDIA 维护者的说法，论文中的配置（例如 AceReason Nemotron 1.1 7B）使用：
- seq_len = 32768，并启用序列打包（sequence packing）
- global_batch_size = 100（约相当于 1024 个打包后的样本）
- warmup_steps = 10
- 仅训练 200–600 步（总计约 1B tokens）；如果数据充足，不要重复使用样本
- 总 token 数：约 1B
- 损失函数：前向 KL（forward KL），温度 T=1
关键要点：
1. 使用模型原始的 SFT 数据集作为蒸馏数据——这一点被强调为至关重要。
2. 通过运行实际的下游基准测试来选择最佳检查点（checkpoint），而不是仅看验证损失。
3. 论文使用的是 NeMo/Megatron-LM 路径（examples/llm_qad），该路径比 Hugging Face/FSDP2 路径（examples/llm_qat）维护得更活跃；复现时请使用 Megatron-LM。
4. 标准的优化器设置（AdamW、lr ~1e-5、cosine schedule、grad clip 1.0、BF16）即可——真正重要的是数据以及批次/序列规模。
故障排除为什么在 TensorRT Model Optimizer 中，FP8 量化张量的范围仅为 ±36 而不是 ±448（INT8 到 FP8 的缩放转换）？
在 modelopt/onnx/quantization/fp8.py 中，INT8 缩放因子通过 np_fp8_scale = (np_scale * 448.0) / 127.0 进行转换。由于 int8_scale = amax / 127 且 fp8_scale = amax / 448，数学上一致的转换应为 fp8_scale = int8_scale * (127.0 / 448.0)。当前的乘数使缩放因子膨胀约 3.5 倍，导致量化后的张量仅占用 FP8 ±448 范围中的约 ±36，并可能引发激活值爆炸、饱和/截断以及层间不均衡。NVIDIA 推荐的临时解决方案：不要转换 INT8 缩放因子，而是直接对 FP8 运行 amax 校准。这样既可避免数值膨胀（当前代码的问题），也可避免数值下溢至零（简单反向比率的问题）。注意：源代码中仍包含 scale * 448 / 127，因此在官方修复发布之前，请优先使用原生 FP8 amax 校准。