从零到一手把手教你用AscendCL在Ubuntu 20.04上跑通第一个AI推理程序附完整CMake配置作为一个刚接触昇腾生态的开发者最迫切的需求往往不是理解复杂的架构原理而是尽快在本地环境跑通第一个可运行的AI推理程序。本文将带你用最直接的方式在Ubuntu 20.04系统上完成从环境配置到程序运行的完整流程避开那些官方文档没明确说明的坑。1. 环境准备避开90%新手会踩的安装陷阱1.1 硬件与系统要求检查在开始之前请确保你的开发环境满足以下最低要求硬件搭载昇腾310/910处理器的Atlas系列设备如Atlas 300加速卡或Ascend开发板操作系统Ubuntu 20.04 LTS推荐使用纯净安装版本内存至少16GB32GB更佳存储空间系统盘剩余空间≥50GB提示运行lspci | grep -i ascend可以检查昇腾设备是否被系统识别。如果没有任何输出请先确认硬件连接和驱动安装。1.2 CANN工具包安装实战华为的CANNCompute Architecture for Neural Networks是昇腾AI的基础软件栈我们需要先安装它# 下载CANN工具包以6.0.RC1版本为例 wget https://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/6.0.RC1/ubuntu20.04/aarch64/Ascend-cann-toolkit_6.0.RC1_linux-aarch64.run # 添加执行权限 chmod x Ascend-cann-toolkit_6.0.RC1_linux-aarch64.run # 执行安装需要root权限 sudo ./Ascend-cann-toolkit_6.0.RC1_linux-aarch64.run --install安装过程中常见的三个问题及解决方案依赖缺失错误运行sudo apt-get install -y gcc g make cmake unzip python3补全基础依赖权限不足确保当前用户属于HwHiAiUser组安装程序会自动创建版本冲突如果之前安装过旧版务必先运行sudo /usr/local/Ascend/uninstall.sh彻底卸载1.3 环境变量配置技巧安装完成后需要配置环境变量使其生效。建议将这些配置加入你的~/.bashrc文件# 设置CANN基础路径 export ASCEND_HOME/usr/local/Ascend/ascend-toolkit/latest # 添加库文件路径 export LD_LIBRARY_PATH${ASCEND_HOME}/lib64:$LD_LIBRARY_PATH # 包含头文件路径 export C_INCLUDE_PATH${ASCEND_HOME}/include:$C_INCLUDE_PATH export CPLUS_INCLUDE_PATH${ASCEND_HOME}/include:$CPLUS_INCLUDE_PATH # 工具链路径 export PATH${ASCEND_HOME}/bin:$PATH执行source ~/.bashrc使配置立即生效然后运行ascend-dmi -i验证安装是否成功。你应该能看到类似下面的输出Device Type: Atlas 300I Pro AI Core Count: 1 Firmware Version: 1.76.22.5.2202. 创建你的第一个AscendCL项目2.1 项目结构设计我们采用以下目录结构来组织代码这是经过多个项目验证的高效布局ascend_hello_world/ ├── CMakeLists.txt # 项目构建配置 ├── include/ # 头文件目录 │ └── utils.h # 辅助函数声明 ├── src/ # 源代码目录 │ ├── main.cpp # 主程序入口 │ └── utils.cpp # 辅助函数实现 └── build/ # 构建目录后续生成2.2 编写最小化AscendCL程序在src/main.cpp中我们创建一个最基本的AscendCL初始化示例#include iostream #include acl/acl.h // AscendCL主头文件 #include utils.h // 自定义工具函数 int main() { std::cout AscendCL Hello World std::endl; // 1. 初始化AscendCL aclError ret aclInit(nullptr); if (ret ! ACL_SUCCESS) { std::cerr aclInit failed: ret std::endl; return -1; } // 2. 设置运行设备默认设备0 ret aclrtSetDevice(0); if (ret ! ACL_SUCCESS) { std::cerr aclrtSetDevice failed: ret std::endl; aclFinalize(); return -1; } // 3. 打印运行模式Host/Device aclrtRunMode runMode; aclrtGetRunMode(runMode); std::cout Current run mode: (runMode ACL_DEVICE ? Device : Host) std::endl; // 4. 演示基础内存操作 demoMemoryOperation(); // 5. 释放资源 aclrtResetDevice(0); aclFinalize(); std::cout Program executed successfully! std::endl; return 0; }对应的src/utils.cpp实现了一个简单的内存操作演示#include utils.h #include cstring void demoMemoryOperation() { const size_t size 256; // 主机内存申请 float *hostBuf nullptr; aclrtMallocHost((void**)hostBuf, size * sizeof(float)); // 设备内存申请 float *deviceBuf nullptr; aclrtMalloc((void**)deviceBuf, size * sizeof(float), ACL_MEM_MALLOC_NORMAL_ONLY); // 初始化主机数据 for (int i 0; i size; i) { hostBuf[i] i * 1.0f; } // 主机到设备内存拷贝 aclrtMemcpy(deviceBuf, size * sizeof(float), hostBuf, size * sizeof(float), ACL_MEMCPY_HOST_TO_DEVICE); std::cout Memory operation demo completed! std::endl; // 释放资源 aclrtFree(deviceBuf); aclrtFreeHost(hostBuf); }2.3 关键CMake配置解析CMakeLists.txt是整个项目的构建核心以下是针对AscendCL优化的配置cmake_minimum_required(VERSION 3.12) project(AscendHelloWorld LANGUAGES CXX) # 设置C标准 set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 查找AscendCL find_path(ACL_INCLUDE_DIR NAMES acl/acl.h PATHS /usr/local/Ascend/ascend-toolkit/latest/include NO_DEFAULT_PATH ) find_library(ACL_LIBRARY NAMES ascendcl PATHS /usr/local/Ascend/ascend-toolkit/latest/lib64 NO_DEFAULT_PATH ) if (NOT ACL_INCLUDE_DIR OR NOT ACL_LIBRARY) message(FATAL_ERROR AscendCL not found! Please check CANN installation.) endif() # 包含目录 include_directories( ${ACL_INCLUDE_DIR} ${PROJECT_SOURCE_DIR}/include ) # 生成可执行文件 add_executable(ascend_hello_world src/main.cpp src/utils.cpp ) # 链接库 target_link_libraries(ascend_hello_world ${ACL_LIBRARY} stdc ) # 编译选项 target_compile_options(ascend_hello_world PRIVATE -Wall -Wextra -O2 )这个配置有几个关键优化点严格路径检查使用NO_DEFAULT_PATH避免系统误找其他路径的同名文件显式错误提示当AscendCL未找到时给出明确指导而非晦涩的链接错误模块化组织为后续添加更多源文件预留了清晰的结构3. 构建与调试实战3.1 编译项目在项目根目录执行以下命令# 创建构建目录 mkdir -p build cd build # 生成Makefile使用Debug模式便于调试 cmake -DCMAKE_BUILD_TYPEDebug .. # 开始编译使用并行加速 make -j$(nproc)成功编译后你会在build目录下看到生成的ascend_hello_world可执行文件。3.2 常见编译错误解决错误类型典型表现解决方案头文件缺失fatal error: acl/acl.h: No such file or directory检查ACL_INCLUDE_DIR路径是否正确确认CANN安装完整链接错误undefined reference toaclInit确保ACL_LIBRARY路径正确检查target_link_libraries是否包含ascendcl权限问题error while loading shared libraries: libascendcl.so: cannot open shared object file运行sudo ldconfig更新库缓存或确认LD_LIBRARY_PATH包含正确路径3.3 运行与验证执行程序并观察输出./ascend_hello_world预期应该看到类似以下输出 AscendCL Hello World Current run mode: Device Memory operation demo completed! Program executed successfully!如果遇到运行时错误可以使用ASCEND_GLOBAL_LOG_LEVEL3环境变量开启详细日志ASCEND_GLOBAL_LOG_LEVEL3 ./ascend_hello_world4. 进阶添加简单矩阵计算现在我们已经搭建好了基础框架让我们扩展一个实际的AI计算功能——矩阵乘法。4.1 添加矩阵乘法算子在include/utils.h中添加声明// 矩阵乘法MxK * KxN MxN void matrixMultiply(const float* A, const float* B, float* C, int M, int N, int K);对应的实现src/utils.cppvoid matrixMultiply(const float* A, const float* B, float* C, int M, int N, int K) { // 创建算子描述 aclopAttr* attr aclopCreateAttr(); // 设置矩阵维度属性 int64_t dimA[2] {M, K}; int64_t dimB[2] {K, N}; int64_t dimC[2] {M, N}; // 创建输入输出张量描述 aclTensorDesc* inputDescA aclCreateTensorDesc( ACL_FLOAT, 2, dimA, ACL_FORMAT_ND); aclTensorDesc* inputDescB aclCreateTensorDesc( ACL_FLOAT, 2, dimB, ACL_FORMAT_ND); aclTensorDesc* outputDesc aclCreateTensorDesc( ACL_FLOAT, 2, dimC, ACL_FORMAT_ND); // 执行矩阵乘法 aclrtStream stream nullptr; aclrtCreateStream(stream); aclError ret aclopMatMul( inputDescA, inputDescB, outputDesc, C, A, B, attr, stream); if (ret ! ACL_SUCCESS) { std::cerr MatMul failed: ret std::endl; } // 同步等待计算完成 aclrtSynchronizeStream(stream); // 释放资源 aclDestroyTensorDesc(inputDescA); aclDestroyTensorDesc(inputDescB); aclDestroyTensorDesc(outputDesc); aclopDestroyAttr(attr); aclrtDestroyStream(stream); }4.2 更新CMake配置为了支持更复杂的算子操作我们需要添加额外的依赖库# 在原有find_library后添加 find_library(ACL_OP_LIBRARY NAMES acl_op PATHS /usr/local/Ascend/ascend-toolkit/latest/lib64 NO_DEFAULT_PATH ) # 更新target_link_libraries target_link_libraries(ascend_hello_world ${ACL_LIBRARY} ${ACL_OP_LIBRARY} stdc )4.3 测试矩阵乘法在main.cpp中添加测试代码// 在demoMemoryOperation后添加 std::cout \nTesting Matrix Multiplication... std::endl; // 准备测试数据2x3 和 3x2 矩阵 float A[6] {1,2,3,4,5,6}; // 2x3 float B[6] {1,0,0,1,1,0}; // 3x2 float C[4] {0}; // 2x2结果 matrixMultiply(A, B, C, 2, 2, 3); std::cout Result Matrix:\n C[0] C[1] \n C[2] C[3] std::endl;重新编译运行后你应该能看到正确的矩阵乘法结果Testing Matrix Multiplication... Result Matrix: 4 1 10 4
从零到一：手把手教你用AscendCL在Ubuntu 20.04上跑通第一个AI推理程序（附完整CMake配置）
发布时间：2026/5/27 20:49:59
从零到一手把手教你用AscendCL在Ubuntu 20.04上跑通第一个AI推理程序附完整CMake配置作为一个刚接触昇腾生态的开发者最迫切的需求往往不是理解复杂的架构原理而是尽快在本地环境跑通第一个可运行的AI推理程序。本文将带你用最直接的方式在Ubuntu 20.04系统上完成从环境配置到程序运行的完整流程避开那些官方文档没明确说明的坑。1. 环境准备避开90%新手会踩的安装陷阱1.1 硬件与系统要求检查在开始之前请确保你的开发环境满足以下最低要求硬件搭载昇腾310/910处理器的Atlas系列设备如Atlas 300加速卡或Ascend开发板操作系统Ubuntu 20.04 LTS推荐使用纯净安装版本内存至少16GB32GB更佳存储空间系统盘剩余空间≥50GB提示运行lspci | grep -i ascend可以检查昇腾设备是否被系统识别。如果没有任何输出请先确认硬件连接和驱动安装。1.2 CANN工具包安装实战华为的CANNCompute Architecture for Neural Networks是昇腾AI的基础软件栈我们需要先安装它# 下载CANN工具包以6.0.RC1版本为例 wget https://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/6.0.RC1/ubuntu20.04/aarch64/Ascend-cann-toolkit_6.0.RC1_linux-aarch64.run # 添加执行权限 chmod x Ascend-cann-toolkit_6.0.RC1_linux-aarch64.run # 执行安装需要root权限 sudo ./Ascend-cann-toolkit_6.0.RC1_linux-aarch64.run --install安装过程中常见的三个问题及解决方案依赖缺失错误运行sudo apt-get install -y gcc g make cmake unzip python3补全基础依赖权限不足确保当前用户属于HwHiAiUser组安装程序会自动创建版本冲突如果之前安装过旧版务必先运行sudo /usr/local/Ascend/uninstall.sh彻底卸载1.3 环境变量配置技巧安装完成后需要配置环境变量使其生效。建议将这些配置加入你的~/.bashrc文件# 设置CANN基础路径 export ASCEND_HOME/usr/local/Ascend/ascend-toolkit/latest # 添加库文件路径 export LD_LIBRARY_PATH${ASCEND_HOME}/lib64:$LD_LIBRARY_PATH # 包含头文件路径 export C_INCLUDE_PATH${ASCEND_HOME}/include:$C_INCLUDE_PATH export CPLUS_INCLUDE_PATH${ASCEND_HOME}/include:$CPLUS_INCLUDE_PATH # 工具链路径 export PATH${ASCEND_HOME}/bin:$PATH执行source ~/.bashrc使配置立即生效然后运行ascend-dmi -i验证安装是否成功。你应该能看到类似下面的输出Device Type: Atlas 300I Pro AI Core Count: 1 Firmware Version: 1.76.22.5.2202. 创建你的第一个AscendCL项目2.1 项目结构设计我们采用以下目录结构来组织代码这是经过多个项目验证的高效布局ascend_hello_world/ ├── CMakeLists.txt # 项目构建配置 ├── include/ # 头文件目录 │ └── utils.h # 辅助函数声明 ├── src/ # 源代码目录 │ ├── main.cpp # 主程序入口 │ └── utils.cpp # 辅助函数实现 └── build/ # 构建目录后续生成2.2 编写最小化AscendCL程序在src/main.cpp中我们创建一个最基本的AscendCL初始化示例#include iostream #include acl/acl.h // AscendCL主头文件 #include utils.h // 自定义工具函数 int main() { std::cout AscendCL Hello World std::endl; // 1. 初始化AscendCL aclError ret aclInit(nullptr); if (ret ! ACL_SUCCESS) { std::cerr aclInit failed: ret std::endl; return -1; } // 2. 设置运行设备默认设备0 ret aclrtSetDevice(0); if (ret ! ACL_SUCCESS) { std::cerr aclrtSetDevice failed: ret std::endl; aclFinalize(); return -1; } // 3. 打印运行模式Host/Device aclrtRunMode runMode; aclrtGetRunMode(runMode); std::cout Current run mode: (runMode ACL_DEVICE ? Device : Host) std::endl; // 4. 演示基础内存操作 demoMemoryOperation(); // 5. 释放资源 aclrtResetDevice(0); aclFinalize(); std::cout Program executed successfully! std::endl; return 0; }对应的src/utils.cpp实现了一个简单的内存操作演示#include utils.h #include cstring void demoMemoryOperation() { const size_t size 256; // 主机内存申请 float *hostBuf nullptr; aclrtMallocHost((void**)hostBuf, size * sizeof(float)); // 设备内存申请 float *deviceBuf nullptr; aclrtMalloc((void**)deviceBuf, size * sizeof(float), ACL_MEM_MALLOC_NORMAL_ONLY); // 初始化主机数据 for (int i 0; i size; i) { hostBuf[i] i * 1.0f; } // 主机到设备内存拷贝 aclrtMemcpy(deviceBuf, size * sizeof(float), hostBuf, size * sizeof(float), ACL_MEMCPY_HOST_TO_DEVICE); std::cout Memory operation demo completed! std::endl; // 释放资源 aclrtFree(deviceBuf); aclrtFreeHost(hostBuf); }2.3 关键CMake配置解析CMakeLists.txt是整个项目的构建核心以下是针对AscendCL优化的配置cmake_minimum_required(VERSION 3.12) project(AscendHelloWorld LANGUAGES CXX) # 设置C标准 set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 查找AscendCL find_path(ACL_INCLUDE_DIR NAMES acl/acl.h PATHS /usr/local/Ascend/ascend-toolkit/latest/include NO_DEFAULT_PATH ) find_library(ACL_LIBRARY NAMES ascendcl PATHS /usr/local/Ascend/ascend-toolkit/latest/lib64 NO_DEFAULT_PATH ) if (NOT ACL_INCLUDE_DIR OR NOT ACL_LIBRARY) message(FATAL_ERROR AscendCL not found! Please check CANN installation.) endif() # 包含目录 include_directories( ${ACL_INCLUDE_DIR} ${PROJECT_SOURCE_DIR}/include ) # 生成可执行文件 add_executable(ascend_hello_world src/main.cpp src/utils.cpp ) # 链接库 target_link_libraries(ascend_hello_world ${ACL_LIBRARY} stdc ) # 编译选项 target_compile_options(ascend_hello_world PRIVATE -Wall -Wextra -O2 )这个配置有几个关键优化点严格路径检查使用NO_DEFAULT_PATH避免系统误找其他路径的同名文件显式错误提示当AscendCL未找到时给出明确指导而非晦涩的链接错误模块化组织为后续添加更多源文件预留了清晰的结构3. 构建与调试实战3.1 编译项目在项目根目录执行以下命令# 创建构建目录 mkdir -p build cd build # 生成Makefile使用Debug模式便于调试 cmake -DCMAKE_BUILD_TYPEDebug .. # 开始编译使用并行加速 make -j$(nproc)成功编译后你会在build目录下看到生成的ascend_hello_world可执行文件。3.2 常见编译错误解决错误类型典型表现解决方案头文件缺失fatal error: acl/acl.h: No such file or directory检查ACL_INCLUDE_DIR路径是否正确确认CANN安装完整链接错误undefined reference toaclInit确保ACL_LIBRARY路径正确检查target_link_libraries是否包含ascendcl权限问题error while loading shared libraries: libascendcl.so: cannot open shared object file运行sudo ldconfig更新库缓存或确认LD_LIBRARY_PATH包含正确路径3.3 运行与验证执行程序并观察输出./ascend_hello_world预期应该看到类似以下输出 AscendCL Hello World Current run mode: Device Memory operation demo completed! Program executed successfully!如果遇到运行时错误可以使用ASCEND_GLOBAL_LOG_LEVEL3环境变量开启详细日志ASCEND_GLOBAL_LOG_LEVEL3 ./ascend_hello_world4. 进阶添加简单矩阵计算现在我们已经搭建好了基础框架让我们扩展一个实际的AI计算功能——矩阵乘法。4.1 添加矩阵乘法算子在include/utils.h中添加声明// 矩阵乘法MxK * KxN MxN void matrixMultiply(const float* A, const float* B, float* C, int M, int N, int K);对应的实现src/utils.cppvoid matrixMultiply(const float* A, const float* B, float* C, int M, int N, int K) { // 创建算子描述 aclopAttr* attr aclopCreateAttr(); // 设置矩阵维度属性 int64_t dimA[2] {M, K}; int64_t dimB[2] {K, N}; int64_t dimC[2] {M, N}; // 创建输入输出张量描述 aclTensorDesc* inputDescA aclCreateTensorDesc( ACL_FLOAT, 2, dimA, ACL_FORMAT_ND); aclTensorDesc* inputDescB aclCreateTensorDesc( ACL_FLOAT, 2, dimB, ACL_FORMAT_ND); aclTensorDesc* outputDesc aclCreateTensorDesc( ACL_FLOAT, 2, dimC, ACL_FORMAT_ND); // 执行矩阵乘法 aclrtStream stream nullptr; aclrtCreateStream(stream); aclError ret aclopMatMul( inputDescA, inputDescB, outputDesc, C, A, B, attr, stream); if (ret ! ACL_SUCCESS) { std::cerr MatMul failed: ret std::endl; } // 同步等待计算完成 aclrtSynchronizeStream(stream); // 释放资源 aclDestroyTensorDesc(inputDescA); aclDestroyTensorDesc(inputDescB); aclDestroyTensorDesc(outputDesc); aclopDestroyAttr(attr); aclrtDestroyStream(stream); }4.2 更新CMake配置为了支持更复杂的算子操作我们需要添加额外的依赖库# 在原有find_library后添加 find_library(ACL_OP_LIBRARY NAMES acl_op PATHS /usr/local/Ascend/ascend-toolkit/latest/lib64 NO_DEFAULT_PATH ) # 更新target_link_libraries target_link_libraries(ascend_hello_world ${ACL_LIBRARY} ${ACL_OP_LIBRARY} stdc )4.3 测试矩阵乘法在main.cpp中添加测试代码// 在demoMemoryOperation后添加 std::cout \nTesting Matrix Multiplication... std::endl; // 准备测试数据2x3 和 3x2 矩阵 float A[6] {1,2,3,4,5,6}; // 2x3 float B[6] {1,0,0,1,1,0}; // 3x2 float C[4] {0}; // 2x2结果 matrixMultiply(A, B, C, 2, 2, 3); std::cout Result Matrix:\n C[0] C[1] \n C[2] C[3] std::endl;重新编译运行后你应该能看到正确的矩阵乘法结果Testing Matrix Multiplication... Result Matrix: 4 1 10 4
