PyPTO cumsum 算子实战:接口用法、TileShape 切分策略与框架内部分块累加实现解析
PyPTO cumsum 算子实战:接口用法、TileShape 切分策略与框架内部分块累加实现解析
本文围绕 PyPTO(CANN/pypto 项目)的 pypto.cumsum 算子展开:先完整给出该算子的函数原型、参数约束与调用示例,再结合开源仓库源码,深入剖析框架在 Vector 核上对累积和(Cumulative Sum)进行切块(Tiling)与跨块进位(Carry)传播的底层机制,帮助读者不仅"会用"cumsum,还能理解它在 Ascend NPU 上的真实执行方式。
1. 功能定位与产品支持情况
pypto.cumsum 是 PyPTO tensor API 中提供的向量(Vector)累加算子,用于计算输入 Tensor input 沿指定维度 dim 的累积和,输出一个与输入 Shape 一致的 Tensor。它等价于 PyTorch 中 torch.cumsum 的语义,在注意力前缀求和(Softmax 归一化)、扫描(Scan)类算法、滑动统计等场景中是基础构件。
产品支持情况
根据 API 文档,该算子的产品支持情况如下:
- Ascend 950PR / Ascend 950DT:支持;
- Atlas A3 训练系列产品 / Atlas A3 推理系列产品:支持;
- Atlas A2 训练系列产品 / Atlas A2 推理系列产品:支持。
源码入口链路
从仓库结构看,该接口的调用链路清晰可溯:
- 用户侧 Python 封装位于 python/pypto/op/math.py,
cumsum函数带@op_wrapper装饰器,直接转发到底层绑定实现; - Pybind 绑定位于 python/src/bindings/operation.cpp:
m.def("cumsum", [](const Tensor& input, int axis) { return npu::tile_fwk::CumSum(input, axis); }, ...),即 Python 层的pypto_impl.cumsum(input, dim)最终调用 C++ 的npu::tile_fwk::CumSum; - C++ 算子核心实现(含校验、类型处理与 Tiling 逻辑)位于 framework/src/interface/operation/vector/cumulative.cpp。
2. 函数原型与参数说明
函数原型
cumsum(input: Tensor, dim: int) -> Tensor
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| input | 输入 | 源操作数。支持的类型为:Tensor。Tensor 支持的数据类型为:DT_FP16,DT_BF16,DT_INT16,DT_INT32,DT_FP32。不支持空 Tensor;Shape 仅支持 1-4 维;Shape Size 不大于 2147483647(即 INT32_MAX)。 |
| dim | 输入 | 指定进行累加的维度。int 类型。 |
返回值说明
- 输出 Tensor 的 Shape 与输入
input一致; input为 DT_FP16、DT_BF16、DT_FP32 等类型时,输出数据类型和输入一致;input为 DT_INT16、DT_INT32 时,输出数据类型为 DT_INT64。
这一"整型升精度"规则并非文档约定而已,源码中可以直接印证:framework/src/interface/operation/vector/cumulative.cpp 中 CumOperation 首先将 axis 规范化为 tmpAxis0 = axis < 0 ? shapeSize + axis : axis(因此负维度同样合法),随后判断:
if (resultDType == DataType::DT_INT16 || resultDType == DataType::DT_INT32) {
resultDType = DataType::DT_INT64;
}
即整型输入会在结果 Tensor 层面提升为 DT_INT64,避免累加过程中的位宽溢出。
3. 约束说明(附源码校验点)
文档给出的约束条件逐条对应到源码中的校验函数,便于在排查报错时快速定位:
- dim 有效范围:必须在输入 Tensor 的有效维度范围内,满足
-input.dim <= dim < input.dim; - dim 轴 ViewShape 不可切分:
input的dim轴 ViewShape 不可切分,其余维度不做限制; - UB 内存约束:TileShape 的维度与 input 相同,所有输入和输出的 TileShape 大小总和不能超过 UB 内存的大小;
- 格式约束:Tensor 类型输入不支持
TileOpFormat.TILEOP_NZ格式。
对应源码中的校验函数 CheckCumOperation(见 cumulative.cpp):
void CheckCumOperation(const Tensor& input, const int& axis, const bool& is_sum)
{
if (is_sum) {
std::unordered_set<DataType> supportedTypes = {DT_FP32, DT_FP16, DT_INT32, DT_INT16, DT_BF16};
CheckTensorDataType(input.GetStorage(), supportedTypes, "CUMSUM");
CheckTensorDimRange(input.GetStorage(), 1, NUM_VALUE_4, "CUMSUM"); // 1-4 维
CheckTensorShapeSize(input.GetStorage(), "CUMSUM"); // Shape Size 检查
}
...
int tmpAxis0 = axis;
CheckAxisRange(input, tmpAxis0); // 维度范围检查
if (input.GetShape().size() == 1) {
CHECK(..., tmpAxis0 == 0) << "when input.GetShape().size() is 1, axis must be 0";
}
...
}
可以看到:支持类型集合 {DT_FP32, DT_FP16, DT_INT32, DT_INT16, DT_BF16}、维度范围 1 ~ 4、1 维输入时 axis 必须为 0,这些细节与文档约束一一对应。而 NZ 格式的拒绝则在 CumSum 入口处执行:CheckTensorFormat(input.GetStorage(), {TileOpFormat::TILEOP_NZ}, "CumSum")。
4. 调用示例
4.1 TileShape 设置示例
调用该 operation 接口前,应通过 set_vec_tile_shapes 设置 TileShape,且 TileShape 维度应与输出一致。
例如输入 input 的 shape 为 [m, n],输出为 [m, n],TileShape 设置为 [m1, n1],则 m1、n1 分别用于切分 m、n 轴:
pypto.set_vec_tile_shapes(4, 16)
set_vec_tile_shapes 的定义位于 python/pypto/_controller.py,支持以变长参数或列表形式传入各维度的 tile 大小。该设置决定了 Vector 核上累加循环的切块粒度:对于非累加维度,tile 大小就是常规的空间切分步长;对于累加维度(dim 轴),tile 大小决定了单次累加覆盖的长度以及进位(carry)传播的粒度。
4.2 接口调用示例
input = pypto.tensor([2, 3], pypto.DT_INT32) # shape (2, 3)
dim = 0
y = pypto.cumsum(input, dim)
结果示例如下:
输入数据x: [[0 1 2],
[3 4 5]]
输出数据y: [[0 1 2],
[3 5 7]] # shape (2, 3)
沿 dim=0 累加时,第 1 行等于第 0 行 + 本行([3,4,5] = [0,1,2] + [3,4,5]),即累积和是"含自身在内的前缀和"。Python 侧封装见 python/pypto/op/math.py 中的 cumsum 定义,其 docstring 示例与上述结果一致。
4.3 完整 Kernel 级实战:view + cumsum + assemble 组合
仓库中的系统级测试 python/tests/st/operation/vector/test_cumsum_onboard.py 展示了一个典型的 2D 分块累加 Kernel 写法,值得完整参考:
@pypto.frontend.jit(debug_options={"runtime_debug_mode": 0, "compile_debug_mode": 0})
def cumsum_onboard_2d_1input_2d_output_kernel(
input0: pypto.Tensor(), output0: pypto.Tensor(), config: CumsumOnboardConfig
):
pypto.set_vec_tile_shapes(*config.tile_shape)
for index_0 in pypto.loop(config.loop_ranges[0]):
for index_1 in pypto.loop(config.loop_ranges[1]):
offsets = [index_0 * config.execution_view_shape[0], index_1 * config.execution_view_shape[1]]
input0_offset = [0 if config.input_shapes[0][axis] == 1 else offsets[axis] for axis in range(2)]
input0_view = pypto.view(input0, config.input_view_shapes[0], input0_offset)
result = pypto.cumsum(input0_view, config.axis)
output_offset = [
0 if config.output_offset_map[axis] < 0 else offsets[config.output_offset_map[axis]]
for axis in range(2)
]
pypto.assemble(result, output_offset, output0)
其验证方式是用 PyTorch 结果作为黄金参考:expected = [torch.cumsum(inputs_cpu[0], dim=config.axis)],并配合 @pypto.options(pass_options={"enable_slice": True}) 开启切片优化。该用例直观体现了约束"dim 轴 ViewShape 不可切分":在按 tile 遍历大 Tensor 时,view 取出的子块在累加维度上保持完整(offset 只在非累加维度上移动),而累加语义的正确性由框架在块间自动维护进位。
5. 源码深度剖析:CumSum 在框架内部如何执行
5.1 数据类型分派策略
CumSum 最终进入 CumOperation → 根据输入类型走不同的计算通路(见 cumulative.cpp 的 TensorCumOperation):
- DT_INT16:先
Cast到 DT_FP32 再截断到 DT_INT32,在 INT32 上执行OP_CUM_SUM,最后再 Cast 回输出(DT_INT64),规避 16 位宽度溢出; - DT_FP16 / DT_BF16:统一升精度到 DT_FP32 执行
OP_CUM_SUM,再 Cast 回原类型输出; - DT_INT32:直接在 INT32 上执行
OP_CUM_SUM,输出 Cast 为 DT_INT64; - 其他(DT_FP32):直接执行
OP_CUM_SUM。
也就是说,浮点低位宽(FP16/BF16)与整型输入在设备上实际都是在更高精度路径上完成累加的,这与返回值"整型升 64 位"的精度语义相呼应。
5.2 分块累加的两阶段 Tiling 与进位传播
Tiling 是理解约束 2("dim 轴 ViewShape 不可切分")的关键。cumulative.cpp 中对 CumSum/CumProd 的 tiling 策略有一段非常清晰的注释与实现:
// CumSum/CumProd tiling (rank 1-4):
// Phase 1 — loop and tile every non-cum dimension (0..rank-1 except axis).
// Phase 2 — within each fixed non-cum fiber, tile only along axis and propagate
// carry (last cum-axis element) between consecutive tiles on that axis.
// Carry is scoped per non-cum fiber so higher-rank slices do not clobber each other.
具体机制分两个阶段:
- 阶段一(非累加维):
InnerTiledCumNonAxisDims对除axis外的所有维度按 TileShape 循环切块(BuildNonCumDimIndices构造这些维度索引); - 阶段二(累加维):对每一条固定的非累加维"纤维"(fiber),
TiledCumAlongAxis沿axis方向按cumTileSize逐块推进。每个 tile 内先对局部输入执行一次OP_CUM_SUM得到局部前缀和;若该 tile 在 axis 上不是第一块(offset[axis] > 0),则取出上一块输出中"axis 维末位元素"(carry,通过View取出 shape 中 axis 维为 1 的末行/末列),用TILE_EXPAND沿 axis 广播后与当前块的局部前缀和做OP_ADD,得到最终局部输出;
if (tileInfo.dstTileInfo.offset[axis] > 0) {
// 上一块的累积和末位元素作为 carry
auto& eop = function.AddOperation("TILE_EXPAND", {lastCarry}, {lastTile});
eop.SetAttribute(OpAttributeKey::expandDims, std::vector<int>{axis});
function.AddOperation(Opcode::OP_ADD, {srcTile, lastTile}, {dstTile});
} else {
function.AddOperation(Opcode::OP_REGISTER_COPY, {srcTile}, {dstTile});
}
随后从当前块输出中取出 axis 维末位元素,更新 lastCarry,供下一个 tile 使用。由于 carry 的作用域限定在"每条非累加纤维"内(注释中 "Carry is scoped per non-cum fiber"),高维切块时不同纤维的进位互不污染——这正是约束 2 要求 dim 轴不可在 View 层切分的工程原因:跨块连续性由框架内部的 carry 机制保证,而用户层 view 若切断了 dim 轴,carry 链就无从建立。
5.3 对累加维非最后一维的特殊处理
CumOperation 中还存在一段值得注意的转置优化逻辑:当结果类型为浮点(非 INT64)、axis 指向最后一个维度(tmpAxis0 == n_1)且不是 0 维时,框架会先 Transpose(input, {n_2, n_1}) 把累加维挪到倒数第二位,同步交换 TileShape 与 dynValidShape 中对应两个维度的大小,完成累加后再转置回原布局:
if ((resultDType != DataType::DT_INT64) && tmpAxis0 > 0 && tmpAxis0 == n_1) {
Tensor tmpInput = Transpose(input, {n_2, n_1});
...
TileShape::Current().SetVecTile(tmpVectile); // 交换 tile[n_2] 与 tile[n_1]
...
Tensor tmpresult = Transpose(result, {n_2, n_1});
TileShape::Current().SetVecTile(oriVectile); // 恢复原 TileShape
}
从源码结构看,这反映了对末维连续累加(向量化最有利)与特定维度布局的底层偏好;对上层用户而言是透明的,但解释了为何 TileShape 交换后最终仍能正确还原结果。
5.4 测试体系印证
仓库为该算子提供了多层级测试,可作为行为验证与回归依据:
- C++ 系统测试:framework/tests/st/operation/src/test_CumSum_operation.cpp,覆盖双切(double cut)等多种 view/tile 组合,其中
GetCumOperationViewShape明确体现了"axis 维保持完整、其余维按 tile 截断"的切分规则; - Python 系统测试:python/tests/st/operation/vector/test_cumsum_onboard.py,以
torch.cumsum为黄金参考做端到端精度比对; - 动态 shape 下的代码生成测试:framework/tests/ut/codegen/src/test_dynamic/test_codegen_dyn_vector/test_codegen_dyn_cumsum.cpp。
6. 使用建议小结
- 维度选择:
dim支持负值(源码中做了shapeSize + axis归一化);1 维输入只能取 0; - 类型预期:FP16/BF16/FP32 输出与输入同类型,INT16/INT32 输入输出为 INT64,涉及整型累计请预留 64 位消费端;
- TileShape 设置:维度数须与 input 一致;累加维的 tile 大小影响 carry 传播次数,非累加维的 tile 大小影响空间切分并行度;总 Tile 占用受 UB 内存限制;
- 格式:输入不可为
TILEOP_NZ格式; - 分块编程:大 Tensor 场景参考第 4.3 节的
view + cumsum + assemble写法,保持累加维完整、非累加维分块遍历。
以上行为与实现均基于当前仓库代码与 docs/zh/api/tensor_api/operation/pypto-cumsum.md 文档;涉及具体硬件特性(如 UB 容量、末维转置优化的实际收益)请以实际硬件与版本发布说明为准。