CANN ops-transformer 中的 RainFusionAttention 算子:块级稀疏注意力原理、ACLNN 两段式接口与实战调用

原创2026-09-18 13:53:041,845 阅读
文章标签:算子库人工智能深度学习大模型高性能计算CANNAscend

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 依次执行:

  1. NpuInfo 采集:获取 UB 大小、LibApi workspace、AIV/AIC 核数;
  2. 属性检查(CheckAttr):读取 kvHeads、scaleValue(缺省回退 1/sqrt(embeddingSize))、maskType、innerPrecise;
  3. 输入处理(ProcessInput):解析布局、Query shape(TND 取 T/N/D,BNSD 取 B/N/S/D)、selectIdx 的 maxKvBlockNum、序列长度数组、blockShape;
  4. 布局校验(CheckKvCacheLayout):Q/KV 布局必须同为 BNSD 或同为非 BNSD,并分别校验 TND(3 维)与 BNSD(4 维)的 shape 合法性、KV 头数与 headDim 一致性;
  5. TND 序列长度总和校验(ValidateTNDSeqlenSum):所有 batch 的 qSeqlen 之和 == Q 的 T,kvSeqlen 之和 == KV 的 T;
  6. 配置校验(ValidateConfiguration):embeddingSize 必须为 64 或 128,blockShapeX/blockShapeY > 0,blockShapeY % 128 == 0,且 innerPrecise=1 时输入不得为 BF16;
  7. 任务切分(CalculateTaskSplit):按 batch 遍历,依据 Q 块数与 GQA groupSize(numHeads/kvHeads)计算每个 batch 的任务数与 Q 块总数,blockDim = min(aicNum, totalTaskNum);
  8. workspace 计算(CalculateWorkSpace):包含 libapiSize 与 mm1Out、online softmax、mm2Out、update 四段中间缓冲,均为 blockDim × 131072 × 元素大小 × 3 量级;
  9. 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 输入下均达标。

八、使用建议与注意事项

  1. 布局选择:变长序列、PagedAttention 场景优先使用 TND(需配套提供 actualSeqLengths 与 actualSeqLengthsKv);定长场景可使用 BNSD,此时序列长度数组可省略。
  2. Q/KV 布局一致性:Q 与 KV 的布局必须同为 BNSD 或同为 TND,不可混用。
  3. 块大小配置:blockShapeX/blockShapeY 必须大于 0,且 tiling 层要求 blockShapeY 能被 128 整除;headDim 仅支持 64 与 128。
  4. 精度搭配:BF16 输入时 innerPrecise 只能取 0(float32 softmax);FP16 输入时可选 1(fp16 softmax,推理优先、性能更好)。
  5. 稀疏索引合法性:selectIdx 有效索引必须升序前置、无效位置填 -1;索引值必须落在有效 KV 块范围内,否则结果未定义或报错。
  6. 稀疏度把控:建议稀疏度不要过低,否则跳过计算的块过少,稀疏收益会被索引加载与流水开销抵消,计算效率反而下降。
  7. 可选参数:attenMask、blockTable(PagedAttention Block 表)、softmaxLse 在当前版本不支持,调用时必须传 nullptr;非 PagedAttention 场景 blockSize 传 0 即可。
  8. 头数约束: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 的可编译示例进行二次开发与集成验证。

登录后查看全文
ops-transformer