CANN ops-transformer ChunkKdaFwd 算子实战指南:KDA 分块正向计算的数学原理、aclnn 接口与工程实现

原创2026-09-19 10:57:282,447 阅读
文章标签:算子库人工智能深度学习大模型高性能计算CANNAscend

CANN ops-transformer ChunkKdaFwd 算子实战指南:KDA 分块正向计算的数学原理、aclnn 接口与工程实现

ChunkKdaFwd 是 CANN ops-transformer 中用于完成不涉及 CP(Context Parallel)切分的 KDA(Key-Decay Attention)分块正向计算的 NPU 算子,面向 Delta Rule / Gated Delta Rule 类线性注意力模型,输出注意力结果、最终状态以及可供反向重计算使用的中间量。本文以 attention/chunk_kda_fwd/README.md 为骨架,结合 aclnn 接口文档、算子设计介绍 与 op_host/op_kernel/tests 源码,系统讲解其数学定义、参数语义、两段式 aclnn 调用、返回策略、kernel 内部流水阶段、tiling 模板与验证方法。读完本文,你将能够理解 ChunkKdaFwd 的完整计算语义,掌握通过 aclnnChunkKdaFwd 与 cann_ops_transformer.ops.chunk_kda_fwd 调用该算子的方式,并了解其在 A2/A3/A5 各平台上的数值设计与优化路径。

一、产品支持情况

产品 是否支持
Ascend 950PR/Ascend 950DT √
Atlas A3 训练系列产品/Atlas A3 推理系列产品 √
Atlas A2 训练系列产品/Atlas A2 推理系列产品 √
Atlas 200I/500 A2 推理产品 ×
Atlas 推理系列产品 ×
Atlas 训练系列产品 ×

从 算子原型注册 可以看到,算子仅在 ascend910b(对应 Atlas A2)、ascend910_93(对应 Atlas A3)和 ascend950(对应 Ascend 950)三类 AiCore 配置上注册;tiling 侧通过 NpuArch::DAV_3510 稳定地识别 Ascend 950,避免依赖随 CANN 版本漂移的 SoC 版本枚举。

二、算子功能与数学定义

2.1 功能概述

ChunkKdaFwd 将每条序列按 C=chunk_sizeC=chunk\_size 划分为 MM 个 chunk,完成分块正向计算,输出:

  • 注意力输出 attn_out;
  • 最终状态 final_state(可选);
  • 供反向继续计算的中间量(gk、w、u、qg、kg、v_new、h,均可选)。

以下公式中,ii、jj 为 chunk 内 token 下标,lcl_c 为该 chunk 最后一个有效 token 下标,公式省略 batch 和 head 下标。可选输出参数只决定是否向调用方返回对应中间量,不改变计算语义。

2.2 GVA 分组值注意力场景

当 HV>HHV>H 时为分组值注意力(Grouped Value Attention,GVA)场景:每组 HV/HHV/H 个连续 Value head 共享一个 Query/Key head;head 编号从 0 开始时,编号为 hvh_v 的 Value head 对应编号为 ⌊hv/(HV/H)⌋\lfloor h_v/(HV/H)\rfloor 的 Query/Key head。

2.3 gate 激活

令 xc,i,d=gc,i,d+dt_biasdx_{c,i,d}=g_{c,i,d}+dt\_bias_d,未传入 dt_bias 时令 dt_biasd=0dt\_bias_d=0。激活后的 gate 为:

γc,i,d={gc,i,d,use_gate_in_kernel=false,−exp⁡(Alog)softplus⁡(xc,i,d),use_gate_in_kernel=true, safe_gate=false,lower_boundsigmoid⁡(exp⁡(Alog)xc,i,d),use_gate_in_kernel=true, safe_gate=true.\gamma_{c,i,d}= \begin{cases} g_{c,i,d}, & use\_gate\_in\_kernel=false,\\ -\exp(A_{log})\operatorname{softplus}(x_{c,i,d}), & use\_gate\_in\_kernel=true,\ safe\_gate=false,\\ lower\_bound\operatorname{sigmoid}(\exp(A_{log})x_{c,i,d}), & use\_gate\_in\_kernel=true,\ safe\_gate=true. \end{cases}

即:use_gate_in_kernel=false 时,g 输入本身即为已激活的自然对数 gate;use_gate_in_kernel=true 时,g 是 raw gate,由 kernel 内部完成激活(safe_gate=false 使用 -exp(A_log)·softplus(g+dt_bias),safe_gate=true 使用有界的 lower_bound·sigmoid(exp(A_log)·(g+dt_bias)))。

2.4 chunk-local 累计 gate 与缩放

gk 为 chunk-local 的 log2 累计 gate:

gkc,i,d=1ln⁡2∑t=0iγc,t,d.gk_{c,i,d}=\frac{1}{\ln 2}\sum_{t=0}^{i}\gamma_{c,t,d}.

qg 和 kg 分别为 gate 缩放后的 Query 和 Key:

qgc,i,d=qc,i,d2gkc,i,d,kgc,i,d=kc,i,d2gkc,lc,d−gkc,i,d.qg_{c,i,d}=q_{c,i,d}2^{gk_{c,i,d}},\qquad kg_{c,i,d}=k_{c,i,d}2^{gk_{c,l_c,d}-gk_{c,i,d}}.

2.5 Aqk 与 Akk

对同一 chunk 内的 token ii、jj,Aqk 为包含对角线的下三角 Query-Key 系数矩阵:

Aqkc,i,j=1j≤i⋅scale∑dqc,i,dkc,j,d2gkc,i,d−gkc,j,d.Aqk_{c,i,j}=\mathbb{1}_{j\le i}\cdot scale \sum_d q_{c,i,d}k_{c,j,d}2^{gk_{c,i,d}-gk_{c,j,d}}.

严格下三角矩阵 LcL_c 及 Akk 为:

Lc,i,j=1j<i⋅βc,i∑dkc,i,dkc,j,d2gkc,i,d−gkc,j,d,Akkc=(I+Lc)−1.L_{c,i,j}=\mathbb{1}_{j<i}\cdot\beta_{c,i} \sum_d k_{c,i,d}k_{c,j,d}2^{gk_{c,i,d}-gk_{c,j,d}},\qquad Akk_c=(I+L_c)^{-1}.

2.6 w / u / v_new 与状态更新

令 wseedw^{seed} 和 useedu^{seed} 为:

wc,i,dseed=βc,ikc,i,d2gkc,i,d,uc,i,eseed=βc,ivc,i,e.w^{seed}_{c,i,d}=\beta_{c,i}k_{c,i,d}2^{gk_{c,i,d}},\qquad u^{seed}_{c,i,e}=\beta_{c,i}v_{c,i,e}.

w 和 u 为:

wc=Akkc wcseed,uc=Akkc ucseed.w_c=Akk_c\,w^{seed}_c,\qquad u_c=Akk_c\,u^{seed}_c.

令 hch_c 为第 cc 个 chunk 计算前的状态;传入 initial_state 时 h0=initial_stateh_0=initial\_state,否则 h0=0h_0=0。v_new 和下一个 chunk 状态为:

vcnew=uc−wc hc,v^{new}_c=u_c-w_c\,h_c,

hc+1=2gkc,lc⊙hc+kgcT vcnew,h_{c+1}=2^{gk_{c,l_c}}\odot h_c+kg_c^T\,v^{new}_c,

其中 2gkc,lc⊙hc2^{gk_{c,l_c}}\odot h_c 表示按 KK 维缩放状态矩阵。h 输出保存各个 chunk 的输入状态,final_state 为最后一个 chunk 更新后的状态:

h[c]=hc,final_state=hM.h[c]=h_c,\qquad final\_state=h_M.

2.7 attn_out 与 initial_state 透传

attn_out 为:

attn_outc=scale⋅qgc hc+Aqkc vcnew.attn\_out_c=scale\cdot qg_c\,h_c+Aqk_c\,v^{new}_c.

Python 接口的第 12 项返回值为输入对象透传:

initial_state_out=initial_state.initial\_state\_out=initial\_state.

三、参数说明

3.1 维度符号约定

符号 含义
B 输入样本 batch 大小
S rank-4 输入的序列长度
T rank-3 输入的总 token 数
H Query 和 Key 的 head 数
HV Value 和 gate 的 head 数
K Query 和 Key 的 head dim
V Value 的 head dim
N 逻辑序列数
C chunk 大小
NC 未传入 cu_seqlens 时为每条序列的 chunk 数 ⌈S/C⌉\lceil S/C\rceil;传入 cu_seqlens 时为所有逻辑序列的 chunk 总数

3.2 完整参数表

参数名 输入/输出/属性 描述 数据类型 数据格式
q 输入 公式中的 Query。BSND为(B, S, H, K),BNSD为(B, H, S, K),TND为(T, H, K),NTD为(H, T, K)。 FLOAT16、BFLOAT16 ND
k 输入 公式中的 Key。shape 和数据类型必须与 q 相同。 FLOAT16、BFLOAT16 ND
v 输入 公式中的 Value。BSND为(B, S, HV, V),BNSD为(B, HV, S, V),TND为(T, HV, V),NTD为(HV, T, V)。数据类型必须与 q 相同。 FLOAT16、BFLOAT16 ND
g 输入 raw gate 或已激活的自然对数 gate。BSND为(B, S, HV, K),BNSD为(B, HV, S, K),TND为(T, HV, K),NTD为(HV, T, K)。 FLOAT、BFLOAT16 ND
beta 输入 公式中的 Delta 系数。BSND为(B, S, HV),BNSD为(B, HV, S),TND为(T, HV),NTD为(HV, T)。 FLOAT、BFLOAT16 ND
a_log 可选输入 gate 衰减参数,shape 为(HV)。当 use_gate_in_kernel=true 时必须传入。 FLOAT ND
dt_bias 可选输入 gate 偏置,shape 为(HV×K)。 FLOAT ND
initial_state 可选输入 初始状态。state_v_first=false 时 shape 为(N, HV, K, V),否则为(N, HV, V, K)。 FLOAT ND
cu_seqlens 可选输入 变长序列累计长度,shape 为(N+1),首元素为 0,末元素为 T 或 S,元素单调不减。 INT64 ND
chunk_indices 可选输入 chunk 索引,shape 为(2×NC),按 (seq_id, chunk_id) 保存,必须采用 sequence-major canonical 顺序。传入时必须同时传入 cu_seqlens。 INT64 ND
attn_out 输出 注意力输出。rank-4 输入固定输出 BSND 格式(B, S, HV, V);rank-3 输入固定输出 TND 格式(T, HV, V)。 FLOAT16、BFLOAT16 ND
final_state 可选输出 最终状态。state_v_first=false 时 shape 为(N, HV, K, V),否则为(N, HV, V, K)。 FLOAT ND
gk 可选输出 chunk-local log2 累计 gate。rank-4 输入为(B, HV, S, K),rank-3 输入为(HV, T, K)。 FLOAT ND
Aqk 输出 chunk 内 Query-Key 系数矩阵。rank-4 输入为(B, HV, S, C),rank-3 输入为(HV, T, C)。 FLOAT16、BFLOAT16 ND
Akk 输出 chunk 内下三角求逆结果。rank-4 输入为(B, HV, S, C),rank-3 输入为(HV, T, C)。 FLOAT16、BFLOAT16 ND
w 可选输出 供反向使用的 W 中间量。rank-4 输入为(B, HV, S, K),rank-3 输入为(HV, T, K)。 FLOAT16、BFLOAT16 ND
u 可选输出 供反向使用的 U 中间量。rank-4 输入为(B, HV, S, V),rank-3 输入为(HV, T, V)。 FLOAT16、BFLOAT16 ND
qg 可选输出 供反向使用的 gate 缩放 Query。rank-4 输入为(B, HV, S, K),rank-3 输入为(HV, T, K)。 FLOAT16、BFLOAT16 ND
kg 可选输出 供反向使用的 gate 缩放 Key。rank-4 输入为(B, HV, S, K),rank-3 输入为(HV, T, K)。 FLOAT16、BFLOAT16 ND
v_new 可选输出 供反向使用的 Value 中间量。rank-4 输入为(B, HV, S, V),rank-3 输入为(HV, T, V)。 FLOAT16、BFLOAT16 ND
h 可选输出 公开 chunk 状态。rank-4 输入为(B, NC, HV, K, V),rank-3 输入为(NC, HV, K, V);state_v_first=true 时交换末两维。 FLOAT16、BFLOAT16 ND
layout 可选属性 输入布局。支持 BSND、BNSD、TND、NTD,默认值为 BSND。该属性只描述输入布局。 STRING -
scale 必选属性 Query 缩放系数。通常取 K−0.5K^{-0.5}。 FLOAT -
chunk_size 必选属性 chunk 大小。支持 64、128,默认值为 64。 INT -
safe_gate 必选属性 是否使用有界 gate。默认值为 false。 BOOL -
lower_bound 可选属性 有界 gate 下界。safe_gate=true 且 use_gate_in_kernel=true 时取值范围为[-5, 0),默认值为 -5.0。 FLOAT -
use_gate_in_kernel 必选属性 是否在 kernel 内由 raw gate 计算激活。默认值为 false。 BOOL -
state_v_first 可选属性 是否将状态张量末两维排列为 (V, K)。默认值为 false。 BOOL -

关于 layout 语义需要特别注意:layout 只描述 q、k、v、g、beta 五个输入的布局,各输出布局是固定的——attn_out 固定为 sequence-major,供反向继续计算的中间输出固定为 head-major,final_state 与公开 h 按参数表约定输出。这一点在 aclnnChunkKdaFwd.md 中也有明确说明。

从算子原型注册 chunk_kda_fwd_def.cpp 还可以看到 dtype 组合的底层约束:q/k/v 支持 FP16/BF16 的 8 种组合,g、beta 可为 FLOAT 或 BF16,而 a_log、dt_bias、initial_state、final_state、gk 固定为 FLOAT(FP32);attn_out、Aqk、Akk、w、u、qg、kg、v_new、h 与 q 保持同一数据类型。

四、Python 返回策略

cann_ops_transformer.ops.chunk_kda_fwd 固定返回 12 项,每一项的返回条件如下:

返回项 返回条件
attn_out 始终返回。
final_state output_final_state=true 时返回,否则为 None。
gk use_gate_in_kernel=false 或 disable_recompute=true 时返回,否则为 None。
Aqk 始终返回。
Akk 始终返回。
w disable_recompute=true 时返回,否则为 None。
u disable_recompute=true 时返回,否则为 None。
qg disable_recompute=true 时返回,否则为 None。
kg disable_recompute=true 时返回,否则为 None。
v_new disable_recompute=true 时返回,否则为 None。
h disable_recompute=true 或 return_intermediate_states=true 时返回,否则为 None。
initial_state 原样返回 Python 输入 initial_state,不是 aclnn 输出。

关键点:aclnn 接口不接收 output_final_state、disable_recompute 或 return_intermediate_states,L2 层只根据每个可选输出指针是否为空决定是否导出该输出。在 算子设计介绍 中进一步说明,该返回策略对齐 fla-org chunk_kda_fwd 提交 0f0f0c97af39343855b43bbbaddcedfda5cb9d77,final_state/gk/w/u/qg/kg/v_new/h 是相互独立的 OPTIONAL_OUTPUT:非空指针表示导出,空指针表示不公开该结果。

五、aclnn 接口调用

5.1 两段式接口

aclnnChunkKdaFwd 遵循 AscendCL 算子调用的两段式接口范式:必须先调用 aclnnChunkKdaFwdGetWorkspaceSize 获取计算所需 workspace 大小以及包含算子计算流程的执行器,再调用 aclnnChunkKdaFwd 执行计算。

aclnnStatus aclnnChunkKdaFwdGetWorkspaceSize(
    const aclTensor *q,
    const aclTensor *k,
    const aclTensor *v,
    const aclTensor *g,
    const aclTensor *beta,
    const aclTensor *aLogOptional,
    const aclTensor *dtBiasOptional,
    const aclTensor *initialStateOptional,
    const aclIntArray *cuSeqlensOptional,
    const aclIntArray *chunkIndicesOptional,
    const char *layout,
    double scale,
    int64_t chunkSize,
    bool safeGate,
    double lowerBound,
    bool useGateInKernel,
    bool stateVFirst,
    const aclTensor *attnOut,
    const aclTensor *finalStateOut,
    const aclTensor *gkOut,
    const aclTensor *aqkOut,
    const aclTensor *akkOut,
    const aclTensor *wOut,
    const aclTensor *uOut,
    const aclTensor *qgOut,
    const aclTensor *kgOut,
    const aclTensor *vNewOut,
    const aclTensor *hOut,
    uint64_t *workspaceSize,
    aclOpExecutor **executor)
aclnnStatus aclnnChunkKdaFwd(
    void *workspace,
    uint64_t workspaceSize,
    aclOpExecutor *executor,
    aclrtStream stream)

5.2 第一段接口关键参数

参数名 输入/输出 描述 使用说明 数据类型 维度(shape) 非连续 Tensor
q 输入 公式中的 Query。 不支持空 Tensor,shape 由 layout 解释。 FLOAT16、BFLOAT16 BSND:[B,S,H,K]
BNSD:[B,H,S,K]
TND:[T,H,K]
NTD:[H,T,K]
√
k 输入 公式中的 Key。 不支持空 Tensor。shape 和数据类型必须与 q 相同。 FLOAT16、BFLOAT16 与 q 相同 √
v 输入 公式中的 Value。 不支持空 Tensor。数据类型必须与 q 相同。 FLOAT16、BFLOAT16 BSND:[B,S,HV,V]
BNSD:[B,HV,S,V]
TND:[T,HV,V]
NTD:[HV,T,V]
√
g 输入 useGateInKernel=false 时为已激活的自然对数 gate;useGateInKernel=true 时为 raw gate。 不支持空 Tensor。 FLOAT32、BFLOAT16 BSND:[B,S,HV,K]
BNSD:[B,HV,S,K]
TND:[T,HV,K]
NTD:[HV,T,K]
√
beta 输入 公式中的 Delta 系数 β\beta。 不支持空 Tensor。 FLOAT32、BFLOAT16 BSND:[B,S,HV]
BNSD:[B,HV,S]
TND:[T,HV]
NTD:[HV,T]
√
aLogOptional 可选输入 gate 衰减参数 AlogA_{log}。 useGateInKernel=true 时必须传入;否则可以传入 nullptr。 FLOAT32 [HV] √
dtBiasOptional 可选输入 gate 偏置。 可以传入 nullptr,表示偏置为 0;仅在 useGateInKernel=true 时参与计算。 FLOAT32 [HV×K] √
initialStateOptional 可选输入 每条逻辑序列的初始状态 h0h_0。 可以传入 nullptr,表示初始状态为 0。末两维顺序由 stateVFirst 决定。 FLOAT32 stateVFirst=false:[N,HV,K,V]
stateVFirst=true:[N,HV,V,K]
√
cuSeqlensOptional 可选输入 变长序列累计长度。 可以传入 nullptr,表示定长序列。传入时元素单调不减,首元素为 0,末元素为 S 或 T;四维变长输入要求 B=1。 INT64 [N+1] -
chunkIndicesOptional 可选输入 按 (seq_id, chunk_id) 展平的 chunk 索引。 可以传入 nullptr。传入时必须同时传入 cuSeqlensOptional,并按 sequence-major canonical 顺序包含每个 chunk。 INT64 [2×NC] -
layout 输入 输入布局。 支持 BSND、BNSD、TND、NTD,区分大小写。只描述 q、k、v、g 和 beta 的布局。 STRING - -
scale 输入 Query 缩放系数。 通常取 K−0.5K^{-0.5}。 DOUBLE - -
chunkSize 输入 chunk 大小。 仅支持 64、128。 INT64 - -
safeGate 输入 是否使用有界 gate。 取值为 true 或 false。 BOOL - -
lowerBound 输入 有界 gate 下界。 safeGate=true 且 useGateInKernel=true 时,取值范围为[-5,0)。 DOUBLE - -
useGateInKernel 输入 是否在算子内由 raw gate 计算激活后的 gate。 取值为 true 或 false。 BOOL - -
stateVFirst 输入 状态张量是否使用 (V,K) 末两维顺序。 取值为 true 或 false。 BOOL - -
attnOut 输出 公式中的注意力输出。 不支持空 Tensor。数据类型必须与 q 相同,固定为 sequence-major 布局。 FLOAT16、BFLOAT16 四维输入:[B,S,HV,V]
三维输入:[T,HV,V]
×
finalStateOut 可选输出 每条逻辑序列最后一个 chunk 更新后的状态 hMh_M。 可以传入 nullptr,表示不导出该结果。末两维顺序由 stateVFirst 决定。 FLOAT32 stateVFirst=false:[N,HV,K,V]
stateVFirst=true:[N,HV,V,K]
×
gkOut 可选输出 chunk 内以 2 为底的累计 gate。 可以传入 nullptr,表示不导出该结果。固定为 head-major 布局。 FLOAT32 四维输入:[B,HV,S,K]
三维输入:[HV,T,K]
×
aqkOut 输出 chunk 内 Query-Key 系数矩阵 AqkAqk。 不支持空 Tensor。数据类型必须与 q 相同,固定为 head-major 布局。 FLOAT16、BFLOAT16 四维输入:[B,HV,S,C]
三维输入:[HV,T,C]
×
akkOut 输出 chunk 内三角求逆结果 AkkAkk。 不支持空 Tensor。数据类型必须与 q 相同,固定为 head-major 布局。 FLOAT16、BFLOAT16 四维输入:[B,HV,S,C]
三维输入:[HV,T,C]
×
wOut / uOut / qgOut / kgOut / vNewOut 可选输出 供反向使用的中间量。 可以传入 nullptr。传入时数据类型必须与 q 相同,固定为 head-major 布局。 FLOAT16、BFLOAT16 见参数表对应 shape ×
hOut 可选输出 每个 chunk 计算前的状态 hch_c。 可以传入 nullptr。传入时数据类型必须与 q 相同,固定为 sequence-major 布局,末两维顺序由 stateVFirst 决定。 FLOAT16、BFLOAT16 四维且 stateVFirst=false:[B,NC,HV,K,V];四维且 stateVFirst=true:[B,NC,HV,V,K];三维同理去掉 B ×
workspaceSize 输出 返回需要在 Device 侧申请的 workspace 大小,单位为 Byte。 - - - -
executor 输出 返回算子执行器,包含算子计算流程。 - - - -

第一段接口完成入参校验,出现以下场景时报错:

返回值 错误码 描述
ACLNN_ERR_PARAM_NULLPTR 161001 q、k、v、g、beta、attnOut、aqkOut 或 akkOut 为空指针;或者 useGateInKernel=true 时 aLogOptional 为空指针。
ACLNN_ERR_PARAM_INVALID 161002 输入或输出的 shape、数据类型、数据格式、layout、chunk 元数据或属性值不在支持范围内。

第二段接口 aclnnChunkKdaFwd 接收 workspace(Device 侧申请的内存地址,workspaceSize 为 0 时可传 nullptr)、workspaceSize、executor 和指定执行任务的 stream,同样返回 aclnnStatus 状态码,具体参见 aclnn 返回码。

5.3 完整调用示例

以下示例来自 aclnnChunkKdaFwd.md(BF16、BSND 布局、useGateInKernel=true、safeGate=true),完整代码可编译运行,编译与执行环境参考编译与运行样例:

#include <iostream>
#include <vector>
#include <cstring>
#include <cmath>
#include <cstdint>
#include <random>
#include "acl/acl.h"
#include "aclnnop/aclnn_chunk_kda_fwd.h"

using namespace std;

#define CHECK_RET(cond, return_expr) \
    do {                               \
        if (!(cond)) {                   \
            return_expr;                   \
        }                                \
    } while (0)

#define LOG_PRINT(message, ...)     \
    do {                              \
        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) {
    // 固定写法,AscendCL初始化
    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;
}

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("CreateAclTensor: ERROR - shape is empty\n");
        return -1;
    }
    for (size_t i = 0; i < shape.size(); ++i) {
        if (shape[i] <= 0) {
            LOG_PRINT("CreateAclTensor: ERROR - shape[%zu]=%ld is invalid\n", i, shape[i]);
            return -1;
        }
    }
    auto size = GetShapeSize(shape) * sizeof(T);
    if (hostData.size() != static_cast<size_t>(GetShapeSize(shape))) {
        LOG_PRINT("CreateAclTensor: ERROR - 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);
    // 计算连续tensor的strides
    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 - returned nullptr\n");
              aclrtFree(*deviceAddr); *deviceAddr = nullptr; return -1);
    return 0;
}

float Bf16ToFloat(int16_t value) {
    // bfloat16转float:低16位补0后按float解释
    uint32_t bits = static_cast<uint32_t>(static_cast<uint16_t>(value)) << 16;
    float result;
    memcpy(&result, &bits, sizeof(result));
    return result;
}

int16_t FloatToBf16(float value) {
    // float转bfloat16:就近舍入后取高16位
    uint32_t bits;
    memcpy(&bits, &value, sizeof(bits));
    uint32_t rounded = bits + 0x7FFF + ((bits >> 16) & 1);
    return static_cast<int16_t>(rounded >> 16);
}

float Sigmoid(float value) {
    return 1.0f / (1.0f + std::exp(-value));
}

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. 构造输入与输出
    int64_t batch = 1;
    int64_t seqLen = 64;
    int64_t headNum = 2;
    int64_t headDim = 128;
    int64_t chunkSize = 64;

    std::vector<int64_t> qkShape = {batch, seqLen, headNum, headDim};       // BSND
    std::vector<int64_t> vShape = {batch, seqLen, headNum, headDim};        // BSND
    std::vector<int64_t> gShape = {batch, seqLen, headNum, headDim};        // BSND
    std::vector<int64_t> betaShape = {batch, seqLen, headNum};              // BSND
    std::vector<int64_t> attnOutShape = {batch, seqLen, headNum, headDim};  // BSND
    std::vector<int64_t> aqkShape = {batch, headNum, seqLen, chunkSize};    // (B, HV, S, C)
    std::vector<int64_t> akkShape = aqkShape;
    std::vector<int64_t> aLogShape = {headNum};                             // (HV,)
    std::vector<int64_t> dtBiasShape = {headNum * headDim};                 // (HV*K,)

    // 使用固定种子生成小随机数作为输入,与pytest数据构造保持一致
    std::mt19937 gen(20260808);
    std::normal_distribution<float> dist(0.0f, 1.0f);
    std::vector<int16_t> qHostData(GetShapeSize(qkShape));
    std::vector<int16_t> kHostData(GetShapeSize(qkShape));
    std::vector<int16_t> vHostData(GetShapeSize(vShape));
    std::vector<float> gHostData(GetShapeSize(gShape));
    std::vector<float> betaHostData(GetShapeSize(betaShape));
    for (size_t i = 0; i < qHostData.size(); i++) {
        qHostData[i] = FloatToBf16(dist(gen) * 0.05f);
        kHostData[i] = FloatToBf16(dist(gen) * 0.05f);
        vHostData[i] = FloatToBf16(dist(gen) * 0.05f);
        gHostData[i] = dist(gen) * 0.02f - 0.5f;
        betaHostData[i] = Sigmoid(dist(gen));
    }
    std::vector<float> aLogHostData = {-0.5f, 0.5f};
    std::vector<float> dtBiasHostData(GetShapeSize(dtBiasShape));
    for (int64_t i = 0; i < static_cast<int64_t>(dtBiasHostData.size()); i++) {
        dtBiasHostData[i] = -0.1f + 0.2f * static_cast<float>(i) / static_cast<float>(dtBiasHostData.size() - 1);
    }
    std::vector<int16_t> attnOutHostData(GetShapeSize(attnOutShape), 0);
    std::vector<int16_t> aqkHostData(GetShapeSize(aqkShape), 0);
    std::vector<int16_t> akkHostData(GetShapeSize(akkShape), 0);

    // 3. 创建输入输出tensor
    void* qAddr = nullptr;
    void* kAddr = nullptr;
    void* vAddr = nullptr;
    void* gAddr = nullptr;
    void* betaAddr = nullptr;
    void* aLogAddr = nullptr;
    void* dtBiasAddr = nullptr;
    void* attnOutAddr = nullptr;
    void* aqkAddr = nullptr;
    void* akkAddr = nullptr;
    void* workspaceAddr = nullptr;

    aclTensor* qTensor = nullptr;
    aclTensor* kTensor = nullptr;
    aclTensor* vTensor = nullptr;
    aclTensor* gTensor = nullptr;
    aclTensor* betaTensor = nullptr;
    aclTensor* aLogTensor = nullptr;
    aclTensor* dtBiasTensor = nullptr;
    aclTensor* attnOutTensor = nullptr;
    aclTensor* aqkTensor = nullptr;
    aclTensor* akkTensor = nullptr;

    ret = CreateAclTensor(qHostData, qkShape, &qAddr, ACL_BF16, &qTensor);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("create q tensor failed\n"); return ret);
    ret = CreateAclTensor(kHostData, qkShape, &kAddr, ACL_BF16, &kTensor);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("create k tensor failed\n"); return ret);
    ret = CreateAclTensor(vHostData, vShape, &vAddr, ACL_BF16, &vTensor);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("create v tensor failed\n"); return ret);
    ret = CreateAclTensor(gHostData, gShape, &gAddr, ACL_FLOAT, &gTensor);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("create g tensor failed\n"); return ret);
    ret = CreateAclTensor(betaHostData, betaShape, &betaAddr, ACL_FLOAT, &betaTensor);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("create beta tensor failed\n"); return ret);
    ret = CreateAclTensor(aLogHostData, aLogShape, &aLogAddr, ACL_FLOAT, &aLogTensor);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("create aLog tensor failed\n"); return ret);
    ret = CreateAclTensor(dtBiasHostData, dtBiasShape, &dtBiasAddr, ACL_FLOAT, &dtBiasTensor);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("create dtBias tensor failed\n"); return ret);
    ret = CreateAclTensor(attnOutHostData, attnOutShape, &attnOutAddr, ACL_BF16, &attnOutTensor);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("create attnOut tensor failed\n"); return ret);
    ret = CreateAclTensor(aqkHostData, aqkShape, &aqkAddr, ACL_BF16, &aqkTensor);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("create aqk tensor failed\n"); return ret);
    ret = CreateAclTensor(akkHostData, akkShape, &akkAddr, ACL_BF16, &akkTensor);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("create akk tensor failed\n"); return ret);

    // 4. 调用第一段接口: 计算workspace大小
    uint64_t workspaceSize = 0;
    aclOpExecutor* executor = nullptr;
    ret = aclnnChunkKdaFwdGetWorkspaceSize(
        qTensor,
        kTensor,
        vTensor,
        gTensor,
        betaTensor,
        aLogTensor,
        dtBiasTensor,
        nullptr,  // initialStateOptional
        nullptr,  // cuSeqlensOptional
        nullptr,  // chunkIndicesOptional
        "BSND",
        1.0 / std::sqrt(static_cast<double>(headDim)),
        chunkSize,
        true,   // safeGate
        -5.0,   // lowerBound
        true,   // useGateInKernel
        false,  // stateVFirst
        attnOutTensor,
        nullptr,  // finalStateOut
        nullptr,  // gkOut
        aqkTensor,
        akkTensor,
        nullptr,  // wOut
        nullptr,  // uOut
        nullptr,  // qgOut
        nullptr,  // kgOut
        nullptr,  // vNewOut
        nullptr,  // hOut
        &workspaceSize,
        &executor
    );
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("GetWorkspaceSize failed. ERROR: %d\n", ret); return ret);
    LOG_PRINT("Workspace size required: %lu bytes\n", workspaceSize);

    // 5. 分配workspace
    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);
    }

    // 6. 调用第二段接口: 执行计算
    LOG_PRINT("Calling aclnnChunkKdaFwd...\n");
    ret = aclnnChunkKdaFwd(workspaceAddr, workspaceSize, executor, stream);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnChunkKdaFwd failed. ERROR: %d\n", ret); return ret);

    // 7. 同步Stream,等待任务执行结束
    ret = aclrtSynchronizeStream(stream);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSynchronizeStream failed. ERROR: %d\n", ret); return ret);

    // 8. 将结果拷贝回Host侧打印
    ret = aclrtMemcpy(attnOutHostData.data(), attnOutHostData.size() * sizeof(int16_t), attnOutAddr,
                      attnOutHostData.size() * sizeof(int16_t), ACL_MEMCPY_DEVICE_TO_HOST);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("copy result from device to host failed.\n"); return ret);

    LOG_PRINT("Execution Success! Output results (first 5 elements of attnOut):\n");
    for (uint64_t i = 0; i < 5 && i < attnOutHostData.size(); i++) {
        LOG_PRINT("  attnOut index %lu: %f\n", i, Bf16ToFloat(attnOutHostData[i]));
    }

    // 9. 释放所有资源
    aclDestroyTensor(qTensor); aclDestroyTensor(kTensor);
    aclDestroyTensor(vTensor); aclDestroyTensor(gTensor);
    aclDestroyTensor(betaTensor); aclDestroyTensor(aLogTensor);
    aclDestroyTensor(dtBiasTensor); aclDestroyTensor(attnOutTensor);
    aclDestroyTensor(aqkTensor); aclDestroyTensor(akkTensor);
    if (qAddr) aclrtFree(qAddr);
    if (kAddr) aclrtFree(kAddr);
    if (vAddr) aclrtFree(vAddr);
    if (gAddr) aclrtFree(gAddr);
    if (betaAddr) aclrtFree(betaAddr);
    if (aLogAddr) aclrtFree(aLogAddr);
    if (dtBiasAddr) aclrtFree(dtBiasAddr);
    if (attnOutAddr) aclrtFree(attnOutAddr);
    if (aqkAddr) aclrtFree(aqkAddr);
    if (akkAddr) aclrtFree(akkAddr);
    if (workspaceAddr) aclrtFree(workspaceAddr);
    aclrtDestroyStream(stream);
    aclrtResetDevice(deviceId);
    aclFinalize();

    LOG_PRINT("ChunkKdaFwd Test completed successfully!\n");
    return 0;
}

示例要点:

  • 数据构造与 pytest 保持一致(固定种子 20260808 的小随机数、beta=Sigmoid),便于与 test_chunk_kda_fwd.py 交叉核对;
  • aqkOut/akkOut 的 shape 为 (B, HV, S, C),是 head-major 的公开输出;
  • initialStateOptional、cuSeqlensOptional、chunkIndicesOptional 以及各类可选输出均可传 nullptr,由指针是否非空决定是否导出。

六、约束说明

  • H 和 HV 必须为正整数,且满足 HV≥H、HV≤128、HV % H=0。
  • K 和 V 取值范围为 [16, 256],且必须为 16 的倍数。
  • chunk_size 仅支持 64 和 128。
  • q、k、v 的数据类型必须相同。
  • use_gate_in_kernel=true 时,a_log 必须传入;dt_bias 可以不传入。
  • safe_gate=true 且 use_gate_in_kernel=true 时,lower_bound 取值范围为 [-5, 0)。
  • rank-4 变长输入要求 B=1。
  • 变长输入最多支持 1024 条逻辑序列。
  • layout 只描述输入。attn_out 固定为 sequence-major;供反向继续计算的中间输出固定为 head-major;final_state 和公开 h 按参数表约定输出。
  • 默认支持确定性计算:同一输入重复执行,attn_out/final_state/Aqk/Akk 二进制一致。

从 tiling 源码 chunk_kda_fwd_tiling.cpp 可以看到这些约束在 host 侧的落地:ResolveShape 校验 q/v rank 一致(仅支持 3/4 维)、HV % H == 0;ResolveSequenceInfo 校验 cu_seqlens 首元素为 0、单调不减且末元素不超过 seqlen,并根据每条序列长度累加 totalChunks,同时校验 chunk_indices 的 shape 恰好为 2 × totalChunks。

七、kernel 内部计算阶段与接口分层

7.1 接口分层

ChunkKdaFwd 是一个单一 L0 算子,内部由多个计算阶段组成:

raw g -> ChunkKdaFwd[
    gate cumsum -> Prepare/Post-WU -> FwdH -> Finalize
] -> attn_out

调用链按层级划分为:

cann_ops_transformer.ops.chunk_kda_fwd
  -> PyTorch C++ extension wrapper
  -> aclnnChunkKdaFwd
  -> ChunkKdaFwd L0 注册与 launcher
  -> chunk_kda_fwd device kernel launch 入口
  -> Gate / Prepare / Post-WU / FwdH / Finalize 内部阶段

Gate、Prepare、Post-WU、FwdH 和 Finalize 只是 kernel 内部计算阶段,不注册 ChunkKdaFwdPrepare、ChunkKdaFwdPostWu 或 ChunkKdaFwdFinalize 等独立 L0 算子。模板选择所需信息均由既有输入、shape 和属性推导,不增加公开属性或接口字段。这在 L0 launcher 实现 中可见:KdaChunkForward 将 cu_seqlens/chunk_indices 转为 ND tensor 后,通过 ADD_TO_LAUNCHER_LIST_AICORE 一次性提交 ChunkKdaFwd 的 10 个输入、11 个输出与 6 个属性。

7.2 各阶段计算职责

阶段 读取 产生 说明
Gate Cumsum raw/已激活 g、可选 a_log/dt_bias gk(FP32 chunk-local log2 累计值) gamma 按 use_gate_in_kernel/safe_gate 分三支计算,随后 gk = chunk_local_cumsum(gamma) / ln(2)
Prepare q/k/v/gk/beta 及变长元数据 Aqk、Akk、qg、w_seed、u_seed qg=q·exp2(gk),w_seed=beta·k·exp2(gk),u_seed=beta·v;score 点积以 BF16/FP16 为输入、FP32 累积
Post-WU k/gk/w_seed/Akk/u_seed w、u、kg w=Akk@w_seed,u=Akk@u_seed,kg=k·exp2(gk_last-gk)
FwdH kg/w/u/gk、可选 initial_state v_new、h_next、final_state v_new=u-w@h_prev,h_next=exp2(gk_last)·h_prev+kg^T@v_new
Finalize qg/Aqk/v_new/h attn_out attn_out = scale·(qg@h) + Aqk@v_new,FP32 累积

几个值得注意的实现细节:

  • Akk 的数值路径:Akk=(I+L)^{-1} 的 LL、单位阵、对角块求逆、分块合并、Cube 输入/累积和 workspace 均为 FP32,并显式关闭 HF32;只在完整 FP32 求解结束后将公开 Akk 写回为 q dtype。
  • Post-WU 的阶段归属由 tiling 决定:满足 A5 dense-aligned 融合条件时,Prepare 直接调用 Post-WU 计算组件;其他场景在 Prepare 结束并完成同步后执行内部 Post-WU 阶段。两种方式复用同一 L0 调用接口。
  • 跨 chunk 状态固定 FP32:跨 chunk 的 h_prev/h_next 保存在 FP32 workspace 或 FP32 final_state 中;公开 h 仅作为反向保存快照按 q dtype 写回,不能反向参与下一 chunk 的状态更新。
  • GVA 的 head 映射:Akk 的 head 循环按 H_v 执行,GVA 映射只在读取 q/k head 时换算(floor(h_v/(HV/H))),避免按 H_k 重复或漏算。
  • Finalize 的 scale 施加时机:scale 在第一项完成 FP32 点积后施加,不预先量化进 BF16 qg;kernel 内直接按 BSND/TND 写出 attn_out,供反向使用的中间量保持 BNSD/NTD。

八、数值设计与输出布局

8.1 数值设计

  • q、k、v 和公式中以输入 dtype 保存的中间量作为矩阵乘输入,矩阵乘使用 FP32 累加。
  • Akk=(I+L)^{-1} 的 LL、单位阵、对角块求逆、分块合并、Cube 输入和累加保持 FP32,不启用 HF32。
  • chunk 间状态 hch_c 和 final_state 的计算保持 FP32,不使用公开 h 的低精度快照继续下一个 chunk 的状态传播。
  • attn_out 的两项矩阵乘和加法使用 FP32 累加,在最终写回时转为输出 dtype。

8.2 状态布局与重计算

  • 内部状态统一使用 [...,K,V]。state_v_first=true 时,L2 在进入 FwdH 前转置 initial state。
  • 内部 hCompute 始终保持 head-major 供 Finalize 消费;公开 hOut 在 L2 导出边界转为 sequence-major,并按 state_v_first 决定末两维顺序。final_state 按序列排列。
  • 内部 hCompute 与公开 hOut 是两个生命周期:hOut 为空时由 kernel workspace 承接,非空时 L2 提供 head-major 临时输出并在导出边界转置。
  • arch35 快路径为隐藏输出传递固定 ABI 占位,并由 tiling 在 kernel workspace 中承接实际中间结果;通用路径使用同一规则,公开输出存在时直接作为内部目标使用。

九、Tiling 设计与平台特化

9.1 编译期 shape 模板

tiling key 编译期常量 A2/A3 实现 A5 实现 覆盖场景
key=1 通用 shape 模板 COMPILE_BT/K/V=0/0/0 根目录通用实现 根目录通用实现 不满足 chunk=64,K=128,V=128 的 dense、tail、varlen、GVA 等场景
key=2 chunk64/K128/V128 模板 COMPILE_BT/K/V=64/128/128 根目录通用实现,使用编译期常量 arch35 特化实现 chunk=64,K=V=128 的 dense、tail、varlen 和不同 head 数

tiling 源码中 useChunk64K128V128Template = chunkSize == 64 && kDim == 128 && vDim == 128 决定了 tiling key 的取值(见 chunk_kda_fwd_tiling.cpp)。SetTilingKey 只检查 chunk、K、V,不检查 SoC、layout、是否 varlen 或是否存在尾块,因此 tiling key 表示 shape 模板族而非平台/接口/算子版本,平台差异由同一 key 编译时的架构分支选择。

9.2 A5 arch35 执行组合

ConfigureChunkKdaFwdArch35(arch35 tiling 实现)从既有输入输出实例化状态派生内部选项,选项不属于公开属性:

执行组合 选择条件 内部阶段顺序
standalone Gate computeGateInPrepare=false Gate 完整执行并同步,再进入 Prepare
Prepare 内联 Gate BF16 q/k/v、raw g 为 FP32、存在 A_log、use_gate_in_kernel=true、safe_gate=true Prepare AIV 在 gate-product 流水中计算 chunk-local gk
A5 dense FwdH BF16 且非 varlen、T % 64 == 0 使用 ChunkKdaFwdFwdH arch35 dense 模板
Prepare/Post-WU 阶段内流水融合 A5 key2、BF16、safe_gate=true、dense-aligned、H_v % 2 == 0,且未选择下一行模板 Prepare AIC 按 head pair 生产后,直接调用 Post-WU 组件分批消费
Post-WU/FwdH 阶段内流水融合 上一行条件成立,同时 Gate 已在 Prepare 内计算,且不导出 qg/v_new/h dense FwdH 直接完成 W/U 和状态传播所需计算
独立内部 Post-WU 阶段 上述两种 Post-WU 融合均未选择 Prepare 完成同步后调用 RunChunkKdaPostWu
通用 FwdH backend FP16、varlen、存在非对齐尾块或不满足 dense FwdH 条件 选择 KDA 私有 KdaFwdHTileShapes128/256 模板

特别说明:"Prepare/Post-WU 融合"只描述满足表中条件的执行组合,不代表所有 key2 场景都取消了内部 Post-WU 阶段——varlen 和非对齐尾块使用独立内部 Post-WU 阶段。arch35 dense FwdH 的 state、W 和 v_new L1 slot 使用 ready/free credit 保护复用,AIV 在最后一个 task 完成后显式消费 AIC 返还的 terminal free credit 再退出 kernel,避免未消费 credit 进入后续执行。

9.3 尾块与 sub-16 特化

Post-WU 与 Finalize 在 arch35 上针对尾块做了细化:16<=curT<64 使用 padded Cube 与按有效行写回;BF16 的 1<=curT<16 使用 regbase 路径(ComputeTailWuRegbaseArch35 / ComputeTailOutputRegbaseRows)一次性暂存所需数据、单次 MTE2-to-V 交接后以 FP32 regbase 直接累加,绕开尾块标量 EventID 链。其中 Post-WU sub-16 模板最坏 staging 为 2*15*128*sizeof(BF16)+15*64*sizeof(BF16)=9,600 B,Finalize sub-16 模板最坏 staging 为 40,928 B,小于现有 gateWritebackBuf_ 在 key2 BF16 下的 40,960 B,因此阈值固定为 16 而非运行时试探。

所有模板保持相同的公式、公开输出顺序、可选输出语义和 layout 契约;模板选择不得改变 ChunkKdaFwd L0、aclnnChunkKdaFwd 或 cann_ops_transformer.ops.chunk_kda_fwd 的接口。

9.4 流水设计要点

  • Prepare 的右矩阵在 L1 驻留,避免 K/K^T 重复搬运和重复转置。
  • AIC 使用 L1/L0 双缓冲组织 MTE2、MTE1、Cube、Fixpipe;AIV 使用输入 staging ping-pong,使下一 tile MTE2 与当前 tile VEC 重叠。
  • A5 VEC 路径使用 regbase 双发射;数值主计算仍保持 FP32。
  • inter-sub-chunk 合并使用独立 workspace 区域,避免阻塞主 tile 流水。

十、测试与验证

测试框架位于 tests/pytest,基于 pytest 和 msopprof 实现功能、一致性、确定性和性能验证,覆盖四种输入布局、可选输出矩阵(默认 / return_intermediate_states=True / disable_recompute=True)、BF16 gate 参数提升、变长序列尾块(NTD、cu_seqlens=[0,64,65]、尾块长度 1)以及 state_v_first 两种状态布局。

在 ops-transformer 仓根目录执行:

# 运行功能用例(含跨布局一致性、可选输出矩阵、BF16参数提升、变长尾块、state_v_first)
python3 -m pytest -rA -s \
  attention/chunk_kda_fwd/tests/pytest/test_chunk_kda_fwd.py \
  -v
# 运行50次二进制确定性验证(比较 attn_out/final_state/Aqk/Akk)
python3 attention/chunk_kda_fwd/tests/pytest/profile_a5_h96_t16k.py \
  --check-determinism \
  --determinism-repeats 50

A5 关键场景(BF16、BSND、B=1、S=16384、H=HV=96、K=V=128、chunk_size=64、safe_gate=True、use_gate_in_kernel=True)性能验证:

mkdir -m 700 -p output/chunk_kda_fwd_profiles

# 采集 ChunkKdaFwd 主 kernel
msopprof \
  --application="python3 attention/chunk_kda_fwd/tests/pytest/profile_a5_h96_t16k.py --repeats 8" \
  --output=output/chunk_kda_fwd_profiles/a5_h96_t16k \
  --aic-metrics=BasicInfo \
  --kernel-name=ChunkKdaFwd \
  --launch-count=5 \
  --warm-up=3 \
  --kill=off

# 采集 BSND beta 布局转换 kernel
msopprof \
  --application="python3 attention/chunk_kda_fwd/tests/pytest/profile_a5_h96_t16k.py --repeats 8" \
  --output=output/chunk_kda_fwd_profiles/a5_h96_t16k_beta \
  --aic-metrics=BasicInfo \
  --kernel-name=Transpose_float16_int64_high_performance_10001 \
  --launch-count=5 \
  --warm-up=3 \
  --kill=off

# 校验端到端 device 侧耗时(主 kernel 与 beta 布局转换 kernel 有效样本最大值之和,上限 11 ms)
python3 attention/chunk_kda_fwd/tests/pytest/check_msopprof.py \
  output/chunk_kda_fwd_profiles/a5_h96_t16k \
  --component Transpose_float16_int64_high_performance_10001 \
    output/chunk_kda_fwd_profiles/a5_h96_t16k_beta \
  --max-ms 11

性能结论只使用 msopprof 采集的 device 侧耗时,不使用 Python wall time;门禁合计超过 11 ms 或任一组件未采集到有效样本即失败。功能用例层面,test_chunk_kda_fwd.py 的 test_optional_output_matrix 按 {0,1,3,4}(默认)、{0,1,3,4,10}(return_intermediate_states=True)与 set(range(11))(disable_recompute=True)三种模式逐一断言 12 个返回项是否物化,与第四节返回策略一一对应;test_varlen_tail_with_host_cu_seqlens 验证 cu_seqlens=[0,64,65] 时输出 shape 为 (65,2,128) 与 (2,2,128,128)。

完整验证矩阵覆盖:平台 A2/A3/A5,dtype FP16/BF16,layout BSND/BNSD/TND/NTD,gate raw/已激活与 safe true/false,shape K=128、V=128/256、chunk=64/128、dense/varlen/tail/GVA,属性 final state、重计算策略与 state_v_first。

十一、总结

ChunkKdaFwd 以"单一 L0 算子 + 内部多阶段流水(Gate Cumsum → Prepare → Post-WU → FwdH → Finalize)"的结构实现 KDA 分块正向计算,通过可选输出指针的置空与否灵活控制反向重计算所需的中间量导出,并以固定 12 项返回的 Python 接口对齐非 CP 的 FLA chunk_kda_fwd 语义。其数学核心在于 chunk-local log2 累计 gate 驱动的 qg/kg 缩放、Akk=(I+L)^{-1} 三角求逆、以及 v_new = u - w·h 与 h_next = exp2(gk_last)·h + kg^T·v_new 的逐 chunk 状态传播;工程实现上以 FP32 贯穿 Akk 求解、跨 chunk 状态与 attn_out 累加,确保数值精度,同时在 A5 上通过 regbase 双发射、head-pair 融合、dense FwdH 与 sub-16 尾块特化等模板覆盖全场景性能。读者可进一步阅读 ChunkKdaFwd 算子设计介绍 获取完整 tiling 模板表,或直接基于 pytest 测试框架 在本地复现功能与性能验证。

登录后查看全文
ops-transformer