CANN pyasc 中 MatmulApiTiling.set_sparse 详解为 Sparse Matmul 场景生成 Tiling 参数【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc导读本文围绕 CANN pyasc 仓库中asc.lib.host.MatmulApiTiling.set_sparse接口展开讲解如何在 Host 侧 Tiling 生成阶段声明 Matmul 计算为 Sparse Matmul稀疏矩阵乘场景。读完本文你将掌握该接口的完整调用方式、返回值与约束语义、与get_tiling等配套方法的正确组合顺序以及 Kernel 侧set_sparse_index如何与 Host 侧设置协同工作可直接照抄示例用于你自己的算子 Tiling 实现。一、接口定位Matmul Tiling API 家族中的场景开关在 CANN pyasc 项目中asc.lib.host模块为算子开发者提供了一组 Matmul Tiling API用于在 Host 侧获取 Matmul Kernel 计算时所需的 Tiling 参数。其设计思路是用户只需传入 A/B/C 矩阵的 Position位置、Format数据格式、DType数据类型等信息调用 API 即可得到TCubeTiling结构体中的相关参数无需手工推导分块大小与搬运偏移参见 host.md 模块说明。这组 API 以MatmulApiTilingBase为公共基类派生出三个面向不同使用场景的类见 MatmulApiTiling.cpp 的绑定定义MatmulApiTiling单核 Matmul 的 Tiling 计算MultiCoreMatmulTiling多核切分场景额外提供set_dim、set_single_shape、enable_multi_core_split_k等接口BatchMatmulTiling多 Batch 场景。set_sparse是这三个类共享的公共接口之一定义在MatmulApiTilingBase上它负责告诉 Tiling 计算逻辑本次 Matmul 是否为 Sparse Matmul 稀疏场景。在 host.md 的接口总览表中它的定位描述是设置 Matmul 的使用场景是否为 Sparse Matmul 场景。二、函数签名与对应 Ascend C 原型MatmulApiTiling.set_sparse(self: libhost.MatmulApiTilingBase, is_sparce_in: bool False) → int对应的 Ascend C 函数原型为int32_t SetSparse(bool isSparseIn false)可以看出pyasc 的 Python 接口与 Ascend C 的 C 接口一一对应is_sparce_in对应 C 侧的isSparseIn默认值均为False。这一点符合 pyasc 项目接口与 Ascend C 一一对应并遵守 Python 原生语法的整体设计目标。三、参数与返回值说明3.1 参数is_sparse_in参数类型默认值含义is_sparse_inboolFalse设置是否为 Sparse Matmul 稀疏场景。传入True表示按稀疏矩阵乘场景生成 TilingFalse默认表示普通稠密 Matmul3.2 返回值返回值含义0设置成功-1设置失败3.3 约束说明本接口必须在get_tiling接口前调用。也就是说set_sparse属于配置类接口它写入的开关必须在触发 Tiling 计算之前生效否则无法影响本次 Tiling 结果。四、完整调用示例可直接复制运行以下示例完整继承自 set_sparse 接口文档并补充了关键步骤注释。它演示了一个 1024×1024×1024、A/B 为 FP16、C/Bias 为 FP32 的 Sparse Matmul Tiling 生成流程import asc.lib.host as host # 1. 获取昇腾 AI 处理器平台信息见 python/asc/lib/host/__init__.py 中 get_ascendc_platform 的实现 ascendc_platform host.get_ascendc_platform() # 2. 创建 MatmulApiTiling 对象 tiling host.MatmulApiTiling(ascendc_platform) # 3. 依次设置 A/B/C/Bias 矩阵的位置、数据格式与数据类型 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) # 4. 关键步骤声明 Sparse Matmul 场景必须在 get_tiling 前调用 tiling.set_sparse(True) # 5. 设置计算形状与原始完整形状单位为元素个数 tiling.set_shape(1024, 1024, 1024) tiling.set_org_shape(1024, 1024, 1024) # 6. 使能 Bias 参与运算 tiling.set_bias(True) # 7. 设置可用的 L1/L0C/UB Buffer 空间-1 表示使用 AI 处理器对应 Buffer 的默认大小 tiling.set_buffer_space(-1, -1, -1) # 8. 调用 get_tiling 获取 Tiling 参数结果写入 TCubeTiling 结构体 tiling_data host.TCubeTiling() ret tiling.get_tiling(tiling_data)其中ret不为-1即表示 Tiling 计算成功tiling_data中的参数可交给 Kernel 侧的Matmul.init(tiling)使用。五、配套接口组合要点set_sparse不是孤立使用的它的效果依赖与下述接口的正确组合5.1 与 get_tiling 的时序关系get_tiling(self, tiling: object) → int将最终 Tiling 结果写入TCubeTiling结构体。Tiling 计算失败时返回-1若需排查失败原因可将日志级别设为 WARNING 级别并在日志中搜索关键字MatmulApi Tiling参见 get_tiling 文档。所有配置类接口包括set_sparse都必须先于get_tiling调用。5.2 形状设置set_shape(m, n, k)设置 Matmul 计算的形状可为原始完整矩阵或其局部矩阵单位是元素set_org_shape(org_m, org_n, org_k)设置原始完整的形状 M、N、K或 Ka/Kb用于辅助 Matmul API 搬运时的偏移计算。当原始形状 Ka 与 Kb 不相等时可使用四参数版本set_org_shape(org_m, org_n, org_ka, org_kb)。5.3 Buffer 空间设置set_buffer_space(l1_size, l0_c_size, ub_size, bt_size)可分别约束 L1 Buffer、L0C Buffer、Unified Buffer 与 BiasTable Buffer 的可使用空间单位字节默认值均为-1表示使用 AI 处理器对应 Buffer 的大小见 MatmulApiTiling.cpp。5.4 其他场景开关enable_bias(is_bias_in)/set_bias(True)设置 Bias 是否参与运算设置信息必须与 Kernel 侧保持一致set_dequant_type(dequant_type)设置量化/反量化模式需与 Kernel 侧set_quant_scalar、set_quant_vector保持一致set_matmul_config_params(...)自定义 MatmulConfig 参数配置的功能在 Tiling 与 Kernel 中必须保持一致。六、Kernel 侧协同set_sparse_index需要特别说明的是Host 侧set_sparse(True)只是声明了稀疏场景真正把稀疏矩阵稠密化过程生成的索引矩阵传入 Kernel 的是 Kernel 侧接口asc.language.adv.Matmul.set_sparse_index参见 set_sparse_index 文档asc.jit(matmul_cube_onlyTrue) # 使能纯Cube模式只有矩阵计算 def matmul_kernel(...): ... asc.adv.register_matmul(pipe, workspace, mm, tiling) mm.set_tensor_a(gm_a) mm.set_tensor_b(gm_b) mm.set_sparse_index(gm_index) # 设置索引矩阵稀疏矩阵稠密化过程的索引 mm.set_bias(gm_bias) mm.iterate_all(gm_c)其对应的 C 原型为__aicore__ inline void SetSparseIndex(const GlobalTensoruint8_t indexGlobal)。使用时有两点约束索引矩阵的 Format 格式要求为NZ 格式该接口仅支持在纯 Cube 模式只有矩阵计算且 MDL 模板的场景下使用。从 pyasc 源码实现看Matmul.set_sparse_index位于 matmul.py通过set_matmul_docstring(api_nameset_sparse_index)装饰器自动生成文档串与 Host 侧set_sparse形成Host 声明场景、Kernel 传入索引的完整闭环。由此可以推断Sparse Matmul 的典型用法是Host 侧通过set_sparse(True)让 Tiling 计算按稀疏模式切分与计算偏移Kernel 侧再配合set_sparse_index传入 NZ 格式的索引矩阵完成实际计算。七、源码级实现验证7.1 Python 绑定层set_sparse的 pybind11 绑定定义在 MatmulApiTiling.cpp.def( set_sparse, [](MatmulApiTilingBase self, bool isSparceIn) { return self.SetSparse(isSparceIn); }, is_sparce_in_a false, ...)可以看到Python 层的set_sparse直接转发到 C 侧的SetSparse(bool isSparseIn)参数名is_sparce_in带默认值false与 C 默认参数一一对应其绑定位置在MatmulApiTilingBase类上因此三个派生类MatmulApiTiling、MultiCoreMatmulTiling、BatchMatmulTiling均可直接使用。7.2 Python 类型声明层在 wrappers.py 中set_sparse被声明为def set_sparse(self, is_sparse_in: bool ...) - int:7.3 平台获取与对象构造示例首行调用的host.get_ascendc_platform()定义于init.py内部通过PlatformAscendCManager.get_instance(soc_version.value)获取硬件平台单例MatmulApiTiling的构造函数接收该平台对象其无参版本则用于单核 Tiling 场景详见 MatmulApiTiling.cpp。八、使用注意事项调用顺序set_sparse必须在get_tiling之前调用否则开关不会生效且返回值可能为-1。保持 Tiling 与 Kernel 一致与enable_bias、set_dequant_type、set_matmul_config_params等接口一样set_sparse(True)所声明的稀疏场景必须与 Kernel 侧的实际计算方式是否使用set_sparse_index传入索引矩阵保持一致否则生成的 Tiling 参数无法正确指导 Kernel 计算。返回值检查建议对set_sparse及get_tiling的返回值做检查-1表示设置/计算失败Tiling 计算失败时按 WARNING 级别日志搜索关键字MatmulApi Tiling定位原因。场景限制Sparse Matmul 的索引矩阵要求 NZ 格式且仅支持纯 Cube 模式MDL 模板场景使用前请确认你的算子满足该前提。九、小结MatmulApiTiling.set_sparse是 CANN pyasc Host 侧 Tiling API 家族中面向稀疏计算的场景开关它以一行tiling.set_sparse(True)让 Tiling 计算进入 Sparse Matmul 模式配合set_shape/set_org_shape/set_buffer_space/get_tiling等接口即可在 Host 侧完成稀疏场景的 Tiling 参数生成Kernel 侧则通过Matmul.set_sparse_index传入 NZ 格式索引矩阵完成计算闭环。遵循配置在前、get_tiling 在后、Tiling 与 Kernel 一致三条原则即可在 pyasc 中稳定落地 Sparse Matmul 算子。【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考