当前位置：首页 > news >正文

CANN/pyasc高级算子API文档

news 2026/5/9 19:33:30

【免费下载链接】pyasc本项目为Python用户提供算子编程接口，支持在昇腾AI处理器上加速计算，接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc

asc.language.adv

Matmul

classasc.language.adv.Matmul(a: MatmulType, b: MatmulType, c: MatmulType, bias: MatmulType | None = None, matmul_config: MatmulConfig | None = None, matmul_policy: MatmulPolicy | None = 0)

classasc.language.adv.Matmul(handle: Value)

Ascend C提供一组Matmul高阶API，方便用户快速实现Matmul矩阵乘法的运算操作。 Matmul的计算公式为：C = A * B + Bias。

`Matmul.async_get_tensor_c`	获取Iterate接口异步计算的结果矩阵。该接口功能已被GetTensorC覆盖，建议直接使用GetTensorC异步接口。
`Matmul.disable_bias`	清除Bias标志位，表示Matmul计算时没有Bias参与。
`Matmul.end`	多个Matmul对象之间切换计算时，必须调用一次End函数，用于释放Matmul计算资源，防止多个Matmul对象的计算资源冲突。
`Matmul.get_batch_tensor_c`	调用一次get_batch_tensor_c，会获取C矩阵片，该接口可以与iterate_n_batch异步接口配合使用。用于在调用iterate_n_batch迭代计算后，获取一片std::max(batch_a, batch_b) * singleCoreM * singleCoreN大小的矩阵分片。
`Matmul.get_offset_c`	预留接口，为后续功能做预留。获取本次计算时当前分片在整个C矩阵中的位置。
`Matmul.get_tensor_c`	本接口和iterate接口配合使用，用于在调用iterate完成迭代计算后，根据MatmulConfig参数中的ScheduleType取值获取一块或两块baseM * baseN大小的矩阵分片。
`Matmul.init`	灵活的自定义Matmul模板参数配置。
`Matmul.iterate`	每调用一次Iterate，会计算出一块baseM * baseN的C矩阵。
`Matmul.iterate_all`	调用一次iterate_all，会计算出singleCoreM * singleCoreN大小的C矩阵。
`Matmul.iterate_batch`	该接口提供批量处理Matmul的功能，调用一次iterate_batch，可以计算出多个singleCoreM * singleCoreN大小的C矩阵。
`Matmul.iterate_n_batch`	调用一次IterateNBatch，会进行N次IterateBatch计算，计算出N个多Batch的singleCoreM * singleCoreN大小的C矩阵。在调用该接口前，需将MatmulConfig中的isNBatch参数设为true，使能多Batch输入多Batch输出功能，并调用SetWorkspace接口申请临时空间，用于缓存计算结果，即IterateNBatch的结果输出至SetWorkspace指定的Global Memory内存中。对于BSNGD、SBNGD、BNGS1S2的Layout格式，调用该接口之前需要在tiling中使用SetALayout/SetBLayout/SetCLayout/SetBatchNum设置A/B/C的Layout轴信息和最大BatchNum数；对于Normal数据格式则需使用SetBatchInfoForNormal设置A/B/C的M/N/K轴信息和A/B矩阵的BatchNum数。实例化Matmul时，通过MatmulType设置Layout类型，当前支持3种Layout类型：BSNGD、SBNGD、BNGS1S2。
`Matmul.set_batch_num`	在不改变Tiling的情况下，重新设置多Batch计算的Batch数。
`Matmul.set_bias`	设置矩阵乘的Bias。
`Matmul.set_hf32`	在纯Cube模式（只有矩阵计算）下，设置是否使能HF32（矩阵乘计算时可采用的数据类型）模式。使能后，在矩阵乘计算时， float32数据类型会转换为hf32数据类型，可提升计算性能，但同时也会带来精度损失。
`Matmul.set_org_shape`	设置Matmul计算原始完整的形状M、N、K，单位为元素个数。用于运行时修改shape，比如复用同一个Matmul对象，从不同的矩阵块取数据计算。
`Matmul.set_quant_scalar`	本接口提供对输出矩阵的所有值采用同一系数进行量化或反量化的功能，即整个C矩阵对应一个量化参数，量化参数的shape为[1]。
`Matmul.set_quant_vector`	本接口提供对输出矩阵采用向量进行量化或反量化的功能，即对于输入shape为[1, N]的参数向量， N值为Matmul矩阵计算时M/N/K中的N值，对输出矩阵的每一列都采用该向量中对应列的系数进行量化或反量化。
`Matmul.set_self_define_data`	使能模板参数MatmulCallBackFunc（自定义回调函数）时，设置需要的计算数据或在GM上存储的数据地址等信息，用于回调函数使用。复用同一个Matmul对象时，可以多次调用本接口重新设置对应数据信息。
`Matmul.set_single_shape`	设置Matmul单核计算的形状singleCoreM、singleCoreN、singleCoreK，单位为元素。用于运行时修改shape，比如复用Matmul对象来处理尾块。与SetTail接口功能一致，建议使用本接口。
`Matmul.set_sparse_index`	设置稀疏矩阵稠密化过程生成的索引矩阵。索引矩阵的Format格式要求为NZ格式。本接口仅支持在纯Cube模式（只有矩阵计算）且MDL模板的场景使用。
`Matmul.set_tail`	在不改变Tiling的情况下，重新设置本次计算的singleCoreM/singleCoreN/singleCoreK，以元素为单位。
`Matmul.set_tensor_a`	设置矩阵乘的左矩阵A。
`Matmul.set_tensor_b`	设置矩阵乘的右矩阵B。
`Matmul.set_user_def_info`	使能模板参数MatmulCallBackFunc（自定义回调函数）时，设置算子tiling地址，用于回调函数使用，该接口仅需调用一次。
`Matmul.set_workspace`	Iterate计算的异步场景，调用本接口申请一块临时空间来缓存计算结果，然后调用GetTensorC时会在该临时空间中获取C的矩阵分片。 IterateNBatch计算时，调用本接口申请一块临时空间来缓存计算结果，然后根据同步或异步场景进行其它接口的调用。
`Matmul.wait_get_tensor_c`	当使用GetTensorC异步接口将结果矩阵从GM拷贝到UB，且UB后续需要进行Vector计算时，需要调用WaitGetTensorC进行同步。
`Matmul.wait_iterate_all`	等待iterate_all异步接口返回，支持连续输出到Global Memory。
`Matmul.wait_iterate_batch`	等待iterate_batch异步接口或iterate_nbatch异步接口返回，支持连续输出到Global Memory。
`get_basic_config`	用于配置BasicBlock模板的参数，获取自定义BasicBlock模板。
`get_ib_share_norm_config`	用于配置IBShare模板的参数，获取自定义IBShare模板。
`get_matmul_api_tiling`	本接口用于在编译期间获取常量化的Matmul Tiling参数。
`get_mdl_config`	用于配置MDL模板的参数，获取自定义MDL模板。
`get_mm_config`	灵活的自定义Matmul模板参数配置。
`get_normal_config`	用于配置Norm模板的参数，获取自定义Norm模板。
`get_special_basic_config`	用于配置SpecialBasicBlock模板的参数，获取自定义SpecialBasicBlock模板。当前为预留接口。
`get_special_mdl_config`	用于配置SpecialMDL模板的参数，获取自定义SpecialMDL模板。
`register_matmul`	主要用于初始化Matmul对象。