Closed
[Documentation|文档反馈]: aclnnConvTbc 文档 bias 维度约束写错:文档要求等于 weight 第一维(K),实现要求等于输出通道(Cout) #8263
liuhanwen8Add on  16 days agoClosed at  12 days ago
liuhanwen8
liuhanwen8
16 days ago Create

aclnnConvTbc 文档中 bias 的维度约束写错:文档要求等于 weight 第一维(K),实现要求等于输出通道(Cout)

docs/aclnnConvTbc.md

Issues Section / 问题文档片段

一维且与 weight 第一维相等,不允许传入空指针。

现象

docs/aclnnConvTbc.md 对 bias 的使用说明原文:

一维且与 weight 第一维相等,不允许传入空指针。

而同一份文档对 weight 的维度定义原文:

shape为(K,Cin,Cout)

按文档字面,bias 的长度应等于 K。但实测按 K 构造时第一阶段直接返回 161002(参数非法),按 C_out 构造才能正常执行。

A3 / Ascend910_9362 / CANN 9.3.0,W=(K=3, C_in=4, C_out=6)、self=(H_in=8, N=2, C_in=4)、pad=0:

bias 长度 来源 ret ws 输出
3 按文档「与 weight 第一维相等」= K 161002 0 未写(哨兵 -777.25 残留 72/72)
6 按输出通道 C_out 0/0 5120 哨兵残留 0/72,out[0] = 12.0
4 按 C_in(另一猜测) 161002 0 未写

out[0] = 12.0 = K × C_in × 1.0 = 3 × 4(输入与权重全 1.0、bias 全 0),与 ConvTbc 的闭式结果精确一致,说明 bias=6 那一组是真正执行成功的合法基线。

期望

文档应改为与实现一致,例如:

一维,长度等于输出通道数 C_out(即 weight 的第三维)。

顺带说明:aclnn_convolution.cpp:1843 的 CheckConvBiasTbc 报错文本自身写的是 shape[0] of bias must be equal to output channel(6),与实现行为一致,与 md 文档不一致。

环境

  • 机器 ubuntu-199(A3),SoC Ascend910_9362,arch35x

  • CANN 9.3.0(readlink -f /usr/local/Ascend/cann → /usr/local/Ascend/cann-9.3.0)

  • 该版本发布件未随附 aclnnop/aclnn_conv_tbc.h,复现程序内按 9.3.0 实际符号手写 extern "C" 原型

  • 文档与实现基准确认:服务端 API 按 master 拉取,cann/ops-nn master HEAD(2026-11-05 22:53);docs/aclnnConvTbc.md 与 conv/convolution_forward 源码均按该 ref 读取

  • aclnn 两阶段 C++ 直调,不走 torch

  • 复核:2026-11-06 15:45 于 cann/ops-nn master 07e32fa44374cd2eedc3d4401cac63198f22f7cb 复核,问题仍存在(文档 docs/aclnnConvTbc.md 的 bias 维度约束与 conv/convolution_forward 实现仍不一致)

复现步骤

  1. 保存下方源码为 convtbc_bias.cpp。
  2. 编译(A3 / CANN 9.3.0):
source /usr/local/Ascend/ascend-toolkit/set_env.sh
g++ -std=c++17 -O2 convtbc_bias.cpp -o convtbc_bias \
  -I$ASCEND_HOME_PATH/include -L$ASCEND_HOME_PATH/lib64 \
  -lascendcl -lopapi -lnnopbase -Wl,-rpath,$ASCEND_HOME_PATH/lib64
  1. 运行 ./convtbc_bias 7(参数为 device id),观察三组的 ret 与 out[0]。

复现脚本

三组只改 bias 的长度,其余逐字相同。完整程序含以下头(aclnn_conv_tbc.h 发布件未随附,故手写原型):

#include <cstdio>
#include <vector>
#include "acl/acl.h"
#include "aclnn/aclnn_base.h"
extern "C" aclnnStatus aclnnConvTbcGetWorkspaceSize(const aclTensor* self, const aclTensor* weight,
                                                    const aclTensor* bias, const int64_t pad, aclTensor* output,
                                                    int8_t cubeMathType, uint64_t* workspaceSize,
                                                    aclOpExecutor** executor);
extern "C" aclnnStatus aclnnConvTbc(void* workspace, uint64_t workspaceSize, aclOpExecutor* executor,
                                    aclrtStream stream);

const int64_t Hin = 8, N = 2, Cin = 4, K = 3, Cout = 6;
const int64_t Hout = Hin - K + 1;   // pad=0 -> 6
std::vector<int64_t> sv{Hin, N, Cin}, wv{K, Cin, Cout}, bv{biasLen}, ov{Hout, N, Cout};
// self / weight / output 全 1.0,bias 全 0
aclTensor* tS = aclCreateTensor(sv.data(), 3, ACL_FLOAT, ss.data(), 0, ACL_FORMAT_ND, sv.data(), 3, dS);
aclTensor* tW = aclCreateTensor(wv.data(), 3, ACL_FLOAT, wstr.data(), 0, ACL_FORMAT_ND, wv.data(), 3, dW);
aclTensor* tB = aclCreateTensor(bv.data(), 1, ACL_FLOAT, bs.data(), 0, ACL_FORMAT_ND, bv.data(), 1, dB);
aclTensor* tO = aclCreateTensor(ov.data(), 3, ACL_FLOAT, os.data(), 0, ACL_FORMAT_ND, ov.data(), 3, dO);
int rc1 = aclnnConvTbcGetWorkspaceSize(tS, tW, tB, 0, tO, 1, &ws, &ex);

实测输出:

[bias len=K=3  (per doc)           ] ret=161002/-1 ws=0        resid=72/72 first=-777.2500
[bias len=Cout=6 (per semantics)   ] ret=0/0 ws=5120     resid=0/72 first=12.0000
[bias len=Cin=4 (third guess)      ] ret=161002/-1 ws=0        resid=72/72 first=-777.2500

ACLLOG 原文(ASCEND_GLOBAL_LOG_LEVEL=2):

[aclnn_convolution.cpp:1843][CheckConvBiasTbc] Parameters bias of aclnnConvTbcGetWorkspaceSize
  have incorrect shapes [3]. Reason: shape[0] of bias must be equal to output channel(6).

影响

用户按文档传入长度为 K 的 bias 时,第一阶段即返回 161002(参数非法),且错误信息只提示「bias shape 不正确」,不与文档的「与 weight 第一维相等」形成对照,用户按文档自查无法发现是文档写错。

ConvTbc 常见于时序卷积场景,K 与 C_out 数值通常不同(本例 3 vs 6),该错误描述会直接导致用户构造失败。

建议

  1. docs/aclnnConvTbc.md 中 bias 的「一维且与 weight 第一维相等」改为「一维,长度等于输出通道数 C_out(weight 的第三维)」。
  2. 建议同步检查 aclnnConvTbcBackward.md 是否有同样的表述问题。
likedislike
liuhanwen8liuhanwen8
16 days ago Added label: documentation
liuhanwen8
liuhanwen8
16 days ago Comments:

复现脚本(完整源码,自包含)

CANN 9.3.0 发布件未随附 aclnnop/aclnn_conv_tbc.h,故程序内按实际符号手写 extern "C" 原型。
aclrtSetDevice(7) 里的 device 号按环境可改。

// aclnnConvTbc:文档说 bias「一维且与 weight 第一维相等」,实测到底要多长?
// 用法: ./convtbc_bias <device>
//   weight shape = (K, C_in, C_out),文档写的是这个顺序
//   若 bias 需要 K,则与文档一致;若需要 C_out,则文档「与 weight 第一维相等」写错
#include <cstdio>
#include <cstdlib>
#include <vector>
#include "acl/acl.h"
#include "aclnn/aclnn_base.h"
// CANN 9.3.0 发布件未随附 aclnn_conv_tbc.h,按文档参数顺序手写原型
extern "C" aclnnStatus aclnnConvTbcGetWorkspaceSize(const aclTensor* self, const aclTensor* weight,
                                                    const aclTensor* bias, const int64_t pad, aclTensor* output,
                                                    int8_t cubeMathType, uint64_t* workspaceSize,
                                                    aclOpExecutor** executor);
extern "C" aclnnStatus aclnnConvTbc(void* workspace, uint64_t workspaceSize, aclOpExecutor* executor,
                                    aclrtStream stream);

static int g_dev = 0;

static void Run(const char* tag, int64_t biasLen, aclrtStream s)
{
    const int64_t Hin = 8, N = 2, Cin = 4, K = 3, Cout = 6;
    const int64_t Hout = Hin - K + 1;   // pad=0, dilation=1 -> 交叉相关,长度收缩

    std::vector<int64_t> sv{Hin, N, Cin}, wv{K, Cin, Cout}, bv{biasLen}, ov{Hout, N, Cout};
    auto cs = [](const std::vector<int64_t>& sh) {
        std::vector<int64_t> r(sh.size(), 1);
        for (int64_t i = (int64_t)sh.size() - 2; i >= 0; i--) r[(size_t)i] = sh[(size_t)(i + 1)] * r[(size_t)(i + 1)];
        return r;
    };
    auto ss = cs(sv), wstr = cs(wv), bs = cs(bv), os = cs(ov);

    size_t nS = (size_t)(Hin * N * Cin), nW = (size_t)(K * Cin * Cout), nB = (size_t)biasLen, nO = (size_t)(Hout * N * Cout);
    std::vector<float> hs(nS, 1.0f), hw(nW, 1.0f), hb(nB, 0.0f);
    void *dS = nullptr, *dW = nullptr, *dB = nullptr, *dO = nullptr;
    aclrtMalloc(&dS, nS * 4, ACL_MEM_MALLOC_HUGE_FIRST);
    aclrtMalloc(&dW, nW * 4, ACL_MEM_MALLOC_HUGE_FIRST);
    aclrtMalloc(&dB, (nB ? nB : 1) * 4, ACL_MEM_MALLOC_HUGE_FIRST);
    aclrtMalloc(&dO, nO * 4, ACL_MEM_MALLOC_HUGE_FIRST);
    aclrtMemcpy(dS, nS * 4, hs.data(), nS * 4, ACL_MEMCPY_HOST_TO_DEVICE);
    aclrtMemcpy(dW, nW * 4, hw.data(), nW * 4, ACL_MEMCPY_HOST_TO_DEVICE);
    aclrtMemcpy(dB, nB * 4, hb.data(), nB * 4, ACL_MEMCPY_HOST_TO_DEVICE);
    std::vector<float> sent(nO, -777.25f);
    aclrtMemcpy(dO, nO * 4, sent.data(), nO * 4, ACL_MEMCPY_HOST_TO_DEVICE);

    aclTensor* tS = aclCreateTensor(sv.data(), 3, ACL_FLOAT, ss.data(), 0, ACL_FORMAT_ND, sv.data(), 3, dS);
    aclTensor* tW = aclCreateTensor(wv.data(), 3, ACL_FLOAT, wstr.data(), 0, ACL_FORMAT_ND, wv.data(), 3, dW);
    aclTensor* tB = aclCreateTensor(bv.data(), 1, ACL_FLOAT, bs.data(), 0, ACL_FORMAT_ND, bv.data(), 1, dB);
    aclTensor* tO = aclCreateTensor(ov.data(), 3, ACL_FLOAT, os.data(), 0, ACL_FORMAT_ND, ov.data(), 3, dO);

    uint64_t ws = 0;
    aclOpExecutor* ex = nullptr;
    int rc1 = (int)aclnnConvTbcGetWorkspaceSize(tS, tW, tB, 0, tO, 1, &ws, &ex);
    int rc2 = -1;
    std::vector<float> out(nO, -777.25f);
    if (rc1 == 0) {
        void* w = nullptr;
        if (ws) aclrtMalloc(&w, ws, ACL_MEM_MALLOC_HUGE_FIRST);
        rc2 = (int)aclnnConvTbc(w, ws, ex, s);
        aclrtSynchronizeStream(s);
        aclrtMemcpy(out.data(), nO * 4, dO, nO * 4, ACL_MEMCPY_DEVICE_TO_HOST);
        if (w) aclrtFree(w);
    }
    int resid = 0;
    for (float v : out) if (v == -777.25f) ++resid;
    printf("[%-34s] ret=%d/%d ws=%-8llu resid=%d/%zu first=%.4f\n",
           tag, rc1, rc2, (unsigned long long)ws, resid, nO, (double)out[0]);

    aclDestroyTensor(tS); aclDestroyTensor(tW); aclDestroyTensor(tB); aclDestroyTensor(tO);
    aclrtFree(dS); aclrtFree(dW); aclrtFree(dB); aclrtFree(dO);
}

int main(int argc, char** argv)
{
    if (argc > 1) g_dev = atoi(argv[1]);
    if (aclInit(nullptr) != ACL_SUCCESS) { printf("aclInit fail\n"); return 1; }
    if (aclrtSetDevice(g_dev) != ACL_SUCCESS) { printf("setDevice fail\n"); return 2; }
    aclrtStream s = nullptr;
    aclrtCreateStream(&s);
    const char* soc = aclrtGetSocName();
    printf("### soc=%s dev=%d  weight=(K=3, Cin=4, Cout=6)\n", soc ? soc : "?", g_dev);
    printf("### doc says bias len == weight dim0 == 3 ; ConvTbc semantics wants Cout == 6\n\n");

    Run("bias len=K=3  (per doc)", 3, s);
    Run("bias len=Cout=6 (per semantics)", 6, s);
    Run("bias len=Cin=4 (third guess)", 4, s);

    aclrtDestroyStream(s);
    aclrtResetDevice(g_dev);
    aclFinalize();
    printf("\n### done\n");
    return 0;
}

实测输出(A3 / Ascend910_9362 / CANN 9.3.0)

### soc=Ascend910_9362 dev=7  weight=(K=3, Cin=4, Cout=6)
### doc says bias len == weight dim0 == 3 ; ConvTbc semantics wants Cout == 6

[bias len=K=3  (per doc)           ] ret=161002/-1 ws=0        resid=72/72 first=-777.2500
[bias len=Cout=6 (per semantics)   ] ret=0/0 ws=5120     resid=0/72 first=12.0000
[bias len=Cin=4 (third guess)      ] ret=161002/-1 ws=0        resid=72/72 first=-777.2500

三点说明

  1. bias=6 那组是真正执行成功的:ws=5120、哨兵残留 0/72(输出写满)、out[0] = 12.0 = K × C_in × 1.0 = 3 × 4,与 ConvTbc 的闭式结果精确一致(输入与权重全 1.0、bias 全 0)。
  2. bias=3 正是按文档构造的:「一维且与 weight 第一维相等」,而文档写明 weight 为 (K, C_in, C_out),第一维即 K=3。该构造返回 161002。
  3. C_in=4 作为第三组负例一并测了,同样 161002,排除「其实要输入通道」这一可能。

补充:即使不做基线,算子自身的报错也已说明要求

ASCEND_GLOBAL_LOG_LEVEL=2 下第一组(bias=3)的 ACLLOG 原文:

[aclnn_convolution.cpp:1843][CheckConvBiasTbc] Parameters bias of aclnnConvTbcGetWorkspaceSize
  have incorrect shapes [3]. Reason: shape[0] of bias must be equal to output channel(6).

即实现侧明确要求 bias.shape[0] == 输出通道数,与 md 文档的「与 weight 第一维相等」不是同一个量(本例 3 vs 6)。

likedislike
liuhanwen8
liuhanwen8
16 days ago Comments:

补充两点,不是改判:原单的结论与「期望」都成立,这里只补两件它没有覆盖到的事实。

一、同一个「第一维」的措辞错误,output 行也有

原单指出了 bias 行。核对时发现 output 行的「使用说明」是同一类表述:

bias:一维且与 weight 第一维相等,不允许传入空指针。
output:通道数等于 weight 第一维,其他维度 ≥ 0。

而 output 自身的 shape 在文档里写作 (H_out,N,C_out) —— 通道数是 C_out。
按 weight = (K,C_in,C_out),「第一维」是 K,于是 output 这一句会推出 C_out = K,与它自己写的 C_out 互相冲突。

即:这两处「weight 第一维」需要一起改,只改 bias 行的话 output 行仍然是矛盾的。

二、实测:bias 的长度要求是第三维 C_out,不是第一维

固定 self=(8,2,4)、weight=(3,4,6)(即 (K,C_in,C_out))、out=(6,2,6)、pad=0、weight 与输入全 1、bias 全 0,只改 bias 长度:

bias 长度 rc1 / rc2 输出
6 0 / 0 out[0] = 12.0,哨兵残留 0/72
3 161002 / — 未写,哨兵残留 72/72

weight 第一维是 K = 3,但 bias 传 3 被拒、传 6 通过 ⇒ 实现取的是 C_out(第三维)。
out[0] = 12.0 = K × C_in × 1.0 = 3 × 4,与 ConvTbc 的闭式结果精确一致,说明 bias=6 那组是真正执行成功的合法基线。

三、建议改法

把 bias 与 output 两处的「weight 第一维」改为「weight 第三维(C_out)」:

  • bias:一维且与 weight 第三维(C_out)相等,不允许传入空指针;
  • output:通道数等于 weight 第三维(C_out),其他维度 ≥ 0。

weight 行的 shape((K,C_in,C_out))与实现已经一致,不需要改。

四、背景:9.0.0 与当前主干的 weight 维度顺序不同

9.0.0 发布件的文档里 weight 写作 (C_out,C_in,K)(C_out 在第一位),那时这两处「第一维」的措辞是成立的。
当前主干改为 (K,C_in,C_out) 之后,「第一维」变成 K,这两处措辞随之失效 —— 这是矛盾的来源。

因此修法有两条路,可任选:

  • 保持现有 weight 顺序,只改上述两处措辞(改动最小,不涉及实现);
  • 或恢复 9.0.0 的 weight 顺序,则两处措辞无需改动,但需同步调整实现——当前实现按 (K,C_in,C_out) 解释 weight(第二轮实测中,weight=(3,4,6) 能构出合法基线)。

复现环境

机器 ubuntu-199,SoC Ascend910_9362(Short_SoC_version=Ascend910_93),NpuArch=2201(dav-c220),CANN 9.3.0;该发布件未随附 aclnnop/aclnn_conv_tbc.h,程序内按 9.3.0 实际符号手写 extern "C" 原型;aclnn 两阶段 C++ 直调,不走 torch。

likedislike
yuning_chenyuning_chenCollaborators
15 days ago Assign huafeng793 as responsible person
yuning_chen
yuning_chenCollaborators
15 days ago Comments:

初步分析

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

现象理解:[Documentation|文档反馈]: aclnnConvTbc 文档 bias 维度约束写错:文档要求等于 weight 第一维(K),实现要求等于输出通道(Cout)。

当前判断:初步判断,待复现确认,还不能当成已确认根因。

涉及范围:根据标题与描述,先对照对应算子的实现/资料/校验路径排查。

下一步:我们会按描述构造用例复现,并对照代码与资料给出修复或文档修正方向。

likedislike
yuning_chen
yuning_chenCollaborators
15 days ago Comments:

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

likedislike
liuhanwen8liuhanwen8
15 days ago Modify description of issue
liuhanwen8liuhanwen8
15 days ago Modify description of issue
李绪杰李绪杰
12 days ago Associated pull request
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
LiuZongguLiuZongguCollaborators
11 days ago Removed responsible person huafeng793
LiuZongguLiuZongguCollaborators
11 days ago Assign lxj33 as responsible person
LiuZongguLiuZongguCollaborators
11 days ago Assign LiuZonggu as responsible person
chenjiayi_chenjiayi_Collaborators
2 days ago Assign chenjiayi_ as responsible person
chenjiayi_
chenjiayi_Collaborators
2 days ago Comments:

补充说明本问题的跟进安排:

该 issue 已关闭,已补充 assign 给 @chenjiayi_ 复核关闭结论,原责任人 @lxj33、@LiuZonggu 保留协同。

当前状态:

  • 关闭状态:已完成;复核项:aclnnConvTbc 文档 bias 维度约束写错:文档要求等于 weight 第一维(K),实现要求等于输出通道(Cout)。
  • 我先核对关闭时的结论与当前 master 的实现/资料是否一致。

下一步:

  • 复核完成后在本 issue 补充结论。
  • 如果还有后续需要,请重新提 issue。
likedislike
chenjiayi_chenjiayi_Collaborators
12 hours ago Removed responsible person chenjiayi_