AMCT 模型适配验证清单新模型族接入 PTQ 主流程的质量闸门【免费下载链接】amctAMCT是CANN提供的昇腾AI处理器亲和的模型压缩工具仓。项目地址: https://gitcode.com/cann/amctAMCTCANN 昇腾 AI 处理器亲和模型压缩工具仓在把新的 LLM 模型族接入 PTQ 主流程时遵循「只做适配、不重写主流程」的原则而.agents/skills/quant-tools/model-adapter/references/validation-checklist.md正是这套适配工作收尾阶段必须逐项核对的验证清单。它把「语法检查、BF16 baseline、quant block 构建、PtqUnit 枚举、浮点等价、参数导出回载」组织成最低必做、推荐再做、收尾自检三层配合 model-adapter.md 的八步工作流使用。读完本文你将掌握在amct_pytorch/common/models/llm/...范围内完成一次合格模型适配所必需的全部验收点以及这些验收点背后对应的源码实现位置与判断依据。清单的定位适配流程的最后一道闸门该 skill 的完整适配流程定义在 SKILL.md 与 model-adapter.md 中先判断新模型结构block / attention / MLP class、dense 还是 MoE、experts 是显式模块还是 packed tensor、PtqUnit 怎么拆再定写入范围、按顺序复用现有抽象、打通最小路径、拿到 BF16 baseline、过浮点等价检查、接最小 PTQ 闭环最后做总结。validation-checklist.md 承接的是上述流程的收尾环节——它不教你如何写 wrapper而是给出「做到什么程度才算真正完成」的可执行判据。清单全文可概括为三组最低必做没有完成就不应宣称适配结束、推荐再做提高适配质量与可回归性、收尾自检结束前用四个问题复查改动边界。其隐含的评测口径约束也值得注意凡涉及 Wikitext PPL 的验证统一使用seq_len4096旧口径如 2048的 baseline 默认不能直接当作当前适配结论复用。最低必做六项硬性验收点1. 对所有修改文件做语法检查这是最廉价却最容易被跳过的检查。适配通常涉及amct_pytorch/common/models/llm/family/model/下的 Python 文件例如 qwen3.py、deepseekv4.py、glm5_2.py改动后应逐文件确认无语法错误避免把低级问题带入后续较长的验证阶段。2. BF16 baseline 路径至少验证一次或明确记录阻塞原因BF16 baseline 是判断量化是否损伤精度的参照系必须在进入量化前先拿到。对应工作流 Step 5 的要求是模型的 BF16 推理路径能跑通、baseline 指标能被记录如果因环境或路径原因暂时拿不到必须显式记录阻塞点不能静默跳过。适配者应把「哪个 block、哪条前向路径、用什么输入规模」跑出的数值记录下来作为后续浮点等价与 PTQ 效果对比的基准。注意默认评测口径为seq_len4096。3. 至少构建一层新模型的 quant blockquant block 的构建入口是模型适配器adapter上的build_quant_block()其职责是把原始 decoder layer 用量化 wrapper 包起来。以 qwen3.py 为例def build_quant_block(self, layer_idx): decoder_layer self.block(layer_idx) if attn-linear in self.quant_target or attn-cache in self.quant_target: apply_quant_to_attn(self.args, decoder_layer, QuantQwen3Attn) if mlp in self.quant_target: apply_quant_to_moe_mlp(self.args, decoder_layer, clsQuantQwen3MLP) return decoder_layer这里按quant_target分派attention 目标用apply_quant_to_attn()包裹self_attn/linear_attnMLP 目标用apply_quant_to_moe_mlp()包裹 MLP 或 MoE experts。通用实现位于 quant_apply.pyapply_quant_to_moe_mlp()会递归遍历named_children()按名称和位置分配group顶层mlp→mlpexperts下的专家 →moe.routedshared_experts→moe.sharedapply_quant_to_attn()则负责替换self_attn/linear_attn。验证时至少构造一层layer_idx 取 0 即可并确认 wrapper 能正常 forward。4. 至少枚举出一个PtqUnitPtqUnit是 PTQ 训练与参数导出回载的最小粒度单元定义在 ptq_units.pydataclass class PtqUnit: kind: str name: str layer_idx: Optional[int] module: Any metadata: dict[str, Any] field(default_factorydict) property def save_name(self) - str: return self.name.replace(., _)kind标识单元类型如attn、mlp、moename用于定位save_name把点号转下划线供导出文件名使用。配套的 make_ptq_unit 与 iter_indexed_units 提供了构造与按索引批量枚举的便捷入口。枚举逻辑的默认实现位于 base.py 的iter_ptq_units()attention 目标产出attn单元MoE 目标用iter_indexed_units逐个产出专家单元并附带{expert_idx: idx}元数据MLP 目标产出mlp单元。多数组族适配器如 qwen3_moe.py、longcat_lite.py通过yield from super().iter_ptq_units(...)复用默认逻辑仅在结构特殊时重写。验证点很简单对至少一层 quant block 调用iter_ptq_units确认能枚举出至少一个 unit。5. 在适配路径上验证关闭量化后 wrapper 前向与原始浮点模块一致或足够接近这是适配正确性验证而非量化效果判断——它要证明 wrapper 本身没有破坏模型语义。实现上依赖观察标志set_model_to_observe(model, flag)quant_apply.py会遍历模块把所有带is_observe属性的量化器切换到观测态flag 为 True 表示不真正量化、只统计。在 base.py 的do_block_forward()中use_quant_blockTrue且enable_quantFalse时即调用set_model_to_observe(block, True)让量化块以浮点等价模式跑前向与原始 float block 的输出做数值对比。判定标准关闭量化后quant block 输出与原始 float block 应一致或足够接近若不一致先修 wrapper 等价性不要继续往 PTQ 走对应 model-adapter.md 的 Step 6。6. 至少验证一个 unit 的 PTQ 参数可以导出PTQ 参数导出/回载的公共接口由PtqParamHandler提供ptq_params.py在 wrapper 上的落点是export_ptq_params()/load_ptq_params()。以可复用的门控 MLP 量化 wrapperQuantGatedMLPquant_apply.py为例def export_ptq_params(self): params PtqParamHandler.export_module(self) if params: return params return PtqParamHandler.export_trainable_module(self) def load_ptq_params(self, params): if isinstance(params, dict) and params and all(isinstance(v, dict) for v in params.values()): PtqParamHandler.load_module(self, params) return PtqParamHandler.load_trainable_module(self, params)导出的参数需能落盘并能被load_ptq_params()回载。层级的加载入口是load_layer_ptq_params()base.py内部走ptq_param_store.load_layer()。验证时至少挑一个 unit导出其参数确认产物完整含save_name对应的文件名。推荐再做四项质量增强检查1. 跑一个 unit 级 PTQ smoke test即 model-adapter.md Step 7 的最小 PTQ 闭环抽一条 unit 输入路径 → 为该 unit 生成 GTground truth→ 跑一次 unit 级 solver → 监控训练健康信号 → 保存参数 → 回载参数。它的定位只是「验证 adapter 已接到 PTQ 主链」不在这一步下 PPL、delta、量化方案优劣的结论。训练健康信号是关键loss 应从初始值逐步收敛若 epoch loss 恒为 0 或 NaN说明该 PTQ unit 未被正确优化可能原因包括build_no_algo_args与iter_ptq_units不一致、输入为 None、梯度未传播应立即停止检查适配逻辑不要浪费计算资源——SKILL.md 中明确点名参考hunyuan/hy3-preview的 shared_experts PTQ 策略矛盾作为反面案例。2. 回载保存的 PTQ 参数并跑一次 forward导出与回载必须成对验证。回载走load_ptq_params()/load_layer_ptq_params()回载后重新 forward确认参数真正生效、无 shape 或 key 不匹配问题。iter_ptq_units的for_loadTrue标志base.py用于选择前向真正使用的专家作为参数落点子类覆写时必须透传该标志这是回载路径容易出错的地方。3. 检查模型特有逻辑是否泄漏到了amct_pytorch/workflows/...workflowworkflows负责 PTQ 主流程编排应按模型族保持稳定。模型特有的结构判断、wrapper 选择、unit 拆分逻辑都应留在amct_pytorch/common/models/llm/family/model/的适配器与 quant_module 中而不是塞进 workflow。若发现需要改 workflow 才能支持新模型说明改动范围越界应回到适配器层重新设计。4. 检查是否无必要地改动了 solversolver 位于 common/optimization承载搜索/优化范式。除非新模型真的需要新的优化范式否则不应改动同理quantization/modules 下的通用 wrapper 也不应在模型适配中轻易修改——只有现有接口确实无法表达该模型结构时才允许。这条检查与「优先复用PtqUnit、QuantLinear、QuantGatedMLP和现有 quant-apply helper」的复用优先原则互为表里。收尾自检结束前的四个问题改动是否主要停留在amct_pytorch/common/models/llm/...默认改动范围只包括amct_pytorch/common/models/llm/family/model/。只有存在明确理由共享抽象不够、通用 wrapper 表达不了、workflow 不兼容才允许触碰 common、quantization/modules 与 workflows且每处越界都要有理由。仓库中已有族级目录可作为边界参考deepseek/、glm/、hyv3/、longcat/、qwen/各自包含*_vN/子目录与quant_module.py族间共用的PtqUnit、wrapper、helper 集中在common/。是否先复用了现有 wrapper再新增抽象复用优先顺序PtqUnit→QuantLinear→QuantGatedMLP→apply_quant_to_attn()/apply_quant_to_moe_mlp()→ 只有真正不同的部分才写模型专属 wrapper。除非同一模式已经在至少两个模型族里重复出现否则不要急着抽新基类。attention / MLP / MoE-MLP 均遵守合并原则同系列两个 wrapper 若初始化、状态与 forward 一致只保留一份实现不因「dense vs moe」之名机械拆分只有底层模块结构、导出语义、PTQ unit 边界、量化路径真正不同时才拆两份。关闭量化时wrapper 是否保住了原始浮点行为即最低必做第 5 项在收尾时的复查set_model_to_observe路径下 quant block 与 float block 前向一致或足够接近。若这里不过关后续一切量化结论都不可信。是否避免了没有必要的框架级重构适配的目标是「以最小改动范围把新模型接入现有 amct PTQ 主流程」不是重构主流程。框架级重构会放大回归面、抬高评审成本应作为最后手段。完成标准与交付输出结合 SKILL.md 的完成标准清单全部通过意味着至少一层 quant wrapper 能正常构建BF16 baseline 已拿到或明确记录阻塞原因已验证适配路径上「关闭量化后 wrapper 保持浮点等价」至少一个 PTQ unit 能被枚举并完成最小 PTQ 集成 smoke已跑过本验证清单已做文档写回判断是否同步repo-map、系列 casebook README、Agent Docs触发则更新未触发则说明理由。适配结束的输出要求与清单配套包括新模型的结构判断结果、实际改动范围是否越界、复用了哪些现有抽象、BF16 baseline 是否跑通、浮点等价检查是否通过、最小 PTQ 集成 smoke 是否打通、剩余风险或未完成项、attention 是否按最小化实现原则收敛、文档写回判断结论。最后再核对本清单的三层条目——逐条打勾、逐条留痕才是对「新模型已合格接入 amct PTQ 主链」最可信的交代。【免费下载链接】amctAMCT是CANN提供的昇腾AI处理器亲和的模型压缩工具仓。项目地址: https://gitcode.com/cann/amct创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考