量化专家经验调优库

职责边界

本 Skill 回答「给定量化目标与模型结构，如何调优量化精度」，输出基于专家经验分析的调优结论：

• 完整手段链：离群值抑制算法、量化方法/粒度/对称性选型、校准集调整、敏感层回退、模型专属策略。
• 回退：排除量化、恢复 BF16/FP16、或把某模块提级到更高精度档位（如 W4A8 中 experts 之外保持 W8A8），只是手段之一，且是最后手段。
• 不回退 / 保持量化：无专家经验支持时保持量化，不等于对所有模型绝对安全。

调优的具体执行（改 YAML、运行离群值抑制 processor、logits 对比、跑 msmodelslim quant、EP 检查、服务化、全集/子集测评）由对应执行 Skill 承接，不在本 Skill 范围内。

三级知识结构

按「通用 → 模型类 → 专属」递进，新模型先通读 L1，再按触发信号读 L2 对应小节，最后按 vendor 查 L3 个案。

层级	定位	文件	阅读时机
L1 通用专家调优意见	与具体结构无关的通用专家调优意见	cross-model-pitfalls.md	任何新模型都先通读
L2 结构化专家调优意见	仅对某类结构成立（MoE / MLA / 混合 attention / 自定义 modeling / VLM / DiT / DSA-SWA-GatedDeltaNet / Dense FFN）	structure-family-pitfalls.md	按触发信号判定，可多属，叠加 L1
L3 模型专属专家调优意见	各 <vendor>/<model>.md 个案，只放该模型/模型类独有的调优意见	models/（索引见 models/README.md）	命中已收录模型时叠加

输入

尽量提供：

• 模型结构类型与完整模块名样例（named_modules）；
• 量化格式：w8a8 / w4a8 / w4a4（含 int / mxfp 系）；
• 是否 MoE / EP、routed/shared experts 与 gate/router 命名；
• 当前生效 YAML 的 include/exclude、回退项与量化配置；
• 浮点基线、量化精度、敏感层分析或异常日志；
• 可引用的既有 Practice YAML 路径。

输出

按以下顺序给出调优结论：

1. 场景定位：结构模型类 + 量化格式，命中 L1/L2/L3 哪几处。
2. 首选调优手段（非回退）：离群值抑制、量化方法/粒度/对称性、校准集。
3. 优先回退候选：模块模式、层范围、回退方式与专家原因。
4. 默认保持量化 / 已保持高精度结构：有明确映射的 BF16 / 排除量化结构。
5. 模型专属策略：L3 命中项。
6. 建议顺序与风险、YAML 变更记录与专家意见可信度。

进入调优阶段时，先接收调用方基于已安装 Adapter 接口得到的 supported_algorithms。 未收到该集合时，先让调用方完成接口预检，再进行算法选择。本 Skill 只从该集合中 向用户介绍离群值抑制候选，说明适用场景和风险，再询问选择； 没有可选算法时不推荐离群值抑制。不得把以下示例中的算法视为当前模型均可选择：

user_confirmed_anti_outlier_algorithms:
  - { type: quarot, config: {}, source: user_confirmed }
  - { type: flex_smooth_quant, config: {}, source: user_confirmed }
  - { type: flex_awq_ssz, config: {}, source: user_confirmed }
  - { type: iter_smooth, config: {}, source: user_confirmed }

示例中的空 config 表示用户没有覆盖参数；执行阶段仍须读取 msModelSlim 对应的官方 *_default 模板，不能把空对象直接当作 flex_awq_ssz 的完整 processor 配置。

该字段只记录用户选择。专家经验不得调用 processor、执行前向或填写 logits PASS/FAIL； 离群值抑制阶段负责算法适配与门禁，调优只信任已安装 Adapter 声明的接口。

不得只根据模块名称直接宣称「回退必然提升精度」，须说明原因（如敏感层、结构重要性、误差传播路径）。

最小工作流

1. 通读 L1 cross-model-pitfalls.md，确认精度调优递进顺序与手段链。
2. 从真实 named_modules/YAML 判断结构模型类，按 L2 触发信号叠加对应小节。
3. 命中有 L3 个案的模型，叠加 models/<vendor>/<model>.md。
4. 说明离群值抑制可选项并询问用户选择，记录 user_confirmed_anti_outlier_algorithms。
5. 再给出其他非回退手段与敏感层回退候选，每条附专家原因。
6. 结论附专家意见可信度；processor 与 logits 校验由离群值抑制阶段承接。

核心规则速查

类别	默认处理	说明
激活离群值	候选包括 Iterative Smooth、Flex Smooth Quant、Flex AWQ SSZ、QuaRot，具体由用户选择	各候选在离群值抑制阶段单独执行和校验，不把组合运行结果当作单算法结果
权重低比特方法	INT8 用 minmax；INT4 用 ssz，不足再 autoround/gptq	权重 per_channel + 对称。ssz 在低比特下对分布适应性更好
激活粒度	性能 per_tensor；精度 per_token；平衡 pd_mix	激活通常非对称。per_token 可适应不同 token 的分布差异
校准集	10–50 条、场景匹配、删异常、加 badcase	第 4 步。校准数据不足或分布偏移会导致量化参数估计偏差
mlp.down_proj	优先回退候选	该层是 FFN 输出投影，聚合了 up_proj/gate_proj 的激活信号，量化误差易在此累积放大
o_proj（self_attn 输出投影）	结构化回退候选	exclude 增加 *.o_proj，单层投影保持浮点。作为 attention 输出聚合层，对整体表征质量影响较大
MoE gate/router	排除量化 / 保持高精度	路由决策敏感，量化误差可能导致 token 路由到错误 expert，造成推理质量下降
MoE experts	W4A8/W4A4 下为低比特落点	敏感实例才提级回退。experts 数量多、参数量大，是低比特的主要收益来源
shared_experts	通常保持高精度	每层共享，被所有 routed experts 复用，其误差会被全局放大，故保持高精度
MLA 低秩投影（kv_b_proj/q_a_proj/wk/weights_proj 等）	条件性排除	该结构承载逐头/低秩信息压缩，量化后误差会沿 attention 路径传播累积
DSA / SWA / GatedDeltaNet	保持高精度（bf16）	这些特殊结构在模型中承担交替扫描/线性注意力等特殊功能，分布与标准 attention 差异大
VLM 跨模态融合（merger/投影/视觉塔）	初版不量化，常见排除	仅量化 LLM 部分。跨模态投影层连接不同模态空间，量化误差可能破坏模态对齐

参考资料

• cross-model-pitfalls.md — L1 通用专家调优意见（离群值抑制/方法/粒度/校准集/回退）
• structure-family-pitfalls.md — L2 结构化专家调优意见（MoE/MLA/混合 attention/VLM/DiT/DSA/自定义 modeling/Dense FFN）
• models/（models/README.md 为索引）— L3 模型专属专家调优意见（deepseek/glm/minimax）
• 协同执行：msmodelslim-ep-parallel-adaptation（EP 适配）；调优主流程由 quantization-accuracy-tuning-orchestrator 承接