Closed
[Documentation|文档反馈]: aclnnMaskedSoftmaxWithRelPosBias 错误码表把 attenMaskOptional 空指针列为 161001,与同文档「mask 可不存在」矛盾 #7390
liuhanwen8Add on  26 days agoClosed at  12 days ago
liuhanwen8
liuhanwen8
26 days ago Create

aclnnMaskedSoftmaxWithRelPosBias 资料:错误码表把 attenMaskOptional 空指针列为 161001,与同文档的「mask 可不存在」描述自相矛盾

现象

docs/aclnnMaskedSoftmaxWithRelPosBias.md 内部有两处相互矛盾的描述:

  1. 错误码表(## aclnnMaskedSoftmaxWithRelPosBiasGetWorkspaceSize → 返回值 → 表格):
    ACLNN_ERR_PARAM_NULLPTR / 161001 → 「传入的 x、attenMaskOptional、relativePosBias 或 out 是空指针。」
  2. 约束说明 → UB 空间公式:
    • 「对于 attenMaskOptional 存在的情况:…」
    • 「对于 attenMaskOptional 不存在的情况:…」

第 2 处明确给出了「mask 不存在」时的计算规格,说明该参数可以为 nullptr;
第 1 处却把「attenMaskOptional 是空指针」列为必须报 161001 的错误。
同文件的参数表 使用说明 列也写着「attenMaskOptional(非空时)…」,同样表示可空。

上板实测(Ascend 910B2 / CANN 9.2.0):把 attenMaskOptional 传 nullptr,两段接口都返回 0,
且输出与「mask 全 0」的等价输入逐位相同 —— 实现按可空处理,与第 2 处一致、与第 1 处冲突。

期望

错误码表 161001 的描述里去掉 attenMaskOptional(改成「传入的 x、relativePosBias 或 out 是空指针」),
或在参数表明确写「attenMaskOptional 允许传 nullptr,传 nullptr 时按无 mask 计算」。
现有写法会让调用方误以为 mask 必填,也让「mask 为空指针返回 161001」这条验收用例无法通过。

环境

  • 硬件:Ascend 910B2(Atlas A2,8 卡),npu-smi 26.1.1
  • CANN:CANN 9.2.0
  • 资料分支:cann/ops-nn master 14c91f2
  • 资料路径:norm/masked_softmax_with_rel_pos_bias/docs/aclnnMaskedSoftmaxWithRelPosBias.md

复现步骤

  1. 准备 cann/ops-nn 仓(或只准备该资料文件),记下仓根
  2. 把下面的脚本存成 doc_check.py
  3. 运行:python3 doc_check.py --repo-root <ops-nn 仓根>
  4. 脚本打印两处原文并给出 [DEFECT],退出码 1(资料自相矛盾)

复现脚本

import argparse, pathlib, sys

REL = "norm/masked_softmax_with_rel_pos_bias/docs/aclnnMaskedSoftmaxWithRelPosBias.md"

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--repo-root", required=True)
    a = ap.parse_args()
    doc = pathlib.Path(a.repo_root) / REL
    lines = doc.read_text(encoding="utf-8").splitlines()
    hit = [i for i, l in enumerate(lines) if "161001" in l]
    row = " ".join(x.strip() for x in lines[hit[0]:hit[0] + 3]) if hit else ""
    ub = [l.strip() for l in lines if "attenMaskOptional不存在" in l]
    print("[资料] 错误码 161001 行:", row)
    print("[资料] UB 公式缺省分支:", ub[0] if ub else "<缺失>")
    if "attenMaskOptional" in row and ub:
        print("[DEFECT] 同一份资料既说 mask 为空指针要报 161001,又给出 mask 不存在的计算公式")
        return 1
    print("[OK] 两处描述一致")
    return 0

if __name__ == "__main__":
    sys.exit(main())

实测输出:

[资料] 错误码 161001 行: <td>161001</td> <td>传入的x、attenMaskOptional、relativePosBias或out是空指针。</td> </tr>
[资料] UB 公式缺省分支: - 对于attenMaskOptional不存在的情况:
[DEFECT] 同一份资料既说 mask 为空指针要报 161001,又给出 mask 不存在的计算公式

影响

按资料做异常场景验收时,「mask 传空指针应返回 161001」这条用例必然与实现相反(实测返回 0);
集成方会据此把 mask 当成必填参数,丢掉「无 mask」这条更省的路径。

建议

  1. 修正错误码表 161001 的描述,去掉 attenMaskOptional;
  2. 在参数表 使用说明 补一句「attenMaskOptional 可传 nullptr,等价于无 mask」;
  3. 若维护者认为 mask 应必填,则应删除 UB 公式里的「不存在」分支并让实现返回 161001 —— 两者只能保留一个。
likedislike
liuhanwen8liuhanwen8
26 days ago Added label: documentation
yuning_chen
yuning_chenCollaborators
26 days ago Comments:

初步分析

感谢反馈,我们已开始核对这个问题。

现象理解:文档反馈;aclnnMaskedSoftmaxWithRelPosBias 错误码表把 attenMaskOptional 空指针列为 161001,与同文档「mask…。
当前判断:从描述看,这是资料/注释与实现口径不一致类文档反馈「aclnnMaskedSoftmaxWithRelPosBias 错误码表把 attenMaskOptional 空指针列为 161001,与同文档「mask…」。需要对照接口文档、头文件注释与实现/实测结果核对哪一侧需修正。以上为初步判断,待复现确认,不能当成已确认根因。
涉及范围:aclnnMaskedSoftmaxWithRelPosBias、aclnnMaskedSoftmaxWithRelPosBiasGetWorkspaceSize
下一步:我们会先核对文档声明与实现/测试结果是否一致,再决定改资料还是改代码。

likedislike
yuning_chenyuning_chenCollaborators
25 days ago Assign Dyrong as responsible person
yuning_chen
yuning_chenCollaborators
25 days ago Comments:

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

likedislike
yuning_chen
yuning_chenCollaborators
15 days ago Comments:

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

likedislike
aiteer
aiteerCollaborators
15 days ago Comments:

/assign

likedislike
CANN-robotCANN-robotCollaborators
15 days ago Assign aiteer as responsible person
yuning_chenyuning_chenCollaborators
13 days ago Removed responsible person Dyrong
aiteeraiteerCollaborators
13 days ago Associated pull request
aiteer
aiteerCollaborators
12 days ago Comments:

您好,感谢反馈,问题已核实,正在修复中。

likedislike
CANN-robotCANN-robotCollaborators
12 days ago Close issue
CANN-robotCANN-robotCollaborators
12 days ago changed custom state from 进行中 to 已完成
CANN-robotCANN-robotCollaborators
12 days ago Added label: resolved
chenjiayi_
chenjiayi_Collaborators
4 days ago Comments:

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

资料中的空指针描述与“mask 可空”已统一。

处理结果:

  • 参数表 attenMaskOptional 补充“允许传 nullptr,传 nullptr 时按无 mask 计算”。
  • 错误码表 161001 去掉 attenMaskOptional,改为“传入的 x、relativePosBias 或 out 是空指针(attenMaskOptional 为可选输入,允许为空指针)”。
  • PR:!13934。

验证:

  • master 文档 norm/masked_softmax_with_rel_pos_bias/docs/aclnnMaskedSoftmaxWithRelPosBias.md:98 与 :190 当前为上述口径。
  • 中英文资料同步修改。

说明:该修复随资料 PR 合入关闭。

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

MR 链接:https://gitcode.com/cann/ops-nn/pull/13934

likedislike