企业官网建设流程全解析

Model-Optimizer（NVIDIA 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 专属 checkpoint

1.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）：

1. 量化 + 导出：加载 Hugging Face 模型（或 Megatron Core 模型），用 Model-Optimizer 完成 PTQ/AWQ 等量化，然后调用export_hf_checkpoint导出统一 checkpoint——其层结构与张量名称与原始 checkpoint 保持一致。
2. 加载 + 加速推理：在支持的推理框架（TensorRT-LLM、vLLM、SGLang）中直接加载该 checkpoint 进行加速推理。

导出结果包含三类内容：

• 一组safetensors 文件：包含量化后的模型权重与缩放因子；
• hf_quant_config.json：记录量化配置（量化方法、格式、block size、payload 字节数等）；
• 其余json 文件：保存模型结构信息、tokenizer 信息与元数据。

2.1 核心导出 API

from 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）为：

源码实现细节（均可作为事实依据）：

• 自动分派：函数先判断是否为 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 dict（unified_export_hf.py）。
• FSDP2 多 rank：is_fsdp2_model(model)且已初始化分布式时走_export_fsdp2_checkpoint_streaming，各 rank 只缓冲自己负责的份额，写入并行执行，最后 barrier 同步（unified_export_hf.py）。
• 张量命名对齐：导出时会做 quantization-aware 的反向重命名（build_reverse_name_mapper+revert_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_type="llama", export_dir=EXPORT_DIR, inference_tensor_parallel=1, inference_pipeline_parallel=1, ) else: export_hf_checkpoint(model, export_dir=EXPORT_DIR)

该 notebook 同时展示了 PTQ 的关键调参项：

• EFFECTIVE_BITS：AutoQuant 搜索的平均精度目标；
• Q_FORMATS：搜索空间（如"fp8,int4_awq"），可加入"nvfp4"、"w4a8_awq"探索权衡；
• KV_FORMAT：KV cache 可选量化，"none"表示跳过；
• EXPORT_FMT：导出格式，官方已标注 Deprecated，应固定使用hf。

三、量化格式与支持矩阵（以 TensorRT-LLM 为中心）

3.1 支持的量化格式

统一 HF 导出 API 支持以下量化格式（见 3_unified_hf.rst）：

1. FP8— 8 位浮点；
2. FP8_PB— 8 位浮点 + per-block 缩放；
3. NVFP4— NVIDIA 4 位浮点；
4. NVFP4_AWQ— NVIDIA 4 位浮点 + AWQ 优化；
5. INT4_AWQ— 4 位整数 + AWQ 优化；
6. W4A8_AWQ— 4 位权重 + 8 位激活 + AWQ 优化；
7. IQ1_S— 1 位 codebook 量化，采用 GGML block layout；
8. IQ2_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为 50，IQ2_XS 为 74）。加载方可通过[*weight.shape[:-2], weight.shape[-2] * 256]恢复逻辑 shape；IQ 导出要求逻辑最后一维可被 256 整除，因此该恢复是唯一无歧义的。生成的配置记录quant_method: modelopt、packing: ggml、256 值的 block size 与 payload 字节数。

以每个 74 字节的 IQ2_XS block 为例（表示 256 个逻辑权重）：

• bytes 0–1：little-endian FP16 super-block scaled；
• bytes 2–65：32 个 little-endianuint16code，每 8 个权重一组，code 内含 9 位 codebook 索引 + 7 位符号位（第 8 位符号由奇偶校验推导）；
• bytes 66–73：16 个 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 导出目前不支持，会抛出NotImplementedError；dense 权重与独立命名的 expert 权重仍使用上述表示。

3.2 最小框架版本

文档特别说明：这些是最老的可加载统一 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 列）：

视觉语言/多模态模型：Model-Optimizer 只量化语言模型部分，视觉编码器保持高精度；导出 checkpoint 的多模态服务依赖推理框架自身的多模态支持。✅ 仅代表纯文本冒烟覆盖（套件只发送与语言模型相同的纯文本 prompt，图片/音频输入并未进入 processor 或视觉编码器），不构成多模态服务的证明。

投机解码 drafter：drafters 部署在各自 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/GB300（sm_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 中加载统一 checkpoint

4.1 环境前提

• 安装 TensorRT-LLM（按其官方安装指引，需v1.2.0 或更新，支持 FP8 与 NVFP4 量化模型）；
• 不需要构建 TensorRT engine：export_hf_checkpoint导出的统一 checkpoint 由 TensorRT-LLM 的PyTorch backend直接加载。

4.2 从 Hugging Face Hub 直接加载

以下样例代码可直接运行（来自 3_unified_hf.rst，使用nvidia/Llama-3.1-8B-Instruct-FP8）：

from 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(temperature=0.8, top_p=0.95) llm = LLM(model="nvidia/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(f"Prompt: {prompt!r}, Generated text: {generated_text!r}") if __name__ == '__main__': main()

要点：

• LLM(model=...)既可直接接受 HF Hub 上的模型 ID（如nvidia/Llama-3.1-8B-Instruct-FP8），也可接受本地导出目录；
• 采样参数SamplingParams(temperature=0.8, top_p=0.95)是 TensorRT-LLM PyTorch backend 的标准用法。

4.3 部署本地量化 checkpoint：仓库内实测脚本

在 examples/hf_ptq/run_tensorrt_llm.py 中，Model-Optimizer 提供了完整的本地推理脚本，可用于验证导出的 checkpoint：

python run_tensorrt_llm.py --checkpoint_dir="$SAVE_PATH"

该脚本支持的关键参数：

其内部实现展示了 TensorRT-LLM LLM API 的完整用法（run_tensorrt_llm.py）：

llm = LLM( args.checkpoint_dir, tokenizer=tokenizer, max_batch_size=len(input_texts), enable_kv_cache_reuse=False, # generate_context_logits 需要禁用 prefix block reuse trust_remote_code=args.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产出的rank<N>.safetensors+config.json必须经过trtllm-build编译为 engine 才能服务，而该后端在当前 TensorRT-LLM 版本已不再支持（见文档 warning），这正是它被弃用的直接原因。

六、迁移指南：从旧 API 到export_hf_checkpoint

旧 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 硬约束：推理需要 Blackwell；Hopper 只能产出 checkpoint 不能服务；sm_103（B300/GB300）必须用 CUDA-13 构建。
• 多模态/扩散/投机解码的矩阵边界：✅ 仅表示"文本路径加载 + 生成"冒烟通过，不代表多模态服务、扩散输出或投机解码已被验证。
• GGUF 转换限制：ModelOpt FP8 无法无损转成 GGML 的 FP8 张量类型，需先转换到其他 GGML 支持的张量类型。

如需深入，可继续阅读 统一 HF 导出指南（本文所引支持矩阵的完整出处）与 hf_ptq 示例（量化→导出→推理的端到端实操），后者也提供了使用export_hf_checkpoint导出、再由tensorrt_llm.LLM直接加载的完整代码片段。