ops-transformer RecurrentKda:面向 Decode/MTP 的线性注意力递归前向算子与 aclnn 两段式调用实战

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

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 逐步推进递归状态 StS_t,天然适配"每步只新增少量 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 的 qtq_t、ktk_t 做 L2 normalize;随后仅对 qtq_t 乘缩放系数 scale,得到 qˉt\bar q_t、kˉt\bar k_t。

gate 分支:当 useGateInKernel=false 时,输入 gate 已经是 step log gate,即 ℓt=gatet\ell_t=gate_t。当 useGateInKernel=true 时,令 xt=gatet+dtBiasx_t=gate_t+dtBias(未传 dtBiasOptional 时不加偏置)、a=exp⁡(Alog⁡)a=\exp(A_{\log}),则:

ℓt={lowerBound⋅σ(axt),safeGate=true−a⋅softplus⁡(xt),safeGate=false,dt=exp⁡(ℓt)\ell_t = \begin{cases} lowerBound\cdot\sigma(a x_t), & safeGate=true \\ -a\cdot\operatorname{softplus}(x_t), & safeGate=false \end{cases}, \qquad d_t=\exp(\ell_t)

beta 的有效值:

βˉt={βt,useBetaSigmoidInKernel=falseσ(βt),useBetaSigmoidInKernel=true, allowNegEigval=false2σ(βt),useBetaSigmoidInKernel=true, allowNegEigval=true\bar\beta_t = \begin{cases} \beta_t, & useBetaSigmoidInKernel=false \\ \sigma(\beta_t), & useBetaSigmoidInKernel=true,\ allowNegEigval=false \\ 2\sigma(\beta_t), & useBetaSigmoidInKernel=true,\ allowNegEigval=true \end{cases}

每个 token 的递归更新:

Sˉt=St−1⊙dtΔt=βˉt(vt−Sˉtkˉt)St=Sˉt+ΔtkˉtTot=Stqˉt\begin{aligned} \bar S_t &= S_{t-1}\odot d_t \\ \Delta_t &= \bar\beta_t\left(v_t-\bar S_t\bar k_t\right) \\ S_t &= \bar S_t+\Delta_t\bar k_t^T \\ o_t &= S_t\bar q_t \end{aligned}

其中,St−1,St∈RVdim×KdimS_{t-1},S_t \in R^{V_{dim}\times K_{dim}},qt,kt∈RKdimq_t,k_t\in R^{K_{dim}},vt,ot∈RVdimv_t,o_t\in R^{V_{dim}}。dtd_t 沿状态矩阵的 K 维广播。多个 value head 可以共享同一个 query/key head,要求 HvH_v 能被 HkH_k 整除。

符号 含义
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 ℓt\ell_t;useGateInKernel=false 时为外部已预计算好的 step log gate
dtd_t 递归衰减系数,dt=exp⁡(ℓt)d_t=\exp(\ell_t),沿状态矩阵的 K 维广播
A_log raw gate 分支参数,算子使用 exp⁡(Alog⁡)\exp(A_{\log}) 参与 gate 计算
dtBias raw gate 偏置
beta Delta 更新系数
StS_t 递归状态矩阵,按 stateVFirst=True 布局存储为 [state_capacity, H_v, V_dim, K_dim],stateVFirst=False 布局存储为 [state_capacity, H_v, K_dim, V_dim]
Sˉt\bar S_t 衰减后的状态,Sˉt=St−1⊙dt\bar S_t=S_{t-1}\odot d_t
Δt\Delta_t Delta 更新量,Δt=βˉt(vt−Sˉtkˉt)\Delta_t=\bar\beta_t(v_t-\bar S_t\bar k_t)

函数原型: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 错误码被拦截,错误日志中带有可读的原因描述,便于快速定位。

登录后查看全文
ops-transformer