CANN ops-nn 算子详解：aclnnNLLLoss 负对数似然损失（NLL Loss）两段式接口开发指南

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

导读

aclnnNLLLoss是 CANN 神经网络算子库（cann/ops-nn）中用于计算负对数似然损失（Negative Log Likelihood Loss, NLL Loss）的 AscendCL 接口，典型应用场景是与LogSoftmax组合完成多分类任务的损失计算。阅读本文后，你将掌握 NLL Loss 的数学原理与reduction/ignoreIndex语义、两段式 API 的完整调用流程与参数约束、错误码定位方法，以及一份可直接编译运行于 Atlas 训练/推理系列产品的 C++ 调用样例，并结合算子源码理解其 Host 侧校验、Tiling 调度与 Kernel 侧实现。

产品支持情况

根据 算子 README 与接口文档，aclnnNLLLoss支持以下产品系列：

说明：在算子定义文件 nll_loss_def.cpp 中，AICore().AddConfig("ascend910b")与AICore().AddConfig("ascend910_93")分别对应上述平台的 AICore 配置，与文档声明一致。

功能说明与计算公式

接口功能

aclnnNLLLoss计算负对数似然损失值，即对每个样本取其目标类别对应的x值取负，并按类别权重加权。

数学公式

设 $x$ 为输入（self），$y$ 为真实标签（target），$w$ 为类别权重（weight），$N$ 为 batch 大小。当reduction为none时：

$$ \ell(x, y) = L = {l_1,\dots,l_N}^\top, \quad l_n = - w_{y_n} x_{n,y_n}, \quad w_{c} = \text{weight}[c] \cdot \mathbb{1}{c \not= \text{ignoreIndex}}, $$

当reduction不是'none'时：

$$ \ell(x, y) = \begin{cases} \sum_{n=1}^N \frac{1}{\sum_{n=1}^N w_{y_n}} l_n, & \text{if reduction} = \text{mean'}\\ \sum_{n=1}^N l_n, & \text{if reduction} = \text{sum'} \end{cases} $$

同时输出参与计算样本的权重之和：

$$ totalWeight = \sum_{n=1}^N w_{y_n} $$

语义要点

• 当target等于ignoreIndex时，该样本不参与计算（损失与权重均按 0 处理）；
• 未传入weight时，各类别权重按 1 处理；
• mean模式的分母是参与计算样本的权重和，而非样本总数，这与 PyTorch 的 NLLLoss 行为保持一致；
• mean模式下若totalWeight为 0，输出 0（见 Kernel 实现 nll_loss.h 中totalWeight != 0.0f的分支判断）。

函数原型与两段式接口

每个算子分为两段式接口：必须先调用aclnnNLLLossGetWorkspaceSize接口获取计算所需 workspace 大小以及包含了算子计算流程的执行器，再调用aclnnNLLLoss接口执行计算。

aclnnStatus aclnnNLLLossGetWorkspaceSize( const aclTensor *self, const aclTensor *target, const aclTensor *weight, int64_t reduction, int64_t ignoreIndex, aclTensor *out, aclTensor *totalWeightOut, uint64_t *workspaceSize, aclOpExecutor **executor)

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

接口声明位于头文件 aclnn_nll_loss.h，其@domain aclnn_ops_train标注表明该接口归属于训练域算子集合。

aclnnNLLLossGetWorkspaceSize 参数详解

参数说明

数据类型与 shape 的校验规则（源码佐证）

从 Host 侧参数校验实现 aclnn_nll_loss.cpp 可以进一步确认：

• shape 规则：self支持 1D 或 2D；当self为 1D 时target必须为 0D，当self为 2D 时target必须为 1D 且其首维与self首维相等（CheckShape，见 aclnn_nll_loss.cpp）；
• weight 长度：必须为 1D 且长度等于类别数 C（Weight tensor should be defined for all %ld classes）；
• out 形状：reduction == 0且self为 2D 时要求 out 为 (N,)，其余情况要求 out 为单元素张量；
• totalWeightOut 形状：必须为 (1,)；
• 按平台区分 dtype 支持：GetDtypeSupportListBySocVersion按 NPU 架构返回不同支持列表——Atlas A2/A3（DAV_2201/DAV_3510）支持 FLOAT、FLOAT16、BFLOAT16，其余平台仅支持 FLOAT、FLOAT16（见 aclnn_nll_loss.cpp）。

返回值与错误码

aclnnStatus返回状态码，具体参见 aclnn返回码。

第一段接口完成入参校验，出现以下场景时报错：

对应源码中CheckParams依次执行空指针检查（CheckNotNull）、数据类型检查（CheckDtypeValid）、reduction范围检查（CheckReduction，见 aclnn_nll_loss.cpp）与 shape 检查（CheckShape），失败时分别返回上述错误码。

aclnnNLLLoss 参数详解

参数说明

返回值

aclnnStatus：返回状态码，具体参见 aclnn返回码。第二段接口在 aclnn_nll_loss.cpp 中通过CommonOpExecutorRun(workspace, workspaceSize, executor, stream)统一驱动执行器完成实际计算。

约束说明

• 确定性计算：aclnnNLLLoss默认非确定性实现，支持通过aclrtCtxSetSysParamOpt开启确定性计算。更完整的确定性计算说明可参考 确定性计算。
• target 取值：需落在[0, C)区间内，或等于ignoreIndex；越界的非忽略值会在 Kernel 内被钳位（ClampIdx，见 nll_loss.h），因此调用方应保证标签合法。
• 空张量语义：当self为空张量时，第一段接口走空张量分支NLLLossEmptyTensorCompute：none模式直接返回成功；mean模式将 out 填充为 NaN、sum模式填充为 0，且 totalWeightOut 均填充为 0（见 aclnn_nll_loss.cpp）。
• 非连续 Tensor：三个输入均支持非连续 Tensor，第一段接口内部会通过l0op::Contiguous做连续性规整，再按平台策略做类型提升与转换（NLLLossPrepareInputs，见 aclnn_nll_loss.cpp）。非连续张量的通用说明可参考 非连续Tensor。

底层实现：从 Host 校验到 Kernel 计算

aclnnNLLLoss在仓库中是一条完整的「API → Host 侧 Tiling → AICore Kernel」算子链路，以下从源码结构看其整体实现：

1. 算子定义（OpDef）：nll_loss_def.cpp 定义了x（必选，FP16/FP32/BF16）、target（必选，INT32/INT64）、weight（可选）、y与total_weight两个输出，属性reduction默认"mean"、ignore_index默认-100，格式全部为 ND。
2. Shape/DataType 推导：nll_loss_infershape.cpp 中InferShapeNllLoss依据reduction决定y的形状——为"none"时与 target 形状一致，否则为 (1,)；total_weight恒为 (1,)。输出数据类型与x保持一致。
3. Tiling 调度：nll_loss_tiling.cpp 根据x的数据类型选择调度模式（FP16→模式0、FP32→模式1、BF16→模式2），再按rowNum × (classNum × 元素大小 + 等效计算开销)估算总工作量并切分 AIV Core 数量、每核行数与 UB tile 行数；reduction与ignoreIndex在此处被解析为整数（none=0/mean=1/sum=2）写入 NllLossTilingData。workspace 大小由系统库 workspace、跨核同步区（32 × usedCoreNum）与跨核归约区（2 × 32 × usedCoreNum）三部分组成。
4. Kernel 计算：nll_loss.cpp 按调度模式模板化实例化half/float两种 Kernel，核心逻辑在 nll_loss.h 的NllLossKernel中：每个核按行分片处理，target为 INT64 时先 Cast 为 INT32；通过CompareScalar与ignoreIndex比较生成掩码，被忽略样本的损失与权重置 0；reduction == none时逐行写出损失，否则在 UB 内ReduceSum累加；多核场景通过 workspace 中的分段缓冲执行跨核归约，最终由 0 号核计算mean（损失/总权重）或sum并写出y与total_weight。

从源码结构可以推断，该实现采用「标量路径 + 向量路径」双模式：当每个核处理行数达到阈值（VEC_THRESHOLD = 128）时走RunVector的Gather/Select向量化路径，否则走逐行标量路径，兼顾小 batch 与大 batch 场景的 UB 利用率。

调用示例

以下示例完整演示了两段式接口的调用流程，示例代码与仓库中的 test_aclnn_nll_loss.cpp 保持一致（该样例与接口文档示例内容等价），具体编译和执行过程可参考 编译与运行样例。

#include <iostream> #include <vector> #include "acl/acl.h" #include "aclnnop/aclnn_nll_loss.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_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret); // 2. 构造输入与输出，需要根据API的接口自定义构造 std::vector<int64_t> selfShape = {2, 3}; std::vector<int64_t> targetShape = {2}; std::vector<int64_t> weightShape = {3}; std::vector<int64_t> outShape = {2}; std::vector<int64_t> totalWeightOutShape = {1}; void* selfDeviceAddr = nullptr; void* targetDeviceAddr = nullptr; void* weightDeviceAddr = nullptr; void* outDeviceAddr = nullptr; void* totalWeightOutDeviceAddr = nullptr; aclTensor* self = nullptr; aclTensor* target = nullptr; aclTensor* weight = nullptr; aclTensor* out = nullptr; aclTensor* totalWeightOut = nullptr; std::vector<float> selfHostData = {0, 1, 2, 3, 4, 5}; std::vector<int32_t> targetHostData = {0, 2}; std::vector<float> weightHostData = {1.1, 1.2, 1.3}; std::vector<float> outHostData(2, 0); std::vector<float> totalWeightOutHostData(1, 0); int64_t reduction = 0; int64_t ignoreIndex = -100; // 创建self aclTensor ret = CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self); CHECK_RET(ret == ACL_SUCCESS, return ret); // 创建target aclTensor ret = CreateAclTensor(targetHostData, targetShape, &targetDeviceAddr, aclDataType::ACL_INT32, &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); // 创建out aclTensor ret = CreateAclTensor(outHostData, outShape, &outDeviceAddr, aclDataType::ACL_FLOAT, &out); CHECK_RET(ret == ACL_SUCCESS, return ret); // 创建totalWeightOut aclTensor ret = CreateAclTensor(totalWeightOutHostData, totalWeightOutShape, &totalWeightOutDeviceAddr, aclDataType::ACL_FLOAT, &totalWeightOut); CHECK_RET(ret == ACL_SUCCESS, return ret); // 3. 调用CANN算子库API，需要修改为具体的API名称 uint64_t workspaceSize = 0; aclOpExecutor* executor; // 调用aclnnNLLLoss第一段接口 ret = aclnnNLLLossGetWorkspaceSize(self, target, weight, reduction, ignoreIndex, out, totalWeightOut, &workspaceSize, &executor); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnNLLLossGetWorkspaceSize 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); } // 调用aclnnNLLLoss第二段接口 ret = aclnnNLLLoss(workspaceAddr, workspaceSize, executor, stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnNLLLoss 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侧，需要根据具体API的接口定义修改 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和aclScalar，需要根据具体API的接口定义修改 aclDestroyTensor(self); aclDestroyTensor(target); aclDestroyTensor(weight); aclDestroyTensor(out); aclDestroyTensor(totalWeightOut); // 7. 释放device资源，需要根据具体API的接口定义修改 aclrtFree(selfDeviceAddr); aclrtFree(targetDeviceAddr); aclrtFree(weightDeviceAddr); aclrtFree(outDeviceAddr); aclrtFree(totalWeightOutDeviceAddr); if (workspaceSize > 0) { aclrtFree(workspaceAddr); } aclrtDestroyStream(stream); aclrtResetDevice(deviceId); aclFinalize(); return 0; }

示例说明

• 示例构造了一个self形状为 (2, 3)（batch=2、类别数=3）、target形状为 (2)、weight形状为 (3) 的场景，reduction=0（none）表示逐样本输出，因此out形状为 (2,)；
• 按公式，样本 0（target=0）的损失为-1.1 × 0 = 0，样本 1（target=2）的损失为-1.3 × 5 = -6.5；
• 若将reduction改为 1（mean），out形状应为 (1,)，结果为-(0 + 6.5) / (1.1 + 1.3) ≈ -2.7083；改为 2（sum）则结果为-6.5；
• 仓库 tests/ut/op_api/test_aclnn_nll_loss.cpp 中还提供了覆盖多种 dtype、shape 与reduction组合的自动化用例，可作为功能验证参考。

关联阅读

• 接口声明与注释：aclnn_nll_loss.h
• 算子总览与参数总表：README.md（含 NllLoss 算子的贡献记录）
• 2D 输入版本接口：aclnnNLLLoss2d
• 通用概念：两段式接口、aclnn返回码、编译与运行样例、确定性计算、非连续Tensor

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