Closed
[Documentation|文档反馈]: aclnnSoftMarginLoss 资料 out 行维度列写 1-8,与同一行「out 为 scalar」互相矛盾 #7565
liuhanwen8Add on  24 days agoClosed at  9 days ago
liuhanwen8
liuhanwen8
24 days ago Create

现象

loss/soft_margin_loss/docs/aclnnSoftMarginLoss.md 参数表里 out 这一行的两列互相矛盾:

  • 第 128 行「使用说明」:若reduction取值为'none',则shape需要与self和target进行broadcast后的shape一致,否则out为scalar。
  • 第 131 行「维度(shape)」:1-8

同一行既说 reduction≠none 时 out 是 scalar(0 维),又把维度写成 1-8(下界 1,排除 0 维)。同仓 experimental 副本描述相反且是对的,可作交叉证据(第 51 行):reduction=0 时 shape 与 self 相同;reduction=1 或 2 时为标量(0 维 tensor);第 89 行还写明「不是 shape=[1],而是 dimNum=0 的标量 tensor」。

实测(Atlas A2 910B2 / CANN 9.2.0,aclnn 原生 C 两段式直调):reduction=1/2 时若 out 的 rank≥1,第一段返回 161002;只有 0 维 out 通过。即 0 维是硬约束,1-8 这一列写错。

期望

out 行维度列改为 reduction=none 时为 broadcast 后的 shape(rank 1-8);reduction≠none 时为 0 维,与同一行使用说明及 experimental 副本一致。

环境

  • 仓:cann/ops-nn,git fetch 后 master daf29d22(工作副本 a74516ec)
  • 资料:loss/soft_margin_loss/docs/aclnnSoftMarginLoss.md(sha256 前 16 位 28b24312d75aeffb)
  • 平台:Atlas A2 训练系列(910B2);CANN 9.2.0

复现步骤

  1. 把下面的脚本存为 check_doc.py
  2. 在 ops-nn 仓外执行 python3 check_doc.py --repo-root <ops-nn 仓根>
  3. 观察输出:打印两个单元格原文与 [DEFECT],退出码 1

复现脚本

import os
import re
import sys

REL = "loss/soft_margin_loss/docs/aclnnSoftMarginLoss.md"


def find_root():
    cands = [os.environ.get("OPS_NN_ROOT", "")]
    for a, v in enumerate(sys.argv):
        if a and sys.argv[a - 1] == "--repo-root":
            cands.append(v)
    for base in (os.path.dirname(os.path.abspath(__file__)), os.getcwd()):
        p = base
        for _ in range(8):
            cands += [p, os.path.join(p, "ops-nn")]
            p = os.path.dirname(p) or p
    return next((c for c in cands if c and os.path.isfile(os.path.join(c, REL))), "")


def out_row(doc):
    lines = open(doc, encoding="utf-8").read().splitlines()
    for i, ln in enumerate(lines):
        if "out(aclTensor*)" in ln or "out(aclTensor*)" in ln:
            cells = re.findall(r"<td[^>]*>(.*?)</td>", "".join(lines[i:i + 12]), re.S)
            if len(cells) < 7:
                return None
            clean = [re.sub(r"<[^>]+>", "", c).strip() for c in cells]
            return clean[6], clean[3], i + 1     # 6=维度(shape) 3=使用说明
    return None


def main():
    root = find_root()
    if not root:
        print("[UNDECIDABLE] 找不到 %s(用 --repo-root 指定 ops-nn 仓根)" % REL)
        return 2
    doc = os.path.join(root, REL)
    row = out_row(doc)
    if not row:
        print("[UNDECIDABLE] %s 定位不到 out(aclTensor*)行" % doc)
        return 2
    shape_cell, desc_cell, lineno = row
    print("文档:%s(out 行起始第 %d 行)" % (doc, lineno))
    print("  维度(shape)列 = %r" % shape_cell)
    print("  使用说明列   = %r..." % desc_cell[:90])
    exp = next((c for c in (os.path.join(root, "experimental", REL),
                            os.path.join(os.path.dirname(root), "experimental", REL))
                if os.path.isfile(c)), "")
    if exp:
        for ln in open(exp, encoding="utf-8").read().splitlines():
            t = ln.strip()
            if t.startswith("| out |") or "out 的 shape 须与 reduction 模式匹配" in t:
                print("  experimental 副本:%s" % t[:110])
    scalar = bool(re.search(r"scalar|标量|0\s*维", desc_cell, re.I))
    rng = re.match(r"^\s*(\d+)\s*[-~]\s*(\d+)\s*$", shape_cell)
    lower = int(rng.group(1)) if rng else None
    if scalar and lower is not None and lower >= 1:
        print("[DEFECT] 同一行自相矛盾:使用说明说 reduction≠none 时 out 为标量(0 维),"
              "维度列却给 %s(下界 %d)" % (shape_cell, lower))
        print("        实测 reduction≠none 且 out 非 0 维时第一段返回 161002,0 维是硬约束")
        return 1
    print("[OK] 维度列与使用说明一致" if scalar else "[UNDECIDABLE] 维度列无法判读")
    return 0 if scalar else 2


if __name__ == "__main__":
    raise SystemExit(main())

实测输出(退出码 1):

文档:<本地路径>/ops_nn_src/loss/soft_margin_loss/docs/aclnnSoftMarginLoss.md(out 行起始第 125 行)
  维度(shape)列 = '1-8'
  使用说明列   = "若reduction取值为'none',则shape需要与self和target进行broadcast后的shape一致,否则out为scalar。"...
  experimental 副本:| out | 输出 | 输出张量。数据类型与 self 相同。reduction=0 时 shape 与 self 相同;reduction=1 或 2 时为标量(0 维 tensor)。 |
[DEFECT] 同一行自相矛盾:使用说明说 reduction≠none 时 out 为标量(0 维),维度列却给 1-8(下界 1)
        实测 reduction≠none 且 out 非 0 维时第一段返回 161002,0 维是硬约束

影响

按 1-8 设计用例或写调用代码时,out 会造出 [1]、[2,4] 这类 rank≥1 的张量,第一段直接返回 161002;同一份资料两列结论相反,用例设计与资料评审会各取一半,回归里也会出现「文档说可以、实测拒绝」的争议。

建议

out 行维度列改为 reduction=none 时为 broadcast 后的 shape(rank 1-8);reduction≠none 时为 0 维,并把 experimental 副本的措辞(「不是 shape=[1],而是 dimNum=0 的标量 tensor」)同步进主资料。

与已有 issue 的差异:#7358 已就同一节提过「reduction=mean/sum 时 out 应为 0 维标量」并已关闭,但当前主资料该行维度列仍是 1-8,属修复残留,故另开一条并引用 #7358;#7364 是 950 与 910 的 inf 传播公式差异,与本单无关。

likedislike
liuhanwen8liuhanwen8
24 days ago Added label: documentation
yuning_chen
yuning_chenCollaborators
24 days ago Comments:

初步分析

感谢反馈。

现象理解:
SoftMarginLoss 资料 out 行既写 scalar 又写维度 1-8,互相矛盾;实测 reduction≠none 要求 0 维。

当前判断:初步判断,待复现确认。
偏文档维度列错误,experimental 副本描述正确。

涉及范围:
docs/aclnnSoftMarginLoss.md out 行。

下一步:
维度列改为含 0 维/标量表述,与使用说明及实现一致。

likedislike
yuning_chenyuning_chenCollaborators
24 days ago Assign ji-songyuan as responsible person
yuning_chen
yuning_chenCollaborators
24 days ago Comments:

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

likedislike
KaranocaVeKaranocaVe
11 days ago Associated pull request
佐助大王佐助大王Collaborators
9 days ago changed custom state from 进行中 to 已完成
佐助大王佐助大王Collaborators
9 days ago Close issue
CANN-robotCANN-robotCollaborators
9 days ago Added label: resolved
chenjiayi_chenjiayi_Collaborators
2 days ago Assign chenjiayi_ as responsible person
chenjiayi_
chenjiayi_Collaborators
2 days ago Comments:

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

已修复并随关联 PR 合入。

处理结果:

  • !14164:[Docs] 补充 SoftMarginLoss 的 BFLOAT16 产品限制

验证:

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

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

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

likedislike
chenjiayi_chenjiayi_Collaborators
18 hours ago Removed responsible person chenjiayi_