asc-devkit 中 ReduceAll 接口实战指南:多维向量逻辑与归约的用法与原理
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 上提供的多维逻辑与归约接口,核心使用要点可归纳为:
- 确定 pattern:二维场景显式选择
AscendC::Pattern::Reduce::AR(尾轴归约)或RA(首轴归约),并与srcShape的二维维度保持一致; - 准备临时空间:通过 GetReduceAllMaxMinTmpSize 在 host 侧获取空间大小并作为 Tiling 参数传入;当前最大最小空间相等,按该值预留即可;
- 内存策略:需要省内存时开启
isReuseSource = true(此时所需临时空间为 0),并注意源操作数会被改写;无论哪种方式,src、dst、sharedTmpBuffer三者地址均不允许重叠; - 数据约束:输入仅支持
uint8_t/float,且源数据只能为 0 或 1,srcInnerPad当前必须为true。
本文配套的接口文档入口为 ReduceAll_interface,完整样例可参考 更多样例,测试覆盖见 test_operator_reduce_all.cpp。