CANN ops-math 数学算子库 Bias 算子全解析:广播形状推导、参数配置与 NPU 图模式调用实战
CANN ops-math 数学算子库 Bias 算子全解析:广播形状推导、参数配置与 NPU 图模式调用实战
Bias 是 CANN ops-math 数学类基础计算算子库(math/bias)中实现的偏置加法算子,它在 NPU 上按照 axis、num_axes、bias_from_blob 三个属性推导 bias 的逻辑广播形状,并执行 y = x + broadcast(bias) 的逐元素加法。本文以 math/bias/README.md 为骨架,结合算子原型注册、InferShape、Tiling 与 Kernel 实现,完整讲解 Bias 的广播规则、参数语义、数据类型/格式约束、Caffe 模型兼容性,以及通过 GEIR 图模式调用的完整可运行样例,帮助开发者在昇腾 NPU 上正确使用与移植 Bias 算子。
产品支持情况
Bias 算子在以下昇腾产品系列上均已支持(来源:math/bias/README.md):
| 产品 | 是否支持 |
|---|---|
| Ascend 950PR/Ascend 950DT | √ |
| Atlas A3 训练系列产品/Atlas A3 推理系列产品 | √ |
| Atlas A2 训练系列产品/Atlas A2 推理系列产品 | √ |
| Atlas 200I/500 A2 推理产品 | √ |
| Atlas 推理系列产品 | √ |
| Atlas 训练系列产品 | √ |
在代码层面,算子原型通过 math/bias/op_host/bias_def.cpp 中的 OpAICoreConfig 显式注册了 ascend950 的 AI Core 配置,并开启 DynamicShapeSupportFlag、DynamicRankSupportFlag、DynamicFormatFlag 等动态编译能力;算子内核与 Tiling 实现位于 math/bias/op_kernel/arch35 与 math/bias/op_host/arch35,对应 arch35(Ascend 950 等)平台架构。
功能说明
Bias 按照 axis、num_axes 和 bias_from_blob 推导 bias 的逻辑广播形状,并计算:
其中 broadcast(bias) 的推导规则如下(来源:math/bias/README.md):
axis < 0时,先执行axis += rank(x),将负轴归一化到[0, rank(x))区间;bias_from_blob = true且num_axes = -1时,broadcast_shape = [1] * axis + shape(bias),即 bias 覆盖从axis开始到末尾的所有维度;bias_from_blob = true且num_axes = 0时,broadcast_shape = [1] * rank(x),即 bias 被当作标量广播到与 x 完全相同的形状;bias_from_blob = true且num_axes > 0时,broadcast_shape = [1] * axis + shape(bias) + [1] * (rank(x) - axis - num_axes),即 bias 精确覆盖axis起的num_axes个维度;bias_from_blob = false且bias为单元素(形状为[1])时,broadcast_shape = [1] * rank(x);bias_from_blob = false的其它场景,broadcast_shape = [1] * axis + shape(bias) + [1] * (rank(x) - axis - rank(bias))。
上述规则在 math/bias/op_host/arch35/bias_tiling_arch35.cpp 的 InferBiasShape 函数中有逐分支的源码级对应实现,并且在该函数中完成了所有合法性校验:
num_axes >= -1,否则直接返回失败;x的维度数>= 1;axis必须位于[-rank(x), rank(x)-1]区间;bias_from_blob = true时:num_axes == -1要求rank(bias) == rank(x) - axis;num_axes == 0要求 bias 为形状长度 1 的标量;num_axes > 0要求axis + num_axes <= rank(x)且rank(bias) == num_axes;bias_from_blob = false时:非标量 bias 要求axis + rank(bias) <= rank(x);- 最终推导出的
broadcast_shape每个维度必须为 1 或与x对应维度相同。
广播规则速查表
| bias_from_blob | num_axes | broadcast_shape | 典型语义 |
|---|---|---|---|
| true | -1 | [1]*axis + shape(bias) |
Caffe blob 偏置,覆盖尾部所有轴 |
| true | 0 | [1]*rank(x) |
标量偏置(全维度广播) |
| true | >0 | [1]*axis + shape(bias) + [1]*(rank(x)-axis-num_axes) |
Caffe blob 偏置,覆盖指定轴数 |
| false | - | [1]*rank(x)(bias 为 [1] 时) |
在线标量偏置 |
| false | - | [1]*axis + shape(bias) + [1]*(rank(x)-axis-rank(bias)) |
在线非标量偏置 |
典型推导示例
假设 x 形状为 [2, 3, 4](rank(x)=3):
axis=1, num_axes=-1, bias_from_blob=true,bias形状[3, 4]:broadcast_shape = [1, 3, 4],即对 batch 维广播;axis=-1, num_axes=1, bias_from_blob=true:先归一化axis = -1 + 3 = 2,bias形状[4]时broadcast_shape = [1, 1, 4],即仅对最后一维做通道偏置;axis=1, num_axes=0, bias_from_blob=true,bias形状[1]:broadcast_shape = [1, 1, 1],等价于全量标量相加。
这些场景分别与 math/bias/tests/ut/op_host/arch35/test_bias_tiling.cpp 中的 bias_test_tiling_fp16_tail_broadcast、bias_test_tiling_negative_axis、bias_test_tiling_scalar_broadcast 等用例一一对应。
参数说明
Bias 算子的输入、属性与输出定义如下(来源:math/bias/README.md):
| 参数名 | 输入/输出/属性 | 描述 | 数据类型 | 数据格式 |
|---|---|---|---|---|
| x | 输入 | 待进行 Bias 计算的输入张量。 | FLOAT、FLOAT16、BFLOAT16 | ND、NC1HWC0 |
| bias | 输入 | 按属性广播后与 x 相加的偏置张量。 | FLOAT、FLOAT16、BFLOAT16 | ND、NC1HWC0 |
| axis | 属性 | bias 逻辑形状的起始对齐轴,默认值为 1。 | INT | - |
| num_axes | 属性 | bias 覆盖的轴数,默认值为 1;支持 -1、0 和正整数。 | INT | - |
| bias_from_blob | 属性 | 是否按 blob bias 规则推导逻辑广播形状,默认值为 true。 | BOOL | - |
| y | 输出 | 输出张量,形状和数据类型跟随 x。 | FLOAT、FLOAT16、BFLOAT16 | ND、NC1HWC0 |
源码级参数语义
- 原型层:math/bias/op_graph/bias_proto.h 通过
REG_OP(Bias)定义x、bias两个输入,y一个输出,以及三个属性,默认值分别是axis=1、num_axes=1、bias_from_blob=true,与 README 中参数表完全一致。原型注释中明确说明该算子与 Caffe 的Bias算子兼容(Compatible with the Caffe operator Bias),其中bias_from_blob = true表示 bias 来自离线训练的 Caffe 模型 blob,false表示来自在线(online)输入。 - 算子定义层:math/bias/op_host/bias_def.cpp 将两个输入均标记为
REQUIRED并声明AutoContiguous(),三个属性为OPTIONAL;数据类型向量kBiasDataType与格式向量kBiasFormat按顺序列出 ND、NC1HWC0 两种格式下的三种数据类型组合。 - InferShape 层:math/bias/op_host/bias_infershape.cpp 实现
InferShape4Bias,直接将输出y的形状赋值为输入x的形状(含 0 维标量场景),这与 README 中"输出形状跟随 x"一致。 - 数据类型推断层:math/bias/op_graph/bias_graph_infer.cpp 的
InferDataTypeBias将输出y的数据类型直接置为输入x的数据类型,从图编译阶段保证了输出类型跟随 x。
约束说明
使用 Bias 算子时需要满足以下约束(来源:math/bias/README.md):
- 支持 ND 和 NC1HWC0 数据格式(4D 输入时支持 NC1HWC0),以及 FLOAT、FLOAT16、BFLOAT16 同数据类型输入输出;不支持混合数据类型;
bias经过属性推导后的每个维度必须为 1,或与x的对应维度相同。
上述约束在 Tiling 阶段会被严格校验:
- 混合数据类型会被拒绝:math/bias/op_host/arch35/bias_tiling_arch35.cpp 中分别校验
x与bias、x与y的数据类型必须一致,随后通过IsSupportedDtype限定仅支持 FLOAT16、FLOAT、BF16(bias_tiling_arch35.cpp)。 - 广播维度合法性校验:推导出的
broadcastBiasShape维度数必须等于rank(x),且每一维要么为 1 要么等于x的对应维(bias_tiling_arch35.cpp)。 - 这些非法输入场景(越界
axis、非法num_axes < -1、混合 dtype)均有对应的单元测试覆盖,例如 test_bias_tiling.cpp 中的tiling_invalid_axis、tiling_invalid_num_axes、tiling_mixed_dtype,它们的期望执行结果均为GRAPH_FAILED。
调用说明
| 调用方式 | 调用样例 | 说明 |
|---|---|---|
| 图模式调用 | test_geir_bias | 通过算子IR构图方式调用 Bias 算子。 |
注:上表中 README 内原有的相对链接(
./examples/test_geir_bias.cpp、./op_graph/bias_proto.h)在仓库根目录视角下的完整路径分别为 math/bias/examples/test_geir_bias.cpp 和 math/bias/op_graph/bias_proto.h。
图模式(GEIR)调用示例
math/bias/examples/test_geir_bias.cpp 提供了一个完整可运行的图模式调用样例,整体流程如下:
- 初始化 GE:通过
ge::GEInitialize(globalOptions)初始化,配置ge.exec.deviceId=0、ge.graphRunMode=1(图模式)、ge.socVersion=Ascend950DT_9592; - 构图:创建
Graph,注册Data算子作为图输入,使用op::Bias("bias_op")创建 Bias 节点,并通过set_input_x、set_input_bias连接数据流; - 设置属性:
set_attr_axis(1)、set_attr_num_axes(-1)、set_attr_bias_from_blob(true),对应示例场景x=[2,3,4]、bias=[3,4],即按规则 1 推导broadcast_shape = [1,3,4]; - 执行与校验:
session->AddGraph+session->RunGraph运行图,示例中输入均为全 1 张量(GenOnesData填充),因此期望输出全为 2,并通过逐元素校验|y - 2.0| < 1e-6验证正确性。
关键代码片段:
auto x = op::Data("x").set_attr_index(0);
auto biasTensor = op::Data("bias").set_attr_index(1);
auto bias = op::Bias("bias_op");
// x: [2,3,4], bias: [3,4], 均为 FLOAT / ND
bias.set_input_x(x);
bias.set_input_bias(biasTensor);
bias.set_attr_axis(1);
bias.set_attr_num_axes(-1);
bias.set_attr_bias_from_blob(true);
// 构图、建会话并运行
session->AddGraph(graphId, graph, graphOptions);
session->RunGraph(graphId, inputs, outputs);
运行成功后程序输出 Bias GEIR example run success。该样例同时演示了 ge.exec.precision_mode=allow_mix_precision 的混合精度图选项配置。
NPU 上的实现原理:从 Tiling 到 Kernel
为帮助读者理解 Bias 在 NPU 上的真实执行路径,这里补充仓库源码层面的实现脉络(属于对 README 的深化,不改变算子对外语义)。
Tiling 阶段:广播形状计算与任务切分
Host 侧 Tiling 入口为 math/bias/op_host/arch35/bias_tiling_arch35.cpp 的 TilingForBias,其核心步骤:
- 读取
x、bias的存储形状与属性,调用InferBiasShape完成广播形状推导(即上文规则)与合法性校验; - 通过
BroadcastTiling(来自atvoss/broadcast/broadcast_tiling.h)生成广播场景下的任务切分参数:blockFormer/blockTail(核间切分)、ubFormer/ubTail/ubOuter(UB 内切分)、ubSplitAxis(切分轴)等; - 将切分结果与
input0/input1/output的 dims 与 strides 一并写入BiasTilingData结构(定义见 math/bias/op_kernel/arch35/bias_tiling_data.h,维度上限BIAS_MAX_DIM_SIZE = 8); - 依据数据类型选择调度模板参数(
schMode:0=FLOAT32、1=FLOAT16、2=BFLOAT16,宏定义于 math/bias/op_kernel/arch35/bias_tiling_key.h),并申请 16MB 固定 workspace; - 调用
context->SetBlockDim(...)设置核数,最终通过IMPL_OP_OPTILING(Bias)注册 Tiling 与TilingParse(后者负责采集平台核数与 UB 大小,见 bias_tiling_arch35.cpp)。
另外,Tiling 中有一个值得注意的细节:当 broadcastBiasShape 与 bias 原始存储形状“右对齐等价”(IsRightAlignedEquivalent,即去掉前导 1 后形状一致)时,无需改写输入形状,直接复用存储形状完成广播;否则将推导后的逻辑广播形状替换进 Tiling 输入,确保 Kernel 侧按逻辑形状寻址。
Kernel 阶段:向量加与双缓冲流水
Device 侧内核入口为 math/bias/op_kernel/arch35/bias.cpp,按 schMode 模板参数实例化 BiasOp::BiasKernel<T, NeedCast>:
BiasKernel<float, false>:FP32 直接向量加法;BiasKernel<half, true>/BiasKernel<bfloat16_t, true>:FP16/BF16 数据在向量寄存器中先Cast到 FP32 计算,再写回,兼顾精度与性能。
核心计算类 math/bias/op_kernel/arch35/bias_kernel.h 的 Process 按 Tiling 数据执行:
- 依据核号与
blockFormer/blockTail计算本核承担的 UB 循环次数; CopyInX/CopyInBias使用BroadcastNddmaWithoutLoop/BroadcastNddmaWithLoop按广播 strides 从 GM 搬运数据到 UB,并利用双缓冲(DOUBLE_BUFFER = 2)隐藏搬运延迟;Compute在__VEC_SCOPE__内按向量寄存器宽度循环执行Add(FP16/BF16 先Cast到 FP32);CopyOut通过DataCopyPad将结果写回 GM 输出张量。
这一“Tiling 推导广播形状 + NDMA 广播搬运 + 向量加法”的实现,保证了前述多种广播规则在 NPU 上以统一的广播计算路径高效执行。
单元测试与验证
Bias 算子配套了 Host 侧 Tiling 单元测试 math/bias/tests/ut/op_host/arch35/test_bias_tiling.cpp,覆盖的典型场景包括:
bias_test_tiling_fp16_tail_broadcast:FP16、x=[2,3,4]、bias=[4]、axis=2, num_axes=1,验证尾维广播;bias_test_tiling_fp32_num_axes_neg1:FP32、axis=1, num_axes=-1,验证 blob 尾部覆盖;bias_test_tiling_bf16_non_tail_broadcast:BF16、bias=[3,1]、axis=1, num_axes=2,验证带 1 维的中间广播;bias_test_tiling_scalar_broadcast:bias=[1]、num_axes=0,验证标量广播;bias_test_tiling_bias_from_blob_false:bias_from_blob=false、axis=2,验证在线输入模式;bias_test_tiling_negative_axis:axis=-1,验证负轴归一化;- 三个失败用例:越界
axis、num_axes < -1、混合数据类型,均期望返回GRAPH_FAILED。
此外还有 ST 级测试数据 math/bias/tests/st/arch35/ttk_kernel_bias_st.csv 与 golden 脚本 math/bias/tests/assets/golden.py,以及 InferShape 单元测试 math/bias/tests/ut/op_host/test_bias_infershape.cpp,共同构成从形状推导到内核执行的完整验证链路。
小结与使用建议
- 默认值记忆:
axis=1、num_axes=1、bias_from_blob=true是三个属性的默认值,bias_from_blob=true时num_axes=-1表示 bias 覆盖axis之后的全部维度,是最常用的 Caffe 兼容用法; - 负轴处理:
axis支持负数,会在内部先归一化为axis += rank(x),等价于从尾部起算的对齐位置; - 数据类型约束:
x、bias、y必须同为 FLOAT、FLOAT16、BFLOAT16 中的一种,混合数据类型会在 Tiling 阶段被拒绝; - 广播合法性:推导后的广播形状每一维必须为 1 或与
x对应维相等,这是“仅做加法不做跨维复制”的边界保证; - 实践路径:直接复用 math/bias/examples/test_geir_bias.cpp 作为起点,通过图模式(
ge.graphRunMode=1)构图调用,即可在支持产品上验证 Bias 算子行为;需要更深入的算子级测试可参考 math/bias/tests 目录下的 UT/ST 用例。