QuantBlockSparseAttn MXFP8 全量化精度测试指南:golden/NPU 对比用例框架与实战运行解析

原创2026-09-19 16:10:431,415 阅读
文章标签:算子库人工智能深度学习大模型高性能计算CANNAscend

QuantBlockSparseAttn MXFP8 全量化精度测试指南:golden/NPU 对比用例框架与实战运行解析

QuantBlockSparseAttn(QBSA)是 CANN ops-transformer 项目中面向 FP8 量化场景的分块稀疏注意力算子,其 quant_mode=2 的 MXFP8 全量化路径(QuantBlockSparseAttnMx)以「E4M3FN 数据 + E8M0 descale」组合完成 Q/K/V 的全量化。本文以仓库中 bsa_fullquant_mxfp8_test 目录 README 为主体,完整讲解 MXFP8 full-quant 用例的 golden/NPU 对比框架:从环境准备、用例查看与选择、CSV 批量运行、CPU golden 复用、Debug 调试,到新增 Case 的字段规范,并深入源码揭示数据生成、MXFP8 量化、block-table 构造、online softmax golden 与精度判定等底层实现。读完本文,你将能够独立运行并扩展 QBSA MXFP8 全量化精度回归用例,并理解其「空行 softmax 语义」「非有限输入传播」等关键约定。

一、测试目标:MXFP8 full-quant 在验证什么

本测试目录用于运行 QuantBlockSparseAttn 的 MXFP8 full-quant golden/NPU 对比用例,即算子文档 QuantBlockSparseAttnMx.md 中描述的 quant_mode=2 全量化路径。与 quant_mode=1(FP8)相比,MXFP8 路径的量化粒度更细:Q/K 按 D 轴每 32 个元素共享一个 FLOAT8_E8M0 scale(per-token-group),V 按 S 轴每 32 个元素共享一个 scale(per-channel-group),P scale 支持 FLOAT8_E8M0 或 FLOAT32。

执行入口脚本 qbsa_mxfp8_golden.py 的文档串(docstring)明确了整体管线:

参考式生成输入 → CPU golden → NPU 调用 → layout 对齐 → 精度对比;输出逐元素表格 + 统计汇总(PctRlt 通过率,双千分之五标准)。

即每个 case 固定走四个阶段:gen(生成输入并保存缓存)→ cpu(生成 CPU golden)→ npu(调用 NPU 算子)→ compare(比较 CPU/NPU 输出)。MXFP8 路径下 Q/QDescale 公共输入仅为 TND 布局,NPU 侧 K/V 使用 PA(PagedAttention)KV Cache。

1.1 Golden 的 softmax 状态模拟与空行语义

用例的 golden 直接模拟 master kernel 的 softmax 状态,不再使用额外的 has_valid_position 判断:

  • 在线 max 从空行哨兵(empty-row sentinel)开始;
  • OUT 以「空行(max 哨兵或 sum == 0)」判断输出 0;
  • 若某行的所有合法 QK score 均为 -Inf,则与 kernel 一致保留 attention_out=0;
  • 由 NaN 或 +Inf 触发的有效 softmax 行仍传播 NaN。

MXFP8 的 EMPTY_LSE 为 -Inf,与 CUDA SDPA 的空 softmax 行语义一致:kernel 侧 MX_EMPTY_LSE_VALUE = -3e+99 经 FP32 溢出后同样是 -Inf(源码 qbsa_mxfp8_golden.py#L1501-L1503 明确注释了这一点)。该语义同时适用于单 tile 和多 tile 的最终归一化。

1.2 非有限输入按 CUDA SDPA 语义保持

输入情况 attention_out LSE
Q/K 产生 NaN 或 +Inf score 传播 NaN 传播 NaN
Q/K 使所有 score 为 -Inf 输出 0 -Inf
V 中的 NaN/±Inf 只传播到 attention_out 仍由 Q/K 决定,不受 V 影响

1.3 STC 的 Q/K/V 数据范围设计

STC(单测场景)用例的 data_range_q/k/v 支持标量 inf、-inf、nan 以及区间 <a href="https://link.gitcode.com/i/42c92651ba06954c474f60b80288eb44" target="_blank">-inf, inf]。源码 [qbsa_mxfp8_golden.py#L613-L663 展示了无界区间的处理细节:

  • 无界区间会在相邻 D 向量的不同 MX group 中分别放入两个无穷端点,避免单个 QK 点积同时包含 -Inf 与 +Inf 导致 order-dependent 的 MX group 累加歧义;
  • ±Inf 使用 E4M3FN 的 ±448 与最大有限 E8M0 descale 2^127 配对,使 FP32 反量化得到同符号 Inf;
  • NaN 保留在 E4M3FN payload 中,并使用该组的合法有限 descale(全 NaN 组使用 1)。

这背后是 MXFP8 的编码约束:E8M0 只有指数位(2^(e-127)),没有数值 0(字节 0x00 表示 2^-127,0xFF 表示 NaN),见源码常量 qbsa_mxfp8_golden.py#L556-L557。

二、文件结构与工程入口

用例目录为 experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/,README 中列出的文件分工如下:

文件 职责
qbsa_mxfp8_golden.py 执行入口,负责生成输入、CPU golden、NPU 调用和精度对比
qbsa_mxfp8_test_cases.py 默认 testcase 文件,保留少量典型 case,便于日常快速回归
qbsa_mxfp8_test_cases.csv 批量 testcase 文件,每行对应一个 case(默认 CSV 数据源)
qbsa_mxfp8_test_cases_full.csv 单 batch 全量因子组合表
qbsa_mxfp8_test_cases_batch_large.csv 多 batch、ragged 和规模压力典型组合表
golden_cache.py 输入、CPU 输出、NPU 输出缓存工具
result_compare_method.py 精度比较工具

在当前仓库快照中,该目录还实际携带了三份 CSV 回归表:qbsa_mxfp8_redline.csv、qbsa_mxfp8_stc.csv、qbsa_mxfp8_stc_perf.csv,分别覆盖红线下发用例、STC 单测组合与性能线性度用例;其同名副本也维护在 tests/ttk/bsa_fullquant_mxfp8_test 目录下。这些 CSV 每行即一个 case,列结构包含 name, enable, B, N1, N2, D, cu_seqlens_q, seqused_kv, sparse_mode, block_size, mask_mode, quant_mode, data_range_* 等运行字段,以及 case_group, shard, S1_max, S2_max, n1_n2_ratio, s1_s2_relation, ... 等设计参考列。

三、前置条件:PTA 扩展编译安装

运行 NPU 路径前,需要先完成 PTA(PyTorch Adapter)扩展的编译与安装,确保 custom_ops 可以导入,并注册 npu_quant_block_sparse_attn 与 npu_quant_block_sparse_attn_metadata 两个自定义算子。从仓库根目录执行:

cd experimental/attention/quant_block_sparse_attn/torch_ops_extension
bash build_and_install.sh

build_and_install.sh 内部依次执行 python3 setup.py build bdist_wheel 编译 wheel 包,再 pip3 install *.whl -I 安装。若未安装,执行入口会抛出明确提示(源码 qbsa_mxfp8_golden.py#L152-L184):

import custom_ops failed. Please build/install QBSA PTA extension first, for example: cd experimental/attention/quant_block_sparse_attn/torch_ops_extension && bash build_and_install.sh.

四、查看与运行用例

4.1 查看用例:--list_cases

从仓库根目录执行:

python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --list_cases

输出会列出所有已加载 case 的名称和 enable 状态(格式为 case_name enable=True/False,对应源码 qbsa_mxfp8_golden.py#L3581-L3584)。

4.2 默认执行:四阶段流水线

不指定数据源和 case 名称时,脚本默认执行 qbsa_mxfp8_test_cases.py 中所有 enable=True 的 case:

python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py

默认 --mode all,等价于依次执行:

  • gen:生成输入并保存缓存
  • cpu:生成 CPU golden
  • npu:调用 NPU 算子
  • compare:比较 CPU/NPU 输出

每个 case 开始时会打印 CASE START <a href="https://link.gitcode.com/i/93967cd3fdc65c894f48467e0b6570b0" target="_blank">idx/total] 标志(对应源码 [qbsa_mxfp8_golden.py#L3113-L3121);一次运行多个 case 时,脚本末尾会输出 QBSA MXFP8 CASE SUMMARY 汇总表(实现见 qbsa_mxfp8_golden.py#L3162-L3217)。汇总表各列含义:

列名 含义
No. 用例序号
Status Pass / Failed / Generated / CpuDone / NpuDone / Error
Time(s) 该 case 总耗时(秒)
mfu*time MFU×时间(us),即 FLOPS / 算力;- 表示未计算(如未走数据生成阶段)
OutPct / OutMaxErr Attention 输出的通过率与最大误差
LsePct / LseMaxErr softmax LSE 的通过率与最大误差
Case case 名称

其中 mfu*time 在每个 case 的数据生成阶段会同时打印 FLOPS 与算力的完整计算过程,包括基本块数量、基本块 shape、单基本块计算量、FLOPS 公式、最小分型 shape、算力公式,以及最终 FLOPS / 算力 = MFU * 时间(us)。从源码 qbsa_mxfp8_golden.py#L2806-L2860 可以看到其口径:FLOPS = 基本块数 × q_block_size × kv_block_size × head_dim × 乘加计算(2) × 两次 bmm(2);算力 = 单位换算(1000) × 最小分型计算量(m=16、n=16、k=32)× 频率(1.65GHz) × AIC 数(32) × 乘加计算(2)。这些常量是脚本内统计用的估算参数,用于给数据生成阶段附加上下文参考。

五、指定单个或多个 Case

通过 --case_name 指定 case 名称:

python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --case_name STC_B1_BS128_MIN_PAGE_EQ_MASK3

--case_id 保留为兼容参数,效果等同于 --case_name(两者不能同时设置,见源码 qbsa_mxfp8_golden.py#L3586-L3588)。

也支持用逗号一次指定多个 case:

python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --case_name STC_B1_BS128_MIN_PAGE_EQ_MASK3,STC_B1_NOMASK_BS128_EQ_TAIL

六、CSV 数据源用法

6.1 基本用法与默认文件

使用 CSV 数据源时必须增加 --csv。此时未指定 --case_files 会读取同目录下的 qbsa_mxfp8_test_cases.csv。CSV 使用 Python 标准库(csv.DictReader)读取,不依赖 pandas 或 openpyxl(见源码 qbsa_mxfp8_golden.py#L283-L300)。

python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --csv

此时不指定 --case_name,会运行 CSV 中所有 enable=true 的 case;指定单个 case 的方式为:

python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --csv --case_name F_BS64_R5_N3_GT_AA

6.2 指定其他 CSV 或一次加载多个 CSV

python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --csv --case_files /path/to/cases_a.csv,/path/to/cases_b.csv

执行 300 条多 batch 与规模压力用例(qbsa_mxfp8_test_cases_batch_large.csv):

python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --csv --case_files qbsa_mxfp8_test_cases_batch_large.csv

6.3 复用 CPU Golden:--rdv

增加 --rdv 后,如果缓存目录中已存在当前 case 对应的 <case_name>_cpu_output.pt,脚本会直接加载该 CPU golden,跳过耗时的 CPU 计算;缓存不存在时仍会按 --mode 正常生成并保存。输入生成、NPU 调用和精度对比不受影响。

python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --csv --rdv

--rdv 默认从 golden_cache/ 查找,也可以配合 --cache-dir 指定缓存目录。缓存按 case 名称匹配;case 参数发生变化后,应删除旧缓存或使用新的 case 名称,避免复用不匹配的 golden。Debug 模式包含 gen 阶段时,新生成的 PT 仍写入 debug/<case_name>/pt/,RDV 查找仍使用正式缓存目录。

此外,CPU golden 的缓存键还会编码 matmul 后端与有效 P scale 值(<case_name>_<backend>_p_scale_<...>,见源码 qbsa_mxfp8_golden.py#L3059-L3077),避免 CPU torch.matmul 与 npu_quant_matmul 两套 golden 相互污染缓存。

不带 --csv 时,--case_files 按 Python testcase 文件解析:

python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --case_files /path/to/custom_test_cases.py

6.4 更多 CLI 选项

除 README 文档列出的选项外,执行入口还提供以下由源码确认的开关(qbsa_mxfp8_golden.py#L3469-L3544):

选项 作用
--aclgraph 使用图模式(torchair + torch.compile)执行 NPU 算子调用
--no_save 不保存 input/cpu_output/npu_output 到磁盘,节省空间和时间
--case_range start:end 只跑 CSV 中指定行范围的用例(1-based,含两端),如 100:200
--quant_matmul 使用 npu_quant_matmul 而非默认的 CPU torch.matmul 做 QK/PV 计算

七、批量用例设计解析

7.1 blocknum 与 block_table 构造

blocknum 表示可供 block_table 映射的物理页池大小。case 显式传入正数时直接使用该值;未传入或传入非正数时,才根据每个 batch 的实际 KV 长度推导默认值:

blocknum = sum(ceil(seqused_kv[b] / block_size))

源码 qbsa_mxfp8_golden.py#L532-L544 中,非正数显式传入会触发警告并回退到推导逻辑。

block_table 的宽度为:

max(max_block_per_batch, max(ceil(seqused_kv[b] / block_size)))

确保每个 batch 的有效逻辑页都可索引。表中每个位置从 <a href="https://link.gitcode.com/i/caa438c0c9c232770c42e9070a580641" target="_blank">0, blocknum) 物理页池中有放回随机采样:一次选中的物理页不会从候选池移除,因此同一 batch 内或不同 batch 间的多个逻辑页允许映射到同一个 physical ID,用于覆盖物理页共享场景(构造实现见 [qbsa_mxfp8_golden.py#L786-L841)。blocknum 不要求等于全部逻辑页数量之和:小于逻辑页总数时可以通过复用完成映射,大于逻辑页总数时也允许存在未被引用的物理页。超过各 batch 有效 KV 长度的 block_table 填充列不会被 kernel 读取。

7.2 S1/S2 关系与对齐:11 个有效组合

CSV 中存在以下仅用于记录用例设计的字段,统一放在 case 属性末尾,不参与 pytest 的类型转换、校验或计算:

case_group, s1_base_size

CSV 按列名而非列位置解析,允许保留其他扩展参考列。因此已有外部泛化 CSV 即使列顺序不同或包含 pytest 未使用的字段,也可以继续加载;实际运行字段仍需提供合法值(这一策略也对应源码注释「其余列作为用例设计参考信息原样保留」)。

一个关键的数学约束:S1/S2 相等时,「S1 不对齐 128、S2 对齐 512」在数学上不可实现——一个数只要对齐 512,就必然对齐 128。因此「三个关系(S1>S2 / S1=S2 / S1<S2)× 四种对齐状态」共有 11 个有效组合,而不是 12 个。

7.3 三张批量用例表的覆盖设计

  • qbsa_mxfp8_test_cases.csv 包含 212 条用例,其中 188 条默认启用,覆盖 block_size=64/128、重点和非重点 head 组合、11 组可实现的 S1/S2 大小关系与对齐状态、mask_mode=0/3、不同稀疏模式、block-table 顺序以及空 Tensor 场景。
  • qbsa_mxfp8_test_cases_full.csv 包含 2948 条单 batch 用例,补齐 mask_mode=0/3 与 return_softmax_lse=true/false 的排列组合;物理页数统一由实际 KV 序列自动推导。
  • qbsa_mxfp8_test_cases_batch_large.csv 包含 300 条全部启用的多 batch 典型与大规模用例:
分组 数量 覆盖点
等长主路径 48 交叉 B=2/4/8、两种 block size、mask、LSE 和重点 head
ragged batch 24 递减、交替、一长多短和 Q/KV 长度反向变化
规模压力 16 最大 S1=16384、S2=32768,并以低头数限制内存
sparse/block-table 8 顺序、反序、随机、尾块和部分稀疏用例
边界用例 4 B=16、缩放参数、部分零长度 batch 和空 actualSeqLengths
扩展典型 80 补齐多 batch 下的 N2=2/5/6/7
中大型组合 80 B=3/12 等长和一长多短用例
扩展 ragged 40 扩展 ragged/部分空 batch/部分 sparse 用例,batch 覆盖扩展到 B=32

默认 Python testcase 文件(qbsa_mxfp8_test_cases.py)当前保留 6 条 BASE/MIX case(默认关闭、用于 mfu 规模回归),并包含 37 条默认启用的 STC,覆盖单 batch、多 batch、ragged、稀疏拼接、scale、mask、LSE、空输入和不同 block-table 顺序。典型 STC 命名如 STC_B1_BS128_MIN_PAGE_EQ_MASK3、STC_B1_PA960_S64_S2_TAIL_MASK3、STC_B1_HIGH_RANGE_QK_PSCALE64,从名称即可读出 block size、PA 页数、S1/S2 关系、mask 模式、GQA 分组与 scale 等关键设计意图。

八、Debug 模式

--debug 必须与一个 --case_name 配合使用,只允许执行单个 case。默认(不指定 --mode 或 --mode all)执行完整的 gen/cpu/npu/compare 流程:

python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --debug --case_name BASE_01

CSV case 同样支持 debug:

python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --csv --debug --case_name F_BS64_R5_N3_GT_AA

也支持指定 --mode 为非 all 的组合,例如只复用已有缓存跑 NPU 对比,不再重新生成数据和 CPU golden:

python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --debug --case_name F_BS64_R5_N3_GT_AA --csv --mode="npu,compare"

输出目录固定为 debug/<case_name>/:

debug/<case_name>/
├── run.log
├── pt/
│   ├── <case_name>_input.pt
│   ├── <case_name>_cpu_output.pt  # RDV 命中正式缓存时不重复写入
│   └── <case_name>_npu_output.pt
└── precision/
    ├── attention_out.png
    └── softmax_lse.png        # return_softmax_lse=true 时生成

cpu_output.pt 保存 CPU golden,npu_output.pt 保存算子输出。精度图逐元素使用与 check_result 相同的 rtol/atol:白色表示通过,蓝色表示失败(生成逻辑见 result_compare_method.py#L270-L407)。图片标题会标注 golden/算子 shape、逻辑矩阵大小、显示大小、元素数和失败数。超大 Tensor 会按区域聚合:某个显示像素对应的原始区域中只要存在一个失败元素,该像素就是蓝色。因此整体比较允许少量失败元素而最终为 Pass 时,图片中仍可能出现少量蓝点。生成 PNG 需要安装 matplotlib。

Debug 模式的数据读写位置取决于 --mode 是否包含 gen:

  • 包含 gen(如 all、gen、gen,cpu):数据生成后写入 debug/<case_name>/pt/,此模式下不允许指定 --cache-dir(debug 自行管理 pt 目录);
  • 不含 gen(如 npu,compare、compare、npu):从已有缓存读取 input.pt、cpu_output.pt 等数据,默认读取本目录下的 golden_cache/,可通过 --cache-dir 指定其他缓存来源;precision PNG 始终输出到 debug/<case_name>/precision/。

无论哪种 --mode,Debug 模式都不允许使用 --cache_case_name(命名由 debug 内部管理),也不能与 --list_cases 组合使用(参数互斥校验见 qbsa_mxfp8_golden.py#L3558-L3574)。

九、指定执行阶段:--mode

--mode 支持 all/gen/cpu/npu/compare,也支持逗号组合:

# 只生成输入
python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --mode gen

# 使用已有缓存,只跑 NPU 并比较
python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --mode npu,compare

阶段间的依赖关系在 run_one_case 中实现:只跑 gen 时数据保存后即以 Generated 状态退出;cpu 阶段会先尝试 RDV 复用;npu 阶段若缺省输入会从缓存加载;compare 阶段需要同时存在 CPU 与 NPU 输出。非法 mode 值会被 argparse 直接拒绝(合法集合定义于 qbsa_mxfp8_golden.py#L3470)。

十、缓存目录管理

默认缓存目录为本目录下的 golden_cache/。可以通过 --cache-dir 指定:

python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --cache-dir /tmp/qbsa_mxfp8_cache

缓存文件名前缀默认使用 case 名称。需要自定义时使用:

python experimental/attention/quant_block_sparse_attn/tests/pytest/bsa_fullquant_mxfp8_test/qbsa_mxfp8_golden.py \
  --cache_case_name my_case

缓存工具 golden_cache.py 按 <case_name>_input.pt、<case_name>_cpu_output.pt、<case_name>_npu_output.pt 三个文件组织读写;同时运行多个 case 时,--cache_case_name 还会与 case id 拼接成 <前缀>_<case_id> 以避免冲突(见 qbsa_mxfp8_golden.py#L3050-L3057)。

十一、新增 Case 指南

默认方式是在 qbsa_mxfp8_test_cases.py 的 TestCases 中新增 dict(TestCases 为 list,每个元素是一个字段 dict)。也可以在 qbsa_mxfp8_test_cases.csv 中新增一行,并通过 --csv 执行。两种方式都要求 name 唯一;enable=True 表示默认运行,关闭的 case 仍可通过 --case_name 单独执行。

字段格式:

  • actual_seq_q、actual_seq_kv 使用 JSON 数组文本,例如 <a href="https://link.gitcode.com/i/258bd60ff005bc7db524b35abf3fd5ee" target="_blank">256]。在当前仓库用例中,序列字段以 cu_seqlens_q(B+1 个前缀和,首元素必须为 0)+ seqused_kv(B 个非负有效长度)承载,且 MXFP8 路径要求 cu_seqlens_kv 与 seqused_q 为空(校验见 [qbsa_mxfp8_golden.py#L371-L408)。
  • 等长多 batch 可以使用单元素总 T,例如 B=8, S1=65536, actual_seq_q=[65536] 会在运行时展开为 8 个 8192。
  • enable、is_contiguous、return_softmax_lse、empty_actual_seq 使用 true/false。
  • softmax_scale 留空时,脚本按 1 / sqrt(D) 自动补齐(见 qbsa_mxfp8_golden.py#L429-L431)。
  • N1 必须能被 N2 整除(GQA 分组约束)。
  • s2_base_size 是 golden 划分 C1 子块的必需运行字段,当前 MXFP8 模板固定为 512,传入其他值会被 validate_mxfp8_case 拒绝。
  • sparse_q_block_size 必须等于 sparse_kv_block_size;block_size(PA 物理块大小)必须是 sparse_kv_block_size 的正整数倍(支持 block_size = m * sparse_kv_block_size,且按算子文档不超过 1024)。
  • s1_base_size 仅作为覆盖场景说明保留,不参与 pytest 计算或校验。
  • p_scale_type 仅支持 float8_e8m0fnu 或 float32 的输入,传入其他值或不传会默认为 float8_e8m0fnu。
  • p_scale_value 若传入必须是正且有限的标量。
  • CSV 可直接扩展到多行;case 名称在一个或多个输入文件之间都不能重复(重复会抛出 duplicate case name,见 qbsa_mxfp8_golden.py#L453-L454)。

十二、源码级实现支撑(进阶)

12.1 数据生成与 MXFP8 配套量化

输入生成遵循「fp32 随机 → 从 fp32 算 descale → fp8 = clamp(fp32/descale)」的配套流程,保证 fp8 × descale ≈ 原始 fp32 且反量化不溢出(qbsa_mxfp8_golden.py#L1325-L1449):

  • Q/K 按 D 轴每 32 元素一组求组内有限绝对值最大值,取 ceil(log2(max / fp8_max)) 的 2 的幂作为共享 descale(quantize_mxfp8_qk,L694-L742),E4M3 饱和钳位到 ±448;
  • V 按 S 轴每 32 元素一组(quantize_mxfp8_v,L745-L783);
  • Q/K descale 按 (偶, 奇) 对打包成 <a href="https://link.gitcode.com/i/0cffb7780ddac16f8b847fde36959422" target="_blank">..., Dg//2, 2] 供 NPU 使用(pack_qk_scale_for_npu,[L1093-L1100);
  • K/V 直接以 PA 物理缓存形态生成(K/V 为 [BlockNum, N2, BlockSize, D],K descale 为 [BlockNum, N2, BlockSize, D//64, 2],V descale 为 [BlockNum, N2, ceil(BlockSize/64), D, 2])。

12.2 block_table 与 PA KV Cache 预处理

mxfp8_pa_preprocessing(L1115-L1208)将 internal BNSD 布局的 K/V 及 descale 按 block_table 写入 PA KV Cache,支持 BnNBsD / BnBsND 两种 kv_layout;V descale 还会做偶奇行交错 packing(convert_v_scale_to_pa)。所有 PA 张量要求严格的 PA_BNBD stride((N*BS*D, BS*D, D, 1)),即使是 size-1 的 N 维也会被 kernel 校验,因此生成侧通过 _materialize_pa_bnsd 显式分配目标 stride。

12.3 CPU golden 的 online softmax 与空行语义

cpu_mxfp8_golden(L2064-L2354)按 sparse block 流计算:

  • 依据 sparse_indices/sparse_seq_len 收集每个 Q block 可访问的 KV block,并按 256-token C1 粒度切分为 chunk(_positions_from_sparse);
  • 在线 max 从 EMPTY_LSE = -Inf 哨兵开始,softmax 前的 max 会对齐到 ln2 的整数倍(ceil(x * INV_LN2) * LN2),与 VF 的 FP32 运算顺序保持一致;
  • mask 值固定为 MASK_VALUE = -10000.0;
  • 行级归一化复刻 kernel 的 LastDivNewVF(sum == 0 输出 0)、RowInvalidUpdateVF(max 为哨兵输出 0)、ComputeLseOutputVF(两者都映射到相同哨兵)三个出口守卫。

为消除「先反量化再 matmul 引入人工 Inf」的偏差,QK/PV 还提供了与 MX Cube 一致的「按组点积 + 指数对齐 sticky-overflow 累加」修复路径(_accumulate_mxfp8_groups_cpu),并仅在 payload 本身不含 NaN 时才做修复,保证真实 NaN 继续传播。

12.4 NPU 调用与图模式

NPU 调用(npu_mxfp8_fa,L2863-L3034)分为两步:

  1. 先执行 metadata 算子 torch.ops.custom.npu_quant_block_sparse_attn_metadata 物化主算子依赖的 metadata(两次 torch_npu.npu.synchronize() 分别保证异步 H2D 输入就绪与 metadata 完成);
  2. 再调用主算子 torch.ops.custom.npu_quant_block_sparse_attn,通过 quant_mode=2 选择 MXFP8 路径,返回 (atten_out, lse_out)。

除单算子模式外,还支持 --aclgraph 图模式(_call_npu_fa_op_graph,L2586-L2686):使用 torchair 的 CompilerConfig(mode="reduce-overhead") 后端,对所有输入执行 torch._dynamo.mark_static 固定 shape,并通过 torch.compile(fullgraph=True) 捕获 ACL 图;同时关闭 reinplace_inplaceable_ops_pass,避免对 custom op 仍在使用的 Buffer 做 reinplace。

12.5 精度比较方法

result_compare_method.py 的 check_result(L168-L267)实现了统一的判定口径:

  • 使用 torch.isclose(rtol, atol, equal_nan=True) 做逐元素比较:默认 rtol=0.005, atol=0.000025,输出为 bf16 时自动切换为 rtol=0.0078125, atol=0.0001(get_compare_tolerance);
  • 通过率阈值 PctThd = 99.5%(即 README 所称的「双千分之五标准」:误差率与通过率各自 5‰),最大相对误差阈值 max_diff_hd = 10,超过任一标准判 Failed;
  • 结果以 PctRlt(通过率百分比)与 Max-RelativeError 输出,并打印逐元素表格(首 10 与末 10 个元素)及错误明细。

结语

QBSA MXFP8 full-quant 测试框架把「算子语义对齐」「数据生成配套量化」「CPU golden 参考实现」「NPU 调用」「精度判定」五件事收敛到一个入口脚本与若干声明式 case 表中。理解其「空行 softmax 语义 = CUDA SDPA 语义」「E8M0 无零值、无界区间端点配对」等设计约定,是新增覆盖场景的关键;而 Python/CSV 双数据源、--rdv 缓存复用、--debug 精度图与 --mode 阶段裁剪则让日常回归、问题定位与大规模批量验证都能高效展开。如需深入算子侧语义,可进一步阅读 QuantBlockSparseAttnMx.md 与 QuantBlockSparseAttn.md;要了解非 MXFP8 的通用 golden 组织方式,可参考同目录的 quant_block_sparse_attn_golden.py。

登录后查看全文
ops-transformer