企业官网建设流程全解析

保姆级三入口：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 的三个入口，本质是对三类资产形态的适配：

判断逻辑很简单：大模型走 HF 入口（产出统一 Checkpoint，一次导出多框架复用），视觉/传统模型走 PyTorch 入口（在内存里做完优化再落盘 ONNX），手里只有 ONNX 文件就走 ONNX 入口（直接在图层面插入 QDQ 节点）。

以量化效果为参照，Model-Optimizer 压缩后质量保持是验证链路的关键一环——例如 SDXL 基线的生成效果（左图）与量化导出后的效果（右图）肉眼几乎无差别，但显存与延迟大幅下降：

入口一：Hugging Face —— 大模型 PTQ 与统一 Checkpoint

HF 入口的 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_samples=calib_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 GPU（sm_100+）；Hopper 可以产出 NVFP4 Checkpoint 但无法服务，B300/GB300 上还要用 CUDA-13 构建的推理框架（CUDA-12 构建缺 sm_103 FP4 kernel）。
• 部署时格式参数：vLLM 加载需quantization="modelopt"（FP8）或quantization="modelopt_fp4"（NVFP4）；TensorRT-LLM 的 PyTorch backend 直接加载，无需额外参数。

入口二：PyTorch —— 原生模型量化后导出 ONNX

如果你的模型就在内存里（timm 的 ViT/Swin/ResNet，或任意自定义nn.Module），examples/torch_onnx/torch_quant_to_onnx.py 提供了一条「量化 → 导出 ONNX → trtexec 建引擎」的全自动管线，支持 FP8、MXFP8、INT8、NVFP4、INT4_AWQ 和 AUTO（混合精度）：

python torch_quant_to_onnx.py \ --timm_model_name=vit_base_patch16_224 \ --qformat=fp8 \ --onnx_save_path=vit_fp8.onnx \ --trt_build # 可选：导出后直接构建 TensorRT 引擎

脚本内部用mtq.quantize(model, config, forward_loop=forward_loop)完成量化（见 examples/torch_onnx/torch_quant_to_onnx.py），随后调用 FP8/INT8/INT4/NVFP4/MXFP8 系列 ONNX exporter（modelopt/onnx/export/init.py）把量化状态写进带 QDQ 的 ONNX 图。

Conv2d 覆盖规则（最容易踩的坑）：TensorRT 对卷积只支持 FP8/INT8 kernel，脚本会自动把 MXFP8/NVFP4 的 Conv2d 覆盖为 FP8、INT4_AWQ 的 Conv2d 覆盖为 INT8；这也意味着 ResNet 这类纯卷积架构只支持 FP8/INT8 与对应 recipe，硬用 NVFP4 会直接报错。此外，Blackwell（compute 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 报错：--qformat=auto需要带标签的校准数据（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-Dequantize（QDQ）节点，生成显式 ONNX 模型。默认量化算子因模式而异——INT8 覆盖 Conv/Gemm/MatMul/Add/Pool 等，INT4 覆盖 Gemm/MatMul，FP8 覆盖 Conv/Gemm/MatMul（见 modelopt/onnx/quantization/quantize.py）。

CLI 一键量化（以 ViT 为例）：

# 1. 准备校准数据（numpy 数组，TensorRT 建议 ≥500 张） python image_prep.py --calibration_data_size=500 --output_path=calib.npy # 2. 量化 python -m modelopt.onnx.quantization \ --onnx_path=vit_base_patch16_224.onnx \ --quantize_mode=int8 \ --calibration_data_path=calib.npy \ --calibration_method=max \ --output_path=vit_base_patch16_224.quant.onnx

Python API 等价写法：

import numpy as np from modelopt.onnx.quantization import quantize quantize( onnx_path="vit_base_patch16_224.onnx", quantize_mode="int8", # fp8 / int8 / int4 calibration_data=np.load("calib.npy"), calibration_method="max", # max / entropy / awq_clip / rtn_dq output_path="vit_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 最低 23；Model-Optimizer 会自动升级 opset 并给出 warning，如果上游链路依赖旧 opset 需提前评估。
• per-node 校准限制：--calibrate_per_node只支持 int8/fp8，INT4（awq_clip/rtn_dq）会直接ValueError。
• 自定义算子：含自定义 op 的 ONNX 需要--trt_plugins=/path/to/libplugin.so，且必须 TensorRT 10+ 与 ORT≥1.20；此时校准会自动把 TensorRT EP 提到首位。
• DirectML 不支持 8-bit：DirectML 后端不支持 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 Checkpoint（FP8 示例） 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(temperature=0.8, top_p=0.95), )

要点：TensorRT-LLM 需要v1.2.0+（vLLM v0.10.1+、SGLang v0.4.10+）；FP8 与 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 的每一条目均为「加载 + 生成」冒烟验证。

决策速查：三入口最终怎么选

三个入口共享同一套优化内核（量化/剪枝/蒸馏/稀疏/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