CANN ops-math 算子 aclnnStdMeanCorrection 完全指南：接口原型、参数校验与两段式调用实战

CANN ops-math 算子 aclnnStdMeanCorrection 完全指南接口原型、参数校验与两段式调用实战【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math本文是 CANN 数学类基础计算算子库ops-math中reduce_std_with_mean算子模块的aclnnStdMeanCorrection单算子接口技术指南。该接口用于在 NPU 上沿指定维度一次性完成样本标准差std与均值mean的归约计算语义对应 PyTorch 的torch.std_mean(x, dim, correctioncorrection, keepdimkeepdim)。读完本文你将掌握该算子的计算公式与语义、完整的 aclnn 两段式接口原型与逐参数约束、错误返回码场景以及从设备初始化、张量构造到 workspace 申请与结果回拷的完整可运行调用流程并能结合仓库源码理解其 Two-Pass 内部管线与 Tiling 原理。产品支持情况aclnnStdMeanCorrection在当前仓库中仅支持 Atlas A2 训练系列产品与 Atlas A2 推理系列产品其 L0 内核ReduceStdWithMean的 AICore 配置也只注册了ascend910b见 reduce_std_with_mean_def.cpp其余产品形态暂不支持产品是否支持Ascend 950PR/Ascend 950DT×Atlas A3 训练系列产品/Atlas A3 推理系列产品×Atlas A2 训练系列产品/Atlas A2 推理系列产品√Atlas 200I/500 A2 推理产品×Atlas 推理系列产品×Atlas 训练系列产品×注仓库 READMEREADME.md中记录了该模块两个 L2 API 的产品支持情况其中ReduceStdWithMeanL0 算子同样仅注册ascend910b平台配置。功能说明与计算公式接口功能为计算样本标准差和均值。假设dim为 $i$则对该维度进行计算$N$ 为该维度的 shape。取 $self_{i}$求出该维度上的平均值 $\bar{x_{i}}$计算公式如下$$ \left{ \begin{array} {rcl} meanOut \bar{x_{i}}\ stdOut \sqrt{\frac{1}{max(0, N - \delta N)}\sum_{j0}^{N-1}(self_{ij}-\bar{x_{i}})^2} \end{array} \right. $$其中δN即correction修正值correction0对应总体标准差除以 Ncorrection1对应样本标准差除以 N-correction即 Bessel 修正。当keepdimtrue时reduce 后保留该维度且输出 shape 中该维度值为 1当keepdimfalse时不保留该维度。从源码看内部计算管线从仓库 L2 API 实现 aclnn_std_mean_correction.cpp 看该接口内部是一条Two-Pass两次遍历管线先算均值、再把均值广播回原 shape 计算方差与标准差self ──→ ReduceMean ──→ mean ──→ Broadcast(Expand) ──→ mean(expanded) │ │ └──→ meanOut └──→ ReduceStdWithMean(self, mean) ──→ stdOutReduceMeanmath/reduce_mean与ReduceStdWithMean本模块 L0 kernel都是 L0 算子ReduceStdWithMean接收预计算并已 broadcast 到与self同 shape 的mean计算diff self - mean进而得出方差和标准差预计算均值避免了在 kernel 内重复计算均值这是 Two-Pass 算法的设计意图而非使用限制在 RegBaseAscend 910B 等非 950 平台路径上代码先调用ReduceMean计算均值aclnn_std_mean_correction.cpp随后通过GetExpandMean对均值执行UnsqueezeNdExpand广播到原 shapeaclnn_std_mean_correction.cpp最后调度ReduceStdWithMeankernel 计算标准差对于非连续归约维度归约维不在最内层L2 API 内部会先执行TransposeContiguous将归约维度移到最内层再调度 kernelaclnn_std_mean_correction.cppkeepdimtrue时还会用逆置换把尺寸为 1 的维度还原到正确位置aclnn_std_mean_correction.cpp调用方无需手动 transpose。空张量与边界情况处理源码中对特殊 shape 做了显式处理避免除零与无效输出空张量self-IsEmpty()stdOut、meanOut均填充 NANDealEmptyaclnn_std_mean_correction.cpp归约元素数shapeProd 1且1 correctionstdOut填充 NANDealshapeProdNANaclnn_std_mean_correction.cppcorrection 1且归约元素数shapeProd correctionstdOut填充 INFINITYDealshapeProdINFaclnn_std_mean_correction.cpp。与 aclnnBatchNormStats 的关系本模块还提供配套接口aclnnBatchNormStats对应 BatchNorm 统计量计算均值 标准差倒数1/sqrt(vareps)两者共享同一 L0 kernelReduceStdWithMean仅通过invert属性区分最终输出是sqrt(var)还是1/sqrt(vareps)核心计算路径完全相同。本文聚焦aclnnStdMeanCorrection相关对照可参考 README.md。函数原型两段式接口每个算子分为两段式接口必须先调用第一段aclnnStdMeanCorrectionGetWorkspaceSize获取入参并根据计算流程计算所需 workspace 大小再调用第二段aclnnStdMeanCorrection执行计算。第一段接口原型aclnnStatus aclnnStdMeanCorrectionGetWorkspaceSize( const aclTensor* self, const aclIntArray* dim, int64_t correction, bool keepdim, aclTensor* stdOut, aclTensor* meanOut, uint64_t* workspaceSize, aclOpExecutor** executor)第二段接口原型aclnnStatus aclnnStdMeanCorrection( void* workspace, uint64_t workspaceSize, aclOpExecutor* executor, const aclrtStream stream)接口声明位于 aclnn_std_mean_correction_experimental.h由自定义算子包custom_math导出。aclnnStdMeanCorrectionGetWorkspaceSize 参数说明参数名输入/输出描述使用说明数据类型数据格式维度(shape)非连续TensorselfaclTensor*输入公式中的 self-FLOAT、BFLOAT16、FLOAT16ND-√dimaclIntArray*输入公式中的 dim表示参与计算的维度取值范围为 [-self.dim(), self.dim()-1]且其中的数据不能相同。当 dim 为 nullptr 或 [] 时视为计算所有维度INT64---correctionint64_t输入公式中的 δN 值修正值-----keepdimbool输入公式中 keepdim是否在输出张量中保留输入张量的维度-----stdOutaclTensor*输出公式中 stdOut-FLOAT、BFLOAT16、FLOAT16ND-√meanOutaclTensor*输出公式中 meanOut-FLOAT、BFLOAT16、FLOAT16ND-√workspaceSizeuint64_t*输出返回需要在 Device 侧申请的 workspace 大小-----executoraclOpExecutor**输出返回 op 执行器包含了算子计算流程-----参数细节与源码级约束self支持 1-8 维OP_CHECK_MAX_DIM检查aclnn_std_mean_correction.cpp支持非连续 Tensordim支持负数索引源码中负值会加上selfDimNum转为正索引aclnn_std_mean_correction.cppdim 为 nullptr 或空数组时GetDimArray会内部构造所有维度的数组执行全量归约aclnn_std_mean_correction.cppcorrection必须为非负整数。当 correction 不小于归约维度元素数时方差为 0输出 0std不会除零崩溃对应源码中denom 0时 clamp 为 0 的逻辑reduce_std_with_mean_kernel.hdtype 一致性在非 RegBase 平台self、stdOut、meanOut三者数据类型必须一致OP_CHECK_DTYPE_NOT_MATCH检查aclnn_std_mean_correction.cppAscend 950 平台IsRegBase()允许输入输出数据类型不一致。返回值第一段接口返回aclnnStatus状态码具体参见 aclnn 返回码完成入参校验以下场景会报错返回值错误码描述ACLNN_ERR_PARAM_NULLPTR161001传入的 self、stdOut、meanOut 是空指针时。ACLNN_ERR_PARAM_INVALID161002self、stdOut、meanOut 数据类型不在支持的范围之内。ACLNN_ERR_PARAM_INVALID161002dim 数组中的维度超出 self 的维度范围。ACLNN_ERR_PARAM_INVALID161002dim 数组中元素重复。ACLNN_ERR_PARAM_INVALID161002stdOut 的 shape 出现如下情况会出错keepdim 为 true 时stdOut.shape ! self.shape指定维度 dim 设置为 1 的形状keepdim 为 false 时stdOut.shape ! self.shape去除指定维度 dim 后的形状。ACLNN_ERR_PARAM_INVALID161002meanOut 的 shape 出现如下情况会出错keepdim 为 true 时meanOut.shape ! self.shape指定维度 dim 设置为 1 的形状keepdim 为 false 时meanOut.shape ! self.shape去除指定维度 dim 后的形状。从源码看上述校验依次由CheckParams中的空指针检查CheckNotNull3Tensor、dtype 检查CheckDtypeValid、维度合法性检查CheckDimValid与输出 shape 推导检查CheckShape内部调用OutInferShape按 keepdim 语义推导期望 shape完成aclnn_std_mean_correction.cpp。输出 shape 的推导逻辑与 L0 算子 InferShape 注册reduce_std_with_mean_infershape.cpp保持一致keepDimstrue走ReduceDimsWithKeepDims否则走ReduceDimsWithoutKeepDims。aclnnStdMeanCorrection 参数说明参数名输入/输出描述workspace输入在 Device 侧申请的 workspace 内存地址。workspaceSize输入在 Device 侧申请的 workspace 大小由第一段接口 aclnnStdMeanCorrectionGetWorkspaceSize 获取。executor输入op 执行器包含了算子计算流程。stream输入指定执行任务的 Stream。返回值aclnnStatus返回状态码具体参见 aclnn 返回码。第二段接口内部调用框架统一的CommonOpExecutorRun完成计算下发aclnn_std_mean_correction.cpp。约束说明确定性计算aclnnStdMeanCorrection默认确定性实现相同输入恒产生相同输出。从源码看该算子采用 Pre-computed Mean Two-Pass 统一算法路径kernel 内使用硬件Sub/Mul/ReduceSum树形归约保证精度reduce_std_with_mean_kernel.h。self维度数rank必须在 1 到 8 之间。仅支持 ND 数据格式。半精度精度保护FLOAT16/BFLOAT16 输入在 kernel 内先Cast升精度到 FLOAT32 再执行Sub → Mul → ReduceSumreduce_std_with_mean_kernel.h规避半精度中间累加的精度损失输出时再Cast回原 dtype。支持多维归约非连续归约维度由 L2 API 通过 Transpose 自动处理。correction 必须为非负整数不会因 correction 过大导致除零崩溃。Tiling 策略源码级Host 侧 Tiling 实现在 reduce_std_with_mean_tiling.cpp策略要点多核切分沿非归约维度切分blockFactor CeilAlign(CeilDiv(nonReduceNum, coreNum), ubBlockSize)每个核处理blockFactor个非归约元素reduce_std_with_mean_tiling.cppUB 分块沿归约维度做单维分块ubLength依据 self/mean 双缓冲队列、fp32 scratch/work 缓冲、以及半精度 cast 缓冲的占用计算reduce_std_with_mean_tiling.cppTilingKey按 dtype 区分调度模式REDUCE_STD_SCH_FP160 / FP321 / BF162reduce_std_with_mean_tiling_key.hworkspace 为 0不需要额外的 GM workspacereduce_std_with_mean_tiling.cpp。调用示例示例代码如下完整可编译版本见 test_aclnn_std_mean_correction.cpp文档调用示例亦收录于 docs/aclnnStdMeanCorrection.md仅供参考具体编译和执行过程请参考编译与运行样例#include iostream #include vector #include acl/acl.h #include aclnnop/aclnn_std_mean_correction.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_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根据自己的需要处理 CHECK_RET(ret 0, LOG_PRINT(Init acl failed. ERROR: %d\n, ret); return ret); // 2.构造输入与输出需要根据API的接口自定义构造 std::vectorint64_t selfShape {2, 3, 4}; std::vectorint64_t stdOutShape {2, 4}; std::vectorint64_t meanOutShape {2, 4}; void* selfDeviceAddr nullptr; void* stdOutDeviceAddr nullptr; void* meanOutDeviceAddr nullptr; aclTensor* self nullptr; aclTensor* stdOut nullptr; aclTensor* meanOut nullptr; std::vectorfloat selfHostData {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24}; std::vectorfloat stdOutHostData {1, 2, 3, 4, 5, 6, 7, 8.0}; std::vectorfloat meanOutHostData {1, 2, 3, 4, 5, 6, 7, 8.0}; std::vectorint64_t dimData {1}; int64_t correction 1; bool keepdim false; // 创建self aclTensor ret CreateAclTensor(selfHostData, selfShape, selfDeviceAddr, aclDataType::ACL_FLOAT, self); CHECK_RET(ret ACL_SUCCESS, return ret); // 创建stdOut aclTensor ret CreateAclTensor(stdOutHostData, stdOutShape, stdOutDeviceAddr, aclDataType::ACL_FLOAT, stdOut); CHECK_RET(ret ACL_SUCCESS, return ret); // 创建meanOut aclTensor ret CreateAclTensor(meanOutHostData, meanOutShape, meanOutDeviceAddr, aclDataType::ACL_FLOAT, meanOut); CHECK_RET(ret ACL_SUCCESS, return ret); const aclIntArray *dim aclCreateIntArray(dimData.data(), dimData.size()); CHECK_RET(dim ! nullptr, return ACL_ERROR_INTERNAL_ERROR); // 3.调用CANN算子库API需要修改为具体的API uint64_t workspaceSize 0; aclOpExecutor* executor; // 调用aclnnStdMeanCorrection第一段接口 ret aclnnStdMeanCorrectionGetWorkspaceSize(self, dim, correction, keepdim, stdOut, meanOut, workspaceSize, executor); CHECK_RET(ret ACL_SUCCESS, LOG_PRINT(aclnnStdMeanCorrectionGetWorkspaceSize 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;); } // 调用aclnnStdMeanCorrection第二段接口 ret aclnnStdMeanCorrection(workspaceAddr, workspaceSize, executor, stream); CHECK_RET(ret ACL_SUCCESS, LOG_PRINT(aclnnStdMeanCorrection 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(stdOutShape); std::vectorfloat stdResultData(size, 0); ret aclrtMemcpy(stdResultData.data(), stdResultData.size() * sizeof(stdResultData[0]), stdOutDeviceAddr, 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(stdResultData[%ld] is: %f\n, i, stdResultData[i]); } std::vectorfloat meanResultData(size, 0); ret aclrtMemcpy(meanResultData.data(), meanResultData.size() * sizeof(meanResultData[0]), meanOutDeviceAddr, 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(meanResultData[%ld] is: %f\n, i, meanResultData[i]); } // 6.释放aclTensor和aclScalar需要根据具体API的接口定义修改 aclDestroyTensor(self); aclDestroyTensor(stdOut); aclDestroyTensor(meanOut); // 7.释放device资源需要根据具体API的接口定义修改 aclrtFree(selfDeviceAddr); aclrtFree(stdOutDeviceAddr); aclrtFree(meanOutDeviceAddr); if (workspaceSize 0) { aclrtFree(workspaceAddr); } aclrtDestroyStream(stream); aclrtResetDevice(deviceId); aclFinalize(); return 0; }示例关键点解析示例输入selfshape 为{2, 3, 4}dim {1}correction 1keepdim false因此输出stdOut、meanOut的 shape 均为{2, 4}去掉维度 1对应torch.std_mean(x, dim1, correction1, keepdimFalse)workspaceSize由第一段接口计算得出仅当其大于 0 时才需要aclrtMalloc申请 Device 内存并必须在结束时aclrtFree释放dim通过aclCreateIntArray构造为aclIntArray传入传nullptr或空数组则全量归约结果读取用aclrtMemcpy(DEVICE_TO_HOST)回拷并在程序结尾统一释放 tensor、Device 内存、Stream 并aclFinalize()。编译与运行构建自定义算子包以 Atlas A2 / ascend910b 为例在仓库根目录、执行source CANN/set_env.sh之后# 构建并安装自定义算子包 bash build.sh --pkg --experimental --socascend910b --opsreduce_std_with_mean -j16 bash build_out/cann-ops-math-custom_linux-*.run --install-path/usr/local/Ascend/cann-8.5.1 # 同步到 opp 目录必须 V/usr/local/Ascend/cann-8.5.1/vendors/custom_math O/usr/local/Ascend/cann-8.5.1/opp/vendors/custom_math cp $V/op_api/lib/libcust_opapi.so $O/op_api/lib/ patchelf --add-needed libopapi_math.so $O/op_api/lib/libcust_opapi.so cp $V/op_impl/ai_core/tbe/op_tiling/liboptiling.so $O/op_impl/ai_core/tbe/op_tiling/ cp -a $V/op_impl/ai_core/tbe/kernel/ascend910b/reduce_std_with_mean $O/op_impl/ai_core/tbe/kernel/ascend910b/ # 加载环境 source /usr/local/Ascend/cann-8.5.1/vendors/custom_math/bin/set_env.bashUT 测试# 在仓库根目录执行 bash build.sh -u --ophost --opapi --opkernel --opsreduce_std_with_mean --experimental -j16UT 用例覆盖 op_host 层test_reduce_std_with_mean_infershape.cpp、test_reduce_std_with_mean_tiling.cpp、op_api 层test_aclnn_std_mean_correction.cpp与 op_kernel 层test_reduce_std_with_mean.cpp。ST 测试ATKsource /usr/local/Ascend/cann-8.5.1/set_env.sh source /usr/local/Ascend/cann-8.5.1/vendors/custom_math/bin/set_env.bash atk aclnn --task accuracy --devices 0 \ experimental/math/reduce_std_with_mean/tests/st/aclnnStdMeanCorrection/atk_aclnnStdMeanCorrection.jsonST 用例与执行器位于 tests/st/aclnnStdMeanCorrectionatk_aclnnStdMeanCorrection.jsonexecutor_aclnnStdMeanCorrection.py。示例代码编译运行# 在仓库根目录执行需先完成算子包构建和安装 bash build.sh --run_example reduce_std_with_mean eager cust --experimental --vendor_namecustom --socascend910b总结aclnnStdMeanCorrection是 ops-math 仓库reduce_std_with_mean模块面向 Atlas A2 系列产品的标准 L2 单算子接口语义等价于torch.std_mean。其内部通过 ReduceMean → Expand 广播 → ReduceStdWithMean 的 Two-Pass 管线在 L0 kernel 中使用预计算均值与 fp32 升精度累加保证精度与确定性对外则以 aclnn 两段式接口GetWorkspaceSize 执行接口提供标准化的 workspace 管理与异步执行流程。开发者可直接参考 调用示例 与 单元/ST 测试 快速接入。【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考