CANN ops-nn 算子 SigmoidCrossEntropyWithLogitsGradV2 深度解析ACLNN 两段式接口、梯度公式与 NPU 实现原理【免费下载链接】ops-nn本项目是CANN提供的神经网络类计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-nn导读本文围绕 CANN ops-nn 仓库中experimental/loss/sigmoid_cross_entropy_with_logits_grad_v2算子目录展开系统讲解带 logits 的二元交叉熵损失Binary Cross Entropy with Logits反向传播梯度的完整计算链路从数学公式、算子参数与约束到 aclnnBinaryCrossEntropyWithLogitsBackward 两段式调用接口、AscendC 内核实现与 Tiling 策略。读完本文你将能够正确理解该算子每个输入/属性/输出的语义与合法性约束独立完成基于 ACLNN 两段式接口的算子调用样例编写与运行并可以从源码层面掌握该算子在 NPU 上的数据搬运、计算拆分与性能调优思路。一、算子概述与产品支持情况SigmoidCrossEntropyWithLogitsGradV2是 CANN ops-nn 项目中用于计算二分类交叉熵带 logits损失对输入 logits 的梯度的算子它对应 PyTorch 中binary_cross_entropy_with_logits的反向传播。该算子位于仓库的 experimental 实验目录下其完整工程结构如下experimental/loss/sigmoid_cross_entropy_with_logits_grad_v2/ ├── README.md # 算子功能、参数与约束说明本文主体依据 ├── docs/aclnnBinaryCrossEntropyWithLogitsBackward.md # ACLNN 两段式接口文档 ├── examples/test_aclnn_sigmoid_cross_entropy_with_logits_grad_v2.cpp # 可运行调用样例 ├── op_host/ │ ├── op_api/ # ACLNN 接口层实现与头文件 │ ├── sigmoid_cross_entropy_with_logits_grad_v2_def.cpp # 算子定义IR 注册 │ ├── sigmoid_cross_entropy_with_logits_grad_v2_infershape.cpp # 输出 shape 推导 │ └── sigmoid_cross_entropy_with_logits_grad_v2_tiling.cpp # Tiling 策略 ├── op_kernel/ │ ├── sigmoid_cross_entropy_with_logits_grad_v2.cpp # AscendC 内核 │ ├── sigmoid_cross_entropy_with_logits_grad_v2.h # 内核类模板声明 │ ├── sigmoid_cross_entropy_with_logits_grad_v2_tiling_data.h # Tiling 数据结构 │ └── sigmoid_cross_entropy_with_logits_grad_v2_tiling_key.h # Tiling Key └── tests/ut/ # op_api / op_host / op_kernel 三级单测根据 README.md 的“产品支持情况”该算子支持Atlas A2 训练系列产品 / Atlas A2 推理系列产品。二、数学原理梯度公式推导2.1 基础定义设输入为predict即 logits用 $x$ 表示、target标签用 $y$ 表示、dout上游梯度先计算 sigmoid$$ p \text{sigmoid}(predict) \frac{1}{1 e^{-predict}} $$2.2 无 pos_weight 的分支当pos_weight不存在时$$ grad_base p - target $$2.3 有 pos_weight 的分支当pos_weight存在时引入正样本权重因子$$ log_weight pos_weight \cdot target $$$$ grad_base (log_weight 1 - target) \cdot p - log_weight $$可以验证当pos_weight 1时log_weight target该式退化为(target 1 - target) · p - target p - target与无pos_weight分支完全一致说明该公式是前者的广义化形式。2.4 梯度合成与权重缩放梯度输出先乘以上游梯度$$ gradient grad_base \cdot dout $$若weight非空样本级权重再逐元素相乘$$ gradient gradient \cdot weight $$当reduction mean时再按元素总数 $N$ 做均值缩放$$ gradient gradient \cdot \frac{1}{N} $$三、参数说明3.1 算子级参数IR 定义根据 README.md 参数表整理如下参数名输入/输出/属性描述数据类型数据格式predict输入模型输出 logitsBFLOAT16、FLOAT16、FLOATNDtarget输入标签张量BFLOAT16、FLOAT16、FLOATNDdout输入上游梯度输入BFLOAT16、FLOAT16、FLOATNDweight可选输入样本权重BFLOAT16、FLOAT16、FLOATNDpos_weight可选输入正样本权重BFLOAT16、FLOAT16、FLOATNDreduction可选属性支持 none、mean、sumSTRING / INT64接口映射-gradient输出梯度输出BFLOAT16、FLOAT16、FLOATND其中reduction在算子 IR 层的默认值为mean见 sigmoid_cross_entropy_with_logits_grad_v2_def.cpp 中的this-Attr(reduction).AttrType(OPTIONAL).String(mean)IR 注册中同时声明了predict、target、dout为 REQUIRED 输入weight、pos_weight为 OPTIONAL 输入支持的数据类型为ge::DT_FLOAT16 / ge::DT_FLOAT / ge::DT_BF16格式统一为ge::FORMAT_ND目标硬件为ascend910b。3.2 约束说明来自 README.md 的约束项输入维度范围为 1-8 维predict、target、dout的 shape 需一致weight、pos_weight为可选输入若存在需与predictshape 一致输入与输出数据类型需保持一致。值得注意的是ACLNN 接口层对 shape 的校验比算子 README 的表述更宽松从 aclnn_binary_cross_entropy_with_logits_backward.cpp 的CheckShape实现可以看到gradOutput、weightOptional、posWeightOptional是按广播语义broadcast校验的——它们需要能够广播到self的 shape最终广播结果必须与self完全一致而target与out则要求与selfshape 严格相等。因此在实践中三个必选输入与输出通常使用相同 shape可选输入可以使用可广播至该 shape 的形态。3.3 输出 shape 推导infershape 实现 中gradient的 shape 直接拷贝predict的 shape即输出与输入 logits 同 shape这符合逐元素梯度算子的直觉——反向传播的梯度形状与正向 logits 张量一一对应。四、ACLNN 两段式接口aclnnBinaryCrossEntropyWithLogitsBackward4.1 接口与参数映射ACLNN 层将该算子包装为aclnnBinaryCrossEntropyWithLogitsBackward采用 CANN 标准的两段式接口调用模式详见 docs/zh/context/two_phase_api.md第一段GetWorkspaceSize完成入参校验与计算流程编排、返回 workspace 大小和执行器第二段执行真正的计算。参数映射关系来自 aclnnBinaryCrossEntropyWithLogitsBackward.mdself↔ 算子输入predictlogitsgradOutput↔ 算子输入dout上游梯度out↔ 算子输出gradientweightOptional↔ 算子输入weightposWeightOptional↔ 算子输入pos_weightreduction以int64_t传入0 表示 none1 表示 mean2 表示 sum函数原型见 aclnn_binary_cross_entropy_with_logits_backward.haclnnStatus aclnnBinaryCrossEntropyWithLogitsBackwardGetWorkspaceSize( const aclTensor* gradOutput, const aclTensor* self, const aclTensor* target, const aclTensor* weightOptional, const aclTensor* posWeightOptional, int64_t reduction, aclTensor* out, uint64_t* workspaceSize, aclOpExecutor** executor); aclnnStatus aclnnBinaryCrossEntropyWithLogitsBackward( void* workspace, uint64_t workspaceSize, aclOpExecutor* executor, const aclrtStream stream);4.2 第一段接口的参数校验逻辑从 aclnn_binary_cross_entropy_with_logits_backward.cpp 的CheckParams可以看到第一段接口依序执行六类检查空指针检查gradOutput、self、target、out任一为空指针时报ACLNN_ERR_PARAM_NULLPTR错误码 161001维度检查所有张量维度不得超过 8 维CheckDimension使用OP_CHECK_MAX_DIM宏MAX_SUPPORT_DIMS_NUMS数据类型检查self/target/gradOutput/out及非空的weight/pos_weight均须落在支持列表内且out类型须与target一致CheckDtypeValid数据格式检查self与target、self与out的存储格式必须相同CheckFormatshape 检查target、out与self严格同 shapegradOutput、weight、pos_weight广播后须与self一致空 tensor 直接放行CheckShapereduction 检查取值必须落在 0~2CheckReduction枚举enum Reductions { None, Mean, Sum, END }。上述任一检查失败均返回ACLNN_ERR_PARAM_INVALID错误码 161002。完整的返回码含义可参见 docs/zh/context/aclnn_return_code.md。4.3 数据类型推导与内部计算流程ACLNN 接口层还实现了一套类型提升promote与格式适配流程BinaryCrossEntropyWithLogitsBackwardStubCheckPromoteType依次对selftarget、gradOutput、weightOptional、posWeightOptional做op::PromoteType类型推导要求最终推导结果可安全 cast 到输出类型输入 tensor 若为非连续non-contiguous则先经l0op::Contiguous转为连续接口文档明确标注各张量均支持“非连续 Tensor”√weight、pos_weight为空时分别用l0op::OnesLike(self)生成全 1 张量参与计算——这解释了算子内核为什么始终能看到“逻辑上存在的”两个权重全部输入 cast 到 promoteType 后调用 L0 级算子l0op::SigmoidCrossEntropyWithLogitsGradV2将reduction枚举映射为字符串{none, mean, sum}计算结果再 cast 回out的数据类型经ReFormat/ViewCopy适配输出 format 与视图非连续输出场景。支持的数据类型列表是平台相关的GetDtypeSupportList()在 DAV_2201 架构或 Regbase 模式下返回{DT_FLOAT16, DT_FLOAT, DT_BF16}其他平台仅返回{DT_FLOAT16, DT_FLOAT}详见 aclnn_binary_cross_entropy_with_logits_backward.cpp。这提醒开发者BFLOAT16 支持是有平台前提的跨平台使用时需确认目标平台的 dtype 支持范围。4.4 确定性计算保证根据 aclnnBinaryCrossEntropyWithLogitsBackward.md 的说明该接口默认采用确定性实现即相同输入在同一软硬件环境下多次运行结果可复现这对训练梯度校验、数值调优与问题定位具有实用价值。确定性计算的通用机制可参考 docs/zh/context/determinism_compute.md。五、完整调用示例从 Host 到 Device5.1 完整样例代码examples/test_aclnn_sigmoid_cross_entropy_with_logits_grad_v2.cpp 给出了一个可运行、可验证的完整样例演示数据均为同 shape不使用广播。其核心步骤包括ACL 环境初始化 → 构造输入/输出 aclTensor → 两段式接口调用 → 同步取回结果 → 资源释放。关键调用片段如下#include aclnnop/aclnn_binary_cross_entropy_with_logits_backward.h // 1. 环境初始化固定写法aclInit / aclrtSetDevice / aclrtCreateStream int32_t deviceId 0; aclrtStream stream; Init(deviceId, stream); // 2. 构造张量predict(32,32)、target(32,32)、dout(32,32) // 可选输入 weight(32,32)、pos_weight(32,32) 同 shape // 通过 aclrtMalloc aclrtMemcpy 放入 Device再 aclCreateTensor 封装 // CreateAclTensor 内部同时计算连续张量 stridesformat 为 ACL_FORMAT_ND // 3. 两段式接口调用 uint64_t workspaceSize 0; aclOpExecutor* executor; int64_t reduction 1; // 0:none, 1:mean, 2:sum ret aclnnBinaryCrossEntropyWithLogitsBackwardGetWorkspaceSize( doutTensor, // gradOutput注意参数顺序gradOutput 在前 predictTensor, // selflogits targetTensor, weightTensor, // 可传 nullptr 表示不使用 posWeightTensor, // 可传 nullptr 表示不使用 reduction, outputTensor, workspaceSize, executor); void* workspaceAddr nullptr; if (workspaceSize 0) { aclrtMalloc(workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST); } ret aclnnBinaryCrossEntropyWithLogitsBackward(workspaceAddr, workspaceSize, executor, stream); aclrtSynchronizeStream(stream); // 4. aclrtMemcpy(DEVICE_TO_HOST) 回拷输出并打印前 8 个元素验证 // 5. aclDestroyTensor / aclrtFree / aclrtDestroyStream / aclrtResetDevice / aclFinalize 释放资源易错点提示第一段接口的参数顺序是gradOutput, self, target, weightOptional, posWeightOptional, reduction, out即dout位于predict之前与直觉上的“先 logits 后梯度”相反样例代码中已用注释特别标注。5.2 编译与运行指引样例的编译执行过程遵循 CANN 算子开发标准流程具体可参考 docs/zh/context/compile_and_run_sample.md。整体要点为头文件路径aclnn_binary_cross_entropy_with_logits_backward.hop_host/op_api 目录中声明的ACLNN_API接口及acl/acl.h链接 CANN 运行时库acl、aclnn 相关动态库并设置好ASCEND_HOME_PATH等环境变量在装有 Atlas A2 系列产品的环境上执行输出 tensor 需预先分配与self同 shape 的 Device 内存。5.3 数值验证小实验样例数据推算以样例中的简化数据为例可直观验证公式若predict 1.0、target 0.5、dout 1.0、weight 1.0、pos_weight 2.0则有$p \frac{1}{1e^{-1}} \approx 0.7310586$$log_weight 2.0 \times 0.5 1.0$$grad_base (1.0 1 - 0.5) \times 0.7310586 - 1.0 1.5 \times 0.7310586 - 1.0 \approx 0.0965879$乘dout、weight后仍约为 0.0965879本组数据下两权重均为 1 或已计入reductionmean 时再除以元素总数。由于样例输入为全 1 / 全 0.5 常量所有元素梯度一致打印结果应为同一常量可用以快速确认算子被正确执行、输出被写回。六、NPU 内核实现原理AscendC 视角6.1 模板化内核与权重组合kernel 实现 以类模板KernelSigmoidCrossEntropyWithLogitsGradV2T, HAS_WEIGHT, HAS_POS_WEIGHT组织T为输入数据类型由DTYPE_PREDICT推导两个布尔模板参数在编译期按weight/pos_weight是否存在的 4 种组合展开见DISPATCH_SIGMOID_GRAD宏从而内核入口签名固定为(predict, target, dout, weight, pos_weight, gradient, workspace, tiling)不存在的可选输入不会申请队列、不会做搬运避免运行时分支开销Init阶段按blockIdx与 tiling 数据切分 Global Memory 缓冲区并根据tileDataNum初始化 UB 上多级队列predict/target/dout、条件性的 weight/pos_weight、输出 grad以及 FP32 计算缓冲区。6.2 计算流水与公式落位内核采用经典的CopyIn → Compute → CopyOut 三段式流水Process循环QUEUE_DEPTH1的双缓冲由 Tiling 侧决定。Compute阶段与数学公式一一对应无 pos_weight 分支对应 2.2 节// sigmoid(x) 1 / (1 exp(-x)) Muls(tmp1, x_fp32, -1.0f); Exp(tmp1, tmp1); Adds(tmp3, tmp1, 1.0f); Duplicate(tmp2, 1.0f); Div(x_fp32, tmp2, tmp3); Sub(x_fp32, x_fp32, y_fp32); // grad_base p - y有 pos_weight 分支对应 2.3 节Mul(tmp1, pos_w_vec_fp32, y_fp32); // log_weight pos_weight * target Adds(tmp3, tmp1, 1.0f); Sub(tmp3, tmp3, y_fp32); // log_weight 1 - target Muls(tmp2, x_fp32, -1.0f); Exp(tmp2, tmp2); Adds(y_fp32, tmp2, 1.0f); Duplicate(tmp2, 1.0f); Div(x_fp32, tmp2, y_fp32); // sigmoid(x) Mul(tmp3, tmp3, x_fp32); Sub(x_fp32, tmp3, tmp1); // grad_base随后统一执行gradient grad_base * dout可选再乘weight最后若tiling.globalScale ! 1.0f则整体缩放reductionmean 时的 $1/N$ 因子。内核注释明确指出该公式序列与 TBE 路径保持一致同时指令顺序对齐 builtin trace。数值精度设计非 FP32 输入FP16/BF16在计算前Cast到 FP32 中间缓冲区calc_fp32全部中间运算在 FP32 下完成输出时再按类型回写——FP16 使用CAST_RINT、BF16 使用CAST_RINT、FP32 直接拷贝最大程度避免中间累积误差calcBuf数量为FP32_BUF_NUMFP32 输入在 lite 模式下可缩减为 3 个缓冲见 6.4 节。非整块数据通过DataCopyPad补齐搬运FP32 尾块在tileDataNum 1024时回退为标量路径以避免 pad 开销源码注释For tiny fp32 tiles, pad copy overhead can exceed scalar fallback benefits。6.3 内核的 Tiling 数据结构内核依赖的 Tiling 参数定义在 sigmoid_cross_entropy_with_logits_grad_v2_tiling_data.hstruct SigmoidCrossEntropyWithLogitsGradV2TilingData { uint64_t smallCoreDataNum; // 小核非尾核处理的数据量 uint64_t bigCoreDataNum; // 大核尾核处理的数据量 uint64_t finalBigTileNum; // 大核的 tile 循环次数 uint64_t finalSmallTileNum; // 小核的 tile 循环次数 uint64_t tileDataNum; // 单个 tile 的元素数 uint64_t smallTailDataNum; // 小核尾 tile 元素数 uint64_t bigTailDataNum; // 大核尾 tile 元素数 uint64_t tailBlockNum; // 承担大核角色的 block 数 float globalScale; // reductionmean 时的 1/N 缩放因子 uint32_t has_weight; // 是否携带 weight uint32_t has_pos_weight; // 是否携带 pos_weight uint32_t fp32_lite_mode; // FP32 精简缓冲模式标记 };内核Init中通过GetBlockIdx()与tailBlockNum判断当前核是大核还是小核并据此确定各自的数据量与 tile 循环次数数据量不同的核之间通过globalBufferIndex的偏移修正保证每个元素恰好被处理一次。七、Tiling 策略与性能调优细节7.1 整体流程tiling 实现 完成读取输入 shape/dtype → 判定has_weight/has_pos_weight→ 解析reduction→ 计算 UB 可用容量与 tileBlockNum → 分配核数 → 通过CalculateCoreBlockNums计算大小核数据分布 → 写入 Tiling 数据并SetBlockDim。7.2 reduction 的“双编码”兼容GetReductionType展示了算子 IR 与 ACLNN 接口层 reduction 编码差异的处理Tiling 侧优先读字符串属性none/sum/mean兼容单字母缩写n/s/m若拿到整数属性则做了一次编码映射——ACLNN 接口的枚举是 0:none、1:mean、2:sum而内部 Tiling 枚举是 0:none、1:sum、2:mean源码注释明确说明该兼容性设计读取后统一换算为内部ReductionType。globalScale仅在 mean内部编码 2且totalLength 0时置为1.0f / totalLength其余情况为 1.0。7.3 核数与 UB 自适应核数选择默认按(totalLength 1023) / 1024估算最优核数并与 AIV 核数、总 block 数取较小值随后依据 dtype 与 workload 范围套用多种细分策略例如FP32 且同时带 weight/pos_weight 的“重计算”场景enableFp32PerfTune按数据量分档限制核数≤8K 用 8 核、≤64K 用 16 核、≤256K/512K 用 24 核、≤1M 用 32 核等避免中小 shape 被过度切分引入 sync/scalar 开销FP32 3D/4D sum 中大规模25 万~95 万元素场景使用FP32_HEAVY_PREFERRED_CORE_NUM 40的偏好核数BF16 3D mean 2 万~3 万元素场景限制到BF16_3D_MEAN_PREFERRED_CORE_NUM 25并同步做 tile 上限收敛FP16 5D none 90 万~120 万元素场景enableFp16FiveDimSyncOpt通过缩小 UB 预留提升单片容量BF16 sum 15 万~18 万元素场景强制每核 2 tileenableBf16Split2Tiles以恢复流水重叠。UB 容量reservedUbSize默认为 64KBFP32 lite 模式 16KB、FP32 重计算 8KB、FP32 heavy 场景仅 4KB进而影响tileBlockNum与单片数据量FP32 路径还要求tileDataNum保持 16 对齐以避免短向量回退。workspaceTiling 阶段通过GetLibApiWorkSpaceSize()设置 workspace 大小供内核框架使用。这些策略均以 workload 区间dtype 维度 reduction 元素量为触发条件属于仓库内已有的调优经验沉淀开发者可参照 tiling 实现 结合自身业务 shape 复现与验证。八、测试体系与验证方式算子目录下配套了三级单元测试tests/utop_kernel 层test_sigmoid_cross_entropy_with_logits_grad_v2.cpp使用 gtest ICPU_RUN_KF在 CPU 模拟环境下运行内核手工构造TilingDataType并校验梯度输出。例如test_case_fp32_smoke用 128 个 FP32 元素、单核单 tile、globalScale1.0的配置运行内核TILING_KEY_FLOATAIV_MODE用于内核正确性冒烟op_host 层test_sigmoid_cross_entropy_with_logits_grad_v2_tiling.cpp验证 Tiling 计算逻辑核数、tile 数、尾块分配等op_api 层test_aclnn_binary_cross_entropy_with_logits_backward.cpp从 ACLNN 接口层做端到端校验覆盖参数校验、广播、两段式调用等路径。如需对算子做二次开发或行为确认可参考上述测试的构造方式先准备 host 数据与 shape再按 tiling 结构填充关键字段最后在 CPU 模拟器或 NPU 环境断言输出与理论公式结果一致。九、总结与使用建议SigmoidCrossEntropyWithLogitsGradV2是 CANN ops-nn 中面向 Atlas A2 系列产品的二分类交叉熵反向算子其完整技术栈可归纳为四层数学层grad_base (pos_weight·target 1 - target)·sigmoid(predict) - pos_weight·target无 pos_weight 时退化为sigmoid(predict) - target再依次乘dout、weightmean 模式下按 $1/N$ 缩放接口层aclnnBinaryCrossEntropyWithLogitsBackward两段式 ACLNN 接口自带空指针/维度/dtype/format/shape/reduction 六重校验、类型提升、非连续张量 contiguity 适配与确定性计算保证内核层AscendC 模板内核FP32 中间精度计算 可选输入编译期展开 大小核数据切分 DataCopyPad 尾块处理调度层按 dtype/维度/reduction/元素量分档的核数与 UB 自适应 Tiling 策略。实用建议调用前确认目标平台为 Atlas A2 系列且非 DAV_2201/Regbase 平台不支持 BF16 输入三个必选输入与输出保持同 shape 与同 dtype可选权重优先使用同 shape 或可广播 shapereduction在 ACLNN 接口层用整数 0/1/2注意与算子 IR 层字符串none/mean/sum的编码差异已由框架内部自动映射若需要快速验证算子行为可直接运行 examples/test_aclnn_sigmoid_cross_entropy_with_logits_grad_v2.cpp 并对照本文 5.3 节的手算结果。参考文档与源码索引算子说明experimental/loss/sigmoid_cross_entropy_with_logits_grad_v2/README.mdACLNN 接口文档experimental/loss/sigmoid_cross_entropy_with_logits_grad_v2/docs/aclnnBinaryCrossEntropyWithLogitsBackward.md调用样例experimental/loss/sigmoid_cross_entropy_with_logits_grad_v2/examples/test_aclnn_sigmoid_cross_entropy_with_logits_grad_v2.cppACLNN 接口实现experimental/loss/sigmoid_cross_entropy_with_logits_grad_v2/op_host/op_api/aclnn_binary_cross_entropy_with_logits_backward.cpp算子 IR 定义experimental/loss/sigmoid_cross_entropy_with_logits_grad_v2/op_host/sigmoid_cross_entropy_with_logits_grad_v2_def.cppTiling 实现experimental/loss/sigmoid_cross_entropy_with_logits_grad_v2/op_host/sigmoid_cross_entropy_with_logits_grad_v2_tiling.cppAscendC 内核experimental/loss/sigmoid_cross_entropy_with_logits_grad_v2/op_kernel/sigmoid_cross_entropy_with_logits_grad_v2.cpp通用机制两段式接口 docs/zh/context/two_phase_api.md、ACLNN 返回码 docs/zh/context/aclnn_return_code.md、编译运行样例 docs/zh/context/compile_and_run_sample.md【免费下载链接】ops-nn本项目是CANN提供的神经网络类计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-nn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考