保姆级三入口：Hugging Face / PyTorch / ONNX 一键导出到 Model-Optimizer

保姆级三入口Hugging Face / PyTorch / ONNX 一键导出到 Model-Optimizer【免费下载链接】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把模型从「训练好的权重」变成「能跑的引擎」中间横着一条最陡的坎精度压缩、格式转换、框架适配。NVIDIA Model-Optimizer 把量化NVFP4/FP8/INT8/INT4、剪枝、蒸馏、NAS、投机解码这些 SOTA 优化技术收进一个统一库并面向 TensorRT-LLM、TensorRT、vLLM、SGLang 等推理引擎输出可直接加载的产物。它最讨喜的一点是无论你的模型资产是 Hugging Face Checkpoint、原生 PyTorch 模型还是现成的 ONNX 图都有对应的「一键入口」。本文不聊抽象概念直接对着仓库源码走完三条入口的导入代码、典型报错以及一条从量化到 TensorRT-LLM 引擎的完整链路。三个入口怎么选先看清你的资产在哪Model-Optimizer 的三个入口本质是对三类资产形态的适配入口资产形态终点产物代表场景Hugging Face 入口HF Hub 模型卡 / 本地 transformers 目录统一 HF Checkpointsafetensors hf_quant_config.jsonLLM / VLM / diffusers 流水线部署到 TensorRT-LLM、vLLM、SGLangPyTorch 入口内存中的torch.nn.Moduletimm、自定义模型FP16 ONNX 文件 → TensorRT 引擎CNN / ViT 等视觉模型边缘与数据中心推理ONNX 入口已存在的.onnx/.pb图带 QDQ 节点的量化 ONNX → TensorRT / ONNX Runtime存量 ONNX 资产、无法回溯到 PyTorch 的模型判断逻辑很简单大模型走 HF 入口产出统一 Checkpoint一次导出多框架复用视觉/传统模型走 PyTorch 入口在内存里做完优化再落盘 ONNX手里只有 ONNX 文件就走 ONNX 入口直接在图层面插入 QDQ 节点。以量化效果为参照Model-Optimizer 压缩后质量保持是验证链路的关键一环——例如 SDXL 基线的生成效果左图与量化导出后的效果右图肉眼几乎无差别但显存与延迟大幅下降入口一Hugging Face —— 大模型 PTQ 与统一 CheckpointHF 入口的 API 极简核心就两步量化 导出。仓库 examples/hf_ptq/README.md 给出的最小示例import modelopt.torch.quantization as mtq # 1. 加载模型AutoModelForCausalLM / AutoModel 等 model AutoModelForCausalLM.from_pretrained(...) # 2. 准备校准数据并定义 forward loop calib_set get_dataloader(num_samplescalib_size) def forward_loop(model): for batch in calib_set: model(batch) # 3. PTQ 量化以 NVFP4 为例 model mtq.quantize(model, mtq.NVFP4_DEFAULT_CFG, forward_loop)量化完成后用 modelopt/torch/export/unified_export_hf.py 的export_hf_checkpoint导出统一 Checkpoint——产物是「一组 safetensors 权重 量化配置hf_quant_config.json 结构/tokenizer/元信息 JSON」层结构与张量名与原 HF Checkpoint 对齐因此 TensorRT-LLM、vLLM、SGLang 三个框架都能不加修改直接加载from modelopt.torch.export import export_hf_checkpoint with torch.inference_mode(): export_hf_checkpoint(model, export_dir)生产环境建议直接用仓库提供的hf_ptq.py命令行入口一条命令完成量化 导出 前后生成对比examples/hf_ptq/hf_ptq.py 内部会自动处理 VLM 语言模型抽取、KV cache 量化、真实量化低显存加载等细节python hf_ptq.py --pyt_ckpt_path model_card --qformat fp8 --export_path export_dir --trust_remote_code统一 Checkpoint 支持的量化格式覆盖 FP8、FP8_PB、NVFP4、NVFP4_AWQ、INT4_AWQ、W4A8_AWQ以及 GGML 布局的 IQ1_S / IQ2_XS / Q8_0见 docs/source/deployment/3_unified_hf.rst。HF 入口常见报错与对策trust_remote_code问题Qwen3、Nemotron 等依赖自定义建模代码的模型必须加--trust_remote_code否则加载即失败。多 GPU 设备不一致校准报 Expected all tensors to be on the same device...先尝试CUDA_VISIBLE_DEVICES缩小 GPU 数量大模型可用--use_seq_device_map或--low_memory_mode后者仅支持 FP8/NVFP4 max 校准压显存。NVFP4 部署翻车NVFP4 推理要求 Blackwell GPUsm_100Hopper 可以产出 NVFP4 Checkpoint 但无法服务B300/GB300 上还要用 CUDA-13 构建的推理框架CUDA-12 构建缺 sm_103 FP4 kernel。部署时格式参数vLLM 加载需quantizationmodeloptFP8或quantizationmodelopt_fp4NVFP4TensorRT-LLM 的 PyTorch backend 直接加载无需额外参数。入口二PyTorch —— 原生模型量化后导出 ONNX如果你的模型就在内存里timm 的 ViT/Swin/ResNet或任意自定义nn.Moduleexamples/torch_onnx/torch_quant_to_onnx.py 提供了一条「量化 → 导出 ONNX → trtexec 建引擎」的全自动管线支持 FP8、MXFP8、INT8、NVFP4、INT4_AWQ 和 AUTO混合精度python torch_quant_to_onnx.py \ --timm_model_namevit_base_patch16_224 \ --qformatfp8 \ --onnx_save_pathvit_fp8.onnx \ --trt_build # 可选导出后直接构建 TensorRT 引擎脚本内部用mtq.quantize(model, config, forward_loopforward_loop)完成量化见 examples/torch_onnx/torch_quant_to_onnx.py随后调用 FP8/INT8/INT4/NVFP4/MXFP8 系列 ONNX exportermodelopt/onnx/export/init.py把量化状态写进带 QDQ 的 ONNX 图。Conv2d 覆盖规则最容易踩的坑TensorRT 对卷积只支持 FP8/INT8 kernel脚本会自动把 MXFP8/NVFP4 的 Conv2d 覆盖为 FP8、INT4_AWQ 的 Conv2d 覆盖为 INT8这也意味着 ResNet 这类纯卷积架构只支持 FP8/INT8 与对应 recipe硬用 NVFP4 会直接报错。此外Blackwellcompute capability 12.0上首层 RGB 卷积in_channels 3没有 FP8 Q→Conv 融合的 tactic脚本已内置_disable_low_channel_fp8_conv_input_quantizers自动关闭该层输入量化——这是跨架构调试时的经典坑。PyTorch 入口常见报错与对策trtexec not found on PATH--trt_build要求先安装 TensorRT 并把trtexec放进 PATH引擎构建失败会抛带完整 stderr 的RuntimeError超时 600 秒。AutoQuantize 报错--qformatauto需要带标签的校准数据loss 计算用且 ResNet 类卷积模型不支持 AutoQuantize--num_score_steps默认 128太大易 OOM。MXFP8/NVFP4 引擎评估评估 MXFP8/NVFP4 ONNX 引擎要求 TensorRT 10.11。量化导出的 ONNX 同样可以评估对比——例如量化后的 SDXL 生成质量与基线一致SDXL FP8 量化生成效果入口三ONNX —— 存量图直接 QDQ 量化手里只有.onnx文件、无法回溯训练代码时examples/onnx_ptq/README.md 的 ONNX PTQ 工具链直接在图层面工作按编译器友好的模式插入 Quantize-DequantizeQDQ节点生成显式 ONNX 模型。默认量化算子因模式而异——INT8 覆盖 Conv/Gemm/MatMul/Add/Pool 等INT4 覆盖 Gemm/MatMulFP8 覆盖 Conv/Gemm/MatMul见 modelopt/onnx/quantization/quantize.py。CLI 一键量化以 ViT 为例# 1. 准备校准数据numpy 数组TensorRT 建议 ≥500 张 python image_prep.py --calibration_data_size500 --output_pathcalib.npy # 2. 量化 python -m modelopt.onnx.quantization \ --onnx_pathvit_base_patch16_224.onnx \ --quantize_modeint8 \ --calibration_data_pathcalib.npy \ --calibration_methodmax \ --output_pathvit_base_patch16_224.quant.onnxPython API 等价写法import numpy as np from modelopt.onnx.quantization import quantize quantize( onnx_pathvit_base_patch16_224.onnx, quantize_modeint8, # fp8 / int8 / int4 calibration_datanp.load(calib.npy), calibration_methodmax, # max / entropy / awq_clip / rtn_dq output_pathvit_base_patch16_224.quant.onnx, )量化后的 ONNX 可直接交给trtexec --onnx...构建 TensorRT 引擎或部署到 ONNX Runtime 的 CUDA / DirectML / TensorRT-RTX / CPU 各 Execution Provider部署细节见 docs/source/deployment/2_onnxruntime.rst。真实项目里 examples/onnx_ptq/quantize_vovnet.py 展示了更精细的用法对精度敏感的 VoVNet 节点用nodes_to_exclude排除、用calibration_data_reader流式喂数据、通过calibration_eps[cuda:0, cpu]指定校准后端。ONNX 入口常见报错与对策opset 过低int8/fp8 最低 19、int4 最低 21、nvfp4 最低 23Model-Optimizer 会自动升级 opset 并给出 warning如果上游链路依赖旧 opset 需提前评估。per-node 校准限制--calibrate_per_node只支持 int8/fp8INT4awq_clip/rtn_dq会直接ValueError。自定义算子含自定义 op 的 ONNX 需要--trt_plugins/path/to/libplugin.so且必须 TensorRT 10 与 ORT≥1.20此时校准会自动把 TensorRT EP 提到首位。DirectML 不支持 8-bitDirectML 后端不支持 8 位精度模型INT8 量化产物应部署到 ORT-CUDA 等其他后端INT4 在 DML 可用。外部数据文件导出的大 ONNX 引用同名.onnx_data权重文件trtexec构建时必须保持两者在同一目录。统一收口一条链路直达 TensorRT-LLM三条入口最终都通向推理引擎。当前 TensorRT-LLM 部署的推荐路径是 HF 入口产出的统一 HF Checkpoint TensorRT-LLM PyTorch backend——docs/source/deployment/1_tensorrt_llm.rst 明确指出export_tensorrt_llm_checkpoint面向的是 legacy C backend自 0.48.0 起标记弃用、将在 0.49.0 移除请改用export_hf_checkpoint。完整的「量化 → 导出 → 加载生成」链路如下# 第 1 步量化并导出统一 HF CheckpointFP8 示例 python hf_ptq.py \ --pyt_ckpt_path meta-llama/Llama-3.1-8B-Instruct \ --qformat fp8 \ --export_path /data/llama31-8b-fp8 \ --trust_remote_code# 第 2 步TensorRT-LLM 直接加载并生成 from tensorrt_llm import LLM, SamplingParams llm LLM(model/data/llama31-8b-fp8) outputs llm.generate( [Hello, my name is, The capital of France is], SamplingParams(temperature0.8, top_p0.95), )要点TensorRT-LLM 需要v1.2.0vLLM v0.10.1、SGLang v0.4.10FP8 与 NVFP4 均支持同一 Checkpoint 无需转换即可在三个框架间迁移。若你的模型/格式组合不在官方验证矩阵内也不必焦虑——文档明确说明 vLLM、SGLang、TensorRT-LLM 会泛化加载统一 Checkpoint只要模型由标准nn.Linear构成且带hf_quant_config.json多数未列出的模型也能直接部署。部署矩阵中官方验证的组合覆盖 Llama 3.x/4、Qwen 3/3.5/3.6、DeepSeek V3/R1/V4、GLM-5、Kimi K2、MiniMax M3、Nemotron 3 等主流模型家族的 FP8/NVFP4 格式详见 docs/source/deployment/3_unified_hf.rst其中 TensorRT-LLM 的每一条目均为「加载 生成」冒烟验证。决策速查三入口最终怎么选你的情况入口关键命令/API手上有 LLM/VLM目标 TensorRT-LLM / vLLM / SGLangHugging Facehf_ptq.py→export_hf_checkpoint→ 框架LLM(model...)手上有 timm/自定义 PyTorch 模型目标 TensorRT 引擎PyTorchtorch_quant_to_onnx.py --trt_build手上只有 ONNX 文件或模型不可回溯ONNXpython -m modelopt.onnx.quantization→trtexec显存紧张、模型很大HF 低显存加--low_memory_mode/--use_seq_device_map/ FSDP2 多节点对精度要求苛刻HF AutoQuantize--recipe general/auto_quantize/nvfp4_fp8_at_5p4bits混合精度搜索三个入口共享同一套优化内核量化/剪枝/蒸馏/稀疏/NAS区别只在「模型从哪来、优化产物落到哪种格式」。理解了这一点无论资产在哪一端你都能在 Model-Optimizer 里找到那条最短路径。【免费下载链接】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），仅供参考