CANN ascend-transformer-boost 训练侧 FastSoftMax 算子全解析:源码路径、参数约束与执行链路

原创2026-09-17 10:52:221,892 阅读
文章标签:算子库人工智能深度学习大模型高性能计算CANN

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)依次执行四道校验:

  1. 平台校验:通过 GetSingleton<atb::Config>().Is910B() 判定,非 Atlas 800I A2 推理产品直接报错,错误信息为 "FastSoftMaxOperation is only supported in Atlas 800I A2 inference product.";
  2. 序列长度校验:调用 OperationUtil::QSeqLenCheck(opParam.qSeqLen, MAX_SEQLEN),其中 MAX_SEQLEN = 4096,即每个样本的序列长度不得超过 4096;
  3. head 数量校验:headNum <= 0 时报错;
  4. 溢出校验:计算 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 类融合算子的阅读与开发中。

登录后查看全文
ascend-transformer-boost