CANN pyasc 中 MatmulApiTiling.set_org_shape 详解:原始形状与 Ka/Kb 非对称配置

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

CANN pyasc 中 MatmulApiTiling.set_org_shape 详解:原始形状与 Ka/Kb 非对称配置

导读

本文围绕 CANN pyasc 中 asc.lib.host.MatmulApiTiling.set_org_shape 接口展开,讲解如何在 Host 侧 Matmul Tiling 计算中设置原始完整矩阵形状 M、N、K(或非对称的 Ka/Kb)。读者将掌握该接口两种重载形式的使用场景、参数语义与返回值约定,理解 org_shape 与 set_shape 的区别,并能结合 pyasc 仓库中的绑定源码与单元测试写出可直接运行的 Tiling 配置代码。

接口定位:Host 侧 Matmul Tiling 参数配置链的一环

asc.lib.host 是 pyasc 提供给用户获取 Matmul Kernel 计算所需 Tiling 参数的一组 Host 侧 API。用户只需传入 A/B/C 矩阵的 Position 位置、Format 格式和 DType 数据类型等信息,即可得到 TCubeTiling 结构体中的相关参数。MatmulApiTiling 是其中最核心的类,set_org_shape 属于其共有接口之一,负责描述"原始完整的形状"信息。

从 host.md 的接口列表可以看到,一次典型的 Tiling 配置通常由 set_a_type、set_b_type、set_c_type、set_bias_type、set_shape、set_org_shape、set_bias、set_buffer_space 等接口按顺序调用组成,最终通过 get_tiling 输出结果。

函数签名与重载形式

set_org_shape 是一个支持重载的 Python 接口,对应文档中的签名如下:

MatmulApiTiling.set_org_shape(*args, **kwargs)

其底层对应两个 Ascend C 函数原型:

int32_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)

在 wrappers.py 的类型声明中,这两种重载被明确标注为 @overload:

@overload
def set_org_shape(self, org_m_in: int, org_n_in: int, org_k_in: int) -> int:
    ...

@overload
def set_org_shape(self, org_m_in: int, org_n_in: int, org_ka_in: int, org_kb_in: int) -> int:
    ...

两种重载形式分别对应"原始 K 对称"与"原始 K 非对称(Ka≠Kb)"两种场景。

参数说明

参数 含义 单位
org_m_in 原始完整的形状 M 大小 元素个数
org_n_in 原始完整的形状 N 大小 元素个数
org_k_in 原始完整的形状 K 大小(仅当原始完整形状 Ka=Kb 时可设置) 元素个数
org_ka_in 矩阵 A 原始完整的形状 Ka 大小 元素个数
org_kb_in 矩阵 B 原始完整的形状 Kb 大小 元素个数

返回值说明:返回 -1 表示设置失败,返回 0 表示设置成功。

关键约束:Ka 与 Kb 可以不等

set_org_shape 最重要的语义约束是:参数 org_ka_in 和 org_kb_in 可以不相等。也就是说,原始矩阵的 Ka 和 Kb 可以不相等,这里的 Ka/Kb 并不是实际 Matmul 计算时的 K,该参数只用于辅助 Matmul API 搬运(搬入搬出)时的偏移计算。

这意味着在诸如 weight-only 量化、A/B 两矩阵内维度不对称等场景中,即便实际计算仍以公共 K 为基准,原始数据的存储维度仍可能不同,此时必须使用四参数重载,将 A、B 各自的原始内维度分别告知 Tiling。

与 set_shape 的分工

  • set_shape(m, n, k) 设置的是 Matmul 计算的形状 m、n、k,该形状可以是原始完整矩阵,也可以是局部矩阵(如多核切分后的单核形状),单位同样是元素。该形状的矩阵乘可以由单核或多核计算完成,参见 set_shape。
  • set_org_shape 设置的则是原始完整矩阵的形状,用于辅助搬运偏移计算,是 Tiling 计算中的基准信息。

两者通常成对出现:先 set_shape 描述本次计算范围,再 set_org_shape 描述原始完整矩阵,确保 Tiling 在切分与搬运寻址时有正确的全局尺寸依据。

调用示例:完整的 MatmulApiTiling 配置流程

以下示例来自关联文档,并可在 pyasc 中直接运行:

import asc.lib.host as host

ascendc_platform = host.get_ascendc_platform()
tiling = host.MatmulApiTiling(ascendc_platform)
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)
tiling.set_org_shape(1024, 1024, 1024)
tiling.set_bias(True)
tiling.set_buffer_space(-1, -1, -1)

tiling_data = host.TCubeTiling()
ret = tiling.get_tiling(tiling_data)

该流程中:

  • get_ascendc_platform() 获取当前昇腾平台信息,作为 MatmulApiTiling 构造参数;
  • set_a_type / set_b_type / set_c_type / set_bias_type 分别声明 A、B、C、Bias 的位置(此处均为 GM)、格式(ND)与数据类型;
  • set_shape 与 set_org_shape 成对设置计算形状与原始形状;
  • set_buffer_space(-1, -1, -1) 表示 Buffer 空间由 Tiling 自动计算;
  • get_tiling 将计算结果写入 TCubeTiling 结构体并返回状态码,返回值不为 -1 表示 Tiling 计算成功。

源码级佐证:绑定实现与重载分发

在 pyasc 中,set_org_shape 通过 pybind11 在 MatmulApiTiling.cpp 中绑定。两个重载分别用 .def("set_org_shape", ...) 注册:

  • 三参数版本:参数名为 org_m_in、org_n_in、org_k_in,内部调用 self.SetOrgShape(orgMIn, orgNIn, orgKIn);
  • 四参数版本:参数名为 org_m_in、org_n_in、org_ka_in、org_kb_in,内部调用 self.SetOrgShape(orgMIn, orgNIn, orgKaIn, orgKbIn)。

两个重载直接透传 int32_t 整型参数,返回值即 SetOrgShape 的返回码(0 成功、-1 失败)。这也印证了文档中"单位为元素个数"的约定——底层 C++ 接口接收的是元素计数而非字节数。

测试验证:单元测试如何覆盖两种重载

pyasc 仓库在 test_matmul_api_tiling.py 中提供了针对 set_org_shape 的单元测试:

def test_set_org_shape(asc_platform):
    matmul_tiling = host.MatmulApiTiling(asc_platform)
    ret = matmul_tiling.set_org_shape(32, 16, 8)
    tiling = asc.adv.TCubeTiling()
    matmul_tiling.get_tiling(tiling)
    assert ret == 0
    assert tiling.m == 32
    assert tiling.n == 16
    assert tiling.k_a == 8
    assert tiling.k_b == 8


def test_set_org_shape_ka_kb(asc_platform):
    matmul_tiling = host.MatmulApiTiling(asc_platform)
    ret = matmul_tiling.set_org_shape(32, 16, 8, 4)
    tiling = asc.adv.TCubeTiling()
    matmul_tiling.get_tiling(tiling)
    assert ret == 0
    assert tiling.m == 32
    assert tiling.n == 16
    assert tiling.k_a == 8
    assert tiling.k_b == 4

从测试可以清晰看到两个关键行为:

  1. 三参数 set_org_shape(32, 16, 8) 会将 k_a 与 k_b 同时置为 8,即对称场景下 Ka=Kb=K;
  2. 四参数 set_org_shape(32, 16, 8, 4) 会将 k_a 置为 8、k_b 置为 4,证明 Ka≠Kb 的非对称场景在 Tiling 结果中确实得到保留。

这从侧面验证了文档"Ka 和 Kb 可以不相等"的约束说明,也说明 set_org_shape 的输入会直接影响最终 TCubeTiling 中 k_a/k_b 字段的取值,进而影响后续数据搬运的偏移计算。

使用建议与注意事项

  1. 对称场景优先使用三参数重载:当原始矩阵 Ka=Kb 时,直接使用 set_org_shape(org_m_in, org_n_in, org_k_in) 即可,代码更简洁;
  2. 非对称场景必须使用四参数重载:当 A/B 原始内维度不一致时,务必分别传入 org_ka_in 与 org_kb_in,否则 Tiling 无法正确计算搬运偏移;
  3. 注意与 set_shape 的配合:set_shape 描述计算范围(可以是局部矩阵),set_org_shape 描述原始完整矩阵,二者缺一不可,且都应使用元素个数作为单位;
  4. 检查返回值:调用后应检查返回值是否为 0;若 get_tiling 返回 -1,可参考 get_tiling 的说明,将日志级别设置为 WARNING 并在日志中搜索关键字 MatmulApi Tiling 定位失败原因;
  5. 信息需与 Kernel 侧保持一致:如 host.md 所述,A/B/C/Bias 的类型与格式等设置信息必须与 Kernel 侧设置保持一致,set_org_shape 传入的原始形状也应与 Kernel 侧实际张量布局对应。

相关接口速览

set_org_shape 是 MatmulApiTiling 系列接口的一部分,完整的共有接口列表见 host.md,常见搭配包括:

  • set_shape:设置计算形状 m/n/k;
  • get_tiling:获取 Tiling 参数;
  • get_base_m / get_base_n / get_base_k:获取 Tiling 计算得到的 baseM/baseN/baseK;
  • 多核与 Batch 场景可参考 MultiCoreMatmulTiling、BatchMatmulTiling 的扩展接口,例如 set_dim、set_single_shape、set_batch_num 等。
登录后查看全文
pyasc