pyasc 的 asc.lib.host Matmul Tiling API 使用指南从 Tiling 参数计算到多核切分【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc导读本文围绕 CANN pyasc 仓库中 docs/python-api/lib/host.md 所定义的asc.lib.host模块展开系统讲解如何使用 Host 侧的 Matmul Tiling APIMatmulApiTiling、MultiCoreMatmulTiling、BatchMatmulTiling在昇腾 AI 处理器上为 Matmul Kernel 计算 Tiling 参数。读完本文后你将掌握 Tiling API 的完整调用流程、各配置接口的参数含义与约束、多核切分与 Batch 场景下的使用要点并能结合 Kernel 侧TCubeTiling结构体独立写出可运行的 Host 侧 Tiling 代码。asc.lib.host是 pyasc 提供给用户的 Host 侧算子开发接口位于仓库 python/asc/lib/host/Python 封装与 python/asc/lib/host/bindings/pybind 绑定中。通过asc.lib.host模块用户可以调用与 Ascend C 一一对应的 Matmul Tiling 接口从而获取 Kernel 侧TCubeTiling结构体中的相关参数避免手工推导 baseM、baseN、baseK 等切分信息。一、模块定位Host 侧 Tiling 计算与 Kernel 侧如何衔接1.1 Tiling 在 Matmul 算子开发中的作用在昇腾 AI 处理器上运行 Matmul 计算时矩阵乘法通常远超单个 AI Core 的片上存储容量L1 Buffer、L0C Buffer、UB 等因此需要将大矩阵切分为若干小分片Tile逐片完成矩阵乘累加。这一过程涉及三个层面的信息原始矩阵信息M、N、K 的大小A/B/C 矩阵的数据类型、数据格式ND/NZ 等、所在 buffer 位置切分策略信息每个 Tile 的 baseM/baseN/baseK、参与计算的核数、K 轴是否切分等循环与搬移信息矩阵的 Layout 轴信息B/S/N/G/D、Batch 数、计算方向的遍历顺序等。asc.lib.host提供的三组 Tiling 类正是用于在 Host 侧统一计算并封装这些信息最终通过TCubeTiling结构体传递给 Kernel。1.2 从用户输入到 TCubeTiling 的调用链路从源码文档 get_tiling 可以看出整个调用流程是通过host.get_ascendc_platform()获取当前平台信息SOC 版本用平台信息构造MatmulApiTiling或MultiCoreMatmulTiling对象依次调用set_a_type/set_b_type/set_c_type/set_bias_type等接口描述矩阵属性调用set_shape、set_org_shape等接口描述矩阵形状调用set_buffer_space、set_batch_num、set_traverse等接口描述资源与策略构造host.TCubeTiling()结构体实例调用get_tiling(tiling)获取 Tiling 结果通过返回值判断 Tiling 计算是否成功非 -1 即成功。对应 Kernel 侧TCubeTiling结构体与 Ascend C 算子中Init接口使用的 Tiling 结构保持一致Kernel 从 GM 侧读取 Host 计算好的 Tiling 参数即可完成分块、搬移与累加。pyasc 的 Kernel 侧示例可参考仓库 examples/04_matmul_cube_only/matmul_cube_only.py 与 examples/05_matmul_leakyrelu/matmul_leakyrelu.py。二、三个 Tiling 类的职责划分asc.lib.host提供三类 Tiling 接口对象类职责关键区别MatmulApiTiling基础 Matmul Tiling 计算单核/多核通用提供全部基础设置接口MultiCoreMatmulTiling多核 Matmul Tiling 计算在基础接口之上增加多核切分相关接口BatchMatmulTilingBatch Matmul Tiling 计算用于多 Batch 场景三个类共享绝大部分接口A/B/C/Bias 类型设置、形状设置、buffer 空间设置等因此 host.md 首先统一列出共有接口列表再分别给出MultiCoreMatmulTiling与BatchMatmulTiling的独有接口。下文先讲解共有接口再讲解多核专属接口。三、共有接口详解MatmulApiTiling / MultiCoreMatmulTiling / BatchMatmulTiling3.1 矩阵属性设置set_a_type / set_b_type / set_c_type / set_bias_type这四个接口分别设置 A/B/C/Bias 矩阵的位置、数据格式、数据类型、是否转置等信息。以set_a_type为例其对应 Ascend C 函数原型为int32_t SetAType(TPosition pos, CubeFormat type, DataType dataType, bool isTrans false)Python 侧调用方式见 set_a_typeimport asc.lib.host as host ascendc_platform host.get_ascendc_platform() tiling host.MatmulApiTiling(ascendc_platform) # 设置A矩阵buffer位置为GM数据格式为ND数据类型为bfloat16默认不转置 tiling.set_a_type(host.TPosition.GM, host.CubeFormat.ND, host.DataType.DT_FLOAT16)参数说明pos矩阵所在 buffer 位置取值如host.TPosition.GMGlobal Memory、host.TPosition.L1等type数据格式如host.CubeFormat.ND、host.CubeFormat.NZdata_type数据类型如host.DataType.DT_FLOAT16、host.DataType.DT_FLOAT、host.DataType.DT_BF16等is_trans是否转置默认False。set_b_type、set_c_type的签名与之类似。set_bias_type仅包含位置、数据格式、数据类型三个参数Bias 不做转置对应原型int32_t SetBiasType(TPosition pos, CubeFormat type, DataType dataType)。一致性约束重要这几个接口设置的矩阵属性必须与 Kernel 侧Matmul对象初始化时传入的配置保持一致否则 Host 计算出的 Tiling 参数无法正确驱动 Kernel 执行。3.2 形状设置set_shape 与 set_org_shapeset_shape(m, n, k)设置本次 Matmul 计算的形状对应原型int32_t SetShape(int32_t m, int32_t n, int32_t k)该形状可以是原始完整矩阵也可以是切分后的局部矩阵单位为元素该形状的矩阵乘可以由单核或多核共同计算完成。set_org_shape(*args, **kwargs)设置 Matmul 计算时的原始完整形状提供两种重载见 set_org_shapeint32_t SetOrgShape(int32_t orgMIn, int32_t orgNIn, int32_t orgKIn) int32_t SetOrgShape(int32_t orgMIn, int32_t orgNIn, int32_t orgKaIn, int32_t orgKbIn)第一种用于 Ka Kb 的场景直接传 orgM / orgN / orgK第二种用于 A/B 矩阵 K 维不一致Ka ≠ Kb的场景此时 org_ka_in、org_kb_in 可以不相等。理解要点org_ka_in / org_kb_in 并不是实际 Matmul 计算时的 K而只是辅助 Matmul API 做数据搬运时偏移计算的原始形状参数。这一点在文档 set_org_shape 中有明确约束说明。3.3 资源空间设置set_buffer_spaceset_buffer_space设置 Matmul 计算时可用的各 Buffer 空间大小单位为字节tiling.set_buffer_space(l1_size-1, l0_c_size-1, ub_size-1, bt_size-1)对应原型int32_t SetBufferSpace(int32_t l1Size -1, int32_t l0CSize -1, int32_t ubSize -1, int32_t btSize -1)参数含义默认值l1_sizeL1 Buffer 可用空间字节-1表示使用 AI 处理器默认 L1 Buffer 大小l0_c_sizeL0C Buffer 可用空间字节-1表示使用默认 L0C Buffer 大小ub_sizeUnified BufferUB可用空间字节-1表示使用默认 UB 大小bt_sizeBiasTable Buffer 可用空间字节-1表示使用默认 BiasTable 大小实际开发中用户通常直接传-1让 Tiling 引擎使用芯片默认 Buffer 容量仅在需要限制资源如为其他算子预留空间时才显式传值。注意单核MatmulApiTiling示例中常写set_buffer_space(-1, -1, -1)省略 bt_size而多核MultiCoreMatmulTiling示例则写set_buffer_space(-1, -1, -1, -1)二者等价于全部使用默认值。3.4 计算方向与调优set_traverse、set_double_buffer、set_mad_type、set_split_rangeset_traverse(traverse)设置固定的 Matmul 计算方向M 轴优先还是 N 轴优先。可选值host.MatrixTraverse.FIRSTM/host.MatrixTraverse.FIRSTN。这决定了一次迭代计算出[baseM, baseN]大小的 C 矩阵分片后下一次迭代输出的 C 矩阵位置沿哪个方向偏移。set_double_buffer(a, b, c, bias, trans_nd2nzTrue, trans_nz2ndTrue)设置 A/B/C/Bias 是否使能 double buffer 功能以及是否需要进行 ND2NZ / NZ2ND 的格式转换主要用于 Tiling 函数内部调优。当 MTE3 与 MTE2 流水存在较多串行等待时使能 double buffer 可以提升流水并行度。set_mad_type(mad_type)设置是否使能 HF32 模式当前版本暂不支持。set_split_range(...)设置 baseM/baseN/baseK 的最大值和最小值当前版本暂不支持该功能。3.5 Batch 场景set_batch_num 与 set_batch_info_for_normalset_batch_num(batch)设置多 Batch 计算的最大 Batch 数最大 Batch 数为 A 矩阵 batchA 和 B 矩阵 batchB 中的最大值。调用iterate_batch接口之前需要在 Host 侧 Tiling 实现中先调用本接口。set_batch_info_for_normal(...)设置 A/B 矩阵的 M/N/K 轴信息以及 Batch 数。仅当 Layout 类型为 NORMAL 时在调用iterate_batch或iterate_n_batch接口之前需要调用本接口。3.6 Layout 轴信息set_a_layout / set_b_layout / set_c_layout对于 BSNGD、SBNGD、BNGS1S2 等 Layout 格式调用iterate_batch接口之前必须在 Host 侧 Tiling 实现中通过set_a_layout/set_b_layout/set_c_layout设置 A/B/C 矩阵的 B、S、N、G、D 五个轴的信息tiling.set_a_layout(a_bnum, a_snum, 1, a_gnum, a_dnum) # 设置 A 矩阵排布 tiling.set_b_layout(b_bnum, b_snum, 1, b_gnum, b_dnum) tiling.set_c_layout(c_bnum, c_snum, 1, c_gnum, c_dnum) tiling.set_batch_num(batch_num)其中参数顺序为(b, s, n, g, d)b 为 B 轴Batch信息、s 为 S 轴信息、n 为 N 轴信息、g 为 G 轴信息、d 为 D 轴信息。这里 n 轴传 1 是因为在上述示例场景中 N 维信息由 S 轴表达具体取值需要与 Kernel 侧矩阵排布一致。3.7 量化场景set_dequant_type 与 set_sparseset_dequant_type(...)设置量化或反量化时的模式用于量化 Matmul 场景。set_sparse(is_sparce_in)设置 Matmul 的使用场景是否为 Sparse Matmul稀疏矩阵乘场景需要在 Kernel 侧同样开启稀疏模式时配套使用。3.8 自定义 MatmulConfigset_matmul_config_paramsset_matmul_config_params用于在计算 Tiling 时自定义 MatmulConfig 参数对应原型void SetMatmulConfigParams(int32_t mmConfigTypeIn 1, bool enableL1CacheUBIn false, ScheduleType scheduleTypeIn ScheduleType::INNER_PRODUCT, MatrixTraverse traverseIn MatrixTraverse::NOSET, bool enVecND2NZIn false) void SetMatmulConfigParams(const MatmulConfigParams configParams)关键参数mm_config_type_inMatmul 模板类型需与 Matmul 对象创建的模板一致当前只支持 0 或 1enable_l1_cache_ub_in是否使能 L1 缓存 UB 计算块适合 MTE3 和 MTE2 流水串行较多的场景schedule_type_inMatmul 数据搬运模式traverse_in矩阵运算的循环迭代顺序en_vec_nd2nz_in是否使能 ND2NZ 转换config_params类型为MatmulConfigParams的整体配置对象。约束说明本接口必须在get_tiling接口之前调用若 Matmul 对象使用NBuffer33模板策略MatmulPolicyNBuffer33MatmulPolicy则必须在get_tiling前将scheduleTypeIn设置为ScheduleType::N_BUFFER_33以启用 NBuffer33 模板策略的 Tiling 生成逻辑本接口配置的参数对应的功能在 Tiling 与 Kernel 中需要保持一致取值需与 Kernel 侧对应的 MatmulConfig 参数值保持一致。3.9 结果获取get_base_m / get_base_n / get_base_k / get_tilingTiling 计算完成后get_base_m()/get_base_n()/get_base_k()分别获取 Tiling 计算得到的 baseM / baseN / baseK 值get_tiling(tiling)将 Tiling 结果写入传入的TCubeTiling结构体对象返回值为int64_t返回值不为 -1Tiling 计算成功可以使用该 Tiling 结构的值返回值为 -1Tiling 计算失败该结果不可用。失败排查提示在 Tiling 计算失败的场景若需查看失败原因请将日志级别设置为 WARNING 级别并在日志中搜索关键字MatmulApi Tiling见 get_tiling。四、一个完整的单核 Matmul Tiling 调用示例综合以上接口一个完整的 MatmulApiTiling 调用流程如下示例来源get_tiling/set_org_shape等接口文档import asc.lib.host as host ascendc_platform host.get_ascendc_platform() tiling host.MatmulApiTiling(ascendc_platform) # 1. 设置矩阵属性需与 Kernel 侧一致 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) # 2. 设置形状 tiling.set_shape(1024, 1024, 1024) tiling.set_org_shape(1024, 1024, 1024) # 3. 使能 Bias tiling.set_bias(True) # 4. 设置计算方向可选M 轴优先 tiling.set_traverse(host.MatrixTraverse.FIRSTM) # 5. 使用默认 Buffer 空间 tiling.set_buffer_space(-1, -1, -1) # 6. 获取 Tiling 结果 tiling_data host.TCubeTiling() ret tiling.get_tiling(tiling_data) # 7. 校验返回值 assert ret ! -1, Tiling compute failed五、多核 MatmulMultiCoreMatmulTiling 的专属接口多核场景下Tiling 引擎需要将整个 Matmul 计算切分到多个 AI Core 上。MultiCoreMatmulTiling在共有接口之上提供以下专属能力5.1 核数控制set_dimtiling.set_dim(use_core_nums) # 设置参与运算的核数set_dim(dim)设置多核 Matmul Tiling 计算时可以使用的核数对应int32_t SetDim(int32_t dim)。Tiling 引擎会依据该核数切分 M/N/K 维度。5.2 单核形状控制set_single_shape / get_single_shapeset_single_shape(single_m_in, single_n_in, single_k_in)手动设置 Matmul 单核计算的形状单位为元素get_single_shape()获取计算后的single_core_m/single_core_n/single_core_k用于核对实际切分结果。5.3 对齐与取值范围set_align_split / set_single_rangeset_align_split(...)多核切分时设置single_core_m/single_core_n/single_core_k的对齐值。例如将single_core_m的对齐值设为 64元素切分出的 singleCoreM 就是 64 的倍数set_single_range(...)设置single_core_m/single_core_n/single_core_k的最大值与最小值约束切分结果的范围。5.4 K 轴切分enable_multi_core_split_ktiling.enable_multi_core_split_k() # 在 get_tiling 前调用多核场景下通过该接口使能切 K 轴。不调用该接口时默认不切 K 轴。该接口必须在get_tiling调用前使用。当 M、N 维度不足以填充所有核时切 K 轴可以将 K 维拆开分配给更多核提升多核利用率。5.5 核数查询get_core_numget_core_num()返回多核切分实际使用的 BlockNum 参数用于 Host 侧确认最终参与运算的核数该接口在BatchMatmulTiling中同样存在。5.6 多核示例带 Layout 轴信息import asc.lib.host as host ascendc_platform host.get_ascendc_platform() tiling host.MultiCoreMatmulTiling(ascendc_platform) m, n, k 32, 256, 64 tiling.set_dim(1) 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) tiling.set_shape(m, n, k) tiling.set_org_shape(m, n, k) tiling.set_bias(True) tiling.set_buffer_space(-1, -1, -1) # Batch/Layout 相关 a_bnum, a_snum, a_gnum, a_dnum 2, 32, 3, 64 b_bnum, b_snum, b_gnum, b_dnum 2, 256, 3, 64 c_bnum, c_snum, c_gnum, c_dnum 2, 32, 3, 256 batch_num 3 tiling.set_a_layout(a_bnum, a_snum, 1, a_gnum, a_dnum) tiling.set_b_layout(b_bnum, b_snum, 1, b_gnum, b_dnum) tiling.set_c_layout(c_bnum, c_snum, 1, c_gnum, c_dnum) tiling.set_batch_num(batch_num) tiling.set_buffer_space(-1, -1, -1) tiling_data host.TCubeTiling() ret tiling.get_tiling(tiling_data)六、BatchMatmulTiling 与多 Batch 注意事项BatchMatmulTiling专用于 Batch Matmul 场景其独有接口为get_core_num()用于获得多核切分所使用的 BlockNum 参数。其余能力set_batch_num、set_a_layout/set_b_layout/set_c_layout、set_batch_info_for_normal等均继承自共有接口列表。多 Batch 场景的关键注意事项set_batch_num(batch)中的 batch 应为 A 矩阵 batchA 与 B 矩阵 batchB 的最大值对 BSNGD、SBNGD、BNGS1S2 等 Layout必须在调用iterate_batch之前通过set_a_layout/set_b_layout/set_c_layout设置好各轴信息对 NORMAL Layout必须在调用iterate_batch/iterate_n_batch之前通过set_batch_info_for_normal设置 M/N/K 轴信息与 Batch 数。这些约束与 Kernel 侧asc.language.adv.Matmul的iterate_batch/iterate_n_batch/set_batch_num等接口一一对应参见 python-api/language/adv.md 及asc.language.adv.Matmul系列接口文档。七、常见问题与排错建议现象可能原因排查方向get_tiling返回 -1矩阵属性与 Kernel 不一致形状参数非法Buffer 空间不足将日志级别调至 WARNING搜索MatmulApi Tiling关键字核对set_a_type/set_b_type/set_c_type与 Kernel 侧配置多核切分后核利用率低未使能 K 轴切分set_dim设置过大在get_tiling前调用enable_multi_core_split_k根据 M/N 维度合理设置set_dimBatch 场景 Tiling 错误未设置 Layout 轴信息或 Batch 数检查是否在iterate_batch前完成set_a_layout/set_b_layout/set_c_layout与set_batch_num设置自定义 MatmulConfig 不生效调用顺序错误或与 Kernel 模板不一致确认在get_tiling之前调用set_matmul_config_paramsmm_config_type与 Kernel 模板保持一致NBuffer33 策略需设置ScheduleType::N_BUFFER_33八、源码级补充接口的底层实现位置上述接口在仓库中的实现脉络如下供深入阅读Python 封装层python/asc/lib/host/wrappers.py 与 python/asc/lib/host/loader.py 负责模块加载与 Python 侧包装pybind 绑定层python/asc/lib/host/bindings/ 目录下的 C 绑定代码将MatmulApiTiling/MultiCoreMatmulTiling/BatchMatmulTiling/TCubeTiling等类型暴露给 Python接口文档全集Host 侧每个接口均有独立文档位于 docs/python-api/lib/generated/例如asc.lib.host.MatmulApiTiling.*、asc.lib.host.MultiCoreMatmulTiling.*、asc.lib.host.BatchMatmulTiling.*使用入口索引docs/python-api/lib/index.md 与 docs/python-api/lib/host.mdKernel 侧 Matmul 编程接口与 Host Tiling 配套使用python/asc/language/adv/matmul.py 及语言侧文档 docs/python-api/language/adv.md。九、总结asc.lib.host的 Matmul Tiling API 将昇腾 Matmul 算子开发中最繁琐的切分计算收敛为一系列语义清晰的 set 接口矩阵属性、形状、Buffer 空间、计算方向、Batch/Layout、多核切分等均可通过接口显式配置最终统一产出TCubeTiling结构体供 Kernel 使用。开发时只需牢记两条主线——所有属性设置必须与 Kernel 侧保持一致以及具有调用顺序要求的接口如set_matmul_config_params、enable_multi_core_split_k必须在get_tiling之前调用——即可稳定地完成 Host 侧 Tiling 开发。【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 pyasc 的 asc.lib.host Matmul Tiling API 使用指南：从 Tiling 参数计算到多核切分
pyasc 的 asc.lib.host Matmul Tiling API 使用指南从 Tiling 参数计算到多核切分【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc导读本文围绕 CANN pyasc 仓库中 docs/python-api/lib/host.md 所定义的asc.lib.host模块展开系统讲解如何使用 Host 侧的 Matmul Tiling APIMatmulApiTiling、MultiCoreMatmulTiling、BatchMatmulTiling在昇腾 AI 处理器上为 Matmul Kernel 计算 Tiling 参数。读完本文后你将掌握 Tiling API 的完整调用流程、各配置接口的参数含义与约束、多核切分与 Batch 场景下的使用要点并能结合 Kernel 侧TCubeTiling结构体独立写出可运行的 Host 侧 Tiling 代码。asc.lib.host是 pyasc 提供给用户的 Host 侧算子开发接口位于仓库 python/asc/lib/host/Python 封装与 python/asc/lib/host/bindings/pybind 绑定中。通过asc.lib.host模块用户可以调用与 Ascend C 一一对应的 Matmul Tiling 接口从而获取 Kernel 侧TCubeTiling结构体中的相关参数避免手工推导 baseM、baseN、baseK 等切分信息。一、模块定位Host 侧 Tiling 计算与 Kernel 侧如何衔接1.1 Tiling 在 Matmul 算子开发中的作用在昇腾 AI 处理器上运行 Matmul 计算时矩阵乘法通常远超单个 AI Core 的片上存储容量L1 Buffer、L0C Buffer、UB 等因此需要将大矩阵切分为若干小分片Tile逐片完成矩阵乘累加。这一过程涉及三个层面的信息原始矩阵信息M、N、K 的大小A/B/C 矩阵的数据类型、数据格式ND/NZ 等、所在 buffer 位置切分策略信息每个 Tile 的 baseM/baseN/baseK、参与计算的核数、K 轴是否切分等循环与搬移信息矩阵的 Layout 轴信息B/S/N/G/D、Batch 数、计算方向的遍历顺序等。asc.lib.host提供的三组 Tiling 类正是用于在 Host 侧统一计算并封装这些信息最终通过TCubeTiling结构体传递给 Kernel。1.2 从用户输入到 TCubeTiling 的调用链路从源码文档 get_tiling 可以看出整个调用流程是通过host.get_ascendc_platform()获取当前平台信息SOC 版本用平台信息构造MatmulApiTiling或MultiCoreMatmulTiling对象依次调用set_a_type/set_b_type/set_c_type/set_bias_type等接口描述矩阵属性调用set_shape、set_org_shape等接口描述矩阵形状调用set_buffer_space、set_batch_num、set_traverse等接口描述资源与策略构造host.TCubeTiling()结构体实例调用get_tiling(tiling)获取 Tiling 结果通过返回值判断 Tiling 计算是否成功非 -1 即成功。对应 Kernel 侧TCubeTiling结构体与 Ascend C 算子中Init接口使用的 Tiling 结构保持一致Kernel 从 GM 侧读取 Host 计算好的 Tiling 参数即可完成分块、搬移与累加。pyasc 的 Kernel 侧示例可参考仓库 examples/04_matmul_cube_only/matmul_cube_only.py 与 examples/05_matmul_leakyrelu/matmul_leakyrelu.py。二、三个 Tiling 类的职责划分asc.lib.host提供三类 Tiling 接口对象类职责关键区别MatmulApiTiling基础 Matmul Tiling 计算单核/多核通用提供全部基础设置接口MultiCoreMatmulTiling多核 Matmul Tiling 计算在基础接口之上增加多核切分相关接口BatchMatmulTilingBatch Matmul Tiling 计算用于多 Batch 场景三个类共享绝大部分接口A/B/C/Bias 类型设置、形状设置、buffer 空间设置等因此 host.md 首先统一列出共有接口列表再分别给出MultiCoreMatmulTiling与BatchMatmulTiling的独有接口。下文先讲解共有接口再讲解多核专属接口。三、共有接口详解MatmulApiTiling / MultiCoreMatmulTiling / BatchMatmulTiling3.1 矩阵属性设置set_a_type / set_b_type / set_c_type / set_bias_type这四个接口分别设置 A/B/C/Bias 矩阵的位置、数据格式、数据类型、是否转置等信息。以set_a_type为例其对应 Ascend C 函数原型为int32_t SetAType(TPosition pos, CubeFormat type, DataType dataType, bool isTrans false)Python 侧调用方式见 set_a_typeimport asc.lib.host as host ascendc_platform host.get_ascendc_platform() tiling host.MatmulApiTiling(ascendc_platform) # 设置A矩阵buffer位置为GM数据格式为ND数据类型为bfloat16默认不转置 tiling.set_a_type(host.TPosition.GM, host.CubeFormat.ND, host.DataType.DT_FLOAT16)参数说明pos矩阵所在 buffer 位置取值如host.TPosition.GMGlobal Memory、host.TPosition.L1等type数据格式如host.CubeFormat.ND、host.CubeFormat.NZdata_type数据类型如host.DataType.DT_FLOAT16、host.DataType.DT_FLOAT、host.DataType.DT_BF16等is_trans是否转置默认False。set_b_type、set_c_type的签名与之类似。set_bias_type仅包含位置、数据格式、数据类型三个参数Bias 不做转置对应原型int32_t SetBiasType(TPosition pos, CubeFormat type, DataType dataType)。一致性约束重要这几个接口设置的矩阵属性必须与 Kernel 侧Matmul对象初始化时传入的配置保持一致否则 Host 计算出的 Tiling 参数无法正确驱动 Kernel 执行。3.2 形状设置set_shape 与 set_org_shapeset_shape(m, n, k)设置本次 Matmul 计算的形状对应原型int32_t SetShape(int32_t m, int32_t n, int32_t k)该形状可以是原始完整矩阵也可以是切分后的局部矩阵单位为元素该形状的矩阵乘可以由单核或多核共同计算完成。set_org_shape(*args, **kwargs)设置 Matmul 计算时的原始完整形状提供两种重载见 set_org_shapeint32_t SetOrgShape(int32_t orgMIn, int32_t orgNIn, int32_t orgKIn) int32_t SetOrgShape(int32_t orgMIn, int32_t orgNIn, int32_t orgKaIn, int32_t orgKbIn)第一种用于 Ka Kb 的场景直接传 orgM / orgN / orgK第二种用于 A/B 矩阵 K 维不一致Ka ≠ Kb的场景此时 org_ka_in、org_kb_in 可以不相等。理解要点org_ka_in / org_kb_in 并不是实际 Matmul 计算时的 K而只是辅助 Matmul API 做数据搬运时偏移计算的原始形状参数。这一点在文档 set_org_shape 中有明确约束说明。3.3 资源空间设置set_buffer_spaceset_buffer_space设置 Matmul 计算时可用的各 Buffer 空间大小单位为字节tiling.set_buffer_space(l1_size-1, l0_c_size-1, ub_size-1, bt_size-1)对应原型int32_t SetBufferSpace(int32_t l1Size -1, int32_t l0CSize -1, int32_t ubSize -1, int32_t btSize -1)参数含义默认值l1_sizeL1 Buffer 可用空间字节-1表示使用 AI 处理器默认 L1 Buffer 大小l0_c_sizeL0C Buffer 可用空间字节-1表示使用默认 L0C Buffer 大小ub_sizeUnified BufferUB可用空间字节-1表示使用默认 UB 大小bt_sizeBiasTable Buffer 可用空间字节-1表示使用默认 BiasTable 大小实际开发中用户通常直接传-1让 Tiling 引擎使用芯片默认 Buffer 容量仅在需要限制资源如为其他算子预留空间时才显式传值。注意单核MatmulApiTiling示例中常写set_buffer_space(-1, -1, -1)省略 bt_size而多核MultiCoreMatmulTiling示例则写set_buffer_space(-1, -1, -1, -1)二者等价于全部使用默认值。3.4 计算方向与调优set_traverse、set_double_buffer、set_mad_type、set_split_rangeset_traverse(traverse)设置固定的 Matmul 计算方向M 轴优先还是 N 轴优先。可选值host.MatrixTraverse.FIRSTM/host.MatrixTraverse.FIRSTN。这决定了一次迭代计算出[baseM, baseN]大小的 C 矩阵分片后下一次迭代输出的 C 矩阵位置沿哪个方向偏移。set_double_buffer(a, b, c, bias, trans_nd2nzTrue, trans_nz2ndTrue)设置 A/B/C/Bias 是否使能 double buffer 功能以及是否需要进行 ND2NZ / NZ2ND 的格式转换主要用于 Tiling 函数内部调优。当 MTE3 与 MTE2 流水存在较多串行等待时使能 double buffer 可以提升流水并行度。set_mad_type(mad_type)设置是否使能 HF32 模式当前版本暂不支持。set_split_range(...)设置 baseM/baseN/baseK 的最大值和最小值当前版本暂不支持该功能。3.5 Batch 场景set_batch_num 与 set_batch_info_for_normalset_batch_num(batch)设置多 Batch 计算的最大 Batch 数最大 Batch 数为 A 矩阵 batchA 和 B 矩阵 batchB 中的最大值。调用iterate_batch接口之前需要在 Host 侧 Tiling 实现中先调用本接口。set_batch_info_for_normal(...)设置 A/B 矩阵的 M/N/K 轴信息以及 Batch 数。仅当 Layout 类型为 NORMAL 时在调用iterate_batch或iterate_n_batch接口之前需要调用本接口。3.6 Layout 轴信息set_a_layout / set_b_layout / set_c_layout对于 BSNGD、SBNGD、BNGS1S2 等 Layout 格式调用iterate_batch接口之前必须在 Host 侧 Tiling 实现中通过set_a_layout/set_b_layout/set_c_layout设置 A/B/C 矩阵的 B、S、N、G、D 五个轴的信息tiling.set_a_layout(a_bnum, a_snum, 1, a_gnum, a_dnum) # 设置 A 矩阵排布 tiling.set_b_layout(b_bnum, b_snum, 1, b_gnum, b_dnum) tiling.set_c_layout(c_bnum, c_snum, 1, c_gnum, c_dnum) tiling.set_batch_num(batch_num)其中参数顺序为(b, s, n, g, d)b 为 B 轴Batch信息、s 为 S 轴信息、n 为 N 轴信息、g 为 G 轴信息、d 为 D 轴信息。这里 n 轴传 1 是因为在上述示例场景中 N 维信息由 S 轴表达具体取值需要与 Kernel 侧矩阵排布一致。3.7 量化场景set_dequant_type 与 set_sparseset_dequant_type(...)设置量化或反量化时的模式用于量化 Matmul 场景。set_sparse(is_sparce_in)设置 Matmul 的使用场景是否为 Sparse Matmul稀疏矩阵乘场景需要在 Kernel 侧同样开启稀疏模式时配套使用。3.8 自定义 MatmulConfigset_matmul_config_paramsset_matmul_config_params用于在计算 Tiling 时自定义 MatmulConfig 参数对应原型void SetMatmulConfigParams(int32_t mmConfigTypeIn 1, bool enableL1CacheUBIn false, ScheduleType scheduleTypeIn ScheduleType::INNER_PRODUCT, MatrixTraverse traverseIn MatrixTraverse::NOSET, bool enVecND2NZIn false) void SetMatmulConfigParams(const MatmulConfigParams configParams)关键参数mm_config_type_inMatmul 模板类型需与 Matmul 对象创建的模板一致当前只支持 0 或 1enable_l1_cache_ub_in是否使能 L1 缓存 UB 计算块适合 MTE3 和 MTE2 流水串行较多的场景schedule_type_inMatmul 数据搬运模式traverse_in矩阵运算的循环迭代顺序en_vec_nd2nz_in是否使能 ND2NZ 转换config_params类型为MatmulConfigParams的整体配置对象。约束说明本接口必须在get_tiling接口之前调用若 Matmul 对象使用NBuffer33模板策略MatmulPolicyNBuffer33MatmulPolicy则必须在get_tiling前将scheduleTypeIn设置为ScheduleType::N_BUFFER_33以启用 NBuffer33 模板策略的 Tiling 生成逻辑本接口配置的参数对应的功能在 Tiling 与 Kernel 中需要保持一致取值需与 Kernel 侧对应的 MatmulConfig 参数值保持一致。3.9 结果获取get_base_m / get_base_n / get_base_k / get_tilingTiling 计算完成后get_base_m()/get_base_n()/get_base_k()分别获取 Tiling 计算得到的 baseM / baseN / baseK 值get_tiling(tiling)将 Tiling 结果写入传入的TCubeTiling结构体对象返回值为int64_t返回值不为 -1Tiling 计算成功可以使用该 Tiling 结构的值返回值为 -1Tiling 计算失败该结果不可用。失败排查提示在 Tiling 计算失败的场景若需查看失败原因请将日志级别设置为 WARNING 级别并在日志中搜索关键字MatmulApi Tiling见 get_tiling。四、一个完整的单核 Matmul Tiling 调用示例综合以上接口一个完整的 MatmulApiTiling 调用流程如下示例来源get_tiling/set_org_shape等接口文档import asc.lib.host as host ascendc_platform host.get_ascendc_platform() tiling host.MatmulApiTiling(ascendc_platform) # 1. 设置矩阵属性需与 Kernel 侧一致 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) # 2. 设置形状 tiling.set_shape(1024, 1024, 1024) tiling.set_org_shape(1024, 1024, 1024) # 3. 使能 Bias tiling.set_bias(True) # 4. 设置计算方向可选M 轴优先 tiling.set_traverse(host.MatrixTraverse.FIRSTM) # 5. 使用默认 Buffer 空间 tiling.set_buffer_space(-1, -1, -1) # 6. 获取 Tiling 结果 tiling_data host.TCubeTiling() ret tiling.get_tiling(tiling_data) # 7. 校验返回值 assert ret ! -1, Tiling compute failed五、多核 MatmulMultiCoreMatmulTiling 的专属接口多核场景下Tiling 引擎需要将整个 Matmul 计算切分到多个 AI Core 上。MultiCoreMatmulTiling在共有接口之上提供以下专属能力5.1 核数控制set_dimtiling.set_dim(use_core_nums) # 设置参与运算的核数set_dim(dim)设置多核 Matmul Tiling 计算时可以使用的核数对应int32_t SetDim(int32_t dim)。Tiling 引擎会依据该核数切分 M/N/K 维度。5.2 单核形状控制set_single_shape / get_single_shapeset_single_shape(single_m_in, single_n_in, single_k_in)手动设置 Matmul 单核计算的形状单位为元素get_single_shape()获取计算后的single_core_m/single_core_n/single_core_k用于核对实际切分结果。5.3 对齐与取值范围set_align_split / set_single_rangeset_align_split(...)多核切分时设置single_core_m/single_core_n/single_core_k的对齐值。例如将single_core_m的对齐值设为 64元素切分出的 singleCoreM 就是 64 的倍数set_single_range(...)设置single_core_m/single_core_n/single_core_k的最大值与最小值约束切分结果的范围。5.4 K 轴切分enable_multi_core_split_ktiling.enable_multi_core_split_k() # 在 get_tiling 前调用多核场景下通过该接口使能切 K 轴。不调用该接口时默认不切 K 轴。该接口必须在get_tiling调用前使用。当 M、N 维度不足以填充所有核时切 K 轴可以将 K 维拆开分配给更多核提升多核利用率。5.5 核数查询get_core_numget_core_num()返回多核切分实际使用的 BlockNum 参数用于 Host 侧确认最终参与运算的核数该接口在BatchMatmulTiling中同样存在。5.6 多核示例带 Layout 轴信息import asc.lib.host as host ascendc_platform host.get_ascendc_platform() tiling host.MultiCoreMatmulTiling(ascendc_platform) m, n, k 32, 256, 64 tiling.set_dim(1) 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) tiling.set_shape(m, n, k) tiling.set_org_shape(m, n, k) tiling.set_bias(True) tiling.set_buffer_space(-1, -1, -1) # Batch/Layout 相关 a_bnum, a_snum, a_gnum, a_dnum 2, 32, 3, 64 b_bnum, b_snum, b_gnum, b_dnum 2, 256, 3, 64 c_bnum, c_snum, c_gnum, c_dnum 2, 32, 3, 256 batch_num 3 tiling.set_a_layout(a_bnum, a_snum, 1, a_gnum, a_dnum) tiling.set_b_layout(b_bnum, b_snum, 1, b_gnum, b_dnum) tiling.set_c_layout(c_bnum, c_snum, 1, c_gnum, c_dnum) tiling.set_batch_num(batch_num) tiling.set_buffer_space(-1, -1, -1) tiling_data host.TCubeTiling() ret tiling.get_tiling(tiling_data)六、BatchMatmulTiling 与多 Batch 注意事项BatchMatmulTiling专用于 Batch Matmul 场景其独有接口为get_core_num()用于获得多核切分所使用的 BlockNum 参数。其余能力set_batch_num、set_a_layout/set_b_layout/set_c_layout、set_batch_info_for_normal等均继承自共有接口列表。多 Batch 场景的关键注意事项set_batch_num(batch)中的 batch 应为 A 矩阵 batchA 与 B 矩阵 batchB 的最大值对 BSNGD、SBNGD、BNGS1S2 等 Layout必须在调用iterate_batch之前通过set_a_layout/set_b_layout/set_c_layout设置好各轴信息对 NORMAL Layout必须在调用iterate_batch/iterate_n_batch之前通过set_batch_info_for_normal设置 M/N/K 轴信息与 Batch 数。这些约束与 Kernel 侧asc.language.adv.Matmul的iterate_batch/iterate_n_batch/set_batch_num等接口一一对应参见 python-api/language/adv.md 及asc.language.adv.Matmul系列接口文档。七、常见问题与排错建议现象可能原因排查方向get_tiling返回 -1矩阵属性与 Kernel 不一致形状参数非法Buffer 空间不足将日志级别调至 WARNING搜索MatmulApi Tiling关键字核对set_a_type/set_b_type/set_c_type与 Kernel 侧配置多核切分后核利用率低未使能 K 轴切分set_dim设置过大在get_tiling前调用enable_multi_core_split_k根据 M/N 维度合理设置set_dimBatch 场景 Tiling 错误未设置 Layout 轴信息或 Batch 数检查是否在iterate_batch前完成set_a_layout/set_b_layout/set_c_layout与set_batch_num设置自定义 MatmulConfig 不生效调用顺序错误或与 Kernel 模板不一致确认在get_tiling之前调用set_matmul_config_paramsmm_config_type与 Kernel 模板保持一致NBuffer33 策略需设置ScheduleType::N_BUFFER_33八、源码级补充接口的底层实现位置上述接口在仓库中的实现脉络如下供深入阅读Python 封装层python/asc/lib/host/wrappers.py 与 python/asc/lib/host/loader.py 负责模块加载与 Python 侧包装pybind 绑定层python/asc/lib/host/bindings/ 目录下的 C 绑定代码将MatmulApiTiling/MultiCoreMatmulTiling/BatchMatmulTiling/TCubeTiling等类型暴露给 Python接口文档全集Host 侧每个接口均有独立文档位于 docs/python-api/lib/generated/例如asc.lib.host.MatmulApiTiling.*、asc.lib.host.MultiCoreMatmulTiling.*、asc.lib.host.BatchMatmulTiling.*使用入口索引docs/python-api/lib/index.md 与 docs/python-api/lib/host.mdKernel 侧 Matmul 编程接口与 Host Tiling 配套使用python/asc/language/adv/matmul.py 及语言侧文档 docs/python-api/language/adv.md。九、总结asc.lib.host的 Matmul Tiling API 将昇腾 Matmul 算子开发中最繁琐的切分计算收敛为一系列语义清晰的 set 接口矩阵属性、形状、Buffer 空间、计算方向、Batch/Layout、多核切分等均可通过接口显式配置最终统一产出TCubeTiling结构体供 Kernel 使用。开发时只需牢记两条主线——所有属性设置必须与 Kernel 侧保持一致以及具有调用顺序要求的接口如set_matmul_config_params、enable_multi_core_split_k必须在get_tiling之前调用——即可稳定地完成 Host 侧 Tiling 开发。【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考