2026/9/19 1:47:04
FEATURED · 精选文章 
pyasc 算子开发指南MatmulApiTiling.set_matmul_config_params 自定义 MatmulConfig Tiling 参数全解析【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc导读在 CANN pyasc 项目中MatmulApiTiling 是 Host 侧用于生成 Matmul 算子 Tiling 参数的核心工具类而set_matmul_config_params则是其中负责“自定义 MatmulConfig 参数”的关键接口它允许开发者在不改动 Tiling 主流程的前提下显式控制模板类型、L1 缓存 UB 计算块、数据搬运模式ScheduleType、矩阵循环迭代顺序Traverse以及 ND2NZ 转换开关从而针对特定形状与流水场景精细调优 Tiling 生成逻辑。读完本文你将掌握该接口的完整签名、五个参数的业务含义与默认值、调用时机约束、与 Kernel 侧 MatmulConfig 保持一致性的原则以及它在 pyasc 仓库中的 Python 绑定实现与单元测试验证方式能够直接在算子工程中正确使用并排查相关问题。一、接口定位MatmulApiTiling 家族中的“自定义配置”入口MatmulApiTiling是 pyasc Host 侧库asc.lib.host为昇腾 Matmul 算子提供的一站式 Tiling 计算接口。典型用法是依次调用set_a_type/set_b_type/set_c_type声明输入输出张量类型用set_shape/set_org_shape声明矩阵形状再用set_buffer_space声明各存储层级空间最后调用get_tiling产出 Tiling 数据见 asc.lib.host.MatmulApiTiling.get_tiling.md。set_matmul_config_params在此流程中属于“可选的额外设置”大多数常规场景下默认的 MatmulConfig 已经可以工作无需调用本接口当 Matmul 对象使用了特定模板策略如 NBuffer33或需要对流水调度、L1 缓存、迭代顺序做定向调优时就必须通过本接口把 MatmulConfig 参数显式传给 Tiling 计算过程。其核心原则是本接口中配置的参数对应的功能在 Tiling 与 Kernel 中需要保持一致即 Host 侧 Tiling 计算使用的 MatmulConfig 参数值必须与 Kernel 侧 Matmul 对象实际使用的 MatmulConfig 参数值保持一致否则 Tiling 与 Kernel 会出现行为不一致导致计算错误或性能回退。二、函数签名与两种调用形态2.1 对应 Ascend C 函数原型本接口在底层对应 Ascend C 的SetMatmulConfigParams提供了两个重载void SetMatmulConfigParams(int32_t mmConfigTypeIn 1, bool enableL1CacheUBIn false, ScheduleType scheduleTypeIn ScheduleType::INNER_PRODUCT, MatrixTraverse traverseIn MatrixTraverse::NOSET, bool enVecND2NZIn false) void SetMatmulConfigParams(const MatmulConfigParams configParams)第一种形态逐参数传入 5 个配置项每个参数都有默认值第二种形态将 5 个配置项封装进MatmulConfigParams结构体后整体传入。2.2 Python 侧签名pyasc 在 Python 层对上述两个 C 重载分别做了绑定源码见 python/asc/lib/host/bindings/MatmulApiTiling.cpp类型签名声明于 python/asc/lib/host/wrappers.pyoverload def set_matmul_config_params(self, mm_config_type_in: int ..., enable_l1_cache_ub_in: bool ..., schedule_type_in: ScheduleType ..., traverse_in: MatrixTraverse ..., en_vec_nd2nz_in: bool ...) - None: ... overload def set_matmul_config_params(self, config_params: MatmulConfigParams) - None: ...其中MatmulConfigParams在 Python 侧同样是一个可独立构造的类class MatmulConfigParams(ProxyBase): def __init__(self, mm_config_type: int ..., enable_l1_cache_ub: bool ..., schedule_type: ScheduleType ..., traverse: MatrixTraverse ..., en_vec_nd2nz: bool ...) - None: ...该结构体在 pybind11 绑定中被注册为可读写的字段类python/asc/lib/host/bindings/MatmulApiTiling.cpp字段名与 C 侧一一对应mm_config_type、enable_l1_cache_ub、schedule_type、traverse、en_vec_nd2nz。三、参数详解含义、默认值与适用场景3.1 mm_config_type_inMatmul 模板类型含义设置 Matmul 的模板类型该值必须与 Matmul 对象创建时所使用的模板保持一致取值约束当前只支持配置为 0 或 1默认值1见 pybind11 绑定中的mm_config_type_a 1注意事项这是与 Kernel 侧一致性要求最直接的参数之一Tiling 与 Kernel 必须使用同一模板类型否则生成的 Tiling 参数无法匹配 Kernel 的执行逻辑。3.2 enable_l1_cache_ub_inL1 缓存 UB 计算块开关含义配置是否使能 L1 缓存 UB 计算块类型bool默认值为False参考使能场景MTE3 与 MTE2 流水串行较多的场景。这类场景中数据搬运MTE2 搬运 GM→L1/L0、MTE3 搬运 L1/L0→UB相互等待、串行执行通过 L1 缓存 UB 计算块可以缓解搬运瓶颈改善流水重叠注意该开关的使能同样需要在 Tiling 与 Kernel 两侧保持一致。3.3 schedule_type_in数据搬运模式含义配置 Matmul 的数据搬运模式调度类型类型ScheduleType枚举默认值为ScheduleType::INNER_PRODUCT可选值以仓库代码为准ScheduleType.INNER_PRODUCT内积模式默认值ScheduleType.OUTER_PRODUCT外积模式单元测试中使用了该枚举值见 python/test/unit/lib/host/test_matmul_api_tiling.pyScheduleType.N_BUFFER_33NBuffer33 模板策略专用的搬运模式详见下文约束说明。典型使用若 Matmul 对象使用 NBuffer33 模板策略NBuffer33MatmulPolicy则必须显式传入ScheduleType::N_BUFFER_33以启用 NBuffer33 模板策略的 Tiling 生成逻辑详见第四节约束说明。3.4 traverse_in矩阵运算循环迭代顺序含义Matmul 做矩阵运算的循环迭代顺序。即一次迭代计算出[baseM, baseN]大小的 C 矩阵分片后自动偏移到下一次迭代输出的 C 矩阵位置的偏移顺序类型MatrixTraverse枚举默认值为MatrixTraverse::NOSET不设置由 Tiling 自行决定可选值除NOSET外仓库中set_traverse接口的文档还给出了MatrixTraverse::FIRSTM/MatrixTraverse::FIRSTN见 python/asc/lib/host/bindings/MatmulApiTiling.cpp即固定沿 M 方向优先或沿 N 方向优先进行迭代分片。如果希望同时固定迭代方向也可以配合独立的 set_traverse 接口使用作用不同的 traverse 顺序会影响 C 矩阵分片在核间与流水中的排布进而影响局部性如 L1/L0 命中率与搬运开销。3.5 en_vec_nd2nz_inND2NZ 使能开关含义是否使能 ND2NZ将 ND 布局数据转换为 NZ 布局类型bool默认值为False背景昇腾 Cube 单元通常以 NZ分形格式进行计算若输入以 ND 格式提供则可能需要在搬运/计算路径中插入 ND2NZ 转换。此开关用于在 Tiling 侧对该转换逻辑做显式控制同样要求与 Kernel 侧配置一致。3.6 config_paramsMatmulConfigParams 结构体当使用第二种重载时需要构造MatmulConfigParams对象一次性携带上述 5 个字段。其构造函数与字段默认值来自 pybind11 绑定 python/asc/lib/host/bindings/MatmulApiTiling.cpp如下字段类型默认值mm_config_typeint321enable_l1_cache_ubboolFalseschedule_typeScheduleTypeINNER_PRODUCTtraverseMatrixTraverseNOSETen_vec_nd2nzboolFalse3.7 参数速查表参数含义类型/枚举默认值mm_config_type_inMatmul 模板类型须与 Matmul 对象模板一致int仅支持 0 或 11enable_l1_cache_ub_in是否使能 L1 缓存 UB 计算块MTE3/MTE2 流水串行场景boolFalseschedule_type_inMatmul 数据搬运模式ScheduleTypeINNER_PRODUCTtraverse_inC 矩阵分片迭代偏移顺序MatrixTraverseNOSETen_vec_nd2nz_in是否使能 ND2NZboolFalseconfig_params上述配置的封装结构体MatmulConfigParams见 3.6四、返回值与调用约束4.1 返回值-1表示设置失败0表示设置成功。说明底层 C 原型SetMatmulConfigParams的返回类型为void文档中沿用了-1/0的返回值语义说明在 Python 绑定层两个重载经 pybind11 绑定后按None返回仓库单元测试中即以assert ret is None进行校验见 python/test/unit/lib/host/test_matmul_api_tiling.py。4.2 约束说明调用时机本接口必须在GetTilingPython 侧为get_tiling接口之前调用。因为 MatmulConfig 参数是 Tiling 计算的输入之一只有先完成配置后续生成的 Tiling 参数才会携带对应的调度决策NBuffer33 模板策略强约束若 Matmul 对象使用 NBuffer33 模板策略即MatmulPolicyNBuffer33MatmulPolicy则在调用GetTiling接口生成 Tiling 参数前必须通过本接口将scheduleTypeIn参数设置为ScheduleType::N_BUFFER_33以启用 NBuffer33 模板策略的 Tiling 生成逻辑。这是本接口最典型、最刚性的使用场景——不做此设置NBuffer33 策略的 Tiling 生成逻辑不会被启用一致性约束所有参数取值需与 Kernel 侧对应的 MatmulConfig 参数值保持一致模板类型、L1 缓存开关、搬运模式、迭代顺序、ND2NZ 开关任一不一致都可能导致 Tiling 与 Kernel 行为失配。五、完整调用示例标准 Matmul Tiling 流程以下示例完整继承自接口文档asc.lib.host.MatmulApiTiling.set_matmul_config_params.md并补充了参数注释可直接作为算子 Tiling 生成代码的骨架import asc.lib.host as host # 1. 获取昇腾平台信息用于 Tiling 计算所需的平台参数 ascendc_platform host.get_ascendc_platform() tiling host.MatmulApiTiling(ascendc_platform) # 2. 声明 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) # 3. 声明形状M、N、K元素个数以及原始形状 tiling.set_shape(1024, 1024, 1024) tiling.set_org_shape(1024, 1024, 1024) # 4. 声明是否带 Bias、各级存储空间-1 表示按默认策略分配 tiling.set_bias(True) tiling.set_buffer_space(-1, -1, -1) # 5. 额外设置自定义 MatmulConfig 参数必须在 get_tiling 之前调用 # 此处仅传模板类型 0其余参数使用默认值 # enable_l1_cache_ubFalse, schedule_typeINNER_PRODUCT, # traverseNOSET, en_vec_nd2nzFalse tiling.set_matmul_config_params(0) # 6. 生成 Tiling 数据 tiling_data host.TCubeTiling() ret tiling.get_tiling(tiling_data)若需要一次性携带多个自定义项推荐使用MatmulConfigParams结构体形态config host.MatmulConfigParams( mm_config_type1, enable_l1_cache_ubFalse, schedule_typehost.ScheduleType.OUTER_PRODUCT, traversehost.MatrixTraverse.FIRSTM, en_vec_nd2nzFalse, ) tiling.set_matmul_config_params(config)六、源码级原理pybind11 绑定如何实现两个重载6.1 C 绑定层在 python/asc/lib/host/bindings/MatmulApiTiling.cpp 中set_matmul_config_params通过两次py::def完成重载注册逐参数重载lambda 捕获 5 个参数int32_t mmConfigType, bool enableL1CacheUB, ScheduleType scheduleType, MatrixTraverse traverse, bool enVecND2NZ全部带有 pybind11 关键字默认值mm_config_type_a 1、enable_l1_cache_ub_a false、schedule_type_a ScheduleType::INNER_PRODUCT、traverse_a MatrixTraverse::NOSET、en_vec_nd2nz_a false内部直接转发到self.SetMatmulConfigParams(mmConfigType, enableL1CacheUB, scheduleType, traverse, enVecND2NZ)结构体重载lambda 接收const MatmulConfigParams configParams转发到self.SetMatmulConfigParams(configParams)。因此 Python 侧既可以“按位置/关键字逐个传参”也可以“先构造MatmulConfigParams再整体传入”两种形态最终都会落到同一组 CSetMatmulConfigParams重载上。6.2 MatmulConfigParams 结构体绑定同一个源文件python/asc/lib/host/bindings/MatmulApiTiling.cpp还将MatmulConfigParams注册为一个可读写字段的 pybind11 类构造函数py::initint32_t, bool, ScheduleType, MatrixTraverse, bool()五个形参mm_config_type、enable_l1_cache_ub、schedule_type、traverse、en_vec_nd2nz均有默认值字段访问通过 5 个def_readwrite将 C 侧成员mmConfigType、enableL1CacheUB、scheduleType、traverse、enVecND2NZ暴露为 Python 可读写的同名小驼峰属性。6.3 Python 侧类型声明与导出类型存根位于 python/asc/lib/host/wrappers.py 与 python/asc/lib/host/wrappers.pyMatmulConfigParams继承ProxyBase通过代理元类在运行时把属性/方法解析到_C加载的 C 对象上set_matmul_config_params以overload形式给出两个重载签名符号导出位于 python/asc/lib/host/init.pyMatmulConfigParams、MatrixTraverse、ScheduleType等均被加入__all__因此开发者可以直接以host.MatmulConfigParams、host.ScheduleType.OUTER_PRODUCT、host.MatrixTraverse.FIRSTM的方式访问。从源码结构看这种“C 核心实现 pybind11 绑定 Python 代理封装”的三层架构是 pyasc 将 Ascend C Tiling 能力无缝映射为 Python 原生接口的通用模式可对照 python/asc/lib/host/bindings 下的其他绑定文件。七、单元测试验证接口契约的可执行证据仓库在 python/test/unit/lib/host/test_matmul_api_tiling.py 中为set_matmul_config_params提供了两个针对性用例def test_set_matmul_config_params_init(asc_platform): matmul_tiling host.MatmulApiTiling(asc_platform) matmul_tiling.set_shape(32, 256, 64) matmul_config_params host.MatmulConfigParams(1, False, host.ScheduleType.OUTER_PRODUCT, host.MatrixTraverse.FIRSTM, False) ret matmul_tiling.set_matmul_config_params(matmul_config_params) assert ret is None def test_set_matmul_config_params(asc_platform): matmul_tiling host.MatmulApiTiling(asc_platform) matmul_tiling.set_shape(32, 256, 64) ret matmul_tiling.set_matmul_config_params(1, False, host.ScheduleType.OUTER_PRODUCT, host.MatrixTraverse.FIRSTM) assert ret is None这两个用例分别验证了结构体重载MatmulConfigParams(1, False, ScheduleType.OUTER_PRODUCT, MatrixTraverse.FIRSTM, False)构造与传入均可用且无返回值异常逐参数重载位置传参(1, False, OUTER_PRODUCT, FIRSTM)省略默认的en_vec_nd2nz同样可用。它们同时印证了 Python 层该接口按None返回的行为以及ScheduleType.OUTER_PRODUCT、MatrixTraverse.FIRSTM等枚举值的真实存在。八、实践建议与排查要点调用顺序始终把set_matmul_config_params放在get_tiling之前若在get_tiling之后调用配置不会影响已经生成的 Tiling 结果。与 Kernel 侧对齐由于“Tiling 与 Kernel 需保持一致”是硬性约束建议在算子工程中把 MatmulConfig 的定义收敛到单一常量或配置文件Host Tiling 与 Kernel 共同引用避免两处手写导致漂移。模板类型取值mm_config_type仅支持 0 或 1且必须与 Matmul 对象创建时的模板一致传其他值可能导致 Tiling 生成失败或行为异常。NBuffer33 必配使用NBuffer33MatmulPolicy时schedule_type必须显式传ScheduleType.N_BUFFER_33这是最容易遗漏的硬性前置条件。按需调优默认参数INNER_PRODUCT/NOSET/ 不使能 L1 缓存在常规场景足够仅在流水串行明显如 MTE3 与 MTE2 相互等待或需要固定迭代方向时才针对性地打开 L1 缓存 UB 计算块、调整traverse或schedule_type并在实测性能后决定是否保留。九、延伸阅读本接口所属类完整方法列表asc.lib.host.MatmulApiTiling 系列文档含init、get_tiling、set_traverse、set_shape、set_buffer_space等Host 侧 API 总览docs/python-api/lib/host.md 与 docs/python-api/lib/index.mdPython 绑定实现python/asc/lib/host/bindings/MatmulApiTiling.cpp、python/asc/lib/host/wrappers.py单元测试python/test/unit/lib/host/test_matmul_api_tiling.py端到端示例仓库 examples 目录下的 Matmul 类样例如 examples/03_matmul_mix、examples/04_matmul_cube_only、examples/05_matmul_leakyrelu展示了完整的 Matmul 算子开发链路可结合阅读以理解 Tiling 参数在整体流程中的位置。【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
pyasc 算子开发指南：MatmulApiTiling.set_matmul_config_params 自定义 MatmulConfig Tiling 参数全解析
pyasc 算子开发指南MatmulApiTiling.set_matmul_config_params 自定义 MatmulConfig Tiling 参数全解析【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc导读在 CANN pyasc 项目中MatmulApiTiling 是 Host 侧用于生成 Matmul 算子 Tiling 参数的核心工具类而set_matmul_config_params则是其中负责“自定义 MatmulConfig 参数”的关键接口它允许开发者在不改动 Tiling 主流程的前提下显式控制模板类型、L1 缓存 UB 计算块、数据搬运模式ScheduleType、矩阵循环迭代顺序Traverse以及 ND2NZ 转换开关从而针对特定形状与流水场景精细调优 Tiling 生成逻辑。读完本文你将掌握该接口的完整签名、五个参数的业务含义与默认值、调用时机约束、与 Kernel 侧 MatmulConfig 保持一致性的原则以及它在 pyasc 仓库中的 Python 绑定实现与单元测试验证方式能够直接在算子工程中正确使用并排查相关问题。一、接口定位MatmulApiTiling 家族中的“自定义配置”入口MatmulApiTiling是 pyasc Host 侧库asc.lib.host为昇腾 Matmul 算子提供的一站式 Tiling 计算接口。典型用法是依次调用set_a_type/set_b_type/set_c_type声明输入输出张量类型用set_shape/set_org_shape声明矩阵形状再用set_buffer_space声明各存储层级空间最后调用get_tiling产出 Tiling 数据见 asc.lib.host.MatmulApiTiling.get_tiling.md。set_matmul_config_params在此流程中属于“可选的额外设置”大多数常规场景下默认的 MatmulConfig 已经可以工作无需调用本接口当 Matmul 对象使用了特定模板策略如 NBuffer33或需要对流水调度、L1 缓存、迭代顺序做定向调优时就必须通过本接口把 MatmulConfig 参数显式传给 Tiling 计算过程。其核心原则是本接口中配置的参数对应的功能在 Tiling 与 Kernel 中需要保持一致即 Host 侧 Tiling 计算使用的 MatmulConfig 参数值必须与 Kernel 侧 Matmul 对象实际使用的 MatmulConfig 参数值保持一致否则 Tiling 与 Kernel 会出现行为不一致导致计算错误或性能回退。二、函数签名与两种调用形态2.1 对应 Ascend C 函数原型本接口在底层对应 Ascend C 的SetMatmulConfigParams提供了两个重载void SetMatmulConfigParams(int32_t mmConfigTypeIn 1, bool enableL1CacheUBIn false, ScheduleType scheduleTypeIn ScheduleType::INNER_PRODUCT, MatrixTraverse traverseIn MatrixTraverse::NOSET, bool enVecND2NZIn false) void SetMatmulConfigParams(const MatmulConfigParams configParams)第一种形态逐参数传入 5 个配置项每个参数都有默认值第二种形态将 5 个配置项封装进MatmulConfigParams结构体后整体传入。2.2 Python 侧签名pyasc 在 Python 层对上述两个 C 重载分别做了绑定源码见 python/asc/lib/host/bindings/MatmulApiTiling.cpp类型签名声明于 python/asc/lib/host/wrappers.pyoverload def set_matmul_config_params(self, mm_config_type_in: int ..., enable_l1_cache_ub_in: bool ..., schedule_type_in: ScheduleType ..., traverse_in: MatrixTraverse ..., en_vec_nd2nz_in: bool ...) - None: ... overload def set_matmul_config_params(self, config_params: MatmulConfigParams) - None: ...其中MatmulConfigParams在 Python 侧同样是一个可独立构造的类class MatmulConfigParams(ProxyBase): def __init__(self, mm_config_type: int ..., enable_l1_cache_ub: bool ..., schedule_type: ScheduleType ..., traverse: MatrixTraverse ..., en_vec_nd2nz: bool ...) - None: ...该结构体在 pybind11 绑定中被注册为可读写的字段类python/asc/lib/host/bindings/MatmulApiTiling.cpp字段名与 C 侧一一对应mm_config_type、enable_l1_cache_ub、schedule_type、traverse、en_vec_nd2nz。三、参数详解含义、默认值与适用场景3.1 mm_config_type_inMatmul 模板类型含义设置 Matmul 的模板类型该值必须与 Matmul 对象创建时所使用的模板保持一致取值约束当前只支持配置为 0 或 1默认值1见 pybind11 绑定中的mm_config_type_a 1注意事项这是与 Kernel 侧一致性要求最直接的参数之一Tiling 与 Kernel 必须使用同一模板类型否则生成的 Tiling 参数无法匹配 Kernel 的执行逻辑。3.2 enable_l1_cache_ub_inL1 缓存 UB 计算块开关含义配置是否使能 L1 缓存 UB 计算块类型bool默认值为False参考使能场景MTE3 与 MTE2 流水串行较多的场景。这类场景中数据搬运MTE2 搬运 GM→L1/L0、MTE3 搬运 L1/L0→UB相互等待、串行执行通过 L1 缓存 UB 计算块可以缓解搬运瓶颈改善流水重叠注意该开关的使能同样需要在 Tiling 与 Kernel 两侧保持一致。3.3 schedule_type_in数据搬运模式含义配置 Matmul 的数据搬运模式调度类型类型ScheduleType枚举默认值为ScheduleType::INNER_PRODUCT可选值以仓库代码为准ScheduleType.INNER_PRODUCT内积模式默认值ScheduleType.OUTER_PRODUCT外积模式单元测试中使用了该枚举值见 python/test/unit/lib/host/test_matmul_api_tiling.pyScheduleType.N_BUFFER_33NBuffer33 模板策略专用的搬运模式详见下文约束说明。典型使用若 Matmul 对象使用 NBuffer33 模板策略NBuffer33MatmulPolicy则必须显式传入ScheduleType::N_BUFFER_33以启用 NBuffer33 模板策略的 Tiling 生成逻辑详见第四节约束说明。3.4 traverse_in矩阵运算循环迭代顺序含义Matmul 做矩阵运算的循环迭代顺序。即一次迭代计算出[baseM, baseN]大小的 C 矩阵分片后自动偏移到下一次迭代输出的 C 矩阵位置的偏移顺序类型MatrixTraverse枚举默认值为MatrixTraverse::NOSET不设置由 Tiling 自行决定可选值除NOSET外仓库中set_traverse接口的文档还给出了MatrixTraverse::FIRSTM/MatrixTraverse::FIRSTN见 python/asc/lib/host/bindings/MatmulApiTiling.cpp即固定沿 M 方向优先或沿 N 方向优先进行迭代分片。如果希望同时固定迭代方向也可以配合独立的 set_traverse 接口使用作用不同的 traverse 顺序会影响 C 矩阵分片在核间与流水中的排布进而影响局部性如 L1/L0 命中率与搬运开销。3.5 en_vec_nd2nz_inND2NZ 使能开关含义是否使能 ND2NZ将 ND 布局数据转换为 NZ 布局类型bool默认值为False背景昇腾 Cube 单元通常以 NZ分形格式进行计算若输入以 ND 格式提供则可能需要在搬运/计算路径中插入 ND2NZ 转换。此开关用于在 Tiling 侧对该转换逻辑做显式控制同样要求与 Kernel 侧配置一致。3.6 config_paramsMatmulConfigParams 结构体当使用第二种重载时需要构造MatmulConfigParams对象一次性携带上述 5 个字段。其构造函数与字段默认值来自 pybind11 绑定 python/asc/lib/host/bindings/MatmulApiTiling.cpp如下字段类型默认值mm_config_typeint321enable_l1_cache_ubboolFalseschedule_typeScheduleTypeINNER_PRODUCTtraverseMatrixTraverseNOSETen_vec_nd2nzboolFalse3.7 参数速查表参数含义类型/枚举默认值mm_config_type_inMatmul 模板类型须与 Matmul 对象模板一致int仅支持 0 或 11enable_l1_cache_ub_in是否使能 L1 缓存 UB 计算块MTE3/MTE2 流水串行场景boolFalseschedule_type_inMatmul 数据搬运模式ScheduleTypeINNER_PRODUCTtraverse_inC 矩阵分片迭代偏移顺序MatrixTraverseNOSETen_vec_nd2nz_in是否使能 ND2NZboolFalseconfig_params上述配置的封装结构体MatmulConfigParams见 3.6四、返回值与调用约束4.1 返回值-1表示设置失败0表示设置成功。说明底层 C 原型SetMatmulConfigParams的返回类型为void文档中沿用了-1/0的返回值语义说明在 Python 绑定层两个重载经 pybind11 绑定后按None返回仓库单元测试中即以assert ret is None进行校验见 python/test/unit/lib/host/test_matmul_api_tiling.py。4.2 约束说明调用时机本接口必须在GetTilingPython 侧为get_tiling接口之前调用。因为 MatmulConfig 参数是 Tiling 计算的输入之一只有先完成配置后续生成的 Tiling 参数才会携带对应的调度决策NBuffer33 模板策略强约束若 Matmul 对象使用 NBuffer33 模板策略即MatmulPolicyNBuffer33MatmulPolicy则在调用GetTiling接口生成 Tiling 参数前必须通过本接口将scheduleTypeIn参数设置为ScheduleType::N_BUFFER_33以启用 NBuffer33 模板策略的 Tiling 生成逻辑。这是本接口最典型、最刚性的使用场景——不做此设置NBuffer33 策略的 Tiling 生成逻辑不会被启用一致性约束所有参数取值需与 Kernel 侧对应的 MatmulConfig 参数值保持一致模板类型、L1 缓存开关、搬运模式、迭代顺序、ND2NZ 开关任一不一致都可能导致 Tiling 与 Kernel 行为失配。五、完整调用示例标准 Matmul Tiling 流程以下示例完整继承自接口文档asc.lib.host.MatmulApiTiling.set_matmul_config_params.md并补充了参数注释可直接作为算子 Tiling 生成代码的骨架import asc.lib.host as host # 1. 获取昇腾平台信息用于 Tiling 计算所需的平台参数 ascendc_platform host.get_ascendc_platform() tiling host.MatmulApiTiling(ascendc_platform) # 2. 声明 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) # 3. 声明形状M、N、K元素个数以及原始形状 tiling.set_shape(1024, 1024, 1024) tiling.set_org_shape(1024, 1024, 1024) # 4. 声明是否带 Bias、各级存储空间-1 表示按默认策略分配 tiling.set_bias(True) tiling.set_buffer_space(-1, -1, -1) # 5. 额外设置自定义 MatmulConfig 参数必须在 get_tiling 之前调用 # 此处仅传模板类型 0其余参数使用默认值 # enable_l1_cache_ubFalse, schedule_typeINNER_PRODUCT, # traverseNOSET, en_vec_nd2nzFalse tiling.set_matmul_config_params(0) # 6. 生成 Tiling 数据 tiling_data host.TCubeTiling() ret tiling.get_tiling(tiling_data)若需要一次性携带多个自定义项推荐使用MatmulConfigParams结构体形态config host.MatmulConfigParams( mm_config_type1, enable_l1_cache_ubFalse, schedule_typehost.ScheduleType.OUTER_PRODUCT, traversehost.MatrixTraverse.FIRSTM, en_vec_nd2nzFalse, ) tiling.set_matmul_config_params(config)六、源码级原理pybind11 绑定如何实现两个重载6.1 C 绑定层在 python/asc/lib/host/bindings/MatmulApiTiling.cpp 中set_matmul_config_params通过两次py::def完成重载注册逐参数重载lambda 捕获 5 个参数int32_t mmConfigType, bool enableL1CacheUB, ScheduleType scheduleType, MatrixTraverse traverse, bool enVecND2NZ全部带有 pybind11 关键字默认值mm_config_type_a 1、enable_l1_cache_ub_a false、schedule_type_a ScheduleType::INNER_PRODUCT、traverse_a MatrixTraverse::NOSET、en_vec_nd2nz_a false内部直接转发到self.SetMatmulConfigParams(mmConfigType, enableL1CacheUB, scheduleType, traverse, enVecND2NZ)结构体重载lambda 接收const MatmulConfigParams configParams转发到self.SetMatmulConfigParams(configParams)。因此 Python 侧既可以“按位置/关键字逐个传参”也可以“先构造MatmulConfigParams再整体传入”两种形态最终都会落到同一组 CSetMatmulConfigParams重载上。6.2 MatmulConfigParams 结构体绑定同一个源文件python/asc/lib/host/bindings/MatmulApiTiling.cpp还将MatmulConfigParams注册为一个可读写字段的 pybind11 类构造函数py::initint32_t, bool, ScheduleType, MatrixTraverse, bool()五个形参mm_config_type、enable_l1_cache_ub、schedule_type、traverse、en_vec_nd2nz均有默认值字段访问通过 5 个def_readwrite将 C 侧成员mmConfigType、enableL1CacheUB、scheduleType、traverse、enVecND2NZ暴露为 Python 可读写的同名小驼峰属性。6.3 Python 侧类型声明与导出类型存根位于 python/asc/lib/host/wrappers.py 与 python/asc/lib/host/wrappers.pyMatmulConfigParams继承ProxyBase通过代理元类在运行时把属性/方法解析到_C加载的 C 对象上set_matmul_config_params以overload形式给出两个重载签名符号导出位于 python/asc/lib/host/init.pyMatmulConfigParams、MatrixTraverse、ScheduleType等均被加入__all__因此开发者可以直接以host.MatmulConfigParams、host.ScheduleType.OUTER_PRODUCT、host.MatrixTraverse.FIRSTM的方式访问。从源码结构看这种“C 核心实现 pybind11 绑定 Python 代理封装”的三层架构是 pyasc 将 Ascend C Tiling 能力无缝映射为 Python 原生接口的通用模式可对照 python/asc/lib/host/bindings 下的其他绑定文件。七、单元测试验证接口契约的可执行证据仓库在 python/test/unit/lib/host/test_matmul_api_tiling.py 中为set_matmul_config_params提供了两个针对性用例def test_set_matmul_config_params_init(asc_platform): matmul_tiling host.MatmulApiTiling(asc_platform) matmul_tiling.set_shape(32, 256, 64) matmul_config_params host.MatmulConfigParams(1, False, host.ScheduleType.OUTER_PRODUCT, host.MatrixTraverse.FIRSTM, False) ret matmul_tiling.set_matmul_config_params(matmul_config_params) assert ret is None def test_set_matmul_config_params(asc_platform): matmul_tiling host.MatmulApiTiling(asc_platform) matmul_tiling.set_shape(32, 256, 64) ret matmul_tiling.set_matmul_config_params(1, False, host.ScheduleType.OUTER_PRODUCT, host.MatrixTraverse.FIRSTM) assert ret is None这两个用例分别验证了结构体重载MatmulConfigParams(1, False, ScheduleType.OUTER_PRODUCT, MatrixTraverse.FIRSTM, False)构造与传入均可用且无返回值异常逐参数重载位置传参(1, False, OUTER_PRODUCT, FIRSTM)省略默认的en_vec_nd2nz同样可用。它们同时印证了 Python 层该接口按None返回的行为以及ScheduleType.OUTER_PRODUCT、MatrixTraverse.FIRSTM等枚举值的真实存在。八、实践建议与排查要点调用顺序始终把set_matmul_config_params放在get_tiling之前若在get_tiling之后调用配置不会影响已经生成的 Tiling 结果。与 Kernel 侧对齐由于“Tiling 与 Kernel 需保持一致”是硬性约束建议在算子工程中把 MatmulConfig 的定义收敛到单一常量或配置文件Host Tiling 与 Kernel 共同引用避免两处手写导致漂移。模板类型取值mm_config_type仅支持 0 或 1且必须与 Matmul 对象创建时的模板一致传其他值可能导致 Tiling 生成失败或行为异常。NBuffer33 必配使用NBuffer33MatmulPolicy时schedule_type必须显式传ScheduleType.N_BUFFER_33这是最容易遗漏的硬性前置条件。按需调优默认参数INNER_PRODUCT/NOSET/ 不使能 L1 缓存在常规场景足够仅在流水串行明显如 MTE3 与 MTE2 相互等待或需要固定迭代方向时才针对性地打开 L1 缓存 UB 计算块、调整traverse或schedule_type并在实测性能后决定是否保留。九、延伸阅读本接口所属类完整方法列表asc.lib.host.MatmulApiTiling 系列文档含init、get_tiling、set_traverse、set_shape、set_buffer_space等Host 侧 API 总览docs/python-api/lib/host.md 与 docs/python-api/lib/index.mdPython 绑定实现python/asc/lib/host/bindings/MatmulApiTiling.cpp、python/asc/lib/host/wrappers.py单元测试python/test/unit/lib/host/test_matmul_api_tiling.py端到端示例仓库 examples 目录下的 Matmul 类样例如 examples/03_matmul_mix、examples/04_matmul_cube_only、examples/05_matmul_leakyrelu展示了完整的 Matmul 算子开发链路可结合阅读以理解 Tiling 参数在整体流程中的位置。【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
