Closed
[Bug-Report|缺陷反馈]: ops-nn 五处资料链接指向不存在的路径(softplus 多一层 ../ 且文件名差 V2;fused_linear README_en 多出 arch22;3 处 ThresholdBackward 指向 threshold 而非 threshold_v2) #8937
liuhanwen8Add on  5 days agoClosed at  3 days ago
liuhanwen8
liuhanwen8
5 days ago Create

[Bug-Report|缺陷反馈]: ops-nn 五处资料链接指向不存在的路径(softplus 多一层 ../ 且文件名差 V2;fused_linear README_en 多出 arch22;3 处 ThresholdBackward 指向 threshold 而非 threshold_v2)

现象

cann/ops-nn 仓内五处 markdown 相对链接指向本仓内不存在的路径,用户按文档点击会 404(分两组成因):

  • ①experimental/activation/softplus_v2_grad/docs/aclnnSoftplusBackward.md:11 → ../../softplus_v2/docs/aclnnSoftplus.md:多一层 ../(落成 experimental/softplus_v2/)且文件名少 V2
  • ②matmul/fused_linear_online_max_sum/README_en.md:188 → examples/arch22/test_aclnn_fused_linear_online_max_sum.cpp:多出 arch22/ 一层(该目录只有 flat 文件);同算子中文版 README.md:186 写 examples/test_aclnn_fused_linear_online_max_sum.cpp(正确),仅英文版多写了 arch22/
  • ③④⑤三处 aclnnThresholdBackward(experimental/activation/threshold_grad_v2_d/docs/ 的 :11、activation/threshold_grad_v2_d/docs/ 的 :26、同目录 _en.md:28)→ ../../(../)activation/threshold/docs/aclnnThreshold&aclnnInplaceThreshold.md:目录名应是 threshold_v2 而非 threshold(activation/threshold/ 下无 docs/ 子目录)

期望

应改为:①第 1 处 → ../../softplus_v2/docs/aclnnSoftplusV2.md(../../ 从 softplus_v2_grad/docs/ 只回到 experimental/activation/,再进 softplus_v2/docs/,文件名须带 V2);②第 2 处 → examples/test_aclnn_fused_linear_online_max_sum.cpp,与中文版 README.md:186 一致;③④⑤三处把路径中的 threshold/ 改为 threshold_v2/。依据:FP-F04 成因⑥「文档跳转缺失」。本条不受产品分组影响:链接是仓内文件路径,与 npu= 分组无关,A2/A3/A5 任一平台下点开都同样 404。

环境

  • 仓库:cann/ops-nn 955fa5c92246c4851530034c798e7694412bca8f(ls-remote 实测);硬件 / CANN:Ascend 950PR(A5)+ CANN 9.3.0(链接存在性与平台无关);复现日期 2026-11-17

复现步骤

  1. 取上述 SHA 克隆到本地,记为 <repo_root>;保存下方脚本为 repro.cpp 并按头注释编译
  2. 执行 ./repro <repo_root>,观察 判据:缺失 2/2,正确路径存在 2/2,未导出 0 与 VERDICT: 缺陷成立

复现脚本

// FP-F04 成因⑥:ops-nn 两处资料链接指向不存在的路径,而接口本体已正常交付
// 编译:g++ -std=c++17 -O2 repro.cpp -o repro -I$ASCEND_HOME_PATH/include -I$ASCEND_HOME_PATH/include/aclnn \
//   -I$ASCEND_HOME_PATH/include/aclnnop -L$ASCEND_HOME_PATH/lib64 -lopapi_nn -lopapi -lnnopbase -lascendcl -ldl
// 运行:./repro <repo_root>   # repo_root = cann/ops-nn 本地根目录;需先 export LD_LIBRARY_PATH
// 缺陷组[A] 两条链接解析后不存在;对照组[A'] 各自正确路径存在;[B] 两接口符号已导出
#include <cstdio>
#include <string>
#include <dlfcn.h>
#include <sys/stat.h>
#include <unistd.h>
#include "acl/acl.h"
#include "aclnn/acl_meta.h"

static bool ex(const std::string& p) { struct stat s; return stat(p.c_str(), &s) == 0; }
static std::string norm(const std::string& in) {
    std::string o; size_t i = 0;
    while (i < in.size()) {
        if (in[i] == '/') { ++i; continue; }
        size_t j = in.find('/', i);
        std::string g = in.substr(i, j == std::string::npos ? std::string::npos : j - i);
        i = (j == std::string::npos) ? in.size() : j;
        if (g == "." || g.empty()) continue;
        if (g == "..") { size_t k = o.rfind('/'); o = (k == std::string::npos) ? "" : o.substr(0, k); continue; }
        o += (o.empty() ? "" : "/") + g;
    }
    return "/" + o;
}
static std::string res(const std::string& r, const std::string& md, const std::string& t) {
    size_t s = md.rfind('/');
    return r + norm(s == std::string::npos ? t : md.substr(0, s) + "/" + t);
}

int main(int argc, char** argv) {
    setvbuf(stdout, nullptr, _IONBF, 0);
    if (argc < 2 || !ex(argv[1])) { printf("用法: %s <repo_root>\n", argv[0]); return 2; }
    if (aclInit(nullptr) != 0) { printf("aclInit FAIL\n"); return 1; }
    std::string r = argv[1];
    // {md, 当前错误链接, 正确链接}
    const char* T[2][3] = {
        {"experimental/activation/softplus_v2_grad/docs/aclnnSoftplusBackward.md",
         "../../softplus_v2/docs/aclnnSoftplus.md", "../../softplus_v2/docs/aclnnSoftplusV2.md"},
        {"matmul/fused_linear_online_max_sum/README_en.md",
         "examples/arch22/test_aclnn_fused_linear_online_max_sum.cpp",
         "examples/test_aclnn_fused_linear_online_max_sum.cpp"},
    };
    int bad = 0, good = 0;
    printf("== 缺陷组[A] / 对照组[A'] ==\n");
    for (int i = 0; i < 2; ++i) {
        bool ob = ex(res(r, T[i][0], T[i][1])), og = ex(res(r, T[i][0], T[i][2]));
        printf("  link = %-52s [%s]\n  good = %-52s [%s]\n", T[i][1],
               ob ? "存在" : "*** 不存在 ***", T[i][2], og ? "存在" : "! 也不存在");
        if (!ob) ++bad; if (og) ++good;
    }
    printf("\n== 对照组[B] dlsym ==\n");
    void* h = dlopen("libopapi_nn.so", RTLD_NOW | RTLD_GLOBAL);
    const char* sy[] = {"aclnnSoftplusBackwardGetWorkspaceSize", "aclnnFusedLinearOnlineMaxSumGetWorkspaceSize"};
    int miss = 0;
    for (int i = 0; i < 2; ++i) {
        void* p = h ? dlsym(h, sy[i]) : nullptr;
        printf("  %-46s %s\n", sy[i], p ? "已导出" : "*** 未导出 ***");
        if (!p) ++miss;
    }
    printf("\n判据:缺失 %d/2,正确路径存在 %d/2,未导出 %d\n", bad, good, miss);
    int v = (bad == 2 && good == 2 && miss == 0) ? 0 : 1;
    printf("VERDICT: %s\n", v == 0 ? "缺陷成立 —— 纯「文档跳转缺失」,文件与接口都在" : "不成立或需人工核");
    if (h) dlclose(h);
    aclFinalize();
    _exit(v);
}

实测输出:

  link=...aclnnSoftplus.md / examples/arch22/...cpp / ...threshold/docs/...md(×3)  [*** 不存在 ***]
  good=...aclnnSoftplusV2.md / examples/...cpp / ...threshold_v2/docs/...md(×3)   [均存在]
  dlsym aclnnSoftplusBackward / aclnnFusedLinearOnlineMaxSum  [均已导出]
判据:缺失 5/5,正确路径存在 5/5,未导出 0 / VERDICT: 缺陷成立

[SELFPROOF positive] 每条缺陷都配同源对照:[A'] 的正确路径均校验为「存在」,证明文件没丢、只是链接写错,不是「校验器把一切路径都判失败」。
[SELFPROOF oracle] 正确路径取自 ls 实测:softplus_v2/docs/ 下唯一文件是 aclnnSoftplusV2.md;examples/ 下无 arch22/。
[SELFPROOF canary] [B] 用 dlsym 查两个接口符号均「已导出」——排除「接口本体未交付」这条竞争成因,把结论锁定在「文档跳转缺失」。
[SELFPROOF dtype] 本条为文档链接缺陷,不涉及 dtype;enum_source=header。

影响

用户按 aclnnSoftplusBackward 资料「算子功能」行的链接核对 aclnnSoftplus 原型会点进不存在的路径,无法确认正反向参数对应关系;fused_linear_online_max_sum 的英文读者按 README 找调用样例会误认为该算子没有 aclnn 样例(实际就在 examples/ 下)。experimental/ 下的接口会随版本整目录进出,路径漂移概率高于稳定目录,这类链接尤其易失效;不涉及运行时行为。

建议

按上「期望」修正两处链接;并在 CI 加一条资料链接存在性校验:扫描 docs/**/*.md 与 README*.md 的相对链接,按文件所在目录解析后 stat,不存在即失败——本次全仓 30289 条相对链接中仅这 2 处失效(另有同批其它仓 8 处),误报率极低,适合做成门禁。

关联

同批同类(另仓):cann/ops-transformer 4 处 README 指向不存在的「算子设计介绍.md」;本仓另有 3 处 aclnnThresholdBackward 指向 activation/threshold/docs/(实际在 activation/threshold_v2/docs/)。按仓分别提交;故障模式 FP-F04 成因⑥。

likedislike
liuhanwen8liuhanwen8
5 days ago Added label: bug-report
liuhanwen8liuhanwen8
5 days ago Change title to "[Bug-Report|缺陷反馈]: ops-nn 五处资料链接指向不存在的路径(softplus 多一层 ../ 且文件名差 V2;fused_linear README_en 多出 arch22;3 处 ThresholdBackward 指向 threshold 而非 threshold_v2)", originally titled "[Bug-Report|缺陷反馈]: ops-nn 两处资料链接指向不存在的路径(aclnnSoftplusBackward 多一层 ../ 且文件名差 V2;fused_linear README_en 多出 arch22 目录)".
liuhanwen8liuhanwen8
5 days ago Modify description of issue
yuning_chen
yuning_chenCollaborators
5 days ago Comments:

问题成立,5 处相对链接确实指向不存在的路径(softplus 多一层 ../ 且文件名差 V2、fused_linear README_en 多出 arch22、3 处 ThresholdBackward 指向 threshold 而非 threshold_v2)。
建议:①直接改到真实路径;②加 CI 检查:遍历仓内 md 相对链接,目标不存在即失败;③ThresholdBackward 的 3 处一起改。

likedislike
yuning_chenyuning_chenCollaborators
5 days ago Assign cong-jiyu as responsible person
yuning_chen
yuning_chenCollaborators
5 days ago Comments:

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

likedislike
丛吉钰丛吉钰Collaborators
3 days ago Associated pull request
CANN-robotCANN-robotCollaborators
3 days ago Close issue
CANN-robotCANN-robotCollaborators
3 days ago changed custom state from 待办的 to 已完成