CANN ascend-transformer-boost 训练侧 FastSoftMax 算子全解析:源码路径、参数约束与执行链路
CANN ascend-transformer-boost 训练侧 FastSoftMax 算子全解析:源码路径、参数约束与执行链路
FastSoftMax 是 CANN ascend-transformer-boost 中面向训练场景的 Softmax 融合算子,专门处理 unpad 后的 QK^T 分数矩阵,在 Atlas 800I A2 推理产品上以 fp16 输入、fp32 累加精度完成逐样本的 Softmax 归一化。本文以知识库路由文档 .agent/knowledge/routing/fast_soft_max.md 为主线,结合其引出的知识条目与仓库源码,完整梳理该算子的文件清单、推荐阅读路径、参数定义与约束、数据布局、Operation → OpsRunner → Kernel 的完整执行链路以及多核 tiling 与片上流水实现,帮助读者在数分钟内定位代码并理解其运行原理。
1. 算子定位:一个训练侧的 Unpad Softmax
从知识库主索引 .agent/knowledge/README.md 可以看到,FastSoftMax 被归入 activation(激活/量化)分类,属于训练算子(train)、复杂度 Tier 为 S(简单算子,4 个文件)、无 ACLNN 路径,其知识条目标记为已完整提取(状态 complete)。
- 功能:将 unpad 处理后的 Q 矩阵与 K 矩阵相乘的结果(即 QK^T 分数)做 Softmax 处理;
- 适用产品:仅支持 Atlas 800I A2 推理产品(源码中通过
Is910B()判定,见下文参数校验); - 计算语义:unpad QK scores → Softmax(fp32 累加)→ 输出;
- 关联算子:
fast_soft_max_grad(反向传播)、self_attention(包含 Softmax 阶段,属推理侧复合算子)。
需要特别说明的是,路由文档原始标注的 Kernel 目录为
src/kernels/mixkernels/laser_attention,经核对仓库实际源码,该算子的 Kernel 实现在src/kernels/mixkernels/fastsoftmax/目录下(laser_attention是另一个独立算子的 Kernel),本文以实际源码路径为准。
2. 文件清单与推荐阅读顺序
路由文档给出了该算子的完整文件清单(共 4 个文件),全部位于 src/ops/ops_train/fast_soft_max/:
| # | 文件 | 角色 |
|---|---|---|
| 1 | fastsoftmax_operation.cpp |
Operation 定义 |
| 2 | fastsoftmax_operation.h |
Operation 定义 |
| 3 | fastsoftmax_ops_runner.cpp |
Ops Runner |
| 4 | fastsoftmax_ops_runner.h |
Ops Runner |
推荐按以下顺序阅读,从接口签名一路深入到执行细节:
| 顺序 | 文件 | 重点关注 |
|---|---|---|
| 1 | fastsoftmax_operation.h |
了解输入输出数量、InferShape 签名 |
| 2 | fastsoftmax_operation.cpp |
CreateRunner() 决策逻辑 |
| 3 | fastsoftmax_ops_runner.h |
原生 Ops 执行接口 |
| 4 | fastsoftmax_ops_runner.cpp |
原生 Ops 调用链 + 平台适配 |
该算子的源码分布遵循知识库中的标准定位模式:
- Op 目录:
src/ops/ops_train/fast_soft_max/(训练算子统一放在ops_train下) - Kernel 目录:
src/kernels/mixkernels/fastsoftmax/(融合 Kernel 统一放在mixkernels下) - 参数头文件:
include/atb/train_op_params.h(训练算子的参数结构体统一声明于此) - 知识条目:详细知识条目见 .agent/knowledge/ops/activation/fast_soft_max/index.md
3. 参数定义与约束
FastSoftMax 的参数结构体 FastSoftMaxParam 定义在 include/atb/train_op_params.h:
//! \brief 将unpad处理后的Q矩阵和K矩阵相乘的结果做Softmax处理。当前只支持仅Atlas 800I A2推理产品。
//! \warning seqLen数组长度不超过32,且要求各元素大于0。
struct FastSoftMaxParam {
//! \brief Attention的head数量。
int32_t headNum = 0;
//! \brief 每个batch的实际输入长度。元素个数为batchSize,最大不超过32
std::vector<int32_t> qSeqLen;
//! \brief 预留参数
uint8_t rsv[8] = {0};
};
| 字段 | 类型 | 含义 | 约束 |
|---|---|---|---|
headNum |
int32 | Attention 的 head 数量 | 必须大于 0 |
qSeqLen |
vector<int32> | 每个 batch 样本的实际输入长度(unpad 后的真实序列长度) | 元素个数即 batchSize,≤ 32,且每个元素 > 0 |
rsv[8] |
uint8[8] | 预留参数 | 恒为 0 |
operator== 仅比较 headNum 与 qSeqLen,rsv 不参与参数相等性判断——这意味着只要这两个核心参数未变化,Runner 不会触发参数更新逻辑。
3.1 参数校验逻辑
fastsoftmax_operation.cpp 中的 ParamCheck 函数(src/ops/ops_train/fast_soft_max/fastsoftmax_operation.cpp)依次执行四道校验:
- 平台校验:通过
GetSingleton<atb::Config>().Is910B()判定,非 Atlas 800I A2 推理产品直接报错,错误信息为 "FastSoftMaxOperation is only supported in Atlas 800I A2 inference product."; - 序列长度校验:调用
OperationUtil::QSeqLenCheck(opParam.qSeqLen, MAX_SEQLEN),其中MAX_SEQLEN = 4096,即每个样本的序列长度不得超过 4096; - head 数量校验:
headNum <= 0时报错; - 溢出校验:计算
nSquareToken = Σ(qSeqLen[i]²),若nSquareToken * headNum超出 int64 上限则报溢出错误,防止后续索引计算溢出。
Kernel 侧的 Mki Operation(src/kernels/mixkernels/fastsoftmax/fastsoftmax_operation.cpp)在 CheckUnpadFastSoftMax 中补充了更细的输入约束:
qSeqLen.size() > 0且≤ 32(对应MAX_BATCH_SIZE);- 每个
sampleSeqLen满足0 < sampleSeqLen ≤ 4096; - 输入 dtype 必须为 float16,format 必须为 ND,且为一维张量;
- 输入第一维大小必须严格等于
nSquareToken * headNum。
4. 数据布局与计算语义
这是理解该算子的关键:由于输入是 unpad 后的稠密一维数据,不同 batch 样本的序列长度不同,因此整个输入张量按"样本拼接"的方式排布。
4.1 输入张量排布
设 batchSize 个样本的序列长度为 seqLen[0], seqLen[1], ..., seqLen[batchSize-1],head 数为 headNum,则输入是一维 Tensor,总长度为:
total = Σ (headNum * seqLen[i] * seqLen[i]) (i = 0 .. batchSize-1)
第 i 个样本的数据在张量中的偏移为 Σ(headNum * seqLen[j]²)(j < i),长度恰为 headNum * seqLen[i]²——这正是该样本所有 head 的 QK^T 分数矩阵(每个 head 一个 seqLen[i] × seqLen[i] 的方阵)按行展开后的结果。
这一排布在 Operation 层(fastsoftmax_operation.cpp)与 Tiling 层(fastsoftmax_tiling.cpp)中被重复计算并严格校验:dataLength = headNum * seqLen²、dataOffset 为累加偏移。
4.2 计算流程
Pipeline 为:unpad QK scores → Softmax(fp32 累加)→ 输出。即对每个样本的每个 head,对其 seqLen × seqLen 的分数矩阵在最后一维(行方向)上做 Softmax,累加过程使用 fp32 精度以保证数值稳定性,最终结果仍以 fp16 输出。
4.3 Golden 参考实现
仓库测试 tests/apitest/opstest/python/operations/fast_soft_max/test_fastsoftmax_operation.py 中的 golden_calc 用 PyTorch 精确复现了这一语义:
def golden_calc(self, in_tensors):
data_input = in_tensors[0]
seq_len_list = OP_PARAM['qSeqLen']
head_num_imm = OP_PARAM['headNum']
golden = torch.empty_like(data_input)
start = 0
for i in range(len(seq_len_list)):
end = start + head_num_imm * seq_len_list[i] * seq_len_list[i]
cur_data_input = data_input[start:end].reshape(-1, seq_len_list[i])
cur_golden = torch.softmax(cur_data_input.to(torch.float32), dim=-1).to(torch.float16)
golden[start:end] = cur_golden.reshape(-1)
start = end
return [golden]
注意 golden 中先 to(torch.float32) 做 Softmax、再转回 torch.float16,与算子 "fp32 累加、fp16 输出" 的语义一一对应。测试用例仅当 soc_version == 'Ascend910B' 时执行,与 Operation 层 Is910B() 的平台限制完全吻合;测试覆盖了 batch=4/head=8 的首次执行与 batch=6 的 update_param 动态改参场景。
5. 执行链路:Operation → OpsRunner → Mki Kernel
该算子属于知识库中标注的 "OpsRunner, Operation" 双组件模式,无 ACLNN 路径。整体调用链为:用户侧 Operation → RunnerPool 分配 OpsRunner → 构建 Mki Kernel Graph → 平台调度执行 Kernel。
5.1 Operation 层(对外接口)
FastSoftMaxOperation 继承自 OperationBase(fastsoftmax_operation.h),对外暴露:
GetInputNum()/GetOutputNum():均为 1;InferShapeImpl:输出 Tensor 形状直接拷贝输入(fastsoftmax_operation.cpp),即输出与输入同形状;InferShapeCheckImpl/SetupCheckImpl:执行输入输出一致性校验(输入 1 维、dims[0] == nSquareToken * headNum、输出与输入同大小);CreateRunner:决策逻辑所在,见下文;SetParam:参数更新时置空runner_强制重建。
5.2 CreateRunner 决策逻辑
CreateRunner(fastsoftmax_operation.cpp)是路由文档要求重点关注的逻辑:
std::shared_ptr<Runner> FastSoftMaxOperation::CreateRunner(Context &context) const
{
ContextBase *contextBase = dynamic_cast<ContextBase *>(&context);
if (!contextBase) {
return nullptr;
}
int64_t runnerTypeIdx = RunnerTypeRegister::GetRunnerTypeIdx("FastSoftMaxOpsRunner");
RunnerPool &pool = contextBase->GetRunnerPool(runnerTypeIdx);
Runner *runner = pool.MallocRunner<FastSoftMaxOpsRunner, train::FastSoftMaxParam>(param_);
if (!runner) {
return std::make_shared<FastSoftMaxOpsRunner>(param_);
}
return std::shared_ptr<Runner>(runner, &pool { pool.FreeRunner(runner); });
}
其核心是通过 RunnerPool 复用 Runner 实例:按 FastSoftMaxOpsRunner 注册名获取 Runner 类型索引,从 ContextBase 的 RunnerPool 中申请实例,失败时才退化为直接 make_shared 新建;归还时通过自定义 deleter 将 Runner 释放回池中,避免反复创建销毁的开销。
5.3 OpsRunner 层(原生 Ops 调用链)
FastSoftMaxOpsRunner 继承自 OpsRunner(fastsoftmax_ops_runner.h),核心在 SetupKernelGraph(fastsoftmax_ops_runner.cpp):
Status FastSoftMaxOpsRunner::SetupKernelGraph(const OpsTensorPack &opsTensorPack)
{
kernelGraph_.inTensors.resize(1);
kernelGraph_.outTensors.resize(1);
Mki::Tensor &dataInputTensor = kernelGraph_.inTensors.at(0);
Mki::Tensor &dataOutputTensor = kernelGraph_.outTensors.at(0);
kernelGraph_.nodes.resize(1);
auto &fastSoftMaxNode = kernelGraph_.nodes.at(0);
AtbOps::OpParam::FastSoftMax fastSoftMaxParam;
fastSoftMaxParam.headNum = param_.headNum;
fastSoftMaxParam.qSeqLen = param_.qSeqLen;
fastSoftMaxNode.opDesc = {0, "FastSoftMaxOperation", fastSoftMaxParam};
fastSoftMaxNode.inTensors = {&dataInputTensor};
fastSoftMaxNode.outTensors = {&dataOutputTensor};
return NO_ERROR;
}
这段代码把上层 train::FastSoftMaxParam 转换为 Mki 层参数 AtbOps::OpParam::FastSoftMax,构建一个仅含单个节点(op 名为 FastSoftMaxOperation,与 Kernel 侧 Mki Operation 注册名一致)的 kernel graph,实现上层参数到原生 Ops 的桥接。文件末尾的 REG_RUNNER_TYPE(FastSoftMaxOpsRunner) 与 REG_OP_PARAM(AtbOps::OpParam::FastSoftMax) 完成 Runner 类型与参数类型的注册。
SetParam(fastsoftmax_ops_runner.cpp)通过 Mki::AnyCast 接收新参数,并用 operator== 判断是否真正变化;变化时才更新参数并置 isParamUpdated_ = true 触发内核重建。
6. Kernel 侧的 Operation 与 Kernel 注册
6.1 Mki Operation
Kernel 侧同样存在一个名为 FastSoftMaxOperation 的 Mki Operation(src/kernels/mixkernels/fastsoftmax/fastsoftmax_operation.cpp),它负责:
GetInputNum/GetOutputNum:各 1 个;InferShapeImpl:校验通过后输出与输入同 desc;GetBestKernel:通过GetKernelByName("FastSoftMaxKernel")返回对应的 Kernel 实现。
6.2 Kernel 的 CanSupport 与 Tiling 尺寸
FastSoftMaxKernel(src/kernels/mixkernels/fastsoftmax/fastsoftmax_kernel.cpp)继承自 KernelBase:
CanSupport:校验输入输出各 1 个、参数类型为OpParam::FastSoftMax;GetTilingSize:返回sizeof(FastSoftMaxTilingData) + batchSize * sizeof(FastSoftMaxSampleTilingData),即全局 tiling 数据 + 逐样本 tiling 数据;InitImpl:调用FastSoftMaxTiling生成 tiling 数据。
REG_KERNEL_BASE(FastSoftMaxKernel) 完成 Kernel 注册。
7. Tiling 策略:逐样本多核负载均衡
Tiling 是 Kernel 侧最重要的设计,实现在 src/kernels/mixkernels/fastsoftmax/tiling/fastsoftmax_tiling.cpp。整个 tiling 数据布局为:头部 FastSoftMaxTilingData(batchSize、headNum)+ 每个样本一份 FastSoftMaxSampleTilingData(结构见 tiling_data.h),kernel 按样本索引顺序依次消费。
7.1 关键常量
tiling_data.h 中定义了以下硬件相关常量:
| 常量 | 值 | 含义 |
|---|---|---|
MAX_BATCH_SIZE |
32 | 最大 batch 数 |
MAX_SEQ_LEN |
4096 | 最大序列长度 |
BUFFER_NUM |
2 | 片上双缓冲队列深度 |
DATA_BYTESIZE |
2 | fp16 数据字节数 |
BASICBLOCK_SIZE |
32 | 基本块字节数 |
SOFTMAX_COMPUTE_DIM |
2 | Softmax 计算维度 |
SOFTMAX_TILING_SIZE |
64 | 内嵌 SoftMax tiling 缓冲区字节数 |
SHARED_TMP_SIZE |
73728 | 共享临时缓冲区字节数(72KB) |
7.2 逐样本 tiling 计算
SetSampleTilingData(fastsoftmax_tiling.cpp)对每个样本计算:
uint32_t sampleSeqLen = AlignUpToBasicBlock(sampleSeqLenOrigin); // 16 元素对齐
uint32_t outerSize = headNum * sampleSeqLenOrigin; // 行数(head × seqLen)
uint32_t innerSize = sampleSeqLen * DATA_BYTESIZE; // 对齐后行字节数
uint32_t maxTileRowNum = (ubSize - SHARED_TMP_SIZE) /
(BUFFER_NUM * SOFTMAX_COMPUTE_DIM * innerSize + 2 * BASICBLOCK_SIZE);
- 行对齐:原始序列长度向上对齐到基本块(16 元素),保证行方向访问对齐;
- UB 容量约束:
maxTileRowNum由可用 UB(减去 72KB 共享临时区)除以单 tile 的双缓冲(BUFFER_NUM=2)与 Softmax 计算维度(2)所需的行内存推算; - 多核均衡:
formerCoreNum/latterCoreNum、formerCoreTileNum/latterCoreTileNum将outerSize行均分到全部 vector core,其中前部分核承担maxCoreTileNum个 tile、剩余核承担少一个 tile,尽量保持各核负载一致; - Tail 处理:
tailTileRowNum = outerSize % tileRowNum为余数行,交给最后一个核单独处理; - 内嵌 SoftMax tiling:通过
AscendC::SoftMaxTilingFunc生成行方向的 SoftMax tiling 并存入softMaxTilingBuffer/tailSoftMaxTilingBuffer(各 64 字节)。
Tiling 主函数(fastsoftmax_tiling.cpp)完成全部样本的 tiling 写入,并以 kernelInfo.SetBlockDim(coreNum) 设置核数为 vector core 总数,从而启动全部 AI Core 参与计算。
8. Kernel 实现:双缓冲流水与 Tail 收尾
Kernel 主体在 src/kernels/mixkernels/fastsoftmax/op_kernel/fast_softmax.cpp,入口为 extern "C" __global__ __aicore__ void fastsoftmax:先解析全局 tiling,再按 batchSize 循环,对每个样本读取各自的 FastSoftMaxSampleTilingData,初始化 FastSoftmax 对象并调用 Process()。
8.1 Init:核内偏移与双缓冲
Init(fast_softmax.cpp)根据 GetBlockIdx() 与 formerCoreNum 判断当前核属于"前段核"还是"后段核",据此计算本核负责的 coreTileNum 与 innerDataOffset(GM 上的行偏移),并初始化:
dataInputGm/dataOutputGm:以样本dataOffset为基址的 fp16 全局 tensor;- 两个深度为
BUFFER_NUM=2的队列(dataInputQueue/dataOutputQueue),形成 CopyIn/Compute/CopyOut 三级双缓冲流水; - 共享临时区
sharedTmpBuffer(72KB)供 SoftMax 计算使用。
8.2 Process:tile 主循环与 Tail
__aicore__ inline void Process()
{
for (uint32_t tileIndex = 0; tileIndex < coreTileNum; ++tileIndex) {
CopyIn(tileRowNum);
Compute(tileRowNum, softMaxTiling);
CopyOut(tileRowNum);
innerDataOffset += tileLengthOrigin;
}
if (isLastCore) {
CopyIn(tailTileRowNum);
Compute(tailTileRowNum, tailSoftMaxTiling);
CopyOut(tailTileRowNum);
}
}
- CopyIn:
DataCopyPad(dataInputUb, dataInputGm[innerDataOffset], DataCopyParams(currentTileRowNum, sampleSeqLenOrigin * DATA_BYTESIZE, 0, 0))按行搬运(行数 × 原始行字节),DataCopyPad同时负责行末 padding,与 tiling 阶段的 16 元素对齐呼应; - Compute:构造
SoftMaxShapeInfo = {currentTileRowNum, sampleSeqLen, currentTileRowNum, sampleSeqLenOrigin},调用SoftMax<half, false>(dataOutputUb, dataInputUb, softmaxTmpUb, currentSoftMaxTiling, srcShape)——模板第二个参数false表示非跨核场景,fp16 数据、fp32 内部累加由 SoftMax 模板保证; - CopyOut:
DataCopyPad写回 GM; - Tail:仅当存在余数行且当前核为最后一个核时执行(
isLastCore判定),使用独立的tailSoftMaxTiling。
整个 kernel 充分利用了双缓冲队列隐藏 GM 访存延迟,并通过 16 元素基本块对齐保证 Vector 单元访问效率。
9. 工程化的参数变更处理
该算子对"动态改参"做了完整的工程化支持,这与训练场景中 batch 形状频繁变化的需求直接相关:
- Operation 层
SetParam更新参数并置空runner_; - OpsRunner 层
SetParam通过operator==检测变化、置isParamUpdated_ = true触发内核重建; - 测试层
execute_update_param(test_fastsoftmax_operation.py)专门验证了从 batch=4 切换到 batch=6 后算子仍能正确执行,且 golden 结果一致。
10. 关联算子与知识库导航
FastSoftMax 在仓库中并非孤立存在,理解其上下游有助于整体把握:
fast_soft_max_grad:FastSoftMax 的反向算子,源码在src/ops/ops_train/fast_soft_max_grad/,Kernel 在src/kernels/mixkernels/fastsoftmaxgrad/,参数结构体FastSoftMaxGradParam同样声明于 include/atb/train_op_params.h,路由文件见 .agent/knowledge/routing/fast_soft_max_grad.md;self_attention:推理侧复合注意力算子(Tier XL、27 文件、支持 ACLNN),其计算管线中包含 Softmax 阶段,可作为理解"Softmax 在注意力中的角色"的横向参照;laser_attention:同为训练分类的注意力算子,位于src/kernels/mixkernels/laser_attention/(路由文档原始 Kernel 路径标注的出处),其 Kernel 位于src/ops/ops_train/laser_attention/对应目录。
如后续需要在知识库内继续深入,可沿以下导航路径:
总结
FastSoftMax 是一个麻雀虽小、五脏俱全的训练侧融合算子:它用 4 个 Operation/OpsRunner 文件完成上层参数到 Mki 原生 Ops 的桥接,配合 src/kernels/mixkernels/fastsoftmax/ 下的 tiling 与 kernel 实现,在 Atlas 800I A2 推理产品上以逐样本 tiling、多核负载均衡、双缓冲流水的方式完成 unpad QK^T 分数的 fp32 精度 Softmax。理解它的文件布局(路由文档)、参数约束(train_op_params.h)、执行链路(fastsoftmax_operation.cpp)与 golden 校验(test_fastsoftmax_operation.py),即掌握了 ATB 训练算子的标准实现范式,可直接迁移到其他 unpad 类融合算子的阅读与开发中。