Model Optimizer Recipes配方系统入门：YAML一键复现任何量化方案

Model Optimizer Recipes配方系统入门YAML一键复现任何量化方案【免费下载链接】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-OptimizerModel OptimizerModelOpt是 NVIDIA 推出的大模型优化统一框架内置量化、蒸馏、剪枝、神经架构搜索、投机解码等 SOTA 技术可将深度学习模型压缩并部署到 TensorRT-LLM、vLLM 等推理引擎。而其中的Recipes 配方系统让如何优化一个模型从散落在 Python 代码里的参数变成一个独立的 YAML 文件——改配置不再改代码一次量化方案可以复现、可分享、可进版本库。本文将带你从零看懂这套系统并用一条命令一键复现官方量化方案。为什么需要配方告别硬编码的量化参数量化一个 70B 模型你通常要决定哪些层用 FP8、哪些层用 NVFP4、KV Cache 用什么精度、校准算法选 max 还是 GPTQ……这些参数如果写死在脚本里会带来四个痛点痛点没有配方时有了 Recipes 后复现结果配置埋在命令行参数里难以追溯一个 YAML 文件完整描述团队协作口头传参版本不一致配方文件可直接 diff、review换模型重新翻代码找要改哪直接选一份现成配方记录实验笔记散落各处配置即文档天然可追溯正如官方文档 docs/source/guides/10_recipes.rst 所说配方是声明式规范declarative specification把优化设置与 Python 代码解耦。配方系统的三层架构整个配方系统由 modelopt/recipe/ 包实现分为三层配方源Recipe sources存放在 modelopt_recipes/ 目录下的 YAML 文件随包发布或你自己文件系统里的 YAML。配置加载器load_config负责读取 YAML、解析路径并自动完成e4m3这类浮点位宽简写转换。配方加载器load_recipe用 Pydantic 模型校验配置返回类型安全的配方对象可直接喂给量化工具。核心入口代码见 modelopt/recipe/loader.py数据模型见 modelopt/recipe/config.py。from modelopt.recipe import load_recipe import modelopt.torch.quantization as mtq # 内置配方库直接用相对路径引用无需前缀 recipe load_recipe(general/ptq/fp8_default-kv_fp8_cast) # 加载后直接用于量化 model mtq.quantize(model, recipe.quantize, forward_loop)解剖一份量化配方结构一目了然以最常用的 fp8_default-kv_fp8_cast.yaml 为例去掉版权头后只有 4 个部分imports: base_disable_all: configs/ptq/units/base_disable_all # 先禁用全部量化器 w8a8_fp8_fp8: configs/ptq/units/w8a8_fp8_fp8 # 线性层 W8A8 FP8 kv_fp8_cast: configs/ptq/units/kv_fp8_cast # KV Cache 用 FP8 default_disabled_quantizers: configs/ptq/units/default_disabled_quantizers metadata: description: W8A8 FP8 E4M3 量化 FP8 KV Cachemax 校准 quantize: algorithm: max # 校准算法 quant_cfg: - $import: base_disable_all - $import: w8a8_fp8_fp8 - $import: kv_fp8_cast - $import: default_disabled_quantizers可以看到它由四块积木拼成先全部禁用 → 打开需要的量化器 → 排除敏感层如 LM head、router→ 完成。这就是官方推荐的 deny-all-then-configure 模式既安全又简洁。上图展示了不同校准算法对量化精度的影响——这正是配方中algorithm字段的价值所在同样的 NVFP4 格式选对校准算法可让 Qwen3 27B 的平均精度损失从 2.31 分降到 0.77 分。内置配方库导航三级查找策略modelopt_recipes/ 是随包发布的配方库官方提供了29 份通用 PTQ 配方。查找配方时遵循由具体到通用的三级策略目录含义查找时机models/org/model_id/特定发布检查点按模型库路径索引你的模型恰好有官方发布配方时model_type/model_type/按架构索引一份覆盖同架构所有检查点你的模型架构有专属配方时general/ptq/模型无关任何模型可用默认起点万金油例如 Qwen3.5 架构的专属配方在 modelopt_recipes/model_type/qwen3_5/ptq/而 MoE 模型专家层专属压缩配方 nvfp4_experts_only-kv_fp8_cast.yaml 则放在通用层。配方文件名本身就是一份说明书命名规律为格式与作用域-KV缓存模式[-校准算法].yaml nvfp4_mlp_only-kv_fp8_cast.yaml └──┬──────────┘ └──┬─────┘ NVFP4 仅 MLP KV 用 FP8完整的选择指南请阅读 modelopt_recipes/ptq.md——它解释了每份配方量化了模型哪些部分全部线性层 / 仅 MLP / 仅 MoE 专家 / 仅权重以及为什么这样设计。一键复现用 --recipe 参数跑通完整流程配方系统打通了 Python API 与命令行两条路径。以 examples/hf_ptq/hf_ptq.py 为例整条命令如下python examples/hf_ptq/hf_ptq.py \ --model Qwen/Qwen3-8B \ --recipe general/ptq/fp8_default-kv_fp8_cast \ --calib_size 512 \ --export_path build/fp8 \ --export_fmt hf关键行为一旦指定--recipe脚本会直接加载配方配置并跳过所有格式相关的零散参数如--qformat、--kv_cache_qformat。也就是说配方是最高优先级的单一配置源——这正是一键复现的含义。图中展示了不同量化方案下有效位宽 vs MMLU 精度的权衡曲线——当你不确定该选哪份配方时这种精度-压缩比曲线就是最好的决策参考。两大省力设计$import 积木与 ExMy 简写1. $import 可组合导入。可复用的配置片段集中存放在 modelopt_recipes/configs/ 下configs/numerics/— 数值格式定义nvfp4.yaml、fp8、mxfp8 等 15 种configs/ptq/units/—quant_cfg构建块default_disabled_quantizers.yaml 等 18 个标准片段导入还支持覆盖先导入nvfp4片段再内联修改type: static即可在不动原片段的前提下微调一个字段。2. ExMy 浮点简写。位宽不用再写 Python 元组(4, 3)num_bits: e4m3 # 自动转为 (4, 3)FP8 标准格式 scale_bits: e8m0 # 自动转为 (8, 0)MX 块缩放大小写不敏感E4M3、e4m3均可。三步写出你自己的配方创建自定义配方只需找一份最接近目标配置的现成配方推荐从general/ptq/开始复制并修改quantize部分——敏感层排除清单和全禁用前缀直接$import内置片段只手写格式相关条目更新metadata.description说明你的改动保存后用--recipe 你的路径或load_recipe(你的路径)加载。路径解析规则很友好相对路径会先查内置配方库再查本地文件系统本地同名文件优先生效——这意味着你可以在不改库的前提下覆盖某份内置配方做实验。不止于 PTQ配方系统的未来版图PTQ 只是第一类配方。系统按metadata声明的配方类型自动匹配对应的 Pydantic 模型目前已支持PTQquantize段当前主力AutoQuantize自动量化搜索约束配置投机解码EAGLE3 / DFlash / Medusa 草稿头训练配方见 modelopt_recipes/general/speculative_decoding/蒸馏扩散模型 DMD2 蒸馏配置load_dmd_config同一份 YAML 同时驱动 Python API、CLI 参数和内置常量未来还将扩展到 QAT、剪枝与多阶段复合配方。对新手而言理解这套系统只需记住一句话配方是配置不是代码——选一份、跑一条命令即可复现。延伸阅读配方总目录 modelopt_recipes/README.md · PTQ 配方选型指南 modelopt_recipes/ptq.md · 完整 API 文档 docs/source/guides/10_recipes.rst【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考