CANN ops-nn 算子 aclnnMaxPool3D 完整指南：两段式接口、三种 Padding 模式与 NPU 端到端调用实战

CANN ops-nn 算子 aclnnMaxPool3D 完整指南两段式接口、三种 Padding 模式与 NPU 端到端调用实战【免费下载链接】ops-nn本项目是CANN提供的神经网络类计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-nn导读aclnnMaxPool3D是 CANN ops-nn 算子库中 MaxPool3D 算子 的 aclnn 标准接口用于在 Atlas A2 训练/推理系列产品上对五维张量的深度D、高度H、宽度W三个维度执行三维最大池化。本文以 aclnnMaxPool3D 接口文档 为主线系统讲解其两段式调用架构、全部参数语义ksize / strides / padding / pads / dilation / ceilMode / dataFormat、三种 Padding 模式的输出尺寸推导公式并结合仓库内的示例代码与 op_host / op_kernel 源码给出可直接复制运行的 NDHWC 与 NCDHW 两种布局的完整调用方案。读完本文你将掌握在 CANN 环境下正确配置并验证 MaxPool3D 算子的完整能力。产品支持情况与基本功能支持的产品产品是否支持Atlas A2 训练系列产品 / Atlas A2 推理系列产品√该算子当前仅面向 Atlas A2 训练/推理系列产品接口内部会针对该平台的 AI Vector Core 能力做分形格式转换与 tiling 编排见 op_host/op_api/aclnn_max_pool3_d.cpp。算子功能与计算公式算子对五维输入张量x的 D、H、W 维执行三维最大池化计算公式为$$ y(n,c,o_d,o_h,o_w)\max_{(i_d,i_h,i_w)\in R(o_d,o_h,o_w)}x(n,c,i_d,i_h,i_w) $$其中 $R(o_d,o_h,o_w)$ 是由ksize、strides、padding、pads和dilation共同确定的有效输入区域padding 区域不参与最大值计算即 padding 处补入的值不会被当作真实元素参与 max 归约。两段式接口架构与 CANN 所有 aclnn 算子一致aclnnMaxPool3D采用两段式调用设计必须先查询 workspace 大小并创建算子执行器再执行计算第一段aclnnMaxPool3DGetWorkspaceSize— 完成基础入参校验、构建执行图返回 Device 侧所需 workspace 大小与算子执行器executor。第二段aclnnMaxPool3D— 传入 workspace 与 executor 在指定 Stream 上异步执行计算。两个函数的原型如下aclnnStatus aclnnMaxPool3DGetWorkspaceSize(const aclTensor *x, const aclIntArray *ksize, const aclIntArray *strides, const char *padding, const aclIntArray *padsOptional, const aclIntArray *dilationOptional, int64_t ceilMode, const char *dataFormatOptional, aclTensor *out, uint64_t *workspaceSize, aclOpExecutor **executor); aclnnStatus aclnnMaxPool3D(void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream);两段接口的返回值均为aclnnStatus状态码ACLNN_SUCCESS表示成功。aclnnMaxPool3DGetWorkspaceSize 参数详解x计算输入类型aclTensor*约束五维输入张量逻辑布局由dataFormatOptional指定支持ND与NDC1HWC0两种数据格式。数据类型FLOAT16、FLOAT、BFLOAT16。特性支持非连续 Tensor接口内部会先做Contiguous连续化处理见下文源码分析。ksize池化窗口大小类型aclIntArray*取值规则支持 1、3 或 5 个元素。1 个元素该值同时作用于 D、H、W 维。3 个元素顺序为 D、H、W。5 个元素按布局区分——NCDHW布局顺序为 N、C、D、H、WNDHWC布局顺序为 N、D、H、W、C。其中N 维和 C 维必须为 1。约束D、H、W 维的值必须大于 0。strides池化窗口步长类型aclIntArray*取值规则元素数量与顺序和ksize完全一致。约束N 维和 C 维必须为 1D、H、W 维的值必须大于 0。paddingPadding 模式类型char*支持以下三种取值模式行为VALID不补齐输入忽略padsOptional和ceilMode。SAME根据输出尺寸自动计算两侧 paddingtotal_padding max(0, (out-1)*stride (ksize-1)*dilation 1 - in)前后各取一半忽略padsOptional和ceilMode。CALCULATED使用padsOptional指定的显式 padding并由ceilMode控制输出尺寸的取整方式。padsOptional显式 Padding类型aclIntArray*可选约束必须包含6 个非负整数顺序为 front、back、top、bottom、left、right。默认值传入空指针时使用[0, 0, 0, 0, 0, 0]。生效范围仅在paddingCALCULATED模式下生效。dilationOptional膨胀率类型aclIntArray*可选取值规则支持 1、3 或 5 个元素空间维的解释方式与ksize相同值必须大于 0。默认值传入空指针时使用[1, 1, 1, 1, 1]。ceilMode输出尺寸取整方式类型int64_t语义仅在CALCULATED模式下生效——0 表示向下取整floor非 0 表示向上取整ceilVALID与SAME模式不使用该参数。dataFormatOptional逻辑布局类型char*可选取值NCDHW或NDHWC。默认值传入空指针时使用NDHWC。out计算输出类型aclTensor*约束最大池化结果数据类型必须与x相同FLOAT16、FLOAT、BFLOAT16逻辑布局必须与dataFormatOptional一致数据格式支持ND和NDC1HWC0。workspaceSize 与 executor出参workspaceSizeuint64_t*返回 Device 侧需要申请的 workspace 大小。executoraclOpExecutor**返回包含算子计算流程的执行器。第一段接口的校验逻辑第一段接口完成基础入参校验以下场景直接返回错误161001ACLNN_ERR_PARAM_NULLPTRx、ksize、strides、padding、out、workspaceSize 或 executor 为空指针。 161002ACLNN_ERR_PARAM_INVALIDx 的数据类型不受支持或 x 与 out 的数据类型不同。而 shape、数据格式、padding 模式及各数组属性不满足上述约束时则会在后续的算子编排图构建或 tiling 校验阶段失败。这一点可以从源码中得到印证CheckParams函数op_host/op_api/aclnn_max_pool3_d.cpp只校验空指针与数据类型padding模式合法性、ksize/strides元素数量与取值、pads非负性等则分别在 tiling 阶段的GetAttrsInfo、GetKernelKsizeInfo、GetStrideInfo、GetCalculatedPadInfo中逐项校验op_host/max_pool3_d_tiling.cpp。三种 Padding 模式的输出尺寸推导了解输出 shape 如何推导是正确设置out张量 shape 的前提。仓库的 op_host/max_pool3_d_infershape.cpp 中给出了三种模式的精确实现这里整理为可直接套用的公式以单维为例D/H/W 各自独立计算VALID忽略 pads 与 ceilModefloor 语义$$ o \left\lfloor \frac{d - dilation \times (k - 1) - 1}{s} \right\rfloor 1 $$SAME输出由输入与步长决定pad 自动计算$$ o \left\lceil \frac{d}{s} \right\rceil $$CALCULATED显式 pads由 ceilMode 决定取整先对补 pad 后的输入尺寸计算$d_{padded} d pad_{front} pad_{back}$floor 时$o \lfloor (d_{padded} - dilation \times (k-1) - 1) / s \rfloor 1$ceil 时分子额外加 $s-1$ 后做整除并且若最后一个窗口起点越过d pad_front即 $(o-1) \times s \ge d pad_{front}$则输出减 1保证窗口不会完全落在 padding 区域之外。此外tiling 阶段会对VALID/SAME模式下的输出 shape 做二次一致性校验CheckOutPutShapeForValid/CheckOutPutShapeForSame输出与推导结果不一致会直接报错CALCULATED模式则完全信任用户传入的输出 shape。aclnnMaxPool3D 执行接口第二段接口参数说明workspacevoid*计算输入Device 侧 workspace 地址当workspaceSize为 0 时允许传入空指针。workspaceSizeuint64_t计算输入第一段接口返回的 workspace 大小。executoraclOpExecutor*计算输入第一段接口返回的算子执行器。streamaclrtStream计算输入执行计算的 Stream。该接口内部通过CommonOpExecutorRun完成异步下发见 op_host/op_api/aclnn_max_pool3_d.cpp。约束说明输入和输出必须是五维逻辑张量不支持广播。输出的逻辑 shape 必须与ksize、strides、padding、padsOptional、dilationOptional、ceilMode和dataFormatOptional共同推导出的 shape 一致NDC1HWC0格式的物理存储 shape 允许包含分形格式所需的补齐容量C1 补齐、C016 对齐等。空输入或空输出直接返回第一段接口返回的 workspace 大小为 0源码中通过x-IsEmpty() || out-IsEmpty()提前短路见 op_host/op_api/aclnn_max_pool3_d.cpp。算子采用确定性最大值归约相同输入和属性产生相同输出利于结果复现与调试。调用示例NDHWC 与 NCDHW 完整流程仓库在 examples 目录下提供了两套完整可编译运行的样例test_aclnn_max_pool3_d.cppNDHWC 布局输入 shape{1, 4, 4, 4, 2}窗口ksize{1,2,2,2,1}、步长strides{1,2,2,2,1}输出{1, 2, 2, 2, 2}。test_aclnn_max_pool3_d_ncdhw.cppNCDHW 布局输入 shape{1, 2, 4, 4, 4}输出{1, 2, 2, 2, 2}。两组样例均包含完整的 ACL 初始化、Tensor 与属性创建、两段式接口调用、结果回拷与数值校验可直接作为算子调试的起点。核心调用流程uint64_t workspaceSize 0; aclOpExecutor* executor nullptr; aclError ret aclnnMaxPool3DGetWorkspaceSize( x, ksize, strides, VALID, pads, dilation, 0, NDHWC, out, workspaceSize, executor); if (ret ! ACL_SUCCESS) { return ret; } void* workspace nullptr; if (workspaceSize 0) { ret aclrtMalloc(workspace, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST); if (ret ! ACL_SUCCESS) { return ret; } } ret aclnnMaxPool3D(workspace, workspaceSize, executor, stream); if (ret ! ACL_SUCCESS) { return ret; } ret aclrtSynchronizeStream(stream); if (workspace ! nullptr) { aclrtFree(workspace); } return ret;NDHWC 布局样例要点解析以 test_aclnn_max_pool3_d.cpp 为例完整步骤为初始化资源AclResources::Initialize依次完成aclInit(nullptr)、aclrtSetDevice(0)、aclrtCreateStream(stream)见 aclnn_max_pool3_d_example_utils.h。创建输入/输出张量CreateFloatTensor先aclrtMalloc分配 Device 内存、aclrtMemcpy拷入初始数据再通过aclCreateTensor(shape, dim, ACL_FLOAT, strides, 0, ACL_FORMAT_ND, ...)构造aclTensor其中 stride 按 NDHWC 连续排布自动计算C 维在最后一维因此tensorStrides从尾向前累乘。创建属性数组通过aclCreateIntArray(data, size)分别创建ksize {1,2,2,2,1}、strides {1,2,2,2,1}、pads {0,0,0,0,0,0}、dilation {1,1,1,1,1}。两段式调用第一段传VALID、ceilMode0、NDHWC第二段异步执行后aclrtSynchronizeStream同步。结果回拷与校验aclrtMemcpy(..., ACL_MEMCPY_DEVICE_TO_HOST)拷回 Host然后逐元素验证——窗口 2×2×2、步长 2等价于对输入按 D/H/W 每维取第 1、3 个元素源码id od*21等比较输出与对应输入是否相等。NCDHW 布局样例差异NCDHW 样例test_aclnn_max_pool3_d_ncdhw.cpp的区别在于输入 shape 为{1, 2, 4, 4, 4}C 在第 1 维ksize {1, 1, 2, 2, 2}、strides {1, 1, 2, 2, 2}N、C 维为 1第一段接口传入NCDHW。由于输入全部初始化为 2.0校验逻辑简化为std::all_of判断输出是否全为 2.0。源码级原理接口内部的执行链路输入连续化与物理格式转换从 op_host/op_api/aclnn_max_pool3_d.cpp 的实现可以看到aclnnMaxPool3DGetWorkspaceSize内部实际完成以下编排l0op::Contiguous(x, executor)将非连续输入连续化PreparePhysicalKernelInput根据 ksize/strides/dilation/padding/布局组合判断是否走NDC1HWC0 物理格式路径。仓库内预置了多条物理加速路径例如IsPool2Stride2PhysicalRouteSAME 模式下 2×2×2 窗口、步长 2 且通道数较大的场景n 1 || c 64 || (FLOAT c 16)视为收益型场景IsK1IdentityPhysicalRoute1×1×1 恒等池化场景IsTinyK3PhysicalRoute、IsHOnlyStride3PhysicalRoute、IsD3H3Dil2PhysicalRoute、IsD2H3W2Dil2PhysicalRoute面向 NDC1HWC0 输出的特殊小窗口/大膨胀率场景。命中物理路径时通过l0op::ReFormat与l0op::TransData(logicalX, FORMAT_NDC1HWC0, ...)将输入转为分形格式输出侧用PreparePhysicalKernelOutput构造{n, d, c1, h, w, c0}六维物理存储 shapec0对 FLOAT 取 8、其余取 16。未命中物理路径时保持 ND 逻辑布局执行计算完成后若输出做过物理格式转换通过l0op::TransDatal0op::ViewCopy将结果拷回用户输出。L0 算子注册与 AICore 下发l0op::MaxPool3Dop_host/op_api/max_pool3_d.cpp通过OP_TYPE_REGISTER(MaxPool3D)注册并使用ADD_TO_LAUNCHER_LIST_AICORE将算子加入 AICore 启动列表携带ksize、strides、padding、pads、dilation、ceilMode、dataFormat全部属性。Tiling 与 KernelTilingop_host/max_pool3_d_tiling.cpp解析平台信息GetCoreNumAiv获取 AIV 核数、UB 内存大小读取属性与 shape针对输出元素总量totalOut、normalCoreOut、splitOut、splitQuantum等字段做多核任务切分并生成MaxPool3DTilingData包含 N/D/H/W/C、ksize/stride/pad/dilation、输入输出 C0 分块等全部字段定义于 op_kernel/max_pool3_d_tiling_data.h。Tiling 阶段还包含RefineShape优化当某维输出为 1 且膨胀率为 1 时将该维 ksize 裁剪到有效输入范围、清零 padding、步长置为输入尺寸减少无效计算。Kernelop_kernel/max_pool3_d.cpp按 tiling 数据在 AICore 上执行三维窗口的最大值归约padding 区域跳过、不参与 max 计算保证确定性输出。单元测试覆盖仓库在 tests/ut 下提供了三组 UTop_graph/test_max_pool3_d_pass.cpp图构建/Pass 级校验op_host/test_max_pool3_d_infershape.cpp三种 padding 模式的输出 shape 推导校验op_host/test_max_pool3_d_tiling.cpptiling 参数与多核切分校验。它们与示例程序共同验证了本文描述的尺寸公式、属性约束与执行路径。常见问题与排查建议报 161001 空指针错误检查x、ksize、strides、padding、out、workspaceSize、executor是否均已有效赋值padding为字符串参数同样不能为nullptr源码中显式单独判空。报 161002 类型错误确认x与out数据类型一致且均为 FLOAT16 / FLOAT / BFLOAT16。shape 校验失败先按上文公式推导输出 shape 再创建outSAME模式要求out ceil(in / stride)VALID模式要求按 floor 公式精确一致CALCULATED模式注意 ceilMode1 时最后一个窗口是否越过有效区域。NDC1HWC0 输出容量不足NDC1HWC0物理 shape 的通道容量C1 × C0必须 ≥ 逻辑通道数 C否则 tiling 校验会报错见CheckShapeChannels。布局混用x/out的逻辑布局必须与dataFormatOptional保持一致NDHWC 下 C 维在最后一维5 元素 ksize/strides 的 N、C 位次与 NCDHW 相反。总结aclnnMaxPool3D为 CANN ops-nn 提供了面向 Atlas A2 的标准化三维最大池化能力两段式接口保证了 workspace 与执行器的显式管理VALID/SAME/CALCULATED三种 padding 模式配合pads、dilation、ceilMode覆盖了绝大多数池化配置NDHWC/NCDHW双布局与ND/NDC1HWC0双数据格式兼顾了易用性与 NPU 分形计算效率。仓库内 接口文档、README、示例程序 与 UT 测试 构成了从文档到验证的完整闭环可直接在此基础上开展算子验证或二次开发。【免费下载链接】ops-nn本项目是CANN提供的神经网络类计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-nn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考