【免费下载链接】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点击查看免费下载Model-OptimizerNVIDIA Model Optimizer是一套集量化、蒸馏、剪枝、神经架构搜索与投机解码等 SOTA 模型优化技术于一体的开源库其产物最终服务于 TensorRT-LLM、vLLM、SGLang 等下游推理框架。本文将围绕docs/source/deployment/1_tensorrt_llm.rst的核心指引完整讲解如何用统一 Hugging Face Checkpoint 工作流在 TensorRT-LLM 上部署量化模型先用量化 API 得到优化模型再通过export_hf_checkpoint导出统一格式 checkpoint最后由 TensorRT-LLM 的 PyTorch backend 直接加载推理——全程无需构建 TensorRT engine。读完本文你将掌握从量化、导出到多框架部署的完整调用链并理解旧export_tensorrt_llm_checkpoint为何被弃用。一、为什么当前推荐统一 HF Checkpoint而非 TensorRT-LLM 专属 checkpoint1.1 两条部署路径的本质区别在 Model-Optimizer 中部署到 TensorRT-LLM 有两条路径统一 Hugging Face Checkpoint推荐通过 export_hf_checkpoint 导出。导出结果的层结构与张量命名与原始 Hugging Face checkpoint 对齐可被 TensorRT-LLM、vLLM、SGLang 等多个推理框架泛化加载且不需要构建 TensorRT engine。旧式 TensorRT-LLM 专用 checkpoint弃用通过export_tensorrt_llm_checkpoint导出面向 TensorRT-LLM 的 legacy TensorRT C backend。1.2 弃用时间线重要迁移信号docs/source/deployment/1_tensorrt_llm.rst明确给出警告export_tensorrt_llm_checkpoint自 0.48.0 起弃用将在 0.49.0 移除。这一结论在源码中得到三重印证在 model_config_export.py 中弃用消息_DEPRECATION_MSG明确写道TensorRT-LLM checkpoint format are deprecated as of 0.48.0 and will be removed in 0.49.0. Use modelopt.torch.export.export_hf_checkpoint instead, which exports a unified Hugging Face checkpoint deployable on TensorRT-LLM, vLLM and SGLang.函数定义处的 docstring 同样标注了.. deprecated:: 0.48.0并在调用时发出DeprecationWarning见 model_config_export.py。在 examples/hf_ptq/notebooks/3_PTQ_AutoQuantization.ipynb 中AutoQuant 的导出选项EXPORT_FMT已注明是Deprecated参数仅保留tensorrt_llm与hf两个选择。结论新项目应一律使用export_hf_checkpoint。旧格式在 0.49.0 后将不复存在迁移窗口即是当前版本。二、端到端工作流概览统一 HF Checkpoint 的部署工作流分为两步见 docs/source/deployment/3_unified_hf.rst量化 导出加载 Hugging Face 模型或 Megatron Core 模型用 Model-Optimizer 完成 PTQ/AWQ 等量化然后调用export_hf_checkpoint导出统一 checkpoint——其层结构与张量名称与原始 checkpoint 保持一致。加载 加速推理在支持的推理框架TensorRT-LLM、vLLM、SGLang中直接加载该 checkpoint 进行加速推理。导出结果包含三类内容一组safetensors 文件包含量化后的模型权重与缩放因子hf_quant_config.json记录量化配置量化方法、格式、block size、payload 字节数等其余json 文件保存模型结构信息、tokenizer 信息与元数据。2.1 核心导出 APIfrom modelopt.torch.export import export_hf_checkpoint with torch.inference_mode(): export_hf_checkpoint( model, # The quantized model. export_dir, # The directory where the exported files will be stored. )export_hf_checkpoint的完整签名见 unified_export_hf.py为参数类型默认值说明modelAny—待导出的完整 torch 模型支持 transformers 模型如LlamaForCausalLM与 diffusers 模型/管线如StableDiffusionPipeline、UNet2DConditionModel会自动检测并走对应导出逻辑dtypetorch.dtypeNone未量化层导出的权重数据类型None表示使用模型默认数据类型export_dirPath\|strtempfile.gettempdir()导出文件的目标目录save_modelopt_stateboolFalse是否保存 modelopt state_dict含 modelopt_state 元数据componentslist[str]None仅用于 diffusers 管线指定要导出的组件名列表None表示导出所有量化组件extra_state_dictdict[str, Tensor]None额外状态字典追加到导出的模型例如模型从未加载过的 MTP head、辅助塔权重等max_shard_sizeint\|str10GB每个 safetensors 分片文件的最大大小源码实现细节均可作为事实依据自动分派函数先判断是否为 diffusers 对象is_diffusers_object(model)是则走_export_diffusers_checkpoint否则判断是否 FSDP2 分片模型、是否 accelerate offload 模型分别走流式/多 rank 导出路径unified_export_hf.py。offload/流式导出has_accelerate_offload(model)为真时走_export_transformers_checkpoint_streaming逐层物化并直接写入分片文件峰值内存约为一层 一个分片缓冲而非整个量化 state dictunified_export_hf.py。FSDP2 多 rankis_fsdp2_model(model)且已初始化分布式时走_export_fsdp2_checkpoint_streaming各 rank 只缓冲自己负责的份额写入并行执行最后 barrier 同步unified_export_hf.py。张量命名对齐导出时会做 quantization-aware 的反向重命名build_reverse_name_mapperrevert_weight_conversion_quant_aware把内存中因 transformers 加载转换而改变的名字还原为与 HF hub checkpoint 一致的命名保证统一 checkpoint 契约成立unified_export_hf.py。2.2 从 AutoQuant 到导出一个完整实操样例在 3_PTQ_AutoQuantization.ipynb 中可以看到完整的量化→导出流程其中导出环节代码为from modelopt.torch.export import export_hf_checkpoint if EXPORT_FMT tensorrt_llm: # 已弃用仅作对比 export_tensorrt_llm_checkpoint( model, model_typellama, export_dirEXPORT_DIR, inference_tensor_parallel1, inference_pipeline_parallel1, ) else: export_hf_checkpoint(model, export_dirEXPORT_DIR)该 notebook 同时展示了 PTQ 的关键调参项EFFECTIVE_BITSAutoQuant 搜索的平均精度目标Q_FORMATS搜索空间如fp8,int4_awq可加入nvfp4、w4a8_awq探索权衡KV_FORMATKV cache 可选量化none表示跳过EXPORT_FMT导出格式官方已标注 Deprecated应固定使用hf。三、量化格式与支持矩阵以 TensorRT-LLM 为中心3.1 支持的量化格式统一 HF 导出 API 支持以下量化格式见 3_unified_hf.rstFP8— 8 位浮点FP8_PB— 8 位浮点 per-block 缩放NVFP4— NVIDIA 4 位浮点NVFP4_AWQ— NVIDIA 4 位浮点 AWQ 优化INT4_AWQ— 4 位整数 AWQ 优化W4A8_AWQ— 4 位权重 8 位激活 AWQ 优化IQ1_S— 1 位 codebook 量化采用 GGML block layoutIQ2_XS— 2 位 codebook 量化采用 GGML block layout。IQ 权重的表示细节对于 IQ1_S / IQ2_XS统一导出会把每个浮点module.weight替换为包含字节级 GGML block 的uint8张量其 shape 为[*logical_shape[:-1], logical_shape[-1] // 256, payload_bytes]IQ1_S 的payload_bytes为 50IQ2_XS 为 74。加载方可通过[*weight.shape[:-2], weight.shape[-2] * 256]恢复逻辑 shapeIQ 导出要求逻辑最后一维可被 256 整除因此该恢复是唯一无歧义的。生成的配置记录quant_method: modelopt、packing: ggml、256 值的 block size 与 payload 字节数。以每个 74 字节的 IQ2_XS block 为例表示 256 个逻辑权重bytes 0–1little-endian FP16 super-block scaledbytes 2–6532 个 little-endianuint16code每 8 个权重一组code 内含 9 位 codebook 索引 7 位符号位第 8 位符号由奇偶校验推导bytes 66–7316 个 4 位 local-scale code每 2 字节打包 2 个每个 local scale 由相邻两个 8 权重组共享。512×8 的 IQ2_XS codebook 属于实现的一部分而非 checkpoint 内容因此单个逻辑权重成本为74 * 8 / 256 2.3125bits。注意GGML 没有与 ModelOpt per-tensor FP8 权重激活格式等价的类型。将 ModelOpt FP8 checkpoint 转换为 GGUF 需要先转换到其他 GGML 支持的张量类型无法无损保留 FP8 编码。Megatron IQ 导出的边界Megatron IQ 导出要求 tensor/pipeline 并行度均为 1打包发生在导出期TP 分片会被当作完整权重打包Megatron fused-MoE IQ 导出目前不支持会抛出NotImplementedErrordense 权重与独立命名的 expert 权重仍使用上述表示。3.2 最小框架版本框架最小版本TensorRT-LLMv1.2.0vLLMv0.10.1SGLangv0.4.10文档特别说明这些是最老的可加载统一 checkpoint 的版本部署套件本身面向更新版本.github/workflows/中的 TensorRT-LLM 容器位于 1.3.x 线。更老的 TensorRT-LLM 可能仍能服务 FP8 checkpoint只是未经测试因此 v1.2.0 是声明的最老版本而非实际能跑的最老版本。3.3 模型支持矩阵TensorRT-LLM 列节选该矩阵源于发布部署套件 tests/examples/hf_ptq/test_deploy.py每个条目加载导出 checkpoint 并用 4 个短文本 prompt 生成、断言非空输出。两个边界需要声明这些是已声明用例而非 PR 必测覆盖套件标记release仅当 pytest 收到--run-release时收集当前 workflow 未传该参数且每个用例只是文本路径上的加载生成冒烟检查不验证精度、图像/音频输入、扩散输出或投机解码是否真正生效。语言模型TensorRT-LLM 列模型量化格式TensorRT-LLMLlama 3.1, 3.3FP8, NVFP4✅Llama 4 Scout, MaverickFP8✅Llama 4 ScoutNVFP4✅Llama Nemotron Super 49B v1, v1.5FP8✅Llama Nemotron Ultra 253B v1FP8✅Nemotron 3 Nano 30B-A3BFP8, NVFP4✅Nemotron 3 Super 120B-A12BFP8, NVFP4✅Nemotron 3 Ultra 550B-A55BNVFP4✅DeepSeek R1, R1-0528NVFP4✅DeepSeek V3, V3.1, V3.2NVFP4✅DeepSeek V4 FlashNVFP4✅Qwen 3 8B, 14BFP8, NVFP4✅Qwen 3 32BNVFP4✅Qwen 3 MoE 235B-A22BFP8, NVFP4✅Qwen 3 MoE 30B-A3BNVFP4✅Qwen 3 Coder 480B-A35BNVFP4✅Qwen 3-Next 80B-A3BNVFP4✅Qwen 3.5 397B-A17BNVFP4✅Gemma 4 31BNVFP4✅GLM-4.7, GLM-5, GLM-5.2NVFP4✅Kimi K2-Thinking, K2.5NVFP4✅MiniMax M2.5, M3NVFP4✅Qwen 2.5 (FP8 / NVFP4)、QwQ-32B、Mixtral 8x7B、DeepSeek R1/V3 (FP8) 等对应格式⚠预期可用非套件条目视觉语言/多模态模型Model-Optimizer 只量化语言模型部分视觉编码器保持高精度导出 checkpoint 的多模态服务依赖推理框架自身的多模态支持。✅ 仅代表纯文本冒烟覆盖套件只发送与语言模型相同的纯文本 prompt图片/音频输入并未进入 processor 或视觉编码器不构成多模态服务的证明。投机解码 drafterdrafters 部署在各自 base checkpoint 之上。EAGLE3 for Llama 3.3 70B、Llama 4 Maverick、Qwen 3 235B-A22B、Kimi K2-Thinking/K2.5/K2.6、gpt-oss-120b 等在 TensorRT-LLM 列均为 ✅Medusa for Llama 3.1 8B 为 ⚠共享 harness 仅在模型 ID 含eagle时构建投机解码配置Medusa 用例实际执行的是普通生成。扩散模型DiffusionGemma 26B-A4B 在 TensorRT-LLM 列为 ✅Wan 2.2 T2V A14B 为 ⚠用例走的是与语言模型相同的自回归文本 helper 并断言生成文本从未调用 diffusion/视频服务 API不能支撑文生视频部署结论。NVFP4 硬件前提NVFP4 推理要求Blackwell GPU。Hopper 可以产出 NVFP4 checkpoint 但无法服务它在 B300/GB300sm_103上需使用CUDA-13 构建的 serving 框架CUDA-12 构建缺少sm_103FP4 kernel。未列入的模型该矩阵只记录 Model-Optimizer 验证过的组合并非可运行集合的全集。vLLM、SGLang、TensorRT-LLM 会泛化加载统一 checkpoint——任何由标准nn.Linear层构成、带hf_quant_config.json的模型通常无需改动即可部署。建议先查 serving 框架自身的模型支持列表再尝试。每个 ✅ 对应的确切 checkpoint含 tensor-parallel 规模与最小 SM 版本列于 tests/examples/hf_ptq/test_deploy.py多数发布在 NVIDIA 的 Hugging Face 组织下。四、在 TensorRT-LLM 中加载统一 checkpoint4.1 环境前提安装 TensorRT-LLM按其官方安装指引需v1.2.0 或更新支持 FP8 与 NVFP4 量化模型不需要构建 TensorRT engineexport_hf_checkpoint导出的统一 checkpoint 由 TensorRT-LLM 的PyTorch backend直接加载。4.2 从 Hugging Face Hub 直接加载以下样例代码可直接运行来自 3_unified_hf.rst使用nvidia/Llama-3.1-8B-Instruct-FP8from tensorrt_llm import LLM, SamplingParams def main(): prompts [ Hello, my name is, The president of the United States is, The capital of France is, The future of AI is, ] sampling_params SamplingParams(temperature0.8, top_p0.95) llm LLM(modelnvidia/Llama-3.1-8B-Instruct-FP8) outputs llm.generate(prompts, sampling_params) for output in outputs: prompt output.prompt generated_text output.outputs[0].text print(fPrompt: {prompt!r}, Generated text: {generated_text!r}) if __name__ __main__: main()要点LLM(model...)既可直接接受 HF Hub 上的模型 ID如nvidia/Llama-3.1-8B-Instruct-FP8也可接受本地导出目录采样参数SamplingParams(temperature0.8, top_p0.95)是 TensorRT-LLM PyTorch backend 的标准用法。4.3 部署本地量化 checkpoint仓库内实测脚本在 examples/hf_ptq/run_tensorrt_llm.py 中Model-Optimizer 提供了完整的本地推理脚本可用于验证导出的 checkpointpython run_tensorrt_llm.py --checkpoint_dir$SAVE_PATH该脚本支持的关键参数参数默认值说明--checkpoint_dir—量化 checkpoint 导出目录--tokenizer默认取checkpoint_dirtokenizer 路径或已加载的 tokenizer 对象--input_textsBorn in north-east France, Soyer trained as a\|Born in California, Soyer trained as a输入文本用|分隔不同 batch--max_output_len100最大输出长度--trust_remote_codeFalse是否信任远程代码自定义模型/分词器其内部实现展示了 TensorRT-LLM LLM API 的完整用法run_tensorrt_llm.pyllm LLM( args.checkpoint_dir, tokenizertokenizer, max_batch_sizelen(input_texts), enable_kv_cache_reuseFalse, # generate_context_logits 需要禁用 prefix block reuse trust_remote_codeargs.trust_remote_code, ) outputs llm.generate_text(input_texts, args.max_output_len) outputs llm.generate_tokens(input_texts, args.max_output_len) logits llm.generate_context_logits(input_texts)脚本还会打印 GPU 显存占用free_memory_before/after便于评估量化模型的显存收益。五、为什么不需要构建 TensorRT engine——PyTorch backend 模式解读传统 TensorRT-LLM 部署流程需要导出 TRT-LLM checkpoint →trtllm-build构建 engine → 用 engine 推理。而统一 HF checkpoint 工作流直接跳过 engine 构建原因在于 TensorRT-LLM 的 PyTorch backend 能够直接消费标准 HF 结构 checkpoint统一导出的 safetensors 权重 hf_quant_config.json量化配置 模型结构 json本身就是 PyTorch backend 可以逐层复现的完整描述hf_quant_config.json中记录quant_method: modelopt等字段让 TensorRT-LLM 的量化层能正确解释 FP8/NVFP4 的缩放语义与 block 布局层结构与张量命名与原始 HF checkpoint 对齐导出时做了 quantization-aware 反向重命名因此框架现成的 transformers 加载逻辑即可复用。这一点与 legacy TensorRT 后端形成鲜明对比export_tensorrt_llm_checkpoint产出的rankN.safetensorsconfig.json必须经过trtllm-build编译为 engine 才能服务而该后端在当前 TensorRT-LLM 版本已不再支持见文档 warning这正是它被弃用的直接原因。六、迁移指南从旧 API 到export_hf_checkpoint事项旧 API新 API入口from modelopt.torch.export.trtllm import export_tensorrt_llm_checkpointfrom modelopt.torch.export import export_hf_checkpoint必填参数model, decoder_type, dtype, export_dir, inference_tensor_parallel, inference_pipeline_parallelmodel, export_dir其余均为可选产物config.jsonrankN.safetensors每 rank 一份需构建 enginesafetensors 分片 hf_quant_config.json 结构/tokenizer/元数据 json直接加载后端legacy TensorRT C backend已不再被支持TensorRT-LLM PyTorch backendv1.2.0多框架仅 TensorRT-LLMTensorRT-LLM、vLLM、SGLang 通用生命周期0.48.0 弃用0.49.0 移除当前推荐路径旧 API 支持的inference_tensor_parallel/inference_pipeline_parallel参数按目标 GPU 规模 merge/split 权重在统一导出路径中由各 serving 框架自己的并行加载机制承担这也是迁移时最需要调整的思维方式并行度配置从导出期决定变为加载期决定。七、常见问题与边界提醒版本下限不是能力上限TensorRT-LLM v1.2.0 是声明的最老版本部署套件实际面向 1.3.x更老版本可能仍能服务 FP8但不在验证范围内。支持矩阵 ≠ 全部可运行模型任何标准nn.Linear结构 hf_quant_config.json的模型都有机会直接部署先查 serving 框架的模型支持列表再尝试。NVFP4 的 GPU 硬约束推理需要 BlackwellHopper 只能产出 checkpoint 不能服务sm_103B300/GB300必须用 CUDA-13 构建。多模态/扩散/投机解码的矩阵边界✅ 仅表示文本路径加载 生成冒烟通过不代表多模态服务、扩散输出或投机解码已被验证。GGUF 转换限制ModelOpt FP8 无法无损转成 GGML 的 FP8 张量类型需先转换到其他 GGML 支持的张量类型。如需深入可继续阅读 统一 HF 导出指南本文所引支持矩阵的完整出处与 hf_ptq 示例量化→导出→推理的端到端实操后者也提供了使用export_hf_checkpoint导出、再由tensorrt_llm.LLM直接加载的完整代码片段。赞分享【免费下载链接】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点击查看免费下载相关推荐Model Optimizer 实战从 NVIDIA Hugging Face Model Hub 一键部署 FP8 量化模型到 TensorRT-LLM、vLLM 与 SGLangModel Optimizer 实战从 NVIDIA Hugging Face Model Hub 一键部署 FP8 量化模型到 TensorRT LLM、vModel-Optimizer 统一 Hugging Face 检查点导出指南从 PTQ 量化到 TensorRT-LLM / vLLM / SGLang 一键部署Model Optimizer 统一 Hugging Face 检查点导出指南从 PTQ 量化到 TensorRT LLM / vLLM / SGLang 一Model-Optimizer 自定义 Hugging Face 模型量化插件开发以 DBRX MoE 为例实现 TensorRT-LLM 部署Model Optimizer 自定义 Hugging Face 模型量化插件开发以 DBRX MoE 为例实现 TensorRT LLM 部署 导读 本文聚创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考