Closed
[Documentation|文档反馈]: [aclnnSquare] 头文件 out 出参 dtype 注释多列 DOUBLE、漏列 INT64,与资料表/实现三方不一致 #4363
liuhanwen8Add on  18 days agoClosed at  18 hours ago
liuhanwen8
liuhanwen8
18 days ago Create

环境

cann/ops-math master @ 365f17f0;math/square/op_api/aclnn_square.h、aclnn_square.cpp、
docs/aclnnSquare.md;CANN 9.2.0 / Atlas A2(Ascend910B3)。

问题

aclnnSquare 的 out 出参 dtype 描述三方不一致:头文件注释比资料表与实现多列 DOUBLE、漏列
INT64,且 BF16 与资料表 BFLOAT16 两种写法并存。

来源 位置 out 支持的 dtype DOUBLE INT64
头文件注释 aclnn_square.h:40 FLOAT、FLOAT16、DOUBLE、INT32、BF16 多列 漏列
资料表 aclnnSquare.md:95 FLOAT、FLOAT16、BFLOAT16、INT32、INT64 无 有
实现 aclnn_square.cpp:30-31 DT_INT64、DT_FLOAT、DT_FLOAT16、DT_INT32、DT_BF16 无 有

实现的支持列表没有 DT_DOUBLE,而 CheckDtypeValid 用 OP_CHECK_DTYPE_NOT_SUPPORT
(aclnn_square.cpp:71)以该列表为准 —— 按头文件注释传 DOUBLE 会在第一段被拒。
资料 aclnnSquare.md:87 对 out 另写「shape和type需与self一致」,self 的 dtype 表(:85)
同样不含 DOUBLE,即 DOUBLE 在资料与实现两侧都无处落地。

复现步骤

保存下方脚本为 repro_doc_square.py,在 cann/ops-math 仓根执行
python3 repro_doc_square.py --repo-root .;退出码 1 且输出含 [DEFECT] 即缺陷成立。
脚本做同源断言:解析头文件 @param [in] out: 的 dtype 行、资料表 out 行数据类型单元格、
实现支持列表,比对三方是否都含 DOUBLE。退出码 0/1/2 = 符合预期/缺陷成立/无法判定。

实测输出(365f17f0);把 aclnn_square.h:40 的 DOUBLE 删掉后同脚本返回 [OK] 三方一致、
退出码 0,说明断言有负向对照:

aclnn_square.h:40  out 含 DOUBLE : True
aclnnSquare.md:95  out 表        : FLOAT、FLOAT16、BFLOAT16、INT32、INT64  (含 DOUBLE: False)
aclnn_square.cpp:31  支持列表    : DT_INT64, DT_FLOAT, ...  (含 DT_DOUBLE: False)
[DEFECT] 头文件 out 注释列出 DOUBLE,资料表与实现支持列表均无

复现脚本

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import argparse, os, sys

H = "math/square/op_api/aclnn_square.h"
C = "math/square/op_api/aclnn_square.cpp"
M = "math/square/docs/aclnnSquare.md"

def read(root, rel):
    p = os.path.join(root, rel)
    return open(p, encoding="utf-8", errors="replace").read() if os.path.isfile(p) else None

def find(text, anchor, needle, reach=4):
    """(anchor 命中行起 reach 行内) 首个含 needle 的行 -> (该行, 1-based 行号)。"""
    lines = text.splitlines()
    for i, ln in enumerate(lines):
        if anchor in ln:
            for off in range(reach):
                if i + off < len(lines) and needle in lines[i + off]:
                    return lines[i + off], i + off + 1
    return None, -1

def doc_out_cell(text):
    """资料表格里 out 行的「数据类型」单元格 -> (值, 行号)。"""
    cells = [(ln.strip()[4:-5].strip(), i + 1)
             for i, ln in enumerate(text.splitlines())
             if ln.strip().startswith("<td>") and ln.strip().endswith("</td>")]
    for k, (v, _) in enumerate(cells):
        if v.startswith("out(aclTensor*)") and k + 4 < len(cells):
            return cells[k + 4][0], cells[k + 4][1]
    return None, -1

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--repo-root", required=True)
    root = ap.parse_args().repo_root
    h, d, c = read(root, H), read(root, M), read(root, C)
    miss = [n for n, t in ((H, h), (M, d), (C, c)) if t is None]
    if miss:
        print("[UNKNOWN] 缺少文件:%s" % ", ".join(miss))
        return 2

    hl, hno = find(h, "@param [in] out:", "数据类型支持")
    dc, dno = doc_out_cell(d)
    il, ino = find(c, "ASCEND910D_DTYPE_DTYPE_SUPPORT_LIST", "DT_FLOAT")
    if hl is None or dc is None or il is None:
        print("[UNKNOWN] 定位失败")
        return 2

    hd, dd, idd = "DOUBLE" in hl, "DOUBLE" in dc, "DT_DOUBLE" in il
    print("=== 三方对账 ===")
    print("  头文件 %s:%d  out 含 DOUBLE : %s" % (H, hno, hd))
    print("  资料   %s:%d  out 表     : %s  (含 DOUBLE: %s)" % (M, dno, dc, dd))
    print("  实现   %s:%d  支持列表  : %s  (含 DT_DOUBLE: %s)"
          % (C, ino, il.strip()[:70], idd))
    if hd and not dd and not idd:
        print("\n[DEFECT] 头文件 out 注释列出 DOUBLE,资料表与实现支持列表均无")
        print("[DEFECT] 按头文件写的 DOUBLE 入参会被实现以 161002 拒绝")
        return 1
    if hd == dd == idd:
        print("\n[OK] 三方一致(DOUBLE 同为 %s),无缺陷" % hd)
        return 0
    print("\n[OK] 未命中目标形态,需人工判断")
    return 0

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

期望结果

以资料表与实现为准,aclnn_square.h:40 应改为 FLOAT、FLOAT16、BFLOAT16、INT32、INT64,
并把 BF16 统一为 BFLOAT16。

实际结果

aclnn_square.h:40 写 FLOAT、FLOAT16、DOUBLE、INT32、BF16 —— 多列 DOUBLE、漏列 INT64、
BF16 与资料表 BFLOAT16 不统一。按该注释传 DOUBLE 会被 OP_CHECK_DTYPE_NOT_SUPPORT
(aclnn_square.cpp:71)拒绝,与注释宣称的支持面相反。

likedislike
liuhanwen8liuhanwen8
18 days ago Added label: documentation
陈思
陈思Collaborators
17 days ago Comments:

您好,感谢反馈!核对 cann/ops-math 提交 212ce9d5460b1be26cfbee481aff1acbf5cc5c62 后,确认头文件 out 注释多列了 DOUBLE、漏列了 INT64:实现的类型列表是 FLOAT、FLOAT16、BFLOAT16、INT32、INT64,并要求 self 与 out 类型一致;文档参数表也与该列表一致。头文件注释、类型校验、参数表

可行的修订是将 out 注释更正为“FLOAT、FLOAT16、BFLOAT16、INT32、INT64,类型与 self 一致”,并将 self 与 out 注释中的 BF16 写法统一为 BFLOAT16。当前接口还受 IsRegBase() 平台条件限制,因此这项注释修订需要与实际产品支持范围区分;您使用的 A2 平台会先经过平台校验,不能据此次类型文案对齐认定 A2 调用已经恢复可用。我们会继续跟踪头文件说明与接口约束的对齐。平台与类型校验顺序

likedislike
陈思陈思Collaborators
17 days ago Assign chen_0715 as responsible person
陈思陈思Collaborators
17 days ago Added label: pending-confirmation
陈思陈思Collaborators
15 days ago Removed label: pending-confirmation
Wwangbo
14 days ago Associated pull request
wangbo
14 days ago Comments:

已提交修复:aclnn_square.h 的 out 出参 dtype 注释按期望结果改为 FLOAT、FLOAT16、BFLOAT16、INT32、INT64:
https://gitcode.com/cann/ops-math/merge_requests/7049

likedislike
CchenyifengCollaborators
14 days ago Assign wang_bo as responsible person
chenyifengCollaborators
18 hours ago Comments:

整改已合入,issue将关闭,后续有问题欢迎继续提issue。

likedislike
CchenyifengCollaborators
18 hours ago changed custom state from 进行中 to 已解决
CchenyifengCollaborators
18 hours ago Close issue