CANN pyasc Python API 全指南asc.language 算子编程与 asc.lib 运行时接口详解【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc导读本文围绕 CANN pyasc 仓库的官方 Python API 文档docs/python-api/index.md展开系统梳理asc.language算子 Kernel 侧编程接口与asc.libHost 侧 Tiling / 运行时配置接口两大模块的完整接口体系。读者将掌握如何在昇腾 AI 处理器上用 Python 原生语法完成 Matmul 矩阵乘、矢量运算、数据搬运与同步控制等算子开发如何理解adv/basic/core/fwk四个子模块的职责边界以及如何借助asc.lib.host的 Matmul Tiling API 与asc.runtime.config的运行时配置搭建可运行的算子工程。文中所有接口签名、约束与代码示例均来自仓库文档与 examples 目录中的真实用例可直接对照查阅。一、Python API 总览从文档骨架看模块划分docs/python-api/index.md是 pyasc 的 API 导航入口将全部编程接口划分为五个层次对应仓库 python/asc 包的实际组织方式API 模块文档路径核心职责asc.language.adv高阶算子 APIMatmul 矩阵乘高阶封装、激活类算子softmax 等、模板配置接口asc.language.basic基础算子 API数据搬运、矢量/标量运算、同步控制、矩阵运算、TensorDescasc.language.core核心数据结构GlobalTensor / LocalTensor / ShapeInfo / LocalMemAllocatorasc.language.fwk框架资源管理TPipe / TQue / TBuf / TBufPool 流水与内存管理asc.lib.hostHost 侧接口Matmul Tiling 计算、运行时配置Backend / Platform这种划分与 Ascend C 的编程模型一一对应core提供张量这一最基本的数据载体basic提供构成算子主体的底层指令级操作fwk负责多级流水MTE2 搬运、Vector 计算、MTE3 回搬的资源编排adv则在上述三者之上提供开箱即用的高阶封装lib.host则运行在 Host 侧负责编译期 Tiling 决策。从 python/asc/language/init.py 可以看出四个子模块的公开符号最终统一汇入asc.language命名空间用户既可import asc后直接调用也可按子模块细分导入。二、asc.language.advMatmul 高阶矩阵乘 APIadv模块的核心是Matmul类文档给出的计算语义为C A × B Bias。Matmul 提供两种构造方式# 方式一显式指定参与计算的矩阵与配置 Matmul(a: MatmulType, b: MatmulType, c: MatmulType, bias: MatmulType | None None, matmul_config: MatmulConfig | None None, matmul_policy: MatmulPolicy | None 0) # 方式二通过已有 handleIR Value构造 Matmul(handle: Value)2.1 核心计算流程接口Matmul 的计算采用「设置输入 → 迭代计算 → 取结果」的三段式编程模型各接口的语义与使用要点如下接口功能关键约束Matmul.init以 TCubeTiling 参数初始化 Matmul 对象需先调用register_matmul完成注册Matmul.set_tensor_a/set_tensor_b设置左矩阵 A / 右矩阵 B可传 GlobalTensor、LocalTensor 或标量TensorA 地址空间不小于 single_m × single_kMatmul.set_bias/disable_bias设置 / 清除 Bias—Matmul.iterate每调用一次计算一块 baseM × baseN 的 C 矩阵使能 MixDualMasterenableMixDualMastertrue时不支持Matmul.iterate_all一次调用计算出 singleCoreM × singleCoreN 的 C 矩阵—Matmul.iterate_batch/iterate_n_batch批量 / N 次批量迭代Batch 场景需预先配置 Layout 轴信息见 5.1 节Matmul.get_tensor_c取回计算结果分片传入 C 矩阵空间不小于 base_m × base_nMatmul.wait_get_tensor_c异步取回后同步供后续 Vector 计算—Matmul.end释放 Matmul 计算资源多 Matmul 对象切换时必须调用防止资源冲突2.2 同步与异步两种典型用法文档在Matmul.iterate与Matmul.get_tensor_c中给出了可直接运行的完整模式# 同步模式iterate 与 get_tensor_c 成对出现在同一循环中 while mm.iterate() as count: mm.get_tensor_c(tensorub_cmatrix) # 异步模式先发起计算再循环取片 mm.iterate(syncFalse) # 其他操作可插入与计算无关的代码 for i in range(single_m // base_m * single_n // base_n): mm.get_tensor_c(tensorub_cmatrix, syncFalse)异步场景下需要注意iterate(syncFalse)之后需通过Matmul.set_workspace预先申请一块 Global Memory 临时空间缓存计算结果get_tensor_c会从该临时空间中取片该接口必须在iterate之前调用。get_tensor_c还支持同时输出到 GM 与 VECIN# 获取 C 矩阵同时输出至 GM 和 VECIN while mm.iterate() as count: mm.get_tensor_c(tensorgm, optional_tensorub_cmatrix)以及「API 返回 GM 上的 C 矩阵、手动拷贝至 UB」的精细控制模式base_m * base_n 128 * 256mm.set_tensor_a(gm_a) mm.set_tensor_b(gm_b) mm.set_tail(single_m, single_n, single_k) mm.iterate(syncFalse) for i in range(single_m // base_m * single_n // base_n): global mm.get_tensor_c(syncFalse) for j in range(4): local que.alloc_tensor(dtypeasc.half) asc.data_copy(local, global[64 * 128 * i:], count64 * 128)2.3 运行时 Shape 与量化控制Matmul 支持在不重建对象的前提下运行时调整计算形态Matmul.set_org_shape设置原始完整形状 M、N、K元素个数用于复用同一 Matmul 对象从不同矩阵块取数Matmul.set_single_shape/set_tail设置单核计算形状 singleCoreM/N/K用于处理尾块两者功能一致文档建议优先使用set_single_shapeMatmul.set_hf32纯 Cube 模式下使能 HF32float32 会转换为 hf32 参与计算以提升性能但伴随精度损失Matmul.set_quant_scalar整个 C 矩阵对应一个量化系数shape 为 [1]对输出做统一量化/反量化Matmul.set_quant_vector输入 shape 为 [1, N] 的量化向量对 C 矩阵每一列使用对应位置的系数Matmul.set_sparse_index稀疏矩阵稠密化生成的索引矩阵NZ 格式仅支持纯 Cube 模式且 MDL 模板场景Matmul.set_user_def_info/set_self_define_data使能模板参数 MatmulCallBackFunc自定义回调时分别设置算子 tiling 地址与计算数据地址前者仅需调用一次。2.4 Matmul 模板配置接口除Matmul类外adv还提供一组配套的模板参数配置函数接口用途register_matmul初始化 Matmul 对象对应调用示例asc.adv.register_matmul(pipe, workspace, mm, tiling)get_mm_config灵活的自定义 Matmul 模板参数配置get_basic_config/get_special_basic_config配置 BasicBlock / SpecialBasicBlock 模板后者为预留接口get_mdl_config/get_special_mdl_config配置 MDL / SpecialMDL 模板get_normal_config配置 Norm 模板get_ib_share_norm_config配置 IBShare 模板get_matmul_api_tiling编译期获取常量化的 Matmul Tiling 参数2.5 Activation Opsadv模块还包含激活类算子文档中以softmax为例给出语义将输入 tensor[m0, m1, ...mt, n]t ≥ 0非尾轴长度相乘看作 m则输入 shape 看作 [m, n]在最后一维上执行 softmax 归一化。三、asc.language.basic基础算子指令集basic模块是与 Ascend C 底层指令一一对应的基础操作集合文档按功能划分为八大类。3.1 数据搬运与格式转换Common operationsdata_copy最核心的搬运接口支持 Local Memory 与 Global Memory 之间、以及 Local Memory 内部的数据搬运可在搬运过程中随路完成格式转换与量化激活data_copy_pad非对齐搬运GM → Local 时可按需填充数据填充值由set_pad_value设置copyVector Core 内部 VECIN / VECCALC / VECOUT 存储单元间的数据搬运load_dataCube 侧矩阵数据加载分形矩阵大小随数据类型变化如 float 在 A1/A2 上为 16×8、B1/B2 上为 8×16支持 GM→A1/B1、A1→A2、B1→B2 等通路load_data_with_transpose带转置的 2D 数据从 A1/B1 到 A2/B2 的加载transpose16×16 矩阵块转置或 [N,C,H,W] ↔ [N,H,W,C] 转换trans_data_to_5hdNCHW → NC1HWC0 格式转换单次 repeat 可处理 512 Byte16 个 datablockload_image_to_local与set_aipp_functions图像数据从 GM 搬运到 A1/B1搬运中完成翻转、抠图、缩放、色域与类型转换等预处理。3.2 流水与核间同步同步控制是昇腾多级流水编程的关键basic提供三个层次的同步原语核内流水间同步set_flag/wait_flag数据依赖的不同流水指令之间、pipe_barrier相同流水内、data_sync_barrier阻塞直到此前内存访问指令结束核间同步sync_all硬同步 / 软同步、ib_set/ib_wait标志位同步成对使用、notify_next_block/wait_pre_block通过 GM 标志位通知前后核分离架构同步cross_core_set_flag/cross_core_wait_flag基于 flagId 计数器支持三种模式模式 0 同步所有 AIC/AIV 核、模式 1 同步 AI Core 内 AIV 核之间、模式 2 同步 AI Core 内 AIC 与 AIV 之间。仓库示例 examples/01_add/add.py 完整展示了上述同步原语在真实算子中的用法双缓冲BUFFER_NUM 2下每个 tile 依次执行data_copyMTE2 搬运→set_flag/wait_flag(MTE2_V)→addVector 计算→set_flag/wait_flag(V_MTE3)→data_copyMTE3 回搬→set_flag/wait_flag(MTE3_MTE2)构成标准的 MTE2→V→MTE3 三级流水。3.3 矢量运算全家桶二元运算add、sub、mul、div、max、min以及融合变体add_relu、add_deq_relu、add_relu_cast、sub_relu、sub_relu_cast、mul_cast、mul_add_dst、fused_mul_add、fused_mul_add_relu、bitwise_and/or、compare、bilinear_interpolation一元运算abs、exp、ln、sqrt、rsqrt、reciprocal、relu、bitwise_not、gather_mask矢量-标量运算adds、muls、maxs、mins、compare_scalar、leaky_relu、shift_left、shift_right归约运算whole_reduce_sum/max/min每个 repeat 内求和 / 求最值及索引、pair_reduce_sum相邻奇偶元素求和、repeat_reduce_sum功能已被 whole_reduce_sum 覆盖文档建议使用后者。3.4 Mask 与原子操作set_mask_count将掩码设为 Counter 模式可自动推断迭代次数并处理非对齐尾块set_mask_norm为默认的 Normal 模式set_vector_mask在不同模式下语义不同reset_mask恢复全 1 默认值set_atomic_add/set_atomic_max/set_atomic_min/set_atomic_none/set_atomic_type控制从 VECOUT/L0C/L1 到 GM 的原子累加 / 原子比较写回。3.5 矩阵运算与调试mmad完成 C A × BABC 分别位于 A2/B2/CO1数据排布为 ZZ/ZN/NZfixpipe矩阵计算后处理可随路量化并把数据从 CO1 搬回 GMload_data_with_sparse/mmad_with_sparse稀疏矩阵场景后者 A 为稀疏矩阵、B 为稠密矩阵需先通过前者载入并生成索引矩阵调试与性能dump_tensor/dump_acc_chk_pointDump 指定 Tensor 内容后者支持偏移定位、printfCPU/NPU 域格式化输出、trapNPU 下中断 AI CoreCPU 下等价 assert、metrics_prof_start/metrics_prof_stop配合 msProf 划定调优代码段、get_system_cycle按 50MHz 换算时间time cycle/50 us、get_block_idx/get_block_num多核索引与核数、get_sub_block_idxVector 核 ID、get_task_ratioAIC/AIV 与 AI Core 数量比例。3.6 TensorDesc 与 ListTensorDescTensorDesc描述动态 shape 场景下的张量元数据构造时可通过dtype指定数据类型TensorDesc(dtype: DataType KT.float32) # 空构造 TensorDesc(handle: Value, dtype: DataType KT.float32)其成员包括set_shape_addr配置存储 shape 的地址、get_dim/get_shape/get_index/get_data_ptr/get_data_obj。ListTensorDesc用于管理一组 TensorDescListTensorDesc(data: GlobalAddress, length: int 4294967295, shape_size: int 4294967295)提供init解析内存排布、get_desc/get_data_ptr按 index 取元数据或地址、get_size数据指针个数。四、asc.language.core张量与内存核心数据结构core模块定义算子编程中最基础的数据对象。4.1 GlobalTensor 与 LocalTensorGlobalTensor(handle: Value)存放 Global MemoryGM全局数据方法包括set_global_buffer传地址初始化、set_value/get_value按偏移读写元素、get_size元素个数、get_phy_addr地址、set_shape_info/get_shape_infoshape 信息需先设置后读取无默认值、set_l2_cache_hintL2 Cache 默认使能LocalTensor存放 AI Core Local Memory内部存储数据支持逻辑位置 TPosition 为 VECIN、VECOUT、VECCALC、A1、A2、B1、B2、CO1、CO2提供多种构造重载指定 dtype / addr / pos / tile_size 等。典型方法get_value/set_value仅 VECIN/VECCALC/VECOUT 支持、set_size重用变量且长度变化时重新设置单位元素、set_buffer_len配合operator[]切片生成新 Tensor 时建议设置便于编译器优化内存与同步、set_addr_with_offset带偏移定义新 Tensor、reinterpret_cast保持字节数不变的类型重解释、set_user_tag/get_user_tag用户自定义 Tag。仓库示例 examples/01_add/add.py 演示了静态 Tensor 编程的典型写法用asc.LocalTensor(data_type, asc.TPosition.VECIN, 0, tile_length * BUFFER_NUM)在 VECIN 上按地址偏移分配双缓冲并通过x_local[buf_id * tile_length:]切片式取用子块——这正是LocalTensor构造与切片 API 的落地场景。4.2 LocalMemAllocator 与 ShapeInfoLocalMemAllocator(hard: Hardware Hardware.UB)是静态 Tensor 编程方式下的内存管理类无需构建 TPipe/TQue直接创建 LocalTensor 开发算子以降低运行时开销、获得更优性能仅支持静态 Tensor 编程不可与 TPipe 等接口混用。提供alloc按逻辑位置、数据类型、长度返回 LocalTensor与get_cur_addr当前物理位置空闲起始地址ShapeInfo存放张量 shape 信息构造签名ShapeInfo(shape: Array, original_shape: Array | None None, data_format: DataFormat DataFormat.ND)配套的get_shape_size返回 Shape 所有 dim 的累乘结果。五、asc.language.fwk流水框架与资源管理fwk模块提供 Ascend C 经典的 TPipe/TQue 流水编程范式一个 Kernel 函数必须且只能初始化一个 TPipe 对象。5.1 TPipe / TBuf / TBufPoolTPipe统一管理 Device 端内存与同步事件init_buffer为 TQue/TBuf 分配内存alloc_event_id/release_event_id/fetch_event_id管理 HardEvent 同步事件 IDalloc 与 release 必须配对fetch 只取不占init_buf_pool初始化 TBufPool 资源池destroy释放资源reset恢复初始化状态TBuf管理临时变量内存TBuf(pos: TPosition)通过 TPipe 的 InitBuffer 初始化后用get获取指定长度 Tensor、get_with_offset从基地址偏移后提取 TensorTBufPool手动管理 / 复用 UB/L1 物理内存适用于多 stage 计算中 UB/L1 不足的场景init_buf_pool划分整块资源、init_buffer为 TQue/TBuf 分配、reset切换资源池时结束当前事件Buffer 内容可能被改写可切回复用。5.2 TQue 与 TQueBindTQue是流水任务间通信与同步的队列TQue(pos: TPosition TPosition.VECIN, depth: int 1)提供alloc_tensor/enque/deque/free_tensor内存分配与出入队以及has_idle_buffer/has_tensor_in_que/vacant_in_que/get_tensor_count_in_que状态查询TQueBind绑定源/目的逻辑位置TQueBind(src: TPosition | None TPosition.VECIN, dst: TPosition | None TPosition.VECIN, depth: int 0, mask: int 0)根据位置对确定内存分配位置并自动插入同步事件。TQue 是 TQueBind 的简化模式常规场景用 TQue涉及特殊数据通路时用 TQueBind后者额外提供free_all_event释放队列中所有同步事件因为同步事件数量有限超出限制时需释放后可再次申请get_tpipe_ptr获取 TPipe 对象创建时设置的全局唯一指针获取后可进行 TPipe 相关操作。六、asc.lib.hostHost 侧 Matmul Tiling 与运行时配置6.1 Matmul Tiling APIasc.lib.host提供 Matmul Tiling API用户只需传入 A/B/C 矩阵的 Position、Format、DType 等信息即可获取 Kernel 侧Init中TCubeTiling结构体所需参数。三类核心类为MatmulApiTiling / MultiCoreMatmulTiling / BatchMatmulTiling。共有接口asc.lib.host.MatmulApiTiling 系列文档接口功能set_a_type/set_b_type/set_c_type/set_bias_type设置矩阵的位置、数据格式、数据类型、是否转置必须与 Kernel 侧保持一致set_shape(m, n, k)设置计算形状可为原始完整矩阵或局部矩阵元素为单位set_org_shape设置原始完整形状 M、N、K 或 Ka/Kbset_buffer_space设置 L1 Buffer / L0C / UB / BiasTable Buffer 空间字节set_double_buffer设置 A/B/C/Bias 是否使能 double buffer 及 ND2NZ / NZ2ND 转换用于 Tiling 内部调优set_traverse固定计算方向M 轴优先或 N 轴优先enable_bias设置 Bias 是否参与运算set_sparse设置是否为 Sparse Matmul 场景set_dequant_type设置量化 / 反量化模式set_matmul_config_params自定义 MatmulConfig 参数取值须与 Kernel 侧一致set_batch_num设置多 Batch 最大 Batch 数max(batchA, batchB)set_a_layout/set_b_layout/set_c_layout设置 B/S/N/G/D 轴信息BSNGD、SBNGD、BNGS1S2 Layout 下调用 IterateBatch 前必须在 Host 侧设置set_batch_info_for_normalNormal Layout 下设置 A/B 的 M/N/K 轴信息与 Batch 数get_base_m/get_base_n/get_base_k/get_tiling获取 Tiling 计算结果set_fix_split、set_split_range、set_mad_type预留 / 暂不支持接口文档明确标注 目前 Tiling 暂时不支持该功能、当前版本暂不支持MultiCoreMatmulTiling 独有接口set_dim参与运算核数、set_align_split切分对齐值如 single_core_m 对齐 64 元素、set_single_range/set_single_shape单核形状的范围 / 固定值、enable_multi_core_split_k使能切 K 轴默认不切须在 GetTiling 前调用、get_core_numBlockNum、get_single_shapesingle_core_m/n/k。BatchMatmulTiling 独有接口get_core_num获取多核切分的 BlockNum。从仓库 python/asc/lib/host 的实现结构看这些接口通过 C bindingsbindings 目录暴露给 Python并由 wrappers.py 封装用户可在自定义 Tiling 算子中直接调用。6.2 运行时配置asc.runtime.configasc.runtime.config提供运行后端的全局配置set_platform(backend[, soc_version, device_id, check])设置后端、SOC 版本与设备 ID。当 backend 为 Model 时soc_version 默认为Ascend910B1当 backend 为 NPU 时soc_version 自动从当前平台获取并校验与传入值是否一致枚举BackendBackend.Model仿真 / 模型运行与Backend.NPU真实 NPU 硬件枚举PlatformAscend910B1 / B2 / B2C / B3 / B4 / B4_1以及 Ascend910_9362 / 9372 / 9381 / 9382 / 9391 / 9392 等 SOC 版本。仓库示例 examples/01_add/add.py 展示了标准的运行方式命令行参数-r指定 backend默认 Model、-v指定 platform先校验枚举合法性再调用config.set_platform(backend, platform)通过device npu if backend Backend.NPU else cpu确定输入数据所在设备最终以vadd_kernelUSE_CORE_NUM, rt.current_stream()的多核网格形式启动 Kernel并用torch.allclose校验结果。examples目录下还提供了matmul_mix、matmul_cube_only、matmul_leakyrelu、gelu、swiglu、rmsnorm、linear、fused_infer_attention等更复杂的参考算子以及配套的bench_*.py性能测试与profile_msprof.py性能剖析脚本可作为 Matmul / 矢量融合算子的进一步学习素材。七、总结从接口清单到算子工程docs/python-api/index.md及其子文档勾勒出 pyasc 的完整 Python 编程面写 Kernelasc.language.core提供张量载体asc.language.basic提供指令级原语asc.language.fwk提供 TPipe/TQue 流水编排asc.language.adv提供 Matmul 等开箱即用的高阶封装算 Tiling / 配运行asc.lib.host的 MatmulApiTiling 系列负责 Host 侧切分决策asc.runtime.config负责后端Model/NPU与 SOC 平台选择验证与调优asc.language.basic中的printf/dump_tensor/metrics_prof_start/stop与 examples 中的 bench / profile 脚本形成闭环。在动手开发前建议结合 examples 目录的完整可运行样例尤其 01_add/add.py 与 03~10 的 Matmul 系列理解「搬运-计算-同步-回搬」的流水范式再按本文接口清单逐项查阅对应生成文档的签名、约束与调用示例即可快速搭建并调通自己的昇腾算子。【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考