Model-Optimizer 模型量化 Agent 实战指南：单候选 PTQ 执行、强制验证门禁与标准化交接-北京尧图网络

人工智能大模型模型优化模型量化模型压缩【免费下载链接】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 仓库中modelopt-model-quantizer这一 AI Agent 定义展开说明它如何在一个已选定的 Day 0 量化方案recipe约束下端到端地产出一个通过验证的 PTQ 量化检查点checkpoint。你将掌握该 Agent 的职责边界与协作分工、其必须加载的三份指令PTQ 执行、任务监控、工作区管理、校准前必须完成的 recipe 覆盖率核查以及作为强制门禁的四组后量化验证与九个固定标题的交接报告格式。文中所有流程均可在本仓库对应的技能文档与源码中直接查证与复用。一、Agent 定位谁负责执行单个 PTQ 候选方案modelopt-model-quantizer是 Model-Optimizer 仓库中一组协作式 Agent 的成员其定义文件位于 plugins/modelopt/agents/modelopt-model-quantizer.md。它的触发场景非常明确当父级流程选定了一个需要验证的 PTQ 检查点时例如用户要求用某个 recipe 量化模型或搜索循环选出了下一个候选方案由本 Agent 负责产出该检查点。与之配套的 Agent 定义还包括modelopt-model-quantize-recipe-searcher.md负责量化策略与下一个候选方案的决策属于搜索/选型环节modelopt-model-deployer.md负责部署modelopt-model-evaluator.md负责评估modelopt-model-performance-benchmarker.md负责性能基准测试modelopt-model-downloader.md负责模型下载。1.1 严格职责边界该 Agent 的职责定义只有一句但边界极严You are responsible for one PTQ candidate selected by the parent. Do not search a recipe portfolio, deploy, evaluate, benchmark, or publish.即✅ 只负责一个由父级选定的 PTQ 候选方案❌ 不搜索 recipe 组合那是 recipe-searcher 的事❌ 不部署、不评估、不做基准测试、不发布。这种单一职责设计使得选型与执行两个环节解耦搜索循环可以并行评估多个候选而每个候选由独立的 quantizer 实例负责互不干扰。1.2 行动前必须加载的三份指令Agent 在采取任何行动前必须先加载以下指令原文对应路径为本仓库内的技能文档指令仓库实际位置作用ptq/SKILL.mdplugins/modelopt/skills/ptq/SKILL.mdPTQ 完整执行流程环境、模型支持、格式选择、校准运行、验证monitor/SKILL.md提交长任务后plugins/modelopt/skills/monitor/SKILL.md长任务如 SLURM 上的校准提交后的注册与状态监控common/workspace-management.mdplugins/modelopt/skills/common/workspace-management.md会话级工作区管理保证并发 Agent 互不踩踏二、执行前置工作区、环境与任务监控2.1 会话级工作区约定workspace-management.md 规定了跨 PTQ → Deploy → Eval 全流水线复用的工作区规范每个 Agent 以其会话 ID 为命名空间Claude Code 使用$CLAUDE_CODE_SESSION_IDCodex 使用$CODEX_THREAD_ID否则自建稳定 ID每个模型/变体一个工作区目录目录名要有语义而非时间戳例如workspaces/session_id/qwen3-0.6b-nvfp4/而不是ptq-20260318-143022/输出、日志、脚本分目录存放output/量化检查点、logs/任务日志、scripts/自定义 PTQ 脚本workspaces/在 gitignore 中属于临时区scratch不入库密钥.env也应放在这里而非技能树下远程执行时本地与远端各建同名工作区模型下载放在远端以避免传输大文件并用remote_sync_to同步 Model-Optimizer 源码与自定义脚本。2.2 任务监控PTQ 校准属于长任务。提交后 Agent 需按 monitor/SKILL.md 执行在.claude/agents/session_id/active_jobs.json注册任务记录type、id、host、user、submitted、description、owner启动一个持续的监视器轮询会话注册表直至所有任务进入终态按任务类型使用各自的状态词汇表NEL 任务用nel status终态 SUCCESS/FAILED/KILLED/ERROR/NOT FOUNDLauncher 任务用后台输出文件追踪关键事件裸 SLURM 任务用sacct判断终态COMPLETED/FAILED/CANCELLED/TIMEOUT/NODE_FAIL/OUT_OF_MEMORY/PREEMPTED/BOOT_FAIL/DEADLINE。注意该文档特别强调不同检查方法的状态词不同混用会导致终态转换永远不触发例如用 SLURM 的COMPLETED正则去匹配nel status的输出会静默失效。三、PTQ 执行核心流程ptq/SKILL.mdplugins/modelopt/skills/ptq/SKILL.md 是 quantizer Agent 的主执行手册其流程分为五个步骤。3.1 Step 1 — 环境准备确认 Model-Optimizer 源码可用、执行环境类型SLURM / DockerGPU / 裸 GPU、Launcher 是否可用以及使用哪个工作区。对应的环境与工作区文档位于 plugins/modelopt/skills/common/。3.2 Step 2 — 模型支持检查对照 examples/hf_ptq/README.md 中的支持矩阵判断目标模型已列出→ 走标准路径使用examples/hf_ptq/hf_ptq.py下述 4A/4B未列出→ 阅读 references/unsupported-models.md判断hf_ptq.py是否仍可工作或需要自定义脚本下述 4C。支持矩阵节选来源examples/hf_ptq/README.mdLLAMA 3.x 支持 fp8/int4_awq/nvfp4LLAMA 4、Mixtral、QWen3/3.5-MOE、DeepSeek V3/R1 等支持 nvfp4T5、Phi-3/4 支持 int8_smoothquantVLMLlava、Qwen-VL、Nemotron VL 等默认只量化语言模型、视觉编码器保持高精度。3.3 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_conv1d时需安装mamba-ssm causal-conv1dMamba/混合模型如 NemotronH、Jamba。使用 Launcher 时通过任务 environment 的EXTRA_PIP_DEPS注入ptq.sh会自动安装手动执行时先unset PIP_CONSTRAINT pip install deps再运行。3.4 Step 3 — 选择量化格式与 recipe 覆盖率核查这是 quantizer 区别于一般脚本执行的关键环节。选择顺序优先查找模型特定 recipels modelopt_recipes/models/ 2/dev/null ls modelopt_recipes/model_type/model_type/ptq/ 2/dev/null若存在优先--recipe path但必须实际检查其 include/exclude 模式对 VLM 要确认视觉塔确实被排除无模型特定 recipe 时按 GPU 选格式BlackwellB100/B200/GB200→nvfp4系列--qformat nvfp4HopperH100/H200及更早 →fp8或int4_awq。格式定义位于 modelopt/torch/quantization/config.py通用 PTQ recipe 位于 modelopt_recipes/general/ptq/--qformat是使用它们的更简方式。校准前覆盖率核查mandatory将所选 qformat/recipe 的 include/exclude 模式与模型结构对照总结哪些层组会被量化、大约匹配多少模块attention 投影、MLP 投影、experts 等。若匹配数为 0 或远小于预期必须停下来修正 recipe 或询问用户不得直接启动校准。VLM 的陷阱泛化的*mlp*/*experts*模式会同时匹配视觉塔model.visual.*量化 ViT 会静默破坏图像基准测试文本表现正常。应使用model_type/model_type/ptq/的 recipe 或显式加入*visual*/*vision_tower*排除并在 Step 5 验证。另一条重要约束如果源检查点本身已量化如 FP8而 recipe 又排除了某些层使其回退到 BF16需先与用户确认这种 FP8→BF16 回退是否有意。此外NVFP4 可在 Hopper 上校准但推理必须 Blackwell。3.5 Step 4 — 运行 PTQ目标在磁盘上得到检查点.safetensorsconfig.json。校准数据集来自examples/hf_ptq/README.md与 SKILL.md纯文本 LLM优先使用代表性混合数据集nemotron-post-training-v3由 modelopt/torch/utils/dataset_utils.py 展开为七个已注册的 Nemotron SFT 域python examples/hf_ptq/hf_ptq.py ... --dataset nemotron-post-training-v3VLM加--calib_with_images走nemotron_vlm_dataset_v2默认子集sparsetables、plotqa_cot、wiki_en真源在examples/hf_ptq/hf_ptq.py与modelopt/torch/utils/vlm_dataset_utils.py--dataset cnn_dailymail仅在受限环境无 gated 数据访问、仅本地公共缓存下作为 fallback。三条执行路径按决策树选择In README table? ─→ YES ─→ SLURM (local or remote)? ─→ LAUNCHER (4B) │ Local Docker GPU? ────────→ LAUNCHER (4B) │ Remote Docker (no SLURM)? ──→ MANUAL (4A) │ Bare GPU (local or remote)? → MANUAL (4A) │ └→ NOT LISTED ──→ UNLISTED MODEL (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--help可查看全部参数。4B — Launcher 路径SLURM 或本地 Dockercd tools/launcher # SLURM (remote or local): SLURM_HOSThost SLURM_ACCOUNTacct uv run launch.py --yaml config.yaml userssh_user identityssh_key --yes # Local Docker: uv run launch.py --yaml config.yaml hf_localhf_cache --yesLauncher 会阻塞并 tail 日志直到任务结束若 Launcher 失败则回退到 4A。完整模板见 references/launcher-guide.md。4C — 未列出模型按 references/unsupported-models.md 排查必要时对 ModelOpt 打最小补丁手动运行hf_ptq.py便于监控调试。先做冒烟测试--calib_size 4成功后再全量校准--calib_size 512。监控任务提交后按 monitor skill 注册并监控见本文 2.2。3.6 Key API Rules 与常见陷阱执行时需遵守的 API 规则来源ptq/SKILL.mdmtq.register()注册的类必须定义_setup()并在__init__中调用量化前必须先调用mto.enable_huggingface_checkpointing()通配符*gate*匹配过宽应使用*mlp.gate*或*router*VLM 场景下hf_ptq.py通过extract_and_prepare_language_model_from_vl()自动抽取语言模型多数情况无需手工处理 VLMFP8 检查点优先用_QuantFP8Linear惰性反量化避免FineGrainedFP8Config(dequantizeTrue)约 2 倍的内存浪费自定义 quantizer 名称必须以_input_quantizer或_weight_quantizer结尾。常见陷阱包括trust_remote_code模型的容器外依赖如mamba-ssm新模型需要比容器内更新的 transformers检查config.json的transformers_version注意容器中PIP_CONSTRAINT会阻止升级gated 校准集需要HF_TOKENNFS root_squash Docker 组合问题。四、强制验证门禁四组后量化检查这是 quantizer 最核心的职责之一。Agent 定义明确要求Treat the PTQ checkpoint-validation gate as mandatory——未通过输出、覆盖率、元数据或服务就绪性验证的检查点不得交接。完整规范见 plugins/modelopt/skills/ptq/references/checkpoint-validation.md该文档强调这是门禁而非建议在四组检查全部通过且验证报告被记录之前不得提交评估、不得启动生产级服务、不得将检查点标记为就绪。四组验证针对将要部署/评估的确切检查点路径执行大小与每权重位数量化检查点磁盘占用应小于基线/源检查点估算的每权重位数更低记录源大小、输出大小及输出/源比率。量化权重覆盖率实际被量化的权重必须与请求的 qformat/recipe/config 目标一致按实际/声明精度分组记录层精度计数NVFP4、FP8、INT4、BF16/未量化排除、意外未量化、声明不匹配。非标准命名可能导致配置模式静默漏层最终在部署框架按量化权重加载 BF16 权重时才暴露为故障。元数据一致性生成设置、tokenizer 文件、聊天模板、模型架构字段、max positions/上下文长度、特殊 token 必须与基线一致量化只应改变权重与量化元数据不得静默改变提示词或生成行为。每个 diff 都要记录并分类为预期或阻塞。下游就绪性与服务 canary记录确切的检查点工作区与路径供 deploy/eval 技能继承盘点 PTQ 期间所有模型兼容性改动依赖升级、源码补丁、自定义代码、环境变量、Launcher/容器变更无则写none然后调用 deployment 技能在同一路径以记录的兼容性清单启动服务运行 canary 查询如What is the capital of France?要求给出有效回答记录目标环境、服务框架与启动配置、查询与响应验证后停止服务除非用户要求保留。4.1 门禁报告表验证后必须输出如下形状的表格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/pathexact workspace/exact checkpoint pathdeploy 与 eval 必须继承PTQ compatibility requirementsdependency upgrades: ...; source patches: ...; custom code: ...; environment variables: ...; launcher/container changes: ...无则noneServing canarytarget environment; framework and launch configuration; query - response阻塞条件满足任一即停止不得继续压缩 recipe 的输出/源比率 1.0除非source_precision已解释即源本身已达或低于 recipe 目标位宽或用户明确接受解释任何本应量化的层组覆盖率为零或异常低任何层的量化元数据与其声明精度不一致提示词、tokenizer、生成、架构、上下文长度或特殊 token 元数据意外变更确切检查点工作区/路径缺失或未保留给部署与评估任一 PTQ 兼容性类别被省略须记录要求或nonedeployment 技能无法从记录的工作区/路径以记录的兼容性要求启动检查点服务 canary 未返回有效响应VLM 专有任何视觉塔权重model.visual.*/vision_tower.*/vision_model.*携带量化 scale除非有意量化 ViT。因为泛化*mlp*/*experts*recipe 会静默匹配 ViT MLP导致图像嵌入变成垃圾数据MMMU-Pro 约 0%而文本侧看起来正常——精度脚本还会把这类权重计为合法 NVFP4所以必须单独跑 VLM 检查。4.2 各 qformat 的预期量化模式Recipe--qformat应量化应排除nvfp4全部线性层lm_head、routers、norms、embeddingsnvfp4_mlp_onlyMLP 层含 MoE expertsAttention 层、lm_head、routersnvfp4_experts_only仅 MoE expert 层稠密 MLP、attention、lm_head、routersnvfp4_omlp_onlyMLP o_proj 层其余 attention 层、lm_head、routersfp8全部线性层lm_head、norms、embeddingsint4_awq全部线性层lm_head、norms、embeddings4.3 仓库提供的验证脚本checkpoint-validation.md 附带了可直接执行的 Python 脚本单行python3 -c形式大小检查对比源与输出的*.safetensors字节总和计算输出/源比率Output/source ratio: ratiox作为每权重位数的第一阶代理层覆盖率与精度脚本读取model.safetensors.index.json与hf_quant_config.json区分统一quant_algo导出与混合精度quantized_layers导出逐一检查每个线性层要么以预期精度量化、要么被显式排除输出层精度计数、意外未量化层清单按模块类型分组self_attn/mlp/experts/router/lm_head/embed_tokens/vision_tower与声明不匹配清单VLM 视觉塔检查遍历 shardedmodel.safetensors.index.json的weight_map或单文件读取 safetensors header导出的全部张量名统计带weight_scale/input_scale且路径含model.visual/vision_tower/vision_model的张量数量期望为 0。4.4 常见模式缺口量化配置模式与模型命名不匹配导致静默漏层的已知案例模型模块路径被漏掉的原因修复Gemma4 MoElayers.N.experts.**mlp*、*block_sparse_moe*不匹配添加*.experts.*模式自定义 MoElayers.N.moe_block.experts.**mlp*不匹配添加匹配模式VLM projectormulti_modal_projector.*—通常被排除需核实警告出现时的处理本应量化却漏掉的层如nvfp4_mlp_only下的 MoE experts修正量化配置模式后重跑 PTQ并检查 ModelOpt 是否已有该模型的插件modelopt/torch/quantization/plugins/huggingface.py有意不量化的层则应加入exclude_modules若导出未自动添加需手工同步写入检查点内的hf_quant_config.json与config.json的quantization_config.ignore防止部署失败。五、标准化交接报告Agent 定义规定只返回一个简洁的交接handoff包含以下九个固定标题并包含请求/观察覆盖率、大小、job ID 与绝对路径不得返回原始日志标题内容Status本次 PTQ 任务的最终状态Source checkpoint源检查点路径Recipe使用的 recipe 路径或补丁Quantized checkpoint量化检查点路径Validation门禁验证结果四组检查摘要Artifacts产物清单job ID、大小等Changes对 Model-Optimizer 源码的改动文件若有Blockers阻塞项这份固定格式的交接报告是 quantizer 与下游 deployer/evaluator 之间的事实契约精确的检查点路径、兼容性清单与 job 元数据使下游技能可以完全基于该报告继续工作而不必重新探查。相应地Agent 定义还要求仅在模型支持确需时做最小化的 Model-Optimizer 源码修改并逐一报告每个变更文件——这保证了仓库源码的稳定性与可审计性。六、与下游流水线的衔接quantizer 的输出通过验证的检查点交接报告会沿PTQ → Deploy → Eval流水线继续流转。工作区规范workspace-management.md为此设计了跨技能共享目录workspaces/session_id/model-name-format/ output/ ← PTQ量化检查点 eval_results/ ← EvaluationNEL 产物每任务 results.yml eval_config.yaml ← EvaluationNEL 配置 scripts/ ← Deployment/PTQ自定义运行脚本 logs/ ← AllSLURM 任务日志配合 ptq/SKILL.md 的 References 表quantizer 可按下表按需取用各参考文档参考何时读取common skill 的environment-setup.md/workspace-management.mdStep 1始终references/launcher-guide.mdStep 4BLauncher 路径references/unsupported-models.mdStep 4C未列出模型references/checkpoint-validation.mdStep 5强制后量化门禁common skill 的remote-execution.md4A/4C 且目标为远端时examples/hf_ptq/README.mdStep 3支持矩阵、CLI 参数、精度指引modelopt/torch/quantization/config.pyStep 3格式定义七、总结modelopt-model-quantizer的设计体现了窄职责强门禁标准交接的 Agent 工程思路它不参与选型、部署、评估只负责把一个已选定的 recipe 高质量地转化为经验证的量化检查点它以校准前的 recipe 覆盖率核查挡住配置模式的静默漏层以四组后量化验证挡住大小未压缩、覆盖不足、元数据漂移与无法服务化的检查点最终以九个固定标题的交接报告把精确路径与兼容性清单传递给下游。对于希望以 Agent 方式编排 PTQ 流水线的开发者本仓库的 agents 定义与 skills 技能树提供了完整、可落地的参考实现。赞分享人工智能大模型模型优化模型量化模型压缩【免费下载链接】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 PyTorch 量化实战指南PTQ、QAT 与 auto_quantize 完整解析Model Optimizer PyTorch 量化实战指南PTQ、QAT 与 auto_quantize 完整解析本文是 Model Optimizer人工智能大模型模型优化模型量化模型压缩Model-Optimizer ONNX 量化PTQ实战指南从校准数据准备到 TensorRT 引擎部署Linux BetaModel Optimizer ONNX 量化PTQ实战指南从校准数据准备到 TensorRT 引擎部署Linux Beta Model Optimi人工智能大模型模型优化模型量化模型压缩使用 Model Optimizer 对 Hugging Face 模型进行后训练量化PTQNVFP4/FP8/INT4/INT8 全流程实战指南使用 Model Optimizer 对 Hugging Face 模型进行后训练量化PTQNVFP4/FP8/INT4/INT8 全流程实战指南本文以人工智能大模型模型优化模型量化模型压缩上一篇go-fastdfs 常见问题解决方案下一篇如何使用BlindWaterMark零基础掌握Python盲水印技术的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Model-Optimizer 模型量化 Agent 实战指南：单候选 PTQ 执行、强制验证门禁与标准化交接

相关推荐

网站制作与网站建设实际报告：3种主流技术栈对比评测与避坑指南

Audio8 ASR Infinite 实时客户端全解：WebSocket 推流转写的完整链路解析

用 LinuxKit 为 Intel Clear Containers 构建精简虚拟机 Guest 内核与镜像

更多资讯

Windows 桌面应用自动更新链复盘：版本号三处不一致导致的静默拒绝安装

深入解析 WPScan 动态指纹识别：如何从 CHANGELOG.md 精准定位 WordPress 插件版本（以 tag-pages 为例）

The Concise TypeScript Book 精读：TypeScript 类型谓词（Type Predicates）实战指南

QuickRecorder macOS 录屏指南：三步从安装到录出第一条视频

绍兴网站建设公司地址新手入门避坑指南

Ajenti 安全加固实战：基于 Fail2ban 的暴力破解防护配置指南

今日更新

如何彻底离线使用 Laya-CoreML：Hugging Face 下载、缓存机制与 local_files_only 详解

基于1Panel 部署MySQL MCP 服务：TaoToken 统一 Key 接入与 config.toml 配置实战

崇州园区营销网站建设避坑指南：5大注意事项保备案安全

本周精选

如何彻底离线使用 Laya-CoreML：Hugging Face 下载、缓存机制与 local_files_only 详解

基于1Panel 部署MySQL MCP 服务：TaoToken 统一 Key 接入与 config.toml 配置实战

崇州园区营销网站建设避坑指南：5大注意事项保备案安全

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？