CANN ops-nn SmoothL1LossV2 算子深度解析:从 aclnn 接口调用到 NPU 内核实现
CANN ops-nn SmoothL1LossV2 算子深度解析:从 aclnn 接口调用到 NPU 内核实现
SmoothL1LossV2 是 CANN ops-nn 神经网络算子库中用于计算 SmoothL1(Huber)损失函数的算子,在目标检测、回归任务等需要对离群值保持鲁棒性的训练场景中广泛使用。本文以 loss/smooth_l1_loss_v2/README.md 为主体,结合算子定义、API 实现、Tiling 与内核 DAG 等仓库源码,系统讲解其功能公式、参数约束、两段式 aclnn 调用方式与底层实现原理。读完本文,你将掌握如何在 CANN 环境下通过 aclnnSmoothL1Loss 接口完成 SmoothL1 损失计算,并理解算子从 Host 侧校验到 NPU 侧向量计算的完整链路。
产品支持情况
SmoothL1LossV2 算子在不同产品形态上的支持情况如下表所示:
| 产品 | 是否支持 |
|---|---|
| Ascend 950PR / Ascend 950DT | √ |
| Atlas A3 训练系列产品 / Atlas A3 推理系列产品 | √ |
| Atlas A2 训练系列产品 / Atlas A2 推理系列产品 | √ |
| Atlas 200I/500 A2 推理产品 | × |
| Atlas 推理系列产品 | √ |
| Atlas 训练系列产品 | √ |
从源码看,算子在 op_host/smooth_l1_loss_v2_def.cpp 中通过 OpAICoreConfig 注册了 ascend950 的 AICore 配置,并声明了动态编译、动态 Rank 与动态 Shape 支持能力(DynamicCompileStaticFlag(true)、DynamicRankSupportFlag(true)、DynamicShapeSupportFlag(true)),对应了上表中 950 系列与 Atlas A3/A2 等新一代产品形态的支持范围。
功能说明与计算公式
SmoothL1LossV2 用于计算预测值 x 与真实标签 y 之间的 SmoothL1 损失,其核心思想是对小残差使用平方(MSE)惩罚、对大残差使用线性(L1)惩罚,从而兼顾梯度的稳定性与对离群点的鲁棒性。
对于 Batch 大小为 N 的输入,当 reduction 为 none 时,损失函数定义为:
其中每个元素 的计算方式为:
当 reduction 为 mean 或 sum 时,进一步对逐元素损失做归约:
其中:
- Xn:predictions,预测值;
- Yn:labels/truth,真实标签。
该公式与 PyTorch 的 torch.nn.functional.smooth_l1_loss(其中 beta 对应本算子的 sigma/beta 参数)语义一致。仓库中 tests/assets/golden.py 的 Golden 函数正是通过 torch.nn.functional.smooth_l1_loss(predict_t, label_t, reduction=reduction, beta=sigma) 生成基准结果,用于 ST 测试验证算子数值正确性。
内核计算图与公式的对应关系
从源码结构看,公式在 NPU 侧通过向量指令 DAG 实现。op_kernel/arch35/smooth_l1_loss_v2_dag.h 中给出了三种计算图模板,分别对应 none(逐元素)、sum(求和归约)与 mean(均值归约)三种模式,其注释直接给出了公式等价式:
|xi - yi| < sigma ? (xi - yi) ** 2 * 0.5 / sigma : |xi - yi| - 0.5 * sigma
以逐元素模式 SmoothL1LossV2OpDag 为例,计算流程为:
Vec::CopyIn加载predict与label两路输入,并通过Vec::Cast提升到计算精度类型(FP16/BF16 提升为 FP32);Vec::Sub求差、Vec::Abs取绝对值;Vec::Muls将差值乘以0.5后再与原差值做Vec::Mul,得到 项;Vec::Compare(模式COMPARE_MODE_LT)比较|x_n-y_n|与sigma的大小;Vec::Select(模式SELECT_TENSOR)根据比较结果选择 M SE 分支或 L1 分支;- 最后
Vec::Cast回写输出精度类型并Vec::CopyOut写出。
SmoothL1LossV2SumDag 与 SmoothL1LossV2MeanDag 则在 Select 之后追加 Vec::ReduceSumOp 归约算子,其中 mean 模式再乘上 系数完成平均,实现了公式中 sum/mean 的归约语义。
参数说明
算子级参数(对应 README.md 及 smooth_l1_loss_v2_def.cpp 中的算子定义)如下表:
| 参数名 | 输入/输出/属性 | 描述 | 数据类型 | 数据格式 |
|---|---|---|---|---|
| predict | 输入 | 公式中的 x,表示用于计算 SmoothL1 损失的预测值输入 |
BFLOAT16、FLOAT16、FLOAT32 | ND |
| label | 输入 | 公式中的 y,表示 predict 需要拟合的真实标签值输入 |
BFLOAT16、FLOAT16、FLOAT32 | ND |
| y | 输出 | 表示 predict 与 label 经 smooth_l1_loss_v2 计算得到的损失值输出 | FLOAT16、BFLOAT16、FLOAT32 | ND |
| sigma | 属性 | 控制 smooth_l1_loss_v2 中 MSE 与 L1 损失分界边界的阈值参数 | FLOAT32 | - |
| reduction | 属性 | 表示对逐元素损失值进行均值/求和/无归约的归约参数 | STRING | - |
结合源码可以补充以下实现细节:
- 属性默认值:在 smooth_l1_loss_v2_def.cpp 中,
sigma属性为 OPTIONAL、默认值1.0,reduction属性为 OPTIONAL、默认字符串"mean"。Tiling 侧读取属性时同样以1.0作为 sigma 的空指针回退默认值(见 smooth_l1_loss_v2_tiling_arch35.cpp 中float sigma = (sigmaPtr == nullptr) ? 1.0 : *sigmaPtr;)。 - sigma 取值约束:sigma 必须非负。Tiling 代码会在
sigma < 0时报错,并预计算两个派生系数:MultiplyValue = 1 / sigma(用于 中的除法)与AddsValue = -0.5 * sigma(用于 中的常数项)。当|sigma| < 1e-6时,MultiplyValue被置为 0 以避免除零/溢出。 - reduction 取值范围:Tiling 中通过映射
{"none": 0, "sum": 1, "mean": 2}将字符串属性转换为内部枚举,仅接受none、sum、mean三种取值。
aclnn 两段式接口调用说明
在 CANN 算子库中,SmoothL1LossV2 通过 aclnnSmoothL1Loss 两段式接口对外暴露,接口声明位于 op_api/aclnn_smooth_l1_loss.h,详细参数说明见 docs/aclnnSmoothL1Loss.md。两段式接口的含义是:必须先调用第一段接口获取计算所需 workspace 大小及包含算子计算流程的执行器,再调用第二段接口执行计算。
第一段接口原型:
aclnnStatus aclnnSmoothL1LossGetWorkspaceSize(
const aclTensor* self,
const aclTensor* target,
int64_t reduction,
float beta,
aclTensor* result,
uint64_t* workspaceSize,
aclOpExecutor** executor)
第二段接口原型:
aclnnStatus aclnnSmoothL1Loss(
void* workspace,
uint64_t workspaceSize,
aclOpExecutor* executor,
aclrtStream stream)
aclnnSmoothL1LossGetWorkspaceSize 参数说明
| 参数名 | 输入/输出 | 描述 | 使用说明 | 数据类型 | 数据格式 | 维度(shape) | 非连续Tensor |
|---|---|---|---|---|---|---|---|
| self(aclTensor*) | 输入 | 输入张量,公式中的输入 self | shape 需与 target 满足 broadcast 关系;数据类型需满足与 target 的数据类型推导规则 | FLOAT、FLOAT16、BFLOAT16 | ND、NCL、NCHW、NHWC | 1-8 | √ |
| target(aclTensor*) | 输入 | 真实标签,公式中的输入 y | shape 需与 self 满足 broadcast 关系;数据类型需满足与 self 的数据类型推导规则 | FLOAT、FLOAT16、BFLOAT16 | ND、NCL、NCHW、NHWC | 1-8 | √ |
| reduction(int64_t) | 输入 | 指定要应用到输出的缩减,公式中的参数 reduction | 支持 0(none) / 1(mean) / 2(sum)。none 表示不应用缩减,mean 表示输出的总和除以输出中的元素数,sum 表示输出被求和 |
INT64 | - | - | - |
| beta(float) | 输入 | 计算属性,指定在 L1 和 L2 损失之间切换的数值 | 该值必须是非负的 | FLOAT | - | - | - |
| result(aclTensor*) | 输出 | 公式中输出的损失函数 ℓ(self,target) | 当 reduction 为 none 时,shape 与 self 和 target 的 broadcast 结果一致;当 reduction 为 mean 或 sum 时为 [1];数据类型为 self 和 target 推导后可转换的数据类型 |
FLOAT、FLOAT16、BFLOAT16 | ND、NCL、NCHW、NHWC | 1-8 | √ |
| workspaceSize(uint64_t*) | 输出 | 返回需要在 Device 侧申请的 workspace 大小 | - | - | - | - | - |
| executor(aclOpExecutor**) | 输出 | 返回 op 执行器,包含了算子计算流程 | - | - | - | - | - |
注意:aclnn 接口层使用 beta(float)作为平滑阈值参数,其与算子定义层的 sigma 属性一一对应——在 op_api/aclnn_smooth_l1_loss.cpp 中,l0op::SmoothL1Loss 调用将接口传入的 beta 直接透传为算子属性。
第一段接口入参校验与返回码
第一段接口完成入参校验,出现以下场景时报错:
| 返回值 | 错误码 | 描述 |
|---|---|---|
| ACLNN_ERR_PARAM_NULLPTR | 161001 | 传入的 self、target 或 result 为空指针 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self、target 或 result 的数据类型不在支持范围之内 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self、target 或 result 的 shape 不符合约束 |
| ACLNN_ERR_PARAM_INVALID | 161002 | reduction 不符合约束 |
| ACLNN_ERR_PARAM_INVALID | 161002 | beta 不符合约束 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self 和 target 的数据类型不满足数据类型推导规则 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self 和 target 的 shape 不满足 broadcast 关系 |
| ACLNN_ERR_PARAM_INVALID | 161002 | reduction=0 时,result 的 shape 与 self 和 target 的 broadcast shape 不一致 |
从 aclnn_smooth_l1_loss.cpp 的 CheckParams 实现可以看出校验顺序与逻辑:空指针检查 → 数据类型支持列表检查 → 类型推导(PromoteType)与输出类型可转换性检查 → reduction 取值范围检查(必须落在 [0, 2])→ shape 维度(不超过 8 维)与 broadcast 关系检查 → 格式告警检查 → beta >= 0 检查。
需要特别说明的是数据类型支持列表随芯片架构变化:
// Ascend 910(Atlas 训练系列产品)支持 FP32/FP16
static const std::initializer_list<DataType> ASCEND910_DTYPE_SUPPORT_LIST = {DataType::DT_FLOAT, DataType::DT_FLOAT16};
// Ascend 910B 系列(Atlas A2 等)额外支持 BF16
static const std::initializer_list<DataType> ASCEND910B_DTYPE_SUPPORT_LIST = {DataType::DT_FLOAT, DataType::DT_FLOAT16, DataType::DT_BF16};
aclnnSmoothL1Loss 参数说明
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| workspace | 输入 | 在 Device 侧申请的 workspace 内存地址 |
| workspaceSize | 输入 | 在 Device 侧申请的 workspace 大小,由第一段接口 aclnnSmoothL1LossGetWorkspaceSize 获取 |
| executor | 输入 | op 执行器,包含了算子计算流程 |
| stream | 输入 | 指定执行任务的 Stream |
第二段接口在实现上调用框架能力 CommonOpExecutorRun(workspace, workspaceSize, executor, stream) 完成计算,其返回值同样是 aclnnStatus 状态码。
约束说明
- 确定性计算:
aclnnSmoothL1Loss默认是确定性实现。 - 输入
predict与label需满足 broadcast 关系(接口层),但在算子定义层(smooth_l1_loss_v2_def.cpp)及 Host 侧 InferShape 中,要求两者维度数相同;aclnn 接口层在 shape 不一致时会先调用BroadcastTo将两者广播到同一 shape 后再送入底层算子。 - 空 Tensor 行为:当
self或target为空 Tensor 时,接口层不进入内核计算,而是直接生成结果——reduction=0(none)直接返回、reduction=1(mean)输出填充 NAN、reduction=2(sum)输出填充 0,见EmptyTensorCompute实现。
结合源码的算子实现链路
Host 侧:算子定义与 Shape/Dtype 推导
算子定义文件 smooth_l1_loss_v2_def.cpp 注册了 SmoothL1LossV2 算子:两个 REQUIRED 输入 predict、label,一个 REQUIRED 输出 y,两个 OPTIONAL 属性 sigma(默认 1.0)与 reduction(默认 "mean"),数据类型均为 BF16/FP16/FP32,格式为 ND。
平滑损失 InferShape 实现 的推导规则为:
- 当
reduction为"none"时,输出 shape 直接拷贝predict的 shape; - 否则输出退化为标量(
SetDimNum(0)); - 输出数据类型与
predict保持一致(仅允许 FLOAT/FLOAT16/BFLOAT16)。
Host 侧:Tiling 策略
Tiling 是决定算子如何在 NPU 上切分数据、分配核数的关键环节。smooth_l1_loss_v2_tiling_arch35.cpp 展示了两种 Tiling 路径:
- 逐元素路径(reduction=none):走
ElewiseBaseTiling,FP16/BF16 输入会先 cast 成 FP32 再按SmoothL1LossV2OpDag<half>::OpDag或SmoothL1LossV2OpDag<float>::OpDag做模板 Tiling; - 归约路径(reduction=mean/sum):调用
Tiling4ReduceOp,按输出精度选择SumDag/MeanDag模板;mean 模式下内部使用ReduceSumOp求和后乘以 系数。
此外,当 reduction 为 none 时,Tiling 会申请 16MB 的 workspace(ASCEND_WORKSPACE),并通过 GEN_REDUCE_TILING_KEY 生成包含 Reduction 模式与 Dtype 信息的 TilingKey 以支持编译缓存。
API 层:输入预处理与 broadcast
aclnn_smooth_l1_loss.cpp 的 aclnnSmoothL1LossGetWorkspaceSize 在完成参数校验后,会依次执行以下预处理:
- 对 self/target 调用
Contiguous保证内存连续; - 若两者 shape 不同,通过
BroadcastInferShape推导广播结果并调用BroadcastTo统一 shape; - 按
PromoteType推导结果调用Cast提升精度,并按需做TransData/ReFormat格式转换(当输入为 NCHW/NHWC 且reduction=0且非 regbase 架构时转成 NC1HWC0 参与计算); - 调用
l0op::SmoothL1Loss完成算子执行器构建(InferShape + 加入 AICore 启动列表); - 最后将中间结果
Cast回输出数据类型并ViewCopy到 result 上,从而支持非连续输出 Tensor。
Kernel 侧:向量化计算
内核层面(smooth_l1_loss_v2_dag.h)以 AscendC 向量指令模板描述计算图,通过 Compare + Select 完成公式中的分段选择,归约模式复用 ReduceSumOp 并配合 MemOptCfg<MemLevel::LEVEL_2> 做二级内存优化。从源码结构看,FP16/BF16 输入统一提升到 FP32 计算后再转回原精度输出,这保证了不同精度下公式计算结果与 FP32 基准的一致性。
调用示例与编译运行
完整可运行的调用示例见 examples/test_aclnn_smooth_l1_loss_v2.cpp,其调用流程为:
- 初始化:
aclInit→aclrtSetDevice→aclrtCreateStream; - 构造 Tensor:通过
aclrtMalloc申请 Device 内存、aclrtMemcpy拷贝 Host 数据,并用aclCreateTensor创建self、target、result三个aclTensor(示例 shape 为{2, 2, 7, 7},数据类型 FP16); - 两段式调用:
int64_t reduction = 0; float beta = 1.0; ret = aclnnSmoothL1LossGetWorkspaceSize(self, target, reduction, beta, result, &workspaceSize, &executor); // 根据 workspaceSize 申请 Device 内存 if (workspaceSize > 0) { ret = aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST); } ret = aclnnSmoothL1Loss(workspaceAddr, workspaceSize, executor, stream); - 同步与取数:
aclrtSynchronizeStream后通过aclrtMemcpy将结果从 Device 拷回 Host 并打印; - 资源释放:依次
aclDestroyTensor、aclrtFree、aclrtDestroyStream、aclrtResetDevice、aclFinalize。
编译时需要链接 CANN ACL 与算子库头文件(acl/acl.h、aclnnop/aclnn_smooth_l1_loss.h),在真实 NPU 设备环境下执行;仓库 tests/ut/op_api/test_aclnn_smooth_l1_loss_l2.cpp 与 tests/st/ 目录下的 ST 测试(atk_aclnnSmoothL1Loss.json、executor_aclnnSmoothL1Loss.py)提供了 UT/ST 层面的验证入口,tests/assets/golden.py 则给出了基于 PyTorch 的 Golden 基准。
总结
SmoothL1LossV2 算子是 CANN ops-nn 中对经典 Huber 损失的标准实现:在 API 层通过 aclnnSmoothL1Loss 两段式接口完成参数校验、类型提升、broadcast 与格式预处理;在 Host 层通过 InferShape 与 Tiling 完成 shape 推导和核间切分;在 Kernel 层通过向量指令 DAG(Compare/Select/ReduceSum)高效实现公式计算。理解这一算子的完整链路,有助于你在 CANN 平台上正确、高效地使用 SmoothL1 损失,也为阅读和开发同类逐元素 + 归约型 loss 算子提供了可复用的参考范式。