CANN ops-nn SoftMarginLoss 算子详解:aclnn 两段式接口调用、归约逻辑与 NPU 实现原理
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' 时,逐元素损失为:
当 reduction 为 'mean' 或 'sum' 时:
其中:
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、targetbroadcast 后的 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。
编译与运行
具体编译与运行过程参考仓库的 编译与运行样例,核心步骤如下:
- 准备调用代码(*.cpp)与编译脚本(CMakeLists.txt),CMakeLists 中需链接
libascendcl.so、libnnopbase.so、libopapi_math.so、libopapi_nn.so并包含${ASCEND_PATH}/include与${ASCEND_PATH}/include/aclnn头文件目录; - 安装 CANN 软件后执行
source ${INSTALL_DIR}/set_env.sh生效环境变量; - 编译并运行:
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 接口的核心实现,其计算图构建流程为:
- 参数校验(
CheckParams); - 空 Tensor 快速路径(
SoftMarginLossEmptyTensorCompute); - 通过
l0op::Contiguous将self、target转为连续 Tensor; - 通过
op::PromoteType计算二者的隐式类型提升类型,再l0op::Cast分别转换,保证后续计算在高精度类型上进行; - 若
self与targetshape 不同,先经BroadcastInferShape推导广播后 shape,再l0op::BroadcastTo拉伸; reduction非'none'时,将广播后的输入Reshape为一维(元素总数),为全量归约做准备;- 调用
l0op::SoftMarginLoss(selfBroadcast, targetBroadcast, reductionStr, executor)构建底层算子节点(op_api/soft_margin_loss.cpp),reduction='none'时输出与输入同 shape,否则输出为 0 维 scalar; - 将计算结果
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 测试:
- L2 单测(tests/ut/op_host/op_api/test_aclnn_soft_margin_loss_l2.cpp):覆盖 self/target/out 为空指针时的
ACLNN_ERR_PARAM_NULLPTR返回、FP32/BF16 正常路径、DOUBLE 类型被拒(ACLNN_ERR_PARAM_INVALID)、空 Tensor 在三种 reduction 下的边界行为等; - L0 单测:位于 tests/ut/op_host/op_api/test_aclnn_soft_margin_loss_l0.cpp;
- ATK ST 测试:见 tests/st/aclnnSoftMarginLoss/atk_aclnnSoftMarginLoss.json,共 201 个用例,覆盖 BF16/FP16/FP32 三种 dtype、1~7 维 shape(含大量含 1 维、非对齐维度的广播型 shape)、reduction 取 0/1/2 的组合,数据取值范围 -5, 5],以
torch.nn.SoftMarginLoss为基准做精度对齐([executor_aclnnSoftMarginLoss.py 中通过torch.nn.SoftMarginLoss(reduction=...)计算参考输出)。
约束与使用建议
- 当前仓库 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 的接入,并理解其底层数值稳定性设计与归约实现路径。