Closed
[Documentation|文档反馈]: aclnnRmsNorm 资料 gamma 约束「n < x_shape.dims()」与「维度 1-8」互斥:rank-1 输入无合法 gamma #7432
liuhanwen8Add on  26 days agoClosed at  6 days ago
liuhanwen8
liuhanwen8
26 days ago Create

Document Link(文档链接)

https://gitcode.com/cann/ops-nn/blob/master/norm/rms_norm/docs/aclnnRmsNorm.md

现象

资料对同一条「归一化轴」约束给了两个互斥的口径:

  • 参数表 x 行的「维度(shape)」列(L89):1-8 —— 即 rank 1 的 x 合法;
  • 参数表 gamma 行的「使用说明」列(L96):「shape需要满足gamma_shape = x_shape[n:], n < x_shape.dims()」。

当 rank(x) = 1 时,切片起点 n 只能取 0(x[0:] 才是 x 本身),而 n < x_shape.dims() = 1
要求 n = 0 必须 小于 0,无解。也就是说:按资料,rank-1 的 x 找不到任何合法 gamma,
与「维度 1-8」自相矛盾。

实测方向(Atlas 910B2 / CANN 9.2.0)实现按 n <= dims() 放行,两种「按资料无解 / 无定义」的形态都返回成功:

x gamma n 按资料 两段实测返回 结果
fp16[8,128] fp32[8,128] 0 n < 2 不成立 → 应拒绝 0 / 0 与 fp64 标杆一致(`max
fp16[128] fp32[128] 0 n < 1 不成立 → 应拒绝 0 / 0 与 fp64 标杆一致

期望

把该约束改成可执行口径,二选一:

  1. 若实现要支持 gamma 覆盖全部维度(含 rank-1 的 x),资料改为 n <= x_shape.dims(),并补一句「gamma 与 x 同 shape 时等价于对全部轴归一化」;
  2. 若实现不打算支持 n = 0,资料须把 x 的维度列从 1-8 改为 2-8(或补「rank-1 输入不支持」),并同步头文件注释与调用示例。

Issues Section(问题文档片段)

L89:      <td>1-8</td>                                        ← x 行「维度(shape)」
L96:      <td><ul><li>不支持空Tensor。</li><li>shape需要满足gamma_shape = x_shape[n:], n < x_shape.dims()。</li></ul></td>

「约束说明」(L190 起)逐条列了平台差异、边界值、dtype 组合与确定性,没有任何「rank-1 输入」或
「gamma 与 x 同 rank」的说明。

环境

  • 硬件:Atlas A2 训练系列(Ascend 910B2),npu-smi 26.1.1;CANN 9.2.0,Linux aarch64,g++ 11.4.0
  • 仓库与提交:cann/ops-nn master 711a4f5dda0d4f55d48eabdb3c17e2f6384fba42(2026-10-26)

复现步骤

  1. 保存下方脚本为 check_doc_claim.py
  2. python3 check_doc_claim.py <ops-nn>/norm/rms_norm/docs/aclnnRmsNorm.md
  3. 退出码 1 且输出含两条 [DEFECT] 即为「资料自相矛盾」成立(0 = 资料自洽、2 = 锚点失效)
  4. 上板复核(可选):x=fp16[8,128]/gamma=fp32[8,128] 与 x=fp16[128]/gamma=fp32[128] 两例两段均返回 0

复现脚本

#!/usr/bin/env python3
"""aclnnRmsNorm 资料自检:gamma 约束「n < x_shape.dims()」与「x 维度 1-8」互斥。"""
import re
import sys

path = sys.argv[1] if len(sys.argv) > 1 else "docs/aclnnRmsNorm.md"
txt = open(path, encoding="utf-8", errors="replace").read()

# 按 <tr> 切行,避免误命中 gamma / rstd 的同名列
rows = re.findall(r"<tr>(.*?)</tr>", txt, re.S)
x_rank = gamma_row = None
for r in rows:
    if "x(aclTensor*)" in r:
        cells = re.findall(r"<td[^>]*>(.*?)</td>", r, re.S)
        x_rank = cells[6].strip() if len(cells) > 6 else None
    if "gamma(aclTensor*)" in r:
        gamma_row = r

if x_rank is None or gamma_row is None:
    print("[UNDECIDED] 找不到 x / gamma 参数行")
    sys.exit(2)
print("[锚点] x 维度列 = %r" % x_rank)
m = re.search(r"n\s*<\s*x_shape\.dims\(\)", gamma_row)
print("[锚点] gamma 使用说明含 'n < x_shape.dims()' = %s" % bool(m))

if x_rank == "1-8" and m:
    print("[DEFECT] rank(x)=1 时 gamma 只能取 n=0,违反 n < x_shape.dims();"
          "按资料 rank-1 输入没有任何合法 gamma")
    sys.exit(1)
print("[OK] 资料自洽")
sys.exit(0)

实测输出:退出码 1,stdout 打印两条 [DEFECT](原文见下一节)。

实测输出

[锚点] x 维度列 = '1-8'
[锚点] gamma 使用说明含 'n < x_shape.dims()' = True
[DEFECT] rank(x)=1 时 gamma 只能取 n=0,违反 n < x_shape.dims();按资料 rank-1 输入没有任何合法 gamma

影响

调用方按资料写「rank-1 输入不支持」的分支(或在 rank-1 时自行拒绝)会与实现行为相反;反过来,按实现写
gamma = x 全维归一化的代码在资料里找不到依据,遇到评审/移植时无法引用条款。这类「资料给了无解约束」
还会让测试设计把 rank-1 误判成负向用例(本轮 2000 条矩阵里 rank-1 就被同时写成正向与负向两套)。

建议

按「期望」二选一改写 L96,并在「约束说明」补一条 n 的取值域(0 <= n < dims() 或 0 <= n <= dims());
若选 n <= dims(),同步补一句 gamma 与 x 同 rank 时的语义与 rstdOut 形状(此时行数为 1)。

查重

  • cann/ops-nn#7362(open):aclnnGemmaRmsNorm 文档「支持空Tensor」未限定归约轴 —— 同一句 gamma_shape = x_shape[n:]
    条款、不同接口的问题,接口不同不合并;
  • cann/ops-nn#7351 / #7317(open):aclnnGroupNormSilu / V2 参数表与约束说明矛盾 —— 同类「资料自相矛盾」先例;
  • cann/ops-nn#7407(open):aclnnInplaceAddRmsNorm 错误码表未声明 rank/shape 违约返回码 —— 同族资料缺口;
  • 未检索到 aclnnRmsNorm 自身关于 gamma rank 取值域的 issue。
likedislike
liuhanwen8liuhanwen8
26 days ago Added label: documentation
yuning_chen
yuning_chenCollaborators
26 days ago Comments:

初步分析

感谢反馈。

现象理解:
aclnnRmsNorm 资料写 x 维度 1-8,同时又要求 gamma 满足 n < x_shape.dims();rank-1 时无合法 gamma,与实测同 rank gamma 可跑通冲突。

当前判断:初步判断,待复现确认。
偏文档自相矛盾。实现更可能允许 gamma 与 x 同 rank(n=0),资料「n <」过严。

涉及范围:
norm/rms_norm/docs/aclnnRmsNorm.md 的 x/gamma 约束表述。

下一步:
统一为「n ≤ dims 且尾维对齐」或明确禁止 rank-1;与实现及示例对齐后改文档。

likedislike
yuning_chenyuning_chenCollaborators
25 days ago Assign east_yang as responsible person
yuning_chenyuning_chenCollaborators
25 days ago Removed responsible person east_yang
yuning_chenyuning_chenCollaborators
25 days ago Assign liujie12345678 as responsible person
yuning_chen
yuning_chenCollaborators
25 days ago Comments:

您好,问题已收到,当前 @liujie12345678 正在处理中。

likedislike
liujie12345678liujie12345678Collaborators
24 days ago Assign gitee-duhuiping as responsible person
liujie12345678liujie12345678Collaborators
24 days ago Removed responsible person liujie12345678
gitee-duhuipinggitee-duhuipingCollaborators
18 days ago Associated pull request
liuyun_njliuyun_njCollaborators
11 days ago Associated pull request
gitee-duhuipinggitee-duhuipingCollaborators
6 days ago Deleted associated pull request: fix issue,add md doc,add check shape
gitee-duhuipinggitee-duhuipingCollaborators
6 days ago Assign liuyun_nj as responsible person
gitee-duhuipinggitee-duhuipingCollaborators
6 days ago changed custom state from 进行中 to 已完成
gitee-duhuipinggitee-duhuipingCollaborators
6 days ago Close issue
CANN-robotCANN-robotCollaborators
6 days ago Added label: resolved
chenjiayi_chenjiayi_Collaborators
3 days ago Assign chenjiayi_ as responsible person
chenjiayi_
chenjiayi_Collaborators
3 days ago Comments:

补充说明本问题的后续处理:

已修复并随关联 PR 合入。

处理结果:

  • !13602:modified md files
  • !14221:fix issue,add md doc,add check shape

验证:

  • 关联 PR(2026-11-05)已合入,变更可从 PR 记录追溯。
  • 本次以 PR 记录与 issue 讨论核对为主,未重新执行复现或真机验证。

说明:合入分支与版本以 PR 记录为准;如仍有问题,请重新提 issue 并附版本、shape 与日志。

如果还有后续需要,请重新提 issue。

likedislike
chenjiayi_chenjiayi_Collaborators
1 day ago Removed responsible person chenjiayi_