人工智能大模型模型优化模型量化模型压缩【免费下载链接】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 仓库中的 PTQPost-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.mdPTQ 全流程环境、支持性、格式选择、运行、校验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/sbatchSLURM、docker infoDockerGPU、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、含gateexperts的 MoE 块等标准模块自动检测许多未列出模型可以直接开箱工作。模型特定依赖检查若模型启用了trust_remote_codeconfig.json中有auto_map需检查其自定义 Python 文件是否引用了容器内没有的包grep -h ^from \|^import model_path/modeling_*.py | sort -u已知的依赖模式出现from mamba_ssm/from causal_conv1d时需要安装mamba-ssm causal-conv1dMamba/混合架构模型如 NemotronH、Jamba。安装方式分两条路Launcher 路径在任务的environment区设置EXTRA_PIP_DEPSptq.sh会自动安装。注意EXTRA_PIP_DEPS会被写入未加引号的export因此禁止/等 shell 元字符必须用精确的固定版本例如EXTRA_PIP_DEPS: transformers5.5.0见 launcher-guide.md。手动路径unset PIP_CONSTRAINT pip install deps之后再跑hf_ptq.py。第二步选择量化格式与 Recipe按 GPU 选格式没有模型专属 Recipe 时根据 GPU 型号决定量化格式详见 hf_ptq.py 支持矩阵BlackwellB100/B200/GB200优先nvfp4系列HopperH100/H200或更老fp8或int4_awq。格式定义集中维护在 modelopt/torch/quantization/config.pyFP8_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 Recipemodelopt_recipes/general/ptq/下的 YAML与这些格式一一对应--qformat是它们的简化用法。重要前提NVFP4 可以在 Hopper 上完成校准但推理必须使用 Blackwell GPU。Recipe 优先原则与覆盖率预检选择格式的第一优先是查找模型专属 Recipels 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——三条路径目标产物是磁盘上的检查点.safetensorsconfig.json含 tokenizer 文件。选择路径的决策流程如下在 README 支持表中 ─→ YES ─→ SLURM本地或远端? ─→ LAUNCHER4B │ 本地 Docker GPU? ─→ LAUNCHER4B │ 远端 Docker无 SLURM? ─→ MANUAL4A │ 裸 GPU本地或远端? ─→ MANUAL4A │ └→ 未列出 ──→ 未列出模型路径4C4A — 直接执行受支持模型、手动运行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 outputhf_ptq.py --help可查看全部参数。远端机器上通过 common 技能的remote_exec.sh中的remote_run执行。4B — LauncherSLURM 或本地 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_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 --yes关键细节见 launcher-guide.mdgpus_per_node必须匹配集群节点 GPU 数/QOS 下限否则sbatch会被QOSMinGRES拒绝EXPORT_PATH控制容器内路径默认/scratchspace/exported_modelLauncher 自动将/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(dequantizeTrue)那会先把整个模型展开成 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-v3VLM加--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 表示按显存自动探测。任务监控提交长任务后按 monitor/SKILL.md 注册并监控作业在.claude/agents/session_id/active_jobs.json中登记作业条目启动常驻 watcher 轮询直到作业进入终态。监控必须按作业类型匹配各自的状态词汇表——SLURM 用sacctCOMPLETED|FAILED|CANCELLED|TIMEOUT|NODE_FAIL|OUT_OF_MEMORY|PREEMPTED|BOOT_FAIL|DEADLINE为终态Launcher 作业 tail 输出文件NEL 用nel status。只报告状态变化不做无意义的心跳汇报。第四步输出校验——强制门禁运行完成后先确认产物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 服务。门禁报告格式移交前必须按如下表格汇报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或列出确切 diffsCheckpoint workspace/path确切的 workspace 与检查点路径PTQ compatibility requirementsdependency upgrades: ...; source patches: ...; custom code: ...; environment variables: ...; launcher/container changes: ...每类没有就写noneServing 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、embeddingnvfp4_mlp_onlyMLP 层含 MoE expertsattention、lm_head、routernvfp4_experts_only仅 MoE expert 层稠密 MLP、attention、lm_head、routernvfp4_omlp_onlyMLP o_proj层其余 attention 层、lm_head、routerfp8所有线性层lm_head、norm、embeddingint4_awq所有线性层lm_head、norm、embedding常见的 pattern 漏配模型模块路径被*mlp*等模式漏掉修复Gemma4 MoElayers.N.experts.**mlp*、*block_sparse_moe*添加*.experts.*自定义 MoElayers.N.moe_block.experts.**mlp*添加匹配模式VLM projectormulti_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.yamlquantizer_name: *enable: false先关闭全部 quantizer 再选择性开启w4a4_nvfp4_nvfp4.yaml对所有*weight_quantizer/*input_quantizer启用动态 NVFP4kv_fp8_cast.yaml对*[kv]_bmm_quantizer启用 FP8 E4M3 KV cache 量化并固定use_constant_amax: truecast 模式无数据驱动校准速度快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 启用 NVFP4attention 保持 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.pyFP8 检查点优先用_QuantFP8Linearlazy dequant避免FineGrainedFP8Config(dequantizeTrue)约 2 倍显存开销自定义 quantizer 名必须以_input_quantizer或_weight_quantizer结尾wildcard 才能匹配。常见坑速查模型特定依赖trust_remote_code模型可能引入容器外依赖如混合 Mamba 模型的mamba-ssm用EXTRA_PIP_DEPS或手动先装transformers 版本新架构可能需要更新的 transformers查看config.json的transformers_versionNGC 容器里的PIP_CONSTRAINT会阻塞升级需unset PIP_CONSTRAINT或--no-deps绕过见 slurm-setup-ptq.md门禁数据集部分校准数据集需要 HF 认证在作业环境设置HF_TOKENcnn_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 以已验证检查点为单位交付量化能力的工程化实践。赞分享人工智能大模型模型优化模型量化模型压缩【免费下载链接】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实战指南从校准数据准备到 TensorRT 引擎部署Linux BetaModel Optimizer ONNX 量化PTQ实战指南从校准数据准备到 TensorRT 引擎部署Linux Beta Model Optimi人工智能大模型模型优化模型量化模型压缩Model-Optimizer ONNX 后训练量化PTQ实战指南从 INT8/FP8/INT4 量化到 TensorRT 部署Model Optimizer ONNX 后训练量化PTQ实战指南从 INT8/FP8/INT4 量化到 TensorRT 部署 导读 本文围绕 exam人工智能大模型模型优化模型量化模型压缩Model-Optimizer PyTorch 量化实战指南PTQ、QAT 与 auto_quantize 完整解析Model Optimizer PyTorch 量化实战指南PTQ、QAT 与 auto_quantize 完整解析 本文是 Model Optimizer人工智能大模型模型优化模型量化模型压缩上一篇FluidVoice全局快捷键实现剖析HotkeyShortcut与激活模式切换完整指南下一篇F3D如何在3秒内打开任何3D文件这款极速查看器的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
