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

10分钟上手asc-tools：昇腾NPU算子开发工具集

news 2026/5/25 5:30:47

前言

要做昇腾NPU算子开发，但不知道从哪入手？Ascend C代码写完了，不知道怎么编译、怎么调试、怎么验证？asc-tools就是为这个场景准备的。

asc-tools是昇腾官方提供的算子开发工具集，包含了编译工具（ascendc++）、调试工具（adb/gdb）、验证工具（acl soot）等，一站式解决算子开发的全流程问题。第一次用它的时候，被它的"一条命令搞定编译"震撼到了——不用配环境变量，不用写Makefile，只要ascendc++ my_op.cpp -o my_op.so，就搞定了。

本文是手把手实战——会从asc-tools的安装讲起，一步步带你在昇腾NPU上写、编译、调试、验证一个简单的VectorAdd算子。

asc-tools在CANN五层架构里的位置

先说清楚asc-tools住在哪。昇腾CANN的架构分五层，asc-tools住在第2层——昇腾计算服务层，具体是工具与开发套件里的算子开发工具集。

第1层：昇腾计算语言层 AscendCL └─ 算子开发接口 Ascend C 第2层：昇腾计算服务层 ← asc-tools 住在这 ├─ AOL 算子库 ├─ AOE 调优引擎 └─ asc-tools（算子开发工具集）← 本文主角 第3层：昇腾计算编译层 ├─ Graph Compiler 图编译器 └─ BiSheng / ATC 编译器 第4层：昇腾计算执行层 ├─ Runtime 运行时 ├─ Graph Executor 图执行器 ├─ HCCL 集合通信库 └─ AIPP / DVPP 第5层：昇腾计算基础层 ├─ RMS/CMS/DMS/DRV └─ SVM/VM/HDC 硬件层：昇腾 AI 硬件（达芬奇架构）

为啥住第2层？因为asc-tools是"开发工具"，是给算子开发者用的，不是给最终用户用的。可以把它理解成"昇腾CANN的SDK"——包含编译、调试、验证工具，让算子开发更简单。

依赖关系

asc-tools → driver → hardware（NPU）。asc-tools依赖driver提供的接口，driver依赖NPU硬件。

环境准备：安装asc-tools

要用asc-tools，先要安装它。

方式1：pip安装（推荐）

# pip安装asc-toolspipinstallascend-ascend-tools-ihttps://pypi.ascend.com/simple/# 验证安装成功ascendc--version# 预期输出（示例）# ascend-ascend-tools 1.2.0# Copyright (C) 2024 Ascend

方式2：源码编译安装

# 克隆asc-tools仓库gitclone https://atomgit.com/cann/asc-tools.git# 编译安装cdasc-toolsmkdirbuild&&cdbuild cmake..make-j$(nproc)sudomakeinstall# 验证安装成功ascendc--version

方式3：Docker镜像

# 拉取昇腾CANN开发镜像（已包含asc-tools）dockerpull ascendcr.jfrog.io/ascend/ascend-cann-toolkit:8.0# 运行容器dockerrun-itascendcr.jfrog.io/ascend/ascend-cann-toolkit:8.0# 验证安装成功ascendc--version

逐步推进：asc-tools的4个使用步骤

asc-tools的使用分4步，一步步拆。

步骤1：写Ascend C代码

用asc-tools的第一步，是写Ascend C代码。Ascend C是昇腾CANN的算子编程语言，基于C++，针对达芬奇架构做了扩展。

代码讲解（VectorAdd算子）：

// vector_add.cpp#include"ascend_c/ascend_c.h"usingnamespaceascend::c;// VectorAdd算子类classVectorAdd:publicKernelOperator{public:// 初始化算子参数voidInit(int32_telement_count){element_count_=element_count;// 绑定输入输出bufferx_buffer_.Bind(this,"x");// 输入xy_buffer_.Bind(this,"y");// 输入yz_buffer_.Bind(this,"z");// 输出z// 设置输出shapez_buffer_.SetShape({element_count_});}// 算子主体voidCompute(){// 分配LocalTensorautox_local=x_buffer_.GetLocal();autoy_local=y_buffer_.GetLocal();autoz_local=z_buffer_.GetLocal();// VectorAdd计算for(inti=0;i<element_count_;i++){z_local.SetValue(i,x_local.GetValue(i)+y_local.GetValue(i));}// 同步数据到GlobalTensorz_buffer_.SyncToGlobal();}private:int32_telement_count_;InputBuffer<x_buffer_,Tensor>x_buffer_;InputBuffer<y_buffer_,Tensor>y_buffer_;OutputBuffer<z_buffer_,Tensor>z_buffer_;};// 算子注册（框架自动调用）REGISTER_OP("VectorAdd").Input(x).Input(y).Output(z).Attr(element_count,Int).SetKernelFunc([](constOpKernelInput&input,OpKernelOutput&output){VectorAdd op;op.Init(input.GetAttr<int32_t>("element_count"));op.Compute();return0;});

代码讲解：

class VectorAdd：VectorAdd算子类，继承自KernelOperator
Init()：初始化算子参数，绑定输入输出buffer
Compute()：算子主体，做VectorAdd计算
REGISTER_OP()：注册算子，告诉框架这个算子叫什么、输入输出是什么

⚠️ 踩坑预警：Ascend C的语法和标准C++有差异（比如__aicore__关键字、LocalTensor/GlobalTensor等），要仔细看文档。

步骤2：编译Ascend C代码

代码写完了，第二步是编译。asc-tools提供了ascendc++编译器，是gcc的昇腾版本，针对达芬奇架构做了优化。

编译命令：

# 编译VectorAdd算子ascendc++-ovector_add.so vector_add.cpp\-I${ASCEND_HOME}/ascend-c/include\-L${ASCEND_HOME}/ascend-c/lib64\-lace# 验证编译成功ls-lhvector_add.so# 预期输出（示例）# -rw-r--r-- 1 root root 45K May 24 10:00 vector_add.so

代码讲解：

ascendc++：昇腾C++编译器，是gcc的昇腾版本
-I${ASCEND_HOME}/ascend-c/include：头文件目录
-L${ASCEND_HOME}/ascend-c/lib64：库文件目录
-lace：链接昇腾C库

⚠️ 踩坑预警：编译前要设置ASCEND_HOME环境变量，不然找不到头文件和库文件。

步骤3：调试Ascend C代码

代码编译成功了，第三步是调试。asc-tools提供了ascend-gdb调试器，是gdb的昇腾版本，支持NPU上的断点调试。

调试命令：

# 启动ascend-gdbascend-gdb ./vector_add_test# ascend-gdb命令（和gdb一样）(gdb)breakVectorAdd::Compute# 在Compute函数打断点(gdb)run# 运行程序(gdb)next# 单步执行(gdb)print element_count_# 打印变量值(gdb)info locals# 打印所有局部变量(gdb)print x_local.GetValue(0)# 打印Tensor值(gdb)continue# 继续执行(gdb)quit# 退出调试器

代码讲解：

ascend-gdb：昇腾GDB调试器，是gdb的昇腾版本
break：在指定位置打断点
run：运行程序
next：单步执行（不进入函数）
step：单步执行（进入函数）
print：打印变量值

⚠️ 踩坑预警：ascend-gdb不支持查看LocalTensor的完整内容，只能查看单个元素。

步骤4：验证Ascend C代码

代码调试通过了，第四步是验证。asc-tools提供了acl soot验证工具，可以在CPU上模拟运行Ascend C代码，不用真机就能验证逻辑正确性。

验证命令：

# 用acl soot验证VectorAdd算子acl soot--opvector_add.so\--input"x=[1,2,3,4,5]; y=[10,20,30,40,50]"\--expected"z=[11,22,33,44,55]"\--attr"element_count=5"# 预期输出（示例）# [PASS] VectorAdd op verification passed# Input x: [1, 2, 3, 4, 5]# Input y: [10, 20, 30, 40, 50]# Output z: [11, 22, 33, 44, 55]# Expected z: [11, 22, 33, 44, 55]# Match: True

代码讲解：

acl soot：昇腾算子验证工具，可以在CPU上模拟运行Ascend C代码
--op：算子动态库路径
--input：输入数据
--expected：期望输出
--attr：算子属性

⚠️ 踩坑预警：acl soot是模拟运行，有些硬件相关的操作（比如DMA）无法模拟，需要真机验证。

完整实战：写一个VectorAdd算子并验证

理论讲完了，来一个完整实战。一步步写、编译、调试、验证一个VectorAdd算子。

步骤1：创建项目目录

# 创建项目目录mkdir-p~/vector_add_project/srcmkdir-p~/vector_add_project/buildmkdir-p~/vector_add_project/testcd~/vector_add_project

步骤2：写Ascend C代码

// src/vector_add.cpp#include"ascend_c/ascend_c.h"usingnamespaceascend::c;classVectorAdd:publicKernelOperator{public:voidInit(int32_telement_count){element_count_=element_count;x_buffer_.Bind(this,"x");y_buffer_.Bind(this,"y");z_buffer_.Bind(this,"z");z_buffer_.SetShape({element_count_});}voidCompute(){autox_local=x_buffer_.GetLocal();autoy_local=y_buffer_.GetLocal();autoz_local=z_buffer_.GetLocal();for(inti=0;i<element_count_;i++){z_local.SetValue(i,x_local.GetValue(i)+y_local.GetValue(i));}z_buffer_.SyncToGlobal();}private:int32_telement_count_;InputBuffer<x_buffer_,Tensor>x_buffer_;InputBuffer<y_buffer_,Tensor>y_buffer_;OutputBuffer<z_buffer_,Tensor>z_buffer_;};REGISTER_OP("VectorAdd").Input(x).Input(y).Output(z).Attr(element_count,Int).SetKernelFunc([](constOpKernelInput&input,OpKernelOutput&output){VectorAdd op;op.Init(input.GetAttr<int32_t>("element_count"));op.Compute();return0;});

步骤3：写测试代码

# test/vector_add_test.pyimportnumpyasnpimportacl# 初始化ACLacl.init()# 分配设备acl.rt.set_device(0)# 准备输入数据x=np.array([1,2,3,4,5],dtype=np.float32)y=np.array([10,20,30,40,50],dtype=np.float32)# 分配设备内存ptr_x=acl.rt.malloc(x.nbytes,acl.RT_MEM_MALLOC_NORMAL_ONLY)ptr_y=acl.rt.malloc(y.nbytes,acl.RT_MEM_MALLOC_NORMAL_ONLY)ptr_z=acl.rt.malloc(x.nbytes,acl.RT_MEM_MALLOC_NORMAL_ONLY)# 拷贝输入数据到设备acl.rt.memcpy(ptr_x,x.nbytes,x.ctypes.data,x.nbytes,acl.RT_MEMCPY_HOST_TO_DEVICE)acl.rt.memcpy(ptr_y,y.nbytes,y.ctypes.data,y.nbytes,acl.RT_MEMCPY_HOST_TO_DEVICE)# 加载算子acl.op.load_operator("VectorAdd","./vector_add.so")# 创建算子描述符op_desc,ret=acl.op.create_op_desc("VectorAdd")acl.op.set_op_desc_input_ptr(op_desc,0,ptr_x,x.nbytes)acl.op.set_op_desc_input_ptr(op_desc,1,ptr_y,y.nbytes)acl.op.set_op_desc_output_ptr(op_desc,0,ptr_z,x.nbytes)acl.op.set_op_desc_attr_int(op_desc,"element_count",5)# 执行算子op_handle,ret=acl.op.create_op(op_desc)acl.op.execute(op_handle)acl.op.sync_op(op_handle)# 拷贝结果回主机result=np.empty(5,dtype=np.float32)acl.rt.memcpy(result.ctypes.data,result.nbytes,ptr_z,result.nbytes,acl.RT_MEMCPY_DEVICE_TO_HOST)print(f"x ={x}")print(f"y ={y}")print(f"z ={result}")print(f"期望: z = [11, 22, 33, 44, 55]")print(f"通过:{np.allclose(result,[11,22,33,44,55])}")# 释放资源acl.op.destroy_op(op_handle)acl.op.destroy_op_desc(op_desc)acl.rt.free(ptr_x)acl.rt.free(ptr_y)acl.rt.free(ptr_z)acl.rt.reset_device(0)acl.finalize()

步骤4：编译算子

cd~/vector_add_project/build# 编译VectorAdd算子ascendc++-o../vector_add.so../src/vector_add.cpp\-I${ASCEND_HOME}/ascend-c/include\-L${ASCEND_HOME}/ascend-c/lib64\-laceecho"编译完成"ls-lh../vector_add.so

步骤5：运行测试

cd~/vector_add_project# 运行测试python3 test/vector_add_test.py# 预期输出（示例）# x = [ 1. 2. 3. 4. 5.]# y = [10. 20. 30. 40. 50.]# z = [11. 22. 33. 44. 55.]# 期望: z = [11, 22, 33, 44, 55]# 通过: True

踩坑实录

用asc-tools的时候，踩过几个坑，分享出来。

坑1：ascendc++编译失败，找不到头文件

现象：运行ascendc++，报错说fatal error: ascend_c/ascend_c.h: No such file or directory。

原因：ASCEND_HOME环境变量没设置，或者设置错了。

解决：设置ASCEND_HOME环境变量。

# 设置ASCEND_HOMEexportASCEND_HOME=/usr/local/Ascend# 验证设置正确echo$ASCEND_HOMEls$ASCEND_HOME/ascend-c/include/ascend_c/ascend_c.h

坑2：ascend-gdb无法打断点

现象：运行ascend-gdb，打断点时报错说No symbol table loaded。

原因：编译时没加-g参数，生成调试信息。

解决：编译时加-g参数。

# 错误写法（没有调试信息）ascendc++-ovector_add.so vector_add.cpp...# 正确写法（有调试信息）ascendc++-g-ovector_add.so vector_add.cpp...

坑3：acl soot验证失败

现象：运行acl soot，报错说op verification failed。

原因：算子的输入输出格式和期望不一致。

解决：检查算子的输入输出格式，确保和测试代码一致。

# 查看算子的输入输出格式acl soot--opvector_add.so --dump-shape# 预期输出（示例）# Operator: VectorAdd# Input x: [N] (float32)# Input y: [N] (float32)# Output z: [N] (float32)# Attr element_count: int32