Model-Optimizer PTQ 量化交付实战：从 Recipe 到经过校验的 Quantized Checkpoint-育师

人工智能
大模型
模型优化
模型量化
模型压缩

【免费下载链接】Model-Optimizer

A 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 仓库中的 PTQ（Post-Training Quantization，训练后量化）交付流程为主线，系统讲解"如何针对一条已选定的量化 Recipe，在 HuggingFace 模型上产出经过校验、可用于部署与评估的量化检查点"。读者将掌握 Model-Optimizer 的 PTQ 完整执行链：模型支持性检查、量化格式与 Recipe 选择、三类运行路径（直接执行 / Launcher / 未列出模型定制）、校准数据集的取舍，以及作为强制门禁的四项检查点校验（体积与位宽、覆盖度、元数据、服务就绪），并学会以标准交接格式交付结果。本文以仓库内 modelopt-model-quantizer 智能体定义为骨架，结合 PTQ 技能、校验门禁、未列出模型处理与 hf_ptq.py 入口等源码与配置展开。

角色边界：量化执行者，不是策略制定者

仓库为 Day 0 量化流水线划分了明确的职责分工。modelopt-model-quantizer 智能体的定位是：只负责由父级（如 recipe 搜索者）选定的一个 PTQ 候选的检查点产出。它不做以下事情：

不搜索/比较 Recipe 组合（那是quant-recipe-search的职责）；
不部署（deployment）、不评估（evaluation）、不做性能基准（benchmark）、不发布。

这种"一个候选一个执行者"的分工，配合 quant-recipe-search 技能中"候选必须经过评估与对比才能成为推荐 Recipe"的原则，保证了检查点产出的可追踪性与验证完备性。

在执行动作之前，智能体必须先加载三份指令：

指令	作用
ptq/SKILL.md	PTQ 全流程：环境、支持性、格式选择、运行、校验
monitor/SKILL.md	提交长任务后注册并监控作业
common/workspace-management.md	按会话/模型组织工作区，串联 PTQ → Deploy → Eval

其中有一条硬性纪律：PTQ 检查点校验门禁（checkpoint-validation gate）是强制性的。校准之前必须验证 Recipe 覆盖度（coverage）；凡是输出、覆盖度、元数据、服务就绪任一校验不过的检查点，不得交接。只有在模型支持确实需要时，才允许对 Model Optimizer 源码做最小改动，且必须逐一报告每个改动文件。

环境准备：三件事必须先弄清楚

按照 environment-setup.md，开工前要确认三件事：

ModelOpt 源码可用：ls examples/hf_ptq/hf_ptq.py能命中即认为源码就绪（必要时git pull origin main保持最新）。
本地还是远端：优先读取~/.config/modelopt/clusters.yaml（或.claude/clusters.yaml）判断是否配置了集群；有集群配置则默认走远端执行。
可用的计算形态：在目标机器上探测srun/sbatch（SLURM）、docker info（Docker+GPU）、nvidia-smi（裸 GPU 型号与显存），并检查tools/launcher/launch.py是否存在以确认 Launcher 可用。没有 GPU 时任务直接终止，因为 PTQ 必须跑在 CUDA 上。

工作区组织遵循 workspace-management.md：每个会话（session id）下按"模型-格式"建目录，例如workspaces/<session_id>/qwen3-0.6b-nvfp4/，输出检查点放output/、日志放logs/、定制脚本放scripts/。这样 PTQ → 部署 → 评估各阶段在同一目录上接力，不会互相覆盖；远端执行时本地与远端建同名工作区，模型只在远端下载以避免大文件传输。

第一步：确认模型是否受支持

在 examples/hf_ptq/README.md 的支持矩阵表中查找目标模型：

已列出→ 直接使用 hf_ptq.py 运行完整校准（--calib_size 512）；
未列出→ 阅读 unsupported-models.md 判断能否用hf_ptq.py直接跑，还是需要定制脚本。

支持矩阵覆盖了主流架构：LLaMA 3.x/4、Mixtral、Phi 系列、Gemma 3、Qwen 2/2.5/3 及 3.5-MoE/Next、DeepSeek V3/R1、GPT-OSS、Nemotron 系列，以及 Llava、Qwen-VL、Nemotron VL 等视觉语言模型（VLM）；格式维度支持 fp8、int8_smoothquant、int4_awq、w4a8_awq_beta、nvfp4 等。需要说明的是：矩阵是"经过验证的支持子集"，未列出不等于不能跑——ModelOpt 会通过nn.Linear、attention、含gate+experts的 MoE 块等标准模块自动检测，许多未列出模型可以直接开箱工作。

模型特定依赖检查

若模型启用了trust_remote_code（config.json中有auto_map），需检查其自定义 Python 文件是否引用了容器内没有的包：

grep -h "^from \|^import " <model_path>/modeling_*.py | sort -u

已知的依赖模式：出现from mamba_ssm/from causal_conv1d时，需要安装mamba-ssm causal-conv1d（Mamba/混合架构模型，如 NemotronH、Jamba）。安装方式分两条路：

Launcher 路径：在任务的environment区设置EXTRA_PIP_DEPS，ptq.sh会自动安装。注意EXTRA_PIP_DEPS会被写入未加引号的export，因此禁止>/<等 shell 元字符，必须用精确的==固定版本，例如EXTRA_PIP_DEPS: "transformers==5.5.0"（见 launcher-guide.md）。
手动路径：unset PIP_CONSTRAINT && pip install <deps>之后再跑hf_ptq.py。

第二步：选择量化格式与 Recipe

按 GPU 选格式

没有模型专属 Recipe 时，根据 GPU 型号决定量化格式（详见 hf_ptq.py 支持矩阵）：

Blackwell（B100/B200/GB200）：优先nvfp4系列；
Hopper（H100/H200）或更老：fp8或int4_awq。

格式定义集中维护在 modelopt/torch/quantization/config.py：FP8_DEFAULT_CFG、INT4_AWQ_CFG、NVFP4_DEFAULT_CFG、NVFP4_EXPERTS_ONLY_CFG、NVFP4_MLP_ONLY_CFG、NVFP4_OMLP_ONLY_CFG等常量均由configs/ptq/presets/model/*加载。命令行用--qformat <name>即可引用同名格式，通用 PTQ Recipe（modelopt_recipes/general/ptq/下的 YAML）与这些格式一一对应，--qformat是它们的简化用法。

重要前提：NVFP4 可以在 Hopper 上完成校准，但推理必须使用 Blackwell GPU。

Recipe 优先原则与覆盖率预检

选择格式的第一优先是查找模型专属 Recipe：

ls modelopt_recipes/models/ 2>/dev/null ls modelopt_recipes/model_type/<model_type>/ptq/ 2>/dev/null # <model_type> 取自本地 config.json

存在模型专属 Recipe 时优先--recipe <path>——但不要假设它一定正确，必须检查其 include/exclude 模式。校准前先做一次"覆盖率 sanity check"：总结哪些层组会被量化、大概命中多少模块/层（attention 投影、MLP 投影、experts 等）。如果命中数为 0，或远小于该模型的预期规模，应停下修复 Recipe 或先征询用户，再启动校准。

这一点正是 modelopt-model-quantizer 职责中"verify recipe coverage before calibration"的落地点：量化配置的 wildcard 模式可能因模型命名不标准而静默漏层——漏层在 PTQ 阶段不报错，直到部署时推理框架把 BF16 权重当量化权重加载才暴露为失败。

VLM 的 vision tower 陷阱

通用的*mlp*/*experts*Recipe 会同时命中视觉塔（model.visual.*），把 ViT 量化后会静默破坏图像基准（文字表现正常、图像指标接近 0）。对策：优先使用model_type/<model_type>/ptq/的 Recipe，或手动添加*visual*/*vision_tower*排除项。仓库的默认禁用单元 default_disabled_quantizers.yaml 正是为这类风险准备的——它统一禁用了*embed_vision*、*vision_tower*、*visual*、*vision_model*、*multi_modal_projector*以及lm_head、router、*output_layer*、mtp.*、BatchNorm、Embedding 等不应量化的模块。

源检查点已量化时的处理

如果源检查点本身已量化，而所选 Recipe 会降低量化覆盖度（例如 FP8 检查点 + 排除某些层的 Recipe，会把这些层从 FP8 退回 BF16），必须先与用户确认意图再运行，明确列出受影响的层组并确认 FP8→BF16 回退是否符合预期。

第三步：运行 PTQ——三条路径

目标产物是磁盘上的检查点：.safetensors+config.json（含 tokenizer 文件）。选择路径的决策流程如下：

在 README 支持表中？ ─→ YES ─→ SLURM（本地或远端）? ─→ LAUNCHER（4B） │ 本地 Docker + GPU? ─→ LAUNCHER（4B） │ 远端 Docker（无 SLURM）? ─→ MANUAL（4A） │ 裸 GPU（本地或远端）? ─→ MANUAL（4A） │ └→ 未列出 ──→ 未列出模型路径（4C）

4A — 直接执行（受支持模型、手动运行）

pip install --no-build-isolation "nvidia-modelopt[hf]" pip install -r examples/hf_ptq/requirements.txt python examples/hf_ptq/hf_ptq.py \ --pyt_ckpt_path <model> \ --qformat <format> \ --calib_size 512 \ --export_path <output>

hf_ptq.py --help可查看全部参数。远端机器上通过 common 技能的remote_exec.sh中的remote_run执行。

4B — Launcher（SLURM 或本地 Docker）

使用 tools/launcher 提交。先写一个 YAML 配置，common/hf/ptq.sh负责封装hf_ptq.py，通过环境变量配置：

job_name: <Model>_<Format> pipeline: task_0: script: common/hf/ptq.sh environment: - HF_MODEL: <HuggingFace model ID, e.g. Qwen/Qwen3-0.6B> - QFORMAT: <format, e.g. nvfp4, fp8, int4_awq> - CALIB_SIZE: "512" - EXPORT_PATH: /scratchspace/exported_model slurm_config: _factory_: "slurm_factory" nodes: 1 ntasks_per_node: 1 gpus_per_node: <num_gpus>

提交命令：

cd tools/launcher # SLURM（远端或本地）： SLURM_HOST=<host> SLURM_ACCOUNT=<acct> uv run launch.py --yaml <config.yaml> user=<ssh_user> identity=<ssh_key> --yes # 本地 Docker： uv run launch.py --yaml <config.yaml> hf_local=<hf_cache> --yes

关键细节（见 launcher-guide.md）：

gpus_per_node必须匹配集群节点 GPU 数/QOS 下限，否则sbatch会被QOSMinGRES拒绝；
EXPORT_PATH控制容器内路径（默认/scratchspace/exported_model），Launcher 自动将/scratchspace挂载到宿主机目录；
SLURM_HF_LOCAL指定 HF 缓存 bind-mount 路径，ptq.sh复用已缓存的模型可跳过下载；
额外的hf_ptq.py参数通过args传入（如--batch_size 2、--trust_remote_code）。

Launcher 会阻塞并实时 tail 日志直到作业完成；若 Launcher 自身失败（缺依赖、配置错误），回退到 4A 手动执行。

4C — 未列出模型

按 unsupported-models.md 的四步走：调查模型 → 必要时打补丁 → smoke test（--calib_size 4）→ 完整校准。调查要点包括：

读 README / config.json：确定 transformers 版本要求与trust_remote_code需求；带自定义modeling_*.py的模型必须加--trust_remote_code；
判断是否已是 FP8 量化检查点：config.json有"quant_method": "fp8"或权重含*_scale_inv*。标准FP8Linear模块由 ModelOpt 的_QuantFP8Linear插件自动接管（见 huggingface.py），不需要手动反量化，也不要用FineGrainedFP8Config(dequantize=True)（那会先把整个模型展开成 BF16，浪费约 2 倍显存）；
对照命名检查配置模式：用脚本扫描model.safetensors.index.json中的参数名，与所选 quant config 的 wildcard 模式比对，找出会静默漏掉的非标准命名；
确定需要的补丁模式：融合专家权重（3D[num_experts, in, out]）、自定义nn.Parameter、VLM 结构、非标准 FP8 参数名分别对应 Pattern 1/2/4/5。

补丁的首选方式是直接修改 huggingface.py 插件文件——它已注册了Llama4TextExperts、FP8Linear、FalconLinear、Conv1D、Qwen3_5MoeExperts等常见非标准模块的量化实现，并通过register_sparse_moe_on_the_fly（第 1653 行）与register_fused_experts_on_the_fly（第 1725 行）在运行时自动注册 MoE 专家模块。自定义量化模块必须遵守三条硬规则：方法名必须是_setup且由__init__调用；quantizer 名必须以_input_quantizer或_weight_quantizer结尾；量化后应调用mtq.print_quant_summary(model)确认没有 quantizer 被静默禁用。

校准数据集的选择

纯文本 LLM：优先nemotron-post-training-v3混合集（由 dataset_utils.py 展开为七个已注册的 Nemotron SFT 域），需要时配置 HF 凭证：
```
python examples/hf_ptq/hf_ptq.py ... --dataset nemotron-post-training-v3
```
VLM：加--calib_with_images走图文校准，使用nemotron_vlm_dataset_v2，默认子集为sparsetables、plotqa_cot、wiki_en（实现见 hf_ptq.py 与 vlm_dataset_utils.py）。该模式下--calib_size必须传单值。
兜底：--dataset cnn_dailymail仅用于代表性数据不可用的受限环境（如无门控数据权限、只有本地公共缓存），不是首选校准集。

校准规模的经验值：默认--calib_size 1024，完整校准推荐 512 样本；未列出模型先用--calib_size 4做 smoke test。--calib_seq默认 512（校准最大序列长度），--batch_size默认 0 表示按显存自动探测。

任务监控

第四步：输出校验——强制门禁

运行完成后先确认产物：

ls -lh <output_path>/ # 期望：config.json、tokenizer 文件、model-*.safetensors

随后执行 checkpoint-validation.md 定义的四组校验。这是部署/评估提交前不可跳过的门禁，必须在将要部署/评估的那个确切检查点路径上执行：

体积与每权重位宽：量化检查点磁盘体积应小于源检查点，估算位宽更低。用脚本只对比.safetensors权重文件（不算缓存与评估产物），计算输出/源体积比作为位宽的一阶代理。压缩 Recipe 下比值 ≥ 1.0x 即为阻塞项，除非source_precision能解释（源精度已低于等于目标位宽）或用户明确接受。
量化权重覆盖度：逐一核对实际被量化的权重与请求的 qformat/Recipe 目标是否一致，按 NVFP4 / FP8 / INT4 / BF16-或-排除 / unexpected / declaration mismatch 分类计数。覆盖脚本会读取hf_quant_config.json，对每个线性层检查其是否有 scale 张量、与声明的精度是否一致，并识别"有 scale 但声明为排除"与"无 scale 但不在排除列表"两类异常。
元数据一致性：generation 设置、tokenizer 文件、chat template、模型架构字段、max position/context length、特殊 token 必须与源模型一致——量化只应改变权重与量化元数据，不应悄悄改变提示与生成行为。每个 diff 都要记录并归类为预期或阻塞。
服务就绪验证：记录确切的检查点 workspace 与路径（部署与评估技能必须继承同一路径），盘点 PTQ 期间所有兼容性改动（依赖升级、源码补丁、自定义代码、环境变量、Launcher/容器变更，没有就写none），然后调用 deployment 技能在该路径上启动服务，跑一个 canary 查询（如What is the capital of France?）并要求有效应答，验证后停止 canary 服务。

门禁报告格式

移交前必须按如下表格汇报：

Check	Result
Size vs source	`<output> GB / <source> GB = <ratio>x`；仅当比值符合 Recipe 压缩意图才 PASS
Source precision	源权重的 dtype（`bf16`/`fp16`/`fp32`/`fp8`/`int8`/`mxfp4`/`nvfp4`/`fp4`/`int4`/`w4a16`/`awq`/`4bit`之一）；混合源记录主导权重质量的精度
Layer precision counts	`<count> NVFP4 / <count> FP8 / <count> INT4 / <count> BF16-or-excluded / <count> unexpected / <count> declaration mismatches`
Metadata	`no unexpected diffs`或列出确切 diffs
Checkpoint workspace/path	确切的 workspace 与检查点路径
PTQ compatibility requirements	`dependency upgrades: ...; source patches: ...; custom code: ...; environment variables: ...; launcher/container changes: ...`；每类没有就写`none`
Serving canary	`<目标环境>; <框架与启动配置>; <查询> -> <响应>`；仅当部署技能从记录的路径成功启动并返回有效响应才 PASS

出现以下任一情况必须停止：压缩 Recipe 下输出/源比值 ≥ 1.0（且source_precision无法解释）；本应量化的层组覆盖度为 0 或异常低；任一层量化元数据与声明精度不一致；提示/tokenizer/generation/架构/上下文长度/特殊 token 元数据意外变化；检查点路径缺失或未保留；任何兼容性类别被省略；部署技能无法从记录路径启动；canary 无有效响应。

VLM 专属检查：视觉塔必须保持未量化

多模态检查点需额外确认视觉分支不带任何量化 scale（脚本会兼容分片与非分片导出，遍历model.visual/vision_tower/vision_model前缀下含weight_scale/input_scale的张量，期望计数为 0）。计数非零说明 ViT 被量化了，应改用model_type/<model_type>/ptq/Recipe 或添加*visual*/*vision_tower*排除后重新量化——因为通用的*mlp*/*experts*Recipe 会静默命中 ViT 的 MLP，产生垃圾图像嵌入（MMMU-Pro 接近 0%），而文字任务看起来却完全正常。

各格式的预期量化模式

Recipe（`--qformat`）	应量化内容	应排除内容
`nvfp4`	所有线性层	lm_head、router、norm、embedding
`nvfp4_mlp_only`	MLP 层（含 MoE experts）	attention、lm_head、router
`nvfp4_experts_only`	仅 MoE expert 层	稠密 MLP、attention、lm_head、router
`nvfp4_omlp_only`	MLP +`o_proj`层	其余 attention 层、lm_head、router
`fp8`	所有线性层	lm_head、norm、embedding
`int4_awq`	所有线性层	lm_head、norm、embedding

常见的 pattern 漏配

模型	模块路径	被`mlp`等模式漏掉	修复
Gemma4 MoE	`layers.N.experts.*`	`mlp`、`block_sparse_moe`	添加`.experts.`
自定义 MoE	`layers.N.moe_block.experts.*`	`mlp`	添加匹配模式
VLM projector	`multi_modal_projector.*`	—	通常排除，需验证

出现警告时的处理原则：本应量化的层被漏掉 → 在配置中补充缺失模式并重跑 PTQ（先检查 ModelOpt 是否已有对应模型的插件）；故意不量化的层（如nvfp4_mlp_only下的 attention）→ 应出现在exclude_modules中，若导出时未写入，需手工补进hf_quant_config.json与config.json的quantization_config.ignore，避免部署期加载失败。

从 Recipe 到配置的源码级视角

Recipe 是声明式 YAML，通过$import组合量化单元。以仓库内置的 nvfp4_default-kv_fp8_cast.yaml 为例，它依次导入四个单元：

base_disable_all.yaml：quantizer_name: '*'+enable: false，先关闭全部 quantizer 再选择性开启；
w4a4_nvfp4_nvfp4.yaml：对所有*weight_quantizer/*input_quantizer启用动态 NVFP4；
kv_fp8_cast.yaml：对*[kv]_bmm_quantizer启用 FP8 E4M3 KV cache 量化并固定use_constant_amax: true（cast 模式，无数据驱动校准，速度快）；
default_disabled_quantizers.yaml：排除 router、lm_head、vision 分支、BatchNorm、Embedding 等。

--qformat nvfp4_mlp_only对应的 nvfp4_mlp_only-kv_fp8_cast.yaml 则只对*mlp*、*block_sparse_moe*、*.experts.*的 weight/input quantizer 启用 NVFP4，attention 保持 BF16——这就是 hf_ptq/README.md 建议在 NVFP4 上优先 MLP-only / experts-only / OMLP-only 以提高精度的原因。

在代码侧，hf_ptq.py 的量化主流程依次是：load_model（默认不指定 dataset 时回退到cnn_nemotron_v2_mix，即 cnn_dailymail + nemotron-post-training-dataset-v2）→make_calib_dataloader→pre_quantize（量化前单样本生成预览，供前后对比）→mono_quantize或auto_quantize（后者仅当--recipe解析为 AutoQuantize Recipe）→post_quantize（打印mtq.print_quant_summary、量化后生成 sanity check）→export_quantized（统一 HF 检查点导出）。入口还包含关键的运行期约束：mto.enable_huggingface_checkpointing()必须在量化前调用（第 151 行）；--low_memory_mode与--recipe互斥（低内存加载器从--qformat预埋 quantizer，无法遵从 Recipe）；--use_fsdp2要求 torchrun 启动且不支持 KV AutoQuantize、sparsity、--cast_mxfp4_to_nvfp4。这些交叉校验在 parse_args 中集中完成，并有 test_hf_ptq_args.py 等测试覆盖（如 KV AutoQuantize 与 FSDP2 的组合拒绝、AutoQuantize 候选的导出安全白名单校验等）。

关键 API 规则速查

mtq.register()注册的量化类必须定义_setup()并在__init__中调用；
量化前必须调用mto.enable_huggingface_checkpointing()；
wildcard*gate*匹配过宽，应用*mlp.gate*或*router*；
VLM 无需手动处理：hf_ptq.py通过extract_and_prepare_language_model_from_vl()自动抽取语言模型并禁用视觉/投影模块的量化（hf_ptq.py）；
FP8 检查点优先用_QuantFP8Linear（lazy dequant），避免FineGrainedFP8Config(dequantize=True)约 2 倍显存开销；
自定义 quantizer 名必须以_input_quantizer或_weight_quantizer结尾，wildcard 才能匹配。

常见坑速查

模型特定依赖：trust_remote_code模型可能引入容器外依赖（如混合 Mamba 模型的mamba-ssm），用EXTRA_PIP_DEPS或手动先装；
transformers 版本：新架构可能需要更新的 transformers（查看config.json的transformers_version）；NGC 容器里的PIP_CONSTRAINT会阻塞升级，需unset PIP_CONSTRAINT或--no-deps绕过（见 slurm-setup-ptq.md）；
门禁数据集：部分校准数据集需要 HF 认证，在作业环境设置HF_TOKEN；cnn_dailymail只是受限环境的兜底；
NFS root_squash + Docker：见 common 技能的 slurm-setup 相关章节。

标准交接格式

量化与校验全部通过后，只返回一份精简交接报告，不输出原始日志。标题固定为以下八个，内容包含请求与观察到的覆盖度、体积、作业 ID 与绝对路径：

Status Source checkpoint Recipe Quantized checkpoint Validation Artifacts Changes Blockers

这份格式化的交接使得父级（recipe 搜索者）与下游（deployment / evaluation）可以仅凭报告继续工作：确切的检查点路径被后续技能继承，PTQ 期间的兼容性改动被逐一记录，覆盖度与位宽数据成为下一个候选决策的证据。整个闭环——选定 Recipe → 执行 PTQ → 强制校验 → 标准交接——正是 Model-Optimizer 以"已验证检查点"为单位交付量化能力的工程化实践。