CANN pyasc 算子调试使用 asc.dump_tensor 在 NPU 上板打印 Tensor 数据【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyascasc.dump_tensor是 CANN pyascAscend C Python 编程接口提供的算子功能调试接口用于在昇腾 AI 处理器 NPU 上板运行时直接 Dump 指定 TensorGlobalTensor/LocalTensor的内容帮助开发者快速核对算子中间计算结果。本文基于 pyasc 仓库中的 API 文档与源码实现系统讲解该接口的函数签名、参数语义、使用约束、完整调用示例及其在编译链路中的实现原理读完即可在自己的算子工程中正确使用 dump_tensor 进行上板调试。接口概述与定位在基于算子工程开发的 Ascend C 算子中当算子计算结果不符合预期时最直接的手段是查看算子内部各阶段 Tensor 的真实数据。asc.dump_tensor正是为此设计的调试接口它可以在 Kernel 执行到指定位置时将GlobalTensorGlobal Memory 上的张量或LocalTensorUnified Buffer / L1 Buffer / L0C Buffer 等本地存储上的张量中指定数量的元素内容打印出来。该接口属于 pyasc 的 basic 能力层与asc.printf打印标量和字符串、asc.dump_acc_chk_point按偏移位置精细 Dump等共同组成算子功能调试工具箱详见 算子调试调优指南。函数签名与参数说明pyasc 通过 Python 重载overload同时支持GlobalTensor与LocalTensor两种入参函数签名如下asc.language.basic.dump_tensor(tensor: GlobalTensor, desc: int, dump_size: int, shape_info: ShapeInfo | None None) - None asc.language.basic.dump_tensor(tensor: LocalTensor, desc: int, dump_size: int, shape_info: ShapeInfo | None None) - None参数类型说明tensorGlobalTensor/LocalTensor需要 Dump 的 Tensordescint用户自定义附加信息行号或其他自定义数字用于区分多次打印dump_sizeint需要 Dump 的元素个数shape_infoShapeInfo \| None传入 Tensor 的 shape 信息可按照 shape 信息进行打印缺省为None从源码实现看python/asc/language/basic/dump_tensor.pydesc与dump_size均被严格校验为RuntimeInt对应 IR 侧的整数运行时值并被转换为uint32类型后传入 IR 构建器shape_info若不为None则必须是ShapeInfo类型并会通过to_ir()转换成 IR 表示。最终统一调用create_asc_DumpTensorOp生成ascendc.dump_tensor算子指令。对应的 Ascend C 函数原型pyasc 接口与 Ascend C 接口一一对应asc.dump_tensor对应 Ascend C 中的DumpTensor模板函数包含带 / 不带ShapeInfo两组重载template typename T __aicore__ inline void DumpTensor(const LocalTensorT tensor, uint32_t desc, uint32_t dumpSize) template typename T __aicore__ inline void DumpTensor(const GlobalTensorT tensor, uint32_t desc, uint32_t dumpSize)template typename T __aicore__ inline void DumpTensor(const LocalTensorT tensor, uint32_t desc, uint32_t dumpSize, const ShapeInfo shapeInfo) template typename T __aicore__ inline void DumpTensor(const GlobalTensorT tensor, uint32_t desc, uint32_t dumpSize, const ShapeInfo shapeInfo)这一映射关系同样可以从编译链路测试中得到印证在 test/Target/AscendC/basic/dump_tensor.mlir 中IR 侧的ascendc.dump_tensor %arg0, %c1_ui32, %c2_ui32经ascir-translate -mlir-to-ascendc生成后输出为AscendC::DumpTensor(v1, v2, v3);而带 shape 的重载则会先构造AscendC::ShapeInfo v4;再生成AscendC::DumpTensor(v1, v2, v3, v4);。使用约束说明根据 API 文档 的约束章节使用该接口前需注意以下几点适用场景该功能仅用于 NPU 上板调试仅支持以下三种调用方式通过 Kernel 直调方式调用算子通过单算子 API 调用方式调用算子间接调用单算子 APIaclnnxxx接口即 PyTorch 框架单算子直调场景。存储位置限制当前仅支持打印存储位置为Unified Buffer / L1 Buffer / L0C Buffer / Global Memory的 Tensor 信息。地址对齐要求操作数地址对齐要求请参见《Ascend C 算子开发接口》中的“通用说明和约束 - 通用地址对齐约束”。数据量上限该接口使用 Dump 功能所有使用 Dump 功能的接口在每个核上 Dump 的数据总量包括信息头不可超过1M。开发者需自行控制待打印的内容数据量超出则不会打印。此外参考 算子调试调优指南 的说明asc.dump_tensor接口会对算子实际运行的性能带来一定影响通常在调测阶段使用正式发布版本前应移除。调用示例无 Tensor shape 的打印只打印 Tensor 数据不关心其形状组织asc.dump_tensor(src_local, 5, date_len)其中src_local为LocalTensordesc5作为本次打印的自定义标识date_len为需要打印的元素个数。带 Tensor shape 的打印先构造asc.ShapeInfo对象再传入数据会按照 shape 信息组织打印shape_info asc.ShapeInfo() asc.dump_tensor(x, 2, 64, shape_info)ShapeInfo定义于 python/asc/language/core/types.py构造时可传入shape: Array、original_shape: Array以及data_format: DataFormat默认为DataFormat.ND并提供shape(dim)、original_shape(dim)方法访问各维度信息。完整实战示例在 vadd 算子中 Dump 数据参考 算子调试调优指南 中的 vadd 示例将 dump_tensor 完整嵌入一个多核 vector 加法算子的调试流程import asc asc.jit def vadd_kernel(x: asc.GlobalAddress, y: asc.GlobalAddress, z: asc.GlobalAddress, BLOCK_LENGTH: asc.ConstExpr[int], BUFFER_NUM: asc.ConstExpr[int], TILE_LENGTH: asc.ConstExpr[int], TILE_NUM: asc.ConstExpr[int]): offset asc.get_block_idx() * BLOCK_LENGTH x_gm asc.GlobalTensor() x_gm.set_global_buffer(x offset) # 使用 dump_tensor 打印 x_gm 输入并附带 shape 信息 tmp_array asc.array(asc.uint32, [4, 16]) tmp_shape_info asc.ShapeInfo(tmp_array) asc.dump_tensor(x_gm, 0, 32, tmp_shape_info) for i in range(TILE_NUM): copy_in(i, x_gm, y_gm, in_queue_x, in_queue_y, TILE_LENGTH) compute(z_gm, in_queue_x, in_queue_y, out_queue_z, TILE_LENGTH) copy_out(i, z_gm, out_queue_z, TILE_LENGTH) asc.jit def copy_in(i: int, x_gm: asc.GlobalAddress, y_gm: asc.GlobalAddress, in_queue_x: asc.TQue, in_queue_y: asc.TQue, TILE_LENGTH: asc.ConstExpr[int]): x_local in_queue_x.alloc_tensor(x_gm.dtype) asc.data_copy(x_local, x_gm[i * TILE_LENGTH:], countTILE_LENGTH) # 使用 dump_tensor 打印 Local Memory 的 Tensor if i 0: asc.dump_tensor(x_local, 1, 32)运行输出样例上板执行后打印结果分为两类Global Memory 的 Tensor 会带positionGM标记并按传入的 shape 组织成二维数组展示超出实际数据的维度以-占位Local MemoryUnified Buffer的 Tensor 则标记为positionUB按一维形式输出opTypev, DumpHead: AIV-0, CoreTypeAIV, block dim16, total_block_num16, block_remain_len1048024, block_initial_space1048576, rsv0, magic5aa5bccd CANN Version: XX.XX, TimeStamp: XXXXXXXXXXXXXXXXX DumpTensor: desc0, addr41200000, data_typefloat32, positionGM, dump_size32 [[19.000000, 4.000000, 38.000000, 50.000000, ...], [39.000000, 9.000000, 82.000000, 37.000000, ...], [-,-,-,-,-,-,-,-,-,-,-,-,-,-,-,-], [-,-,-,-,-,-,-,-,-,-,-,-,-,-,-,-]] DumpTensor: desc1, addr0, data_typefloat32, positionUB, dump_size32 [6.000000, 34.000000, 52.000000, 38.000000, ...]每条DumpTensor输出的信息头包含desc本次 Dump 的自定义标识、addrTensor 起始地址、data_type元素数据类型、position存储位置 GM/UB/L1/L0C、dump_size元素个数便于与代码中的调用点一一对应定位。源码级实现原理Python 层生成 DumpTensorOp 指令dump_tensor的 Python 实现位于 python/asc/language/basic/dump_tensor.py核心流程如下对desc、dump_size做类型校验须为RuntimeInt若传入shape_info校验其类型并通过shape_info.to_ir()转换为 IR 值调用全局 IR 构建器global_builder.get_ir_builder().create_asc_DumpTensorOp(...)将tensor、desc转为uint32、dump_size转为uint32以及可选的shapeInfo组装为ascendc.dump_tensor算子指令。该文件还同时定义了printf、print_time_stamp、dump_acc_chk_point、metrics_prof_start/stop等调试接口统一通过require_jit装饰器约束其在 JIT 编译上下文中使用并在 python/asc/language/basic/init.py 中导出到asc命名空间如asc.dump_tensor。编译链路从 IR 到 Ascend C 代码生成的ascendc.dump_tensor指令在代码生成阶段由 lib/Target/AscendC/Basic/DumpTensor.cpp 等目标代码发射模块处理最终产出AscendC::DumpTensor(...)调用。该映射关系由 test/Target/AscendC/basic/dump_tensor.mlir 中的FileCheck测试用例完整覆盖包括 GlobalTensor / LocalTensor 两种形态以及带 / 不带 ShapeInfo 两种重载。调试模式自动识别仓库中还实现了调试模式的自动检测机制在 lib/Dialect/Asc/Transforms/DetectEnableDebugPass.cpp 中Pass 会遍历算子 IR一旦发现ascendc::DumpTensorOp或PrintfOp等其他调试算子即为所在函数或模块设置enableDebug属性驱动后续编译流程打开调试支持。这意味着开发者只需在 Kernel 代码中写下asc.dump_tensor(...)编译链会自动识别并启用相应能力无需手工配置开关。单元测试验证pyasc 的单元测试 python/test/unit/language/basic/test_common_api.py 中对dump_tensor做了覆盖在 Kernel 直调场景下分别对LocalTensorx_local与GlobalTensorx_gm调用asc.dump_tensor(tensor..., desc0, dump_size5)验证接口在 JIT 编译与启动全链路下可正常生成与执行。与相关调试接口的对比接口打印对象特点asc.dump_tensorTensor 内容支持 GM/UB/L1/L0C可带 shape 打印按元素个数 dumpasc.dump_acc_chk_pointTensor 内容与 dump_tensor 类似但支持指定 Tensor 的偏移位置进行 Dump且附加信息仅支持uint32_t适用于精细化调试asc.printf标量与字符串类似 Cprintf需对\n转义打印执行位置与中间标量值asc.print_time_stamp时间戳打印时间戳辅助分析执行时序各接口的完整 API 说明可参阅 basic 语言接口索引调试整体流程可参阅 算子调试调优指南。使用建议控制打印数据量每个核上所有 Dump 接口的数据总量含信息头不超过 1M超出部分不会被打印因此应只对关键位置、关键 Tensor 做局部 dump避免整个大 Tensor 全量打印。善用 desc 标识在循环内或多个位置调用时通过不同的desc值如行号、循环序号区分输出便于与代码点对应。配合 shape_info 使用对 Global Memory 的输入张量传入真实 shape可得到按维度组织的可读输出对无 shape 需求或一维数据可不传。仅用于调测阶段dump_tensor 会显著影响算子实际运行性能正式发布前应移除相关调用。【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CANN pyasc 算子调试使用 asc.dump_tensor 在 NPU 上板打印 Tensor 数据【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyascasc.dump_tensor是 CANN pyascAscend C Python 编程接口提供的算子功能调试接口用于在昇腾 AI 处理器 NPU 上板运行时直接 Dump 指定 TensorGlobalTensor/LocalTensor的内容帮助开发者快速核对算子中间计算结果。本文基于 pyasc 仓库中的 API 文档与源码实现系统讲解该接口的函数签名、参数语义、使用约束、完整调用示例及其在编译链路中的实现原理读完即可在自己的算子工程中正确使用 dump_tensor 进行上板调试。接口概述与定位在基于算子工程开发的 Ascend C 算子中当算子计算结果不符合预期时最直接的手段是查看算子内部各阶段 Tensor 的真实数据。asc.dump_tensor正是为此设计的调试接口它可以在 Kernel 执行到指定位置时将GlobalTensorGlobal Memory 上的张量或LocalTensorUnified Buffer / L1 Buffer / L0C Buffer 等本地存储上的张量中指定数量的元素内容打印出来。该接口属于 pyasc 的 basic 能力层与asc.printf打印标量和字符串、asc.dump_acc_chk_point按偏移位置精细 Dump等共同组成算子功能调试工具箱详见 算子调试调优指南。函数签名与参数说明pyasc 通过 Python 重载overload同时支持GlobalTensor与LocalTensor两种入参函数签名如下asc.language.basic.dump_tensor(tensor: GlobalTensor, desc: int, dump_size: int, shape_info: ShapeInfo | None None) - None asc.language.basic.dump_tensor(tensor: LocalTensor, desc: int, dump_size: int, shape_info: ShapeInfo | None None) - None参数类型说明tensorGlobalTensor/LocalTensor需要 Dump 的 Tensordescint用户自定义附加信息行号或其他自定义数字用于区分多次打印dump_sizeint需要 Dump 的元素个数shape_infoShapeInfo \| None传入 Tensor 的 shape 信息可按照 shape 信息进行打印缺省为None从源码实现看python/asc/language/basic/dump_tensor.pydesc与dump_size均被严格校验为RuntimeInt对应 IR 侧的整数运行时值并被转换为uint32类型后传入 IR 构建器shape_info若不为None则必须是ShapeInfo类型并会通过to_ir()转换成 IR 表示。最终统一调用create_asc_DumpTensorOp生成ascendc.dump_tensor算子指令。对应的 Ascend C 函数原型pyasc 接口与 Ascend C 接口一一对应asc.dump_tensor对应 Ascend C 中的DumpTensor模板函数包含带 / 不带ShapeInfo两组重载template typename T __aicore__ inline void DumpTensor(const LocalTensorT tensor, uint32_t desc, uint32_t dumpSize) template typename T __aicore__ inline void DumpTensor(const GlobalTensorT tensor, uint32_t desc, uint32_t dumpSize)template typename T __aicore__ inline void DumpTensor(const LocalTensorT tensor, uint32_t desc, uint32_t dumpSize, const ShapeInfo shapeInfo) template typename T __aicore__ inline void DumpTensor(const GlobalTensorT tensor, uint32_t desc, uint32_t dumpSize, const ShapeInfo shapeInfo)这一映射关系同样可以从编译链路测试中得到印证在 test/Target/AscendC/basic/dump_tensor.mlir 中IR 侧的ascendc.dump_tensor %arg0, %c1_ui32, %c2_ui32经ascir-translate -mlir-to-ascendc生成后输出为AscendC::DumpTensor(v1, v2, v3);而带 shape 的重载则会先构造AscendC::ShapeInfo v4;再生成AscendC::DumpTensor(v1, v2, v3, v4);。使用约束说明根据 API 文档 的约束章节使用该接口前需注意以下几点适用场景该功能仅用于 NPU 上板调试仅支持以下三种调用方式通过 Kernel 直调方式调用算子通过单算子 API 调用方式调用算子间接调用单算子 APIaclnnxxx接口即 PyTorch 框架单算子直调场景。存储位置限制当前仅支持打印存储位置为Unified Buffer / L1 Buffer / L0C Buffer / Global Memory的 Tensor 信息。地址对齐要求操作数地址对齐要求请参见《Ascend C 算子开发接口》中的“通用说明和约束 - 通用地址对齐约束”。数据量上限该接口使用 Dump 功能所有使用 Dump 功能的接口在每个核上 Dump 的数据总量包括信息头不可超过1M。开发者需自行控制待打印的内容数据量超出则不会打印。此外参考 算子调试调优指南 的说明asc.dump_tensor接口会对算子实际运行的性能带来一定影响通常在调测阶段使用正式发布版本前应移除。调用示例无 Tensor shape 的打印只打印 Tensor 数据不关心其形状组织asc.dump_tensor(src_local, 5, date_len)其中src_local为LocalTensordesc5作为本次打印的自定义标识date_len为需要打印的元素个数。带 Tensor shape 的打印先构造asc.ShapeInfo对象再传入数据会按照 shape 信息组织打印shape_info asc.ShapeInfo() asc.dump_tensor(x, 2, 64, shape_info)ShapeInfo定义于 python/asc/language/core/types.py构造时可传入shape: Array、original_shape: Array以及data_format: DataFormat默认为DataFormat.ND并提供shape(dim)、original_shape(dim)方法访问各维度信息。完整实战示例在 vadd 算子中 Dump 数据参考 算子调试调优指南 中的 vadd 示例将 dump_tensor 完整嵌入一个多核 vector 加法算子的调试流程import asc asc.jit def vadd_kernel(x: asc.GlobalAddress, y: asc.GlobalAddress, z: asc.GlobalAddress, BLOCK_LENGTH: asc.ConstExpr[int], BUFFER_NUM: asc.ConstExpr[int], TILE_LENGTH: asc.ConstExpr[int], TILE_NUM: asc.ConstExpr[int]): offset asc.get_block_idx() * BLOCK_LENGTH x_gm asc.GlobalTensor() x_gm.set_global_buffer(x offset) # 使用 dump_tensor 打印 x_gm 输入并附带 shape 信息 tmp_array asc.array(asc.uint32, [4, 16]) tmp_shape_info asc.ShapeInfo(tmp_array) asc.dump_tensor(x_gm, 0, 32, tmp_shape_info) for i in range(TILE_NUM): copy_in(i, x_gm, y_gm, in_queue_x, in_queue_y, TILE_LENGTH) compute(z_gm, in_queue_x, in_queue_y, out_queue_z, TILE_LENGTH) copy_out(i, z_gm, out_queue_z, TILE_LENGTH) asc.jit def copy_in(i: int, x_gm: asc.GlobalAddress, y_gm: asc.GlobalAddress, in_queue_x: asc.TQue, in_queue_y: asc.TQue, TILE_LENGTH: asc.ConstExpr[int]): x_local in_queue_x.alloc_tensor(x_gm.dtype) asc.data_copy(x_local, x_gm[i * TILE_LENGTH:], countTILE_LENGTH) # 使用 dump_tensor 打印 Local Memory 的 Tensor if i 0: asc.dump_tensor(x_local, 1, 32)运行输出样例上板执行后打印结果分为两类Global Memory 的 Tensor 会带positionGM标记并按传入的 shape 组织成二维数组展示超出实际数据的维度以-占位Local MemoryUnified Buffer的 Tensor 则标记为positionUB按一维形式输出opTypev, DumpHead: AIV-0, CoreTypeAIV, block dim16, total_block_num16, block_remain_len1048024, block_initial_space1048576, rsv0, magic5aa5bccd CANN Version: XX.XX, TimeStamp: XXXXXXXXXXXXXXXXX DumpTensor: desc0, addr41200000, data_typefloat32, positionGM, dump_size32 [[19.000000, 4.000000, 38.000000, 50.000000, ...], [39.000000, 9.000000, 82.000000, 37.000000, ...], [-,-,-,-,-,-,-,-,-,-,-,-,-,-,-,-], [-,-,-,-,-,-,-,-,-,-,-,-,-,-,-,-]] DumpTensor: desc1, addr0, data_typefloat32, positionUB, dump_size32 [6.000000, 34.000000, 52.000000, 38.000000, ...]每条DumpTensor输出的信息头包含desc本次 Dump 的自定义标识、addrTensor 起始地址、data_type元素数据类型、position存储位置 GM/UB/L1/L0C、dump_size元素个数便于与代码中的调用点一一对应定位。源码级实现原理Python 层生成 DumpTensorOp 指令dump_tensor的 Python 实现位于 python/asc/language/basic/dump_tensor.py核心流程如下对desc、dump_size做类型校验须为RuntimeInt若传入shape_info校验其类型并通过shape_info.to_ir()转换为 IR 值调用全局 IR 构建器global_builder.get_ir_builder().create_asc_DumpTensorOp(...)将tensor、desc转为uint32、dump_size转为uint32以及可选的shapeInfo组装为ascendc.dump_tensor算子指令。该文件还同时定义了printf、print_time_stamp、dump_acc_chk_point、metrics_prof_start/stop等调试接口统一通过require_jit装饰器约束其在 JIT 编译上下文中使用并在 python/asc/language/basic/init.py 中导出到asc命名空间如asc.dump_tensor。编译链路从 IR 到 Ascend C 代码生成的ascendc.dump_tensor指令在代码生成阶段由 lib/Target/AscendC/Basic/DumpTensor.cpp 等目标代码发射模块处理最终产出AscendC::DumpTensor(...)调用。该映射关系由 test/Target/AscendC/basic/dump_tensor.mlir 中的FileCheck测试用例完整覆盖包括 GlobalTensor / LocalTensor 两种形态以及带 / 不带 ShapeInfo 两种重载。调试模式自动识别仓库中还实现了调试模式的自动检测机制在 lib/Dialect/Asc/Transforms/DetectEnableDebugPass.cpp 中Pass 会遍历算子 IR一旦发现ascendc::DumpTensorOp或PrintfOp等其他调试算子即为所在函数或模块设置enableDebug属性驱动后续编译流程打开调试支持。这意味着开发者只需在 Kernel 代码中写下asc.dump_tensor(...)编译链会自动识别并启用相应能力无需手工配置开关。单元测试验证pyasc 的单元测试 python/test/unit/language/basic/test_common_api.py 中对dump_tensor做了覆盖在 Kernel 直调场景下分别对LocalTensorx_local与GlobalTensorx_gm调用asc.dump_tensor(tensor..., desc0, dump_size5)验证接口在 JIT 编译与启动全链路下可正常生成与执行。与相关调试接口的对比接口打印对象特点asc.dump_tensorTensor 内容支持 GM/UB/L1/L0C可带 shape 打印按元素个数 dumpasc.dump_acc_chk_pointTensor 内容与 dump_tensor 类似但支持指定 Tensor 的偏移位置进行 Dump且附加信息仅支持uint32_t适用于精细化调试asc.printf标量与字符串类似 Cprintf需对\n转义打印执行位置与中间标量值asc.print_time_stamp时间戳打印时间戳辅助分析执行时序各接口的完整 API 说明可参阅 basic 语言接口索引调试整体流程可参阅 算子调试调优指南。使用建议控制打印数据量每个核上所有 Dump 接口的数据总量含信息头不超过 1M超出部分不会被打印因此应只对关键位置、关键 Tensor 做局部 dump避免整个大 Tensor 全量打印。善用 desc 标识在循环内或多个位置调用时通过不同的desc值如行号、循环序号区分输出便于与代码点对应。配合 shape_info 使用对 Global Memory 的输入张量传入真实 shape可得到按维度组织的可读输出对无 shape 需求或一维数据可不传。仅用于调测阶段dump_tensor 会显著影响算子实际运行性能正式发布前应移除相关调用。【免费下载链接】pyasc本项目为Python用户提供算子编程接口支持在昇腾AI处理器上加速计算接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
