Model-Optimizer 检查点镜像配方：以 `models/＜org＞/＜model_id＞` 目录精确复现已发布量化检查点

人工智能大模型模型优化模型量化模型压缩【免费下载链接】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-OptimizerModelOpt的配方库modelopt_recipes/中models/目录专门存放针对单个已发布模型检查点调优的优化配方主要是后训练量化 PTQ 配方。本指南说明这类检查点镜像/别名配方的目录组织、命名约定、运行时加载方式以及判断何时该为此检查点新增一条目、该写 mirror 还是 alias的完整决策依据帮助读者把任意 Hugging Face Hub / ModelScope 上的具体 checkpoint 与其量化配方一一对应并精确复现发布版本的混合精度方案。一、models/在配方库中的定位按检查点而非架构组织ModelOpt 配方是声明式的 YAML 文件描述一次完整的模型优化工作流算法、逐层数值格式、校准方式作为如何优化一个模型的单一受控事实来源。配方库按适用范围分为几层modelopt_recipes/README.md 的布局表给出了全景目录覆盖范围modelopt_recipes/general/模型无关model-agnostic配方适合任何模型的起点modelopt_recipes/model_type/model_type/按 transformersmodel_type组织的架构级配方一个配方覆盖该架构的所有检查点modelopt_recipes/timm/architecture/面向 timm 模型的架构级配方modelopt_recipes/models/org/model_id/检查点级配方镜像某个特定已发布检查点以其模型仓库路径为键modelopt_recipes/configs/共享构建块numerics/、ptq/units/、ptq/presets/等仅供$import组合不直接运行models/与前两者的关键区别在于键keymodel_type/model_type/以架构为键一个条目服务该架构下的所有检查点而models/下的每个条目以唯一一个已发布检查点为键——即使两个检查点架构相同只要发布了不同精度的量化版本就需要各自的条目。从源码结构看这是为了让给定一个 hub 上的 checkpoint立刻能找到它的量化配方这一映射关系无须查表即可成立。二、目录结构磁盘路径即模型仓库路径models/的目录树完全镜像模型仓库如 Hugging Face Hub、ModelScope上的路径。每个实例以它的model-hub 路径org/model_id也就是传给from_pretrained(...)或出现在 hub URL 中的那个字符串为键modelopt_recipes/models/ org/ # hub 命名空间 / 组织例如 nvidia、mistralai model_id/ # hub 模型 id例如 Nemotron-3-Nano-4B-BF16 task/ # 优化工作流例如 ptq recipe.yaml [recipe.aux.yaml] # 可选的 $import 辅助片段snippet [README.md] # 可选说明该检查点特有的部分task表示该配方面向的优化工作流如ptq表示后训练量化也可以是auto_quantize、speculative_decoding等。当前仓库中models/下已存在按此约定的实例部分列举nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16/ptq/nvfp4_w4a16.yamlnvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16/ptq/nvfp4-max-calib.yaml、nvfp4-mse.yamlnvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B-BF16/ptq/nvfp4-4o6.yamlnvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16/ptq/w4a16_nvfp4_4o6.yaml另有speculative_decoding/dspark_warmstart.yamlQwen/Qwen3.5-397B-A17B/ptq/nvfp4_experts_mse-fp8_rest-kv_fp8.yamlQwen/Qwen3.8-27B/ptq/nvfp4_w4a4_mlp_fp8_attn_local_hessian.yamlQwen/Qwen3.8-2.4T-A95B/ptq/nvfp4_experts_mse-fp8_self_attn-fp8_linear_attn-kv_fp8_cast.yamldeepseek-ai/DeepSeek-V4-Pro-0813/ptq/nvfp4_experts_only.yamlmoonshotai/Kimi-K2.6/ptq/nvfp4_experts_only_mse-kv_fp8_cast.yaml、Kimi-K3/ptq/nvfp4_experts-fp8_pb_attention.yamlmistralai/Mistral-Medium-3.5-128B/ptq/nvfp4-max-calib.yamlstepfun-ai/Step-3.5-Flash/ptq/nvfp4-mlp-only.yamlzai-org/GLM-5.3-Flash/ptq/nvfp4_experts_dense_mlp-kv_fp8_cast.yamlMiniMaxAI/MiniMax-M2.7/ptq/nvfp4_experts_only-kv_fp8_cast.yamlmeta-models/Muse-Glimmer-30B/auto_quantize/w4a16_nvfp4_4o6_mixed.yaml由于文件夹路径本身就是 hub 路径从检查点 id 到配方、从配方回到检查点都无需任何查找表。命名org/model_id文件夹的规则使用检查点在 hub 上的精确org/model_id包括大小写。当同一份权重在多个 hub如 Hugging Face Hub 与 ModelScope以相同org/model_id发布时一个文件夹即可服务所有 hub。当配方是针对某个canonical / base 检查点调优、但同样适用于它的镜像mirror版本时以该 base 模型的 id 作为文件夹名。三、如何选择配方从最具体到最通用优先选择对当前模型最具体的条目models/org/model_id/——如果存在与你精确检查点匹配的条目。用它来对齐一个已发布的量化检查点它要么复现该版本经过验证的、常为逐组件混合精度的方案要么 alias 到能产出该方案的通用配方。modelopt_recipes/model_type/model_type/——架构级配方适用于该model_type的每个检查点。modelopt_recipes/general/——模型无关配方任何没有更具体条目的模型的良好起点。models/目录的存在本身就是一个信号该模型有经过调优、推荐使用的配方。查找顺序遵循先精确、后架构、再通用避免用户在通用配方上重复调参。四、运行时选择配方CLI 与 Python API配方路径以modelopt_recipes/为根。命令行示例如examples/hf_ptq/hf_ptq.py的--recipe参数使用--recipe models/org/model_id/task/recipe例如--recipe models/nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16/ptq/nvfp4_w4a16。Python 侧通过 modelopt/recipe/loader.py 暴露的load_recipe加载from modelopt.recipe import load_recipe recipe load_recipe(models/nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16/ptq/nvfp4_w4a16)从 loader.py 的源码 看路径解析遵循以下规则先查文件系统、后查内置配方库用户自己的本地配方树优先于同名内置配方。扩展名.yaml/.yml可省略加载器会自动探测。支持huggingface/→model_type/的向后兼容别名源码树中保留 symlink内置 wheel 中通过_alias_builtin_recipe_prefix重写前缀旧--recipe huggingface/...路径对 pip 安装用户仍可解析但会触发FutureWarning提示改用新前缀——这是此前model_type/曾叫huggingface/的遗留。load_recipe还接受overrides参数key.pathvalue形式的 dotlist在 YAML 校验前通过 OmegaConf 合并覆盖值用yaml.safe_load解析类型foo.bartrue→ bool 等目录形式metadata.ymlquantize.yml仅限 PTQ不支持 overrides。加载器在原始 YAML 层面做前置校验_REQUIRED_SECTION_PER_RECIPE_TYPE给出比 pydantic 缺字段更友好的错误PTQ 配方必须含quantize段auto_quantize配方必须含auto_quantize段speculative_eagle/speculative_dflash/speculative_medusa分别要求eagle/dflash/medusa段。五、两类条目mirror镜像与 alias别名models/下的条目有两种形式添加时二者的区别至关重要。1. Checkpoint mirror——配方实体就在这里只有当配方镜像一个具体已发布或计划发布检查点——手工映射、通常逐层或逐组件的精度方案专门对齐那次发布——才在这里承载完整的 body。若该调优能推广到某架构的每个检查点应放到modelopt_recipes/model_type/model_type/若模型无关应放到modelopt_recipes/general/。modelopt_recipes/ptq.md说明了每个检查点镜像的具体做法及其与通用 baseline 的对比。以 NVIDIA-Nemotron-3-Nano-4B-BF16 的nvfp4_w4a16.yaml为例它是一个典型的逐层手工映射 mirror方案来源镜像 GGUF Q4_K_M 的位分配Q4_K/Q5_0权重 → NVFP4 W4A4Q6_K权重 → FP8 W8A8Q8_0→ 依情况处理映射到 NVFP4 / FP8 之上。逐层覆盖注意力q/k/v/o_proj、MLP 各投影及部分层down_proj走 NVFP4 W4A4特定编号层1, 3, 5, 8, 10, 18, 25, 33, 41的mixer.down_proj显式改为 FP8 W8A8lm_head→ FP8 W8A16仅权重embedding → NVFP4 W4A16仅权重。导出约束q/k/v在导出时融合必须共享同一格式因此第 24、32 层的v_proj不单独用 FP8。默认禁用集通过$import: default_disabled_quantizers把lm_head、embedding、conv1d、BatchNorm 等关掉保持 BF16再以enable: true精确重开需要量化的两个目标。NVIDIA-Nemotron-3-Super-120B-A12B-BF16/ptq/nvfp4-max-calib.yaml则展示了组件级混合精度的另一种形态MoE 路由专家 → NVFP4 W4A4block 16、e4m3 缩放共享专家与 Mambain/out_proj→ FP8 per-tensorKV cache → FP8而lm_head/MTP head/潜在 MoE/q/k/v_proj保持 BF16 不量化。nvfp4-max-calib.yaml文件头注明它近似镜像发布版hf_quant_config.json但校准用 amax/max 而非 MSE。再如 Qwen3.8-2.4T-A95B 的混合注意力配方该模型是qwen3_5_moe_text架构92 层、512 路由专家 共享专家、gated-delta 线性注意力层与全注意力层交错配方把路由专家置为 NVFP4MSE 静态权重缩放、动态输入缩放自注意力与线性注意力全链路含linear_attn.conv1d置为 FP8 W8A8KV cache 用 FP8 cast 模式MTP 块保持 BF16。文件头明确记录了验证依据导出检查点在 GPQA、AA-LCR、SciCode、IFBench、Terminal-Bench 2.1 上相对 BF16 baseline 无有意义精度回退且源检查点本身以原生 block-FP8 发布加载器会先反量化到 BF16 再插入量化器校准。2. Alias——配方实体在别处这里只留记录许多已发布检查点用的方案就是某个通用配方原样产出的没有任何检查点特有的改动。此时仍可在models/下给它一条目让配方在检查点自己的 hub 路径下可被发现——但条目只是一个薄 alias把整个 body 委托给那个配方imports: base: general/ptq/nvfp4_default-kv_fp8_cast $import: base metadata: description: - meta-llama/Llama-3.1-8B-Instruct quantized with the general NVFP4 scheme and an FP8 KV cache in cast mode, as published in nvidia/Llama-3.1-8B-Instruct-NVFP4.顶层$import把被导入配方的整个 body 引入与之并排给出的键覆盖被导入的键。因此这个 alias 自带自己的metadata而quantize算法和每一条quant_cfg原样继承。没有任何重复编辑 base 配方会自动影响所有指向它的 alias。实际仓库中还有一种alias 覆盖的混合形态例如 Qwen3.8-27B 的nvfp4_w4a4_mlp_fp8_attn_local_hessian.yaml它以base: models/Qwen/Qwen3.8-27B/ptq/nvfp4_w4a4_mlp_fp8_attn_max为基$import: base继承其 NVFP4 W4A4 FP8 W8A8 分配该分配由 5.5-bit NVFP4-max AutoQuantize 扫描导出随后仅覆盖algorithm为local_hessian启用 layerwise、从上一层取 QDQ 激活。这演示了$import的键级覆盖语义在检查点条目中的灵活用法。alias 不声明什么是有意为之它没有recipe_type因为类型就是被导入配方的类型。一个配方可以在下列任意位置声明自己的类型加载器按序取第一个生效者命名其 schema 类的# modelopt-schema:注释metadata.recipe_type——已弃用仍会读取但新配方应省略通过顶层$import委派的那个配方。从 loader.py 的_peek_recipe_type可以看到这条解析链的完整实现它还负责检测$import委派环cycle并报告recipe A 委派给委派回 A 的 recipe。任何声明必须为真同时声明 schema 注释和recipe_type且二者一致是允许的跨委派亦然——一个配方与被它导入的配方必须是同一类型因为 import 接管整个 body。任何不一致都是错误而非偏好。唯一必需项被其他文件 import 的配方必须带 schema 注释因为$import解析要靠它校验被导入的负载。不被任何配方 import 的文件则不需要。因此首次 alias 一个配方时需要在同一改动中给它补上注释。决策准则写 mirror 还是 alias先假设写 alias只有在确认没有可移植配方能表达该发布的方案时才写 body——把发布自带的hf_quant_config.json以及区分相关时其导出的 scale 张量与候选配方quant_cfg会产出的结果逐一比对。从通用配方复制一份 body 是维护负债它不再跟踪被复制配方的后续修改。六、什么情况不该给发布版本加条目只有模型卡描述的是后训练post-training量化配方时才会在这里补条目。若模型卡记录的是PTQ 之后的量化感知蒸馏QAD则刻意不加没有任何 PTQ 配方能复现该检查点宣称能复现的条目反而是错的。如果你来找某个 NVIDIA 已发布检查点却没找到通常是这个原因——先看模型卡是否提到 QAD再断定条目只是缺失。这解释了当前models/目录下为何只有 PTQ 与少量auto_quantize、speculative_decoding条目而不会有 QAD 训练的条目。七、跨配方共享内容snippet 片段当多个配方复用同一 body 时把它抽到同级的snippet文件中带# modelopt-schema:头、通过$import引入让每个配方 wrapper 保持轻薄。snippet 的命名要明显表明不可直接运行例如recipe.field.yaml并以其相对modelopt_recipes/的路径引用。当前 modelopt_recipes/configs/ 下的共享块正是这一机制的基础设施——configs/numerics/fp8.yaml、configs/numerics/nvfp4.yaml、configs/ptq/units/base_disable_all.yaml等都带# modelopt-schema: modelopt.torch.quantization.config.QuantizerAttributeConfig或LayerPatternList类注释是$import解析的合法目标。这也解释了上文各检查点配方里$import: fp8、$import: nvfp4、$import: base_disable_all、$import: default_disabled_quantizers这类写法数值格式与禁用集合被抽成可复用单元检查点配方只描述自己的增量。八、Per-folder README记录检查点特有的意图每个task/文件夹可含一个简短README.md精确说明什么是检查点特有的——哪些层偏离通用预设、使用了什么校准数据、镜像的参考检查点是哪个——让评审者和用户不必把 YAML 与通用预设逐一 diff 就能看出意图。例如meta-models/Muse-Glimmer-30B/auto_quantize/README.md即配套其搜索配方存在。查看具体配方意图时应优先阅读同目录 README 与 YAML 头部的注释块各镜像配方在文件头完整记录了方案来源、HF 与 Megatron-Core 的命名对应、校准变体等。小结把检查点变成可复现的配方modelopt_recipes/models/用最朴素的方式解决了一个已发布量化检查点如何被精确复现的问题目录路径即 hub 路径条目即检查点能通用表达的就用$import委派成薄 alias不能通用表达的就在文件头记录完整来源并逐层映射成 mirror。配合 modelopt/recipe/loader.py 的路径解析、类型判定与覆盖机制任一from_pretrained能加载的模型 id都可以直接换算成一条--recipe models/org/model_id/task/recipe从而在 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点击查看免费下载相关推荐docker-stacks镜像发布检查清单确保镜像质量与安全docker stacks镜像发布检查清单确保镜像质量与安全 1. 基础合规性检查 1.1 镜像构建策略验证 检查依据 新镜像/包策略 https://l云原生开发工具数据科学Model-Optimizer 实战DeepSeek V3 / V4 系列 NVFP4FP4量化与 TRT-LLM 统一检查点导出指南Model Optimizer 实战DeepSeek V3 / V4 系列 NVFP4FP4量化与 TRT LLM 统一检查点导出指南 本指南完整讲解 N人工智能大模型模型优化模型量化模型压缩LangGraph 0.3.3版本发布优化检查点恢复机制LangGraph 0.3.3版本发布优化检查点恢复机制 LangGraph是一个基于Python的轻量级工作流编排框架专注于构建和运行复杂的多步骤任务流程人工智能AI AgentAgent 框架流程编排后端上一篇tanstack/vue-router 1.167 → 1.170 演进解读匹配调度重构、错误边界与响应式订阅模型下一篇终极指南zfile v4.0如何彻底重构你的云存储管理体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考