深入解析 CANN pyasc 多核 Matmul Tiling 的 get_single_shape：读取单核计算形状的完整指南

深入解析 CANN pyasc 多核 Matmul Tiling 的 get_single_shape读取单核计算形状的完整指南【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc导读本文围绕 CANN pyasc 中asc.lib.host.MultiCoreMatmulTiling.get_single_shape接口展开讲解如何在多核 Matmul 算子开发中获取 Tiling 计算完成后的单核计算形状single_core_m/single_core_n/single_core_k。通过阅读本文你将掌握该接口的调用时机、返回值语义、与set_single_shape等接口的配合方式并从 pybind11 绑定源码与单元测试两个层面理解其底层实现能够在自己的算子 Tiling 程序中正确读取并使用单核分片尺寸。接口速览get_single_shape是 MultiCoreMatmulTiling 多核 Matmul Tiling 对象提供的一个查询类Getter接口其作用是在完成 Tiling 计算后回读三个关键的单核分片参数MultiCoreMatmulTiling.get_single_shape(self: libhost.MultiCoreMatmulTiling) → object该接口在 Tiling 计算get_tiling完成后调用返回计算得到的single_core_m单核负责计算的 M 方向元素个数single_core_n单核负责计算的 N 方向元素个数single_core_k单核负责计算的 K 方向元素个数。这三个参数在多核并行切分中起着核心作用Kernel 侧通常依据它们来计算当前核block_idx负责的数据切片偏移量例如仓库示例 examples/03_matmul_mix/matmul_mix.py 中的calc_offsets即通过tiling.m.ceildiv(tiling.single_core_m)等表达式推导各核的数据偏移。与 Ascend C 的对应关系该接口是 Ascend C 中MultiCoreMatmulTiling类的GetSingleShape方法的 Python 封装对应的 C 函数原型为int32_t GetSingleShape(int32_t shapeM, int32_t shapeN, int32_t shapeK)即通过三个输出引用参数返回 M/N/K 三个方向的单核形状返回值int32_t用于指示调用是否成功。从源码结构看pybind11 绑定将这一 C 接口封装为 Python 的无参调用形式内部先声明三个int32_t变量作为输出再调用底层方法并把结果组装为 Python 元组返回详见下文源码级解读。参数与返回值说明参数说明从 Python 侧看get_single_shape不接收任何输入参数。原文档参数说明一节中出现的 flag是否使能切K轴 属于模板复制产生的笔误实际该接口没有输入参数是否使能切K轴 是 enable_multi_core_split_k 接口的职责读者在使用时无需为get_single_shape传参。返回值说明接口以元组方式返回(single_core_m, single_core_n, single_core_k)。需要注意原文档中写作 (single_core_m, single_core_m, single_core_k)第二个元素应为single_core_n从绑定源码 MatmulApiTiling.cpp 看返回的是py::make_tuple(shapeM, shapeN, shapeK)即按 M、N、K 顺序排列的三元组。在 Python 中典型的使用方式为直接解包single_core_m, single_core_n, single_core_k tiling.get_single_shape()约束说明使用该接口需满足以下约束必须使用已创建的MultiCoreMatmulTiling对象调用必须在完成 Tiling 计算get_tiling之后调用。原因在于single_core_m/single_core_n/single_core_k是 Tiling 计算过程的结果产物Tiling 函数会依据用户设置的核数set_dim、单核形状set_single_shape、对齐值set_align_split等输入综合硬件平台信息计算并写出最终的切分结果。在get_tiling之前这些值尚未确定调用查询会得到非预期结果。完整调用示例以下示例完整演示MultiCoreMatmulTiling从创建、配置、计算到回读单核形状的全过程代码基于原文档示例整理并结合测试用例 test_multi_core_matmul_tiling.py 修正了实际可运行的调用方式import asc.lib.host as host # 1. 获取硬件平台信息并创建多核 Tiling 对象 ascendc_platform host.get_ascendc_platform() tiling host.MultiCoreMatmulTiling(ascendc_platform) # 2. 配置参与运算的核数与各矩阵类型 use_core_nums 8 tiling.set_dim(use_core_nums) # 设置多核 Matmul 参与运算的核数 tiling.set_a_type(host.TPosition.GM, host.CubeFormat.ND, host.DataType.DT_FLOAT16) tiling.set_b_type(host.TPosition.GM, host.CubeFormat.ND, host.DataType.DT_FLOAT16) tiling.set_c_type(host.TPosition.GM, host.CubeFormat.ND, host.DataType.DT_FLOAT) tiling.set_bias_type(host.TPosition.GM, host.CubeFormat.ND, host.DataType.DT_FLOAT) # 3. 设置形状信息 tiling.set_shape(1024, 1024, 1024) # 设置 Matmul 计算的形状 m/n/k tiling.set_single_shape(1024, 1024, 1024) # 设置单核计算的形状不设置则传 -1 由 Tiling 自行计算 tiling.set_org_shape(1024, 1024, 1024) # 设置原始完整形状 tiling.set_bias(True) tiling.set_buffer_space(-1, -1, -1) # 可用 Buffer 空间-1 表示使用默认值 # 4. 执行 Tiling 计算 tiling_data host.TCubeTiling() ret tiling.get_tiling(tiling_data) # 5. 在 get_tiling 之后获取计算后的单核形状 single_core_m, single_core_n, single_core_k tiling.get_single_shape() print(single_core_m, single_core_n, single_core_k)源码级解读Python 接口的底层绑定在 pyasc 仓库中该接口的绑定位于 python/asc/lib/host/bindings/MatmulApiTiling.cpp其核心逻辑如下.def( get_single_shape, [](MultiCoreMatmulTiling self) - py::object { int32_t shapeM, shapeN, shapeK; auto ret self.GetSingleShape(shapeM, shapeN, shapeK); if (ret ! 0) { return py::none(); } else { return py::make_tuple(shapeM, shapeN, shapeK); } }, ... )这段绑定代码揭示了几个重要的实现事实无参调用、元组返回Python 侧调用时无需传入参数绑定内部为底层 C 接口GetSingleShape的输出引用参数分配临时变量调用后通过py::make_tuple(shapeM, shapeN, shapeK)组装为 Python 元组失败返回 None当底层调用返回值ret ! 0即失败时Python 侧返回py::none()而非抛出异常。因此防御性编程中可先判断返回值是否为None再解包类型标注在类型桩文件 python/asc/lib/host/wrappers.py 中声明为def get_single_shape(self) - object说明返回类型为通用对象实际为三元组或None。单元测试 python/test/unit/lib/host/test_multi_core_matmul_tiling.py 对该行为给出了直接验证def test_get_single_shape(asc_platform): matmul_tiling host.MultiCoreMatmulTiling(asc_platform) matmul_tiling.set_shape(32, 32, 32) matmul_tiling.set_single_shape(32, 16, 8) tiling asc.adv.TCubeTiling() ret matmul_tiling.get_tiling(tiling) result matmul_tiling.get_single_shape() assert ret 0 assert result is not None single_core_m, single_core_n, single_core_k result assert single_core_m 32 assert single_core_n 16 assert single_core_k 8该测试确认在set_single_shape(32, 16, 8)且完成get_tiling后get_single_shape()返回的元组与设置的输入形状完全一致且元组顺序为(m, n, k)。与相关接口的配合使用get_single_shape读取的是多核切分的最终结果与其对应的写侧接口是 set_single_shape设置单核计算的输入形状参数默认值为-1表示不指定、由 Tiling 函数自行计算。二者关系如下接口方向作用set_single_shape(single_m_in, single_n_in, single_k_in)输入设置单核形状的期望值单位元素-1表示交由 Tiling 自行计算get_single_shape()输出获取 Tiling 计算后实际的单核形状三元组此外多核切分的最终结果还受以下接口共同影响set_dim设置参与运算的核数直接决定 M/N 方向如何分给多个核set_align_split设置single_core_m/n/k的对齐值例如 M 对齐到 64则切分出的single_core_m为 64 的倍数enable_multi_core_split_k使能切 K 轴多核场景默认不切 Kget_core_num获取多核切分所使用的 BlockNum 参数返回(dim, m_dim, n_dim)元组与get_single_shape同为get_tiling后的查询类接口。这些接口的统一约束是设置类接口需在get_tiling之前调用查询类接口需在get_tiling之后调用详见 host.md 中的接口列表说明。典型应用场景多核算子中计算数据偏移在实际的多核 Matmul 算子中Kernel 侧通常需要根据single_core_m/single_core_n/single_core_k计算每个核负责的 A/B/C 矩阵切片偏移。仓库示例 examples/03_matmul_mix/matmul_mix.py 展示了这种典型用法asc.jit def calc_offsets(tiling: asc.adv.TCubeTiling, is_trans_a: bool False, is_trans_b: bool False) - Tuple[int, int, int, int, int]: block_idx asc.get_block_idx() m_single_blocks tiling.m.ceildiv(tiling.single_core_m) ...可以看到TCubeTiling中的single_core_m等字段正是get_single_shape所读取的数据来源Host 侧 Tiling 计算完成后这些字段被写入TCubeTiling结构体供 Kernel 侧通过tiling.single_core_m等属性访问。因此在 Host 侧 Tiling 函数中如果你需要把这些分片信息进一步加工、封装或打印输出就可以通过get_single_shape()一次性读取三个维度而无需逐个访问tiling_data的字段。常见问题与注意事项调用时机错误在get_tiling之前调用get_single_shape无法拿到有效结果。请务必遵循先get_tiling后查询的顺序返回值判空底层绑定在 C 调用失败时返回py::none()建议先判断结果是否为None再解包避免运行时解包错误元组顺序返回元组顺序固定为(single_core_m, single_core_n, single_core_k)与 C 原型GetSingleShape(int32_t shapeM, int32_t shapeN, int32_t shapeK)的参数顺序一致不要搞混与原文档示例的差异原文档示例中ret tiling.get_single_shape(single_m, single_n, single_k)的传参写法与仓库实际绑定不符——当前版本该接口为无参调用并返回元组实际用法应以本文及仓库测试用例为准与set_single_shape的配合set_single_shape传入的值是 Tiling 计算的期望输入最终实际分片结果可能因对齐、核数、Buffer 空间等约束被 Tiling 函数调整务必通过get_single_shape读取最终值而不是假定与输入完全一致。小结MultiCoreMatmulTiling.get_single_shape是多核 Matmul Tiling 流程中一个简单但关键的查询接口在get_tiling完成后调用无参数、返回(single_core_m, single_core_n, single_core_k)三元组失败时返回None。其底层由 pybind11 绑定封装 Ascend C 的GetSingleShape接口实现见 MatmulApiTiling.cpp并有对应的单元测试保障行为正确见 test_multi_core_matmul_tiling.py。在多核 Matmul 算子开发中它是衔接 Host 侧 Tiling 与 Kernel 侧数据切片逻辑的重要桥梁。【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考