ops-math 是 CANN 里最基础的算子库。加减乘除、指数对数、随机数生成——这些算子看起来简单，但 Ascend C 的硬件约束和 FP16 的数值特性让它们成了高频踩坑区。

以下四个坑，每一个都在社区 Issues 里出现过不止一次。

踩坑一：FP16 溢出静默归零

FP16 的指数位是 5 位，能表示的最大数是 65504。超过这个数，FP16 直接溢出变成 inf——但 Ascend C 的 Vector 单元默认不抛异常，inf 继续参与后续计算，最后结果变成 NaN 或者全零，排查起来非常隐蔽。

错误写法：

// ops-math/ops/exp/exp_kernel.cpp（踩坑版本）
// 计算 exp(x)，x 是 FP16

__aicore__ void exp_kernel_bad(GlobalTensor<FP16>& output, 
                               GlobalTensor<FP16>& input, 
                               int32_t numel) {
    LocalTensor<FP16> x_local(numel);
    LocalTensor<FP16> y_local(numel);
    
    DataCopy(x_local, input, numel);
    
    // 直接算 exp，没有检查溢出
    // 如果 x 里有值 > 11.09（因为 exp(11.09) ≈ 65504）
    // FP16 直接溢出变成 inf
    vexp(y_local, x_local, numel);  // 溢出点
    
    DataCopy(output, y_local, numel);
}

正确写法：先做一个范围裁剪，保证输入在 FP16 的安全范围内。

// ops-math/ops/exp/exp_kernel.cpp（正确版本）

__aicore__ void exp_kernel(GlobalTensor<FP16>& output, 
                           GlobalTensor<FP16>& input, 
                           int32_t numel) {
    LocalTensor<FP16> x_local(numel);
    LocalTensor<FP16> y_local(numel);
    LocalTensor<FP16> clip_max(numel);
    LocalTensor<FP16> clip_min(numel);
    
    DataCopy(x_local, input, numel);
    
    // 先裁剪到 FP16 安全范围
    // exp 的安全上限：x ≤ 11.0（留一点余量）
    // exp 的安全下限：x ≥ -20.0（exp(-20) ≈ 2e-9，FP16 能表示）
    float16_t fp16_max = float16_t(11.0f);
    float16_t fp16_min = float16_t(-20.0f);
    
    // 生成常量的本地 tensor
    Duplicate(clip_max, fp16_max, numel);
    Duplicate(clip_min, fp16_min, numel);
    
    // x = min(x, 11.0)
    vmin(x_local, x_local, clip_max, numel);
    // x = max(x, -20.0)
    vmax(x_local, x_local, clip_min, numel);
    
    // 现在安全了
    vexp(y_local, x_local, numel);
    
    DataCopy(output, y_local, numel);
}

排查技巧：结果出现 NaN 或全零，先检查中间张量的最大值。用 np.max(tensor_float32) 转换到 FP32 看范围——FP16 溢出在转换成 FP32 之前是看不出来的。

踩坑二：Broadcast 维度的隐式对齐

NumPy 的 broadcast 规则是「从后往前对齐，维度不够的补 1」。Ascend C 的 broadcast 算子实现这条规则，但有一个常见的误用：把 (4096, 1) 的向量 broadcast 到 (4096, 4096) 的矩阵时，如果向量的 stride 没设对，结果不是按列复制，而是全零或者乱码。

错误写法：

# ops-math 的 broadcast_add 错误用法
import torch
import torch_npu

# 矩阵：(4096, 4096)，向量：(4096,) —— 想做 row-wise 加法
matrix = torch.randn(4096, 4096).npu().half()
vector = torch.randn(4096).npu().half()

# 错误：vector 的 shape 是 (4096,)，broadcast 沿着 dim=0
# 结果是 (4096, 4096) 的矩阵，但 vector 被复制到了每一行 —— 这是错的
# 正确意图：vector 加到每一列（dim=0 不变，dim=1 复制）
result = torch.ops.ops_math.broadcast_add(matrix, vector)
# 实际结果：vector 被当成了 (4096, 1) 来 broadcast，不是 (1, 4096)

正确写法：显式 reshape 向量到目标 broadcast 维度。

# 正确：先把 vector reshape 到 (1, 4096)，再 broadcast 到 (4096, 4096)
vector_2d = vector.reshape(1, 4096)  # shape: (1, 4096)
result = torch.ops.ops_math.broadcast_add(matrix, vector_2d)
# 现在 vector_2d 沿着 dim=0 复制 4096 次，每一列加上相同的 vector

# 验证：检查 result[0, :] 和 result[1, :] 是否相等（应该相等，因为加的是同一行 vector）
assert torch.allclose(result[0, :], result[1, :], atol=1e-3)

C++ 侧的根本原因：Ascend C 的 broadcast 算子内部用 BroadcastTiling 计算分块策略，如果输入张量的 stride 信息和 shape 不匹配（比如 (4096,) reshape 到 (1, 4096) 但 stride 没更新），tiling 算出来的块大小是错的，导致 Vector 单元读到了错误的内存地址。

踩坑三：Random 算子的种子没有跨 NPU 同步

ops-math 的随机数生成算子（ops.random.rand、ops.random.randn）依赖 NPU 上的随机数种子。如果多张 NPU 用相同的种子初始化，生成的随机数是完全一样的——分布式训练时这是个严重问题，因为每张卡的数据增强结果相同，相当于只做了一个样本。

错误写法：

# 分布式训练：每张 NPU 用相同的随机种子
import torch
import torch_npu
import torch.distributed as dist

dist.init_process_group(backend='hccl')

# 错误：所有 NPU 的种子都是 42
torch.manual_seed(42)
torch.npu.manual_seed(42)  # 所有 NPU 都是 42

# DataLoader 生成的随机增强是完全相同的
train_loader = torch.utils.data.DataLoader(dataset, shuffle=True, num_workers=4)

# NPU 0 和 NPU 1 拿到的 batch 是完全相同的
# 梯度同步后相当于 batch_size 没有翻倍

正确写法：用 NPU rank 做种子偏移。

# 正确：每张 NPU 用不同的随机种子
import torch
import torch_npu
import torch.distributed as dist
import os

dist.init_process_group(backend='hccl')
local_rank = int(os.environ['LOCAL_RANK'])

# 种子 = 基础种子 + rank
base_seed = 42
torch.manual_seed(base_seed + local_rank)
torch.npu.manual_seed(base_seed + local_rank)

# 现在每张 NPU 的随机数序列不同
train_loader = torch.utils.data.DataLoader(dataset, shuffle=True, num_workers=4)

# NPU 0 和 NPU 1 拿到的 batch 不同
# 梯度同步后 batch_size 真正翻倍

C++ 侧细节：ops-math 的随机数生成器在 NPU 的 Vector 单元上跑，种子存在 HBM 的固定地址上。torch.npu.manual_seed(seed) 做的是把种子值写到这个 HBM 地址——如果所有 NPU 写相同的种子值，生成的随机数序列就完全相同。

踩坑四：类型转换的精度损失链

Cast 算子做数据类型转换，但 FP32 → FP16 → FP32 的往返不是无损的。FP16 的尾数是 10 位，FP32 的尾数是 23 位——从 FP32 转到 FP16 时，尾数的后 13 位直接丢掉。如果计算流程里多次往返转换，精度损失会累积。

错误写法：

# 精度损失链：FP32 → FP16 → FP32 → FP16 → ... 往返多次
import torch
import torch_npu

# 原始数据：FP32，高精度
data_fp32 = torch.randn(1024, 1024).cuda()  # 假设在 CPU 上

# 错误：多次 FP32 ↔ FP16 往返
for i in range(10):
    # 每次到 NPU 上算都转成 FP16（省 HBM）
    data_fp16 = data_fp32.half().npu()
    result = torch.ops.ops_math.matmul(data_fp16, weight_fp16)
    # 结果转回 FP32 做梯度累加
    data_fp32 = result.float().cpu()

# 10 次往返后，data_fp32 的精度损失累积
# MSE 相对于原始数据：~1e-3（FP16 单次转换的 MSE 是 ~1e-4，10 次累积到 1e-3）

正确写法：训练时保持 FP32 的权重主副本，只在计算密集的矩阵乘和卷积时才转成 FP16。

# 正确：Master-Weights 策略（混合精度训练的标准做法）
import torch
import torch_npu

# 权重的主副本：FP32
weight_master = torch.randn(1024, 1024).float().npu()

for i in range(10):
    # 计算时：权重转 FP16（省 HBM 和算力）
    weight_fp16 = weight_master.half()
    data_fp16 = data_fp32.half().npu()
    
    result_fp16 = torch.ops.ops_math.matmul(data_fp16, weight_fp16)
    
    # 梯度：FP16（省 HBM）
    grad_fp16 = result_fp16.backward()
    
    # 优化器更新：转回 FP32，用主副本更新
    grad_fp32 = grad_fp16.float()
    # optimizer.step() 用 weight_master 和 grad_fp32 更新
    # weight_master 始终保持在 FP32，没有精度损失累积

# 10 次迭代后，weight_master 的精度损失可以忽略（只有优化器状态的舍入误差）

C++ 侧验证：ops-math 的 Cast 算子内部调的是 vconv 指令（Vector 单元的数据类型转换）。vconv(FP32, FP16, ...) 的舍入策略是「最接近偶数舍入」（round-to-nearest-even），单次转换的 RMSE 大约是 2^{-11} ≈ 4.9e-4。往返一次（FP32→FP16→FP32）的 RMSE 大约是 7e-4。10 次往返的 RMSE 大约是 2.2e-3——对于梯度累加来说已经不可忽略了。

总结

这四个坑的共同点是：它们都不是「算子算错了」，而是「用法不对」。FP16 溢出、broadcast 维度、随机种子、精度损失链——都属于数值计算和硬件约束层面的陷阱，Ascend C 的算子实现是正确的，但调用方需要理解底层约束才能用对。

ops-math 作为最基础的数学算子库，踩坑成本也最高——上层所有算子仓库都依赖它，一个数值错误会层层传递上去。理解这四个坑，能避免相当一部分「结果看起来对但实际精度不对」的问题。