| name | model-infer-quantization |
| description | infer 仓模型量化适配改造技能。分析并接入既有 compressed-tensors 量化方案和权重，完成量化产物契约检查、结构参考匹配、量化 runtime 映射、权重加载、post-load 处理、融合算子量化冲突回退、真实生效验证和收益评估。用于模型优化流程中的量化初评估和量化改造任务；不重新设计上游量化算法，不实现 compressed-tensors 之外的量化路线。 |
模型量化适配改造
分析 infer 模型代码与既有 compressed-tensors 量化产物，按模型结构匹配仓库参考经验，完成量化接入、验证和收益评估。初评估模式只输出方案不改代码；改造模式在契约和用户决策满足后实施。
硬规则（TLDR）
本节是「该怎么做」的执行边界（范围 / 许可 / 流程 / 停止条件）；纯「别做啥」的禁止类统一见文末「反模式」。
- 范围：只做
compressed-tensors 主线；不碰 GPTQ / AWQ / 外部 patch / service 部署，也不碰 module/quantization/ 下 fp8 / mxfp4 / mxfp8 等仓内非 compressed-tensors route。
- 许可：可改 infer 侧 loader、模块映射、post-load、runner 和融合回退代码。
- 改造模式必须有用户继续量化的明确决策；缺决策只做分析（§1.2）。
- 融合算子不支持量化时，在主流程/用户确认后回退非融合路径继续跑量化基线，不因冲突放弃量化（§6.5）。
- 停止分两类：契约字段缺失 / 张量语义不清 / 权重不完整 → 停止并输出产物契约补充诉求（L3）；缺 infer 量化 runtime 能力 → 停止并确认是否另起 runtime 任务（L2，见 §4.3）。
工作流程
1 确认输入和执行模式 → 2 检查量化产物契约 → 3 拆解模型结构与量化对象
→ 4 匹配仓库参考与评估接入分级 → 5 方案审查
→ 6 实施量化接入（仅改造）→ 7 验证真实生效与收益 → 8 记录、后验决策与经验沉淀
每步「读取」标注该步要看的 reference；references 按需加载，不一次性全读。回退规则、验证要求、后验决策三段为本 SKILL 唯一真相源（§6.5 / §7 / §8.2），ref 不复述。
第一步：确认输入和执行模式
1.1 输入
| 输入 | 适用模式 | 说明 |
|---|
model_dir | 初评估 / 改造 / 验证 | infer 模型工作目录 |
quant_export_dir | 初评估 / 改造 / 验证 | 量化权重和量化方案目录 |
mode | 初评估 / 改造 / 验证 | 执行模式 |
baseline | 改造 / 验证 | 非量化部署基线；改造还应参考量化前最新基线 |
user_decision | 改造 | 用户明确继续量化的决策 |
1.2 模式分流
| 模式 | 允许动作 | 禁止动作 |
|---|
初评估 | 分析量化产物、结构、显存、接入分级，写初评估报告 | 改模型代码 |
改造 | 按已确认方案接入 runtime、加载权重、post-load、跑量化基线 | 改量化方案或权重语义 |
验证 | 验证真实生效、输出可用性、性能和显存收益 | 自行调试或改代码 |
1.3 输入缺失
- 缺
model_dir：转 model-infer-migrator 或要求补模型目录。
- 缺
quant_export_dir：停止量化路径，要求补齐产物目录。
- 改造/验证缺非量化基线：先补部署基线，不进入收益验证。
- 改造缺用户决策：只做分析，不改代码。
第二步：检查量化产物契约
读取：{quant_export_dir}/config.json、model.safetensors.index.json、deploy_quantization.md + references/quantization-contract.md §1-§4。
2.1 契约检查项
config.json 有 quantization_config（或 compression_config），quant_method = compressed-tensors。config_groups 能描述权重/激活量化；targets / ignore 能区分量化模块与浮点回退。model.safetensors.index.json 可索引量化与保留张量；张量语义明确（qweight / weight_scale / smooth scale / zero point 等）且可映射到 infer 参数前缀。deploy_quantization.md 写清量化对象、模式、回退策略、下游加载要求。
2.2 契约不满足时
任一关键项缺失：不猜测、不硬编码、不改方案，输出补充诉求（缺失项 / 影响模块和 runtime object / 期望格式 shape·dtype·scale / 阻塞原因），不进入改造。
第三步：拆解模型结构与量化对象
读取：{model_dir}/agentic/progress.md、{model_dir}/config/*.yaml、{model_dir}/runner_*.py（部分模型有，如 deepseek/glm/longcat-flash）、{model_dir}/models/modeling_*.py + references/quantization-contract.md §4-§6。
3.1 识别结构指纹（按真实结构，不按模型名）
| 结构指纹 | 判断依据 |
|---|
Dense Decoder | decoder-only，无 routed experts，有 attention projection 和 dense MLP |
MoE Decoder | 有 router/topk、routed experts、expert gate/up/down |
MLA + MoE / KVCache | 有 latent KV、MLA prolog、KV cache scale 或 MLA absorb |
Indexer / 长序列 + MoE | 有 Indexer、LI cache、Sparse FA、Hadamard 或长序列专属契约 |
| 特殊 packed expert | 专家权重或 scale 有特殊 pack/shard 规则 |
3.2 建立量化对象映射
| 量化目标 | infer runtime object |
|---|
| Dense Linear | Linear / ReplicatedLinear / RowParallelLinear |
| Dense MLP gate/up/down | 可量化 Linear；必要时 post-load 恢复 gate/up 融合 |
| Attention q/k/v/o | 可量化 Linear；必要时 post-load 恢复 q/k/v 融合 |
| MoE experts | MoEGMM / FusedMoEGMM，不满足时回退 per-expert Linear |
| KVCache | kv_cache_scheme / cache scale / cache runtime |
ignore 模块 | 浮点回退，不宣称已量化 |
3.3 记录运行场景
Prefill/Decode 分支差异、部署卡数 + TP/EP + 是否 online split、量化模式（W8A8 / W8A8C8 / W4A8C8 等）、量化前是否已有融合/前序优化、可能影响量化的 dtype/layout/scale/cache 组织。
第四步：匹配仓库参考与评估接入分级
读取：references/quantization-structure-cards.md 结构卡 A/B/C + references/quantization-fusion-and-benefit.md §A（融合兼容性）、§B.3（主线路径 A1-A4）。
4.1 按结构匹配参考卡
匹配结构卡（Dense / MoE / MLA+MoE / Indexer），各卡重点见卡内「改造要点」。结构卡命中 ≠ 经验全套用：forward 替身、scale 路径、post-load 例外必须基于当前模型实际算子链独立核对。只有结构无法落入已有卡，或出现新 runtime object / 张量语义 / post-load 规则 / 融合回退模式时，才新增卡。
4.2 融合算子兼容性判断
按 fusion-and-benefit §A.1 分级（A 量化主线-保留接量化输入 / B 共存-契约满足时保留 / C 需替身-先 post-load 融合或换量化友好算子 / D 专属契约-先看输出 dtype·cache layout·side tensor）+ §A.2 算子映射判断。冲突处理由主流程改造前向用户确认，回退规则见 §6.5。
4.3 接入分级（按模块/能力逐项打级，不压成单维）
按 §3.2 映射逐项打级（Linear / MoEGMM / KVCache / Indexer 独立给级），评估卡逐项写入；整体动作按最坏级触发，但保留逐项分级以记录「哪些就绪、哪些卡住」。
| 级别 | 判定 | 动作 |
|---|
| L0 | 只需配置或 YAML 对齐 | 补配置，直接验证 |
| L1 | 需要模型映射、runner 或 post-load | 改模型/runner/加载逻辑 |
| L2 | 缺 infer 量化 runtime object / 算子能力（compressed-tensors 无对应 method/kernel） | 停止当前适配，标 runtime gap，向主流程/用户确认是否另起 runtime 任务；不在本次适配内默默补 kernel |
| L3 | 量化契约缺失，无法安全接入 | 停止落代码，输出补充诉求 |
第五步：方案审查
进入代码改造前审查；未完成则回对应步骤补齐。此为改造前的统一 gate。
初评估任务到此结束：按 references/quantization-templates.md 的「量化方案初评估」模板输出报告（字段对应 progress_template「阶段 0.5」超集），不进入实施。
第六步：实施量化接入
仅改造任务执行。每次围绕「一个模块映射或一个 post-load 问题」推进，验证通过再继续下一个风险点。
读取：命中结构卡的「改造要点 / 已确认模型经验 / post-load 例外」。
接入形态：新模型走框架（model_worker 调 module/quantization 的 get_quant_config 读配置 + _process_weights_after_loading 触发 modeling 的 process_weights_after_loading，无 per-model runner）；少数早期模型用 runner_*.py 自己读 config 调 post-load（详见 contract §5）。
6.1 接入 quant_config
- 在真实 model loading 入口把
config.json 的量化配置解析成 CompressedTensorsConfig（实现可能是 get_quant_config(...) / CompressedTensorsConfig.from_config(...) / loader 内部 helper，不假定唯一入口）。
- 挂到模型 config（框架经
get_quant_config 挂到 hf_config.quant_config）并透传到各可量化模块；保持 prefix 稳定使 targets / ignore 命中。
- 输出头（如
lm_head）即使命中 targets:["Linear"] 又不在 ignore，构造时不传 quant_config 即可（输出头一般保持浮点：词表维度大、收益有限、影响采样分布，产物方通常也不导出其量化张量）。
6.2 替换或映射 runtime object
- Dense Linear：接入
Linear / ReplicatedLinear / RowParallelLinear 的量化方法。
- MoE experts：优先
MoEGMM / FusedMoEGMM；统一 W8A8 检查 gmm_quant_mode 是否继承 mm_quant_mode；混合位宽必须有独立 targets=["MoEGMM"] group。
- KVCache：按
kv_cache_scheme 和 cache scale 接入。ignore 模块显式浮点回退，不计入收益。
6.3 处理权重加载和 post-load
核对：量化张量名↔参数前缀、TP/EP shard 与 online split、weight 转置、NZ/base format、scale dtype、smooth scale 完整性、MoE expert pack/unpack、cache scale 来源（细则见结构卡「post-load 例外」）。
6.4 恢复量化后运行时融合
Dense 优先检查量化产物是否拆散原 fused gate/up 或 q/k/v、能否在 post-load 后恢复更大的量化 matmul（减少小粒度 matmul 和动态量化开销）。不改变量化方案语义。
6.5 处理融合算子冲突（唯一回退规则真相源）
本节是融合算子量化冲突的唯一回退规则真相源；其它 reference 不复述。
融合算子拒绝量化 dtype/layout/scale 时：① 不改量化方案 / targets / ignore / 张量语义；② 检查主流程是否已传入用户确认的回退原则，没有则停止改造并输出待决策项；③ 用户已接受则把该模块回退到原非融合路径；④ 继续按原量化产物加载验证；⑤ 记录融合算子名、失败输入契约、错误、回退点、后续融合量化需求。
6.6 ignore 不完备的兼容处理
触发：产物里既不在 ignore 也无 weight_scale 的 Linear 候选模块（contract §3 ignore 完备性启发式）。
- 前置 0 步：模型代码若已通过常规机制（
_keys_to_ignore_on_load_unexpected / load_state_dict(strict=False) / 不传 quant_config）让缺 scale 模块不参与量化加载，即等价合规；仍记补充诉求让产物方下版补 ignore。
- 读
deploy_quantization.md 量化范围声明，三分支：范围明确不覆盖该模块 → 视为 implicit BF16 + ignore 漏列，走隐式回退（infer 侧把前缀注入 effective ignore set，扩展 CompressedTensorsConfig.ignore 走 UnquantizedLinearMethod；不改产物 config.json；在 agentic/progress.md 记 implicit BF16 前缀 + 范围依据 + 补充诉求）；范围模糊或与 ignore 不一致 / 应量化但 scale 缺失 → 停止改造，输出对应补充诉求。
反模式：造假 scale 强行量化；int8 forward without scale；改产物 config.json；替产物方决策「漏 ignore 还是漏 scale」。
改造完成（进入验证前自检）
第七步：验证真实生效与收益
本步是量化验证要求的唯一真相源；其它 reference 不复述。
读取：references/quantization-fusion-and-benefit.md §B.1 五维口径。量化改造不能只看 diff，必须证明真实运行。
7.1 功能验证 + 等价性自检
- 功能：量化模型可加载，Prefill/Decode 至少各跑通一次，输出可读（不重复/非全零/非提前 EOS），日志能证明走到量化 runtime；验证命令记录模型路径、产物路径、卡数、YAML。
- 等价性自检（接线正确性，非精度评测）：绝对精度由产物方在
deploy_quantization.md 报告，本 skill 不评测精度。固定一组 prompt，量化基线与 infer BF16 基线各跑 greedy，文本 diff 记首个分歧 token；W8A8 允许细微差异，重点是不出现乱码/早停/与 BF16 显著走偏（抓 scale/layout 接错的「能跑但输出垃圾」）。连 BF16 参照都跑不了：标「等价性未核，转产物方精度报告」，不静默判通过。
7.2 生效验证（probe 优先，贴输出，不空打勾）
- probe-B 对象级（主，零开销）：加载后抽查量化目标层，
type(layer.quant_method).__name__ 不应为 UnquantizedLinearMethod（应是 CompressedTensorsW8A8Int8LinearMethod / MoEGMM method 等）。只查 load 后构造结果。
- probe-C 权重级：从加载日志统计命中的
qweight/weight_scale 等量化张量数，与期望量化模块数对账。
- probe-A 算子级（复用 §7.3 profiling，不单独跑）：已 profiling 则在
op_statistic grep QuantBatchMatmul/GroupedMatmul/DequantSwigluQuant/DynamicQuant 计数 >0。
并记录：已量化模块 / ignore 浮点回退 / 融合算子回退。
7.3 性能和显存验证
显存 / Prefill / Decode 三项均对比「非量化基线、量化前最新基线、量化基线」，部署卡数对比「原形态、量化后形态」。性能数据多轮取中位数 + 充分 warmup，避免 single-sample。初评估判断量化后单卡可能满足时，优先给单卡验证结果。
7.4 失败处理
- 映射/加载/post-load/scale dtype/runtime object 错误：优先修 infer 侧。
- 融合算子冲突：回退非融合路径继续验证并记录需求。
- 契约缺失或权重不完整：停止改造，输出补充诉求。
- 功能生效但性能未升：保留证据，分析动态量化开销/算子粒度/部署配置/profile；先做归因分离再下结论，不直接套单一根因。
完成标志
第八步：记录内容、后验决策与经验沉淀
8.1 量化应记录到 progress.md 的内容
写入由执行的 analyzer / implementer 子代理按其 progress.md 写入格式（只追加、不覆盖其他角色）落盘到 {model_dir}/agentic/progress.md（多优化路径如 longcat 为 agentic/progress_{path}.md）；归档（archive_progress.py → progress_history.md）与常驻区「量化接入常驻结论」由 model-infer-optimize 主流程维护。本 skill 只定记录内容，不负责写入机制与归档（与兄弟 skill 一致）。
记录内容清单见 references/quantization-templates.md 的「量化记录内容」。
8.2 后验决策依据（唯一后验决策真相源）
本节是量化基线产出后用户决策的唯一真相源；其它 reference 不复述。
量化基线产出后，本 Skill 只输出证据和建议，不替用户做最终取舍。给主流程提供三选择依据：① 采用部分回退的量化方案（接受当前收益，回退项沉淀为融合量化需求）；② 保留融合、跳过量化（收益不足或回退代价过高，继续非量化优化）；③ 修正量化方案后迭代（需补契约 / target / ignore / 张量语义 / 上游量化能力）。不在基线产出前给最终建议，不替用户确认是否接受。
8.3 经验沉淀
产生可复用经验时，按 references/quantization-structure-cards.md 末尾「经验沉淀模板」+「新结构补卡规则」追加：只按结构沉淀不按模型名堆卡；现有卡可覆盖时只补差异点和实践数据；只有出现新结构 / runtime object / 张量语义 / post-load 规则 / 融合回退模式时才新增卡。
输出格式
结束时按序输出：① 契约结论（满足/不满足/需补充）；② 当前模式；③ 量化产物目录、模式、覆盖范围；④ 结构参考卡、接入分级、关键映射；⑤ 已量化 / 浮点回退 / 融合回退模块；⑥ 验证证据和收益结论；⑦ 后续决策选项和建议；⑧ 阻塞点或补充诉求；⑨ 已沉淀或待沉淀的参考卡位置。
参考文档索引
按需查阅，避免一次性加载消耗 token。
| 主题 | 路径 |
|---|
| 产物契约 / 张量语义 / 运行对象映射 / 9 步机制（两种接入形态）/ 关键入口 | references/quantization-contract.md |
| 结构卡 A/B/C + 模型经验 + post-load 例外 + 经验沉淀模板 + 新结构补卡规则 | references/quantization-structure-cards.md |
| 融合算子兼容性 + 收益判断口径 + 主线路径 A1-A4 + 文件职责 | references/quantization-fusion-and-benefit.md |
| 初评估输出模板 + 量化记录内容清单 | references/quantization-templates.md |
反模式（final guard）
各章节已分散给出规则；本节汇总收尾前须排除的反模式。
- 重新跑上游量化实验 / 替代 AMCT-Q 等量化算法侧。
- 替代模型迁移、并行化、KVCache/FA、融合算子或图模式 Skill。
- 修改量化方案 /
targets / ignore / 张量语义 / dtype 来掩盖错误（§2.2 / §6.5 / §6.6）。
- 猜测缺失张量语义（§2.2 / 第三步）。
- 造假 scale 强行量化；int8 forward without scale（§6.6 反模式）。
- 修改产物
config.json（产物语义只读；§6.6 反模式）。
- 静默回退（§7.4 / §8.2）。
- 未验证真实生效就宣称量化成功（§7 / §8.2）。
- 量化基线产出前替用户做最终取舍（§8.2）。
