CANN ops-nn SoftMarginLoss 算子详解:aclnn 两段式接口调用、归约逻辑与 NPU 实现原理

原创2026-09-22 18:09:181,613 阅读
文章标签:人工智能深度学习算子库高性能计算模型量化AscendCANN

CANN ops-nn SoftMarginLoss 算子详解:aclnn 两段式接口调用、归约逻辑与 NPU 实现原理

SoftMarginLoss 是 CANN ops-nn 算子库中用于计算二分类逻辑损失(Binary Classification Logistic Loss)的损失函数算子,对应 PyTorch 的 torch.nn.SoftMarginLoss。本文以 loss/soft_margin_loss/README.md 为主线,结合同目录下的 aclnnSoftMarginLoss 接口文档、完整可运行的 aclnn 调用示例 以及 op_api / op_host / op_kernel 各层源码与测试用例,系统讲解该算子的数学定义、参数约束、两段式接口调用流程、NPU 底层实现与边界行为,帮助读者在 Atlas 系列 NPU 上正确、高效地使用 SoftMarginLoss。

产品支持情况

SoftMarginLoss 算子在当前 ops-nn 仓库中的产品支持矩阵如下(与 README 及 aclnnSoftMarginLoss 文档 保持一致):

产品 是否支持
Ascend 950PR / Ascend 950DT √
Atlas A3 训练系列产品 / Atlas A3 推理系列产品 √
Atlas A2 训练系列产品 / Atlas A2 推理系列产品 √
Atlas 200I/500 A2 推理产品 ×
Atlas 推理系列产品 √
Atlas 训练系列产品 √

从源码看,算子注册中只显式声明了 ascend950 的 AICore 配置(见 op_host/soft_margin_loss_def.cpp),而 A3 / A2 / 910 / 310P 等平台通过上层框架的 tiling 分发与 kernel 匹配机制完成支持;Atlas 200I/500 A2 推理产品(310B)不在支持范围内。

功能说明与数学定义

算子功能

SoftMarginLoss 用于计算输入张量 self 与真实标签 target 之间的二分类逻辑损失。self 为模型输出(未经过激活的分数/logits),target 为取值为 +1 或 -1 的真实标签。其本质是对逐元素项 L 进行归约(reduction):reduction 指定应用到输出的归约方式,支持 'none'、'mean'、'sum' 三种取值。

计算公式

当 reduction 为 'none' 时,逐元素损失为:

out(self,target)=L=log⁡(1+exp⁡(−target[i]⋅self[i]))\text{out}(self,target)=L=\log(1+\exp(-target[i]\cdot self[i]))

当 reduction 为 'mean' 或 'sum' 时:

out(self,target)={mean⁡(L),if reduction=’mean’sum⁡(L),if reduction=’sum’\text{out}(self,target)=\begin{cases} \operatorname{mean}(L), & \text{if reduction} = \text{'mean'}\\ \operatorname{sum}(L), & \text{if reduction} = \text{'sum'} \end{cases}

其中:

  • self:输入张量(公式中的预测分数);
  • target:真实标签张量(公式中的标签,取值通常为 +1 或 -1)。

与 Softplus 的一致性及数值稳定性

从 op_kernel/arch35/soft_margin_loss_dag.h 的算子 DAG 可以看出,NPU kernel 并不是直接按 log(1+exp(-x)) 逐项计算,而是将其改写为数值上更稳定的等价形式:

L[i] = max(0, -target*self) + log1p(exp(-|target*self|))

其中 log1p 采用与 SoftplusV2 对齐的精度补偿实现:当 1 + e 在浮点下舍入为 1 时直接返回 e,否则用 log(1+e) * e / ((1+e) - 1) 补偿舍入误差(见 soft_margin_loss_dag.h 中 OpAddOneEqOne、OpCompensatedLog、OpLog1p 等节点)。这种写法避免了 exp(-x) 极大/极小时 log(1+exp(-x)) 直接求值的溢出与精度损失,与 PyTorch CPU 的 SoftMarginLoss 语义保持一致。

参数说明

aclnn 接口层参数

参数名 输入/输出/属性 描述 数据类型 数据格式
self 输入 公式中的 self,表示输入张量 BFLOAT16、FLOAT16、FLOAT32 ND
target 输入 公式中的 target,表示真实标签 BFLOAT16、FLOAT16、FLOAT32 ND
loss 输出 self 与 target 经 soft_margin_loss 计算得到的损失值输出 FLOAT16、BFLOAT16、FLOAT32 ND
reduction 属性 逐元素损失值的归约参数,支持 'none'、'mean'、'sum' STRING -

在 aclnn 接口(aclnnSoftMarginLoss)中,reduction 以 int64_t 数值形式传入,映射关系为:

reduction 数值 对应字符串 行为
0 'none' 不应用归约,逐元素输出损失
1 'mean' 输出总和除以元素个数
2 'sum' 输出求和

该映射在 op_api/aclnn_soft_margin_loss.cpp(REDUCTION_NONE_NUM/MEAN_NUM/SUM_NUM)与 op_host tiling 层的 STR_2_INT 映射表(op_host/arch35/soft_margin_loss_tiling_arch35.cpp)中均有体现;tiling 侧也会对非法 reduction 值报错(仅接受 none、sum、mean)。

shape 与 broadcast 约束

  • self 与 target 的 shape 需要满足 broadcast 关系,维度范围为 1~8 维;
  • 数据类型需满足二者之间的隐式类型推导规则;
  • 当 reduction='none' 时,out 的 shape 需与 self、target broadcast 后的 shape 一致;当 reduction 为 'mean' 或 'sum' 时,out 为 0 维 scalar tensor(见 aclnn_soft_margin_loss.cpp 的 CheckShape 实现);
  • self、target、out 均支持非连续 Tensor(底层通过 Contiguous 与 ViewCopy 处理)。

从 op_host/soft_margin_loss_infershape.cpp 可以看到 GE 图模式下的 shape 推导逻辑:当 reduction='none' 时输出 shape 等于输入 shape,否则输出维度数置 0(scalar);同时该处要求 self 与 target 的原始 shape 相同。需要说明的是,aclnn 单算子调用场景下 self/target shape 不同时会在 op_api 层先做 BroadcastTo 再进入 kernel,因此两种调用方式对 shape 的要求存在差异,这也是 aclnn 文档中强调两者需满足 broadcast 关系的原因。

第一段接口参数(aclnnSoftMarginLossGetWorkspaceSize)

参数名 输入/输出 描述 数据类型 维度
self(aclTensor*) 输入 公式中的输入 self FLOAT、FLOAT16、BFLOAT16 1~8
target(aclTensor*) 输入 公式中的输入 target FLOAT、FLOAT16、BFLOAT16 1~8
reduction(int64_t) 输入 0('none') / 1('mean') / 2('sum') INT64 -
out(aclTensor*) 输出 公式中的输出损失 out FLOAT、FLOAT16、BFLOAT16 1~8
workspaceSize(uint64_t*) 输出 需要在 Device 侧申请的 workspace 大小 - -
executor(aclOpExecutor**) 输出 包含算子计算流程的 op 执行器 - -

第二段接口参数(aclnnSoftMarginLoss)

参数名 输入/输出 描述
workspace 输入 在 Device 侧申请的 workspace 内存地址
workspaceSize 输入 workspace 大小,由第一段接口获取
executor 输入 op 执行器,包含算子计算流程
stream 输入 指定执行任务的 Stream

两段式接口调用说明

SoftMarginLoss 遵循 CANN 单算子 API 的两段式接口调用模型:必须先调用 aclnnSoftMarginLossGetWorkspaceSize 获取计算所需的 workspace 大小与执行器,再调用 aclnnSoftMarginLoss 执行计算。第二段接口不能重复调用,否则会出现异常。

两段接口的函数原型如下:

aclnnStatus aclnnSoftMarginLossGetWorkspaceSize(
  const aclTensor* self,
  const aclTensor* target,
  int64_t reduction,
  aclTensor* out,
  uint64_t* workspaceSize,
  aclOpExecutor** executor)
aclnnStatus aclnnSoftMarginLoss(
  void* workspace,
  uint64_t workspaceSize,
  aclOpExecutor* executor,
  aclrtStream stream)

第一段接口的校验与返回值

第一段接口完成入参校验,常见报错场景如下(错误码定义可参考 aclnn 返回码说明):

返回值 错误码 描述
ACLNN_ERR_PARAM_NULLPTR 161001 传入的 self、target 或 out 是空指针
ACLNN_ERR_PARAM_INVALID 161002 self、target 或 out 的数据类型不在支持范围之内
ACLNN_ERR_PARAM_INVALID 161002 self 和 target 的 shape 不满足 broadcast 规则,或 broadcast 后的 shape 与 out 不一致

上述校验在 op_api/aclnn_soft_margin_loss.cpp 的 CheckParams 中依次执行:空指针检查(CheckNotNull3Tensor)→ 数据类型检查(CheckDtypeValid,支持列表见 aclnn_soft_margin_loss.cpp,不同芯片型号支持列表有差异)→ shape 检查 → 格式检查(Ascend 950 上拒绝私有格式,且 FORMAT_FRACTAL_NZ 会给出精度告警)。

空 Tensor 的边界处理

从 op_api/aclnn_soft_margin_loss.cpp 的 SoftMarginLossEmptyTensorCompute 可以看出,当 self 或 target 为空 Tensor 时:

  • reduction='none':返回空 Tensor;
  • reduction='mean':填充 NAN(0/0 语义);
  • reduction='sum':填充 0。

该边界行为同样被 tests/ut/op_host/op_api/test_aclnn_soft_margin_loss_l2.cpp 中的空 Tensor 用例覆盖。

完整调用示例与编译运行

仓库中提供了可直接参考的完整示例代码 examples/test_aclnn_soft_margin_loss.cpp,其核心流程分为七个步骤:设备初始化 → 构造输入输出 Tensor → 两段式 API 调用 → 同步等待 → 回拷结果 → 释放 Tensor → 释放设备资源。

示例使用 self = {0.3, 0.7, 0.5, 0.5}、target = {-1, 1, 1, -1}、reduction = 0('none'),输出 shape 为 {2, 2}。按公式手算可验证:

i self[i] target[i] -target[i]*self[i] L = log(1+exp(-target*self))
0 0.3 -1 0.3 ≈ 0.8544
1 0.7 1 -0.7 ≈ 0.4032
2 0.5 1 -0.5 ≈ 0.4741
3 0.5 -1 0.5 ≈ 0.9741

核心调用代码

#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_soft_margin_loss.h"

// ... 省略 Init / CreateAclTensor 等固定写法 ...

int main() {
  // 1. device/stream 初始化(固定写法)
  int32_t deviceId = 0;
  aclrtStream stream;
  auto ret = Init(deviceId, &stream);

  // 2. 构造输入与输出
  std::vector<int64_t> selfShape = {2, 2};
  std::vector<int64_t> targetShape = {2, 2};
  std::vector<int64_t> outShape = {2, 2};
  void* selfDeviceAddr = nullptr;
  void* targetDeviceAddr = nullptr;
  void* outDeviceAddr = nullptr;
  aclTensor* self = nullptr;
  aclTensor* target = nullptr;
  aclTensor* out = nullptr;
  std::vector<float> selfHostData = {0.3, 0.7, 0.5, 0.5};
  std::vector<float> targetHostData = {-1, 1, 1, -1};
  std::vector<float> outHostData = {0, 0, 0, 0};
  int64_t reduction = 0;  // 0:'none' 1:'mean' 2:'sum'

  // 创建 self / target / out 三个 aclTensor(内部完成 H2D 拷贝)
  ret = CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self);
  ret = CreateAclTensor(targetHostData, targetShape, &targetDeviceAddr, aclDataType::ACL_FLOAT, &target);
  ret = CreateAclTensor(outHostData, outShape, &outDeviceAddr, aclDataType::ACL_FLOAT, &out);

  // 3. 调用第一段接口:获取 workspace 大小与执行器
  uint64_t workspaceSize = 0;
  aclOpExecutor* executor;
  ret = aclnnSoftMarginLossGetWorkspaceSize(self, target, reduction, out, &workspaceSize, &executor);

  // 根据 workspaceSize 申请 device 侧内存
  void* workspaceAddr = nullptr;
  if (workspaceSize > 0) {
    ret = aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
  }

  // 调用第二段接口执行计算
  ret = aclnnSoftMarginLoss(workspaceAddr, workspaceSize, executor, stream);

  // 4. 同步等待任务执行结束
  ret = aclrtSynchronizeStream(stream);

  // 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);
  for (int64_t i = 0; i < size; i++) {
    LOG_PRINT("result[%ld] is: %f\n", i, resultData[i]);
  }

  // 6. 释放 aclTensor
  aclDestroyTensor(self);
  aclDestroyTensor(target);
  aclDestroyTensor(out);

  // 7. 释放 device 资源
  aclrtFree(selfDeviceAddr);
  aclrtFree(targetDeviceAddr);
  aclrtFree(outDeviceAddr);
  if (workspaceSize > 0) {
    aclrtFree(workspaceAddr);
  }
  aclrtDestroyStream(stream);
  aclrtResetDevice(deviceId);
  aclFinalize();
  return 0;
}

完整代码(含 Init、CreateAclTensor、CHECK_RET 宏等辅助实现)请直接查看 examples/test_aclnn_soft_margin_loss.cpp。

编译与运行

具体编译与运行过程参考仓库的 编译与运行样例,核心步骤如下:

  1. 准备调用代码(*.cpp)与编译脚本(CMakeLists.txt),CMakeLists 中需链接 libascendcl.so、libnnopbase.so、libopapi_math.so、libopapi_nn.so 并包含 ${ASCEND_PATH}/include 与 ${ASCEND_PATH}/include/aclnn 头文件目录;
  2. 安装 CANN 软件后执行 source ${INSTALL_DIR}/set_env.sh 生效环境变量;
  3. 编译并运行:
mkdir -p build && cd build
cmake ../ -DCMAKE_CXX_COMPILER=g++ -DCMAKE_SKIP_RPATH=TRUE
make
cd bin
./opapi_test

运行成功后终端会逐行打印 result[0] is: ... 形式的输出。若执行报错,可使用 aclGetRecentErrMsg 接口获取具体异常信息。

源码实现深度解析

op_api 层:输入预处理与隐式类型提升

op_api/aclnn_soft_margin_loss.cpp 是 aclnn 接口的核心实现,其计算图构建流程为:

  1. 参数校验(CheckParams);
  2. 空 Tensor 快速路径(SoftMarginLossEmptyTensorCompute);
  3. 通过 l0op::Contiguous 将 self、target 转为连续 Tensor;
  4. 通过 op::PromoteType 计算二者的隐式类型提升类型,再 l0op::Cast 分别转换,保证后续计算在高精度类型上进行;
  5. 若 self 与 target shape 不同,先经 BroadcastInferShape 推导广播后 shape,再 l0op::BroadcastTo 拉伸;
  6. reduction 非 'none' 时,将广播后的输入 Reshape 为一维(元素总数),为全量归约做准备;
  7. 调用 l0op::SoftMarginLoss(selfBroadcast, targetBroadcast, reductionStr, executor) 构建底层算子节点(op_api/soft_margin_loss.cpp),reduction='none' 时输出与输入同 shape,否则输出为 0 维 scalar;
  8. 将计算结果 Cast 回 out 的数据类型,再通过 l0op::ViewCopy 写入 out(支持非连续输出 Tensor)。

op_host 层:shape 推导与 tiling 分发

  • shape/数据类型推导:见 op_host/soft_margin_loss_infershape.cpp,输出数据类型继承自输入,'none' 时输出 shape 同输入、否则为 0 维;
  • 算子注册:见 op_host/soft_margin_loss_def.cpp,输入 input_x/input_y、输出 output_z 均支持 BF16/FP16/FP32 与 ND 格式,reduction 属性为可选字符串、默认 'mean',AICore 配置开启动态编译、动态 rank、动态 shape 支持;
  • tiling:见 op_host/arch35/soft_margin_loss_tiling_arch35.cpp,根据 reduction 字符串决定走 Elementwise('none')还是 Reduce('mean'/'sum')tiling 路径;'none' 路径会申请固定大小(16MB,见 soft_margin_loss_tiling_arch35.cpp 的 ASCEND_WORKSPACE)的 workspace;tiling 同时校验输入 dtype 必须相同、shape 必须相同,并生成包含 patternID、reduction、dtype 信息的 tiling key。

op_kernel 层:AICore 上的向量化实现

op_kernel/soft_margin_loss.cpp 中的 kernel 根据 Reduction 模板参数分流:

  • Reduction == 0(none):使用 ElementwiseSch 逐元素调度,DAG 为 SoftMarginLossOp;
  • Reduction == 1(sum):使用 ReduceSch,DAG 为 SoftMarginLossSumDag,先逐元素计算 L 再 PairwiseReduceSumOp 求和;
  • Reduction == 2(mean):使用 ReduceSch,DAG 为 SoftMarginLossMeanDag,ReduceSumOp 求和后乘以 meanVar(1/N 均值系数)得到均值。

三种 DAG 共用同一套逐元素计算子图(OpMulTx → OpNegTx/OpAbsTx → OpExp → 精度补偿 OpLog1p → OpMax → OpResult),mean/sum 路径额外启用 L2 级内存优化(MemCfg = MemOptCfg<MemLevel::LEVEL_2>),详见 op_kernel/arch35/soft_margin_loss_dag.h。

确定性计算

aclnnSoftMarginLoss 文档 明确说明 aclnnSoftMarginLoss 默认采用确定性实现,即相同输入在多次执行下结果可复现,这对训练调试与单元测试比对具有重要意义。

测试与验证

仓库为 SoftMarginLoss 提供了 L0/L2 两级单测与 ATK 框架的 ST 测试:

约束与使用建议

  • 当前仓库 README 中 SoftMarginLoss 的约束说明为“无”,但实际使用中仍须遵循接口文档中的 dtype/shape/broadcast 限制,例如 self 与 target 数据类型需满足隐式类型推导关系、维度范围为 1~8;
  • target 语义上应取值为 +1 / -1(对应二分类正负样本),示例与 ST 用例均在 [-5, 5] 范围内取值以覆盖一般情况;
  • reduction 通过 int64_t 传入 aclnn 接口时仅接受 0/1/2,其他值在 tiling 层会被拒绝(soft_margin_loss_tiling_arch35.cpp);
  • Ascend 950 平台拒绝私有数据格式输入,若传入 FORMAT_FRACTAL_NZ 会产生精度告警日志,建议统一使用 ND 格式。

通过本文的公式推导、参数说明、完整示例与源码级剖析,开发者可以在 Atlas 训练/推理系列及 Ascend 950 产品上直接套用 examples/test_aclnn_soft_margin_loss.cpp 快速完成 SoftMarginLoss 的接入,并理解其底层数值稳定性设计与归约实现路径。

登录后查看全文
ops-nn