企业官网建设流程全解析

ATVOSS 快速入门指南：环境搭建、源码编译与算子验证全流程

【免费下载链接】atvossATVOSS（Ascend C Templates for Vector Operator Subroutines）是一套基于Ascend C开发的Vector算子库，致力于为昇腾硬件上的Vector类融合算子提供极简、高效、高性能、高拓展的编程方式。项目地址: https://gitcode.com/cann/atvoss

ATVOSS（Ascend C Templates for Vector Operator Subroutines）是一套基于 Ascend C 开发的 Vector 算子模板库，致力于为昇腾硬件上的 Vector 类融合算子提供极简、高效、高性能、高拓展的编程方式。本文以 docs/quick_start.md 为主线，完整讲解从环境准备、CANN 包安装、环境验证、源码下载到 examples 编译执行、仿真验证及 UT/ST 测试的全流程，并结合仓库内的 examples 源码与 scripts/build.sh 实现细节，帮助你从零跑通第一个 ATVOSS 算子样例。

一、认识 ATVOSS

ATVOSS（Ascend 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 驱动和固件已安装。

安装依赖（含版本要求）：

提示：完整依赖的安装与验证方式，可配合查看 docs/directory_structure.md 中的构建脚本说明。

2.2 支持的产品与架构

ATVOSS 当前支持的产品为：

• Ascend 950PR / Ascend 950DT

对应到编译层面，构建脚本 scripts/build.sh 中-DSOC参数仅支持ascend950，CMake 侧（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.sh）：

if [[ ! -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 git@gitcode.com:cann/atvoss.git

[!NOTE] 注意 gitcode 平台在使用 SSH 协议时，请在本地生成 SSH 公钥进行克隆、推送等操作。

六、编译执行与算子验证

开发者调用 ATVOSS 实现自定义算子开发后，可通过单算子调用的方式验证算子功能。仓库提供部分算子实现及其调用样例，具体参考 examples 目录下的样例。

6.1 样例一览

以最基础的 abs 为例，其 Compute 表达式仅一行（examples/abs/abs.cpp）：

struct AbsCompute { template <template <typename> class Tensor> __host_aicore__ constexpr auto Compute() const { auto in = Atvoss::PlaceHolder<1, Tensor<Dtype>, Atvoss::ParamUsage::IN>(); auto out = Atvoss::PlaceHolder<2, Tensor<Dtype>, Atvoss::ParamUsage::OUT>(); return (out = Abs(in)); }; };

而 rms_norm 则展示了多算子表达式级联的写法（examples/rms_norm/rms_norm.cpp）：

auto in1 = Atvoss::PlaceHolder<1, Tensor<DtypeV1>, Atvoss::ParamUsage::IN>(); auto in2 = Atvoss::PlaceHolder<2, Tensor<DtypeV2>, Atvoss::ParamUsage::IN>(); auto out = Atvoss::PlaceHolder<3, Tensor<DtypeV3>, Atvoss::ParamUsage::OUT>(); auto _1 = Atvoss::ReduceSum<Atvoss::Pattern::AR>(in1 * in1); auto _2 = Atvoss::Broadcast<Atvoss::Pattern::AB>(_1); auto _3 = in1 / Atvoss::Sqrt(Atvoss::Divs<WIDTH>(_2)); return out = in2 * _3;

6.2 编译 example

ATVOSS 仓库提供一键式编译 examples 的能力，可以指定单个 example 编译（例如，编译 examples/rms_norm 目录里的用例）：

bash scripts/build.sh -DSOC=ascend950 rms_norm

该命令实际走的是 scripts/build.sh 的 legacy 模式：-DSOC=ascend950作为 CMake 选项透传（CMAKE_OPTIONS），rms_norm作为直接构建目标。脚本会先检查ASCEND_HOME_PATH，然后在仓库根目录创建build/与output/，执行cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=output完成配置（若build/CMakeCache.txt已存在则跳过配置），再通过cmake --build build --target rms_norm -j编译并安装到output/bin。

提示：构建脚本还支持显式模式写法，如bash scripts/build.sh -DSOC=ascend950 --example rms_norm，不指定名字时默认构建全部 examples（目标atvoss_examples）。也可以先执行bash scripts/build.sh查看帮助与全部选项。

6.3 单样例执行（依赖 Device 环境）

编译完成后会生成output/bin/rms_norm可执行文件：

./output/bin/rms_norm --shape=512,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 解析）：

• --shape=M,N,...：Tensor 各维度大小（必填），如--shape=512,3；abs 样例最多支持 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 --shape=512,3

给自建的 run.sh 增加可执行权限，然后使用仿真命令 cannsim 执行：

chmod +x run.sh cannsim record ./run.sh -s Ascend950 --gen-report

执行完成后会在当前目录生成一个cannsim_xxx的结果文件夹。

说明：-s Ascend950指定仿真芯片型号（与前面-DSOC=ascend950对应）；仿真模式不需要安装 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 -DSOC=ascend950 --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. 编译 st

bash scripts/build.sh -DSOC=ascend950 --st ${st_case_name}

其中${st_case_name}对应 tests/st 下的用例名（不指定时默认构建st目标，构建脚本会仿真执行预置的 ST 用例列表并检查Accuracy verification passed）。

2. 执行 st

cannsim 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.md：API 文档（运算 API、参数构建器等）
• examples/README.md：样例介绍与 PyTorch 框架对接说明（examples/python_extension）
• include/atvoss.h 及 include/elewise、include/operators 下的头文件：模板库核心实现
• scripts/build.sh：一键构建脚本的完整实现

【免费下载链接】atvossATVOSS（Ascend C Templates for Vector Operator Subroutines）是一套基于Ascend C开发的Vector算子库，致力于为昇腾硬件上的Vector类融合算子提供极简、高效、高性能、高拓展的编程方式。项目地址: https://gitcode.com/cann/atvoss