迁移避坑指南从旧量化工具链切到 Model-Optimizer这些 API 差异逐个对【免费下载链接】Model-OptimizerA unified library of SOTA model optimization techniques like quantization, distillation, pruning, neural architecture search, speculative decoding, etc. It compresses deep learning models for downstream deployment frameworks like TensorRT-LLM, TensorRT, vLLM, etc. to optimize inference speed.项目地址: https://gitcode.com/GitHub_Trending/te/Model-Optimizer当 2025 年底 TensorRT Model Optimizer 正式更名 NVIDIA Model Optimizer、并于 2026 年初发布提速 50% 的 v1.2 版本时大量仍握着pytorch-quantization、TensorRTtrtexec、ONNX Runtime 量化脚本的老玩家开始动手迁移。社区里流传的迁移指南往往只讲新工具更好用却很少回答一个实际问题把旧的量化/校准/导出代码改成 Model OptimizerModelOpt风格究竟要动哪些 API哪些看似一样的参数其实语义全变本文不写营销话术而是直接对照仓库源码与官方变更记录把从旧工具链迁到 ModelOpt 的真实差异逐条拆开量化配置怎么写、校准怎么驱动、导出链路怎么换以及迁移后如何做精度与性能回退检查。文中的每一段代码都来自仓库真实文件你可以按路径逐一核对。一、先认清一件事这是另一套范式不是换皮旧工具链TensorRT 隐式量化、trtexec --int8、ONNX Runtime 静态量化的核心是量化 编译一步到位calibrator 收集激活范围builder 直接产出 engine。而 ModelOpt 的哲学完全不同——它在 PyTorch 里做模拟量化fake quantization只把低精度计算演出来用于校准和验证真正的加速要等导出到 TensorRT / TensorRT-LLM / vLLM / SGLang 等后端才发生。官方文档在 PyTorch Quantization 里写得很直白ModelOpt quantization is fake quantization, which means it only simulates the low-precision computation in PyTorch. Real speedup and memory saving should be achieved by exporting the model to deployment frameworks.这句提示是所有迁移误区的总源头如果你在 ModelOpt 上做完量化后直接跑 PyTorch 推理测速度性能一定没提升这不是工具坏了而是流程不对。迁移的第一步是把量化即编译的旧心智换成量化→校准→导出→部署四段式的新心智。二、API 对照量化配置从塞模块变成写配置2.1 旧世界手动插 quantizer calibrator在pytorch-quantization时代你需要手写TensorQuantizer替换网络层、维护自己的CalibQuantizer再对接 TensorRT 的EntropyCalibrator2/MinMaxCalibrator生成 calibration cache。配置与代码深度耦合换一个量化格式往往要改多处。2.2 新世界一个 config 字典 一个 forward loopModelOpt 把量化哪些层、用什么格式、怎么校准收敛成一份配置一行调用完成替换与校准model_quant.py 中的quantize()import modelopt.torch.quantization as mtq model mtq.quantize(model, mtq.NVFP4_DEFAULT_CFG, forward_loop)官方入口在 hf_ptq/README.md 中给出完整示例mtq.quantize(model, config, forward_loop)会原地把模块替换为量化版本并按config[algorithm]驱动forward_loop完成校准。forward_loop是迁移中第一个容易踩坑的点旧习惯calibrator 是一个独立对象喂数据、收统计都靠它新习惯forward loop 只是一个带model参数的函数内部把校准数据 loader 跑一遍即可。仓库还明确警告无参的forward_loop用法已进入弃用流程model_quant.py中calibrate()会发DeprecationWarning。配置结构本身是字典 顺序覆盖详见 config.pyMY_QUANT_CFG { quant_cfg: [ # 先全部禁用 {quantizer_name: *, enable: False}, # 再按通配符精确开启 {quantizer_name: *weight_quantizer, cfg: {num_bits: 8, axis: 0}}, {quantizer_name: *input_quantizer, cfg: {num_bits: 8, axis: None}}, # 对特定父模块排除 {quantizer_name: *input_quantizer, parent_class: nn.LeakyReLU, enable: False}, ], algorithm: max, }三个细节务必记牢列表按顺序生效后写的覆盖先写的。官方推荐先deny-all、再逐格式开启、最后追加默认排除BatchNorm、LM head、MoE router的三段式写法这直接决定了你的自定义 config 写在哪、怎么写。cfg可以是一个列表用于 W4A8 这类先 INT4 再 FP8的顺序量化SequentialQuantizer这是旧工具链没有的概念。通配符直接打在模块名上*weight_quantizer、*input_quantizer想跳过lm_head只需追加一条{quantizer_name: *lm_head*, enable: False}。2.3 CLI 迁移--qformat让位给--recipe如果你靠命令行脚本过日子这条差异杀伤力最大。CHANGELOG 记录了明确的演进旧版examples/hf_ptq/hf_ptq.py的--qformat/--kv_cache_qformat已弃用改由--recipe承载modelopt_recipes/configs/ptq/presets/model/下躺着 40 个预置配方presets/model从fp8.yaml、int8_smoothquant.yaml到nvfp4.yaml、w4a8_awq_beta.yaml一应俱全。YAML 配方用$import机制组合公共单元nvfp4.yamlimports: base_disable_all: configs/ptq/units/base_disable_all w4a4_nvfp4_nvfp4: configs/ptq/units/w4a4_nvfp4_nvfp4 default_disabled_quantizers: configs/ptq/units/default_disabled_quantizers algorithm: max quant_cfg: - $import: base_disable_all - $import: w4a4_nvfp4_nvfp4 - $import: default_disabled_quantizers配方把量化配置 校准算法 KV cache 设置收在一个文件里避免了三组 flag 各自为政导致的漂移。迁移时注意旧--qformat的短名int8_sq、nvfp4_awq等已在 0.47 移除直接用配方 basename。三、校准从 calibrator 对象到 forward-loop 驱动3.1 算法选择与参数注入calibrate()model_quant.py支持的算法与旧工具链差异明显max最简校准等价于旧 MinMax但仅权重量化 max时不需要 forward loopsmoothquant迁移量最大的旧用户通常会选它做 INT8 平滑量化awq_lite / awq_full / awq_clipAWQ 家族旧链路上要自己找脚本新算法SVDQuant、Local-Hessian、NVFP4 MSE等则是旧工具链完全没有的。算法可以用字符串也可以传字典注入超参例如{method: awq_clip, max_co_batch_size: 4096}。仓库示例还展示了按专家比例校准 MoEbuild_quant_cfg()example_utils.py会把moe_calib_experts_ratio注入 algorithm 字典——这是迁移 MoE 模型时最容易被忽略的调参入口。3.2 校准数据要求校准数据规模在官方指南里有明确推荐128–512 个样本PyTorch Quantization默认混合cnn_dailymail与nemotron-post-training-dataset-v2两个数据集。旧工具链的 calibration cache 文件.cache在 ModelOpt 里没有对应概念——统计量全部在校准过程中动态收集并写入模型内部的_amax你不需要也不能复用旧的 cache 文件。3.3 迁移后新增的防呆检查这是 ModelOpt 比旧工具链体贴的地方也是迁移后第一次跑通时最容易愣住的点quantize()内部有两个量化是否真的生效的守卫model_quant.py_check_weight_quantization_took_effect配置要求量化权重、但通配符没匹配到任何模块时直接抛RuntimeError而不是像旧工具那样静默产出一个根本没量化的模型。官方注释点出了动机早期版本就是默默导出quant_algo: null的空量化 checkpointMoE 架构的模块命名与通用配方不匹配时尤其容易触发。误报时可用环境变量MODELOPT_SKIP_WEIGHT_QUANT_CHECK1跳过管道并行下某 rank 本地确实没有目标模块时用。_check_indexer_quantization_took_effect稀疏注意力 indexer 的同类守卫。迁移时的正确姿势报错先读信息——它通常会告诉你配方没匹配上架构的模块命名去 model_type 配方目录 找对应模型的专属配方而不是改错环境变量硬跳过。四、导出链路从出 engine到出统一 checkpoint4.1 最大的 API 替换export_hf_checkpoint旧链路终点是trtexec --onnxxxx.onnx --saveEnginexxx.engine或 Python builder 直接出 engine。ModelOpt 的终点是统一 Hugging Face checkpointUnified HuggingFace Checkpointfrom modelopt.torch.export import export_hf_checkpoint with torch.inference_mode(): export_hf_checkpoint(model, export_dir)产出物是safetensors 权重 hf_quant_config.json量化配置 结构/分词器/元数据 jsonTensorRT-LLM≥ v1.2.0、vLLM≥ v0.10.1、SGLang≥ v0.4.10都能直接加载。同一个 checkpoint 喂三个后端这是旧一次编译一个 engine的链路做不到的。4.2 旧导出 API 正在退场CHANGELOG 白纸黑字export_tensorrt_llm_checkpoint与torch_to_tensorrt_llm_checkpoint已发DeprecationWarning计划在 0.49.0 移除实现迁移到modelopt.torch.export.trtllm子包get_model_type等返回 TRT-LLM 模型名的辅助函数同样弃用改用model.config.model_type。如果你还在 import 这些旧函数迁移的第一步就是换成export_hf_checkpoint。4.3 状态保存modelopt_state是新的checkpoint 灵魂量化、剪枝、蒸馏都会改动模型架构和权重ModelOpt 把修改记录在modelopt_state里Saving Restoringimport modelopt.torch.opt as mto # 一起存 mto.save(model, modelopt_model.pth) # 或只存状态权重用自己的方式存 torch.save(mto.modelopt_state(model), modelopt_state.pth) # 恢复 mto.restore(model, modelopt_model.pth)迁移要点架构修改必须随状态一起恢复光存state_dict会丢掉量化的_amax与替换后的模块结构。另外 CHANGELOG 提醒携带 0.45 之前旧版layerwise布尔字段的modelopt_state在新版恢复时直接校验失败而不是自动迁移需先用 0.45/0.46 重存一次。4.4 真实压缩与 GGML新的导出分支对显存敏感的场景mtq.compress()compress.py把权重真正压成低比特存储。统一导出还支持 GGML 布局IQ1_S / IQ2_XS / Q8_0此时权重被替换为字节精确的 GGML blockuint8 张量形状为[*logical_shape[:-1], logical_shape[-1] // block_size, payload_bytes]。坑在于ModelOpt 的 per-tensor FP8 格式在 GGML 中没有等价类型FP8 checkpoint 转 GGUF 必须先转成 GGML 支持的张量类型做不到无损直转。规划 GGML 落地前务必先确认这条限制。五、ONNX 侧的对应差异QDQ 是终点不是起点如果迁移的是 ONNX 链路检测、分割等视觉模型入口换成modelopt.onnx.quantization的quantize()quantize.py、ONNX Quantizationimport modelopt.onnx.quantization as moq calibration_data np.load(calibration_data_path) # npz/npydict 键必须与 ONNX 输入名一致 moq.quantize( onnx_pathonnx_path, calibration_datacalibration_data, output_pathquant.onnx, quantize_modeint8, # int8 | int4 | fp8 calibration_methodmax, # int8/fp8: entropy|max; int4: awq_clip|awq_lite|awq_full|rtn_dq )对照旧 ONNX Runtime 静态量化差异集中在四点校准数据格式只收 npz/npy且字典键必须匹配模型输入名也可以用CalibrationDataReader或calibration_shapes指定输入形状。执行 Provider 顺序calibration_eps[cpu, cuda:0, trt]含自定义算子时trt会被自动追加TensorRT ≥ 10.0 才支持 TensorRT EP。产出是带 QDQ 的 ONNX不是 engine文档明确generated ONNX should be compiled into TensorRT engine才真正提速——trtexec --onnxquant.onnx --saveEnginequant.engine。这一步与旧链路看似相同但 QDQ 插入遵循 TensorRT 的显式量化规则op_types_to_quantize、nodes_to_exclude、trt_plugins等参数直接决定 QDQ 放哪、精度损失在哪。模块被移除modelopt.onnx.quantization.ort_patching与graph_utils已无兼容层直接删除旧的 patch 写法需按迁移映射改用graph_rewrites等新模块见 CHANGELOG。六、迁移后必做的回退检查清单6.1 精度回退打印量化摘要mtq.print_quant_summary(model)核对 quantizer 是否落到预期层上这是定位静默未量化最快的抓手。读导出配置导出的hf_quant_config.json里quant_algo不能是nullquantized_layers不能为空——这正是 3.3 节守卫要防的失败模式。先选对配方再谈精度NVFP4 默认配方全层量化官方在 hf_ptq/README.md 明确建议高精度优先用NVFP4_MLP_ONLY_CFG只量化 MLP/MoE、NVFP4_EXPERTS_ONLY_CFG只量化专家层或NVFP4_OMLP_ONLY_CFG外加o_proj保住注意力 QKV 投影的高精度。校准数据一致性旧 cache 不可复用校准集与验证集要隔离MoE 记得调moe_calib_experts_ratio。低比特精度救济若精度回退超预期检查block_sizesconfig.py 的QuantizerAttributeConfig——低比特必须用 per-block如{-1: 32}、{type: dynamic}还能用scale_bits/scale_block_sizes做 scale 的双重量化4-bit 精度不足时考虑 AWQ 或 SVDQuant再不行就上 QAT/QAD 训练补救。6.2 性能回退别在 PyTorch 里测速fake quant 不加速只有导出后测4.1/5.1 节。对比基准用trtexec报告的 Latency / Throughput同参数、同 GPU、同精度档位才可比。确认后端版本统一 checkpoint 有最低版本要求TRT-LLM v1.2.0 / vLLM v0.10.1 / SGLang v0.4.10旧容器加载新格式大概率报KeyError或结构错误——这是迁移后最常见的环境坑。验证收益预期仓库最新成果给出了可参照的量化收益量级——Nemotron 3 Ultra 550B 量化到 NVFP4 后解码吞吐最高 5.9×、精度持平 BF16Qwen3.6-35B-A3B 走 NVFP4 W4A4 PTQ 量化感知蒸馏后vLLM 吞吐 1.30×、checkpoint 缩小 3.1×。你的模型跑不出这个数不等于失败先对照是否漏了导出步骤、KV cache 是否量化、配方是否选对。分布式注意FSDP2 下export_hf_checkpoint需要所有 rank 参与 collectives只有 rank 0 写文件offload 流式导出路径不支持save_modelopt_stateTrue——这些都会在迁移后第一次多卡运行时冒出来。七、迁移总路线图把上面的差异收敛成一张行动清单照着走基本不会踩空改入口mtq.quantize(model, config, forward_loop)替换手动插 quantizer calibratorforward_loop记得带model参数。改配置--qformat换成--recipe或 YAML 配方自定义格式按deny-all → 逐格式开启 → 默认排除顺序写quant_cfg。改校准丢弃旧 cache 文件用 128–512 样本的 forward loop先max打底再按需上 SmoothQuant / AWQ / SVDQuant。改导出export_hf_checkpoint替代export_tensorrt_llm_checkpoint/trtexec状态用mto.save/mto.restore或单独存modelopt_state。回退验证print_quant_summaryhf_quant_config.json验结构导出后测速验证性能必要时用block_sizes、配方选择与 QAT/QAD 兜底精度。ModelOpt 这套链路最反直觉、也最值得记住的一句话是量化在校准性能在导出。想清楚这句迁移路上的大多数性能没提升和导出就报错都能少走一半弯路。【免费下载链接】Model-OptimizerA unified library of SOTA model optimization techniques like quantization, distillation, pruning, neural architecture search, speculative decoding, etc. It compresses deep learning models for downstream deployment frameworks like TensorRT-LLM, TensorRT, vLLM, etc. to optimize inference speed.项目地址: https://gitcode.com/GitHub_Trending/te/Model-Optimizer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/16 12:10:17 · 阅读 1.2k 迁移避坑指南：从旧量化工具链切到 Model-Optimizer，这些 API 差异逐个对
迁移避坑指南从旧量化工具链切到 Model-Optimizer这些 API 差异逐个对【免费下载链接】Model-OptimizerA unified library of SOTA model optimization techniques like quantization, distillation, pruning, neural architecture search, speculative decoding, etc. It compresses deep learning models for downstream deployment frameworks like TensorRT-LLM, TensorRT, vLLM, etc. to optimize inference speed.项目地址: https://gitcode.com/GitHub_Trending/te/Model-Optimizer当 2025 年底 TensorRT Model Optimizer 正式更名 NVIDIA Model Optimizer、并于 2026 年初发布提速 50% 的 v1.2 版本时大量仍握着pytorch-quantization、TensorRTtrtexec、ONNX Runtime 量化脚本的老玩家开始动手迁移。社区里流传的迁移指南往往只讲新工具更好用却很少回答一个实际问题把旧的量化/校准/导出代码改成 Model OptimizerModelOpt风格究竟要动哪些 API哪些看似一样的参数其实语义全变本文不写营销话术而是直接对照仓库源码与官方变更记录把从旧工具链迁到 ModelOpt 的真实差异逐条拆开量化配置怎么写、校准怎么驱动、导出链路怎么换以及迁移后如何做精度与性能回退检查。文中的每一段代码都来自仓库真实文件你可以按路径逐一核对。一、先认清一件事这是另一套范式不是换皮旧工具链TensorRT 隐式量化、trtexec --int8、ONNX Runtime 静态量化的核心是量化 编译一步到位calibrator 收集激活范围builder 直接产出 engine。而 ModelOpt 的哲学完全不同——它在 PyTorch 里做模拟量化fake quantization只把低精度计算演出来用于校准和验证真正的加速要等导出到 TensorRT / TensorRT-LLM / vLLM / SGLang 等后端才发生。官方文档在 PyTorch Quantization 里写得很直白ModelOpt quantization is fake quantization, which means it only simulates the low-precision computation in PyTorch. Real speedup and memory saving should be achieved by exporting the model to deployment frameworks.这句提示是所有迁移误区的总源头如果你在 ModelOpt 上做完量化后直接跑 PyTorch 推理测速度性能一定没提升这不是工具坏了而是流程不对。迁移的第一步是把量化即编译的旧心智换成量化→校准→导出→部署四段式的新心智。二、API 对照量化配置从塞模块变成写配置2.1 旧世界手动插 quantizer calibrator在pytorch-quantization时代你需要手写TensorQuantizer替换网络层、维护自己的CalibQuantizer再对接 TensorRT 的EntropyCalibrator2/MinMaxCalibrator生成 calibration cache。配置与代码深度耦合换一个量化格式往往要改多处。2.2 新世界一个 config 字典 一个 forward loopModelOpt 把量化哪些层、用什么格式、怎么校准收敛成一份配置一行调用完成替换与校准model_quant.py 中的quantize()import modelopt.torch.quantization as mtq model mtq.quantize(model, mtq.NVFP4_DEFAULT_CFG, forward_loop)官方入口在 hf_ptq/README.md 中给出完整示例mtq.quantize(model, config, forward_loop)会原地把模块替换为量化版本并按config[algorithm]驱动forward_loop完成校准。forward_loop是迁移中第一个容易踩坑的点旧习惯calibrator 是一个独立对象喂数据、收统计都靠它新习惯forward loop 只是一个带model参数的函数内部把校准数据 loader 跑一遍即可。仓库还明确警告无参的forward_loop用法已进入弃用流程model_quant.py中calibrate()会发DeprecationWarning。配置结构本身是字典 顺序覆盖详见 config.pyMY_QUANT_CFG { quant_cfg: [ # 先全部禁用 {quantizer_name: *, enable: False}, # 再按通配符精确开启 {quantizer_name: *weight_quantizer, cfg: {num_bits: 8, axis: 0}}, {quantizer_name: *input_quantizer, cfg: {num_bits: 8, axis: None}}, # 对特定父模块排除 {quantizer_name: *input_quantizer, parent_class: nn.LeakyReLU, enable: False}, ], algorithm: max, }三个细节务必记牢列表按顺序生效后写的覆盖先写的。官方推荐先deny-all、再逐格式开启、最后追加默认排除BatchNorm、LM head、MoE router的三段式写法这直接决定了你的自定义 config 写在哪、怎么写。cfg可以是一个列表用于 W4A8 这类先 INT4 再 FP8的顺序量化SequentialQuantizer这是旧工具链没有的概念。通配符直接打在模块名上*weight_quantizer、*input_quantizer想跳过lm_head只需追加一条{quantizer_name: *lm_head*, enable: False}。2.3 CLI 迁移--qformat让位给--recipe如果你靠命令行脚本过日子这条差异杀伤力最大。CHANGELOG 记录了明确的演进旧版examples/hf_ptq/hf_ptq.py的--qformat/--kv_cache_qformat已弃用改由--recipe承载modelopt_recipes/configs/ptq/presets/model/下躺着 40 个预置配方presets/model从fp8.yaml、int8_smoothquant.yaml到nvfp4.yaml、w4a8_awq_beta.yaml一应俱全。YAML 配方用$import机制组合公共单元nvfp4.yamlimports: base_disable_all: configs/ptq/units/base_disable_all w4a4_nvfp4_nvfp4: configs/ptq/units/w4a4_nvfp4_nvfp4 default_disabled_quantizers: configs/ptq/units/default_disabled_quantizers algorithm: max quant_cfg: - $import: base_disable_all - $import: w4a4_nvfp4_nvfp4 - $import: default_disabled_quantizers配方把量化配置 校准算法 KV cache 设置收在一个文件里避免了三组 flag 各自为政导致的漂移。迁移时注意旧--qformat的短名int8_sq、nvfp4_awq等已在 0.47 移除直接用配方 basename。三、校准从 calibrator 对象到 forward-loop 驱动3.1 算法选择与参数注入calibrate()model_quant.py支持的算法与旧工具链差异明显max最简校准等价于旧 MinMax但仅权重量化 max时不需要 forward loopsmoothquant迁移量最大的旧用户通常会选它做 INT8 平滑量化awq_lite / awq_full / awq_clipAWQ 家族旧链路上要自己找脚本新算法SVDQuant、Local-Hessian、NVFP4 MSE等则是旧工具链完全没有的。算法可以用字符串也可以传字典注入超参例如{method: awq_clip, max_co_batch_size: 4096}。仓库示例还展示了按专家比例校准 MoEbuild_quant_cfg()example_utils.py会把moe_calib_experts_ratio注入 algorithm 字典——这是迁移 MoE 模型时最容易被忽略的调参入口。3.2 校准数据要求校准数据规模在官方指南里有明确推荐128–512 个样本PyTorch Quantization默认混合cnn_dailymail与nemotron-post-training-dataset-v2两个数据集。旧工具链的 calibration cache 文件.cache在 ModelOpt 里没有对应概念——统计量全部在校准过程中动态收集并写入模型内部的_amax你不需要也不能复用旧的 cache 文件。3.3 迁移后新增的防呆检查这是 ModelOpt 比旧工具链体贴的地方也是迁移后第一次跑通时最容易愣住的点quantize()内部有两个量化是否真的生效的守卫model_quant.py_check_weight_quantization_took_effect配置要求量化权重、但通配符没匹配到任何模块时直接抛RuntimeError而不是像旧工具那样静默产出一个根本没量化的模型。官方注释点出了动机早期版本就是默默导出quant_algo: null的空量化 checkpointMoE 架构的模块命名与通用配方不匹配时尤其容易触发。误报时可用环境变量MODELOPT_SKIP_WEIGHT_QUANT_CHECK1跳过管道并行下某 rank 本地确实没有目标模块时用。_check_indexer_quantization_took_effect稀疏注意力 indexer 的同类守卫。迁移时的正确姿势报错先读信息——它通常会告诉你配方没匹配上架构的模块命名去 model_type 配方目录 找对应模型的专属配方而不是改错环境变量硬跳过。四、导出链路从出 engine到出统一 checkpoint4.1 最大的 API 替换export_hf_checkpoint旧链路终点是trtexec --onnxxxx.onnx --saveEnginexxx.engine或 Python builder 直接出 engine。ModelOpt 的终点是统一 Hugging Face checkpointUnified HuggingFace Checkpointfrom modelopt.torch.export import export_hf_checkpoint with torch.inference_mode(): export_hf_checkpoint(model, export_dir)产出物是safetensors 权重 hf_quant_config.json量化配置 结构/分词器/元数据 jsonTensorRT-LLM≥ v1.2.0、vLLM≥ v0.10.1、SGLang≥ v0.4.10都能直接加载。同一个 checkpoint 喂三个后端这是旧一次编译一个 engine的链路做不到的。4.2 旧导出 API 正在退场CHANGELOG 白纸黑字export_tensorrt_llm_checkpoint与torch_to_tensorrt_llm_checkpoint已发DeprecationWarning计划在 0.49.0 移除实现迁移到modelopt.torch.export.trtllm子包get_model_type等返回 TRT-LLM 模型名的辅助函数同样弃用改用model.config.model_type。如果你还在 import 这些旧函数迁移的第一步就是换成export_hf_checkpoint。4.3 状态保存modelopt_state是新的checkpoint 灵魂量化、剪枝、蒸馏都会改动模型架构和权重ModelOpt 把修改记录在modelopt_state里Saving Restoringimport modelopt.torch.opt as mto # 一起存 mto.save(model, modelopt_model.pth) # 或只存状态权重用自己的方式存 torch.save(mto.modelopt_state(model), modelopt_state.pth) # 恢复 mto.restore(model, modelopt_model.pth)迁移要点架构修改必须随状态一起恢复光存state_dict会丢掉量化的_amax与替换后的模块结构。另外 CHANGELOG 提醒携带 0.45 之前旧版layerwise布尔字段的modelopt_state在新版恢复时直接校验失败而不是自动迁移需先用 0.45/0.46 重存一次。4.4 真实压缩与 GGML新的导出分支对显存敏感的场景mtq.compress()compress.py把权重真正压成低比特存储。统一导出还支持 GGML 布局IQ1_S / IQ2_XS / Q8_0此时权重被替换为字节精确的 GGML blockuint8 张量形状为[*logical_shape[:-1], logical_shape[-1] // block_size, payload_bytes]。坑在于ModelOpt 的 per-tensor FP8 格式在 GGML 中没有等价类型FP8 checkpoint 转 GGUF 必须先转成 GGML 支持的张量类型做不到无损直转。规划 GGML 落地前务必先确认这条限制。五、ONNX 侧的对应差异QDQ 是终点不是起点如果迁移的是 ONNX 链路检测、分割等视觉模型入口换成modelopt.onnx.quantization的quantize()quantize.py、ONNX Quantizationimport modelopt.onnx.quantization as moq calibration_data np.load(calibration_data_path) # npz/npydict 键必须与 ONNX 输入名一致 moq.quantize( onnx_pathonnx_path, calibration_datacalibration_data, output_pathquant.onnx, quantize_modeint8, # int8 | int4 | fp8 calibration_methodmax, # int8/fp8: entropy|max; int4: awq_clip|awq_lite|awq_full|rtn_dq )对照旧 ONNX Runtime 静态量化差异集中在四点校准数据格式只收 npz/npy且字典键必须匹配模型输入名也可以用CalibrationDataReader或calibration_shapes指定输入形状。执行 Provider 顺序calibration_eps[cpu, cuda:0, trt]含自定义算子时trt会被自动追加TensorRT ≥ 10.0 才支持 TensorRT EP。产出是带 QDQ 的 ONNX不是 engine文档明确generated ONNX should be compiled into TensorRT engine才真正提速——trtexec --onnxquant.onnx --saveEnginequant.engine。这一步与旧链路看似相同但 QDQ 插入遵循 TensorRT 的显式量化规则op_types_to_quantize、nodes_to_exclude、trt_plugins等参数直接决定 QDQ 放哪、精度损失在哪。模块被移除modelopt.onnx.quantization.ort_patching与graph_utils已无兼容层直接删除旧的 patch 写法需按迁移映射改用graph_rewrites等新模块见 CHANGELOG。六、迁移后必做的回退检查清单6.1 精度回退打印量化摘要mtq.print_quant_summary(model)核对 quantizer 是否落到预期层上这是定位静默未量化最快的抓手。读导出配置导出的hf_quant_config.json里quant_algo不能是nullquantized_layers不能为空——这正是 3.3 节守卫要防的失败模式。先选对配方再谈精度NVFP4 默认配方全层量化官方在 hf_ptq/README.md 明确建议高精度优先用NVFP4_MLP_ONLY_CFG只量化 MLP/MoE、NVFP4_EXPERTS_ONLY_CFG只量化专家层或NVFP4_OMLP_ONLY_CFG外加o_proj保住注意力 QKV 投影的高精度。校准数据一致性旧 cache 不可复用校准集与验证集要隔离MoE 记得调moe_calib_experts_ratio。低比特精度救济若精度回退超预期检查block_sizesconfig.py 的QuantizerAttributeConfig——低比特必须用 per-block如{-1: 32}、{type: dynamic}还能用scale_bits/scale_block_sizes做 scale 的双重量化4-bit 精度不足时考虑 AWQ 或 SVDQuant再不行就上 QAT/QAD 训练补救。6.2 性能回退别在 PyTorch 里测速fake quant 不加速只有导出后测4.1/5.1 节。对比基准用trtexec报告的 Latency / Throughput同参数、同 GPU、同精度档位才可比。确认后端版本统一 checkpoint 有最低版本要求TRT-LLM v1.2.0 / vLLM v0.10.1 / SGLang v0.4.10旧容器加载新格式大概率报KeyError或结构错误——这是迁移后最常见的环境坑。验证收益预期仓库最新成果给出了可参照的量化收益量级——Nemotron 3 Ultra 550B 量化到 NVFP4 后解码吞吐最高 5.9×、精度持平 BF16Qwen3.6-35B-A3B 走 NVFP4 W4A4 PTQ 量化感知蒸馏后vLLM 吞吐 1.30×、checkpoint 缩小 3.1×。你的模型跑不出这个数不等于失败先对照是否漏了导出步骤、KV cache 是否量化、配方是否选对。分布式注意FSDP2 下export_hf_checkpoint需要所有 rank 参与 collectives只有 rank 0 写文件offload 流式导出路径不支持save_modelopt_stateTrue——这些都会在迁移后第一次多卡运行时冒出来。七、迁移总路线图把上面的差异收敛成一张行动清单照着走基本不会踩空改入口mtq.quantize(model, config, forward_loop)替换手动插 quantizer calibratorforward_loop记得带model参数。改配置--qformat换成--recipe或 YAML 配方自定义格式按deny-all → 逐格式开启 → 默认排除顺序写quant_cfg。改校准丢弃旧 cache 文件用 128–512 样本的 forward loop先max打底再按需上 SmoothQuant / AWQ / SVDQuant。改导出export_hf_checkpoint替代export_tensorrt_llm_checkpoint/trtexec状态用mto.save/mto.restore或单独存modelopt_state。回退验证print_quant_summaryhf_quant_config.json验结构导出后测速验证性能必要时用block_sizes、配方选择与 QAT/QAD 兜底精度。ModelOpt 这套链路最反直觉、也最值得记住的一句话是量化在校准性能在导出。想清楚这句迁移路上的大多数性能没提升和导出就报错都能少走一半弯路。【免费下载链接】Model-OptimizerA unified library of SOTA model optimization techniques like quantization, distillation, pruning, neural architecture search, speculative decoding, etc. It compresses deep learning models for downstream deployment frameworks like TensorRT-LLM, TensorRT, vLLM, etc. to optimize inference speed.项目地址: https://gitcode.com/GitHub_Trending/te/Model-Optimizer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考