asc-devkit 中 ReduceAll 接口实战指南:多维向量逻辑与归约的用法与原理

原创2026-10-15 11:01:322,126 阅读
文章标签:人工智能深度学习高性能计算CANN

asc-devkit 中 ReduceAll 接口实战指南:多维向量逻辑与归约的用法与原理

ReduceAll 是 CANN asc-devkit 提供的归约(Reduction)高级 API 之一,用于对多维向量在指定维度上求逻辑与。本文以 ReduceAll_interface 系列文档为核心,完整覆盖函数原型、模板参数、临时空间分配、host 侧 Tiling 配套接口与调用示例,并结合仓库源码说明其底层实现,帮助你正确、高效地在核函数(Kernel)中使用 ReduceAll。

一、功能与适用场景

1.1 功能说明

ReduceAll 对一个多维向量在指定的维度求逻辑与(AND)。定义指定计算的维度(Reduce 轴)为 R 轴,非指定维度(Normal 轴)为 A 轴。

以 shape 为 (2, 3) 的二维矩阵为例:

  • 指定在第一维(A 轴)上求逻辑与,输出结果为 [1, 0, 0];
  • 指定在第二维(R 轴)上求逻辑与,输出结果为 [0, 0]。

从语义上看,逻辑与即"全部为真才为真":当 R 轴上所有元素均为 1 时结果为 1,只要出现 0 结果即为 0。因此该接口常用于掩码合并、多通道条件汇总、特征压缩等需要按维度做布尔归约的场景。

1.2 产品支持情况

根据 ReduceAll.md 的说明,产品支持情况如下:

  • Ascend 950PR & 950DT 系列产品:支持;
  • Atlas A3 系列产品:支持;
  • Atlas A2 系列产品:支持;
  • Atlas 200I/500 A2 推理产品:不支持;
  • Atlas 推理系列产品 AI Core / Vector Core:不支持;
  • Atlas 训练系列产品:不支持。

从源码角度看,接口仅在 AI Vector Core 上生效(reduce.h 中 if ASCEND_IS_AIC { return; }),且通过编译期架构宏对 __NPU_ARCH__ 为 2201、3510、9201、5102、5162、3003、3113 等平台分发实现,与文档列出的支持产品相互印证。

二、函数原型与两种临时空间方案

2.1 函数原型

接口提供两种重载形式:

  • 通过 sharedTmpBuffer 入参传入临时空间:
template <class T, class pattern, bool isReuseSource = false>
__aicore__ inline void ReduceAll(const LocalTensor<T>& dstTensor, const LocalTensor<T>& srcTensor, const LocalTensor<uint8_t>& sharedTmpBuffer, const uint32_t srcShape[], bool srcInnerPad)
  • 由接口框架申请临时空间:
template <class T, class pattern, bool isReuseSource = false>
__aicore__ inline void ReduceAll(const LocalTensor<T>& dstTensor, const LocalTensor<T>& srcTensor, const uint32_t srcShape[], bool srcInnerPad)

由于接口内部实现涉及复杂的数学计算,需要额外的临时空间存储中间变量。两种方式的取舍如下:

  • 通过 sharedTmpBuffer 传入:开发者自行管理临时空间,接口框架不再申请。调用完成后该内存可复用,不会反复申请释放,灵活性高、内存利用率高;
  • 接口框架申请:开发者无需申请,但需要预留临时空间大小。

临时空间大小 BufferSize 通过 GetReduceAllMaxMinTmpSize 获取。两种重载在源码层面也一一对应:带 sharedTmpBuffer 的重载直接调用 Internal::ReduceAllImpl(reduce.h);不带临时空间的重载内部通过 PopStackBuffer<uint8_t, TPosition::LCM> 从栈中弹出临时缓冲后再调用前者(reduce.h)。

2.2 临时空间获取:GetReduceAllMaxMinTmpSize

核函数侧 ReduceAll 需要预留/申请临时空间,host 侧通过 GetReduceAllMaxMinTmpSize 获取预留/申请的最大最小临时空间大小,开发者据此范围选择合适的空间大小作为 Tiling 参数传递给核函数侧使用。

  • 为保证功能正确,预留/申请的临时空间大小不能小于最小临时空间大小;
  • 在最小临时空间到最大临时空间的范围内,随临时空间增大,核函数侧计算性能会有一定程度的优化提升;当前版本最大临时空间等于最小临时空间,因此直接按该数值预留即可。

函数原型:

void GetReduceAllMaxMinTmpSize(const AscendC::TensorShape& srcShape, const AscendC::TensorDataType dataType, ReducePattern pattern, bool isSrcInnerPad, bool isReuseSource, uint32_t& maxValue, uint32_t& minValue)

参数说明:

参数名 输入/输出 功能
srcShape 输入 输入 shape 信息,类型为 AscendC::TensorShape,取值与 ReduceAll 的 srcShape 参数保持一致
dataType 输入 输入数据类型,类型为 AscendC::TensorDataType,支持类型与 ReduceAll 模板参数 T 保持一致
pattern 输入 用于指定计算轴,ReducePattern 类型,取值与 ReduceAll 的 pattern 参数保持一致,当前只支持 AscendC::ReducePattern::AR 与 AscendC::ReducePattern::RA
isSrcInnerPad 输入 最内层轴数据是否 32Bytes 对齐,取值与 ReduceAll 的 srcInnerPad 保持一致
isReuseSource 输入 是否复用源操作数空间,取值与 ReduceAll 的 isReuseSource 保持一致
maxValue 输出 完成计算所需的最大临时空间大小,超出该值的空间不会被接口使用。注意:maxValue 仅作参考,可能大于 UB 剩余空间,此场景下需根据 UB 剩余空间选取合适大小
minValue 输出 完成计算所需的最小临时空间大小,预留/申请空间不能小于该数值

ReducePattern 枚举定义如下(reduce_tiling.h 声明了该接口,枚举定义见 GetReduceAllMaxMinTmpSize.md):

enum class ReducePattern : uint32_t {
    AR = 0,
    RA = 1,
    R,
    ARA,
    ARAR,
    ARARAR,
    ARARARAR,
    ARARARARA,
    RAR,
    RARA,
    RARAR,
    RARARA,
    RARARAR,
    RARARARA,
};

需要说明的是:枚举定义了多维扩展形态(如 ARA、ARAR 等),但当前 ReduceAll 仅支持二维 AR 与 RA,host 侧实现在 reduce_tiling.cpp 中通过 ASCENDC_HOST_ASSERT 强制校验 pattern == ReducePattern::AR || pattern == ReducePattern::RA,同时要求 shape 维度必须为 2(shapeDims.size() == ALLOWED_SHAPE_DIM)。

2.3 Host 侧调用示例

// 输入shape为16*32的矩阵;算子输入的数据类型为float;不允许修改源操作数
auto shape = AscendC::TensorShape({16, 32});
uint32_t maxValue = 0;
uint32_t minValue = 0;
bool isSrcInnerPad = true;
bool isReuseSource = false;
AscendC::GetReduceAllMaxMinTmpSize(
    shape, AscendC::TensorDataType::DT_FLOAT, AscendC::ReducePattern::AR, isSrcInnerPad, isReuseSource, maxValue, minValue);

host 侧 Tiling 的完整配套流程(获取临时空间大小 → 写入 TilingData → Kernel 侧读取并分配)可参考 更多样例:其中展示了通过 AscendC::TensorShape 描述输入形状、调用 GetXxxMaxMinTmpSize 获取 maxValue/minValue、再与 platform_ascendc::PlatformAscendC 获取的 UB 剩余空间比较后确定实际临时空间大小的完整写法。

三、参数说明

3.1 模板参数

参数名 描述
T 操作数数据类型,支持 uint8_t、float
pattern 指定 ReduceAll 计算轴(Reduce 轴与 Normal 轴)。由与向量维度数量相同的 A、R 字母组合形成,A 表示 Normal 轴,R 表示 Reduce 轴。例如 AR 表示二维向量第一维为 Normal 轴、第二维为 Reduce 轴。pattern 是定义在 AscendC::Pattern::Reduce 命名空间下的结构体,成员变量无需关注,当前仅支持显式指定 AscendC::Pattern::Reduce::AR 或 AscendC::Pattern::Reduce::RA
isReuseSource 是否允许修改源操作数,默认 false。置 true 后接口内部计算复用 src 内存空间以节省内存;置 false 则不复用。使用样例可参考 更多样例

3.2 接口参数

参数名 输入/输出 描述
dstTensor 输出 目的操作数,类型为 LocalTensor,支持 TPosition 为 VECIN/VECCALC/VECOUT
srcTensor 输入 源操作数,类型为 LocalTensor,支持 TPosition 为 VECIN/VECCALC/VECOUT,数据类型需与目的操作数一致
sharedTmpBuffer 输入 临时缓存,类型为 LocalTensor,支持 TPosition 为 VECIN/VECCALC/VECOUT,用于存储中间变量,大小通过 GetReduceAllMaxMinTmpSize 获取
srcShape 输入 uint32_t 数组,表示源操作数 shape,维度必须与模板参数 pattern 一致,当前只支持二维 shape
srcInnerPad 输入 实际需要计算的最内层轴数据是否 32Bytes 对齐,当前只支持 true

返回值:无。

四、约束说明

使用 ReduceAll 需满足以下约束:

  • 操作数地址对齐要求参见 通用地址对齐约束;
  • 源操作数 srcTensor 的输入数据只能为 0 或 1;
  • 不支持源操作数与目的操作数地址重叠;
  • 不支持 sharedTmpBuffer 与源操作数、目的操作数地址重叠。

这些约束在仓库测试中有专门覆盖:参数校验测试 kernel_reduce_all_check.cpp 中的 ReduceAllAPICheckOverlap 用例验证地址重叠异常上报,ReduceAllAPICheckSrcPos、ReduceAllAPICheckDstPos、ReduceAllAPICheckTmpPos 用例分别校验 src、dst、tmp 的 TPosition 合法性,ReduceAllAPICheckSrcShapeLastAxis、ReduceAllAPICheckReduceAllSrcInnerPad 等用例校验 shape 与内层对齐参数的取值。Kernel 侧参数检查的入口实现在 reduce_all_check.h,其按架构分发到 reduce_all_check_common.h 或 reduce_all_check_c310.h。

五、调用示例与输出

5.1 Kernel 侧调用示例

// dstLocal:输出结果
// srcLocal:输入数据
// tmp:存储中间结果的临时空间
// shape:输入数据的shape信息,当前仅支持2维
uint32_t shape[] = {2, 8};
// isReuse:是否允许修改源操作数srcLocal,true-允许,false-不允许
constexpr bool isReuse = true;
// 按尾轴求逻辑与
AscendC::ReduceAll<float, AscendC::Pattern::Reduce::AR, isReuse>(dstLocal, srcLocal, tmp, shape, true);

结果示例如下:

输入输出的数据类型为float
输入数据(src):
[[ 0.0 1.0 1.0 0.0 1.0 0.0 1.0 1.0],
 [ 0.0 1.0 0.0 1.0 0.0 1.0 1.0 0.0]]
输入pattern:AR
输入shape:(2,8)
输出数据(dst): [0.0 0.0]

pattern = AR 表示对第二维(尾轴,R 轴)归约:第一行数据 [0.0, 1.0, 1.0, 0.0, 1.0, 0.0, 1.0, 1.0] 中包含 0,逻辑与结果为 0;第二行同样包含 0,结果为 0,因此输出 [0.0, 0.0]。

5.2 测试用例中的两种调用形态

仓库测试 test_operator_reduce_all.cpp 同时覆盖了两种调用形态:

  • isReuse = false 时,通过 TBuf 申请临时空间并显式传入 ReduceAll<T, Pattern::Reduce::AR/RA, isReuse>(dstLocal, srcLocal, tmp, shape, true);
  • isReuse = true 时,直接调用不带临时空间参数的重载 ReduceAll<T, Pattern::Reduce::AR/RA, isReuse>(dstLocal, srcLocal, shape, true),由接口框架从栈上申请临时空间。

参数化测试用例覆盖 float 与 uint8_t 两种类型、AR/RA 两种 pattern、isReuse 开关组合,以及 first/last 维度如 (8, 32)、(16, 7)、(7, 1)、(1, 8) 等多种 shape,验证接口在不同输入规模下的正确性。

六、源码级实现原理

6.1 通用平台实现(reduce_all_v220_impl.h)

在通用架构实现 reduce_all_v220_impl.h 中,ReduceAllImpl 通过编译期检查约束,并按下述策略完成计算:

  • static_assert 校验数据类型仅支持 float/uint8_t,pattern 仅支持 Pattern::Reduce::AR/RA;
  • uint8_t + AR:计算 splitK(取 last 最近 2 的幂次,last < elePerBlk 时置 0),调用 BinaryReduceAnyAllCompute 完成尾部归约;
  • uint8_t + RA:由于 u8 按 2 个元素打包进 int16,先 ReinterpretCast<int16_t> 将元素数减半,再调用 BinaryReduceByFirstAxis<int16_t, ..., And<int16_t, false>> 按第一维归约;
  • float + AR:将 sharedTmpBuffer 重解释为 T 类型后调用 BlockReduceByLastAxis<T, ..., ApiMode::API_MODE_ALL, Min<T, false>> 按尾轴分块归约;
  • float + RA:调用 BinaryReduceByFirstAxis<T, ..., Min<T, false>> 按第一维归约。

逻辑与借助 Min 归约算子实现:由于输入仅取 0/1,min 运算等价于逻辑与,这是源码层面"求逻辑与"的底层落点。同时 SetMaskNorm()/ResetMask() 完成掩码状态管理。此外 reduce_all_3510_impl.h 提供了 3510/9201 平台的寄存器级实现:ReduceAllARImpl 在 dimR <= vlSize 时走单向量寄存路径 ReduceARReuseSourceLessThanVL,否则走 ReduceAROverVLImpl 跨向量路径。

6.2 临时空间大小计算的源码逻辑

host 侧 GetReduceAllMaxMinTmpSize 首先通过 ASCENDC_HOST_ASSERT 校验数据类型(仅 float/uint8_t),随后按数据类型分派:

  • uint8_t:走 GetReduceAnyAllCommonTmpSize;
  • float:走 GetReduceCommonMaxMinTmpSize(reduce_tiling.cpp)。

以 float + AR 为例,空间估算依据 last 与单块元素数 elePerBlk = ONE_BLK_SIZE / sizeof(T)、单次迭代元素数 elePerRep 的关系给出 0、first * elePerBlk * sizeof(T) 或 first * elePerRep * sizeof(T) 等不同取值;RA 则按 FindK(first) 的最接近 2 的幂次计算分块空间。值得注意的是:当 isReuseSource = true 时,maxValue = minValue = 0(reduce_tiling.cpp),即复用源操作数后接口不再需要额外临时空间,这也是开启 isReuseSource 能显著省内存的底层原因。

七、总结

ReduceAll 是 asc-devkit 在 AI Vector Core 上提供的多维逻辑与归约接口,核心使用要点可归纳为:

  1. 确定 pattern:二维场景显式选择 AscendC::Pattern::Reduce::AR(尾轴归约)或 RA(首轴归约),并与 srcShape 的二维维度保持一致;
  2. 准备临时空间:通过 GetReduceAllMaxMinTmpSize 在 host 侧获取空间大小并作为 Tiling 参数传入;当前最大最小空间相等,按该值预留即可;
  3. 内存策略:需要省内存时开启 isReuseSource = true(此时所需临时空间为 0),并注意源操作数会被改写;无论哪种方式,src、dst、sharedTmpBuffer 三者地址均不允许重叠;
  4. 数据约束:输入仅支持 uint8_t/float,且源数据只能为 0 或 1,srcInnerPad 当前必须为 true。

本文配套的接口文档入口为 ReduceAll_interface,完整样例可参考 更多样例,测试覆盖见 test_operator_reduce_all.cpp。

登录后查看全文
asc-devkit