CANN ops-math 中 TileWithAxis 算子详解:沿指定维度复制 Tensor 的实现与调用实践
CANN ops-math 中 TileWithAxis 算子详解:沿指定维度复制 Tensor 的实现与调用实践
本文以 ops-math 仓库中 conversion/tile_with_axis 算子模块为核心,系统讲解 TileWithAxis 算子的功能定义、参数约束与图模式调用方式,并结合算子的 op_graph 原型、形状推导、AICore/AICPU 双路径 Kernel 实现,说明其"沿指定维度复制输入数据、扩展输出 Tensor"的完整落地机制。读完后,你将掌握该算子在 NPU 图模式中的构图调用方法,并能理解其在主机侧 Tiling 与设备侧搬运上的实现细节。
算子功能与计算示例
TileWithAxis 是 ops-math 提供的张量转换类算子,位于 conversion/tile_with_axis 目录。其核心功能是:沿指定维度复制输入 Tensor 数据,扩展输出 Tensor。
仓库 README 给出的官方计算示例如下:
- 输入
x = [[[1, 2], [3, 4], [5, 6]], [[7, 8], [9, 10], [11, 12]]],shape =(2, 3, 2) axis = 1,tiles = 2- 输出
y = [[[1, 2], [3, 4], [5, 6], [1, 2], [3, 4], [5, 6]], [[7, 8], [9, 10], [11, 12], [7, 8], [9, 10], [11, 12]]],shape =(2, 6, 2)
计算公式可以概括为一句话:输出 y 的 shape 与输入 x 完全相同,仅 axis 维度变为 x.shape[axis] * tiles,即把输入张量在 axis 维度上首尾拼接 tiles 份自身。这与 PyTorch 中 torch.repeat_interleave(x, tiles, dim=axis) 的语义一致(注意不是 tile 的网格平铺),在需要将序列沿时间维、通道维等某一维度做整数倍重复的场景(如时序展开、位置编码对齐)中非常实用。
从源码结构看,算子原型注释还说明了其第三方框架兼容性:与 Caffe 的 Tile 算子语义对齐(见 tile_with_axis_proto.h 中 @par Third-party framework compatibility 说明)。
参数说明
以下为 README 中的完整参数表,并结合 op_graph 原型做了数据类型补充:
| 参数名 | 输入/输出/属性 | 描述 | 数据类型 | 数据格式 |
|---|---|---|---|---|
| x | 输入 | 输入张量 | FLOAT16、FLOAT、INT8、INT16、INT32、INT64、UINT8、UINT16、UINT32、UINT64 | ND |
| axis | 属性(可选) | 指定复制的维度,默认为 1 | INT | - |
| tiles | 属性(必选) | 复制次数,必须大于 0 | INT | - |
| y | 输出 | 输出张量,与 x 具有相同的数据类型和格式 | 与 x 一致 | ND |
关于数据类型需要结合源码进一步说明。图模式原型 tile_with_axis_proto.h 中 REG_OP(TileWithAxis) 声明的输入/输出类型集合为:
REG_OP(TileWithAxis)
.INPUT(x, TensorType({DT_BF16, DT_FLOAT16, DT_FLOAT, DT_INT64, DT_INT32, DT_INT16, DT_INT8, DT_UINT64, DT_UINT32,
DT_UINT16, DT_UINT8}))
.OUTPUT(y, TensorType({DT_BF16, DT_FLOAT16, DT_FLOAT, DT_INT64, DT_INT32, DT_INT16, DT_INT8, DT_UINT64, DT_UINT32,
DT_UINT16, DT_UINT8}))
.ATTR(axis, Int, 1)
.REQUIRED_ATTR(tiles, Int)
.OP_END_FACTORY_REG(TileWithAxis);
可以看到,相比 README 参数表,原型额外声明了 DT_BF16,且 axis 属性默认值为 1、tiles 为必选属性。而 AICore 侧算子定义 tile_with_axis_def.cpp 中注册的 Ascend950(DAV_3510)配置仅覆盖 6 种类型:DT_FLOAT、DT_FLOAT16、DT_BF16、DT_INT32、DT_INT8、DT_UINT8。也就是说,AICore 路径支持浮点类型(含 BF16/FP16)和 INT32/INT8/UINT8;像 INT64、UINT64 等宽整型会走 AICPU 路径——这一点在图模式样例代码的注释中得到印证:
"使用 DT_INT64 数据类型,AICore 不支持该类型,自动走 AICPU 算子路径。"(test_geir_tile_with_axis.cpp 文件头注释)
这一"双路径"设计是该算子实现上的一个重要特点:AICore Kernel 面向主力数据类型在 NPU 上做 NDDMA 高速搬运,AICPU Kernel 则以通用方式覆盖全部 10 种整型/浮点类型。
约束说明
README 明确列出了四条约束,AICPU Kernel 源码 的 TileParaCheck 函数中逐条落地了这些校验逻辑:
- axis 必须在输入 Tensor 的维度范围内,支持负数索引(如
axis=-1表示最后一维)。源码中负索引通过axis = axis + dims归一化,随后校验axis < 0 || axis >= dims即报KERNEL_STATUS_PARAM_INVALID。 - tiles 必须大于 0。源码中
tiles <= 0直接返回参数非法。 - 输出 Tensor 在 axis 维度的大小必须等于输入在该维度的大小乘以 tiles。源码校验
shape_output[axis] != shape_input[axis] * tiles时报错,保证输出描述与属性严格自洽。 - 输入 Tensor 维度不超过 8 维。AICPU 实现通过
TileComputeInDims的 switch 分派支持 rank 1~8(rank 0 标量按特殊路径处理),超出范围返回KERNEL_STATUS_PARAM_INVALID。
图模式调用
README 的调用说明如下表:
| 调用方式 | 样例代码 | 说明 |
|---|---|---|
| 图模式调用 | test_geir_tile_with_axis | 通过算子IR构图方式调用 TileWithAxis 算子。 |
该样例程序基于 GEIR(图引擎 IR)构建一个最小图并执行,其完整流程可直接作为调用该算子的参考模板:
- 初始化图引擎:
ge::GEInitialize,并通过ge.exec.deviceId指定设备、ge.graphRunMode控制运行模式; - 构建算子节点:
auto node = op::TileWithAxis("tile_with_axis_1");,随后设置输入x(shape{2, 3, 2},FORMAT_ND)与属性:
node.set_input_x(xData);
node.SetAttr("axis", 1);
node.SetAttr("tiles", 2);
vector<int64_t> yShape = {2, 6, 2};
TensorDesc yDesc(ge::Shape(yShape), FORMAT_ND, inDtype);
node.update_output_desc_y(yDesc);
- 运行图并落盘:
session->AddGraph(...)后session->RunGraph(graph_id, input, output)执行,ProcessInputData/ProcessOutputData把输入输出 Tensor 写成.bin文件,便于与参考结果做逐字节比对。
样例特意选用 DT_INT64 作为输入类型(inDtype = DT_INT64),从而在 Ascend950 目标上验证 AICPU 路径的端到端正确性;如需验证 AICore 路径,只需把 inDtype 换成 DT_FLOAT/DT_FLOAT16/DT_INT8 等 AICore 定义支持的类型即可。
源码实现剖析
形状推导:输出 shape 如何自动计算
主机侧形状推导逻辑位于 tile_with_axis_infershape.cpp,核心规则:
- 常规情况:复制输入 shape 到输出,仅将
axis维替换为input_shape[axis] * tiles;负axis先做axis + rank归一化; - rank = 0(标量)特例:输出 shape 被推导为
[tiles],即一个 1 维、大小为 tiles 的张量,与 AICPU Kernel 中case 0的标量复制路径对应; - 未知 rank 特例:输入 rank 未知时输出同样置为未知 rank,保证动态形状场景下推导安全;
- 数据类型推导(
InferDataType4TileWithAxis)直接令输出 dtype 等于输入 dtype,印证了"y 与 x 数据类型一致"的参数约定。
AICore 路径:3D 折叠模型与 NDDMA 搬运
Ascend950(arch35)上的 AICore 实现是该算子工程上的亮点,相关文件包括 tile_with_axis.h、tile_with_axis_apt.cpp 和 tile_with_axis_tiling.cpp。
从源码结构看,整个实现把任意 rank 的输入折叠为统一的 3D 模型:
inShape = [outerDim, 1, rowLength]outShape = [outerDim, tiles, rowLength]- 其中
outerDim = prod(x.shape[0..axis-1]),rowLength = axisDim * innerDim,innerDim = prod(x.shape[axis+1..])
这一折叠模型体现在 TilingData 结构体中,字段包括展平后的 inShape[3]/outShape[3]、UB 块总数 totalCount、每核块数 perCoreCount、UB 切分轴 ubAxis(0=outerDim / 1=tiles / 2=rowLength)、切分因子 ubFactor、乒乓缓冲区大小 bufferSize,以及算子特有的 tiles 与 rowLength。
主机侧 Tiling 采用两步法(见 tile_with_axis_tiling.cpp):
- UB 切分:按
bufferSize = ubSize / 2(为 ping-pong 双缓冲各留一半)计算三条候选轴各自的ubFactor(每条轴上 UB 单块能容纳多少元素),优先级 0 > 1 > 2 选定初始轴; - 核心利用率调节:当
totalCount < coreNum * 0.8(TARGET_CORE_RATIO = 0.8)时,先在同轴上降低ubFactor增加块数,仍不足则跨轴回退到能产生更多块的候选轴;随后按MIN_PER_CORE_ELEMENTS = 4096限制块数上限,把totalCount均分为perCoreCount分派给各核,并通过SetBlockDim(realCoreNum)只启用实际需要的核数。
设备侧 Kernel 按 ubAxis 编译为 3 个模板实例(由 ASCENDC_TPL_SEL_PARAM(context, ubAxis) 选择):
- ubAxis=0:单次 3 维 NDDMA 把
ubFactor行各复制tiles份(loopSize[1]=tiles负责维间复制,loopSize[2]=ubFactor负责多行); - ubAxis=1:2 维 NDDMA 退化形式,沿 tiles 维重复
ubFactor次; - ubAxis=2:直接用
DataCopyPad(blockCount=1)连续搬运。
主循环为经典的 ping-pong 双缓冲流水线:UpdateLayoutByIdx 计算本块偏移后,依次执行 CopyIn(GM→UB)→ SetFlag/WaitFlag(MTE2_MTE3) 同步 → CopyOut(UB→GM)→ SetFlag/WaitFlag(MTE3_MTE2) 同步。由于 CopyOut 的目标 block 在输出 GM 上天然连续(输出就是输入的平铺重复),写回可以单指令完成,这也解释了为什么只有读入端需要复杂的 NDDMA 参数。
AICPU 路径:Eigen broadcast 的通用实现
AICPU 实现位于 tile_with_axis_aicpu.cpp,思路非常直接:把输入视为 1 维张量后 reshape 为原始 shape,再用 Eigen 的 broadcast 在 axis 维广播 tiles 份写回输出:
output0.reshape(out_reshape) = input0.reshape(in_reshape).broadcast(bcast);
两个值得注意的细节:
- tiles == 1 的快速路径:直接
memcpy_s输出等于输入,避免走完整的 reshape/broadcast 流程; - 内存对齐自适应:
TileCompute先用AddrAlignedCheck检查输入指针是否对齐,再分派Eigen::Aligned/Eigen::Unaligned两套模板实例,兼顾性能与正确性。
该文件末尾通过 OPS_MATH_REGISTER_CPU_KERNELV2(kTileWithAxis, TileWithAxisCpuKernel) 完成 AICPU 算子注册。
测试与验证路径
仓库为该算子提供了三层测试资产,覆盖从主机侧推导逻辑到设备侧数值正确性:
- test_tile_with_axis_infershape.cpp:单元测试,验证上述形状推导规则(含负 axis、标量 rank=0、未知 rank 等边界);
- test_tile_with_axis_tiling.cpp:针对 arch35 的 Tiling 单元测试,覆盖 UB 切分轴选择与核心利用率调节分支;
- test_tile_with_axis.cpp:AICPU Kernel 数值正确性测试。
图模式端到端验证则由 examples/test_geir_tile_with_axis.cpp 承担:构图 → RunGraph → 输入/输出落盘为 bin 文件,形成完整可复现的验证闭环。
小结
TileWithAxis 是 ops-math 中一个"语义简单、实现考究"的张量展开算子:
- 语义层面:输出 shape 与输入一致,仅
y.shape[axis] = x.shape[axis] * tiles,axis 支持负索引且默认 1,tiles 必须大于 0; - 接入层面:通过 GEIR 构图调用,输入支持 11 种类型(含 BF16),AICore 路径覆盖 6 种主力类型(Ascend950),宽整型自动落到 AICPU 路径;
- 实现层面:AICore 侧把任意 rank 折叠为 3D 模型,用 ubAxis 0/1/2 三套 NDDMA 模板 + ping-pong 双缓冲完成高效搬运,主机侧 Tiling 通过利用率调节保证多核均衡;AICPU 侧以 Eigen broadcast 提供全类型兜底;
- 产品支持:根据 README,该算子支持 Ascend 950PR/950DT、Atlas A3/A2 训练与推理系列产品、Atlas 200I/500 A2 推理产品以及 Atlas 推理/训练系列产品。
在 ops-math 仓库中,该算子与同目录下的 tile(网格平铺语义)形成功能互补:需要"同一维度重复自身"时用 TileWithAxis,需要"多轴网格复制"时用 tile,二者共同覆盖了张量展开的常见需求。