Closed
[Documentation|文档反馈]: aclnnCompressorGrad 资料未说明 161002 与 561002 的校验分层,两条描述对同一 shape 错误都成立 #6864
liuhanwen8Add on  18 days agoClosed at  11 days ago
liuhanwen8
liuhanwen8
18 days ago Create

[Documentation|文档反馈]: aclnnCompressorGrad 资料未说明 161002 与 561002 的校验分层,两条描述对同一 shape 错误都成立

现象

资料错误码表里两条描述对同一类非法入参同时成立:

  • 161002:输入参数的 shape(维度/尺寸)、dtype(数据类型)不在接口支持的范围内。
  • 561002:tiling 发生异常,入参的 dtype 类型或者 shape 错误。

实测同一接口两类"只改一个维度"的非法输入分别落到这两个码:
x 的 dtype 改成 fp32 → 161002;x 的 rank 改成 1 → 561002。
资料全文没有任何一句说明两者的校验分层或优先级,使用者无法预判会拿到哪个码。

期望

在「约束说明」或错误码表后补一句分层说明,例如:"aclnn 参数校验层(dtype/必选空指针等)
返回 161001/161002;tiling 阶段校验(rank、维度、一致性等)失败返回 561002",
或明确"shape/rank/dtype 一律返回 161002"。

环境

  • 资料:cann/ops-transformer attention/compressor_grad/docs/aclnnCompressorGrad.md @ 45a09b29
  • 复核平台:Ascend 950PR(Ascend950PR_9579)、CANN 9.2.0-beta.2(用于确认实测返回码)

复现步骤

  1. 取资料仓:git clone https://gitcode.com/cann/ops-transformer,进入仓根。
  2. 运行下方断言脚本:python3 doc_repro_p2_3.py --repo-dir .
  3. 脚本从 <tr> 逐行解析错误码表(无 rowspan),检查两条描述是否都覆盖 shape+dtype、全文是否提到分层。
  4. 退出码 1 且输出含 [DEFECT] 即缺陷成立。

复现脚本

#!/usr/bin/env python3
# 采集不给资料打补丁前,可用本脚本直接判定;退出码 1 且含 [DEFECT] = 缺陷成立
import os, re, sys, argparse

REL = "attention/compressor_grad/docs/aclnnCompressorGrad.md"

def find_doc(explicit=""):
    for c in ([os.path.join(explicit, REL)] if explicit else []) + [REL]:
        if os.path.isfile(c):
            return c
    return None

ap = argparse.ArgumentParser()
ap.add_argument("--repo-dir", default="")
p = find_doc(ap.parse_args().repo_dir)
if not p:
    print("[SKIP] 未找到 %s" % REL); sys.exit(2)
text = open(p, encoding="utf-8").read()
rows = []
for tr in re.findall(r"<tr>(.*?)</tr>", text, re.S):
    cs = [re.sub(r"<[^>]+>", "", c).strip()
          for c in re.findall(r"<td[^>]*>(.*?)</td>", tr, re.S)]
    if len(cs) >= 3 and re.fullmatch(r"\d{6}", cs[1] or ""):
        rows.append((cs[1], cs[2]))
d = dict(rows)
c161, c561 = d.get("161002", ""), d.get("561002", "")
if not c161 or not c561:
    print("[SKIP] 错误码表缺 161002 或 561002"); sys.exit(2)
print("161002:", c161)
print("561002:", c561)
cover161 = ("shape" in c161) and ("dtype" in c161)
cover561 = ("shape" in c561) and ("dtype" in c561)
layer = re.search(r"(aclnn\s*层|tiling\s*层|参数校验层|优先返回|先返回|校验顺序|由\s*aclnn|由\s*tiling)", text)
print("覆盖重叠:", cover161, cover561, "| 分层说明:", layer.group(0) if layer else "无")
if cover161 and cover561 and not layer:
    print("[DEFECT] 两条描述对同一 shape/dtype 错误都成立,且资料未说明校验分层或优先级")
    sys.exit(1)
print("[OK] 描述不重叠或已有分层说明")
sys.exit(0)

实测输出:

161002: 输入参数的shape(维度/尺寸)、dtype(数据类型)不在接口支持的范围内。
561002: tiling发生异常,入参的dtype类型或者shape错误。
覆盖重叠: True True | 分层说明: 无
[DEFECT] 两条描述对同一 shape/dtype 错误都成立,且资料未说明校验分层或优先级

影响

  • 使用者按资料写错误处理分支(161002 → 提示改 shape;561002 → 当内部故障重试/上报)时,
    rank 越界这类纯参数错误会落进"内部故障"分支,被误判成算子 bug。
  • 同一份资料里两条描述的适用范围重叠,评审时也无法据此判断实现是否符合契约。

建议

在错误码表下方补一段分层说明(哪一层返回哪个码),或把 561002 的描述收窄为
"仅 tiling 内部计算失败(如 workspace/核数不足)",把 rank/维度类校验明确归到 161002。

附件信息:实测证据(哪类入参返回哪个码)见同接口的缺陷 issue,
本单只针对资料侧的描述重叠与分层缺失。

同族参考:#6833(QuantCompressor 23 类非法 shape/attr 返回 561002)与本单互补——
#6833 从实现侧说"码与资料不符",本单从资料侧说"两条描述重叠且没写分层",
建议一起看再决定改代码还是改资料。

likedislike
liuhanwen8liuhanwen8
18 days ago Added label: documentation
周云飞
周云飞Collaborators
18 days ago Comments:

感谢您提供文档片段和返回码对照。本单的核心是错误码说明能否指导使用者区分失败原因,而不只是两个错误码是否允许同时涉及 shape 或 dtype。

从您贴出的描述看,161002 和 561002 都涵盖 shape、dtype 错误,但没有说明各自在哪个阶段返回。结合您在 Ascend 950PR、CANN 9.2.0-beta.2 上报告的结果——x 改为 fp32 返回 161002,rank 改为 1 返回 561002——现有文字不足以解释这两种输入为何得到不同返回码。不过,这两项结果还不能证明所有 dtype 检查都在 aclnn 参数校验阶段完成,也不能证明所有 rank、维度检查都在 tiling 阶段完成。

一个可行的文档调整方向是在错误码表后说明:同类非法参数可能在不同阶段被检查,返回码取决于具体检查位置;再补充该接口已确认的检查项目及对应返回码。如果存在多个参数同时非法的情况,也应说明是否有稳定的校验顺序,避免把单项测试结果理解为固定优先级。

“补充分层说明”和“将 shape/rank/dtype 错误统一返回 161002”是两种不同的处理方式,后者涉及实现行为及现有错误处理逻辑的兼容性,不能仅靠修改文档达成。同样,在确认 tiling 的实际失败范围前,不宜把 561002 收窄为仅表示内部计算失败。就您报告的 rank 用例而言,也不宜仅凭 561002 将其判定为内部故障并直接重试。

目前仍需确认该接口各项检查到公开返回码的对应关系,才能确定准确的分层措辞;本单可以先聚焦文档说明不清的问题,是否统一实现侧返回码则需另行评估。

likedislike
周云飞
周云飞Collaborators
17 days ago Comments:

/assign @wangss21

likedislike
CANN-robotCANN-robotCollaborators
17 days ago Assign wangss21 as responsible person
CANN-robotCANN-robotCollaborators
11 days ago Close issue
CANN-robotCANN-robotCollaborators
11 days ago Added label: resolved
周云飞
周云飞Collaborators
6 days ago Comments:

处置结果

已在 aclnnCompressorGrad 文档补充校验分层。必选参数空指针和不支持的 dtype 分别在 ACLNN 参数校验阶段返回 161001 和 161002,rank、shape、一致性或属性约束在 tiling 阶段校验失败时返回 561002。

变更已合入 master,详见 PR #15124。

likedislike