企业官网建设流程全解析

AMCT 量化评测指标与边界体系：基于 Wikitext PPL 与 delta 阈值的方案判读指南

【免费下载链接】amctAMCT是CANN提供的昇腾AI处理器亲和的模型压缩工具仓。项目地址: https://gitcode.com/cann/amct

AMCT（Ascend Model Compression Toolkit）在进行大模型量化方案评估时，需要一套统一、可复现、可判读的评测口径。本文以仓库内量化工具链的指标规范文档为主线，系统讲解 AMCT 当前采用的"单一主指标 + 差值边界"评测体系：为什么只用 Wikitext PPL、如何拿到 BF16 baseline 与量化结果、delta = ppl_quant - ppl_bf16的计算与0.2阈值判定、异常结果排查清单，以及配套的直转量化判读与 PTQ 算法收益判读流程。读完本文，你将掌握 AMCT 量化结果从"拿到数值"到"给出下一步决策"的完整判读方法，并能对照源码理解 PPL 指标在仓库中的真实计算方式。

当前主指标：为什么只用 Wikitext PPL

按照 指标与边界 的约定，当前阶段默认只使用一个主指标：

• Wikitext PPL（困惑度，Perplexity）

之所以收敛到单一指标，核心考量是"可测、可解释、可复现"。PPL 不需要复杂的评测管线，一条命令即可拿到数值，且对量化掉点足够敏感，适合作为直转量化第一轮判断和 PTQ 结果的粗判口径。这与工具链的定位一致——第一版方案优先求简单，不追求一步到位。

PPL 在仓库中的实际计算实现位于 eval_ppl.py 的wikitext2_ppl函数，其核心逻辑为：

• 对每个样本取shift_logits，构造shift_labels = samples[i][:, 1:]，与 logits 对齐；
• 用nn.CrossEntropyLoss()计算逐 token 损失，再乘上seq_len得到该样本的负对数似然（nll）；
• 累加所有样本的 nll，最终按torch.exp(nll_sum / (nsamples * seq_len))计算 PPL。

该函数还有两处严格的防护逻辑：logits 数量必须与样本数完全一致，否则抛出ValueError；logits 必须位于指定 device 上，否则同样报错。这些防护保证了 PPL 数值的可靠性，也解释了为什么评测结果异常时首先要怀疑链路而非直接下结论。

比较方式：BF16 baseline 与量化结果的差值

当前评测不是看绝对 PPL 值，而是以差值作为判定依据，比较方式如下：

1. 先拿到BF16 baseline：ppl_bf16；
2. 再评测量化结果：ppl_quant；
3. 计算边界量：delta = ppl_quant - ppl_bf16。

其中 BF16 baseline 的获取方式，在 quant-run 命令模板 中有明确约定：以examples/eval.sh为权威评测模板，直转评测命令为

python -m amct_pytorch.eval --model <path> --model_name <name> --device npu:N \ --granularity block --eval_mode quant --quant_target <mlp|moe|attn-linear|attn-cache> \ --quant_dtype <int|mxfp> --bit_config amct_pytorch/configs/<wXaY>.yaml --seq_len 4096

bf16 baseline 就是把--eval_mode换成bf16，其余参数保持一致。这里有几个必须遵守的口径约束：

• --model_name必填（已注册适配器名，缺失会默认 deepseek 造成误用）；
• --granularity block必填（默认的model粒度不真正量化，会给出假的"无掉点"结果）；
• --seq_len 4096是评测口径的一部分，direct-quant-eval 判读流程 要求确认口径一致（Wikitext PPL、seq_len=4096、同模型版本/代码口径），口径不同的旧结果不能直接横向比较。

当前默认边界：delta ≤ 0.2

边界判定规则非常明确：

• 如果delta <= 0.2，认为当前量化方案可接受。

这个0.2的阈值目前只用于两个场景：

• 直转量化第一轮判断：直转方案（不引入 PTQ 训练，直接按目标 bit/dtype 构建量化模型并评测）是否达标；
• PTQ 结果的粗判：进入 PTQ 升级后的第一层粗筛。

具体的判读流程见 direct-quant.md 和 direct-quant-eval 判读流程：

• delta <= 0.2：当前方案可接受；
• delta > 0.2：不可接受，建议缩小量化范围或转入 PTQ 升级；
• delta ≈ 0或 quant PPL 与 bf16 逐位相同：量化很可能未真正生效（例如granularity=model没真量化、quant_target未落到算子），不可直接判达标，应让 implementer 复核--granularity block、BitPolicy 与 quant_target 是否真正落到算子。

需要注意：delta <= 0.2只是"当前阶段"的默认边界。同一方案还可用"已满足业务目标"作为可接受的补充条件（满足任一条即可）。

当前不使用的规则

为了避免过早引入复杂度，指标规范明确要求当前阶段先不要引入以下三类规则：

• 相对比例阈值（例如按 PPL 的百分比掉点来判读，而非绝对差值）；
• 多数据集混合边界（例如在多个数据集上分别设阈值再合并判定）；
• 多指标联合打分（例如 PPL 与其他指标加权评分）。

这些规则标记为"以后再补"。这意味着现阶段所有判读都收敛到delta <= 0.2单一规则上，保证不同模型、不同方案之间的结果可以直接横比，不受附加规则干扰。

结果异常时的默认解释

当量化结果出现"反直觉"的数值时，规范给出的处理原则是：先不当作成功或失败，而是先检查链路。

量化后 PPL 明显比 BF16 更低

量化模型的 PPL 明显优于 BF16 在很多情况下并不代表量化"更准"，而是链路存在问题的信号。优先怀疑：

• 评测链路：PPL 计算或样本对齐是否正确；
• wrapper 实现：量化模块的包装器是否实现正确；
• forward / mask 逻辑：模型前向、attention mask 等逻辑是否在量化路径中被破坏；
• 保存与加载不一致：量化后权重/参数的保存与加载是否与推理路径一致。

量化后 PPL 明显高得离谱

掉点远超经验值时，优先怀疑：

• 量化范围过大：量化 bit 过低或 clip 范围设置不当；
• 某一类模块特别敏感：例如 attention 或 MoE 路径中的特定模块对量化格外敏感；
• 关闭量化后 wrapper 其实不等价：即 wrapper 在关闭量化时与原始浮点实现并不等价，导致基线口径被污染；
• 量化参数没有正确加载：PTQ 训练出的参数未随 eval/deploy 正确加载（参见下文"--algos 一致性"问题）。

这些排查方向与 ptq-escalation.md 中"不建议继续升级"的条件相互印证：当BF16 baseline 还不稳定、关闭量化后 wrapper 还不等价时，不允许继续叠加复杂度，必须先修链路。

从数值到决策：三步骤使用原则

指标规范给出的使用原则一共三条，形成"基线 → 差值 → 决策"的判读闭环：

1. 先看 BF16 baseline 是否稳定：baseline 不稳定，一切差值都不可信；
2. 再看当前方案的delta：与0.2阈值比较，判定可接受/不可接受/异常；
3. 不要只报数值，必须给出下一步决策：数值本身不是产出，基于数值的决策才是。

直转量化判读卡

direct-quant-eval SKILL 定义了一张标准的"直转量化判读卡"，用于固化每次判读的产出，字段包括：

• 当前方案：量化模块 /quant_dtype/a_bits / w_bits/algos/granularity；
• 评测口径：数据集 / 指标 /seq_len/ 模型版本·代码口径；
• 结果：ppl_bf16/ppl_quant/delta；
• 结果判读：是否达标 / 判断依据 / 是否异常；
• 异常检查（交 implementer）：优先检查 1 / 2 / 3；
• 下一步建议：保持当前方案 / 缩小量化范围 / 转入 PTQ 升级判读；
• 结果复用情况：是否复用旧结果 / 未复用原因。

PTQ 算法收益判读：delta_gain

当进入 PTQ 升级后，algorithm-validation SKILL 给出另一套基于差值的收益判读口径，注意此时基准必须是同位宽直转（而不是 BF16）：

• delta_direct = ppl_direct - ppl_bf16
• delta_algo = ppl_algo - ppl_bf16
• delta_gain = delta_direct - delta_algo

判定规则：

• delta_algo明显优于delta_direct（delta_gain为正且可观）→ 算法值得继续；
• 改善很小 / 不稳定 → 建议停用或换算法（W8A8 直转常已近最优、PTQ 无收益属于正常现象，不是失败）；
• ppl_algo明显优于 BF16 很多 / 数值异常 → 先让 implementer 查链路；
• 注意 solver 打印的 loss 经过归一化，跨 epoch 不动不代表没有学到，以 PPL 为准。

这里还有一个容易误判的坑：评测/deploy 若漏带与 ptq 训练一致的--algos，会报KeyError: Submodule '...algorithms.<algo>' is not found，这是参数加载侧的问题（quant-run 内建约束），不要误判为框架闭环或结构 bug。

最小化实验与防超时

在进入 PTQ 升级路径时，ptq-escalation.md 要求每轮实验后只能做三种决策之一：停止（结果已够用）、补定位（信息不足，不继续叠复杂度）、小幅升级（方向有效，再增加一档复杂度）。同时，大模型评测（30B+ 模型单段约 20 分钟以上）与 PTQ 训练（约 1 分钟/层）容易超过 agent runtime 的单条 Bash 超时上限（约 600s），必须采用后台运行 + 轮询的方式（nohup <命令> > run.log 2>&1 &启动后用多次短命令轮询），PTQ 中断可用--start_block_idx续跑。

总结

AMCT 当前的量化评测体系可以概括为一句话：以 Wikitext PPL 为唯一主指标，以delta = ppl_quant - ppl_bf16 <= 0.2为默认达标边界，先确认 BF16 baseline 稳定，再判读差值，最后必须给出下一步决策。这套体系刻意保持简单——不引入相对阈值、多数据集和多指标联合规则——以保证直转第一轮判断与 PTQ 粗判的可解释性和可复现性。当结果出现反直觉的偏低或偏高时，遵循"先查链路、再下结论"的原则，结合 direct-quant.md、ptq-escalation.md 与 quant-run 的执行规范，即可把每一次量化实验从"拿到数值"推进到"给出决策"。

【免费下载链接】amctAMCT是CANN提供的昇腾AI处理器亲和的模型压缩工具仓。项目地址: https://gitcode.com/cann/amct