CANN pyasc 中 MatmulApiTiling.set_org_shape 详解:原始形状与 Ka/Kb 非对称配置
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
从测试可以清晰看到两个关键行为:
- 三参数
set_org_shape(32, 16, 8)会将k_a与k_b同时置为 8,即对称场景下 Ka=Kb=K; - 四参数
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 字段的取值,进而影响后续数据搬运的偏移计算。
使用建议与注意事项
- 对称场景优先使用三参数重载:当原始矩阵 Ka=Kb 时,直接使用
set_org_shape(org_m_in, org_n_in, org_k_in)即可,代码更简洁; - 非对称场景必须使用四参数重载:当 A/B 原始内维度不一致时,务必分别传入
org_ka_in与org_kb_in,否则 Tiling 无法正确计算搬运偏移; - 注意与 set_shape 的配合:
set_shape描述计算范围(可以是局部矩阵),set_org_shape描述原始完整矩阵,二者缺一不可,且都应使用元素个数作为单位; - 检查返回值:调用后应检查返回值是否为 0;若
get_tiling返回-1,可参考 get_tiling 的说明,将日志级别设置为 WARNING 并在日志中搜索关键字MatmulApi Tiling定位失败原因; - 信息需与 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等。