CANN ops-math 算子实战aclnnFmodTensor 与 aclnnInplaceFmodTensor 张量取余接口全解析【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math导读aclnnFmodTensor/aclnnInplaceFmodTensor是 CANN ops-math 仓库中 ModFmod截断取余算子在 aclnnAscend CANN 轻量算子接口层的张量形态对外接口用于对self与可广播的other执行out self - other * trunc(self / other)逐元素取余。本文以 关联文档 为核心骨架结合 op_api 实现、tiling 实现 与 UT 用例 等仓库源码完整讲解两段式接口的调用流程、数据类型与产品约束、A2/A3 平台的 INT16 增强与大商数值稳定性算法并给出可直接编译运行的完整示例帮助读者在 NPU 上正确、高效地完成张量取余计算。功能说明与数学语义Mod 算子返回self除以other的余数采用截断取余trunc-mod结果符号跟随被除数语义$$ out_{i} self_{i} - other \times trunc(self_{i} / other) $$核心要点见 关联文档 与 README 功能说明other需要能广播broadcast到self广播后逐元素计算out的 shape 必须与self完全一致余数形状跟随被除数self、other、out均支持 ND 格式维度不超过 8 维。接口原型两段式GetWorkspaceSize Execute异步调用aclnnFmodTensor与aclnnInplaceFmodTensor均遵循 aclnn 两级接口约定先调用GetWorkspaceSize完成参数校验与图构建查询所需 workspace 大小并得到executor再调用执行接口在指定stream上异步下发算子。两个接口的原型如下见 关联文档 与 接口头文件aclnnStatus aclnnFmodTensorGetWorkspaceSize( const aclTensor* self, const aclTensor* other, aclTensor* out, uint64_t* workspaceSize, aclOpExecutor** executor); aclnnStatus aclnnFmodTensor( void* workspace, uint64_t workspaceSize, aclOpExecutor* executor, aclrtStream stream); aclnnStatus aclnnInplaceFmodTensorGetWorkspaceSize( aclTensor* selfRef, const aclTensor* other, uint64_t* workspaceSize, aclOpExecutor** executor); aclnnStatus aclnnInplaceFmodTensor( void* workspace, uint64_t workspaceSize, aclOpExecutor* executor, aclrtStream stream);两者区别仅在于aclnnFmodTensor非原地版本self、other、out三个张量独立传入结果写入outaclnnInplaceFmodTensor原地版本只有selfRef同时充当被除数与输出和other结果直接写回selfRef。从 源码 可以看到原地版本内部通过auto out const_castaclTensor*(selfRef);将out指向selfRef并复用CheckParamsInplaceTensorTensor做参数校验后与普通版本共享同一条ExecFmodTensorGetWorkspaceSize执行链路。参数说明参数名输入/输出/属性描述数据类型数据格式self输入待进行 mod 计算的入参即公式中的 self_i被除数BFLOAT16、FLOAT16、FLOAT32、INT32、INT16*NDother输入待进行 mod 计算的入参即公式中的 other除数BFLOAT16、FLOAT16、FLOAT32、INT32、INT16*NDout输出待进行 mod 计算的出参即公式中的 out_i余数BFLOAT16、FLOAT16、FLOAT32、INT32、INT16*ND*INT16 同数据类型计算以及self/other分别为 INT16 与 BFLOAT16/FLOAT16/FLOAT32 的混合数据类型计算仅由 Atlas A2 训练系列产品/Atlas A2 推理系列产品、Atlas A3 训练系列产品/Atlas A3 推理系列产品的 AICore 支持其余产品上该增强不适用BFLOAT16/FLOAT16/FLOAT32/INT32 的既有支持不受影响。约束与数据类型支持形状约束self、other、out支持 ND维度不超过 8 维源码中通过CheckTensorDimSize校验见 aclnn_fmod_tensor.cppother必须可广播到self且广播结果 shape 必须等于selfshapeoutshape 必须等于selfshape。这两条校验实现在 CheckBroadcastShape先计算广播 shape再与self-GetViewShape()、out-GetViewShape()逐一比对不满足即返回ACLNN_ERR_PARAM_INVALID。数据类型与产品差异化aclnn 层支持 DOUBLE、BFLOAT16、FLOAT16、FLOAT32、INT32、INT64、INT8、UINT8、INT16 的类型推导AICore kernel 直接覆盖 BFLOAT16、FLOAT16、FLOAT32、INT32其余类型DOUBLE/INT64/INT8/UINT8走 AICPU fallback。其中INT16 同数据类型计算以及INT16 与 BFLOAT16/FLOAT16/FLOAT32 的混合数据类型计算是 Atlas A2 / Atlas A3 平台AICore的专属增强其余产品上的 INT16 增强不适用但已有的 BFLOAT16/FLOAT16/FLOAT32/INT32 同数据类型计算与 DOUBLE/INT64/INT8/UINT8 的 AICPU 回退行为保持不变。从 op_api 源码 可以看到不同 NPU 架构的 dtype 支持列表是分架构维护的ASCEND910B_DTYPE_DTYPE_SUPPORT_LIST对应DAV_2201及 RegBase即 Atlas A2/A3 平台在原有 DOUBLE/BF16/FP16/FP32/INT32/INT64/INT8/UINT8 基础上新增了 INT16源码注释明确标注 int16 同 dtype lane 的 L2 门控 (A2)而ASCEND910_DTYPE_DTYPE_SUPPORT_LISTDAV_2002与ASCEND310P_DTYPE_DTYPE_SUPPORT_LISTDAV_1001均不含 INT16。精度说明大商场景数值稳定性增强针对self/other商值较大大 |self/other|的场景Atlas A2/A3 上的 AICore 计算路径引入了数值稳定性增强算法相比朴素截断取余trunc-mod实现降低了大商场景下的精度损失风险。该增强与 INT16/混合数据类型能力一并限定于 Atlas A2/A3其余产品的既有算法与精度行为不变见 README 精度说明。其工程实现在 mod_tiling.cpp 中定义了自适应路由阈值FMOD_NAIVE_THRESH_DEFAULT 256.0f当 |商| 超过该阈值时路由到增强算法源码注释为 AlgoA 大商精度路该阈值可由环境变量FMOD_NAIVE_THRESH覆盖供真机精度 sweep 使用生产环境默认不设置FmodNaiveThresh 对非法输入无法解析、溢出、非有限值、非正值会安全回退到默认阈值FP32/FP16/INT16/INT32 各 dtype 按 kernel 缓冲区的实际占用分别使用不同的 UB 切分因子UB_DIVIDER_FP3269、UB_DIVIDER_FP1665、UB_DIVIDER_INT1645、UB_DIVIDER_INT3269其中 INT16 同 dtype 走整数域 naive 路径、不分配 A1..A5 工作块因此每元素占用更低连续派发isInput2Scalar || isInput2SameShape的同 dtype FP32/FP16/BF16 场景还会走 kernel 精简核USE_LEAN_CONTIGUB 切分因子进一步下调到 48以获得更宽的 tile。产品支持情况产品是否支持Ascend 950PR/Ascend 950DT√Atlas A3 训练系列产品/Atlas A3 推理系列产品√Atlas A2 训练系列产品/Atlas A2 推理系列产品√Atlas 200I/500 A2 推理产品×Atlas 推理系列产品√Atlas 训练系列产品√来源README 产品支持情况完整调用示例两段式接口实战仓库在 examples/test_aclnn_fmod_tensor.cpp 提供了可直接参考的完整示例。整个调用流程分为初始化设备、构造 aclTensor、两段式执行、读取结果、释放资源五个阶段核心执行逻辑如下int Compute(aclrtStream stream, aclTensor* self, aclTensor* other, aclTensor* out) { uint64_t workspaceSize 0; aclOpExecutor* executor; // 第一阶段查询 workspace 大小并构建执行器 auto ret aclnnFmodTensorGetWorkspaceSize(self, other, out, workspaceSize, executor); if (ret ! ACL_SUCCESS) { LOG_PRINT(aclnnFmodTensorGetWorkspaceSize failed. ERROR: %d\n, ret); return ret; } void* workspaceAddr nullptr; if (workspaceSize 0) { ret aclrtMalloc(workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST); if (ret ! ACL_SUCCESS) { LOG_PRINT(allocate workspace failed. ERROR: %d\n, ret); return ret; } } // 第二阶段在指定 stream 上异步执行 ret aclnnFmodTensor(workspaceAddr, workspaceSize, executor, stream); if (ret ! ACL_SUCCESS) { LOG_PRINT(aclnnFmodTensor failed. ERROR: %d\n, ret); return ret; } ret aclrtSynchronizeStream(stream); if (ret ! ACL_SUCCESS) { LOG_PRINT(aclrtSynchronizeStream failed. ERROR: %d\n, ret); return ret; } if (workspaceSize 0) { aclrtFree(workspaceAddr); } return 0; }示例主函数中构造了{4, 4}的 FLOAT 类型输入std::vectorint64_t selfShape {4, 4}; std::vectorint64_t otherShape {4, 4}; std::vectorint64_t outShape {4, 4}; std::vectorfloat selfData {5.5, -11.51, 36.23, 7, -10, -8, -15, -7, 10, 8, 15, 7, -10, -8, -15, -7}; std::vectorfloat otherData {2, 3, -24.1, 2, 3, 5, 4, 2, -3, -5, -4, -2, -3, -5, -4, -2};使用要点总结初始化先aclInit(nullptr)、aclrtSetDevice(deviceId)、aclrtCreateStream(stream)张量构造通过aclrtMallocaclrtMemcpyHOST_TO_DEVICE准备设备侧数据再用aclCreateTensor创建 ND 格式、带连续 strides 的aclTensorworkspace 分配仅当workspaceSize 0时才需要aclrtMalloc分配 workspace执行完毕记得aclrtFree异步语义aclnnFmodTensor为异步下发必须aclrtSynchronizeStream(stream)后再读取结果结果回读aclrtMemcpyDEVICE_TO_HOST将结果拷回 host 打印资源释放依次aclDestroyTensor、aclrtFree、aclrtDestroyStream、aclrtResetDevice、aclFinalize。源码级实现剖析从 aclnn 到 AICore 的完整链路op_api 层参数校验与 dtype 归一化aclnn_fmod_tensor.cpp 是 aclnn 接口的核心实现非原地入口aclnnFmodTensorGetWorkspaceSizeL694-L702依次完成空指针检查CheckNotNullTensorTensor校验self/other/out非空类型推导检查CheckPromoteType计算self与other的 promote 类型要求其能 cast 成out且属于当前 NPU 架构的 dtype 支持列表当out为 INT16 时要求 promote 类型必须是{FLOAT32, FLOAT16, BFLOAT16, INT16}之一源码 L234-L273广播与形状检查CheckBroadcastShape校验广播合法性及outshape 与self一致维度检查CheckTensorDimSize限制不超过 8 维。随后ExecFmodTensorGetWorkspaceSizeL567-L598按计算 dtype 选择执行路径AICore 路径当 promote 类型或计算类型属于{BF16, FP16, FP32, INT32, INT16}时IsAiCoreComputeDtypeL145-L150对self/other先Contiguous归一再以计算 dtype 做 Mod最后把结果 cast 到out的 dtype 并ViewCopy落盘。这一设计保证窄输出尤其是outint16不会改变运算精度域——先按 promote 类型算最后才收窄混合 dtype 的 FP32 桥接CastWithFp32BridgeL169-L188针对INT16 ↔ BF16之间的互转做了特殊处理——DAV_2201 架构没有 int16 与 bf16 之间的直接 Cast lane因此统一经 FP32 中转int16/bf16 - fp32是精确的最终 Cast 的收窄与直接转换等价通用路径AICPU fallback对于 DOUBLE/INT64/INT8/UINT8 等非 AICore dtypeInitializeTensor先将张量转连续、0 维转 1 维、cast 到 promote 类型BroadcastTensor广播到outshape 后交给底层l0op::Mod完成。host 层shape 推导与 tilingshape 推导mod_infershape.cpp 中InferShape4Mod校验other能右对齐广播到selfCanBroadcastOtherToSelf逐维判断otherDim 1 || otherDim selfDim然后令输出 shape 直接继承selfshape*yShape *xShape印证了余数形状跟随被除数的语义tilingmod_tiling.cpp 的ModTilingForGe读取 x1/x2/y 三个 dtype 并映射为编译期 tiling keyMOD_TPL_FP32/FP16/BF16/INT32/INT16按每核最小 1024 元素、UB 容量与 dtype 对应的ubDivider计算needCoreNum、perCoreDataCount等切分参数此外还会对通用广播场景尝试融合广播tilingSetFusedBroadcastTiling将右对齐后恰好为 OUTER行广播或 INNER列广播的二维折叠形状命中为融合路径降低广播场景的访存开销最终SetBlockDim(tilingData-needCoreNum)并设置 32MB 的 workspaceWORK_SPACE_SIZE算子定义mod_def.cpp 注册Mod算子的 x1/x2/y 输入输出dtype 三元组为{BF16, FP16, FP32, INT32, INT16}kernel 只暴露同 dtype 原型跨 dtype 由 aclnn 层先 promote cast并声明AICore().AddConfig(ascend910b)与AICore().AddConfig(ascend910_93)——即该 AICore kernel 仅在 Atlas A2/A3 平台DAV_2201注册这与文档INT16 增强仅 A2/A3的产品边界完全一致。kernel 层同 dtype 分发与 AlgoA 数值稳定性mod_dispatch_impl.h 展示了ModKernelDispatchSameDtype的五个同 dtype 分发 laneINT32 - ModintFP16 - ModhalfFP32 - ModfloatBF16 - Modbfloat16_t在__NPU_ARCH__ 3003上不编译INT16 - Modint16_t受MOD_ENH_ARCH22宏保护即 A2/A3 增强。结合 op_kernel 目录 下的mod_compute_impl.h、mod_algoa_impl.h、mod_bcast_impl.h、mod_flat_impl.h、mod_leancontig_impl.h、mod_int32_impl.h等实现文件可以推断 kernel 层按输入几何形态标量/同形/广播/扁平/连续精简与大商判定分别走不同的计算内核其中mod_algoa_impl.h即大商数值稳定性增强算法AlgoA的实现载体。测试与验证仓库为 Tensor 形态接口提供了完整的 UT 覆盖test_aclnn_fmod_tensor.cpp覆盖float_same_shape、fp16_broadcast{2,3,5}对{1,3,1}广播、invalid_broadcast非法广播返回ACLNN_ERR_PARAM_INVALID、int16_same_dtypeINT16 同 dtype 新 lane、mixed_int16_fp32_promote_to_fp32INT16 self × FP32 other 归一化到 FP32 计算、mixed_int16_fp32_to_int16FP32 计算后 cast 回 INT16 输出等关键场景test_aclnn_inplace_fmod_tensor.cpp覆盖原地版本的float_same_shape与invalid_broadcasthost 侧另有 test_mod_infershape.cpp 与 test_mod_tiling.cpp 验证 shape 推导与 tiling 切分。这些用例从三个维度印证了文档约束广播合法性会被拒绝、FP32 计算 收窄输出的混合 dtype 语义正确、INT16 增强仅在 A2/A3 dtype 支持列表内放行。常见问题与使用建议返回ACLNN_ERR_PARAM_INVALID优先检查other是否可广播到self、outshape 是否严格等于selfshape、维度是否超过 8 维、promote 类型是否在架构 dtype 支持列表内INT16 报不支持INT16 同/混合 dtype 计算仅限 Atlas A2/A3 训练/推理系列产品AICore其他产品请改用 INT32 等既有支持类型原地版本别忘自引用aclnnInplaceFmodTensor没有独立的out结果覆盖selfRef调用前应确认原始self数据不再需要workspace 不要无条件分配遵循示例代码仅当workspaceSize 0时再aclrtMalloc避免不必要的显存开销大商精度敏感场景Atlas A2/A3 上 AICore 已内置 AlgoA 大商数值稳定性增强默认阈值 256可用FMOD_NAIVE_THRESH环境变量覆盖以做真机 sweep建议在精度敏感应用中使用该路径非 A2/A3 平台仍为朴素 trunc-mod 语义精度行为保持不变。延伸阅读Tensor 形态配套接口aclnnFmodScalar aclnnInplaceFmodScalarself为张量、other为标量的取余接口Mod 算子总览参数表、贡献说明、调用方式汇总experimental/math/mod/README.md完整示例examples/test_aclnn_fmod_tensor.cpp。【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考