pyasc Matmul 异步取结果接口 async_get_tensor_c 使用指南从 Iterate 异步计算获取 C 矩阵的正确姿势【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc导读本文聚焦 CANN pyasc为 Python 用户提供、与 Ascend C 一一对应的算子编程接口中asc.language.adv.Matmul高阶矩阵乘法 API 的异步取结果接口async_get_tensor_c。文章从该接口的签名与语义出发结合仓库源码与其接替者get_tensor_c讲清何时用它、它如何工作、为何官方建议改用get_tensor_c异步模式、以及 MixDualMaster 双主模式下的使用禁区并给出可直接套用的异步计算完整代码骨架。读完本文你将能理解 Matmul 迭代计算的同步/异步两条取数路径并正确迁移到官方推荐的异步写法。接口速览签名、原型与语义async_get_tensor_c是Matmul类上用于获取 Iterate 接口异步计算的结果矩阵的成员方法其完整签名定义于仓库的 接口参考文档Matmul.async_get_tensor_c(c: LocalTensor) → None功能获取 Iterate 接口异步计算的结果矩阵即把异步模式下由迭代计算产生的 C 矩阵分片取出到用户指定的 LocalTensor。对应 Ascend C 函数原型__aicore__ inline void AsyncGetTensorC(const LocalTensorDstT c)参数说明c—— 结果矩阵类型为LocalTensor即存放 C 矩阵分片的目标缓冲区。约束说明当使能 MixDualMaster双主模式场景时即模板参数enableMixDualMaster设置为true时不支持使用该接口。重要状态提示文档明确说明该接口功能已被 GetTensorC 覆盖建议直接使用 GetTensorC 异步接口即这是一个已被功能替代、保留兼容的接口新代码应优先走 Matmul.get_tensor_c 的异步路径。背景Matmul 高阶 API 与 Iterate 迭代计算在 pyasc 中Matmul是一组与 Ascend C Matmul 高阶 API 一一对应的封装其计算模型为C A * B Bias见 Matmul 类定义。使用流程通常为用MatmulType声明 A、B、C 的位置、格式与数据类型构造Matmul对象通过asc.adv.register_matmul(pipe, workspace, matmul)完成注册matmul.init(tiling)用 tiling 信息初始化matmul.set_tensor_a(...)、matmul.set_tensor_b(...)等配置输入调用matmul.iterate(...)逐块迭代计算baseM * baseN的 C 矩阵分片通过取结果接口把 C 分片搬运到目标位置matmul.end()收尾。iterate是异步取数的前提每次调用 Matmul.iterate 会计算出一块baseM * baseN的 C 矩阵其签名支持sync: bool参数控制同步或异步模式。同步模式下while mm.iterate() as count:循环内直接取数即可异步模式下iterate(syncFalse)只发起计算不等待完成取数侧需要配合 wait/异步取数接口这正是async_get_tensor_c存在的场景。源码实现一个 Op 的薄封装在仓库中async_get_tensor_c的实现位于 python/asc/language/adv/matmul.py#L563-L567是典型的IR 构建器薄封装模式require_jit set_matmul_docstring(api_nameasync_get_tensor_c) def async_get_tensor_c(self, c: LocalTensor) - None: builder global_builder.get_ir_builder() builder.create_asc_MatmulAsyncGetTensorCOp(self.to_ir(), c.to_ir())require_jit装饰器表明该方法必须在asc.jit装饰的 kernel 函数内调用由 JIT 编译器捕获并翻译为 IRcreate_asc_MatmulAsyncGetTensorCOp会在 IR 中创建一个MatmulAsyncGetTensorCOp算子把Matmul对象句柄与cLocalTensor句柄一并传入后续由编译流水线发射为 Ascend C 代码中的AsyncGetTensorC其用户可见的文档字符串并非硬编码在 matmul.py 中而是由 python/asc/language/adv/utils.py#L783-L810 的async_get_tensor_c_docstring()动态生成并通过set_matmul_docstring注入。这也解释了为什么官方文档与源码注释语义完全一致——它们出自同一处模板文档生成工具docs/API_docstring_generation_tool_guide.md所描述的工作流正是从这类 docstring 模板产出docs/python-api/language/generated/下的 Markdown 文件。与异步取数配套的接口围绕异步取数Matmul还提供了配套方法同一源码文件内定义Matmul.wait_get_tensor_c等待上一次异步取数完成是异步路径的同步点Matmul.get_tensor_c支持sync: bool True参数可同时设定syncFalse走异步模式即官方文档所说的GetTensorC 异步接口Matmul.set_workspace异步场景下需要一块临时空间缓存 iterate 计算结果须在iterate之前调用。官方建议的迁移方向使用 get_tensor_c 异步模式async_get_tensor_c的全部能力把异步计算的 C 矩阵取到 LocalTensor已被get_tensor_c覆盖。后者提供了更丰富的取数形态Matmul.get_tensor_c(tensor: BaseTensor, en_atomic: int 0, en_sequential_write: bool False, sync: bool True, optional_tensor: BaseTensor | None None) → None Matmul.get_tensor_c(en_atomic: int 0, en_sequential_write: bool False, sync: bool True) → GlobalTensor其取值目标既可以是 LocalTensorVECIN也可以是 GlobalTensor还可通过optional_tensor同时输出到 GM 与 VECIN。异步模式下的标准范式见 get_tensor_c 文档调用示例# 异步模式iterate 不等待循环内逐个取分片 mm.iterate(syncFalse) # 其他操作 for i in range(single_m // base_m * single_n // base_n): mm.get_tensor_c(tensorub_cmatrix, syncFalse)以及API 返回 GM 上的 C 矩阵、手动拷贝至 UB的异步写法# base_m * base_n 128 * 256 mm.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)其中syncFalse的get_tensor_c即文档所指的GetTensorC 异步接口配合wait_get_tensor_c即可完成与旧接口等价的异步取数同时获得输出到 GM、en_atomic、en_sequential_write等扩展能力。因此新代码应优先采用get_tensor_c(syncFalse)而非async_get_tensor_c。实践验证单元测试中的完整异步链路仓库单元测试 python/test/unit/language/adv/test_matmul.py#L300-L349test_iterate_n_batch给出了async_get_tensor_c的真实使用上下文可用作自测与学习样例asc.jit def kernel_iterate_n_batch(a, b, c, workspace) - None: pipe asc.TPipe() a_type asc.adv.MatmulType(positionasc.TPosition.GM, formatasc.CubeFormat.ND, dtypeasc.float16, is_transFalse, layoutasc.LayoutMode.BSNGD) b_type asc.adv.MatmulType(positionasc.TPosition.GM, formatasc.CubeFormat.ND, dtypeasc.float16, is_transTrue, layoutasc.LayoutMode.BSNGD) c_type asc.adv.MatmulType(positionasc.TPosition.GM, formatasc.CubeFormat.ND, dtypeasc.float16, layoutasc.LayoutMode.BSNGD) matmul asc.adv.Matmul(a_type, b_type, c_type) asc.adv.register_matmul(pipe, workspace, matmul) tiling asc.adv.TCubeTiling(used_core_num24, m512, k_a512, k_b512, n512, base_m64, base_k64, base_n64, single_core_m256, single_core_k256, single_core_n256, depth_a11, depth_b11, step_m1, step_n1, share_mode0, share_ub_size0, share_l1_sizeasc.property(asc.TOTAL_L1_SIZE), share_l0c_sizeasc.property(asc.TOTAL_L0C_SIZE)) matmul.init(tiling) # ... set_tensor_a / set_tensor_b / set_hf32 / set_tail / iterate_n_batch ... matmul.set_workspace(workspace, 1024) matmul.wait_get_tensor_c() x_local asc.LocalTensor(dtypeasc.float16, posasc.TPosition.VECIN, addr0, tile_size512) matmul.async_get_tensor_c(cx_local) matmul.end()从该测试可以提取出使用async_get_tensor_c的关键事实目标缓冲区c为 VECIN 位置asc.TPosition.VECIN的LocalTensor即结果矩阵落在统一缓冲区UB的 VECIN 侧调用时机在wait_get_tensor_c()之后调用二者构成等待计算结果就绪 → 异步搬运结果的配对生命周期与iterate_*系列如iterate_n_batch、set_workspace、end同处一个 JIT kernel 中说明它属于 Matmul 迭代计算流水线的一部分tiling 前提base_m/base_n决定了单次取出的矩阵分片尺寸接口本身不感知全局形状分片逻辑由外层循环负责。使用约束与注意事项MixDualMaster 双主模式不适用当模板参数enableMixDualMaster设置为true时不支持使用async_get_tensor_c同样也不支持get_tensor_c与iterate的某些形态详见各接口文档的约束说明。涉及双主模式的场景需改用其他取数路径。仅限 JIT kernel 内调用require_jit约束意味着不能在普通 Python 脚本中直接调用必须位于asc.jit装饰的算子函数内。已被功能替代接口文档明确标注其功能已被get_tensor_c覆盖。除非维护历史代码否则新实现应迁移至get_tensor_c(syncFalse)异步模式以获得 GM 输出、en_atomic、en_sequential_write等扩展能力。与set_workspace的配合异步场景需要临时空间缓存 iterate 计算结果须在iterate之前通过set_workspace预置该约束同样适用于get_tensor_c的异步用法。小结async_get_tensor_c是 pyasc Matmul 高阶 API 异步取数的早期形态其职责单一——把 Iterate 异步计算的结果矩阵搬运到 VECIN 上的 LocalTensor底层对应 Ascend C 的AsyncGetTensorC。虽然该接口功能已被get_tensor_c异步模式覆盖并建议弃用但理解它有助于把握 Matmul 异步流水线iterate(syncFalse) → wait_get_tensor_c → 异步取数的核心脉络。在实际开发中请优先选择 get_tensor_c 的syncFalse形态并结合 iterate、wait_get_tensor_c、set_workspace 构建完整、可上板的异步 Matmul 算子。【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 pyasc Matmul 异步取结果接口 async_get_tensor_c 使用指南：从 Iterate 异步计算获取 C 矩阵的正确姿势
pyasc Matmul 异步取结果接口 async_get_tensor_c 使用指南从 Iterate 异步计算获取 C 矩阵的正确姿势【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc导读本文聚焦 CANN pyasc为 Python 用户提供、与 Ascend C 一一对应的算子编程接口中asc.language.adv.Matmul高阶矩阵乘法 API 的异步取结果接口async_get_tensor_c。文章从该接口的签名与语义出发结合仓库源码与其接替者get_tensor_c讲清何时用它、它如何工作、为何官方建议改用get_tensor_c异步模式、以及 MixDualMaster 双主模式下的使用禁区并给出可直接套用的异步计算完整代码骨架。读完本文你将能理解 Matmul 迭代计算的同步/异步两条取数路径并正确迁移到官方推荐的异步写法。接口速览签名、原型与语义async_get_tensor_c是Matmul类上用于获取 Iterate 接口异步计算的结果矩阵的成员方法其完整签名定义于仓库的 接口参考文档Matmul.async_get_tensor_c(c: LocalTensor) → None功能获取 Iterate 接口异步计算的结果矩阵即把异步模式下由迭代计算产生的 C 矩阵分片取出到用户指定的 LocalTensor。对应 Ascend C 函数原型__aicore__ inline void AsyncGetTensorC(const LocalTensorDstT c)参数说明c—— 结果矩阵类型为LocalTensor即存放 C 矩阵分片的目标缓冲区。约束说明当使能 MixDualMaster双主模式场景时即模板参数enableMixDualMaster设置为true时不支持使用该接口。重要状态提示文档明确说明该接口功能已被 GetTensorC 覆盖建议直接使用 GetTensorC 异步接口即这是一个已被功能替代、保留兼容的接口新代码应优先走 Matmul.get_tensor_c 的异步路径。背景Matmul 高阶 API 与 Iterate 迭代计算在 pyasc 中Matmul是一组与 Ascend C Matmul 高阶 API 一一对应的封装其计算模型为C A * B Bias见 Matmul 类定义。使用流程通常为用MatmulType声明 A、B、C 的位置、格式与数据类型构造Matmul对象通过asc.adv.register_matmul(pipe, workspace, matmul)完成注册matmul.init(tiling)用 tiling 信息初始化matmul.set_tensor_a(...)、matmul.set_tensor_b(...)等配置输入调用matmul.iterate(...)逐块迭代计算baseM * baseN的 C 矩阵分片通过取结果接口把 C 分片搬运到目标位置matmul.end()收尾。iterate是异步取数的前提每次调用 Matmul.iterate 会计算出一块baseM * baseN的 C 矩阵其签名支持sync: bool参数控制同步或异步模式。同步模式下while mm.iterate() as count:循环内直接取数即可异步模式下iterate(syncFalse)只发起计算不等待完成取数侧需要配合 wait/异步取数接口这正是async_get_tensor_c存在的场景。源码实现一个 Op 的薄封装在仓库中async_get_tensor_c的实现位于 python/asc/language/adv/matmul.py#L563-L567是典型的IR 构建器薄封装模式require_jit set_matmul_docstring(api_nameasync_get_tensor_c) def async_get_tensor_c(self, c: LocalTensor) - None: builder global_builder.get_ir_builder() builder.create_asc_MatmulAsyncGetTensorCOp(self.to_ir(), c.to_ir())require_jit装饰器表明该方法必须在asc.jit装饰的 kernel 函数内调用由 JIT 编译器捕获并翻译为 IRcreate_asc_MatmulAsyncGetTensorCOp会在 IR 中创建一个MatmulAsyncGetTensorCOp算子把Matmul对象句柄与cLocalTensor句柄一并传入后续由编译流水线发射为 Ascend C 代码中的AsyncGetTensorC其用户可见的文档字符串并非硬编码在 matmul.py 中而是由 python/asc/language/adv/utils.py#L783-L810 的async_get_tensor_c_docstring()动态生成并通过set_matmul_docstring注入。这也解释了为什么官方文档与源码注释语义完全一致——它们出自同一处模板文档生成工具docs/API_docstring_generation_tool_guide.md所描述的工作流正是从这类 docstring 模板产出docs/python-api/language/generated/下的 Markdown 文件。与异步取数配套的接口围绕异步取数Matmul还提供了配套方法同一源码文件内定义Matmul.wait_get_tensor_c等待上一次异步取数完成是异步路径的同步点Matmul.get_tensor_c支持sync: bool True参数可同时设定syncFalse走异步模式即官方文档所说的GetTensorC 异步接口Matmul.set_workspace异步场景下需要一块临时空间缓存 iterate 计算结果须在iterate之前调用。官方建议的迁移方向使用 get_tensor_c 异步模式async_get_tensor_c的全部能力把异步计算的 C 矩阵取到 LocalTensor已被get_tensor_c覆盖。后者提供了更丰富的取数形态Matmul.get_tensor_c(tensor: BaseTensor, en_atomic: int 0, en_sequential_write: bool False, sync: bool True, optional_tensor: BaseTensor | None None) → None Matmul.get_tensor_c(en_atomic: int 0, en_sequential_write: bool False, sync: bool True) → GlobalTensor其取值目标既可以是 LocalTensorVECIN也可以是 GlobalTensor还可通过optional_tensor同时输出到 GM 与 VECIN。异步模式下的标准范式见 get_tensor_c 文档调用示例# 异步模式iterate 不等待循环内逐个取分片 mm.iterate(syncFalse) # 其他操作 for i in range(single_m // base_m * single_n // base_n): mm.get_tensor_c(tensorub_cmatrix, syncFalse)以及API 返回 GM 上的 C 矩阵、手动拷贝至 UB的异步写法# base_m * base_n 128 * 256 mm.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)其中syncFalse的get_tensor_c即文档所指的GetTensorC 异步接口配合wait_get_tensor_c即可完成与旧接口等价的异步取数同时获得输出到 GM、en_atomic、en_sequential_write等扩展能力。因此新代码应优先采用get_tensor_c(syncFalse)而非async_get_tensor_c。实践验证单元测试中的完整异步链路仓库单元测试 python/test/unit/language/adv/test_matmul.py#L300-L349test_iterate_n_batch给出了async_get_tensor_c的真实使用上下文可用作自测与学习样例asc.jit def kernel_iterate_n_batch(a, b, c, workspace) - None: pipe asc.TPipe() a_type asc.adv.MatmulType(positionasc.TPosition.GM, formatasc.CubeFormat.ND, dtypeasc.float16, is_transFalse, layoutasc.LayoutMode.BSNGD) b_type asc.adv.MatmulType(positionasc.TPosition.GM, formatasc.CubeFormat.ND, dtypeasc.float16, is_transTrue, layoutasc.LayoutMode.BSNGD) c_type asc.adv.MatmulType(positionasc.TPosition.GM, formatasc.CubeFormat.ND, dtypeasc.float16, layoutasc.LayoutMode.BSNGD) matmul asc.adv.Matmul(a_type, b_type, c_type) asc.adv.register_matmul(pipe, workspace, matmul) tiling asc.adv.TCubeTiling(used_core_num24, m512, k_a512, k_b512, n512, base_m64, base_k64, base_n64, single_core_m256, single_core_k256, single_core_n256, depth_a11, depth_b11, step_m1, step_n1, share_mode0, share_ub_size0, share_l1_sizeasc.property(asc.TOTAL_L1_SIZE), share_l0c_sizeasc.property(asc.TOTAL_L0C_SIZE)) matmul.init(tiling) # ... set_tensor_a / set_tensor_b / set_hf32 / set_tail / iterate_n_batch ... matmul.set_workspace(workspace, 1024) matmul.wait_get_tensor_c() x_local asc.LocalTensor(dtypeasc.float16, posasc.TPosition.VECIN, addr0, tile_size512) matmul.async_get_tensor_c(cx_local) matmul.end()从该测试可以提取出使用async_get_tensor_c的关键事实目标缓冲区c为 VECIN 位置asc.TPosition.VECIN的LocalTensor即结果矩阵落在统一缓冲区UB的 VECIN 侧调用时机在wait_get_tensor_c()之后调用二者构成等待计算结果就绪 → 异步搬运结果的配对生命周期与iterate_*系列如iterate_n_batch、set_workspace、end同处一个 JIT kernel 中说明它属于 Matmul 迭代计算流水线的一部分tiling 前提base_m/base_n决定了单次取出的矩阵分片尺寸接口本身不感知全局形状分片逻辑由外层循环负责。使用约束与注意事项MixDualMaster 双主模式不适用当模板参数enableMixDualMaster设置为true时不支持使用async_get_tensor_c同样也不支持get_tensor_c与iterate的某些形态详见各接口文档的约束说明。涉及双主模式的场景需改用其他取数路径。仅限 JIT kernel 内调用require_jit约束意味着不能在普通 Python 脚本中直接调用必须位于asc.jit装饰的算子函数内。已被功能替代接口文档明确标注其功能已被get_tensor_c覆盖。除非维护历史代码否则新实现应迁移至get_tensor_c(syncFalse)异步模式以获得 GM 输出、en_atomic、en_sequential_write等扩展能力。与set_workspace的配合异步场景需要临时空间缓存 iterate 计算结果须在iterate之前通过set_workspace预置该约束同样适用于get_tensor_c的异步用法。小结async_get_tensor_c是 pyasc Matmul 高阶 API 异步取数的早期形态其职责单一——把 Iterate 异步计算的结果矩阵搬运到 VECIN 上的 LocalTensor底层对应 Ascend C 的AsyncGetTensorC。虽然该接口功能已被get_tensor_c异步模式覆盖并建议弃用但理解它有助于把握 Matmul 异步流水线iterate(syncFalse) → wait_get_tensor_c → 异步取数的核心脉络。在实际开发中请优先选择 get_tensor_c 的syncFalse形态并结合 iterate、wait_get_tensor_c、set_workspace 构建完整、可上板的异步 Matmul 算子。【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考