Closed
[Documentation|文档反馈]: 修正 IndexerQuantCache README 的量化粒度与 HiFloat8 scale 说明 #6477
KaranocaVeAdd on  26 days agoClosed at  26 days ago
KaranocaVe
KaranocaVe
26 days ago Create

[Documentation|文档反馈]: 修正 IndexerQuantCache README 的量化粒度与 HiFloat8 scale 说明

Document Link(文档链接)

https://gitcode.com/cann/ops-transformer/blob/master/attention/indexer_quant_cache/README.md

Issues Section(问题文档片段)

README 将 quant_mode=1(Normal)描述为“动态逐块量化”,并将 cache_scale 统一描述为原地更新;HiFloat8 一节没有说明 cache_scale 不会写回。

Existing Issues(存在的问题)

attention/indexer_quant_cache/README.md 将 quant_mode=1 Normal 描述为“动态逐块量化”,但实际 tiling 和 kernel 对每个 token 的整行 d 元素只计算并存储一个 float32 scale。README 还将 cache_scale 统一描述为原地更新,并未说明 HiFloat8 例外;实际 HiFloat8 路径只按 x_scale 把输入转换为 hifloat8,single-row 和 multi-row kernel 都跳过 cache_scale 的 CopyOut,因此输入 cache_scale 保持不变。

预期行为

README 应准确说明 Normal 模式每行使用一个 scale,并说明 HiFloat8 模式下 cache_scale 保持输入值不变。

实际行为

Normal 模式的 scale 按行计算;HiFloat8 模式只按 x_scale 转换 cache,不计算或写回 cache_scale。

影响

按 README 设计 Normal 的 cache_scale shape 或按块解释 scale,会错误估计 scale 数量;按 HiFloat8 文档读取“更新后的 scale”则会误以为该输入被写回。

修复

明确 Normal 为每行一个 scale,并说明 HiFloat8 仅按 x_scale 转换 cache、不计算或写回 cache_scale,同时更新参数表中的输入/输出说明。

验证

  • README 补丁在目标仓库本地 origin/master 上通过 git apply --check,仅修改 attention/indexer_quant_cache/README.md。
  • 目标仓库 pre-commit 4.6.2 对该 README 的限定文件检查通过,OAT 合规扫描覆盖 1 个文件;检查后没有额外差异。

关联 PR: https://gitcode.com/cann/ops-transformer/merge_requests/14356

likedislike
KaranocaVeKaranocaVe
26 days ago Associated pull request
周云飞
周云飞Collaborators
26 days ago Comments:

/assign @KaranocaVe

likedislike
CANN-robotCANN-robotCollaborators
26 days ago Assign KaranocaVe as responsible person
周云飞
周云飞Collaborators
26 days ago Comments:

感谢您详细说明量化粒度和 cache_scale 写回行为的差异,并提供文档补丁的检查结果。

按您描述的实现行为,README 需要区分以下两点:

  • Normal(quant_mode=1)的量化粒度:每个 token 的整行 d 个元素共用一个 float32 scale,而不是沿 d 维分成多个块、每块使用一个 scale。“动态逐块量化”的表述容易让使用者错误估计 scale 数量。
  • HiFloat8 的写回行为:仅按 x_scale 将输入转换为 HiFloat8 并写入 cache,不计算或写回 cache_scale;cache_scale 保持输入值不变,不能将其理解为本次转换产生的 scale。

建议将这两点同步到模式说明、HiFloat8 小节和参数表中,尤其应为 cache_scale 的“原地更新”说明补充适用条件,避免把其他量化路径的行为套用到 HiFloat8。这个调整方向聚焦文档与实现的一致性,不涉及改变量化计算或接口行为;具体措辞仍需与对应的 tiling、单行和多行内核分支逐项确认。

likedislike
KaranocaVeKaranocaVe
26 days ago Modify description of issue
KaranocaVe
KaranocaVe
26 days ago Comments:

已逐项对照 tiling 和两类 kernel:Normal(quant_mode=1)的 tiling 将 scaleCol_ 设为 1,kernel 对每行完整的 d 维求最大值并写入一个 scale。single-row 和 multi-row kernel 的 HiFloat8 分支都调用 VFProcessHifp8Quant,并跳过 cache_scale 的 CopyOut。README 已据此区分 Normal 的逐行 scale 和 HiFloat8 不写回 cache_scale 的行为。

likedislike
CANN-robotCANN-robotCollaborators
26 days ago Close issue
CANN-robotCANN-robotCollaborators
26 days ago Added label: resolved
周云飞
周云飞Collaborators
6 days ago Comments:

已通过 PR #14356 修正 IndexerQuantCache README:

  • 明确 Normal 模式按每个 token 的整行动态量化,每行计算一个 float32 scale;MX-FP8 和 MX-FP4 按每 32 个元素分组。
  • 明确 HiFloat8 模式将 x × x_scale 转换为 hifloat8,不计算或写回 cache_scale,并同步修正参数表。
  • README 补丁通过 git apply --check 和限定文件的 pre-commit 检查。

关联 PR:PR #14356

likedislike