人工智能大模型模型优化模型量化模型压缩【免费下载链接】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 中plugins/modelopt/skills/ptq/SKILL.md的完整执行流程系统讲解如何用 Model OptimizerModelOpt对预训练 Hugging Face 模型执行后训练量化Post-Training Quantization, PTQ最终产出一个可直接部署的量化 Checkpoint.safetensorsconfig.json。读完本文你将掌握量化格式与 Recipe 的选择方法、examples/hf_ptq/hf_ptq.py三种运行路径手动 / Launcher / 未列出模型、校准数据集的选择原则以及部署前必须通过的量化后验证门禁。本文所有命令与参数均来自仓库内真实文档与源码可直接对照复现。Step 1 — 环境准备PTQ 需要一张 NVIDIA GPU 与完整的 ModelOpt 运行环境。SKILL 建议先完成环境与工作区管理确认以下信息就绪ModelOpt 源码可用建议在仓库根目录执行pip install -e .[hf] --no-build-isolation该方式与 examples/hf_ptq/slurm/multinode_fsdp2_ptq.slurm 的容器内安装方式一致能尽早暴露构建问题本地或远程执行环境远程还需集群配置运行方式SLURM / DockerGPU / 裸 GPU是否有 Launcher 可用见 tools/launcher选用哪个工作区存放模型与输出。HF 模型的推荐运行环境是 TensorRT-LLM Docker 镜像如nvcr.io/nvidia/tensorrt-llm/release:1.2.0。也可本地安装 Model Optimizer 与示例依赖pip install --no-build-isolation nvidia-modelopt[hf] pip install -r examples/hf_ptq/requirements.txtStep 2 — 模型是否受支持首先查阅 examples/hf_ptq/README.md 的Hugging Face Supported Models 支持矩阵确认目标模型是否在已验证列表中。已在列表→ 受支持直接使用hf_ptq.py对应下文 Step 4 的路径 4A/4B不在列表→ 阅读 references/unsupported-models.md判断hf_ptq.py是否仍可工作或需要自定义脚本对应路径 4C。支持矩阵节选完整表见 README涵盖了 LLAMA 3.x/4、Mixtral、Phi-3/4、Llama-Nemotron Super/Ultra、Gemma 3、QWen 2/2.5/3、DeepSeek V3/R1、GPT-OSS、T5、Whisper、Nemotron-3以及 LLaVA、Qwen-VL、Nemotron VL 等视觉语言模型VLM。不同模型可用的格式不同例如 LLAMA 4 仅支持 fp8 与 nvfp4而 DeepSeek 与 Kimi K3 只列出 nvfp4。一个值得注意的例外是Kimi K3其 routed experts 以打包的 MXFP4 张量发布因此不使用内存内hf_ptq.py流程而是走校准无关的 streaming converter见 examples/kimi/README.md。注意矩阵脚注中的关键限制NVFP4 推理要求 Blackwell GPU 与 TensorRT-LLM v1.2w4a8_awq_beta 是实验性格式精度损失可能更大VLM 默认只量化语言模型视觉编码器保持高精度除非显式传--vlm或使用视觉量化 Recipe不在支持矩阵 ≠ 不能运行ModelOpt 会自动识别标准 HF 模块linear 层、attention、含gateexperts的 MoE 块许多未列出模型可直接跑通。Step 2.5 — 检查模型特定依赖若模型需要trust_remote_code查看本地config.json是否含auto_map先检查其自定义 Python 文件是否引用了容器中没有的包grep -h ^from \|^import model_path/modeling_*.py | sort -u已知依赖模式导入语句需安装的包适用模型from mamba_ssm/from causal_conv1dmamba-ssm causal-conv1dMamba/混合模型NemotronH、Jamba安装方式取决于运行路径Launcher4B在任务environment区设置EXTRA_PIP_DEPScommon/hf/ptq.sh 会自动安装手动4A运行hf_ptq.py前先unset PIP_CONSTRAINT pip install deps。此外注意transformers 版本新模型可能需要比容器更新的 transformers。查看config.json的transformers_version字段在容器中PIP_CONSTRAINT可能阻止升级需先unset PIP_CONSTRAINT详见 references/slurm-setup-ptq.md。Step 3 — 选择量化格式先查模型特定 Recipels modelopt_recipes/models/ 2/dev/null ls modelopt_recipes/model_type/model_type/ptq/ 2/dev/null # 按架构model_type 取自本地 config.jsonHub IDAutoConfig.from_pretrained若存在模型特定 Recipe优先使用--recipe path——但必须检查其 include/exclude 模式不要想当然例如对 VLM确认视觉塔确实被排除。无模型特定 Recipe 时按 GPU 选格式BlackwellB100/B200/GB200nvfp4系列HopperH100/H200或更老fp8或int4_awq。NVFP4 可以在 Hopper 上校准但推理必须用 Blackwell。使用--qformat name如--qformat nvfp4是最简单的选格式方式。格式定义位于 modelopt/torch/quantization/config.py通用 PTQ Recipe 位于 modelopt_recipes/general/ptq/如nvfp4_default-kv_fp8_cast.yaml、fp8_default-kv_fp8_cast.yaml、nvfp4_mlp_only-kv_fp8_cast.yaml、nvfp4_experts_only-kv_fp8_cast.yaml等两者对应同一批格式--qformat是更简单的用法。核心量化格式一览ModelOpt 支持以下主要格式对应config.py中的常量与--qformat取值qformat说明主要适用 GPUfp88-bit 浮点权重激活量化校准快、精度稳健Hopper / AdaCC≥8.9nvfp4Blackwell 4-bit 浮点权重 4bit 激活压缩率高Blackwell推理nvfp4_mlp_only仅量化 MLP含 MoE层attention 保持高精度Blackwell推理nvfp4_experts_only仅量化专家层*mlp.experts*与*block_sparse_moe*适合 MoEBlackwell推理nvfp4_omlp_onlyMLP-only 基础上额外量化o_projBlackwell推理int8_smoothquantINT8 权重激活SmoothQuant 算法Hopper / 更老int8_weight_onlyINT8 仅权重通用int4_awqINT4 仅权重 AWQ低 batch 推理延迟最优Hopper / 更老w4a8_awq_betaINT4 权重 FP8 激活实验性通用从源码看这些常量如 NVFP4_DEFAULT_CFG、NVFP4_MLP_ONLY_CFG、NVFP4_EXPERTS_ONLY_CFG、NVFP4_OMLP_ONLY_CFG、FP8_DEFAULT_CFG、INT4_AWQ_CFG、W4A8_AWQ_BETA_CFG都由_load_quantize_config_dict(configs/ptq/presets/model/name)从 YAML 预设加载即--qformat与 Recipe 本质同源。对于NVFP4 高精度场景仓库 README 明确建议优先使用nvfp4_mlp_only、nvfp4_experts_only或nvfp4_omlp_only将敏感的自注意力 QKV 投影保持未量化同时仍获得显著压缩。运行前必须做的 sanity-check在启动校准之前检查所选 qformat/Recipe 的 include/exclude 模式并总结哪些层组会被量化、大约匹配到多少模块/层attention 投影、MLP 投影、专家等。如果匹配数为 0 或远小于预期立即停下修正 Recipe 或询问用户不要盲目启动校准——量化配置模式可能因模型命名不标准而静默漏掉层这在部署阶段才会暴露为框架把未量化权重当作量化权重加载的失败。VLM 特殊注意通用的*mlp*/*experts*Recipe 也会匹配视觉塔model.visual.*量化 ViT 会静默破坏图像 benchmark。请使用model_type/model_type/ptq/下的 Recipe或添加*visual*/*vision_tower*排除项并在 Step 5 中验证见 references/checkpoint-validation.md。另外如果源 Checkpoint 已被量化、而请求的 Recipe/配置会缩减量化覆盖范围必须与用户确认意图。例如输入是 FP8 CheckpointRecipe 排除某些层使其回退为 BF16则应明确指出受影响的层组并确认该 FP8→BF16 回退是否符合预期。Step 4 — 运行 PTQ目标磁盘上有一个量化 Checkpoint.safetensorsconfig.json。已支持模型4A/4B直接完整校准--calib_size 512未支持模型4C先跑冒烟测试--calib_size 4成功后做完整校准。推荐校准数据集纯文本 LLM PTQ优先使用代表性的nemotron-post-training-v3混合集。modelopt/torch/utils/dataset_utils.py 中DATASET_COMBOS将其展开为七个已注册的 Nemotron SFT 领域如 nemotron-sft-instruction-following-chat-v2、nemotron-science-v1、nemotron-competitive-programming-v1 等。需要时配置 Hugging Face 凭据python examples/hf_ptq/hf_ptq.py ... \ --dataset nemotron-post-training-v3VLM PTQ使用图文校准--calib_with_images。该路径使用nemotron_vlm_dataset_v2默认子集为sparsetables、plotqa_cot、wiki_enexamples/hf_ptq/hf_ptq.py 与 modelopt/torch/utils/vlm_dataset_utils.py 是权威依据python examples/hf_ptq/hf_ptq.py ... \ --calib_with_images注意--dataset只选文本校准数据不能替代多模态样本。仅在代表性数据不可用无 gated-data 权限、只有本地公共缓存时才用--dataset cnn_dailymail作为兜底。三种运行路径在 README 表中 ─→ 是 ──→ SLURM本地或远程 ──→ LAUNCHER4B │ 本地 Docker GPU ───────→ LAUNCHER4B │ 远程 Docker无 SLURM ─→ MANUAL4A │ 裸 GPU本地或远程 ───→ MANUAL4A │ └→ 不在表中 ──→ UNLISTED MODEL4C4A — 直接执行已支持模型手动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运行--help查看全部选项。远程环境使用 common skill 的remote_exec.sh的remote_run。4B — Launcher已支持模型SLURM 或本地 Docker编写 YAML 配置使用 tools/launcher/common/hf/ptq.sh 包装hf_ptq.py。完整的现成示例见 tools/launcher/examples/Qwen/Qwen3-8B/hf_ptq.yaml其核心结构为job_name: hf_ptq_nvfp4 pipeline: global_vars: hf_local: /hf-local/ hf_model: Qwen/Qwen3-8B task_0: script: common/hf/ptq.sh args: - --repo global_vars.hf_model - --local-dir global_vars.hf_localglobal_vars.hf_model - -- - --quant nvfp4 - --tasks quant slurm_config: _factory_: slurm_factory nodes: 1 ntasks_per_node: 1 gpus_per_node: 1 time: 04:00:00 container: nvcr.io/nvidia/tensorrt-llm/release:1.3.0rc20运行在 tools/launcher 目录下# SLURM远程或本地 SLURM_HOSThost SLURM_ACCOUNTacct uv run launch.py --yaml config.yaml userssh_user identityssh_key --yes # 本地 Docker uv run launch.py --yaml config.yaml hf_localhf_cache --yesLauncher 会阻塞并实时 tail 日志直到任务完成。若 Launcher 失败缺依赖、配置错误回退到 4A 手动执行。Launcher 相关要点见 references/launcher-guide.mdgpus_per_node必须匹配集群节点 GPU 数 / QOS 最低要求否则sbatch会以QOSMinGRES或Requested node configuration is not available拒绝任务EXTRA_PIP_DEPS中避免 shell 元字符如、否则写入未加引号的export后会被 shell 重定向吞掉用精确固定版本EXPORT_PATH控制容器内路径默认/scratchspace/exported_modelLauncher 自动把/scratchspace挂载到宿主机目录本地 Docker 下用find tools/launcher/local_experiments -name config.json -path */exported_model/*找结果远程 SLURM 下结果在远程机器上通常在~/experiments/...。4C — 未列出模型按 references/unsupported-models.md 走完整调查流程下载模型 → 判断架构是否已知 → 检查是否已 FP8 量化 → 确定需要哪些自定义补丁 → 对照 ModelOpt 配置模式核对权重命名 → 运行并迭代。建议像 4A 一样手动运行以便监控和调试。调查流程的核心结论大多数模型是标准nn.Linear结构无需任何自定义代码即可被自动量化先检查 modelopt/torch/quantization/plugins/huggingface.py 是否已注册该非标准模块的补丁Llama4TextExperts、FP8Linear、FalconLinear、Conv1D、Qwen3_5MoeExperts等需要自定义补丁的典型场景融合/批量专家权重3D 张量而非独立nn.Linear、直接用nn.Parameter的自定义权重、需要排除视觉编码器的 VLM、非标准参数名的 FP8 Checkpoint自定义QuantModule的硬性规则_setup()方法必须存在并在__init__中调用量化器名必须以_input_quantizer或_weight_quantizer结尾若需要mtq.register()或QuantModuleRegistry.register注册新模块完成后总是运行mtq.print_quant_summary(model)验证FP8 Checkpoint优先_QuantFP8Linear惰性反量化不要用FineGrainedFP8Config(dequantizeTrue)会把整个模型展开为 BF16浪费约 2 倍显存。SLURM 手动执行时参考 references/slurm-setup-ptq.md容器镜像处理.sqsh复用或 enroot 导入、GPU 数量估算hf_ptq.py用device_mapauto自动填充 GPU、先跑冒烟测试--calib_size 4、--time00:30:00再提交完整校准。hf_ptq.py 关键命令行参数来自源码 parse_args参数默认值说明--pyt_ckpt_path/--model必填模型路径或 Hugging Face 模型名--qformatfp8单格式 PTQ 的量化格式--recipe存在时被忽略--recipeNonePTQ / AutoQuantize Recipe YAML 文件或名称无后缀如general/ptq/nvfp4_default-kv_fp8_cast--calib_size1024校准样本数支持逗号分隔列表每个数据集一个值--calib_seq512校准最大序列长度--batch_size0校准 batch size0 表示按显存自动探测最大值--export_pathexported_model量化 Checkpoint 输出目录--dataset默认cnn_nemotron_v2_mix数据集名或逗号分隔列表可用集见get_supported_datasets()--kv_cache_qformatfp8_castKV cache 量化格式none关闭--calib_with_imagesFalse图文校准VLM使用 nemotron_vlm_dataset_v2--trust_remote_codeFalse为使用自定义建模代码的模型开启--use_fsdp2False多节点 FSDP2 分布式校准需 torchrun 启动--low_memory_modeFalse低显存模式加载时即压缩权重仅 FP8/NVFP4 max 校准--awq_block_size0AWQ 块大小--moe_calib_experts_ratioNoneMoE 模型校准的专家比例取值(0.0, 1.0]--cast_mxfp4_to_nvfp4FalseGPT-OSS 等 MXFP4 Checkpoint 的封闭式 NVFP4 转换--auto_quantize_checkpointNoneAutoQuantize 搜索状态保存/恢复--skip_generateFalse跳过量化前后model.generate()预览--vllm_fakequant_exportFalse导出 vLLM fake-quant Checkpoint--mlflow uri—记录 PTQ 运行到 MLflow 服务器KV cache 量化格式--kv_cache_qformat详见 examples/hf_ptq/README.md 的 KV Cache Quantization 小节fp8_cast默认无校准的常量 amax、fp8、fp8_affine、nvfp4_cast、nvfp4、nvfp4_affine、nvfp4_rotate、none。以_cast结尾的格式直接把 amax 设为格式满量程速度快其他格式使用数据驱动校准精度可能更好。Recipe 体系补充除--qformat外--recipe是推荐的前进方向hf_ptq.py中--recipe优先于--qformat通用 PTQ Recipemodelopt_recipes/general/ptq/如nvfp4_default-kv_fp8_cast按架构调优的 Recipemodelopt_recipes/model_type/model_type/ptq/模型特定 Recipemodelopt_recipes/models/如 nvidia、Qwen、deepseek-ai 目录下。Recipe 对 KV cache 的处理PTQ Recipe 把 KV cache 编入自身配置并忽略--kv_cache_qformatAutoQuantize Recipe 回退到--kv_cache_qformat除非显式设置kv_cache字段。python examples/hf_ptq/hf_ptq.py \ --pyt_ckpt_path huggingface_model_card \ --recipe general/ptq/nvfp4_default-kv_fp8_cast \ --export_path quantized_ckpt_path监控任务提交后按monitor skill注册任务并设置监控。Step 5 — 验证输出基础检查ls -lh output_path/ # 预期config.json、tokenizer 文件、model-*.safetensors向用户报告路径与大小。量化后验证门禁部署前强制关卡这是任何部署或评测提交之前的强制门禁。在确认为可部署/可评测状态之前不得提交评测、启动生产 serving 或交接 Checkpoint含 serving canary 通过前。按 references/checkpoint-validation.md 对即将部署/评测的确切 Checkpoint 路径执行四组验证大小与每权重位数量化 Checkpoint 磁盘大小应小于基线/源 Checkpoint且估算每权重位数更低。用脚本对比 safetensors 大小输出/源 ≥ 1.0x对压缩 Recipe 是阻塞项除非source_precision说明源本就等于或低于目标位数如 mxfp4 源配 nvfp4 Recipe 无法再缩小量化权重覆盖率实际量化的权重与请求的 qformat/Recipe/配置一致。用层精度统计脚本按实际/声明精度分组计数NVFP4、FP8、INT4、BF16/未量化排除、意外未量化、声明不一致。量化配置模式可能因非标准命名静默漏掉层——只在部署时服务框架试图以量化格式加载未量化权重时才暴露元数据一致性不应改变的元数据与基线一致生成设置、tokenizer 文件、chat template、模型架构字段、max positions/上下文长度、特殊 token。量化只应改变权重与量化元数据不应静默改变提示或生成行为下游交接与 serving 就绪记录确切的 Checkpoint 工作区与路径下游 skill 必须继承盘点 PTQ 期间所有模型兼容性改动依赖升级、源码补丁、自定义代码、环境变量、launcher/容器变更每类写none或具体内容然后启动 serving 并运行 canary 查询如What is the capital of France?要求返回有效回答。VLM 专项检查确认视觉分支不带量化 scale。用脚本扫描model.visual.*/vision_tower.*/vision_model.*权重中是否含weight_scale/input_scale预期为 0。通用*mlp*/*experts*Recipe 会静默匹配 ViT 的 MLP → 垃圾图像 embeddingMMMU-Pro 约 0% 得分而文本看起来正常精度统计脚本还会把它们计为合法 NVFP4所以必须跑此 VLM 检查。非零即需用model_type/model_type/ptq/Recipe 或添加*visual*/*vision_tower*排除项重新量化。门禁报告格式向用户汇报时应以表格呈现可参考 checkpoint-validation.md 的规范格式CheckResultSize vs sourceoutput GB / source GB ratiox仅当比率符合 Recipe 压缩意图时 PASSSource precision源权重的 dtypebf16/fp16/fp32/fp8/int8/mxfp4/nvfp4/fp4/int4/w4a16/awq/4bit之一Layer precision countscount NVFP4 / count FP8 / count INT4 / count BF16-or-excluded / count unexpected / count declaration mismatchesMetadatano unexpected diffs或列出确切差异Checkpoint workspace/path精确路径必须被部署与评测继承PTQ compatibility requirements五类改动逐项记录或写noneServing canary目标环境、框架与启动配置、查询 → 响应仅当 serving 返回有效响应时 PASS阻塞项包括压缩 Recipe 下输出/源比率 ≥ 1.0且 source_precision 无法解释预期量化的层组覆盖为零或异常低层量化元数据与声明精度不一致提示/tokenizer/生成/架构/上下文长度/特殊 token 元数据意外变化VLM 视觉塔带量化 scale除非有意量化 ViTcanary 未返回有效响应等。各 Recipe 的预期量化模式快速对照Recipe--qformat应量化的层应排除的层nvfp4所有 linear 层lm_head、routers、norms、embeddingsnvfp4_mlp_onlyMLP 层含 MoE 专家attention、lm_head、routersnvfp4_experts_only仅 MoE 专家层稠密 MLP、attention、lm_head、routersnvfp4_omlp_onlyMLP o_proj其他 attention 层、lm_head、routersfp8所有 linear 层lm_head、norms、embeddingsint4_awq所有 linear 层lm_head、norms、embeddingsKey API Rules核心 API 规则mtq.register()注册的类必须定义_setup()并在__init__中调用在量化之前调用mto.enable_huggingface_checkpointing()examples/hf_ptq/hf_ptq.py 在模块级执行了该调用通配符*gate*匹配过宽应改用*mlp.gate*或*router*VLMhf_ptq.py通过 extract_and_prepare_language_model_from_vl() 自动提取语言模型大多数情况无需手动处理 VLMFP8 Checkpoint优先_QuantFP8Linear惰性反量化避免FineGrainedFP8Config(dequantizeTrue)浪费约 2 倍显存自定义量化器名必须以_input_quantizer或_weight_quantizer结尾否则通配符匹配不到。常见陷阱Common Pitfalls模型特定依赖trust_remote_code模型可能 import 容器中不存在的包如混合 Mamba 模型的mamba-ssm。见 Step 2.5Launcher 用EXTRA_PIP_DEPS手动则先装再跑Transformers 版本新模型可能需要更新的 transformers。检查config.json的transformers_version容器中注意PIP_CONSTRAINT阻止升级unset PIP_CONSTRAINT后pip install -U transformers仍冲突则--no-deps详见 references/slurm-setup-ptq.mdGated 数据集部分校准数据集需要 HF 认证在任务环境中设置HF_TOKEN。--dataset cnn_dailymail只作为受限环境的兜底不是首选校准集NFS root_squash Docker见 common skill 的slurm-setup.md第 5 节静默漏量化非标准命名如 Gemma4 MoE 的layers.N.experts.*被*mlp*、*block_sparse_moe*漏掉自定义 MoE 的moe_block.experts.*被*mlp*漏掉导致层被静默跳过——用 Step 5 的覆盖率脚本检查发现后给配置补模式并重跑 PTQ或手动把层加入exclude_modules。参考文档索引参考何时阅读examples/hf_ptq/README.mdStep 3支持矩阵、CLI 参数、精度指引references/checkpoint-validation.mdStep 5部署/评测前的强制验证门禁references/unsupported-models.mdStep 4C未列出模型的调查与补丁references/launcher-guide.mdStep 4BLauncher 路径references/slurm-setup-ptq.mdStep 4A/4CPTQ 专用 SLURM容器、GPU 规模、FSDP2tools/launcher/CLAUDE.mdStep 4BLauncher 细节tools/launcher/examples/Qwen/Qwen3-8B/hf_ptq.yamlStep 4B现成的 HF PTQ Launcher 配置示例modelopt/torch/quantization/config.pyStep 3量化格式定义modelopt/torch/utils/dataset_utils.pyStep 4校准数据集注册与组合展开modelopt_recipes/Step 3预构建 Recipeexamples/llm_eval/README.md量化后的精度评测MMLU、lm-eval 等赞分享人工智能大模型模型优化模型量化模型压缩【免费下载链接】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 ONNX 后训练量化PTQ实战指南从 INT8/FP8/INT4 量化到 TensorRT 部署Model Optimizer ONNX 后训练量化PTQ实战指南从 INT8/FP8/INT4 量化到 TensorRT 部署 导读 本文围绕 exam人工智能大模型模型优化模型量化模型压缩Model-Optimizer PTQ 量化交付实战从 Recipe 到经过校验的 Quantized CheckpointModel Optimizer PTQ 量化交付实战从 Recipe 到经过校验的 Quantized Checkpoint 本篇技术指南以 Model Op人工智能大模型模型优化模型量化模型压缩Model-Optimizer ResNet PTQ 配方解析残差连接量化的 FP8/INT8 后训练量化实战Model Optimizer ResNet PTQ 配方解析残差连接量化的 FP8/INT8 后训练量化实战 导读 本文聚焦 Model Optimizer人工智能大模型模型优化模型量化模型压缩创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
人工智能大模型模型优化模型量化模型压缩【免费下载链接】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 中plugins/modelopt/skills/ptq/SKILL.md的完整执行流程系统讲解如何用 Model OptimizerModelOpt对预训练 Hugging Face 模型执行后训练量化Post-Training Quantization, PTQ最终产出一个可直接部署的量化 Checkpoint.safetensorsconfig.json。读完本文你将掌握量化格式与 Recipe 的选择方法、examples/hf_ptq/hf_ptq.py三种运行路径手动 / Launcher / 未列出模型、校准数据集的选择原则以及部署前必须通过的量化后验证门禁。本文所有命令与参数均来自仓库内真实文档与源码可直接对照复现。Step 1 — 环境准备PTQ 需要一张 NVIDIA GPU 与完整的 ModelOpt 运行环境。SKILL 建议先完成环境与工作区管理确认以下信息就绪ModelOpt 源码可用建议在仓库根目录执行pip install -e .[hf] --no-build-isolation该方式与 examples/hf_ptq/slurm/multinode_fsdp2_ptq.slurm 的容器内安装方式一致能尽早暴露构建问题本地或远程执行环境远程还需集群配置运行方式SLURM / DockerGPU / 裸 GPU是否有 Launcher 可用见 tools/launcher选用哪个工作区存放模型与输出。HF 模型的推荐运行环境是 TensorRT-LLM Docker 镜像如nvcr.io/nvidia/tensorrt-llm/release:1.2.0。也可本地安装 Model Optimizer 与示例依赖pip install --no-build-isolation nvidia-modelopt[hf] pip install -r examples/hf_ptq/requirements.txtStep 2 — 模型是否受支持首先查阅 examples/hf_ptq/README.md 的Hugging Face Supported Models 支持矩阵确认目标模型是否在已验证列表中。已在列表→ 受支持直接使用hf_ptq.py对应下文 Step 4 的路径 4A/4B不在列表→ 阅读 references/unsupported-models.md判断hf_ptq.py是否仍可工作或需要自定义脚本对应路径 4C。支持矩阵节选完整表见 README涵盖了 LLAMA 3.x/4、Mixtral、Phi-3/4、Llama-Nemotron Super/Ultra、Gemma 3、QWen 2/2.5/3、DeepSeek V3/R1、GPT-OSS、T5、Whisper、Nemotron-3以及 LLaVA、Qwen-VL、Nemotron VL 等视觉语言模型VLM。不同模型可用的格式不同例如 LLAMA 4 仅支持 fp8 与 nvfp4而 DeepSeek 与 Kimi K3 只列出 nvfp4。一个值得注意的例外是Kimi K3其 routed experts 以打包的 MXFP4 张量发布因此不使用内存内hf_ptq.py流程而是走校准无关的 streaming converter见 examples/kimi/README.md。注意矩阵脚注中的关键限制NVFP4 推理要求 Blackwell GPU 与 TensorRT-LLM v1.2w4a8_awq_beta 是实验性格式精度损失可能更大VLM 默认只量化语言模型视觉编码器保持高精度除非显式传--vlm或使用视觉量化 Recipe不在支持矩阵 ≠ 不能运行ModelOpt 会自动识别标准 HF 模块linear 层、attention、含gateexperts的 MoE 块许多未列出模型可直接跑通。Step 2.5 — 检查模型特定依赖若模型需要trust_remote_code查看本地config.json是否含auto_map先检查其自定义 Python 文件是否引用了容器中没有的包grep -h ^from \|^import model_path/modeling_*.py | sort -u已知依赖模式导入语句需安装的包适用模型from mamba_ssm/from causal_conv1dmamba-ssm causal-conv1dMamba/混合模型NemotronH、Jamba安装方式取决于运行路径Launcher4B在任务environment区设置EXTRA_PIP_DEPScommon/hf/ptq.sh 会自动安装手动4A运行hf_ptq.py前先unset PIP_CONSTRAINT pip install deps。此外注意transformers 版本新模型可能需要比容器更新的 transformers。查看config.json的transformers_version字段在容器中PIP_CONSTRAINT可能阻止升级需先unset PIP_CONSTRAINT详见 references/slurm-setup-ptq.md。Step 3 — 选择量化格式先查模型特定 Recipels modelopt_recipes/models/ 2/dev/null ls modelopt_recipes/model_type/model_type/ptq/ 2/dev/null # 按架构model_type 取自本地 config.jsonHub IDAutoConfig.from_pretrained若存在模型特定 Recipe优先使用--recipe path——但必须检查其 include/exclude 模式不要想当然例如对 VLM确认视觉塔确实被排除。无模型特定 Recipe 时按 GPU 选格式BlackwellB100/B200/GB200nvfp4系列HopperH100/H200或更老fp8或int4_awq。NVFP4 可以在 Hopper 上校准但推理必须用 Blackwell。使用--qformat name如--qformat nvfp4是最简单的选格式方式。格式定义位于 modelopt/torch/quantization/config.py通用 PTQ Recipe 位于 modelopt_recipes/general/ptq/如nvfp4_default-kv_fp8_cast.yaml、fp8_default-kv_fp8_cast.yaml、nvfp4_mlp_only-kv_fp8_cast.yaml、nvfp4_experts_only-kv_fp8_cast.yaml等两者对应同一批格式--qformat是更简单的用法。核心量化格式一览ModelOpt 支持以下主要格式对应config.py中的常量与--qformat取值qformat说明主要适用 GPUfp88-bit 浮点权重激活量化校准快、精度稳健Hopper / AdaCC≥8.9nvfp4Blackwell 4-bit 浮点权重 4bit 激活压缩率高Blackwell推理nvfp4_mlp_only仅量化 MLP含 MoE层attention 保持高精度Blackwell推理nvfp4_experts_only仅量化专家层*mlp.experts*与*block_sparse_moe*适合 MoEBlackwell推理nvfp4_omlp_onlyMLP-only 基础上额外量化o_projBlackwell推理int8_smoothquantINT8 权重激活SmoothQuant 算法Hopper / 更老int8_weight_onlyINT8 仅权重通用int4_awqINT4 仅权重 AWQ低 batch 推理延迟最优Hopper / 更老w4a8_awq_betaINT4 权重 FP8 激活实验性通用从源码看这些常量如 NVFP4_DEFAULT_CFG、NVFP4_MLP_ONLY_CFG、NVFP4_EXPERTS_ONLY_CFG、NVFP4_OMLP_ONLY_CFG、FP8_DEFAULT_CFG、INT4_AWQ_CFG、W4A8_AWQ_BETA_CFG都由_load_quantize_config_dict(configs/ptq/presets/model/name)从 YAML 预设加载即--qformat与 Recipe 本质同源。对于NVFP4 高精度场景仓库 README 明确建议优先使用nvfp4_mlp_only、nvfp4_experts_only或nvfp4_omlp_only将敏感的自注意力 QKV 投影保持未量化同时仍获得显著压缩。运行前必须做的 sanity-check在启动校准之前检查所选 qformat/Recipe 的 include/exclude 模式并总结哪些层组会被量化、大约匹配到多少模块/层attention 投影、MLP 投影、专家等。如果匹配数为 0 或远小于预期立即停下修正 Recipe 或询问用户不要盲目启动校准——量化配置模式可能因模型命名不标准而静默漏掉层这在部署阶段才会暴露为框架把未量化权重当作量化权重加载的失败。VLM 特殊注意通用的*mlp*/*experts*Recipe 也会匹配视觉塔model.visual.*量化 ViT 会静默破坏图像 benchmark。请使用model_type/model_type/ptq/下的 Recipe或添加*visual*/*vision_tower*排除项并在 Step 5 中验证见 references/checkpoint-validation.md。另外如果源 Checkpoint 已被量化、而请求的 Recipe/配置会缩减量化覆盖范围必须与用户确认意图。例如输入是 FP8 CheckpointRecipe 排除某些层使其回退为 BF16则应明确指出受影响的层组并确认该 FP8→BF16 回退是否符合预期。Step 4 — 运行 PTQ目标磁盘上有一个量化 Checkpoint.safetensorsconfig.json。已支持模型4A/4B直接完整校准--calib_size 512未支持模型4C先跑冒烟测试--calib_size 4成功后做完整校准。推荐校准数据集纯文本 LLM PTQ优先使用代表性的nemotron-post-training-v3混合集。modelopt/torch/utils/dataset_utils.py 中DATASET_COMBOS将其展开为七个已注册的 Nemotron SFT 领域如 nemotron-sft-instruction-following-chat-v2、nemotron-science-v1、nemotron-competitive-programming-v1 等。需要时配置 Hugging Face 凭据python examples/hf_ptq/hf_ptq.py ... \ --dataset nemotron-post-training-v3VLM PTQ使用图文校准--calib_with_images。该路径使用nemotron_vlm_dataset_v2默认子集为sparsetables、plotqa_cot、wiki_enexamples/hf_ptq/hf_ptq.py 与 modelopt/torch/utils/vlm_dataset_utils.py 是权威依据python examples/hf_ptq/hf_ptq.py ... \ --calib_with_images注意--dataset只选文本校准数据不能替代多模态样本。仅在代表性数据不可用无 gated-data 权限、只有本地公共缓存时才用--dataset cnn_dailymail作为兜底。三种运行路径在 README 表中 ─→ 是 ──→ SLURM本地或远程 ──→ LAUNCHER4B │ 本地 Docker GPU ───────→ LAUNCHER4B │ 远程 Docker无 SLURM ─→ MANUAL4A │ 裸 GPU本地或远程 ───→ MANUAL4A │ └→ 不在表中 ──→ UNLISTED MODEL4C4A — 直接执行已支持模型手动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运行--help查看全部选项。远程环境使用 common skill 的remote_exec.sh的remote_run。4B — Launcher已支持模型SLURM 或本地 Docker编写 YAML 配置使用 tools/launcher/common/hf/ptq.sh 包装hf_ptq.py。完整的现成示例见 tools/launcher/examples/Qwen/Qwen3-8B/hf_ptq.yaml其核心结构为job_name: hf_ptq_nvfp4 pipeline: global_vars: hf_local: /hf-local/ hf_model: Qwen/Qwen3-8B task_0: script: common/hf/ptq.sh args: - --repo global_vars.hf_model - --local-dir global_vars.hf_localglobal_vars.hf_model - -- - --quant nvfp4 - --tasks quant slurm_config: _factory_: slurm_factory nodes: 1 ntasks_per_node: 1 gpus_per_node: 1 time: 04:00:00 container: nvcr.io/nvidia/tensorrt-llm/release:1.3.0rc20运行在 tools/launcher 目录下# SLURM远程或本地 SLURM_HOSThost SLURM_ACCOUNTacct uv run launch.py --yaml config.yaml userssh_user identityssh_key --yes # 本地 Docker uv run launch.py --yaml config.yaml hf_localhf_cache --yesLauncher 会阻塞并实时 tail 日志直到任务完成。若 Launcher 失败缺依赖、配置错误回退到 4A 手动执行。Launcher 相关要点见 references/launcher-guide.mdgpus_per_node必须匹配集群节点 GPU 数 / QOS 最低要求否则sbatch会以QOSMinGRES或Requested node configuration is not available拒绝任务EXTRA_PIP_DEPS中避免 shell 元字符如、否则写入未加引号的export后会被 shell 重定向吞掉用精确固定版本EXPORT_PATH控制容器内路径默认/scratchspace/exported_modelLauncher 自动把/scratchspace挂载到宿主机目录本地 Docker 下用find tools/launcher/local_experiments -name config.json -path */exported_model/*找结果远程 SLURM 下结果在远程机器上通常在~/experiments/...。4C — 未列出模型按 references/unsupported-models.md 走完整调查流程下载模型 → 判断架构是否已知 → 检查是否已 FP8 量化 → 确定需要哪些自定义补丁 → 对照 ModelOpt 配置模式核对权重命名 → 运行并迭代。建议像 4A 一样手动运行以便监控和调试。调查流程的核心结论大多数模型是标准nn.Linear结构无需任何自定义代码即可被自动量化先检查 modelopt/torch/quantization/plugins/huggingface.py 是否已注册该非标准模块的补丁Llama4TextExperts、FP8Linear、FalconLinear、Conv1D、Qwen3_5MoeExperts等需要自定义补丁的典型场景融合/批量专家权重3D 张量而非独立nn.Linear、直接用nn.Parameter的自定义权重、需要排除视觉编码器的 VLM、非标准参数名的 FP8 Checkpoint自定义QuantModule的硬性规则_setup()方法必须存在并在__init__中调用量化器名必须以_input_quantizer或_weight_quantizer结尾若需要mtq.register()或QuantModuleRegistry.register注册新模块完成后总是运行mtq.print_quant_summary(model)验证FP8 Checkpoint优先_QuantFP8Linear惰性反量化不要用FineGrainedFP8Config(dequantizeTrue)会把整个模型展开为 BF16浪费约 2 倍显存。SLURM 手动执行时参考 references/slurm-setup-ptq.md容器镜像处理.sqsh复用或 enroot 导入、GPU 数量估算hf_ptq.py用device_mapauto自动填充 GPU、先跑冒烟测试--calib_size 4、--time00:30:00再提交完整校准。hf_ptq.py 关键命令行参数来自源码 parse_args参数默认值说明--pyt_ckpt_path/--model必填模型路径或 Hugging Face 模型名--qformatfp8单格式 PTQ 的量化格式--recipe存在时被忽略--recipeNonePTQ / AutoQuantize Recipe YAML 文件或名称无后缀如general/ptq/nvfp4_default-kv_fp8_cast--calib_size1024校准样本数支持逗号分隔列表每个数据集一个值--calib_seq512校准最大序列长度--batch_size0校准 batch size0 表示按显存自动探测最大值--export_pathexported_model量化 Checkpoint 输出目录--dataset默认cnn_nemotron_v2_mix数据集名或逗号分隔列表可用集见get_supported_datasets()--kv_cache_qformatfp8_castKV cache 量化格式none关闭--calib_with_imagesFalse图文校准VLM使用 nemotron_vlm_dataset_v2--trust_remote_codeFalse为使用自定义建模代码的模型开启--use_fsdp2False多节点 FSDP2 分布式校准需 torchrun 启动--low_memory_modeFalse低显存模式加载时即压缩权重仅 FP8/NVFP4 max 校准--awq_block_size0AWQ 块大小--moe_calib_experts_ratioNoneMoE 模型校准的专家比例取值(0.0, 1.0]--cast_mxfp4_to_nvfp4FalseGPT-OSS 等 MXFP4 Checkpoint 的封闭式 NVFP4 转换--auto_quantize_checkpointNoneAutoQuantize 搜索状态保存/恢复--skip_generateFalse跳过量化前后model.generate()预览--vllm_fakequant_exportFalse导出 vLLM fake-quant Checkpoint--mlflow uri—记录 PTQ 运行到 MLflow 服务器KV cache 量化格式--kv_cache_qformat详见 examples/hf_ptq/README.md 的 KV Cache Quantization 小节fp8_cast默认无校准的常量 amax、fp8、fp8_affine、nvfp4_cast、nvfp4、nvfp4_affine、nvfp4_rotate、none。以_cast结尾的格式直接把 amax 设为格式满量程速度快其他格式使用数据驱动校准精度可能更好。Recipe 体系补充除--qformat外--recipe是推荐的前进方向hf_ptq.py中--recipe优先于--qformat通用 PTQ Recipemodelopt_recipes/general/ptq/如nvfp4_default-kv_fp8_cast按架构调优的 Recipemodelopt_recipes/model_type/model_type/ptq/模型特定 Recipemodelopt_recipes/models/如 nvidia、Qwen、deepseek-ai 目录下。Recipe 对 KV cache 的处理PTQ Recipe 把 KV cache 编入自身配置并忽略--kv_cache_qformatAutoQuantize Recipe 回退到--kv_cache_qformat除非显式设置kv_cache字段。python examples/hf_ptq/hf_ptq.py \ --pyt_ckpt_path huggingface_model_card \ --recipe general/ptq/nvfp4_default-kv_fp8_cast \ --export_path quantized_ckpt_path监控任务提交后按monitor skill注册任务并设置监控。Step 5 — 验证输出基础检查ls -lh output_path/ # 预期config.json、tokenizer 文件、model-*.safetensors向用户报告路径与大小。量化后验证门禁部署前强制关卡这是任何部署或评测提交之前的强制门禁。在确认为可部署/可评测状态之前不得提交评测、启动生产 serving 或交接 Checkpoint含 serving canary 通过前。按 references/checkpoint-validation.md 对即将部署/评测的确切 Checkpoint 路径执行四组验证大小与每权重位数量化 Checkpoint 磁盘大小应小于基线/源 Checkpoint且估算每权重位数更低。用脚本对比 safetensors 大小输出/源 ≥ 1.0x对压缩 Recipe 是阻塞项除非source_precision说明源本就等于或低于目标位数如 mxfp4 源配 nvfp4 Recipe 无法再缩小量化权重覆盖率实际量化的权重与请求的 qformat/Recipe/配置一致。用层精度统计脚本按实际/声明精度分组计数NVFP4、FP8、INT4、BF16/未量化排除、意外未量化、声明不一致。量化配置模式可能因非标准命名静默漏掉层——只在部署时服务框架试图以量化格式加载未量化权重时才暴露元数据一致性不应改变的元数据与基线一致生成设置、tokenizer 文件、chat template、模型架构字段、max positions/上下文长度、特殊 token。量化只应改变权重与量化元数据不应静默改变提示或生成行为下游交接与 serving 就绪记录确切的 Checkpoint 工作区与路径下游 skill 必须继承盘点 PTQ 期间所有模型兼容性改动依赖升级、源码补丁、自定义代码、环境变量、launcher/容器变更每类写none或具体内容然后启动 serving 并运行 canary 查询如What is the capital of France?要求返回有效回答。VLM 专项检查确认视觉分支不带量化 scale。用脚本扫描model.visual.*/vision_tower.*/vision_model.*权重中是否含weight_scale/input_scale预期为 0。通用*mlp*/*experts*Recipe 会静默匹配 ViT 的 MLP → 垃圾图像 embeddingMMMU-Pro 约 0% 得分而文本看起来正常精度统计脚本还会把它们计为合法 NVFP4所以必须跑此 VLM 检查。非零即需用model_type/model_type/ptq/Recipe 或添加*visual*/*vision_tower*排除项重新量化。门禁报告格式向用户汇报时应以表格呈现可参考 checkpoint-validation.md 的规范格式CheckResultSize vs sourceoutput GB / source GB ratiox仅当比率符合 Recipe 压缩意图时 PASSSource precision源权重的 dtypebf16/fp16/fp32/fp8/int8/mxfp4/nvfp4/fp4/int4/w4a16/awq/4bit之一Layer precision countscount NVFP4 / count FP8 / count INT4 / count BF16-or-excluded / count unexpected / count declaration mismatchesMetadatano unexpected diffs或列出确切差异Checkpoint workspace/path精确路径必须被部署与评测继承PTQ compatibility requirements五类改动逐项记录或写noneServing canary目标环境、框架与启动配置、查询 → 响应仅当 serving 返回有效响应时 PASS阻塞项包括压缩 Recipe 下输出/源比率 ≥ 1.0且 source_precision 无法解释预期量化的层组覆盖为零或异常低层量化元数据与声明精度不一致提示/tokenizer/生成/架构/上下文长度/特殊 token 元数据意外变化VLM 视觉塔带量化 scale除非有意量化 ViTcanary 未返回有效响应等。各 Recipe 的预期量化模式快速对照Recipe--qformat应量化的层应排除的层nvfp4所有 linear 层lm_head、routers、norms、embeddingsnvfp4_mlp_onlyMLP 层含 MoE 专家attention、lm_head、routersnvfp4_experts_only仅 MoE 专家层稠密 MLP、attention、lm_head、routersnvfp4_omlp_onlyMLP o_proj其他 attention 层、lm_head、routersfp8所有 linear 层lm_head、norms、embeddingsint4_awq所有 linear 层lm_head、norms、embeddingsKey API Rules核心 API 规则mtq.register()注册的类必须定义_setup()并在__init__中调用在量化之前调用mto.enable_huggingface_checkpointing()examples/hf_ptq/hf_ptq.py 在模块级执行了该调用通配符*gate*匹配过宽应改用*mlp.gate*或*router*VLMhf_ptq.py通过 extract_and_prepare_language_model_from_vl() 自动提取语言模型大多数情况无需手动处理 VLMFP8 Checkpoint优先_QuantFP8Linear惰性反量化避免FineGrainedFP8Config(dequantizeTrue)浪费约 2 倍显存自定义量化器名必须以_input_quantizer或_weight_quantizer结尾否则通配符匹配不到。常见陷阱Common Pitfalls模型特定依赖trust_remote_code模型可能 import 容器中不存在的包如混合 Mamba 模型的mamba-ssm。见 Step 2.5Launcher 用EXTRA_PIP_DEPS手动则先装再跑Transformers 版本新模型可能需要更新的 transformers。检查config.json的transformers_version容器中注意PIP_CONSTRAINT阻止升级unset PIP_CONSTRAINT后pip install -U transformers仍冲突则--no-deps详见 references/slurm-setup-ptq.mdGated 数据集部分校准数据集需要 HF 认证在任务环境中设置HF_TOKEN。--dataset cnn_dailymail只作为受限环境的兜底不是首选校准集NFS root_squash Docker见 common skill 的slurm-setup.md第 5 节静默漏量化非标准命名如 Gemma4 MoE 的layers.N.experts.*被*mlp*、*block_sparse_moe*漏掉自定义 MoE 的moe_block.experts.*被*mlp*漏掉导致层被静默跳过——用 Step 5 的覆盖率脚本检查发现后给配置补模式并重跑 PTQ或手动把层加入exclude_modules。参考文档索引参考何时阅读examples/hf_ptq/README.mdStep 3支持矩阵、CLI 参数、精度指引references/checkpoint-validation.mdStep 5部署/评测前的强制验证门禁references/unsupported-models.mdStep 4C未列出模型的调查与补丁references/launcher-guide.mdStep 4BLauncher 路径references/slurm-setup-ptq.mdStep 4A/4CPTQ 专用 SLURM容器、GPU 规模、FSDP2tools/launcher/CLAUDE.mdStep 4BLauncher 细节tools/launcher/examples/Qwen/Qwen3-8B/hf_ptq.yamlStep 4B现成的 HF PTQ Launcher 配置示例modelopt/torch/quantization/config.pyStep 3量化格式定义modelopt/torch/utils/dataset_utils.pyStep 4校准数据集注册与组合展开modelopt_recipes/Step 3预构建 Recipeexamples/llm_eval/README.md量化后的精度评测MMLU、lm-eval 等赞分享人工智能大模型模型优化模型量化模型压缩【免费下载链接】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 ONNX 后训练量化PTQ实战指南从 INT8/FP8/INT4 量化到 TensorRT 部署Model Optimizer ONNX 后训练量化PTQ实战指南从 INT8/FP8/INT4 量化到 TensorRT 部署 导读 本文围绕 exam人工智能大模型模型优化模型量化模型压缩Model-Optimizer PTQ 量化交付实战从 Recipe 到经过校验的 Quantized CheckpointModel Optimizer PTQ 量化交付实战从 Recipe 到经过校验的 Quantized Checkpoint 本篇技术指南以 Model Op人工智能大模型模型优化模型量化模型压缩Model-Optimizer ResNet PTQ 配方解析残差连接量化的 FP8/INT8 后训练量化实战Model Optimizer ResNet PTQ 配方解析残差连接量化的 FP8/INT8 后训练量化实战 导读 本文聚焦 Model Optimizer人工智能大模型模型优化模型量化模型压缩创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
