CANN pyasc 中 MultiCoreMatmulTiling.set_single_range:多核 Matmul 单核计算形状上下界约束的 Host 侧 Tiling 接口详解
CANN pyasc 中 MultiCoreMatmulTiling.set_single_range:多核 Matmul 单核计算形状上下界约束的 Host 侧 Tiling 接口详解
导读
asc.lib.host.MultiCoreMatmulTiling.set_single_range 是 CANN pyasc 项目为 Python 开发者提供的 Host 侧 Matmul Tiling 编程接口,用于在多核 Matmul 场景下显式约束每个 AI Core 单核计算形状 single_core_m / single_core_n / single_core_k 的最大值与最小值。本指南以该接口为核心,结合仓库源码(python/asc/lib/host/bindings/MatmulApiTiling.cpp、python/asc/lib/host/wrappers.py)与单元测试(python/test/unit/lib/host/test_multi_core_matmul_tiling.py),完整讲解其函数签名、参数语义、返回值、调用时机,并给出可直接运行的完整示例,帮助读者掌握通过上下界引导 Tiling 函数自动切分多核 Matmul 的实战方法。
接口定位:多核 Matmul 单核计算形状的“护栏”
在昇腾 AI 处理器上运行 Matmul 算子时,一个完整矩阵乘法(例如 M×N×K)通常会被切分成多个子任务分发给多个 AI Core 并行计算。切分结果的量化描述正是单核计算形状:
single_core_m:单个核在 M 轴方向负责的元素个数;single_core_n:单个核在 N 轴方向负责的元素个数;single_core_k:单个核在 K 轴方向负责的元素个数。
默认情况下,MultiCoreMatmulTiling 的 Tiling 函数会根据 A/B/C 矩阵的位置(Position)、数据格式(Format)、数据类型(DType)、可用 Buffer 空间(L1/L0C/UB/BiasTable)以及参与运算的核数(set_dim 设置)自动计算这三个值。set_single_range 的作用是为这个自动计算过程划定上下界区间:开发者可以在不精确指定单核形状的前提下(精确指定请使用 set_single_shape),约束 Tiling 函数“切出的单核形状不要超过/不要小于某个值”,让自动切分结果落在期望的性能区间内。
该接口与同一类上的 set_single_shape(精确指定)、set_align_split(对齐约束)、get_single_shape(读取计算结果)、enable_multi_core_split_k(使能切 K 轴)、get_core_num(读取核数信息)共同构成多核 Matmul Tiling 的完整单核形状控制体系,可从 docs/python-api/lib/host.md 的接口清单总览中看到这些接口的完整列表。
函数签名与 Ascend C 原型
Python 接口签名
MultiCoreMatmulTiling.set_single_range(self: libhost.MultiCoreMatmulTiling, max_m: SupportsInt = -1, max_n: SupportsInt = -1, max_k: SupportsInt = -1, min_m: SupportsInt = -1, min_n: SupportsInt = -1, min_k: SupportsInt = -1) → int
- 六个参数全部可选,均接受支持
int语义的类型(SupportsInt),默认值均为-1; - 返回值为
int:-1表示设置失败,0表示设置成功。
对应的 Ascend C 函数原型
int32_t SetSingleRange(int32_t maxM = -1, int32_t maxN = -1, int32_t maxK = -1, int32_t minM = -1, int32_t minN = -1, int32_t minK = -1)
pyasc 作为 Python 侧的算子编程接口,其 Host 侧 Tiling 类与 Ascend C 的 Tiling API 一一对应。仓库中的 pybind11 绑定代码 python/asc/lib/host/bindings/MatmulApiTiling.cpp#L1593-L1639 将 C++ 侧的 SetSingleRange 以参数名 max_m / max_n / max_k / min_m / min_n / min_k 暴露给 Python:
.def(
"set_single_range",
[](MultiCoreMatmulTiling& self, int32_t maxM, int32_t maxN, int32_t maxK, int32_t minM, int32_t minN,
int32_t minK) { return self.SetSingleRange(maxM, maxN, maxK, minM, minN, minK); },
"max_m"_a = -1, "max_n"_a = -1, "max_k"_a = -1, "min_m"_a = -1, "min_n"_a = -1, "min_k"_a = -1, ...)
而 Python 类型层面的桩声明位于 python/asc/lib/host/wrappers.py#L274-L276,其中 MultiCoreMatmulTiling 继承自 MatmulApiTilingBase,共享 A/B/C/Bias 类型设置、形状设置、Buffer 空间设置等通用接口。
参数说明:六个形参的完整语义
| 参数 | 语义 | 默认值 | 默认行为 |
|---|---|---|---|
max_m |
设置最大的 single_core_m 值 |
-1 |
不设置 M 轴单核形状最大值,由 Tiling 函数自行计算 |
max_n |
设置最大的 single_core_n 值 |
-1 |
不设置 N 轴单核形状最大值,由 Tiling 函数自行计算 |
max_k |
设置最大的 single_core_k 值 |
-1 |
不设置 K 轴单核形状最大值,由 Tiling 函数自行计算 |
min_m |
设置最小的 single_core_m 值 |
-1 |
不设置 M 轴单核形状最小值,由 Tiling 函数自行计算 |
min_n |
设置最小的 single_core_n 值 |
-1 |
不设置 N 轴单核形状最小值,由 Tiling 函数自行计算 |
min_k |
设置最小的 single_core_k 值 |
-1 |
不设置 K 轴单核形状最小值,由 Tiling 函数自行计算 |
使用要点:
- 六个维度(M/N/K 三轴的最大值与最小值)彼此独立,可以只设置其中一部分,未设置的维度保持
-1,由 Tiling 函数自行计算; - 参数单位为元素个数,与
set_shape、set_single_shape、set_org_shape保持一致; - 设置的最大值应当大于等于对应最小值,且需要符合硬件对 Cube 计算分形的对齐约束(Tiling 计算时会进行对齐处理,可参考
set_fix_split接口中对 base_m/base_n 对齐的约束说明:half/bfloat16_t 的 C0_size 为 16、float 的 C0_size 为 8、int8_t 的 C0_size 为 32); - 该接口属于设置类(Set)方法,必须在调用
get_tiling之前完成调用,否则无法影响 Tiling 计算结果。
返回值与失败处理
0:设置成功;-1:设置失败。
需要说明的是,set_single_range 的返回值仅反映本次参数设置是否被成功接受,Tiling 计算是否成功由后续 get_tiling 的返回值决定。从 docs/python-api/lib/generated/asc.lib.host.MatmulApiTiling.get_tiling.md 的约束说明可知,若 get_tiling 计算失败,可将日志级别设置为 WARNING,并在日志中搜索关键字 “MatmulApi Tiling” 定位失败原因。
完整调用示例
以下示例来自接口文档,展示了 set_single_range 在多核 Matmul Tiling 配置流程中的典型位置——设置形状信息之后、获取 Tiling 结果之前:
import asc.lib.host as host
ascendc_platform = host.get_ascendc_platform()
tiling = host.MultiCoreMatmulTiling(ascendc_platform)
tiling.set_dim(use_core_nums) # 设置参与运算的核数
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(1024, 1024, 1024) # 设置 Matmul 计算的整体形状
tiling.set_single_range(1024, 1024, 1024, 1024, 1024, 1024) # 设置 single_core_m/n/k 的最大值与最小值
tiling.set_org_shape(1024, 1024, 1024) # 设置原始完整形状
tiling.set_bias(True) # 使能 Bias 参与运算
tiling.set_buffer_space(-1, -1, -1) # 使用默认 Buffer 空间
tiling_data = host.TCubeTiling()
ret = tiling.get_tiling(tiling_data) # 执行 Tiling 计算
上述示例同时设置六个参数(最大与最小均为 1024),等价于要求每个核在 M/N/K 三轴上的计算形状都被固定为 1024;如果希望“只设上界、不设下界”,可写作:
tiling.set_single_range(max_m=512, max_n=512, max_k=-1)
即只约束 M/N 轴的单核形状不超过 512,K 轴及所有最小值维度全部交由 Tiling 函数自行决定。
测试用例验证
仓库中的单元测试 python/test/unit/lib/host/test_multi_core_matmul_tiling.py 直接验证了该接口的行为:
def test_set_single_range(asc_platform):
matmul_tiling = host.MultiCoreMatmulTiling(asc_platform)
matmul_tiling.set_shape(32, 32, 32)
ret = matmul_tiling.set_single_range(32, 32, 32, 16, 16, 16)
assert ret == 0
该用例在形状为 32×32×32 的 Matmul 上设置单核形状范围(最大 32、最小 16),并断言返回值为 0(设置成功)。同一测试文件中的 test_set_single_shape 与 test_get_single_shape 则验证了配套接口:set_single_shape(32, 16, 8) 之后通过 get_tiling 计算,再调用 get_single_shape() 读取到 (single_core_m, single_core_n, single_core_k) = (32, 16, 8),这组测试共同说明了“设置单核形状 → Tiling 计算 → 读取单核形状”的完整闭环用法。
与同族接口的配合使用
set_single_range 单独使用即可引导 Tiling 自动切分,但在实际算子开发中通常与其他接口组合:
- 精确指定单核形状:使用 set_single_shape,直接指定
single_m_in/single_n_in/single_k_in(单位元素,默认-1表示由 Tiling 函数自行计算); - 对齐约束:使用
set_align_split,例如设置single_core_m的对齐值为 64,则切分出的single_core_m为 64 的倍数; - 读取计算结果:Tiling 计算完成后调用 get_single_shape(返回元组
(single_core_m, single_core_n, single_core_k))或get_core_num,供 Kernel 侧逻辑(如asc.adv.Matmul.set_single_shape、iterate_all等)使用; - 切 K 轴:调用 enable_multi_core_split_k 使能 K 轴多核切分(默认不切 K 轴),需注意使能后 C 矩阵结果仅支持输出到 Global Memory,且首次写入分片结果前需先清零 Global Memory、写入时开启 AtomicAdd 累加,否则可能因累加无效原始数据产生精度问题。
在真实算子示例中,examples/03_matmul_mix/matmul_mix.py#L89-L92 与 examples/04_matmul_cube_only/matmul_cube_only.py#L97-L100 均采用“创建 MultiCoreMatmulTiling 对象 → 设置 A/B/C/Bias 类型与形状 → 调用 get_tiling 获取 TCubeTiling”的标准流程,其分块、多核、Tiling 逻辑详见 examples/03_matmul_mix/README.md 与 examples/04_matmul_cube_only/README.md。而 python/test/generalization/adv/test_matmul.py#L92-L95 则展示了在泛化测试中通过 MultiCoreMatmulTiling 生成 Tiling 并与 Kernel 侧 Matmul 接口对接的通用写法。
常见误区与注意事项
- 调用时机:
set_single_range必须在get_tiling之前调用,Tiling 计算完成后设置无效; - 参数独立性:六个参数可部分设置,未设置的维度保持
-1,勿误以为必须成对传入 max/min; - 与
set_shape的关系:set_shape描述的是整个 Matmul 计算的整体(或局部)形状,set_single_range约束的是切分后单核的计算形状,二者维度相同但语义不同,先set_shape再set_single_range的顺序是文档示例的标准用法; - 对齐约束:设置的上下界需要符合 Cube 计算分形与 C0_size 对齐要求,若上下界相互矛盾或违反硬件约束,最终 Tiling 计算可能失败(返回
-1),失败时按 WARNING 日志关键字 “MatmulApi Tiling” 排查。
小结
MultiCoreMatmulTiling.set_single_range 为多核 Matmul 的自动 Tiling 切分提供了“最大/最小单核形状”的双向护栏:既可以用 max_* 防止单个核承担过大的计算分片、保障负载均衡与 Buffer 空间约束,也可以用 min_* 防止切分过碎、降低核间调度开销。配合 set_single_shape、set_align_split、get_single_shape 与 enable_multi_core_split_k,开发者可以在不手写复杂切分算法的情况下,将多核 Matmul 的 Tiling 行为引导到期望的性能形态,这正是 pyasc 项目“接口与 Ascend C 一一对应、遵守 Python 原生语法”设计理念在 Host 侧 Tiling 编程中的直接体现。