
ATVOSS 快速入门指南环境搭建、源码编译与算子验证全流程【免费下载链接】atvossATVOSSAscend C Templates for Vector Operator Subroutines是一套基于Ascend C开发的Vector算子库致力于为昇腾硬件上的Vector类融合算子提供极简、高效、高性能、高拓展的编程方式。项目地址: https://gitcode.com/cann/atvossATVOSSAscend C Templates for Vector Operator Subroutines是一套基于 Ascend C 开发的 Vector 算子模板库致力于为昇腾硬件上的 Vector 类融合算子提供极简、高效、高性能、高拓展的编程方式。本文以 docs/quick_start.md 为主线完整讲解从环境准备、CANN 包安装、环境验证、源码下载到 examples 编译执行、仿真验证及 UT/ST 测试的全流程并结合仓库内的 examples 源码与 scripts/build.sh 实现细节帮助你从零跑通第一个 ATVOSS 算子样例。一、认识 ATVOSSATVOSSAscend C Templates for Vector Operator Subroutines是一套基于 Ascend C 开发的 Vector 算子模板库通过模板化、表达式化的编程方式屏蔽底层 Vector 指令细节让开发者像写数学表达式一样定义算子计算逻辑如out in * scalar、out in2 * (in1 / sqrt(mean(in1*in1)))再由框架自动完成分块Tiling、分核Segment、缓冲区分配与调度。从源码结构看ATVOSS 的核心能力分为三层见 include/atvoss.h表达式层include/expression、include/operators提供Abs、Sqrt、ReduceSum、Broadcast、Cast等运算 API 与表达式变换、线性化能力构建层include/elewise/block/builder.h、include/elewise/kernel/builder.h提供BlockBuilder、KernelBuilder将 Compute 表达式编译为块级与核级算子适配层include/elewise/device/device_adapter.h提供DeviceAdapter对接 ACL 运行时完成 Host 侧调用。本文档重点聚焦“环境搭建 → 编译 → 运行 → 验证”的完整上手链路这也是在昇腾硬件上使用 ATVOSS 的第一步。二、环境准备环境搭建一般分为以下两种场景可以按需安装编译态仅编译不运行本项目只需安装前置依赖和 CANN toolkit 包。运行态运行本项目编译运行或纯运行除了安装前置依赖和 CANN toolkit 包还需安装驱动与固件、CANN ops 包。2.1 系统要求与依赖清单ATVOSS 支持源码编译进行源码编译前请确保如下基础依赖、NPU 驱动和固件已安装。安装依赖含版本要求依赖版本要求说明python 3.7.0建议 3.10构建与工具链脚本依赖gcc 7.3.0编译工具链cmake 3.16.0构建系统examples/CMakeLists.txt 中同样声明cmake_minimum_required(VERSION 3.16)pigz可选建议 2.4安装后可提升打包速度dos2unix-文本格式转换gawk-文本处理make-构建工具googletest仅执行 UT 时依赖建议 release-1.11.0单元测试框架对应 tests/ut 下的 host_ut 用例提示完整依赖的安装与验证方式可配合查看 docs/directory_structure.md 中的构建脚本说明。2.2 支持的产品与架构ATVOSS 当前支持的产品为Ascend 950PR / Ascend 950DT对应到编译层面构建脚本 scripts/build.sh 中-DSOC参数仅支持ascend950CMake 侧examples/CMakeLists.txt会将ascend950映射为 NPU 架构dav-3510其他 SOC 值会直接报错终止if(SOC STREQUAL ascend950) set(NPU_ARCH dav-3510) else() message(FATAL_ERROR SOC only supports ascend950, but get ${SOC}) endif()2.3 安装驱动与固件运行态依赖运行算子时必须安装驱动与固件若仅编译算子可跳过本操作。根据实际产品型号和环境架构从昇腾社区下载对应的Ascend-hdk-chip_type-npu-driver_version_linux-arch.run、Ascend-hdk-chip_type-npu-firmware_version.run包安装指导详见《CANN 软件安装指南》中“安装指南 安装NPU驱动和固件”。2.4 手动安装 CANN 包步骤 1下载软件包选择最新发布日期对应的目录根据实际产品型号和环境架构获取Ascend-cann-toolkit_${cann_version}_linux-${arch}.run。步骤 2安装软件包# 需要确保安装目录权限至少为755 # 确保安装包具有可执行权限 chmod x Ascend-cann-toolkit_${cann_version}_linux-${arch}.run # 安装命令 ./Ascend-cann-toolkit_${cann_version}_linux-${arch}.run --install --force --install-path${install_path}参数说明${cann_version}CANN 包版本号。${arch}CPU 架构如aarch64、x86_64。${install_path}指定安装路径默认安装在/usr/local/Ascend目录。三、环境验证安装完 CANN 包或进入 Docker 容器后需验证环境和驱动是否正常。检查 NPU 设备仿真执行可跳过此步骤# 运行npu-smi若能正常显示设备信息则驱动正常 npu-smi info检查 CANN 安装# 查看CANN Toolkit版本信息非root用户将/usr/local替换为${HOME} cat /usr/local/Ascend/cann/opp/version.info四、环境变量配置按需选择合适的命令使环境变量生效# 默认路径安装以root用户为例非root用户将/usr/local替换为${HOME} source /usr/local/Ascend/cann/set_env.sh # 指定路径安装 source ${install_path}/cann/set_env.sh需要特别注意的是scripts/build.sh在构建前会强制校验环境变量ASCEND_HOME_PATH是否已设置scripts/build.shif [[ ! -v ASCEND_HOME_PATH ]]; then echo -e ${ERROR}ASCEND_HOME_PATH environment variable is not set!${NC} exit 1 fi因此source set_env.sh之后请确认ASCEND_HOME_PATH已经指向 CANN 安装目录通常为/usr/local/Ascend/ascend-toolkit/latest否则构建脚本会在第一步就退出。五、源码下载git clone -b master gitgitcode.com:cann/atvoss.git[!NOTE] 注意 gitcode 平台在使用 SSH 协议时请在本地生成 SSH 公钥进行克隆、推送等操作。六、编译执行与算子验证开发者调用 ATVOSS 实现自定义算子开发后可通过单算子调用的方式验证算子功能。仓库提供部分算子实现及其调用样例具体参考 examples 目录下的样例。6.1 样例一览样例名描述算子调用方式abs展示最基础的表达式开发方式Kernel 直调muls展示涉及多 DAG 特性的算子开发方式Kernel 直调rms_norm展示表达式级联的算子开发方式Kernel 直调以最基础的 abs 为例其 Compute 表达式仅一行examples/abs/abs.cppstruct AbsCompute { template template typename class Tensor __host_aicore__ constexpr auto Compute() const { auto in Atvoss::PlaceHolder1, TensorDtype, Atvoss::ParamUsage::IN(); auto out Atvoss::PlaceHolder2, TensorDtype, Atvoss::ParamUsage::OUT(); return (out Abs(in)); }; };而 rms_norm 则展示了多算子表达式级联的写法examples/rms_norm/rms_norm.cppauto in1 Atvoss::PlaceHolder1, TensorDtypeV1, Atvoss::ParamUsage::IN(); auto in2 Atvoss::PlaceHolder2, TensorDtypeV2, Atvoss::ParamUsage::IN(); auto out Atvoss::PlaceHolder3, TensorDtypeV3, Atvoss::ParamUsage::OUT(); auto _1 Atvoss::ReduceSumAtvoss::Pattern::AR(in1 * in1); auto _2 Atvoss::BroadcastAtvoss::Pattern::AB(_1); auto _3 in1 / Atvoss::Sqrt(Atvoss::DivsWIDTH(_2)); return out in2 * _3;6.2 编译 exampleATVOSS 仓库提供一键式编译 examples 的能力可以指定单个 example 编译例如编译 examples/rms_norm 目录里的用例bash scripts/build.sh -DSOCascend950 rms_norm该命令实际走的是 scripts/build.sh 的 legacy 模式-DSOCascend950作为 CMake 选项透传CMAKE_OPTIONSrms_norm作为直接构建目标。脚本会先检查ASCEND_HOME_PATH然后在仓库根目录创建build/与output/执行cmake -S . -B build -DCMAKE_BUILD_TYPERelease -DCMAKE_INSTALL_PREFIXoutput完成配置若build/CMakeCache.txt已存在则跳过配置再通过cmake --build build --target rms_norm -j编译并安装到output/bin。提示构建脚本还支持显式模式写法如bash scripts/build.sh -DSOCascend950 --example rms_norm不指定名字时默认构建全部 examples目标atvoss_examples。也可以先执行bash scripts/build.sh查看帮助与全部选项。6.3 单样例执行依赖 Device 环境编译完成后会生成output/bin/rms_norm可执行文件./output/bin/rms_norm --shape512,3以 rms_norm 样例为例其 Host 侧流程见 examples/rms_norm/rms_norm.cpp包含标准的 ACL 调用序列aclInit→aclrtSetDevice→aclrtCreateContext→aclrtCreateStream→aclrtMalloc分配设备内存 →aclrtMemcpy拷贝输入 → 构造Atvoss::Tensor与Atvoss::ArgumentsBuilder→DeviceOp.Run(arguments, stream)执行算子 →aclrtSynchronizeStream同步 → 拷回结果并调用VerifyResults做精度校验。可执行文件支持的命令行参数通过 examples/common/command_line.h 解析--shapeM,N,...Tensor 各维度大小必填如--shape512,3abs 样例最多支持 8 维rms_norm 样例限制最多 2 维且维度值不能为负--help/-h打印使用说明。精度校验依赖 examples/common/example_common.h 中定义的容差相对容差REL_TOL 1e-3f绝对容差ABS_TOL 1e-5f逐元素比较 golden 值与实际输出。6.4 仿真执行不依赖 Device 环境利用 cannsim 实现仿真运行将上述执行脚本写到自建的 Shell 脚本如run.sh中# run.sh ./output/bin/rms_norm --shape512,3给自建的 run.sh 增加可执行权限然后使用仿真命令 cannsim 执行chmod x run.sh cannsim record ./run.sh -s Ascend950 --gen-report执行完成后会在当前目录生成一个cannsim_xxx的结果文件夹。说明-s Ascend950指定仿真芯片型号与前面-DSOCascend950对应仿真模式不需要安装 NPU 驱动与固件也无需真实 Device适合在纯编译/开发环境中提前验证算子功能。构建脚本内部也使用相同的 cannsim 方式对样例与 ST 用例做仿真回归scripts/build.sh并检查日志中是否包含Accuracy verification passed作为通过标志。6.5 判断运行结果若提示如下信息则说明算子运行成功精度校验通过Accuracy verification passed.更详细的用例执行流程请参阅 examples/README.md。七、UT 测试可选UT 测试面向 Host 侧单元测试tests/ut/host 下的用例如 test_arguments、test_expr_linearizer、test_utility 等以及 tests/ut/builtin_tiling、tests/ut/builtin_kernel 中的内置能力测试。该环节依赖 googletest建议 release-1.11.0。bash scripts/build.sh -DSOCascend950 --host_ut该命令通过 scripts/build.sh 的--host_ut模式构建 host_ut 目标编译完成会直接运行 host_ut 并输出 UT 执行结果脚本在构建安装后会自动执行build/tests/ut/host/target可执行文件。八、ST 测试可选ST 测试系统级测试的用例位于 tests/st 目录例如test_block_cast12、test_tile_rms_norm_14、test_compute_buffer_reuse等覆盖分块 Cast、级联表达式、缓冲区复用等场景。1. 编译 stbash scripts/build.sh -DSOCascend950 --st ${st_case_name}其中${st_case_name}对应 tests/st 下的用例名不指定时默认构建st目标构建脚本会仿真执行预置的 ST 用例列表并检查Accuracy verification passed。2. 执行 stcannsim record ./output/bin/${st_case_name} -s Ascend950 --gen-report九、继续深入相关文档与源码入口完成上述全流程后可以继续深入以下文档与源码docs/summary.md项目整体介绍docs/directory_structure.md目录结构说明含 scripts/ 构建脚本目录docs/tutorials/developer_guide.md以 muls 为例的详细算子开发流程Compute 定义、策略配置、CMake 编写、编译执行docs/api/README.mdAPI 文档运算 API、参数构建器等examples/README.md样例介绍与 PyTorch 框架对接说明examples/python_extensioninclude/atvoss.h 及 include/elewise、include/operators 下的头文件模板库核心实现scripts/build.sh一键构建脚本的完整实现【免费下载链接】atvossATVOSSAscend C Templates for Vector Operator Subroutines是一套基于Ascend C开发的Vector算子库致力于为昇腾硬件上的Vector类融合算子提供极简、高效、高性能、高拓展的编程方式。项目地址: https://gitcode.com/cann/atvoss创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考