CANN pyasc 中 MultiCoreMatmulTiling.set_single_range:多核 Matmul 单核计算形状上下界约束的 Host 侧 Tiling 接口详解

原创2026-09-18 18:51:351,671 阅读
文章标签:编译器编程语言人工智能开发工具Ascend

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 接口对接的通用写法。

常见误区与注意事项

  1. 调用时机:set_single_range 必须在 get_tiling 之前调用,Tiling 计算完成后设置无效;
  2. 参数独立性:六个参数可部分设置,未设置的维度保持 -1,勿误以为必须成对传入 max/min;
  3. 与 set_shape 的关系:set_shape 描述的是整个 Matmul 计算的整体(或局部)形状,set_single_range 约束的是切分后单核的计算形状,二者维度相同但语义不同,先 set_shape 再 set_single_range 的顺序是文档示例的标准用法;
  4. 对齐约束:设置的上下界需要符合 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 编程中的直接体现。

登录后查看全文
pyasc