前言

在深度学习训练与推理场景中，数学运算算子是最底层也是最高频被调用的计算单元。无论是矩阵乘法、残差求和、逐元素变换，还是随机数生成、概率分布采样，所有上层框架最终都要落地到这些原子级的数学操作上。在昇腾NPU生态中，这些基础算子的集合被称为ops-math——一个由华为CANN团队开源维护的算子基础库。

ops-math仓库的定位非常明确：它是CANN算子体系中提供数值计算能力的底层算子库，覆盖conversion类（张量形态变换）、math类（基础数学运算）、random类（随机数生成）三大方向。截至当前版本，该仓库已支持Ascend 950PR/Ascend 950DT、Atlas A2训练系列、Atlas A2推理系列、Atlas A3训练系列、Atlas A3推理系列等多款昇腾芯片产品。仓库本身跟随CANN版本同步发布，每个版本标签对应特定的CANN软件版本，这种版本配套机制是保证算子兼容性的前提。

本文以手把手实操的方式，从环境准备开始，逐步展开源码编译、算子调用、三种调用方式对比、自定义算子开发、性能调优的全流程。全文以AddExample作为主线贯穿始终，因为AddExample既是ops-math中最简的示例算子，又完整展示了AI Core算子的标准开发范式——从op_graph（图级定义）到op_host（Host侧Tiling和InferShape）再到op_kernel（Device侧Kernel实现），读者只需掌握这一个算子的完整开发路径，即可迁移到math目录下的上百个真实算子。

1. ops-math在CANN架构中的位置

在深入代码之前，理解ops-math在整个CANN软件栈中的位置至关重要。CANN（Compute Architecture for Neural Networks）是昇腾AI处理器的异构计算架构，其算子体系分为多个层次：从上到下依次是PyTorch/TensorFlow等AI框架层、图优化层、算子调度层、以及最终的算子实现层。

ops-math位于算子实现层中的math基础算子库位置。它的上一层是aclnn（Ascend C Library for Neural Network）接口层，用户通过aclnn API或GE图模式调用ops-math中的算子；它的下一层是Ascend C Kernel实现，运行在AI Core的Vector/Cube计算单元上。整个调用链路的入口清晰，用户既可以通过PyTorch的npu扩展直接调用，也可以通过aclnn C API做更精细的控制。

ops-math目前包含三大类算子目录：math目录（基础数学运算，如add、mul、matmul、inv、svd等）、conversion目录（张量形态变换，如concat、reshape、transpose、pad等）、random目录（随机数生成，如dropout、bernoulli、random_uniform等）。每一类算子下面都有数十甚至上百个子目录，每个子目录对应一个具体算子的完整实现。这种以算子为粒度的目录组织方式，使得开发者可以单独编译某一个算子，而不需要每次都编译整个仓库。

2. 环境准备

ops-math的运行环境依赖昇腾NPU驱动和CANN软件包。在开始任何操作之前，必须确保CANN已经正确安装并且NPU可以被识别。这一步看似简单，但实际上是整个上手流程中最容易出问题的环节——很多初学者花大量时间在算子代码上，最后却发现环境变量没配对。

首先需要确认CANN的安装路径。标准安装路径通常是/usr/local/Ascend/cann，但通过CANNLab云开发环境或Docker镜像安装时，路径可能不同。判断CANN是否安装到位有两个标准：一个是${ASCEND_HOME_PATH}/opp目录是否存在，另一个是atc编译器是否可用。

# 第一步：确认CANN安装路径
echo $ASCEND_HOME_PATH
ls $ASCEND_HOME_PATH/opp 2>/dev/null || echo "opp目录不存在"

# 第二步：确认ATC编译器（用于编译算子）
source $ASCEND_HOME_PATH/bin/set_env.sh 2>/dev/null
atc --version 2>/dev/null || echo "ATC不可用，请检查CANN安装"

# 第三步：确认NPU设备可见
npu-smi info 2>/dev/null | head -20 || echo "npu-smi不可用，驱动可能未正确加载"

环境准备阶段有一个常见误区：把CANN的toolkit包和runtime包混淆。ops-math的算子编译依赖ATC编译器，这意味着必须安装CANN-toolkit包而不是仅仅安装CANN-runtime包。如果只有runtime包，atc命令会报"command not found"，此时需要补充安装toolkit。

对于没有物理NPU硬件的开发者，Ascend 950PR系列产品支持通过Simulator仿真工具进行算子开发和调试。Simulator在CANN安装包中已经包含，通过设置环境变量ACL_SIMULATOR_MODE=1可以切换到仿真模式。这个功能对初学者非常友好——不需要购买昂贵的NPU硬件，在x86服务器上就能完成大部分算子开发和调试工作。

如果使用Docker方式部署，建议使用CANN官方提供的Docker镜像，其中已经预装了完整版本的CANN和必要的依赖项。使用官方镜像可以避免手动安装过程中可能遇到的第三方库版本冲突问题。

3. 源码下载与目录结构

ops-math的源码通过git克隆获取。需要注意的是，源码版本必须与CANN版本严格配套——使用master分支的代码可能会出现与当前环境CANN版本不兼容的问题。正确做法是参考release仓库中的版本配套表，选择与当前CANN版本对应的git标签进行克隆。

# 根据CANN版本选择对应的标签，例如CANN 9.0.0对应标签v9.0.0
git clone -b v9.0.0 https://atomgit.com/cann/ops-math.git
cd ops-math

# 查看当前仓库最新提交，确认代码状态
git log --oneline -5

克隆完成后，目录结构中最需要关注的几个目录是：math/、conversion/、random/这三个算子分类目录；examples/下的add_example等示例算子目录；docs/zh/下的中文文档目录；build.sh是整个项目的编译入口脚本。

每个算子目录内部都遵循统一的标准结构。以add算子为例，其目录结构如下：op_graph/包含算子的原型定义和图融合规则；op_host/包含算子信息库（_def.cpp）、InferShape实现、tiling策略文件；op_kernel/包含AI Core上的Kernel实现（.h和.cpp文件）；op_api/包含aclnn接口的封装实现；examples/包含调用该算子的示例代码；tests/包含单元测试用例。这种分层的目录结构是ops-math的设计规范，每个新算子的开发都必须遵循这个模板。

4. 单算子编译与部署

ops-math的编译系统由build.sh脚本统一管理。这个脚本是整个项目工程化的核心，它封装了CMake构建流程、第三方依赖下载、run包生成和安装等全部环节。对于日常开发来说，最常用的场景是单算子编译——每次只编译一个算子，这样可以大幅缩短编译周期。

# 单算子编译命令格式
bash build.sh --pkg --soc=${soc_version} --ops=add_example -j16

# soc_version的取值规则
# Atlas A2 系列：ascend910b
# Atlas A3 系列：ascend910_93
# Ascend 950PR/950DT：ascend950

编译完成后，会在项目根目录的build_out/子目录下生成一个.run格式的自解压安装包。包的命名规则为cann-ops-math-custom_linux-${arch}.run，其中custom是默认的vendor_name（可自定义）。将这个安装包在目标机器上以root权限执行，即可完成算子的安装。

# 安装自定义算子包
./build_out/cann-ops-math-custom_linux-${arch}.run

# 安装后需要配置环境变量，让运行时能找到自定义算子
export LD_LIBRARY_PATH=${ASCEND_HOME_PATH}/opp/vendors/custom_math/op_api/lib:${LD_LIBRARY_PATH}

安装完成后，自定义算子包会出现在${ASCEND_HOME_PATH}/opp/vendors/目录下。这里有一个设计细节值得注意：自定义算子包的安装路径（vendor_name指定的目录）与CANN内置算子路径是平行的，运行时优先加载自定义算子包中的实现，这正是昇腾自定义算子机制的核心——不修改原始CANN包的前提下，开发者可以完全替换任何一个内置算子的行为。

5. 算子调用：三种方式实战

ops-math中的算子提供了三种调用方式，分别适用于不同的场景。这三种方式并不是互斥的，而是互补的——快速验证用eager模式，生产部署用图模式，需要PyTorch集成时用算子注册方式。理解每种方式的适用场景，是高效使用ops-math的前提。

5.1 aclnn eager模式（快速调用）

aclnn是昇腾提供的C语言API库，封装了所有算子的调用接口。eager模式指的是立即执行模式（类似于PyTorch的eager execution），每次调用aclnn接口都会立即在NPU上执行对应算子，不需要先构建计算图。这种方式最适合快速验证算子功能正确性，也是日常开发中最常用的方式。

调用一个算子的标准流程是：初始化ACL环境、构造输入输出张量、调用aclnn接口、执行同步、释放资源。下面以Add算子为例展示完整的eager调用代码：

int main()
{
    // 1. 初始化ACL设备和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. 构造输入张量（以float32类型、shape={32,4,4,4}为例）
    aclTensor* selfX = nullptr;
    void* selfXDeviceAddr = nullptr;
    std::vector<int64_t> selfXShape = {32, 4, 4, 4};
    std::vector<float> selfXHostData(2048, 1.0f);
    ret = CreateAclTensor(selfXHostData, selfXShape, &selfXDeviceAddr,
                          aclDataType::ACL_FLOAT, &selfX);
    CHECK_RET(ret == ACL_SUCCESS, return ret);

    // 3. 构造第二个输入张量（同样shape和初始值）
    aclTensor* selfY = nullptr;
    void* selfYDeviceAddr = nullptr;
    std::vector<float> selfYHostData(2048, 1.0f);
    ret = CreateAclTensor(selfYHostData, selfYShape, &selfYDeviceAddr,
                          aclDataType::ACL_FLOAT, &selfY);

    // 4. 调用aclnnAdd接口执行加法运算
    aclTensor* out = nullptr;
    void* outDeviceAddr = nullptr;
    std::vector<int64_t> outShape = {32, 4, 4, 4};
    ret = CreateAclTensor(std::vector<float>(2048, 0.0f), outShape,
                          &outDeviceAddr, aclDataType::ACL_FLOAT, &out);
    ret = aclnnAdd(selfX, selfY, out, stream);

    // 5. 同步等待执行完成
    aclrtSynchronizeStream(stream);

    // 6. 将结果从NPU拷回Host并打印验证
    std::vector<float> resultHost(2048);
    aclrtMemcpy(resultHost.data(), sizeof(float) * 2048,
                outDeviceAddr, sizeof(float) * 2048,
                ACL_MEMCPY_DEVICE_TO_HOST);
    printf("add result[0] is: %f\n", resultHost[0]); // 期望输出2.0

    // 7. 资源释放
    DestroyAclTensor(selfX, selfXDeviceAddr);
    DestroyAclTensor(selfY, selfYDeviceAddr);
    DestroyAclTensor(out, outDeviceAddr);
    aclrtDestroyStream(stream);
    aclFinalize();
    return 0;
}

**WHY讲解：**这个代码段展示了aclnn调用的完整生命周期。Init函数内部完成了aclOpenDevice和aclrtCreateStream两个关键操作，前者让Host进程获得对指定NPU设备的访问权限，后者创建了一个命令流用于组织和排序算子执行。CreateAclTensor函数的作用是在NPU上分配设备内存并将Host数据拷贝过去——注意这里有两个地址：selfXDeviceAddr是指向NPU设备内存的指针，Host上的selfXHostData只是初始化数据的来源。aclnnAdd执行完成后，结果还在NPU设备内存中，必须通过aclrtMemcpy将数据拷回Host才能打印验证。没有aclrtSynchronizeStream的话，打印出来的数据可能还是旧值，因为算子可能还没执行完。

使用build.sh快速执行eager模式算子样例是最简化的验证方式，不需要手动写编译脚本：

# 直接执行build.sh内置的算子样例运行功能
bash build.sh --run_example add eager cust --vendor_name=custom

# 执行结果
add first input[0] is: 1.000000, second input[0] is: 1.000000, result[0] is: 2.000000

5.2 GE图模式（构图调用）

GE（Graph Engine）图模式适用于需要将多个算子组合成计算图进行优化的场景。在图模式下，每个算子被表示为一个节点，节点之间的边表示数据依赖关系。GE会在图级别做算子融合、常量折叠、布局转换等优化，这些优化在eager模式下是无法实现的。

图模式调用的核心是构造一个Graph对象，将算子节点和输入输出连接起来，然后通过Session运行整个图：

int main() {
    // 1. 创建Graph对象
    Graph graph("add_graph");

    // 2. 初始化GE全局选项（必须调用）
    Status ret = ge::GEInitialize(globalOptions);

    // 3. 创建Add算子节点，参数是节点名称
    auto addNode = op::Add("add_node");

    // 4. 定义输入输出
    std::vector<Operator> inputs{};
    std::vector<Operator> outputs{};

    // 5. 使用宏展开方式绑定输入输出张量
    std::vector<int64_t> xShape = {32, 4, 4, 4};
    aclDataType inDtype = ACL_FLOAT;
    ADD_INPUT(1, x1, inDtype, xShape);   // 第1个输入
    ADD_INPUT(2, x2, inDtype, xShape);  // 第2个输入
    ADD_OUTPUT(1, y, inDtype, xShape);  // 输出

    // 6. 将addNode设置为图的输出
    outputs.push_back(addNode);

    // 7. 设置图的输入和输出算子
    graph.SetInputs(inputs).SetOutputs(outputs);

    // 8. 创建Session并注册图
    ge::Session* session = new Session(buildOptions);
    uint32_t graphId = 0;
    ret = session->AddGraph(graphId, graph, graphOptions);

    // 9. 准备输入数据并运行图
    std::vector<ge::Tensor> input;
    ret = session->RunGraph(graphId, input, output);

    // 10. 清理GE资源
    GEFinalize();
    return 0;
}

**WHY讲解：**图模式的核心优势在于GE可以在运行时对整张图做图级优化。例如，如果连续有两个Add操作，GE会自动将它们融合成一个Add算子执行，减少中间结果的访存开销。此外，GE还会做shape inference、dtype检查等静态分析，在真正执行前就能发现输入形状不匹配等错误。Session对象是GE的核心抽象，它管理图的编译缓存、算子调度队列、以及与Runtime的交互。在实际生产部署中，图模式通常与模型序列化结合使用——先构图编译生成离线模型文件（.om格式），然后直接加载执行，这样可以完全脱离Python环境，适合嵌入式或服务器端的高性能推理场景。

5.3 PyTorch算子注册（框架集成）

当需要将ops-math中的算子直接集成到PyTorch训练流程中时，可以使用算子注册方式。这种方式将算子Kernel注册到PyTorch的Dispatcher系统，使得算子可以像调用torch.add、torch.matmul一样直接调用，而不需要显式处理Device-to-Host数据拷贝。

ops-math提供了一个轻量级算子注册框架（fast_kernel_launch_example），使用Python C Extension机制将算子暴露给PyTorch：

# 进入轻量级算子开发框架目录
cd examples/fast_kernel_launch_example

# 安装算子包（会自动注册到PyTorch）
pip install -e . --verbose

# 在Python中直接调用
python -c "
import torch
from ascend_ops import add

# 直接在NPU上调用ops-math的add算子
x = torch.randn(1024, 1024, device='npu')
y = torch.randn(1024, 1024, device='npu')
z = add(x, y)  # 像调用torch.add一样调用自定义算子
print(z)
"

**WHY讲解：**PyTorch算子注册方式的核心是Python C Extension。setup.py中的torch.utils.cpp_extension.CUDAExtension将C++代码编译成CUDA风格的.so模块（虽然这里实际上是NPU模块），PyTorch的Dispatcher根据输入张量的device类型自动路由到NPU实现。整个过程对用户透明——用户不需要关心张量在哪个设备上，不需要手动调用aclrtMemcpy，一切都在PyTorch的张量抽象下自动完成。这种方式非常适合需要将自定义算子嵌入到现有PyTorch训练脚本中的场景，如自定义Loss函数、自定义激活函数等。

6. 效率对比：使用ops-math前后的实际差异

理解ops-math的价值，最好的方式是通过具体数据来感受。以下从三个维度对比使用ops-math前后的差异。

6.1 矩阵运算性能对比

在昇腾NPU上，使用ops-math内置的优化算子与使用纯AI Core汇编级手写实现的性能差异，主要体现在Tiling策略和向量化加载上。以矩阵加法为例，优化后的算子实现采用了多级Tiling策略：首先将大矩阵按AI Core的存储层级（GMem -> UBffer -> RegFile）分层搬入，然后在UBffer中完成向量化SIMD计算，最后结果直接写回GMem。相比手写的不带Tiling的单核实现，优化后的算子在Ascend 910上可以将4096x4096规模的矩阵加法吞吐提升约6倍。

更关键的是类型多样性和数值精度。ops-math的math类算子支持从INT8到FLOAT64的完整数据类型覆盖，还支持BFLOAT16（对大模型训练极为重要）和COMPLEX64/COMPLEX128（对信号处理任务必需）。手写实现很难在每种数据类型上都做针对性的精度优化和性能调优，而ops-math作为基础设施库，在每种数据类型上都经过标准化的精度验证。

6.2 开发效率对比

从开发效率角度看，ops-math提供的eager调用方式让一个算子的功能验证周期从"天"级别缩短到"分钟"级别。不使用ops-math的情况下，开发者需要自己实现完整的Host-Device交互代码，包括内存分配、数据拷贝、同步等待等，这些代码不仅量大，而且容易出错。使用aclnn接口后，同样的功能只需要关注算子本身的语义逻辑，ACL层自动处理了所有底层细节。

以AddExample为例，从源码下载到算子正确执行，全流程可以在30分钟内完成。如果使用原始的手写方式，仅Tiling策略的调试就可能耗费数天时间。ops-math提供的不仅是一个个算子实现，更是一套完整的工程框架——包括编译系统、测试框架、调优工具链。

6.3 全量编译与单算子编译的时间对比

ops-math的全量编译涉及所有算子（目前已超过300个算子），在16核x86服务器上使用-j16并行编译，完整编译时间约为15到20分钟。但更重要的是ops-math支持的单算子编译机制：开发者只需要指定–ops参数即可只编译目标算子，编译时间从20分钟缩短到约30秒。

这个差异在实际开发中的影响是巨大的：假设一个开发者在一天内要调试一个算子的5个不同版本，如果不使用单算子编译，每次改动后都要等待20分钟的完整编译，一天下来实际开发时间可能只有2到3个小时；而使用单算子编译，5次编译的总时间只有2.5分钟，几乎所有时间都可以用于真正的开发工作。

7. 自定义算子开发：从AddExample出发

掌握了算子的调用方式后，接下来进入自定义算子开发环节。AddExample是ops-math中最适合入门的示例，因为它结构完整、实现简洁、功能明确——整个算子只做一件事：将两个输入张量相加输出结果。

7.1 算子目录结构

在开始写代码之前，必须理解AddExample的目录结构以及每个文件的作用。AddExample是一个标准的AI Core算子，其完整目录如下：

examples/add_example/
  ├── op_kernel/                    # 算子Kernel实现（AI Core上运行）
  │   ├── add_example.h             # Kernel核心逻辑定义
  │   ├── add_example.cpp           # Kernel入口和调度
  │   ├── add_example_tiling.h      # Tiling策略头文件
  │   └── add_example_tiling_data.h # Tiling参数定义
  ├── op_host/                      # Host侧实现（CPU上运行）
  │   ├── add_example_def.cpp       # 算子信息注册
  │   └── add_example_infershape.cpp # Shape推导实现
  ├── op_graph/                     # 图模式相关（原型定义）
  │   └── add_example_proto.h
  └── examples/                     # 调用示例
      ├── test_aclnn_add_example.cpp # aclnn调用样例
      └── test_geir_add_example.cpp  # GE图模式样例

7.2 Kernel实现：核心计算逻辑

算子的核心计算逻辑在op_kernel/add_example.h中定义。Ascend C是昇腾AI Core的编程模型，它提供了一套类C++的API用于编写算子核心逻辑。AddExample的Kernel实现使用了AscendC::Add这个向量化计算接口：

// op_kernel/add_example.h
template <typename T>
__aicore__ inline void AddExample<T>::Compute(int32_t progress)
{
    // 第一步：从输入队列中取出一个Tile的数据
    AscendC::LocalTensor<T> xLocal = inputQueueX.DeQue<T>();
    AscendC::LocalTensor<T> yLocal = inputQueueY.DeQue<T>();

    // 第二步：为输出分配存储空间
    AscendC::LocalTensor<T> zLocal = outputQueueZ.AllocTensor<T>();

    // 第三步：调用AscendC的向量化Add接口完成计算
    // tileLength_是Tiling策略确定的每个Tile处理的元素个数
    AscendC::Add(zLocal, xLocal, yLocal, tileLength_);

    // 第四步：将结果放回输出队列，交由框架处理后续流程
    outputQueueZ.EnQue<T>(zLocal);

    // 第五步：释放已用完的输入Tensor（将内存归还复用池）
    inputQueueX.FreeTensor(xLocal);
    inputQueueY.FreeTensor(yLocal);
}

**WHY讲解：**这段代码看似简单，实际上蕴含了Ascend C编程模型的核心设计思想。LocalTensor是Ascend C对AI Core本地存储（UBffer）的抽象——它不是一个普通指针，而是一个带有存储层级信息的句柄，底层会自动处理数据在GMem和UBffer之间的搬入搬出。inputQueueX.DeQue()不是简单的malloc，而是一个生产者-消费者队列的操作：从队列中取出一个Tile的输入数据，队列的另一边连接着数据预取模块。AscendC::Add是昇腾SIMD（单指令多数据）向量化计算接口，它的第三个参数tileLength_指定了向量化处理的宽度——这个值不是随意设定的，而是在Tiling阶段根据数据规模和硬件缓存容量精心计算出来的。如果tileLength_设置过小，向量化效率会降低；如果设置过大，可能会导致UBffer溢出。

7.3 Tiling策略：计算粒度的艺术

Tiling是NPU算子开发中最核心也是最复杂的环节之一。它的本质是将一个大张量划分成多个小块（Tile），每个Tile可以被AI Core完整加载到UBffer中计算。Tiling策略的好坏直接决定了算子的性能——好的Tiling策略可以让AI Core的Vector计算单元利用率接近100%，差的Tiling策略可能只能达到30%甚至更低。

AddExample的Tiling实现在add_example_tiling.h中：

// add_example_tiling.h
struct AddExampleTiling {
    int32_t blockLength;   // 每个Block处理的元素个数
    int32_t tileNum;        // 分成多少个Tile
    int32_t totalLength;    // 总元素个数
};

// Tiling策略计算逻辑
void AddExampleTilingData::SetTiling()
{
    // 1. 根据输入总元素个数计算Block长度
    blockLength_ = (tilingData->totalLength + AscendC::GetBlockNum() - 1) / AscendC::GetBlockNum();

    // 2. 根据Block长度和UBffer容量计算Tile数量
    // BUFFER_NUM是硬件定义的UBffer缓冲区数量（通常为2或3）
    tileNum_ = (blockLength_ + TILING_BUFFER_SIZE - 1) / TILING_BUFFER_SIZE;
    tileLength_ = (blockLength_ + tileNum_ - 1) / tileNum_;
}

**WHY讲解：**GetBlockNum()返回的是参与计算的AI Core核数。昇腾NPU支持多核并行计算——一个4096x4096的矩阵会被自动划分到多个AI Core上并行处理。blockLength_的含义是"每个AI Core核负责多少个元素"，tileNum_的含义是"每个核内部还要把数据分成多少个Tile来分批处理"。分Tile的必要性在于UBffer的容量有限——即使是一个AI Core，也不可能一次性把4096x4096个FLOAT32数据全部加载到UBffer中（UBffer通常只有几百KB），必须分批搬入、分批计算、分批写回。这种分批策略就叫Tiling，而Tiling参数的质量就决定了UBffer的利用率——理想情况下，tileLength_应该恰好等于UBffer容量能容纳的元素个数，这样每次搬入的数据都能被充分计算，不会产生UBffer空间浪费。

7.4 打印调试与性能采集

算子开发过程中不可避免会遇到功能错误或性能瓶颈。ops-math提供了两套调试手段：PRINTF日志打印和msprof性能分析。

在Kernel代码中添加打印的典型场景是确认数据流是否正确：

// 在op_kernel/add_example.h中添加调试打印
blockLength_ = (tilingData->totalLength + AscendC::GetBlockNum() - 1) / AscendC::GetBlockNum();
tileNum_ = tilingData->tileNum;
tileLength_ = ((blockLength_ + tileNum_ - 1) / tileNum_ / BUFFER_NUM) ?
      ((blockLength_ + tileNum_ - 1) / tileNum_ / BUFFER_NUM) : 1;

// 打印当前核的Block长度和Tile参数
AscendC::PRINTF("BlockLength is %d, TileNum is %d, TileLength is %d\n",
                blockLength_, tileNum_, tileLength_);

// 如果需要打印Tensor内容（截取前128个元素）
AscendC::LocalTensor<T> zLocal = outputQueueZ.DeQue<T>();
DumpTensor(zLocal, 0, 128);  // 打印从索引0开始的128个元素

性能采集使用msprof工具，它可以生成算子各阶段的耗时分解，包括数据搬入耗时、计算耗时、数据搬出耗时、以及各阶段的占比。msprof是昇腾官方的性能分析工具，运行在NPU上可以直接读取硬件性能计数器，不依赖任何软件插桩，因此精度非常高。

# 生成可执行文件（如果还没有）
bash build.sh --run_example add_example eager cust --vendor_name=custom

# 采集性能数据
cd build/
msprof --application="./test_aclnn_add_example"

8. experimental目录与社区贡献

ops-math不仅是一个算子库，更是一个开放的算子开发平台。experimental目录正是为此设计的——它为社区开发者提供了存放和调试自定义算子的空间，而不需要改动主仓库的代码结构。

experimental目录的组织方式与主目录完全一致，也分为conversion、math、random三个子目录。开发者可以将自己的算子放在对应目录下，参考主仓库的算子模板完成开发，然后通过build.sh的–experimental参数编译和运行。

# 编译experimental目录下的自定义算子
bash build.sh --pkg --experimental --soc=ascend910b --ops=my_custom_op -j16

# 运行experimental目录下的算子样例
bash build.sh --experimental --run_example my_custom_op eager cust --vendor_name=custom

experimental目录的设计解决了算子开发中的一个实际痛点：在生产环境的算子库中，任何一个算子的修改都需要经过完整的代码评审和质量验证流程，周期较长。而experimental目录允许开发者独立开发、自由试错，直到算子成熟后再提交贡献。这种"实验田"模式既保证了主仓库的稳定性，又降低了社区参与的门槛。

9. 从算子调用到模型集成

ops-math的价值最终要通过上层模型体现。开发者通常有两种集成路径：将算子注册到PyTorch中作为自定义OP使用，以及通过aclnn接口在C++应用层直接集成。

PyTorch集成的关键在于理解Dispatch机制。PyTorch的NPU后端通过at::Dispatch机制根据输入张量的device类型自动选择对应的算子实现。当我们通过fast_kernel_launch_example将ops-math算子注册后，PyTorch会在执行每个算子调用时查询Dispatcher——如果输入是NPU张量，就路由到我们在C++中定义的NPU实现。整个过程对Python层完全透明，用户只需要在定义张量时指定device=‘npu’，后续的操作会自动在NPU上执行。

对于C++应用层集成（不依赖Python），最直接的方式是使用aclnn接口。应用层代码直接链接ops-math编译出的动态库，在代码中构造输入张量、调用aclnn API、执行同步即可。这种方式的优点是完全没有Python依赖，适合部署在纯C++的生产环境中；缺点是需要开发者自己管理内存和生命周期。

10. 实际项目中的选型建议

在实际项目中使用ops-math时，需要根据具体场景选择合适的调用方式。

如果项目处于算法验证阶段，重点是快速验证新算子的功能正确性，优先选择eager模式下的build.sh快速执行。用一条命令就能编译运行一个算子，改代码后再编译运行，整个迭代周期控制在分钟级别。

如果项目是正式的训练或推理任务，需要考虑性能优化和部署便利性。对于训练场景，建议使用PyTorch算子注册方式，将自定义算子无缝嵌入到训练流程中。对于推理场景，如果追求极致性能和最小化部署，推荐使用图模式编译生成.om离线模型文件，然后用aclrt接口直接加载执行——离线模型的加载速度比在线构图快10倍以上。

如果项目需要支持多种昇腾芯片（Atlas A2、A3、Ascend 950等），在开发阶段需要使用单算子编译配合–soc参数分别构建。同一套算子源码只需要在编译时指定不同的soc_version，即可生成对应芯片的二进制包。开发过程中要特别注意不同芯片的UBffer大小和AI Core数量差异——这些硬件参数直接影响Tiling策略的选择。

结语

ops-math是昇腾CANN生态中最基础也最核心的算子仓库之一。它不仅仅提供了一套可用的数学算子实现，更重要的是提供了一套完整的算子开发工程框架：从Tiling策略到Kernel实现，从eager调试到图模式部署，从单算子编译到全量包构建，每一个环节都有标准化的工具和文档支撑。

掌握了ops-math的开发范式，就掌握了在昇腾NPU上进行高性能计算的核心能力。无论是自定义新的数学算子，还是优化现有的模型性能，抑或是将PyTorch/TensorFlow模型高效部署到昇腾平台，ops-math都是不可或缺的底层基础设施。

---

仓库链接：https://atomgit.com/cann/ops-math