ops-transformer RecurrentKda:面向 Decode/MTP 的线性注意力递归前向算子与 aclnn 两段式调用实战
ops-transformer RecurrentKda:面向 Decode/MTP 的线性注意力递归前向算子与 aclnn 两段式调用实战
本文以 aclnnRecurrentKda 接口文档 为主体,系统讲解 CANN ops-transformer 算子库中 RecurrentKda 算子的数学模型、aclnn 两段式接口原型、全部输入输出参数与约束,并结合 host 侧参数校验实现、tiling 调度逻辑 与 PyTorch 测试框架 深入解析任务切分、状态池(state pool)复用与错误码触发路径,帮助你在 NPU 上正确接入基于 Gated Delta Rule 的线性注意力 decode 路径。
产品支持情况
根据文档与 模块 README,当前支持矩阵如下:
| 产品 | 是否支持 |
|---|---|
| Ascend 950PR/Ascend 950DT | 支持 |
| Atlas A3 训练系列产品/Atlas A3 推理系列产品 | 支持 |
| Atlas A2 训练系列产品/Atlas A2 推理系列产品 | 支持 |
| Atlas 200I/500 A2 推理产品 | 不支持 |
| Atlas 推理系列产品 | 不支持 |
| Atlas 训练系列产品 | 不支持 |
功能定位:为什么需要递归实现
aclnnRecurrentKda 是基于 Gated Delta Rule 的线性注意力前向计算接口的递归(recurrent)实现,面向 decode / MTP(Multi-Token Prediction)短序列场景。与前向训练常用的并行(chunked)实现不同,递归实现按 token 逐步推进递归状态 ,天然适配"每步只新增少量 token、但需要维护并回写状态"的推理场景:
- 变长输入:配合
cuSeqlensOptional描述 batch 内各序列的 token 边界; - MTP 槽位复用:配合
ssmStateIndicesOptional与numAcceptedTokensOptional,实现投机解码/MTP 场景下对状态池(state pool)槽位的选择与裁剪; - 数值稳定处理:可选在 kernel 内将
gate解释为 raw gate 并转换为 step log gate、对 q/k 做 L2 normalize、对 beta 做 sigmoid,从而把一组"模型侧原始张量"直接喂入算子。
模块整体目录结构如下(位于 attention/recurrent_kda):op_host/ 存放 aclnn 接口实现与 tiling,op_kernel/ 存放架构相关的 kernel 实现(arch22 与 arch35 两套适配),tests/pytest/ 提供 NPU 精度验证框架,torch_extension/ 提供 PyTorch 算子封装。
计算公式与符号说明
设内部状态矩阵按 [V_dim, K_dim] 参与计算。useQkL2normInKernel=true 时,算子先对每个 token 的 、 做 L2 normalize;随后仅对 乘缩放系数 scale,得到 、。
gate 分支:当 useGateInKernel=false 时,输入 gate 已经是 step log gate,即 。当 useGateInKernel=true 时,令 (未传 dtBiasOptional 时不加偏置)、,则:
beta 的有效值:
每个 token 的递归更新:
其中,,,。 沿状态矩阵的 K 维广播。多个 value head 可以共享同一个 query/key head,要求 能被 整除。
| 符号 | 含义 |
|---|---|
| B | Batch Size,输入样本批量大小 |
| T | Token Capacity,BSND 为 B*T,TND 为输入首维;有效 token 数可以小于 T |
| H_k | Query/Key 头数 |
| H_v | Value/Gate 头数(要求 H_v 能被 H_k 整除) |
| K_dim | Key 每一个头的维度 |
| V_dim | Value 每一个头的维度 |
| seq_num | 逻辑序列数(定长时等于 B,变长时等于 cuSeqlensOptional 长度减 1) |
| scale | 缩放系数,通常为 K_dim^-0.5 |
| gate | gate 张量。useGateInKernel=true 时为 raw gate 输入,由算子内部转换为 step log gate ;useGateInKernel=false 时为外部已预计算好的 step log gate |
| 递归衰减系数,,沿状态矩阵的 K 维广播 | |
| A_log | raw gate 分支参数,算子使用 参与 gate 计算 |
| dtBias | raw gate 偏置 |
| beta | Delta 更新系数 |
递归状态矩阵,按 stateVFirst=True 布局存储为 [state_capacity, H_v, V_dim, K_dim],stateVFirst=False 布局存储为 [state_capacity, H_v, K_dim, V_dim] |
|
| 衰减后的状态, | |
| Delta 更新量, |
函数原型:aclnn 两段式接口
每个算子分为 两段式接口,必须先调用 aclnnRecurrentKdaGetWorkspaceSize 获取计算所需 workspace 大小以及包含算子计算流程的执行器,再调用 aclnnRecurrentKda 执行计算。接口声明见 aclnn_recurrent_kda.h:
aclnnStatus aclnnRecurrentKdaGetWorkspaceSize(
const aclTensor *query,
const aclTensor *key,
const aclTensor *value,
const aclTensor *gate,
const aclTensor *beta,
aclTensor *initialStateRef,
const aclTensor *cuSeqlensOptional,
const aclTensor *ssmStateIndicesOptional,
const aclTensor *aLogOptional,
const aclTensor *dtBiasOptional,
const aclTensor *numAcceptedTokensOptional,
const char *layout,
double scale,
bool outputFinalState,
bool inplaceFinalState,
bool useQkL2normInKernel,
bool useGateInKernel,
bool useBetaSigmoidInKernel,
bool allowNegEigval,
bool safeGate,
double lowerBound,
bool stateVFirst,
const aclTensor *attnOut,
const aclTensor *finalState,
uint64_t *workspaceSize,
aclOpExecutor **executor)
aclnnStatus aclnnRecurrentKda(
void *workspace,
uint64_t workspaceSize,
aclOpExecutor *executor,
aclrtStream stream)
从 host 侧实现 可以看到,第一段接口内部按"空指针检查(CheckNotNull)→ dtype 检查(CheckDtypeValid)→ shape/属性检查(CheckShape)→ 预处理(PreProcess,对输入张量调用 Contiguous 并将 SetOriginalShape 记录原始形状)"的顺序完成入参校验,校验逻辑与下文错误码表一一对应。
aclnnRecurrentKdaGetWorkspaceSize 参数说明
| 参数名 | 输入/输出 | 描述 | 使用说明 | 数据类型 | 数据格式 | 维度(shape) | 非连续的Tensor |
|---|---|---|---|---|---|---|---|
| query | 输入 | Query 张量。 | 按 layout 为 BSND: [B,T,H_k,K_dim] 或 TND: [T,H_k,K_dim]。 | BFLOAT16 | ND | [B,T,H_k,K_dim] 或 [T,H_k,K_dim] | √ |
| key | 输入 | Key 张量。 | 与 query 形状相同,数据类型与 query 相同。 | BFLOAT16 | ND | [B,T,H_k,K_dim] 或 [T,H_k,K_dim] | √ |
| value | 输入 | Value 张量。 | 按 layout 为 BSND: [B,T,H_v,V_dim] 或 TND: [T,H_v,V_dim]。 | BFLOAT16 | ND | [B,T,H_v,V_dim] 或 [T,H_v,V_dim] | √ |
| gate | 输入 | 预计算 step log gate 或 raw gate。 | 按 layout 为 BSND: [B,T,H_v,K_dim] 或 TND: [T,H_v,K_dim]。 | FLOAT、BFLOAT16、FLOAT16 | ND | [B,T,H_v,K_dim] 或 [T,H_v,K_dim] | √ |
| beta | 输入 | Delta 更新系数。 | 按 layout 为 BSND: [B,T,H_v] 或 TND: [T,H_v]。 | FLOAT、BFLOAT16、FLOAT16 | ND | [B,T,H_v] 或 [T,H_v] | √ |
| initialStateRef | 输入/输出 | 初始状态或 state pool。 | stateVFirst=true 时 Shape: [state_capacity,H_v,V_dim,K_dim];stateVFirst=false 时 Shape: [state_capacity,H_v,K_dim,V_dim]。未传 ssmStateIndicesOptional 时 state_capacity 必须等于 seq_num。 | BFLOAT16、FLOAT | ND | [state_capacity,H_v,V_dim,K_dim] 或 [state_capacity,H_v,K_dim,V_dim] | √ |
| cuSeqlensOptional | 输入 | 变长序列累计 token offset。 | 可选;设备侧一维 Tensor,Shape: [seq_num+1],长度至少为 2。 | INT32、INT64 | ND | [seq_num+1] | √ |
| ssmStateIndicesOptional | 输入 | 每个 token 对应的 state slot 索引。 | 可选;支持 packed 一维 [>=T] 或 speculative 二维 [seq_num,max_step],可以不传 numAcceptedTokensOptional。 | INT32、INT64 | ND | [>=T] 或 [seq_num,max_step] | √ |
| aLogOptional | 输入 | A_log 参数。 | useGateInKernel=true 时必选;Shape: [H_v]。 | FLOAT | ND | [H_v] | √ |
| dtBiasOptional | 输入 | raw gate 偏置。 | Shape: [H_v*K_dim] 或 [H_v,K_dim]。 | FLOAT | ND | [H_v*K_dim] 或 [H_v,K_dim] | √ |
| numAcceptedTokensOptional | 输入 | 每条序列已接受的 token 数量。 | 可选;传入时必须同时传 ssmStateIndicesOptional;Shape: [seq_num],每个值须位于对应序列的 [1,seq_len]。 | INT32、INT64 | ND | [seq_num] | √ |
| layout | 输入 | query、key、value 的数据 Layout 格式。 | 枚举值: BSND | TND。 | STRING | - | - | - |
| scale | 输入 | 缩放系数。 | 乘到 query 上,通常为 K_dim^-0.5。 | DOUBLE | - | - | - |
| outputFinalState | 输入 | 是否输出有效最终状态。 | 为 true 时 finalState 返回有效最终状态;是否原位更新由 inplaceFinalState 决定。 | BOOL | - | - | - |
| inplaceFinalState | 输入 | 状态是否原地更新。 | 为 true 时最终状态写回 initialStateRef;为 false 时 initialStateRef 不更新。 | BOOL | - | - | - |
| useQkL2normInKernel | 输入 | 是否对 q/k 做 L2 normalize。 | - | BOOL | - | - | - |
| useGateInKernel | 输入 | 是否将 gate 解释为 raw gate。 | 为 true 时 aLogOptional 必选。 | BOOL | - | - | - |
| useBetaSigmoidInKernel | 输入 | 是否在 kernel 内计算 sigmoid(beta)。 | - | BOOL | - | - | - |
| allowNegEigval | 输入 | beta sigmoid 后是否乘 2。 | - | BOOL | - | - | - |
| safeGate | 输入 | raw gate 的 safe 分支开关。 | 与 useGateInKernel 配合使用。 | BOOL | - | - | - |
| lowerBound | 输入 | safe gate 下界。 | safeGate=true 时生效,取值范围 [-5,0)。 | DOUBLE | - | - | - |
| stateVFirst | 输入 | 状态布局标志。 | 支持 true([state_capacity,H_v,V_dim,K_dim])/ false([state_capacity,H_v,K_dim,V_dim]),默认为 false。 | BOOL | - | - | - |
| attnOut | 输出 | Recurrent KDA 输出。 | Shape 与 value 相同。 | BFLOAT16 | ND | [B,T,H_v,V_dim] 或 [T,H_v,V_dim] | √ |
| finalState | 输出 | 最终状态。 | Shape 和数据类型必须与 initialStateRef 一致;outputFinalState=true 时内容有效。 | BFLOAT16、FLOAT | ND | [state_capacity,H_v,V_dim,K_dim] 或 [state_capacity,H_v,K_dim,V_dim] | √ |
| workspaceSize | 输出 | 返回需要在 Device 侧申请的 workspace 大小。 | - | - | - | - | - |
| executor | 输出 | 返回 op 执行器,包含了算子计算流程。 | - | - | - | - | - |
返回值:aclnnStatus,返回状态码,具体参见 aclnn 返回码。第一段接口会完成入参校验,出现以下场景时报错:
| 返回值 | 错误码 | 描述 |
|---|---|---|
| ACLNN_ERR_PARAM_NULLPTR | 161001 | 如果传入参数是必选输入、输出或者必选属性,且是空指针,则返回 161001 |
| ACLNN_ERR_PARAM_INVALID | 161002 | query/key/value dtype 不属于 {BFLOAT16} |
| ACLNN_ERR_PARAM_INVALID | 161002 | gate/beta dtype 不在 {FLOAT, BFLOAT16, FLOAT16} 范围内 |
| ACLNN_ERR_PARAM_INVALID | 161002 | initialState/finalState dtype 不在 {BFLOAT16, FLOAT} 范围内或两者不一致 |
| ACLNN_ERR_PARAM_INVALID | 161002 | cuSeqlensOptional/ssmStateIndicesOptional/numAcceptedTokensOptional dtype 不在 {INT32, INT64} 范围内 |
| ACLNN_ERR_PARAM_INVALID | 161002 | aLogOptional/dtBiasOptional dtype 不为 FLOAT |
| ACLNN_ERR_PARAM_INVALID | 161002 | layout 不在 {BSND, TND} 集合内或与 rank 不匹配 |
| ACLNN_ERR_PARAM_INVALID | 161002 | K_dim 不等于 128;V_dim 不属于 {128, 256} |
| ACLNN_ERR_PARAM_INVALID | 161002 | H_v 不能被 H_k 整除 |
| ACLNN_ERR_PARAM_INVALID | 161002 | query/key shape 不一致,或 query/key/value/gate/beta 的 shape 关系不满足对应 layout 要求 |
| ACLNN_ERR_PARAM_INVALID | 161002 | cuSeqlensOptional 不是一维 Tensor,或长度小于 2 |
| ACLNN_ERR_PARAM_INVALID | 161002 | initialState/finalState shape 与 stateVFirst 不匹配;未传 ssmStateIndicesOptional 时 state_capacity 不等于 seq_num |
| ACLNN_ERR_PARAM_INVALID | 161002 | ssmStateIndicesOptional 既不是长度大于等于 token capacity 的一维 Tensor,也不是 [seq_num,max_step] 二维 Tensor |
| ACLNN_ERR_PARAM_INVALID | 161002 | numAcceptedTokensOptional 长度不等于 seq_num |
| ACLNN_ERR_PARAM_INVALID | 161002 | useGateInKernel=true 时 aLogOptional 为空 |
| ACLNN_ERR_PARAM_INVALID | 161002 | useGateInKernel=false 时传入了 aLogOptional/dtBiasOptional 或 safeGate=true |
| ACLNN_ERR_PARAM_INVALID | 161002 | aLogOptional shape 不为 [H_v] |
| ACLNN_ERR_PARAM_INVALID | 161002 | dtBiasOptional shape 不为 [H_v*K_dim] 或 [H_v,K_dim] |
| ACLNN_ERR_PARAM_INVALID | 161002 | safeGate=true 时 lowerBound 不在 [-5,0) 范围内 |
| ACLNN_ERR_PARAM_INVALID | 161002 | numAcceptedTokensOptional 未与 ssmStateIndicesOptional 同时提供 |
这些校验点在 aclnn_recurrent_kda.cpp 的 CheckShape、CheckDtypeValid 函数中可以逐条找到对应实现,例如 useGateInKernel=false 时传入 A_log/dt_bias/safe_gate 的拦截即位于该文件的属性依赖检查段。
aclnnRecurrentKda 参数说明
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| workspace | 输入 | 在 Device 侧申请的 workspace 内存地址。 |
| workspaceSize | 输入 | 在 Device 侧申请的 workspace 大小,由第一段接口 aclnnRecurrentKdaGetWorkspaceSize 获取。 |
| executor | 输入 | op 执行器,包含了算子计算流程。 |
| stream | 输入 | 指定执行任务的 Stream。 |
返回值:aclnnStatus,返回状态码,具体参见 aclnn 返回码。
约束说明
- 确定性计算:aclnnRecurrentKda 默认确定性实现。
- 场景限制:该接口面向 decode / MTP 短序列场景,dense 单序列长度与 varlen 单序列长度均必须小于等于 8。
- dtype 一致性:query、key、value 数据类型必须保持一致,且仅支持 BFLOAT16;attnOut 与 value 同 dtype。
- gate/beta:支持 FLOAT、BFLOAT16、FLOAT16(接口内部会转换为 FLOAT 参与计算)。
- 状态张量:initialState 与 finalState 数据类型必须一致,支持 BFLOAT16 或 FLOAT。finalState 必须提供,仅在 outputFinalState=true 时保证内容有效。
- metadata tensor:cuSeqlensOptional、ssmStateIndicesOptional、numAcceptedTokensOptional 支持 INT32 或 INT64,kernel 按实际 dtype 读取;aLogOptional、dtBiasOptional 必须为 FLOAT。
- layout:取值仅支持 BSND、TND(必须大写)。
- 维度约束:K_dim 仅支持 128,V_dim 仅支持 128 或 256;H_v 必须能被 H_k 整除。
- stateVFirst:支持 true 和 false(默认 false)。为 true 时 initialState 与 finalState 的 shape 必须满足
[state_capacity, H_v, V_dim, K_dim];为 false 时必须满足[state_capacity, H_v, K_dim, V_dim]。未传 ssmStateIndicesOptional 时 state_capacity 必须等于逻辑序列数;传入后 state_capacity 可以与 seq_num 不同,由索引选择有效槽位。 - cuSeqlensOptional:首元素必须为 0、各 offset 必须非递减且不得超过输入 token capacity;每段变长序列长度必须小于等于 8。末元素可以小于 token capacity,此时 padding tail 输出不保证有效且不更新 state。
- ssmStateIndicesOptional:支持长度大于等于 token capacity 的 1D tensor,或 shape 为 [seq_num,max_step] 的 2D tensor;二维形式的 max_step 必须覆盖每条实际序列长度,索引值必须位于 [0,state_capacity)。numAcceptedTokensOptional 必须为长度等于 seq_num 的 1D tensor,且每个值位于对应序列的 [1,seq_len];它依赖 ssmStateIndicesOptional,但 ssmStateIndicesOptional 可以单独提供。
- gate 属性依赖:useGateInKernel=true 时 aLogOptional 必选;useGateInKernel=false 时传入了 aLogOptional、dtBiasOptional 或 safeGate=true 均会报错。aLogOptional shape 必须为 [H_v];dtBiasOptional shape 必须为 [H_v*K_dim] 或 [H_v,K_dim]。
- safeGate:safeGate=true 时 lowerBound 必须落在 [-5, 0) 区间内。
- 两个状态开关可独立组合:inplaceFinalState=true 时最终状态写回 initialState;outputFinalState=true 时 finalState 返回有效最终状态。
- 非连续支持:query/key/value/gate/beta 及可选 metadata tensor 支持非连续,接口内部会调用 Contiguous 处理。initialState/finalState 直接支持非连续 view,但内部二维 state 矩阵必须稠密:stride[3]=1、stride[2]=shape[3],slot/head 外层 stride 不得造成地址区间重叠。
源码纵深:参数如何从接口层流到 kernel
参数默认值与解析。从 aclnn_recurrent_kda.cpp 的 RecurrentKdaParams 结构可以看到默认值约定:layout="BSND"、scale=1.0、outputFinalState=false、inplaceFinalState=true、lowerBound=-5.0、stateVFirst=false,与文档一致。ParseLayout 函数仅接受大写 "BSND"/"TND" 字符串,layout==nullptr 会退化为 BSND。
tiling 切分策略。recurrent_kda_tiling_processor.h 揭示了调度模型:
- 任务单元:
RuleUpdateDynamicBlockDimByTaskUnits中,任务单元数taskUnits = b * nv(逻辑序列数 × value 头数),实际向量核数取min(taskUnits, aivNum)。也就是说每个 (序列, value head) 组合占用一个向量核任务——这与"递归状态必须按序列串行推进、无法在序列维度再并行"的算法特性相符。 - 短序列上限:常量
RKDA_MAX_MTP = 8正是文档约束"dense 与 varlen 单序列长度均 ≤ 8"的代码出处;UB(Unified Buffer)空间按RKDA_MAX_MTP深度预分配输入队列(q/k/v 为 bf16,gate 为 fp32)。 - V 维分块:
FinalizeVStepFromUb会在固定候选缓冲区组合{(stateOut,attnOut)=(1,1),(1,2),(2,2)}中,依据剩余 UB 空间选择 repeatTime 最小、缓冲深度最大的 vStep 方案,且 vStep 必须不小于 8;若 shape 过大导致 vStep < 8 会直接报 "shape is too big" 失败。 - state 转置代价:
CalcVStepCoeff显示stateVFirst=false时额外占用一份stateDtypeSize * aDk的 K-first state 转置缓冲——这解释了为何 kernel 入口 recurrent_kda.cpp 中,K 维优先(stateVFirst)布局是计算更直接的形态,V 优先布局则需要转换。
kernel 执行路径。recurrent_kda.cpp 中的 __global__ 入口声明 KERNEL_TYPE_AIV_ONLY(纯向量核任务),并依据 tilingData.inplaceFinalState 决定状态写回目标:
GM_ADDR stateOutput = tilingData.inplaceFinalState == 1 ? initialStateOut : finalState;
即 inplaceFinalState=true 时状态写回 initialStateRef,否则写入独立的 finalState 缓冲,这与文档中"两个开关可独立组合"的语义完全对应。tiling 数据结构定义于 recurrent_kda_struct.h,其中 ssmStateStride 仅在 ssmStateIndicesOptional 为二维时非零,承载 speculative 二维索引的步长信息。
state stride 重叠校验。ValidateStateStrides 强制:内部 state 矩阵必须稠密(stride<a href="https://link.gitcode.com/i/61fcb7febd62b6a3bfbdd497bdc21252" target="_blank">3]=1、stride[2]=shape[3]),且 head 维度 stride 不小于 densePlane、slot 维度 stride 不小于覆盖整个 slot 的最小跨度,防止非连续 view 造成地址区间重叠——对应约束说明中的非连续支持条款,该行为在 [pytest 框架 中亦有"非法 state stride 拦截"的专门验证用例。
调用示例
示例代码如下,仅供参考,具体编译和执行过程请参考 编译与运行样例。该示例为 BSND 布局、B=T=1、H_k=H_v=2、K=V=128、stateVFirst=true、状态以 FLOAT 存储的最小可运行场景:
#include <iostream>
#include <vector>
#include <cmath>
#include <cstring>
#include "securec.h"
#include "acl/acl.h"
#include "aclnnop/aclnn_recurrent_kda.h"
using namespace std;
namespace {
#define CHECK_RET(cond) ((cond) ? true :(false))
#define LOG_PRINT(message, ...) \
do { \
(void)printf(message, ##__VA_ARGS__); \
} while (0)
int64_t GetShapeSize(const std::vector<int64_t>& shape) {
int64_t shapeSize = 1;
for (auto i : shape) {
shapeSize *= i;
}
return shapeSize;
}
int Init(int32_t deviceId, aclrtStream* stream) {
auto ret = aclInit(nullptr);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
LOG_PRINT("aclInit failed. ERROR: %d\n", ret);
return ret;
}
ret = aclrtSetDevice(deviceId);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
LOG_PRINT("aclrtSetDevice failed. ERROR: %d\n", ret);
return ret;
}
ret = aclrtCreateStream(stream);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
LOG_PRINT("aclrtCreateStream failed. ERROR: %d\n", ret);
return ret;
}
return 0;
}
template <typename T>
int CreateAclTensor(const std::vector<T>& hostData, const std::vector<int64_t>& shape, void** deviceAddr,
aclDataType dataType, aclTensor** tensor) {
auto size = GetShapeSize(shape) * sizeof(T);
auto ret = aclrtMalloc(deviceAddr, size, ACL_MEM_MALLOC_HUGE_FIRST);
if (!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);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
LOG_PRINT("aclrtMemcpy failed. ERROR: %d\n", ret);
return ret;
}
std::vector<int64_t> strides(shape.size(), 1);
for (int64_t i = 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);
return 0;
}
struct TensorResources {
void* queryDeviceAddr = nullptr;
void* keyDeviceAddr = nullptr;
void* valueDeviceAddr = nullptr;
void* gateDeviceAddr = nullptr;
void* betaDeviceAddr = nullptr;
void* initialStateDeviceAddr = nullptr;
void* outDeviceAddr = nullptr;
void* finalStateDeviceAddr = nullptr;
aclTensor* queryTensor = nullptr;
aclTensor* keyTensor = nullptr;
aclTensor* valueTensor = nullptr;
aclTensor* gateTensor = nullptr;
aclTensor* betaTensor = nullptr;
aclTensor* initialStateTensor = nullptr;
aclTensor* outTensor = nullptr;
aclTensor* finalStateTensor = nullptr;
};
int InitializeTensors(TensorResources& resources) {
// BSND layout: q/k [B,T,H_k,K], v [B,T,H_v,V], gate [B,T,H_v,K], beta [B,T,H_v]
// state [seq_num,H_v,V,K]
int64_t B = 1;
int64_t T = 1;
int64_t Hk = 2;
int64_t Hv = 2;
int64_t K = 128;
int64_t V = 128;
std::vector<int64_t> queryShape = {B, T, Hk, K};
std::vector<int64_t> keyShape = {B, T, Hk, K};
std::vector<int64_t> valueShape = {B, T, Hv, V};
std::vector<int64_t> gateShape = {B, T, Hv, K};
std::vector<int64_t> betaShape = {B, T, Hv};
std::vector<int64_t> initialStateShape = {B, Hv, V, K};
std::vector<int64_t> outShape = {B, T, Hv, V};
std::vector<int64_t> finalStateShape = {B, Hv, V, K};
int64_t querySize = GetShapeSize(queryShape);
int64_t keySize = GetShapeSize(keyShape);
int64_t valueSize = GetShapeSize(valueShape);
int64_t gateSize = GetShapeSize(gateShape);
int64_t betaSize = GetShapeSize(betaShape);
int64_t initialStateSize = GetShapeSize(initialStateShape);
int64_t outSize = GetShapeSize(outShape);
int64_t finalStateSize = GetShapeSize(finalStateShape);
std::vector<aclBfloat16> queryHostData(querySize, 0);
std::vector<aclBfloat16> keyHostData(keySize, 0);
std::vector<aclBfloat16> valueHostData(valueSize, 0);
std::vector<float> gateHostData(gateSize, 0);
std::vector<float> betaHostData(betaSize, 0);
std::vector<float> initialStateHostData(initialStateSize, 0);
std::vector<aclBfloat16> outHostData(outSize, 0);
std::vector<float> finalStateHostData(finalStateSize, 0);
// Create query aclTensor.
int ret = CreateAclTensor(queryHostData, queryShape, &resources.queryDeviceAddr,
aclDataType::ACL_BF16, &resources.queryTensor);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
return ret;
}
// Create key aclTensor.
ret = CreateAclTensor(keyHostData, keyShape, &resources.keyDeviceAddr,
aclDataType::ACL_BF16, &resources.keyTensor);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
return ret;
}
// Create value aclTensor.
ret = CreateAclTensor(valueHostData, valueShape, &resources.valueDeviceAddr,
aclDataType::ACL_BF16, &resources.valueTensor);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
return ret;
}
// Create gate aclTensor.
ret = CreateAclTensor(gateHostData, gateShape, &resources.gateDeviceAddr,
aclDataType::ACL_FLOAT, &resources.gateTensor);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
return ret;
}
// Create beta aclTensor.
ret = CreateAclTensor(betaHostData, betaShape, &resources.betaDeviceAddr,
aclDataType::ACL_FLOAT, &resources.betaTensor);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
return ret;
}
// Create initialState aclTensor.
ret = CreateAclTensor(initialStateHostData, initialStateShape, &resources.initialStateDeviceAddr,
aclDataType::ACL_FLOAT, &resources.initialStateTensor);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
return ret;
}
// Create out aclTensor.
ret = CreateAclTensor(outHostData, outShape, &resources.outDeviceAddr,
aclDataType::ACL_BF16, &resources.outTensor);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
return ret;
}
// Create finalState aclTensor.
ret = CreateAclTensor(finalStateHostData, finalStateShape, &resources.finalStateDeviceAddr,
aclDataType::ACL_FLOAT, &resources.finalStateTensor);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
return ret;
}
return ACL_SUCCESS;
}
int ExecuteRecurrentKda(TensorResources& resources, aclrtStream stream,
void** workspaceAddr, uint64_t* workspaceSize) {
constexpr const char layoutStr[] = "BSND";
double scale = 1.0 / sqrt(128.0);
bool outputFinalState = true;
bool inplaceFinalState = true;
bool useQkL2normInKernel = false;
bool useGateInKernel = false;
bool useBetaSigmoidInKernel = false;
bool allowNegEigval = false;
bool safeGate = false;
double lowerBound = -5.0;
bool stateVFirst = true;
aclOpExecutor* executor;
int ret = aclnnRecurrentKdaGetWorkspaceSize(
resources.queryTensor, resources.keyTensor, resources.valueTensor,
resources.gateTensor, resources.betaTensor, resources.initialStateTensor,
nullptr, nullptr, nullptr, nullptr, nullptr,
layoutStr, scale, outputFinalState, inplaceFinalState, useQkL2normInKernel, useGateInKernel,
useBetaSigmoidInKernel, allowNegEigval, safeGate, lowerBound, stateVFirst,
resources.outTensor, resources.finalStateTensor, workspaceSize, &executor);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
LOG_PRINT("aclnnRecurrentKdaGetWorkspaceSize failed. ERROR: %d\n", ret);
return ret;
}
if (*workspaceSize > 0ULL) {
ret = aclrtMalloc(workspaceAddr, *workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
LOG_PRINT("allocate workspace failed. ERROR: %d\n", ret);
return ret;
}
}
ret = aclnnRecurrentKda(*workspaceAddr, *workspaceSize, executor, stream);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
LOG_PRINT("aclnnRecurrentKda failed. ERROR: %d\n", ret);
return ret;
}
return ACL_SUCCESS;
}
int PrintOutResult(std::vector<int64_t> &shape, void** deviceAddr) {
auto size = GetShapeSize(shape);
std::vector<aclBfloat16> resultData(size, 0);
auto ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]),
*deviceAddr, size * sizeof(resultData[0]), ACL_MEMCPY_DEVICE_TO_HOST);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
LOG_PRINT("copy result from device to host failed. ERROR: %d\n", ret);
return ret;
}
for (int64_t i = 0; i < size; i++) {
LOG_PRINT("result[%ld] is: %f\n", i, aclBfloat16ToFloat(resultData[i]));
}
return ACL_SUCCESS;
}
void CleanupResources(TensorResources& resources, void* workspaceAddr,
aclrtStream stream, int32_t deviceId) {
if (resources.queryTensor) {
aclDestroyTensor(resources.queryTensor);
}
if (resources.keyTensor) {
aclDestroyTensor(resources.keyTensor);
}
if (resources.valueTensor) {
aclDestroyTensor(resources.valueTensor);
}
if (resources.gateTensor) {
aclDestroyTensor(resources.gateTensor);
}
if (resources.betaTensor) {
aclDestroyTensor(resources.betaTensor);
}
if (resources.initialStateTensor) {
aclDestroyTensor(resources.initialStateTensor);
}
if (resources.outTensor) {
aclDestroyTensor(resources.outTensor);
}
if (resources.finalStateTensor) {
aclDestroyTensor(resources.finalStateTensor);
}
if (resources.queryDeviceAddr) {
aclrtFree(resources.queryDeviceAddr);
}
if (resources.keyDeviceAddr) {
aclrtFree(resources.keyDeviceAddr);
}
if (resources.valueDeviceAddr) {
aclrtFree(resources.valueDeviceAddr);
}
if (resources.gateDeviceAddr) {
aclrtFree(resources.gateDeviceAddr);
}
if (resources.betaDeviceAddr) {
aclrtFree(resources.betaDeviceAddr);
}
if (resources.initialStateDeviceAddr) {
aclrtFree(resources.initialStateDeviceAddr);
}
if (resources.outDeviceAddr) {
aclrtFree(resources.outDeviceAddr);
}
if (resources.finalStateDeviceAddr) {
aclrtFree(resources.finalStateDeviceAddr);
}
if (workspaceAddr) {
aclrtFree(workspaceAddr);
}
if (stream) {
aclrtDestroyStream(stream);
}
aclrtResetDevice(deviceId);
aclFinalize();
}
} // namespace
int main() {
int32_t deviceId = 0;
aclrtStream stream = nullptr;
TensorResources resources = {};
void* workspaceAddr = nullptr;
uint64_t workspaceSize = 0;
std::vector<int64_t> outShape = {1, 1, 2, 128};
int ret = ACL_SUCCESS;
// 1. Initialize device and stream
ret = Init(deviceId, &stream);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
LOG_PRINT("Init acl failed. ERROR: %d\n", ret);
return ret;
}
// 2. Initialize tensors
ret = InitializeTensors(resources);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
CleanupResources(resources, workspaceAddr, stream, deviceId);
return ret;
}
// 3. Execute the operation
ret = ExecuteRecurrentKda(resources, stream, &workspaceAddr, &workspaceSize);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
CleanupResources(resources, workspaceAddr, stream, deviceId);
return ret;
}
// 4. Synchronize stream
ret = aclrtSynchronizeStream(stream);
if (!CHECK_RET(ret == ACL_SUCCESS)) {
LOG_PRINT("aclrtSynchronizeStream failed. ERROR: %d\n", ret);
CleanupResources(resources, workspaceAddr, stream, deviceId);
return ret;
}
// 5. Process results
printf("-----------out输出-----------\n");
PrintOutResult(outShape, &resources.outDeviceAddr);
// 6. Cleanup resources
CleanupResources(resources, workspaceAddr, stream, deviceId);
return 0;
}
通过 PyTorch 调用与精度自验
除 aclnn C 接口外,仓库提供了 torch_extension 封装(见 torchapi_recurrent_kda.md)。recurrent_kda.py 注册的算子 schema 与 aclnn 参数一一对应,关键默认值与 aclnn 侧保持一致:layout="BSND"、inplace_final_state=True、output_final_state=False、state_v_first=False,返回 (out, final_state?) 二元组,其中 final_state 仅在 output_final_state=True 时非空;initial_state 在 inplace_final_state=True 时是可变输入。
精度验证可参考 tests/pytest 框架:用 PyTorch CPU golden 实现 生成参考结果,通过 cann_ops_transformer 调用 NPU 算子后对比输出与最终状态,并验证非法 state stride 的拦截行为。构建与运行方式:
cd <repo_root>
bash build.sh --torch_extension --ops=recurrent_kda --vendor_name=custom
python3 -m pip install build_out/*-1.0.0-py3-none-any.whl --force-reinstall --no-deps
export PYTHONPATH=$(pwd)/torch_extension:${PYTHONPATH}
cd attention/recurrent_kda/tests/pytest
bash test_run.sh single
默认使用 NPU 0,可通过 TEST_DEVICE_ID=1 bash test_run.sh single 指定其他设备。
总结
aclnnRecurrentKda 把 Gated Delta Rule 线性注意力的"逐步状态推进"压缩为单一 NPU 算子,用五个正交开关(L2 norm / raw gate / beta sigmoid / 状态布局 / 状态写回方式)覆盖了 decode 与 MTP 推理链路的主要数值处理变体,并通过 cuSeqlens、ssmStateIndices、numAcceptedTokens 三组 metadata tensor 支撑变长与状态池复用。接入时建议按以下顺序核对:dtype(q/k/v 必须 BF16)→ layout 与 shape 关系 → K_dim=128 / V_dim∈{128,256} 与 H_v % H_k == 0 → 单序列长度 ≤ 8 → state stride 稠密性,任一环节不满足都会在 第一段接口 以 161002 错误码被拦截,错误日志中带有可读的原因描述,便于快速定位。