asc-devkit Where 高阶 API 条件选择算子样例:从 Kernel 实现到编译运行全解析

原创2026-10-14 13:21:322,187 阅读
文章标签:人工智能深度学习高性能计算CANN

asc-devkit Where 高阶 API 条件选择算子样例:从 Kernel 实现到编译运行全解析

本文围绕 asc-devkit 仓库中基于 SIMD(向量)编程模型实现的 Where 高阶 API 样例(examples/01_simd_cpp_api/04_advanced_api/10_math/where)展开,系统讲解"根据条件从两个源操作数中选择元素"这一典型条件选择算子的完整落地路径:从样例规格、Kernel 源码结构、Where API 的函数原型与底层指令级实现,到数据生成、编译运行(NPU/CPU 调试/NPU 仿真三种模式)与精度验证。读者学完后,既能直接复现该样例的编译与运行,也能掌握 Where API 张量/标量四种混合调用模式以及其背后 Reg::Select 指令级选择原理,为编写同类高阶 API 算子提供可参考的工程范式。

样例概述:功能、计算公式与规格

该样例基于 Where 高阶 API 实现条件选择功能:根据指定的条件(condition),从两个源操作数(src0、src1)中选择元素,生成目标操作数(dst)。两个源操作数均可以是 LocalTensor 或标量,即支持张量与标量混合模式,这也是本样例区别于基础向量 API 的核心亮点。

计算公式如下:

dst_i = src0_i,  if condition_i 为真(非 0)
dst_i = src1_i,  otherwise(condition_i 为 0)

样例规格(对应 README.md 中的样例规格表):

项 说明
样例类型(OpType) where
样例输入 src0 shape [1, 32],数据类型 float,格式 ND
样例输入 src1 shape [1, 32],数据类型 float,格式 ND
样例输入 condition shape [1, 32],数据类型 bool,格式 ND
样例输出 dst shape [1, 32],数据类型 float,格式 ND
核函数名 where_custom

产品与版本支持情况:Ascend 950PR&950DT 系列产品,CANN 软件版本 >= 9.1.0。

样例目录结构

where
├── scripts
│   └── gen_data.py         // 输入数据和真值数据生成脚本
├── CMakeLists.txt          // 编译工程文件
├── data_utils.h            // 数据读入写出函数
├── where.asc               // Ascend C 样例实现 & 调用样例
└── README.md               // 样例说明文档

其中:

  • where.asc 是样例核心文件,同时包含 Kernel 实现(KernelWhere 类 + where_custom 核函数)与主机侧调用实现(基于 ACL 运行时 API 的 main 函数);
  • gen_data.py 使用 NumPy 生成输入二进制文件与真值(golden)文件;
  • data_utils.h 提供 ReadFile/WriteFile 两个文件读写工具函数,用于主机侧读写 input/、output/ 目录下的二进制数据;
  • CMakeLists.txt 通过 find_package(ASC REQUIRED) 引入 asc-devkit 提供的 ASC 语言编译工具链,并将 where.asc 编译为可执行程序 demo。

Kernel 实现深度解析

Kernel 侧实现位于 where.asc,整体遵循"CopyIn → Compute → CopyOut"三段式流水结构。

类与成员:KernelWhere<T>

KernelWhere 是模板类,T 为数据类型(本样例实例化为 float)。它通过 TPipe 管理三路向量输入队列与一路输出队列:

  • inQueueX、inQueueY、inQueueZ:TQue<QuePosition::VECIN, 1>,分别缓存 src0、src1、condition;
  • outQueue:TQue<QuePosition::VECOUT, 1>,缓存计算结果 dst;
  • 对应的 GlobalTensor:src0Global、src1Global、dstGlobal(类型 T)以及 conditionGlobal(类型 bool)。

在 Init 中,使用 SetGlobalBuffer 为全局张量绑定显存地址,其中 condition 缓冲区按 (shape + 31) / 32 * 32 对齐到 32 的整数倍;随后用 InitBuffer 为各队列申请 UB(统一缓冲区)空间。该初始化还接收 shape(元素数)、count(参与计算元素个数)、mode(调用模式)三个控制参数。

三段式流水:CopyIn / Compute / CopyOut

Process 依次执行 CopyIn、Compute、CopyOut,并在首尾通过 AscendC::AscendCUtils::SetOverflow(1) / SetOverflow(0) 开启/关闭溢出检测开关,用于调试时暴露计算溢出问题。

  • CopyIn:分别 AllocTensor<T>() 从三个输入队列申请 LocalTensor,调用 AscendC::DataCopy 将全局内存数据拷入 UB,最后 EnQue 入队。
  • Compute:DeQue 出队得到三个输入 LocalTensor,先 AscendC::Duplicate(dstLocal, (T)0, shape) 将输出清零,然后根据 mode 选择调用形态调用 AscendC::Where<T>(...),完成后 EnQue 输出队列并 FreeTensor 释放输入队列。
  • CopyOut:从输出队列 DeQue 取出结果,AscendC::DataCopy 拷回全局内存,再 FreeTensor。

四种调用模式:张量与标量混合

where.asc 中通过 mode 参数区分四种 Where 调用形态:

mode 形态 调用示例(代码注释中的说明)
0 张量对张量 Where<T>(dstLocal, src0Local, src1Local, conditionLocal, dataSize)
1 src0 为标量 Where<T>(dstLocal, src0, src1Local, conditionLocal, dataSize)
2 src1 为标量 Where<T>(dstLocal, src0Local, src1, conditionLocal, dataSize)
3 src0 与 src1 均为标量 Where<T>(dstLocal, src0, src1, conditionLocal, dataSize)

需要特别说明的是标量提取过程:标量并非直接由外部传入,而是通过 src0Local.GetValue(0) 从已入队的 LocalTensor 中取出首元素作为标量。由于 GetValue 是标量(S)侧操作,而数据搬运是 MTE2 侧操作,二者存在跨流水单元的数据依赖,因此代码中使用硬件事件同步保证正确性:

event_t eventIdMTE2ToS = static_cast<event_t>(GetTPipePtr()->FetchEventID(AscendC::HardEvent::MTE2_S));
AscendC::SetFlag<AscendC::HardEvent::MTE2_S>(eventIdMTE2ToS);
AscendC::WaitFlag<AscendC::HardEvent::MTE2_S>(eventIdMTE2ToS);
T src0 = src0Local.GetValue(0);
event_t eventIdSToV = static_cast<event_t>(GetTPipePtr()->FetchEventID(AscendC::HardEvent::S_V));
AscendC::SetFlag<AscendC::HardEvent::S_V>(eventIdSToV);
AscendC::WaitFlag<AscendC::HardEvent::S_V>(eventIdSToV);

即先用 MTE2_S 事件保证"MTE2 数据搬运完成 → 标量读取",再用 S_V 事件保证"标量读取完成 → 向量计算可用",这是 SIMD 编程模型中处理 MTE2/标量/向量跨单元依赖的标准写法。

主机侧调用实现

核函数 where_custom 声明为 __global__ __vector__,固定 shape=32、count=32、mode=0(张量对张量模式)。主机侧 main 函数完整走通 ACL 运行时流程:

  1. aclInit 初始化、aclrtSetDevice/aclrtCreateContext/aclrtCreateStream 建立设备上下文与流;
  2. 为 src0、src1、condition、tiling 及输出分别 aclrtMallocHost + aclrtMalloc 申请主机与设备内存;
  3. 通过 ReadFile 读取 ./input/*.bin,用 aclrtMemcpy(..., ACL_MEMCPY_HOST_TO_DEVICE) 拷入设备;
  4. 使用内核调用符 where_custom<<<numBlocks, 0, stream>>>(param1Device, param2Device, param3Device, param5Device) 触发核函数(本样例 numBlocks = 1);
  5. aclrtSynchronizeStream 等待执行完成,ACL_MEMCPY_DEVICE_TO_HOST 拷回结果并 WriteFile 写出 ./output/output.bin;
  6. 调用 CompareResult 与真值 ./output/golden.bin 逐元素比对,绝对误差与相对误差均大于 EPS = 1e-4 才判定为错误,最终打印 test pass! 或 test failed!。

Where 高阶 API:函数原型与参数说明

样例调用的 AscendC::Where 属于高级 API(adv_api)数学计算接口,公开头文件为 include/adv_api/math/where.h,完整接口说明可参见 docs/zh/api/SIMD-API/adv_api/math_compute/Where_interface/Where.md。

函数原型:

template <typename T, typename U, typename S, typename V>
__aicore__ inline void Where(
    const LocalTensor<T>& dst, const U& src0, const S& src1,
    const LocalTensor<V>& condition, const uint32_t count)

模板参数说明:

模板参数 描述
T 目的操作数数据类型。支持 bool、int8_t、uint8_t、int16_t、uint16_t、half、bfloat16_t、int32_t、uint32_t、float、int64_t、uint64_t。
U LocalTensor 类型或标量类型,由 src0 自动推导,无需显式配置;src0 数据类型须与目的操作数一致。
S LocalTensor 类型或标量类型,由 src1 自动推导,无需显式配置;src1 数据类型须与目的操作数一致。
V 条件操作数数据类型,当前仅支持 bool。

参数说明:

参数 方向 说明
dst 输出 目的操作数,类型为 LocalTensor<T>,支持的 TPosition 为 VECIN/VECCALC/VECOUT。
src0、src1 输入 源操作数,类型为标量或 LocalTensor;为 LocalTensor 时支持的 TPosition 为 VECIN/VECCALC/VECOUT,数据类型须与目的操作数一致。
condition 输入 条件操作数,类型为 LocalTensor<bool>,支持的 TPosition 为 VECIN/VECCALC/VECOUT。
count 输入 参与计算的元素个数。

官方接口文档给出的调用示例(half 类型):

AscendC::LocalTensor<half> dst, src0, src1;
AscendC::LocalTensor<bool> condition;
uint32_t count = 512; // 参与计算的元素个数
AscendC::Where(dst, src0, src1, condition, count);

对应语义为:condition 为 1 时选择 src0 元素,为 0 时选择 src1 元素。

产品支持范围(据 Where.md):Ascend 950PR&950DT 系列产品支持;Atlas A3/A2 系列、Atlas 200I/500 A2 推理产品、Atlas 推理系列产品及 Atlas 训练系列产品均不支持。此外,where.h 头部明确禁止在 --enable-simt(纯 SIMT 编译)模式下包含该头文件。

底层实现原理:指令级条件选择

Where 的 Kernel 侧实现位于 impl/adv_api/detail/math/where/where_3510_impl.h(该文件为内部头文件,官方要求开发者只通过 #include "adv_api/math/where.h" 使用公开接口)。分析该实现可以还原 Where 的指令级工作方式。

静态类型约束

WhereImpl 通过 static_assert 与 SupportType 编译期约束模板参数:

  • T(数据类型)支持 bool/int8_t/uint8_t/int16_t/uint16_t/half/bfloat16_t/int32_t/uint32_t/float/int64_t/uint64_t;
  • condition 类型 V 仅支持 bool;
  • 当 src0、src1 为 LocalTensor 时,其模板参数须与 T 及 PrimType 一致(static_assert(Std::is_same<U, S>::value) 等),保证三者的元素类型统一。

四种形态的模板分派

WhereImpl 用 if constexpr 结合 TypeUtils::IsLocalTensorType / IsInnerDefaultType 在编译期区分四种输入形态(对应样例中的 mode 0~3),并将是否标量固化为模板参数 src0Val/src1Val 传给 WhereCompute。WhereCompute<src0Val, src1Val, ...> 利用 if constexpr (src0Val) 提前用 Reg::Duplicate 把标量值灌入向量寄存器,避免在循环体内反复加载。

核心计算循环

WhereCompute 的核心是逐 repeat 的寄存器级循环,关键步骤为:

  1. Reg::LoadAlign(selReg, conditionUb + i * repeatElm) 加载条件数据;
  2. Reg::CompareScalar<uint8_t, CMPMODE::NE>(selMask, selReg, 0, maskFull) 将条件与 0 比较,生成选择掩码(bool 非 0 即真);
  3. 对 2/4/8 字节数据类型执行 Reg::MaskUnPack 将按字节展开的掩码压缩为与元素粒度一致的掩码;
  4. Reg::LoadAlign 加载 src0、src1 数据(仅当对应操作数为张量时);
  5. Reg::Select(dstReg, src0Reg, src1Reg, selMask) 依据掩码完成指令级选择:掩码位为 1 选 src0,为 0 选 src1;
  6. Reg::StoreAlign(dstUb + i * repeatElm, dstReg, maskReg) 按剩余 count 生成的掩码回写结果。

其中 repeatTime = CeilDivision(count, GetVecLen() / sizeof(WhereType)) 表示按向量长度切分的重复次数;对于 8 字节类型(int64_t/uint64_t),实现选用 Reg::RegTraitNumTwo(双寄存器粒度)与 uint64_t 工作类型,以适配 64 位元素在向量寄存器中的排布。

参数校验与 Tiling 辅助接口

  • 设备侧参数校验:CheckFuncWhere(见 where_check_aicore.h)在 CPU 调试(ASCENDC_CPU_DEBUG)场景下对 count 与各 Tensor 进行 CalCountVerifyingParameters(计算个数校验)与 TensorVerifyingParameters(TPosition 为 VECIN/VECOUT/VECCALC 的位置校验),从 API 层拦截非法调用;
  • 主机侧 Tiling 辅助: where_tiling.h 提供 GetWhereMaxMinTmpSize(获取最大/最小临时空间)与 GetWhereTmpBufferFactorSize(推导单次迭代计算元素数)两个接口,供 Tiling 算子计算临时缓冲区大小。其实现(where_tiling_impl.cpp)目前仅接受 DAV_3510 与 DAV_9201 两种架构,且校验通过后返回的临时空间需求为 0——说明该实现版本中 Where 为"原地直算"型算子,无需额外临时空间,Tiling 阶段只需依据剩余空间切分迭代即可。

数据生成与真值对比

gen_data.py 使用 NumPy 生成测试数据与真值:

  • src0:np.random.uniform(10.0, 20.0, [32]),即 10~20 区间的 float32 随机数;
  • src1:np.random.uniform(0, 10.0, [32]),即 0~10 区间的 float32 随机数;
  • condition:np.random.choice([True, False], size=shape) 随机布尔序列;
  • 真值 golden = np.where(condition, src0, src1),与 Kernel 语义一一对应;脚本同时支持 mode 0~3 四种真值计算分支;
  • 另将 [shape, count, mode, is_dynamic] 打包为 uint32 数组写入 input_tiling.bin,作为 Tiling 参数输入。

脚本生成 ./input/input_src0.bin、./input/input_src1.bin、./input/input_condition.bin、./input/input_tiling.bin 及 ./output/golden.bin。主机侧 CompareResult 从 ./output/golden.bin 读取真值,按 EPS = 1e-4 的绝对/相对误差双阈值逐元素比对,全部通过才输出 test pass!。

编译运行:三种运行模式与编译选项

配置环境变量

根据当前环境上 CANN 开发套件包的安装方式配置环境变量:

source ${install_path}/cann/set_env.sh

说明:${install_path} 为 CANN 包安装目录,未指定安装目录时默认安装至 /usr/local/Ascend 下。

样例执行(默认 NPU 模式)

在样例根目录 examples/01_simd_cpp_api/04_advanced_api/10_math/where 下依次执行:

mkdir -p build && cd build;                       # 创建并进入 build 目录
cmake -DCMAKE_ASC_ARCHITECTURES=dav-3510 ..; make -j;  # 编译工程,默认 npu 模式
python3 ../scripts/gen_data.py                    # 生成测试输入数据
./demo                                            # 执行编译生成的可执行程序

CPU 调试与 NPU 仿真模式

在 cmake 阶段追加 -DCMAKE_ASC_RUN_MODE 参数即可切换运行模式:

cmake -DCMAKE_ASC_RUN_MODE=cpu -DCMAKE_ASC_ARCHITECTURES=dav-3510 ..; make -j;  # CPU 调试模式
cmake -DCMAKE_ASC_RUN_MODE=sim -DCMAKE_ASC_ARCHITECTURES=dav-3510 ..; make -j;  # NPU 仿真模式

注意:切换编译模式前需清理 cmake 缓存,可在 build 目录下执行 rm CMakeCache.txt 后重新 cmake。

编译选项说明

选项 可选值 说明
CMAKE_ASC_RUN_MODE npu(默认)、cpu、sim 运行模式:NPU 运行、CPU 调试、NPU 仿真
CMAKE_ASC_ARCHITECTURES dav-3510(默认) NPU 架构:dav-3510 对应 Ascend 950PR&950DT 系列产品

这两个选项在 CMakeLists.txt 中以 CACHE STRING 形式声明(CMAKE_ASC_RUN_MODE 默认 npu,CMAKE_ASC_ARCHITECTURES 默认 dav-3510,并注明亦支持 dav-2201),工程通过 find_package(ASC REQUIRED) 找到 ASC 编译器后,以 target_compile_options 传入 --npu-arch=${CMAKE_ASC_ARCHITECTURES} 完成目标架构编译。

执行结果

精度对比成功后输出:

test pass!

测试用例佐证:多类型多形态覆盖

仓库单元测试 tests/api/adv_api/math/where/test_operator_where.cpp 用 gtest 参数化测试(AdvanceWhereTestSuite)覆盖了 Where 的多种组合,印证了样例 Kernel 设计的通用性:

  • 数据类型:float(4 字节)、half(2 字节)、int8_t(1 字节)、int64_t(8 字节),对应 WhereTestParams.dataTypeSize 1/2/4/8;
  • 数据规模:32、64、96、256、1024、4096 等多种 count;
  • 调用形态:mode 0~3 全部覆盖,且测试 Kernel 中的 mode 分支与样例 where.asc 保持一致(Where 张量/标量四种调用)。

这组测试同时验证了 Where 在 64 位数据类型上的寄存器扩展实现(RegTraitNumTwo)与 1 字节类型上的掩码压缩逻辑。

约束与注意事项

  • 不支持源操作数与目的操作数地址重叠,开发者需保证 dst 与 src0、src1、condition 指向不同缓冲区;
  • 操作数地址偏移对齐要求遵循高阶 API 的通用说明和约束;
  • 产品支持面较窄:当前仅 Ascend 950PR&950DT 系列(CANN >= 9.1.0)支持该 API,Atlas A2/A3、推理及训练系列均不支持,跨平台迁移前需先确认目标产品的支持矩阵;
  • 头文件 where.h 明确禁止在 --enable-simt 编译选项下使用;
  • 标量模式(mode 1/2/3)涉及 GetValue(0) 的标量读取,必须配以 MTE2_S 与 S_V 事件同步,否则可能读到搬运未完成的数据。

综上,该 Where 样例从 API 使用、指令级原理到工程化编译运行形成了完整闭环,既是条件选择类算子的标准实现范本,也是理解高阶 API 张量/标量混合调用与跨流水单元同步机制的绝佳入门样例。

登录后查看全文
asc-devkit