CANN ops-transformer 中的 RainFusionAttention 算子:块级稀疏注意力原理、ACLNN 两段式接口与实战调用
CANN ops-transformer 中的 RainFusionAttention 算子:块级稀疏注意力原理、ACLNN 两段式接口与实战调用
本篇技术指南围绕 CANN ops-transformer 仓库中基于 CATLASS 模板库迁移而来的 RainFusionAttention(RFA)高性能稀疏注意力算子展开,系统讲解其块级稀疏计算模型、selectIdx 稀疏索引格式、TND/BNSD 数据布局、aclnnRainFusionAttention 两段式 ACLNN 接口的完整参数语义与约束,并结合源码给出可编译、可运行的实战调用示例。读完本文,你将掌握在昇腾 A2/A3 平台上使用 RainFusionAttention 构造自定义稀疏注意力 Kernel 的完整方法,并理解其在长序列推理场景下降低计算量与内存占用的核心机制。
一、算子概述:从 CATLASS 迁移而来的稀疏注意力实现
RainFusionAttention 是 CANN ops-transformer 算子库中的一个高性能稀疏注意力算子,位于 attention/rain_fusion_attention。它基于 CATLASS 模板库实现,从 catlass 的 32_sparse_attention_infer 示例迁移而来,并针对 ops-transformer 开发框架进行了适配,充分利用昇腾 A2 系列硬件的 AI Core 与 Vector Core 特性。
稀疏注意力的核心动机是:在长序列 Transformer 推理中,每个 Query 位置通常只需关注 Key/Value 序列中一小部分相关区域(例如局部窗口、Top-k 选择结果等),而密集注意力会对全部 token 计算注意力分数,导致大量无效计算与内存开销。RainFusionAttention 通过**块级稀疏(block-sparse)**方式,只对由 selectIdx 指定的 KV 块执行 QK 矩阵乘与 PV 矩阵乘,从而在保持精度的前提下显著降低计算量。
其主要功能特性包括:
- 灵活的稀疏块模式:支持自定义的
x*y块级稀疏模式,通过blockShape参数指定 Q 方向与 KV 方向的块大小; - TND 格式 KV Cache:支持
[T, N, D]布局的 KV cache,适用于变长序列与 PagedAttention 场景; - 多种 Q 输入布局:支持 TND、BNSD 两种 Query 输入布局;
- 高性能计算:基于 CATLASS 模板库的 GEMM 与 Online Softmax 流水,充分挖掘昇腾 A2 硬件特性;
- 多精度支持:支持 FP16 与 BF16 两种输入精度;
- 非对齐序列:序列长度不必被块大小整除,自动处理边界块。
二、计算模型与稀疏索引格式
2.1 计算公式
RainFusionAttention 的计算遵循标准缩放点积注意力公式,其中稀疏块大小为 blockShapeX × blockShapeY,稀疏模式由 selectIdx 指定:
attentionOut = Softmax(scale · query · keyᵀ + atten_mask) · value
其中 scale 为缩放因子(scaleValue,一般取 D^-0.5)。实际执行时,QK 矩阵乘只针对被选中的 KV 块进行,Softmax 采用 online 方式在块间流式更新,最终结果再与 Value 做 PV 矩阵乘并 rescale 输出,从而在数学上与密集注意力等价、计算量却大幅下降。
2.2 块划分规则
设 Q 方向序列长度为 qSeqlen、KV 方向为 kvSeqlen,则:
- Q 方向分块数:
ceil(qSeqlen / blockShapeX) - KV 方向分块数:
ceil(kvSeqlen / blockShapeY)
分块数通过向上取整计算(见 rain_fusion_attention_tiling.cpp 中的 CeilDiv 与 GetQBlocks 实现),因此序列长度不需要被块大小整除,最后一块不完整时由系统自动处理边界。
2.3 selectIdx / selectNumIdx 稀疏索引格式
RainFusionAttention 使用新的 selectIdx 索引格式,不需要传统的 sBlockIdx 计算。核心是两个 INT64 输入:
- selectIdx:形状为
[T, headNum, maxKvBlockNum]的稀疏块索引数组。T:所有 batch 中 Q 方向切块的总数(按blockShapeX计算);headNum:头数;maxKvBlockNum:最大 KV 块数量;- 存储每个 Q 块选择的 KV 块索引,有效索引放数组前、升序排列,无效位置放数组后、用 -1 填充。
- selectNumIdx:形状为
[T, headNum]的稀疏块数量数组,存储每个 Q 块实际选择的 KV 块数量。
以 qSeqlen=256, kvSeqlen=512, blockShapeX=64, blockShapeY=64 为例:
Q方向: ceil(256/64) = 4块 [0, 1, 2, 3]
KV方向: ceil(512/64) = 8块 [0, 1, 2, 3, 4, 5, 6, 7]
每个Q块可以选择任意KV块组合:
- Q块0选择的KV块: [0, 2, 5]
- Q块1选择的KV块: [1, 3, 6]
- Q块2选择的KV块: [0, 4, 7]
- Q块3选择的KV块: [2, 5, 6]
此时 selectNumIdx[0] = 3、selectIdx[0] = [0, 2, 5, -1, -1, -1, -1, -1],以此类推。稀疏度越低(选中的块越少),跳过计算的块越多,加速收益越大。
2.4 源码层面的索引处理
从源码结构看,tiling 阶段通过 ProcessSelectIdx 从 selectIdx 的第三维解析出 maxKvBlockNum,并据此计算 maxNumBlocksPerBatch = maxKvBlockNum × numHeads(见 rain_fusion_attention_tiling.cpp)。Kernel 侧则直接读取 selectIdx 与 selectNumIdx 的全局内存,按 Q 块逐个加载被选中的 KV 块执行 QK/PV 计算(见 rain_fusion_attention_kernel.h)。
三、数据布局:TND 与 BNSD
RainFusionAttention 的输入可通过 qInputLayout 与 kvInputLayout 两个字符串参数指定多种维度排布解读方式。官方 API 文档(docs/aclnnRainFusionAttention.md)与源码当前支持 "TND" 与 "BNSD" 两种布局;仓库根目录 README 中提到的 BSH 布局与"BNSD 暂不支持"属于早期描述,以源码与正式 API 文档为准:当前 BNSD 已实现支持。
- T:B 和 S 合轴紧密排列的长度(Total tokens);
- B:输入样本批量大小(Batch);
- S:序列长度(Seq-Length);
- N:多头数(Head-Num);
- D:隐藏层最小单元尺寸,满足
D = H / N(Head-Dim); - H:隐藏层大小(Head-Size)。
3.1 TND 格式 [T, N, D]
T:总 token 数量;N:KV 头数;D:头维度。
适用于变长序列场景。TND 格式下必须提供 actualSeqLengths 与 actualSeqLengthsKv,且所有 batch 的 qSeqlen 之和必须等于 Q 的 T、所有 batch 的 kvSeqlen 之和必须等于 KV 的 T,tiling 阶段的 ValidateTNDSeqlenSum 会执行该校验。
3.2 BNSD 格式 [B, N, S, D]
- 每个维度分别表示 Batch、头数、序列长度、头维度。
BNSD 格式下 actualSeqLengths 可传 nullptr,此时使用 BNSD 的 S 维度作为统一序列长度(useUniformQSeqlen/useUniformKvSeqlen 标志置位);若传入数组,则逐 batch 校验其值不超过 shape 中的 S 维。Key 与 Value 的 BNSD 四维必须完全一致(见 ValidateBNSDFormat)。
3.3 Q/KV 布局一致性约束
如果 Q 布局与 KV 布局中一个是 BNSD,另一个也必须为 BNSD,否则报错。该约束在 inferShape 阶段(rain_fusion_attention_infershape.cpp)、tiling 阶段(CheckKvCacheLayout)以及 ACLNN 参数校验(aclnn_rain_fusion_attention.cpp)三层均有实现。
四、ACLNN 两段式接口详解
RainFusionAttention 遵循昇腾 ACLNN 的两段式接口设计:先调用 aclnnRainFusionAttentionGetWorkspaceSize 完成入参校验、推导 workspace 大小并生成包含算子计算流程的执行器 executor,再调用 aclnnRainFusionAttention 执行实际计算。
4.1 第一段接口
aclnnStatus aclnnRainFusionAttentionGetWorkspaceSize(
const aclTensor *query, // Query输入,FLOAT16/BFLOAT16,ND,3维
const aclTensor *key, // Key输入,FLOAT16/BFLOAT16,ND,3维
const aclTensor *value, // Value输入,FLOAT16/BFLOAT16,ND,3维
const aclTensor *selectIdx, // 稀疏块索引 [T, headNum, maxKvBlockNum],INT64
const aclTensor *selectNumIdx, // 每个Q块的KV块数量 [T, headNum],INT64
const aclIntArray *blockShape, // 块形状 [blockShapeX, blockShapeY],至少2个元素
const aclTensor *attenMaskOptional, // 当前不支持,传nullptr
const aclIntArray *actualSeqLengthsOptional, // 各batch的Q序列长度(变长序列)
const aclIntArray *actualSeqLengthsKvOptional,// 各batch的KV序列长度(变长序列)
const aclTensor *blockTableOptional, // PagedAttention Block表,当前不支持,传nullptr
char *qInputLayout, // "TND" 或 "BNSD"
char *kvInputLayout, // "TND" 或 "BNSD"
int64_t numKeyValueHeads, // KV头数
int64_t maskType, // 0表示无mask,3为CausalMask
double scaleValue, // 缩放系数,一般取 D^-0.5
int64_t innerPrecise, // 0=float32 softmax,1=fp16 softmax
int64_t blockSize, // PagedAttention块大小,不使用可传0
const aclTensor *attentionOut, // 输出,shape与query一致
const aclTensor *softmaxLseOptional, // LSE输出,当前不支持,传nullptr
uint64_t *workspaceSize, // 返回workspace大小
aclOpExecutor **executor) // 返回执行器
各参数要点如下:
| 参数 | 输入/输出 | 关键说明 |
|---|---|---|
| query / key / value | 输入 | 三者数据类型必须一致(FLOAT16 或 BFLOAT16),均支持非连续 Tensor(内部会自动做 Contiguous 处理) |
| selectIdx | 输入 | shape 为 [QBlockNum, headNum, maxKvBlockNum],有效索引升序前置、无效位用 -1 填充 |
| selectNumIdx | 输入 | shape 为 [QBlockNum, headNum] |
| blockShape | 输入 | 至少两个元素 [blockShapeX, blockShapeY],两者均须大于 0;tiling 阶段还要求 blockShapeY 能被 128 整除 |
| attenMaskOptional / blockTableOptional / softmaxLseOptional | 输入/输出 | 当前版本不支持,必须传 nullptr |
| actualSeqLengthsOptional / actualSeqLengthsKvOptional | 输入 | TND 格式下必填;BNSD 格式下可省略(使用 shape 中的 S 维) |
| numKeyValueHeads | 输入 | Q 头数 N1 与 KV 头数 N2 需满足 N1 >= N2 && N1 % N2 == 0,且 G = N1 / N2 < 128 && 128 % G == 0 |
| maskType | 输入 | 0 表示无 mask,3 表示 CausalMask |
| scaleValue | 输入 | 缩放系数,默认缺省时 tiling 自动取 1/sqrt(embeddingSize) |
| innerPrecise | 输入 | 仅允许 0 或 1;Query 为 BF16 时只能配置为 0(fp16 softmax 不支持 BF16) |
| blockSize | 输入 | PagedAttention 的 block 大小,非 PagedAttention 场景传 0 即可 |
| attentionOut | 输出 | 数据类型与 shape 与 query 保持一致 |
4.2 第二段接口
aclnnStatus aclnnRainFusionAttention(
void *workspace, // Device侧workspace地址(第一段接口计算大小)
uint64_t workspaceSize, // workspace大小
aclOpExecutor *executor, // 第一段接口返回的op执行器
const aclrtStream stream) // 指定执行任务的Stream
4.3 返回值与错误码
接口返回 aclnnStatus 状态码,具体可参考 aclnn返回码。第一段接口完成入参校验,以下场景会报错:
| 返回值 | 错误码 | 触发场景 |
|---|---|---|
| ACLNN_ERR_PARAM_NULLPTR | 161001 | query、key、value、selectIdx、selectNumIdx 传入空指针 |
| ACLNN_ERR_PARAM_INVALID | 161002 | query/key/value 数据类型不在支持范围;qInputLayout 或 kvInputLayout 不合法;blockShape 元素少于 2 或值小于等于 0;innerPrecise 不是 0 或 1 |
4.4 约束说明汇总
- 默认确定性实现,
aclnnRainFusionAttention计算结果可复现; - 与 PyTorch 配合使用时,需保证 CANN 相关包与 PyTorch 相关包的版本匹配;
- 输入 query、key、value 数据类型必须一致;
- tiling 阶段校验 headDim(embeddingSize)必须为 64 或 128(见 ValidateConfiguration);
- 稀疏块索引必须在有效范围内,无效位置用 -1 填充。
五、完整调用示例
以下示例整理自仓库 examples/test_aclnn_rain_fusion_attention.cpp(完整可编译代码请直接查看该文件),展示了 TND 布局下稀疏率=1(即每个 Q 块选择全部 KV 块)的调用流程。编译运行的整体流程可参考编译与运行样例。
#include <iostream>
#include <vector>
#include <cstring>
#include <cmath>
#include <cstdint>
#include "acl/acl.h"
#include "aclnn/opdev/fp16_t.h"
#include "aclnnop/aclnn_rain_fusion_attention.h"
using namespace std;
#define CHECK_RET(cond, return_expr) \
do { if (!(cond)) { return_expr; } } while (0)
#define LOG_PRINT(message, ...) printf(message, ##__VA_ARGS__)
// 计算shape元素总数
int64_t GetShapeSize(const std::vector<int64_t>& shape) {
int64_t shapeSize = 1;
for (auto i : shape) { shapeSize *= i; }
return shapeSize;
}
// AscendCL初始化:aclInit + 设置device + 创建stream
int Init(int32_t deviceId, aclrtStream* stream) {
auto ret = aclInit(nullptr);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclInit failed. ERROR: %d\n", ret); return ret);
ret = aclrtSetDevice(deviceId);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSetDevice failed. ERROR: %d\n", ret); return ret);
ret = aclrtCreateStream(stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtCreateStream failed. ERROR: %d\n", ret); return ret);
return 0;
}
// 通用创建aclTensor模板:host数据 -> device内存 -> aclTensor(ND格式、连续strides)
template <typename T>
int CreateAclTensor(const std::vector<T>& hostData, const std::vector<int64_t>& shape, void** deviceAddr,
aclDataType dataType, aclTensor** tensor) {
if (shape.empty()) { LOG_PRINT("shape is empty\n"); return -1; }
auto size = GetShapeSize(shape) * sizeof(T);
if (hostData.size() != static_cast<size_t>(GetShapeSize(shape))) {
LOG_PRINT("hostData size mismatch\n"); return -1;
}
auto ret = aclrtMalloc(deviceAddr, size, ACL_MEM_MALLOC_HUGE_FIRST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMalloc failed. ERROR: %d\n", ret); return ret);
ret = aclrtMemcpy(*deviceAddr, size, hostData.data(), size, ACL_MEMCPY_HOST_TO_DEVICE);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMemcpy failed. ERROR: %d\n", ret);
aclrtFree(*deviceAddr); *deviceAddr = nullptr; return ret);
std::vector<int64_t> strides(shape.size(), 1);
if (shape.size() > 1) {
for (int64_t i = static_cast<int64_t>(shape.size()) - 2; i >= 0; i--) {
strides[i] = shape[i + 1] * strides[i + 1];
}
}
*tensor = aclCreateTensor(shape.data(), shape.size(), dataType, strides.data(), 0,
aclFormat::ACL_FORMAT_ND, shape.data(), shape.size(), *deviceAddr);
CHECK_RET(*tensor != nullptr, LOG_PRINT("aclCreateTensor failed\n");
aclrtFree(*deviceAddr); *deviceAddr = nullptr; return -1);
return 0;
}
int main() {
// 1. 固定写法:device/stream初始化
int32_t deviceId = 0;
aclrtStream stream;
auto ret = Init(deviceId, &stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret);
// 2. 设置参数
int32_t batch = 1, qSeqlen = 128, kvSeqlen = 128;
int32_t numHeads = 1, numKvHeads = 1, headDim = 128;
int32_t blockShapeX = 128, blockShapeY = 128;
// 计算TND格式维度与分块数
int64_t totalQTokens = batch * qSeqlen;
int64_t totalKvTokens = batch * kvSeqlen;
int32_t qBlockNum = (qSeqlen + blockShapeX - 1) / blockShapeX; // Q方向块数(向上取整)
int32_t kvBlockNum = (kvSeqlen + blockShapeY - 1) / blockShapeY; // KV方向块数(向上取整)
int32_t totalQBlocks = qBlockNum * numHeads; // 所有batch的Q块总数
int32_t maxKvBlockNum = kvBlockNum;
// 3. 创建Query tensor (TND: [totalQTokens, numHeads, headDim])
std::vector<int64_t> queryShape = {totalQTokens, numHeads, headDim};
std::vector<op::fp16_t> queryHostData(totalQTokens * numHeads * headDim, 1.0f);
void* queryDeviceAddr = nullptr; aclTensor* queryTensor = nullptr;
ret = CreateAclTensor(queryHostData, queryShape, &queryDeviceAddr, ACL_FLOAT16, &queryTensor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Failed to create query tensor\n"); return ret);
// 4. 创建Key/Value tensor (TND: [totalKvTokens, numKvHeads, headDim])
std::vector<int64_t> kvShape = {totalKvTokens, numKvHeads, headDim};
std::vector<op::fp16_t> keyHostData(totalKvTokens * numKvHeads * headDim, 1.0f);
std::vector<op::fp16_t> valueHostData(totalKvTokens * numKvHeads * headDim, 1.0f);
void* keyDeviceAddr = nullptr; aclTensor* keyTensor = nullptr;
void* valueDeviceAddr = nullptr; aclTensor* valueTensor = nullptr;
ret = CreateAclTensor(keyHostData, kvShape, &keyDeviceAddr, ACL_FLOAT16, &keyTensor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Failed to create key tensor\n"); return ret);
ret = CreateAclTensor(valueHostData, kvShape, &valueDeviceAddr, ACL_FLOAT16, &valueTensor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Failed to create value tensor\n"); return ret);
// 5. 生成稀疏索引:稀疏率=1,每个Q块选择全部KV块
// selectIdx: [totalQBlocks, numHeads, maxKvBlockNum],无效位-1
// selectNumIdx: [totalQBlocks, numHeads]
std::vector<int64_t> selectIdxHostData(totalQBlocks * numHeads * maxKvBlockNum, -1);
std::vector<int64_t> selectNumIdxHostData(totalQBlocks * numHeads, 0);
for (int32_t qb = 0; qb < totalQBlocks; ++qb) {
for (int32_t h = 0; h < numHeads; ++h) {
selectNumIdxHostData[qb * numHeads + h] = maxKvBlockNum; // 选满所有KV块
int64_t baseIdx = static_cast<int64_t>((qb * numHeads + h) * maxKvBlockNum);
for (int32_t k = 0; k < maxKvBlockNum; ++k) {
selectIdxHostData[baseIdx + k] = k; // 索引0..maxKvBlockNum-1
}
}
}
std::vector<int64_t> selectIdxShape = {totalQBlocks, numHeads, maxKvBlockNum};
std::vector<int64_t> selectNumIdxShape = {totalQBlocks, numHeads};
void* selectIdxDeviceAddr = nullptr; aclTensor* selectIdxTensor = nullptr;
void* selectNumIdxDeviceAddr = nullptr; aclTensor* selectNumIdxTensor = nullptr;
ret = CreateAclTensor(selectIdxHostData, selectIdxShape, &selectIdxDeviceAddr, ACL_INT64, &selectIdxTensor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Failed to create selectIdx tensor\n"); return ret);
ret = CreateAclTensor(selectNumIdxHostData, selectNumIdxShape, &selectNumIdxDeviceAddr, ACL_INT64, &selectNumIdxTensor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Failed to create selectNumIdx tensor\n"); return ret);
// 6. 创建输出tensor(shape与query一致)
std::vector<int64_t> outputShape = {totalQTokens, numHeads, headDim};
std::vector<op::fp16_t> outputHostData(GetShapeSize(outputShape), 0.0f);
void* outputDeviceAddr = nullptr; aclTensor* outputTensor = nullptr;
ret = CreateAclTensor(outputHostData, outputShape, &outputDeviceAddr, ACL_FLOAT16, &outputTensor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Failed to create output tensor\n"); return ret);
// 7. 创建blockShape数组 [blockShapeX, blockShapeY]
std::vector<int64_t> blockShapeData = {blockShapeX, blockShapeY};
aclIntArray* blockShape = aclCreateIntArray(blockShapeData.data(), blockShapeData.size());
CHECK_RET(blockShape != nullptr, LOG_PRINT("Failed to create blockShape array\n"); return -1);
// 8. 创建actualSeqLengths/actualSeqLengthsKv(TND格式下为必需参数,host侧数组)
std::vector<int64_t> actualSeqLengthsHost(batch, static_cast<int64_t>(qSeqlen));
std::vector<int64_t> actualSeqLengthsKvHost(batch, static_cast<int64_t>(kvSeqlen));
aclIntArray* actualSeqLengths = aclCreateIntArray(actualSeqLengthsHost.data(), batch);
aclIntArray* actualSeqLengthsKv = aclCreateIntArray(actualSeqLengthsKvHost.data(), batch);
CHECK_RET(actualSeqLengths != nullptr && actualSeqLengthsKv != nullptr,
LOG_PRINT("Failed to create actualSeqLengths arrays\n"); return -1);
// 9. 准备布局字符串参数(注意需为可写缓冲区)
char qLayoutBuffer[16] = {0}, kvLayoutBuffer[16] = {0};
strncpy(qLayoutBuffer, "TND", sizeof(qLayoutBuffer) - 1);
strncpy(kvLayoutBuffer, "TND", sizeof(kvLayoutBuffer) - 1);
// 10. 计算scaleValue = D^-0.5
float scaleValue = 1.0f / std::sqrt(static_cast<float>(headDim));
// 11. 调用第一段接口:获取workspace大小与executor
uint64_t workspaceSize = 0;
aclOpExecutor* executor = nullptr;
ret = aclnnRainFusionAttentionGetWorkspaceSize(
queryTensor, // query
keyTensor, // key
valueTensor, // value
selectIdxTensor, // selectIdx
selectNumIdxTensor, // selectNumIdx
blockShape, // blockShape
nullptr, // attenMaskOptional(不支持)
actualSeqLengths, // actualSeqLengthsOptional
actualSeqLengthsKv, // actualSeqLengthsKvOptional
nullptr, // blockTableOptional(不支持)
qLayoutBuffer, // qInputLayout = "TND"
kvLayoutBuffer, // kvInputLayout = "TND"
numKvHeads, // numKeyValueHeads
0, // maskType = 0(无mask)
scaleValue, // scaleValue
0, // innerPrecise = 0(float32 softmax)
128, // blockSize(非PagedAttention场景可传0)
outputTensor, // attentionOut
nullptr, // softmaxLseOptional(不支持)
&workspaceSize, // workspaceSize (out)
&executor); // executor (out)
CHECK_RET(ret == ACL_SUCCESS && executor != nullptr,
LOG_PRINT("GetWorkspaceSize failed. ERROR: %d\n", ret); return ret);
// 12. 按需分配workspace并调用第二段接口执行计算
void* workspaceAddr = nullptr;
if (workspaceSize > 0) {
ret = aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("allocate workspace failed. ERROR: %d\n", ret); return ret);
}
ret = aclnnRainFusionAttention(workspaceAddr, workspaceSize, executor, stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnRainFusionAttention failed. ERROR: %d\n", ret); return ret);
// 13. 同步等待执行结束,并将结果从device侧拷贝回host侧
ret = aclrtSynchronizeStream(stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSynchronizeStream failed. ERROR: %d\n", ret); return ret);
std::vector<op::fp16_t> resultData(GetShapeSize(outputShape), 0);
ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(op::fp16_t), outputDeviceAddr,
GetShapeSize(outputShape) * sizeof(op::fp16_t), ACL_MEMCPY_DEVICE_TO_HOST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("copy result failed. ERROR: %d\n", ret); return ret);
// 14. 打印前10个结果
uint64_t printNum = 10;
LOG_PRINT("Output results (first %lu elements):\n", printNum);
for (uint64_t i = 0; i < printNum && i < resultData.size(); i++) {
LOG_PRINT(" index %lu: %f\n", i, static_cast<float>(resultData[i]));
}
// 15. 释放所有资源(device内存、tensor、intArray、stream、device、acl)
if (workspaceAddr) aclrtFree(workspaceAddr);
if (queryDeviceAddr) aclrtFree(queryDeviceAddr);
if (keyDeviceAddr) aclrtFree(keyDeviceAddr);
if (valueDeviceAddr) aclrtFree(valueDeviceAddr);
if (outputDeviceAddr) aclrtFree(outputDeviceAddr);
if (selectIdxDeviceAddr) aclrtFree(selectIdxDeviceAddr);
if (selectNumIdxDeviceAddr) aclrtFree(selectNumIdxDeviceAddr);
if (queryTensor) aclDestroyTensor(queryTensor);
if (keyTensor) aclDestroyTensor(keyTensor);
if (valueTensor) aclDestroyTensor(valueTensor);
if (outputTensor) aclDestroyTensor(outputTensor);
if (selectIdxTensor) aclDestroyTensor(selectIdxTensor);
if (selectNumIdxTensor) aclDestroyTensor(selectNumIdxTensor);
if (blockShape) aclDestroyIntArray(blockShape);
if (actualSeqLengths) aclDestroyIntArray(actualSeqLengths);
if (actualSeqLengthsKv) aclDestroyIntArray(actualSeqLengthsKv);
aclrtDestroyStream(stream);
aclrtResetDevice(deviceId);
aclFinalize();
LOG_PRINT("Test completed successfully!\n");
return 0;
}
要点提示:
selectIdx/selectNumIdx为 INT64 类型,blockShape、actualSeqLengths等数组用aclCreateIntArray在 host 侧创建(其内部数据会在算子下发时同步到 device);qInputLayout/kvInputLayout传入的是可写字符缓冲区而非字符串字面量;- 真正做稀疏时,只需把
selectIdx中未选中的位置填 -1、并将selectNumIdx设为实际选中的块数,其余流程完全一致。
六、Tiling 与 Kernel 实现内幕
6.1 OpDef 注册与硬件适配
算子在 rain_fusion_attention_def.cpp 中注册,输入 query/key/value 支持 DT_FLOAT16 与 DT_BF16,selectIdx/selectNumIdx/blockShape 为 DT_INT64,输出 attentionOut 与输入同类型、softmaxLse 为 DT_FLOAT。属性默认值:qInputLayout="TND"、kvInputLayout="TND"、numKeyValueHeads=1、maskType=0、scaleValue=0.0(缺省时 tiling 自动取 1/sqrt(headDim))、innerPrecise=1(fp16 softmax,推理优先)、blockSize=128。AICore 配置覆盖 ascend910b(A2 训练/推理)、ascend910_93(A3)、ascend950 三个平台。
官方 API 文档的产品支持情况为:Atlas A2 训练/推理系列产品(ascend910b)与 Atlas A3 训练/推理系列产品支持;Ascend 950PR/950DT、Atlas 200I/500 A2 推理产品、Atlas 推理系列产品(310p)、Atlas 训练系列产品(910)不支持。
6.2 Tiling 阶段的校验与任务切分
rain_fusion_attention_tiling.cpp 是整个 host 侧调度的核心,按 GetRFATiling 依次执行:
- NpuInfo 采集:获取 UB 大小、LibApi workspace、AIV/AIC 核数;
- 属性检查(
CheckAttr):读取 kvHeads、scaleValue(缺省回退1/sqrt(embeddingSize))、maskType、innerPrecise; - 输入处理(
ProcessInput):解析布局、Query shape(TND 取 T/N/D,BNSD 取 B/N/S/D)、selectIdx 的 maxKvBlockNum、序列长度数组、blockShape; - 布局校验(
CheckKvCacheLayout):Q/KV 布局必须同为 BNSD 或同为非 BNSD,并分别校验 TND(3 维)与 BNSD(4 维)的 shape 合法性、KV 头数与 headDim 一致性; - TND 序列长度总和校验(
ValidateTNDSeqlenSum):所有 batch 的 qSeqlen 之和 == Q 的 T,kvSeqlen 之和 == KV 的 T; - 配置校验(
ValidateConfiguration):embeddingSize必须为 64 或 128,blockShapeX/blockShapeY > 0,blockShapeY % 128 == 0,且innerPrecise=1时输入不得为 BF16; - 任务切分(
CalculateTaskSplit):按 batch 遍历,依据 Q 块数与 GQA groupSize(numHeads/kvHeads)计算每个 batch 的任务数与 Q 块总数,blockDim = min(aicNum, totalTaskNum); - workspace 计算(
CalculateWorkSpace):包含 libapiSize 与 mm1Out、online softmax、mm2Out、update 四段中间缓冲,均为blockDim × 131072 × 元素大小 × 3量级; - tiling 数据填充(
FillTilingData)与 tilingKey 生成(GenerateTilingKey)。
6.3 TilingKey 编码
tilingKey 采用十进制位域编码(见 GenerateTilingKey):位 0-1 编码 Q Layout(2=TND,3=BNSD),位 2-4 编码 Mask Type(0=NoMask,3=CausalMask),位 5-7 编码 Softmax 精度(0=Float,1=Half),位 8-10 编码 PagedCache 标志,位 11-13 编码 KV Layout,位 14-15 编码数据类型(00=FP16,22=BF16),位 16-18 为算子类别(900=RFA)。例如 FP16 + TND + TND + NoCache + Half + NoMask 的 tilingKey 为 9000000030100002,Float Softmax 时为 9000000030000002。该 key 用于内核分发的模板实例选择。
6.4 Kernel 侧的模板化流水
Kernel 定义在 rain_fusion_attention_kernel.h,是一个高度模板化的类 RainFusionAttentionKernel,模板参数包括:
BlockMmadQK/BlockMmadPV:块级 QK 矩阵乘与 PV 矩阵乘模块(实现在 attn_infra/gemm/block 下);EpilogueOnlineSoftmax/EpilogueRescaleO:Online Softmax 流水与输出 rescale 模块(实现在 attn_infra/epilogue 下);PAGED_CACHE_FLAG:是否使用 Paged KV cache;QUERY_LAYOUT/KV_CACHE_LAYOUT:Q 与 KV 的布局(0=TND,1=BNSD)。
从源码结构可以推断,算子按"QK 分块计算 → Online Softmax 流式更新 → PV 聚合 → rescale 输出"的流水组织,围绕昇腾 AI Core 的 L1/L0 多级缓存与 UB(Unified Buffer)做数据搬移(attn_infra/gemm/tile_common 下的 GM↔L1↔L0A/L0B 拷贝模块),这是其高性能的主要来源。
七、编译、测试与验证
7.1 编译
算子编译集成在 ops-transformer 的统一编译流程中:
bash build.sh --soc=ascend910b
仓库根目录 CMakeLists.txt 会汇总各算子目录(含 attention/rain_fusion_attention/CMakeLists.txt)统一构建 op_host 与 op_kernel 产物。
7.2 测试套件
测试说明见 tests/README.md,覆盖:
- 基础 TND 格式测试:batch=1、qSeq=256、kvSeq=512、heads=8;
- 不同 blockShape 配置:小块(32×32)、大块(128×128)、非对称块(64×128);
- 边界条件:非对齐序列(qSeq=250、kvSeq=500)、极小序列(64/128)、单头(numHeads=1)、多 batch(batch=2);
- 稀疏度:高稀疏(sparsity=0.1,仅选 10% 块)、低稀疏(sparsity=0.8)。
测试程序 test_rain_fusion_attention.cpp 以 TestConfig 向量驱动,新增用例只需向其中 push 一个配置即可。测试使用固定随机种子保证结果可复现,运行于昇腾设备环境。
7.3 Golden 精度验证
spec.py 是 ACLNN 模式的 TestSpec 入口,通过 impl/golden.py、impl/inputs.py、impl/compare.py 三个模块实现三方对比:高精度 golden(输入 upcast 到 FP32 完整计算)作为参考,benchmark 用原 dtype 计算,NPU 输出与两者做统计相对误差(stat_rel_err)对比,保证算子精度在 FP16/BF16/FP32 输入下均达标。
八、使用建议与注意事项
- 布局选择:变长序列、PagedAttention 场景优先使用 TND(需配套提供
actualSeqLengths与actualSeqLengthsKv);定长场景可使用 BNSD,此时序列长度数组可省略。 - Q/KV 布局一致性:Q 与 KV 的布局必须同为 BNSD 或同为 TND,不可混用。
- 块大小配置:
blockShapeX/blockShapeY必须大于 0,且 tiling 层要求blockShapeY能被 128 整除;headDim 仅支持 64 与 128。 - 精度搭配:BF16 输入时
innerPrecise只能取 0(float32 softmax);FP16 输入时可选 1(fp16 softmax,推理优先、性能更好)。 - 稀疏索引合法性:
selectIdx有效索引必须升序前置、无效位置填 -1;索引值必须落在有效 KV 块范围内,否则结果未定义或报错。 - 稀疏度把控:建议稀疏度不要过低,否则跳过计算的块过少,稀疏收益会被索引加载与流水开销抵消,计算效率反而下降。
- 可选参数:
attenMask、blockTable(PagedAttention Block 表)、softmaxLse在当前版本不支持,调用时必须传nullptr;非 PagedAttention 场景blockSize传 0 即可。 - 头数约束:Q 头数 N1 与 KV 头数 N2 需满足
N1 >= N2 && N1 % N2 == 0,且G = N1/N2 < 128 && 128 % G == 0,即支持 MQA/GQA 剪枝头配置。
RainFusionAttention 为长序列稀疏注意力推理提供了一条"以块为单位精准跳过无关计算"的高效路径,其 selectIdx 索引格式与 GQA 头约束也便于与各类路由/剪枝算法对接。建议结合 docs/aclnnRainFusionAttention.md 的完整参数表与 examples/test_aclnn_rain_fusion_attention.cpp 的可编译示例进行二次开发与集成验证。