企业官网建设流程全解析

• 人工智能
• 算子库
• 深度学习
• CANN
• Ascend

本篇技术指南围绕 CANN 神经网络算子库（ops-nn）中SigmoidCrossEntropyWithLogitsV2算子的 aclnn 接口展开，完整讲解aclnnBinaryCrossEntropyWithLogits的数学原理、两段式调用流程、全部入参约束与错误码，并结合仓库源码与示例给出可直接编译运行的 C++ 调用范例。读完本文，你将能够在 NPU 上正确、高效地完成带 Sigmoid 的二分类交叉熵损失（BCEWithLogitsLoss）计算，并理解该算子在接口层与 Kernel 层的分工。

功能说明与数学原理

aclnnBinaryCrossEntropyWithLogits接口用于计算输入 logits（self）与标签（target）之间的二分类交叉熵损失（BCELoss）。与BinaryCrossEntropy不同，该接口的输入是未经 Sigmoid 激活的 logits，Sigmoid 计算被融合进算子内部，因此无需在调用前手动执行Sigmoid，数值稳定性更好，这也是 PyTorch 中BCEWithLogitsLoss的等价语义（见 算子原型定义 中 "Compatible with PyTorch operator BCEWithLogitsLoss" 的说明）。

单标签场景

$$ \ell(self, target) = L = {l_{1},..., l_{n}}^{T} $$

$$ \ell_{n} = -weight_{n}[target_{n} \cdot log(\sigma(self_{n})) + (1 - target_{n}) \cdot log(1 - \sigma(self_{n}))] $$

其中 $\sigma$ 为 Sigmoid 函数。根据reduction参数的不同，最终输出为：

$$ \ell(self, target) = \begin{cases} L, & if\ reduction = none\ mean(L), & if\ reduction = mean\ sum(L), & if\ reduction = sum \end{cases} $$

多标签场景

当每个样本对应多个标签（即target为多维度、每维取值在 0/1 区间）时，按类别逐元素计算：

$$ \ell_c(self, target) = L_c = {l_{1,c},..., l_{n,c}}^{T} $$

$$ \ell_{n,c} = -weight_{n,c}[pos_weight_{n,c} \cdot target_{n,c} \cdot log(\sigma(self_{n,c})) + (1 - target_{n,c}) \cdot log(1 - \sigma(self_{n,c}))] $$

其中pos_weight（正类权重）用于缓解类别不平衡：当pos_weight > 1时提高正类召回率，pos_weight < 1时提高负类召回率。当pos_weight未传入时，其效果等价于取值为 1。

产品支持情况

依据 接口文档 与 算子 README，该算子在不同硬件产品上的支持情况如下：

注意：在Atlas 推理系列产品与Atlas 训练系列产品上，数据类型不支持 BFLOAT16（详见后文参数说明）。

两段式接口与函数原型

与 CANN 单算子 API 的通用调用范式一致，该算子采用两段式接口：必须先调用第一段接口aclnnBinaryCrossEntropyWithLogitsGetWorkspaceSize获取 workspace 大小并完成入参校验，再根据返回的 workspaceSize 在 Device 侧申请内存，最后调用第二段接口aclnnBinaryCrossEntropyWithLogits执行计算。第二段接口不能重复调用。

aclnnStatus aclnnBinaryCrossEntropyWithLogitsGetWorkspaceSize( const aclTensor *self, const aclTensor *target, const aclTensor *weightOptional, const aclTensor *posWeightOptional, int64_t reduction, aclTensor *out, uint64_t *workspaceSize, aclOpExecutor **executor)

aclnnStatus aclnnBinaryCrossEntropyWithLogits( void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, const aclrtStream stream)

其中aclnn为算子接口前缀，BinaryCrossEntropyWithLogits为算子类型名。workspace 指除输入/输出外，算子在 NPU 上完成计算所需的临时内存，其大小由第一段接口计算得出。

aclnnBinaryCrossEntropyWithLogitsGetWorkspaceSize 参数详解

参数说明

产品差异约束：在 Atlas 推理系列产品、Atlas 训练系列产品上，上述所有 Tensor 的数据类型不支持 BFLOAT16。

从源码实现（op_api/aclnn_binary_cross_entropy_with_logits.cpp）看，数据类型支持范围是按 SoC 版本动态区分的：

• ASCEND910_DTYPE_SUPPORT_LIST = {DT_FLOAT, DT_FLOAT16}：旧型号 SoC 仅支持 FLOAT 与 FLOAT16；
• ASCEND910B_DTYPE_SUPPORT_LIST = {DT_FLOAT, DT_FLOAT16, DT_BF16}：SoC 版本位于 ASCEND910B～ASCEND910E 区间或运行于 RegBase 模式时，额外支持 BF16。

返回值与错误码

第一段接口会完成入参校验，返回aclnnStatus状态码（完整定义见 aclnn 返回码说明）。校验失败场景如下：

这些校验逻辑与源码一一对应：CheckNotNull负责空指针检查（self、target、out 任一为空即返回 161001）；CheckDtypeValid负责数据类型检查，并要求out与target类型一致；CheckReduction检查 reduction 必须落在 [0, 2] 区间；CheckShape检查所有 Tensor 维度不超过 8 维、self与targetshape 必须相等、weight/pos_weight必须能通过 broadcast 扩展为 target 形状（其中 shape 为空的 tensor 跳过 broadcast 判断，与 GPU 行为保持一致，单独输出特定值）。

aclnnBinaryCrossEntropyWithLogits 参数说明

该接口返回aclnnStatus状态码，具体参见 aclnn 返回码说明。

源码级实现解析：接口层与 Kernel 层的分工

理解该算子内部实现，有助于在实际项目中合理选择reduction取值并预判性能表现。从仓库源码看，该算子采用了**"融合算子 + 接口层二次规约"**的分层设计：

1. 算子原型与属性定义

算子原型 定义了 4 个输入（predict、target为必选，weight、pos_weight为可选）与 1 个输出loss，属性reduction为字符串类型，取值["none", "mean", "sum"]，默认"mean"；Host 侧算子定义 进一步声明了 AICore 配置（ascend950、ascend350），并开启动态 Shape、动态 Rank 支持。

2. Kernel 仅实现 reduction = "none"

在 tiling 实现 中可以看到关键注释："算子本身仅实现 reduction = none 的情况，其他情况会在接口层面调用其他算子融合实现"。tiling 阶段只接受"none"字符串，并通过模板实例化区分四种组合：

• 同时传入weight与pos_weight：SigmoidCEWithLogitsV2HasTwoWeight
• 仅传入weight：SigmoidCEWithLogitsV2WeightOnly
• 仅传入pos_weight：SigmoidCEWithLogitsV2PosWeightOnly
• 均未传入：SigmoidCEWithLogitsV2

对应 Kernel 实现 中通过if constexpr在编译期展开四种 DAG（数据流图），并复用atvoss/broadcast/broadcast_sch.h的BroadcastSch调度框架完成广播计算，说明该算子底层对 weight/pos_weight 的广播计算做了专门优化。

3. 接口层融合：mean/sum 由 Reduce 算子完成

aclnn 接口实现 中的调用链清晰地展示了完整流程：

1. 连续性转换：对self、target（以及非空的weight、pos_weight）调用l0op::Contiguous，保证后续计算基于连续内存；
2. 类型提升：通过PromoteType求出self与target的统一计算类型，并对各输入执行l0op::Cast；未传入pos_weight时，用l0op::OnesLike生成全 1 张量等价替代；
3. 核心计算：调用融合算子l0op::SigmoidCrossEntropyWithLogitsV2(..., "none")，先求出 reduction = none 下的逐元素损失；
4. 二次规约：当reduction = 1（mean）时调用l0op::ReduceMean、reduction = 2（sum）时调用l0op::ReduceSum，对所有维度求均值/求和（HandleMeanAndSumReductionOut中dimAll覆盖全部维度）；
5. 类型回写：将结果 Cast 回out声明的数据类型，最后通过l0op::ViewCopy拷贝到输出（out可以是非连续 Tensor）。

因此从调用方视角看，reduction取 mean/sum 也能得到正确结果（对应 README 中"直调算子当前仅支持 none 值"指的是 Kernel 层，接口层通过融合完整支持 0/1/2 三种取值），但会额外引入一次规约算子的开销，在高频小 batch 场景下值得关注。

4. 空 Tensor 的特殊处理

源码中HandleEmptyTensor专门处理输入self为空 Tensor 的情况：reduction = none时直接返回空 Tensor；reduction = mean时输出填充 NaN 的结果（与 PyTorch 语义一致），reduction = sum时输出填充 0 的结果。

约束说明

• 确定性计算：aclnnBinaryCrossEntropyWithLogits默认采用确定性实现，即相同输入在多次运行中产生一致输出，便于调试与回归验证（相关背景可参考 确定性计算说明）。
• 维度上限：所有输入 Tensor 的维度（rank）不超过 8。
• 形状一致性：self与target的 shape 必须完全一致；weight、pos_weight的 shape 必须能够 broadcast 到target（广播机制详见 broadcast 关系说明）。
• 输出形状规则：reduction = 0时out的 shape 与self一致；reduction = 1或2时out为标量（shape 为[1]）。
• 类型一致性：target与self类型一致，out与target类型一致。

完整调用示例

以下示例代码完整展示了从资源初始化、Tensor 构造、两段式调用到结果回拷与资源释放的全流程（源码同时收录于仓库 examples/test_aclnn_sigmoid_cross_entropy_with_logits_v2.cpp，具体编译与执行过程请参考 编译与运行样例）：

#include <iostream> #include <vector> #include "acl/acl.h" #include "aclnnop/aclnn_binary_cross_entropy_with_logits.h" #define CHECK_RET(cond, return_expr) \ do { \ if (!(cond)) { \ return_expr; \ } \ } while (0) #define LOG_PRINT(message, ...) \ do { \ printf(message, ##__VA_ARGS__); \ } while (0) int64_t GetShapeSize(const std::vector<int64_t>& shape) { int64_t shapeSize = 1; for (auto i : shape) { shapeSize *= i; } return shapeSize; } int Init(int32_t deviceId, aclrtStream* stream) { // 固定写法，资源初始化 auto ret = aclInit(nullptr); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclInit failed. ERROR: %d\n", ret); return ret); ret = aclrtSetDevice(deviceId); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSetDevice failed. ERROR: %d\n", ret); return ret); ret = aclrtCreateStream(stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtCreateStream failed. ERROR: %d\n", ret); return ret); return 0; } template <typename T> int CreateAclTensor(const std::vector<T>& hostData, const std::vector<int64_t>& shape, void** deviceAddr, aclDataType dataType, aclTensor** tensor) { auto size = GetShapeSize(shape) * sizeof(T); // 调用aclrtMalloc申请Device侧内存 auto ret = aclrtMalloc(deviceAddr, size, ACL_MEM_MALLOC_HUGE_FIRST); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMalloc failed. ERROR: %d\n", ret); return ret); // 调用aclrtMemcpy将Host侧数据拷贝到Device侧内存上 ret = aclrtMemcpy(*deviceAddr, size, hostData.data(), size, ACL_MEMCPY_HOST_TO_DEVICE); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMemcpy failed. ERROR: %d\n", ret); return ret); // 计算连续tensor的strides std::vector<int64_t> strides(shape.size(), 1); for (int64_t i = shape.size() - 2; i >= 0; i--) { strides[i] = shape[i + 1] * strides[i + 1]; } // 调用aclCreateTensor接口创建aclTensor *tensor = aclCreateTensor(shape.data(), shape.size(), dataType, strides.data(), 0, aclFormat::ACL_FORMAT_ND, shape.data(), shape.size(), *deviceAddr); return 0; } int main() { // 1.（固定写法）device/stream初始化，参考acl API手册 // 根据自己的实际device填写deviceId int32_t deviceId = 0; aclrtStream stream; auto ret = Init(deviceId, &stream); // check根据自己的需要处理 CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret); // 2. 构造输入与输出，需要根据API的接口自定义构造 std::vector<int64_t> inputShape = {4, 2}; std::vector<int64_t> targetShape = {4, 2}; std::vector<int64_t> weightShape = {4, 2}; std::vector<int64_t> posWeightShape = {4, 2}; std::vector<int64_t> outShape = {4, 2}; void* inputDeviceAddr = nullptr; void* targetDeviceAddr = nullptr; void* weightDeviceAddr = nullptr; void* posWeightDeviceAddr = nullptr; void* outDeviceAddr = nullptr; aclTensor* input = nullptr; aclTensor* target = nullptr; aclTensor* weight = nullptr; aclTensor* posWeight = nullptr; aclTensor* out = nullptr; std::vector<float> inputHostData = {0.1, 0.1, 0.2, 0.2, 0.3, 0.3, 0.4, 0.4}; std::vector<float> targetHostData = {0.2, 0.2, 0.1, 0.1, 0.2, 0.2, 0.1, 0.1}; std::vector<float> weightHostData = {0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5}; std::vector<float> posWeightHostData = {0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5}; std::vector<float> outHostData = {0, 0, 0, 0, 0, 0, 0, 0}; // 创建input aclTensor ret = CreateAclTensor(inputHostData, inputShape, &inputDeviceAddr, aclDataType::ACL_FLOAT, &input); CHECK_RET(ret == ACL_SUCCESS, return ret); // 创建target aclTensor ret = CreateAclTensor(targetHostData, targetShape, &targetDeviceAddr, aclDataType::ACL_FLOAT, &target); CHECK_RET(ret == ACL_SUCCESS, return ret); // 创建weight aclTensor ret = CreateAclTensor(weightHostData, weightShape, &weightDeviceAddr, aclDataType::ACL_FLOAT, &weight); CHECK_RET(ret == ACL_SUCCESS, return ret); // 创建posWeight aclTensor ret = CreateAclTensor(posWeightHostData, posWeightShape, &posWeightDeviceAddr, aclDataType::ACL_FLOAT, &posWeight); CHECK_RET(ret == ACL_SUCCESS, return ret); // 创建out aclTensor ret = CreateAclTensor(outHostData, outShape, &outDeviceAddr, aclDataType::ACL_FLOAT, &out); CHECK_RET(ret == ACL_SUCCESS, return ret); int64_t reduction = 0; uint64_t workspaceSize = 0; aclOpExecutor* executor; // 3. 调用CANN算子库API：先调第一段接口获取workspace大小 ret = aclnnBinaryCrossEntropyWithLogitsGetWorkspaceSize(input, target, weight, posWeight, reduction, out, &workspaceSize, &executor); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnBinaryCrossEntropyWithLogitsGetWorkspaceSize failed. ERROR: %d\n", ret); return ret); // 根据第一段接口计算出的workspaceSize申请device内存 void* workspaceAddr = nullptr; if (workspaceSize > 0) { ret = aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("allocate workspace failed. ERROR: %d\n", ret); return ret); } // 再调用第二段接口执行计算 ret = aclnnBinaryCrossEntropyWithLogits(workspaceAddr, workspaceSize, executor, stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnBinaryCrossEntropyWithLogits failed. ERROR: %d\n", ret); return ret); // 4.（固定写法）同步等待任务执行结束 ret = aclrtSynchronizeStream(stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSynchronizeStream failed. ERROR: %d\n", ret); return ret); // 5. 获取输出的值，将Device侧内存上的结果拷贝至Host侧 auto size = GetShapeSize(outShape); std::vector<float> resultData(size, 0); ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]), outDeviceAddr, size * sizeof(resultData[0]), ACL_MEMCPY_DEVICE_TO_HOST); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("copy result from device to host failed. ERROR: %d\n", ret); return ret); for (int64_t i = 0; i < size; i++) { LOG_PRINT("result[%ld] is: %f\n", i, resultData[i]); } // 6. 释放aclTensor aclDestroyTensor(input); aclDestroyTensor(target); aclDestroyTensor(weight); aclDestroyTensor(posWeight); aclDestroyTensor(out); // 7. 释放device资源 aclrtFree(inputDeviceAddr); aclrtFree(targetDeviceAddr); aclrtFree(weightDeviceAddr); aclrtFree(posWeightDeviceAddr); aclrtFree(outDeviceAddr); if (workspaceSize > 0) { aclrtFree(workspaceAddr); } aclrtDestroyStream(stream); aclrtResetDevice(deviceId); aclFinalize(); return 0; }

示例要点解读

• 两段式调用顺序不可颠倒：必须先GetWorkspaceSize再执行；workspaceSize可能为 0（例如空 Tensor 场景下直接返回），此时无需申请 workspace 内存，示例中的if (workspaceSize > 0)判断覆盖了该边界。
• Tensor 构造与清理成对出现：aclrtMalloc申请的 Device 内存与aclCreateTensor创建的aclTensor对象必须在最后分别用aclrtFree与aclDestroyTensor释放，避免显存与句柄泄漏。
• reduction 取值扩展：示例中reduction = 0输出与输入同 shape 的逐元素损失；若改为 1 或 2，需将outShape调整为{1}（标量输出）。
• 非连续 Tensor 支持：接口允许传入非连续 Tensor，内部会通过Contiguous自动做连续性转换，示例中展示的 strides 计算是构造连续 Tensor 的标准写法；非连续 Tensor 的相关语义可参考 非连续 Tensor 说明。

测试与验证路径

仓库为该算子提供了完整的测试与配置资产，可用于功能验证与回归：

• UT 测试：op_api 单测 覆盖接口调用层面的正确性；tiling 单测 覆盖 Host 侧 tiling 逻辑。
• ST 测试：执行器用例 与配套的 ATK 配置 用于端到端功能验收。
• 二进制配置：ascend350 配置 与 ascend950 配置 定义了不同 dtype 组合（float16/float32/bfloat16 输入与输出）对应的 kernel 二进制，可见算子对"输入 float16 输出 float32"这类精度提升场景有专门的 kernel 变体支持。

小结

aclnnBinaryCrossEntropyWithLogits是 CANN ops-nn 中实现带 Sigmoid 融合的二分类交叉熵损失的高效接口，其"Kernel 只算 none、mean/sum 由接口层 Reduce 融合"的分层设计兼顾了 kernel 复用与接口语义完整性。使用时重点把握三点：严格遵守两段式调用顺序、保证self/targetshape 与类型一致、理解reduction三种取值对应的输出 shape 规则。结合仓库中提供的示例与测试用例，开发者可以快速在 Atlas 训练/推理系列产品上落地 BCEWithLogitsLoss 相关的训练与推理场景。

• 人工智能
• 算子库
• 深度学习
• CANN
• Ascend