CANN ops-cv 算子接口详解aclnnUpsampleNearest1dV2 一维最近邻上采样调用指南【免费下载链接】ops-cv本项目是CANN提供的图像处理、目标检测相关的算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-cv导读aclnnUpsampleNearest1dV2 是 CANN ops-cv 开源算子库experimental/image/upsample_nearest3d 模块提供的单算子接口用于对输入信号沿 L 维长度维应用最近邻插值算法进行一维上采样广泛适用于音频波形长度对齐、一维序列特征缩放等场景。本文以 experimental/image/upsample_nearest3d/docs/aclnnUpsampleNearest1dV2.md 为主体结合该算子在仓库中的 op_api 实现、host 端算子定义与单元测试完整讲解接口的功能定义、两段式调用模型、全部参数约束、返回码语义并给出可直接编译运行的最小示例代码帮助开发者快速将一维最近邻上采样能力集成到 NPU 计算流程中。一、功能说明与计算公式该接口对由多个输入通道组成的输入信号应用最近邻插值算法进行上采样。输入 shape 为(N, C, L)时输出 shape 为(N, C, outputSize)其中 N 为 Batch 维度、C 为通道维度、L 为长度维度。与基础接口 aclnnUpsampleNearest1d 相比本接口额外增加了入参scaleL用于显式指定 L 维的空间缩放乘数。开发者应根据实际场景选择合适的接口当需要同时通过输出尺寸与缩放因子两种途径控制输出大小时选用本 V2 接口基础版接口的使用方式可参考 image/resize_nearest_neighbor_v2/docs/aclnnUpsampleNearest1d.md。计算过程遵循最近邻插值的核心思想将输出坐标映射回输入坐标取距离最近的输入点数值作为输出值。具体公式如下$$ out(N, C, l) self(N, C, \min(\lfloor l \times scaleL \rfloor, L-1)), \quad scaleL outputSize[0] / self_L $$即在输出坐标l处先在输入 L 维上计算l * scaleL得到浮点坐标向下取整后与L-1取最小值防止越界然后直接复制该输入位置的值。这一“映射 取整 边界裁剪 值复制”的模式与同目录下三维版本 experimental/image/upsample_nearest3d/docs/aclnnUpsampleNearest3d.md 在 D/H/W 三个方向上的处理逻辑一脉相承。二、产品支持情况接口在当前仓库中的产品支持情况如下产品是否支持Ascend 950PR/Ascend 950DT支持Atlas A3 训练系列产品/Atlas A3 推理系列产品支持Atlas A2 训练系列产品/Atlas A2 推理系列产品支持Atlas 200I/500 A2 推理产品不支持Atlas 推理系列产品支持Atlas 训练系列产品支持需要说明的是不同产品对数据类型的支持存在差异在 Atlas 推理系列产品与 Atlas 训练系列产品上入参self与出参out的数据类型不支持 BFLOAT16。这一点在 op_api 层的实现中亦有印证experimental/image/upsample_nearest3d/op_api/aclnn_upsample_nearest_1d_v2.cpp 中通过GetDtypeSupportList()依据GetCurNpuArch()区分平台Ascend 910BDAV_2201及注册基RegBase架构返回包含DT_BF16的支持列表其余架构返回仅含 FLOAT16、FLOAT、DOUBLE、UINT8 的支持列表。三、函数原型与两段式调用模型与 CANN 其他 aclnn 单算子接口一致本接口遵循两段式接口调用模型必须先调用第一段接口aclnnUpsampleNearest1dV2GetWorkspaceSize获取计算所需的 workspace 大小及包含算子计算流程的执行器再调用第二段接口aclnnUpsampleNearest1dV2执行实际计算。第一段接口原型aclnnStatus aclnnUpsampleNearest1dV2GetWorkspaceSize( const aclTensor *self, const aclIntArray *outputSize, float scaleL, aclTensor *out, uint64_t *workspaceSize, aclOpExecutor **executor)第二段接口原型aclnnStatus aclnnUpsampleNearest1dV2( void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream)两段式设计的核心价值在于第一段接口在 Host 侧完成全部参数校验与计算图算子执行流程的构建并将所需的临时内存大小返回给用户第二段接口则通过传入用户自行申请的 workspace 与 executor在指定 Stream 上异步执行计算从而让用户对 Device 内存的申请与释放拥有完全的控制权。四、aclnnUpsampleNearest1dV2GetWorkspaceSize 参数详解4.1 参数说明第一段接口共 6 个参数其完整语义如下参数名输入/输出描述使用说明数据类型数据格式维度(shape)非连续TensorselfaclTensor*输入表示进行上采样的输入数据对应公式中的self。不支持空 Tensor输入维度必须是 3 维self 的所有维度取值均小于等于 (2^31-1)当数据类型为 DOUBLE、UINT8 时self 的 L 维取值必须同时小于等于 (2^24)。FLOAT32、FLOAT16、BFLOAT16、DOUBLE、UINT8NCL3√outputSizeaclIntArray*输入表示输出 out 在 L 维度上的空间大小。size 为 1且取值大于 0。INT64---scaleLfloat输入表示指定空间大小的乘数对应公式中的scaleL。-----outaclTensor*输出表示进行上采样的输出结果对应公式中的out。不支持空 Tensor数据类型与入参self保持一致out 的所有维度取值均小于等于 (2^31-1)当数据类型为 DOUBLE、UINT8 时out 的 L 维取值必须同时小于等于 (2^24)。FLOAT32、FLOAT16、BFLOAT16、DOUBLE、UINT8NCL3√workspaceSizeuint64_t*输出返回需要在 Device 侧申请的 workspace 大小。-----executoraclOpExecutor**输出返回 op 执行器包含了算子计算流程。-----从源码层面看这些约束在 experimental/image/upsample_nearest3d/op_api/aclnn_upsample_nearest_1d_v2.cpp 的CheckParams校验链中逐项落实校验顺序为空指针检查 → 输入数据类型检查 → self/out 数据类型一致性检查 → shape 检查维度必须为 3、C/L 维非零、outputSize 与 out 的 L 维一致且大于 0→ format 检查self/out 存储格式一致且必须为 NCL。校验通过后若 self 或 out 为空 Tensor接口直接返回ACLNN_SUCCESS并将workspaceSize置 0无需执行实际计算。4.2 返回值与异常场景第一段接口返回aclnnStatus状态码完整返回码定义参见 docs/zh/context/aclnn_return_code.md。本接口在入参校验阶段的主要报错场景如下返回码错误码描述ACLNN_ERR_PARAM_NULLPTR161001传入参数是必选输入、输出或必选属性且是空指针。ACLNN_ERR_PARAM_INVALID161002self、out 的数据类型不在支持的范围之内self、out 的数据类型、数据格式不一致self 的 shape 不是 3 维outputSize 的取值为 0。上述异常路径均有对应的单元测试覆盖详见下文第七节。五、aclnnUpsampleNearest1dV2 参数详解第二段接口负责真正执行计算共 4 个参数参数名输入/输出描述workspace输入在 Device 侧申请的 workspace 内存地址。workspaceSize输入在 Device 侧申请的 workspace 大小由第一段接口 aclnnUpsampleNearest1dV2GetWorkspaceSize 获取。executor输入op 执行器包含了算子计算流程。stream输入指定执行任务的 Stream。返回值同样为aclnnStatus状态码具体参见 docs/zh/context/aclnn_return_code.md。从实现看第二段接口直接调用CommonOpExecutorRun(workspace, workspaceSize, executor, stream)将执行器提交到指定 Stream 上运行。六、约束说明参数self、outputSize、scaleL需要满足如下约束关系即输出 L 维尺寸必须等于输入 L 维尺寸乘以缩放因子后向下取整$$ outputSize \lfloor self_L \times scaleL \rfloor $$确定性计算aclnnUpsampleNearest1dV2 默认为确定性实现即在相同输入与环境下多次执行输出结果保持一致便于结果复现与测试比对。七、调用示例以下为完整的可参考调用代码具体编译与执行流程请参考编译与运行样例。该示例在仓库中的完整版本位于 experimental/image/upsample_nearest3d/examples/test_aclnn_upsample_nearest1d_v2.cpp。#include iostream #include vector #include acl/acl.h #include aclnnop/aclnn_upsample_nearest_1d_v2.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::vectorint64_t shape) { int64_t shape_size 1; for (auto i : shape) { shape_size * i; } return shape_size; } 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::vectorT hostData, const std::vectorint64_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::vectorint64_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_NCL, 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 0, LOG_PRINT(Init acl failed. ERROR: %d\n, ret); return ret); // 2. 构造输入与输出需要根据API的接口自定义构造 std::vectorint64_t selfShape {1, 3, 3}; std::vectorint64_t outShape {1, 3, 6}; void* selfDeviceAddr nullptr; void* outDeviceAddr nullptr; aclTensor* self nullptr; aclTensor* out nullptr; float scaleL 0.0; std::vectorfloat selfHostData {0, 1, 2, 3, 4, 5, 6, 7, 8}; std::vectorint64_t outputSizeHostData {6}; std::vectorfloat outHostData(6); // 创建self aclTensor ret CreateAclTensor(selfHostData, selfShape, selfDeviceAddr, aclDataType::ACL_FLOAT, self); CHECK_RET(ret ACL_SUCCESS, return ret); // 创建outputSize aclIntArray auto outputSizeArray aclCreateIntArray(outputSizeHostData.data(), 1); // 创建out aclTensor ret CreateAclTensor(outHostData, outShape, outDeviceAddr, aclDataType::ACL_FLOAT, out); CHECK_RET(ret ACL_SUCCESS, return ret); // 3. 调用CANN算子库API uint64_t workspaceSize 0; aclOpExecutor* executor; // 调用aclnnUpsampleNearest1dV2第一段接口 ret aclnnUpsampleNearest1dV2GetWorkspaceSize(self, outputSizeArray, scaleL, out, workspaceSize, executor); CHECK_RET(ret ACL_SUCCESS, LOG_PRINT(aclnnUpsampleNearest1dV2GetWorkspaceSize 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;); } // 调用aclnnUpsampleNearest1dV2第二段接口 ret aclnnUpsampleNearest1dV2(workspaceAddr, workspaceSize, executor, stream); CHECK_RET(ret ACL_SUCCESS, LOG_PRINT(aclnnUpsampleNearest1dV2 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::vectorfloat resultData(size, 0); ret aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]), outDeviceAddr, size * sizeof(float), 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(self); aclDestroyIntArray(outputSizeArray); aclDestroyTensor(out); // 7. 释放device资源 aclrtFree(selfDeviceAddr); aclrtFree(outDeviceAddr); if (workspaceSize 0) { aclrtFree(workspaceAddr); } aclrtDestroyStream(stream); aclrtResetDevice(deviceId); aclFinalize(); return 0; }示例整体可分为七个阶段其中第 1、4 阶段设备初始化与 Stream 同步为 AscendCL 固定写法环境初始化aclInit初始化 ACL 运行时aclrtSetDevice绑定指定设备aclrtCreateStream创建执行 Stream。构造输入输出本例将输入 shape 设为{1, 3, 3}N1、C3、L3输出 shape 设为{1, 3, 6}L 维放大 2 倍scaleL传 0.0 表示不直接指定缩放因子此时输出尺寸完全由outputSize即 6决定实际缩放比例由outputSize[0] / self_L推导。CreateAclTensor模板函数完成 Host 数据到 Device 内存的拷贝并依据连续布局自动计算 strides通过aclCreateTensor创建 NCL 格式的 aclTensor。两段式调用先调用aclnnUpsampleNearest1dV2GetWorkspaceSize得到workspaceSize与executor若 workspace 大于 0 则用aclrtMalloc申请 Device 内存再调用aclnnUpsampleNearest1dV2执行计算。同步等待aclrtSynchronizeStream阻塞直至 Stream 上所有任务完成确保结果可读。结果回拷通过aclrtMemcpy将 Device 侧结果拷贝回 Host 侧并逐元素打印。释放 Tensor依次销毁 self、outputSizeArray、out。释放资源释放 Device 内存与 workspace销毁 Stream、复位设备并aclFinalize。八、源码实现原理接口如何落到底层计算深入 experimental/image/upsample_nearest3d/op_api/aclnn_upsample_nearest_1d_v2.cpp 可以看到该 aclnn 接口并非直接调用单一底层算子而是基于 CANN 的 Level0 算子l0op与已有算子进行组合编排其核心流程为形状适配View3dAs4d将 NCL 三维输入转为 NCHW 四维contiguous → unsqueeze(2) → reformatView4dAs5d/View5dAs4d在四维与 NCDHW 五维之间转换将一维上采样问题统一映射为底层 NCDHW 算子的特例D、H 维保持为 1。平台分派依据当前 NPU 架构与数据类型选择计算路径。对 FLOAT16/FLOAT/BF16 等 AICore 支持的数据类型在 Ascend 950 等支持scaleL的架构上直接构造 scales 数组{1.0, 1.0, scaleL}并调用l0op::UpsampleNearest3dNcdhw完成计算在注册基RegBase架构上则复用l0op::ResizeNearestNeighborV2其余 AICore 平台先通过TransDataSpecial转到 NC1HWC0 格式计算后再转回。对 DOUBLE、UINT8 等数据类型则走 AICPU 路径upsampleNearest1dV2AiCpuCompute同样复用l0op::ResizeNearestNeighborV2。结果回写最终通过View4dAs3d与l0op::ViewCopy将计算结果写回用户提供的 out Tensor。在算子底层定义方面experimental/image/upsample_nearest3d/op_host/upsample_nearest3d_def.cpp 注册了UpsampleNearest3d算子输入 x 与输出 y 支持 FLOAT、FLOAT16、BF16、DOUBLE、UINT8 五种数据类型属性包含可选的output_sizeListInt与scale_d/scale_h/scale_wFloat默认 0.0AICore 配置覆盖 ascend910b、ascend910_93、ascend310p、kirinx90、kirin9030、ascend950 等平台。图模式下 shape 推导由 experimental/image/upsample_nearest3d/op_host/upsample_nearest3d_infershape.cpp 完成当output_size非空时直接以 output_size 设置输出 D/H/W 维当仅scales非空时输出维等于输入维乘以对应 scale 后取整两者不能同时为空。九、单元测试验证约束与异常路径的代码级佐证接口的入参校验行为在 experimental/image/upsample_nearest3d/tests/ut/op_api/test_aclnn_upsample_nearest_1d_v2.cpp 中有系统的单测覆盖与文档所述的返回码一一对应空指针校验self 为空、out 为空、outputSize 为空时均返回ACLNN_ERR_PARAM_NULLPTR空 Tensor 处理输入 shape 为{0, 1, 2}时返回ACLNN_SUCCESS空 Tensor 不执行计算而 C 维为 0 的{1, 0, 2}则返回ACLNN_ERR_PARAM_INVALID尺寸校验outputSize 为 0 时返回ACLNN_ERR_PARAM_INVALIDoutputSize 为 6 且与 out 的 L 维匹配时返回成功数据类型校验INT32、INT64 等非支持类型返回ACLNN_ERR_PARAM_INVALIDshape 校验2 维输入返回ACLNN_ERR_PARAM_INVALID。该模块的算子级测试位于 experimental/image/upsample_nearest3d/tests/ut/op_kernel/upsample_nearest3d_data 目录通过gen_data.py生成输入数据、compare_data.py对比输出结果可结合使用验证计算正确性。十、接口家族与选型建议在 experimental/image/upsample_nearest3d/README.md 中该算子模块对外提供三套 aclnn 接口均基于同一个UpsampleNearest3d底层算子实现调用方式分别对应aclnnUpsampleNearest1dV2三维输入(N, C, L)仅沿 L 维上采样新增scaleL入参aclnnUpsampleNearest2dV2沿 H、W 两维上采样aclnnUpsampleNearest3d沿 D、H、W 三维上采样输入格式为 NCDHW。选型时可按数据维度与缩放需求决定若任务仅需处理一维序列如音频帧对齐使用本文的 1dV2 接口若输入为图像二维空间或体数据三维空间则分别选用 2dV2 与 3d 接口。除 aclnn 调用外该算子还支持通过 op_graph/upsample_nearest3d_proto.h 中的算子 IR 以图模式构图调用适用于需要将算子嵌入整图编译执行的场景。【免费下载链接】ops-cv本项目是CANN提供的图像处理、目标检测相关的算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-cv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
