前言

昇腾CANN作为华为昇腾AI处理器的核心软件栈，提供了完整的算子开发与管理体系。在深度学习和科学计算领域，矩阵运算、张量变换和基础数学计算是支撑各类算法落地的关键基石。ops-math作为CANN算子库中的数学类算子库，承载着从基础算术到复杂数学变换的全栈能力，为昇腾NPU提供了高性能的数值计算支持。

ops-math项目覆盖了conversion类、math类、random类等多个算子类别，实现了张量形态变换、基础数学运算、随机数生成等核心功能。随着Ascend 950系列芯片的推出，ops-math持续演进，通过Ascend C编程语言实现算子内核，充分发挥昇腾NPU的硬件算力优势。

ops-math架构与算子分类

ops-math采用分层设计，将数学算子按照功能特性划分为多个独立模块，每个模块职责清晰，便于开发者快速定位和维护。

算子库目录结构

ops-math的源码组织遵循CANN算子开发规范，主要目录包括：

• math/ - 基础数学算子，包含abs、acos、add、mul、matmul等标准数学运算。该目录已实现超过60个数学算子，覆盖三角函数、指数对数、矩阵运算等科学计算核心需求。每个算子独立维护自己的kernel实现、tiling策略与单元测试。
• conversion/ - 张量形态变换算子，负责数据类型转换、维度重排、切片拼接等操作。典型算子包括cast（类型转换）、transpose（转置）、concat（拼接）等，这些算子在神经网络的前向推理和反向传播中频繁调用。
• random/ - 随机数生成算子，提供正态分布、均匀分布、随机采样等能力。random目录下的算子支持可复现的随机种子机制，满足模型训练和推理的一致性要求。
• examples/ - 算子开发示例，以add_example为模板展示完整的算子开发流程。开发者可以参考该目录下的代码结构和编译配置，快速创建自定义算子。
• docs/ - 文档中心，包含快速入门、编译指南、API参考等。文档覆盖从环境准备、算子开发、性能调优到社区贡献的全流程。
• common/ - 公共头文件和工具类，提供算子开发的通用基础设施。包括tiling_base_class.h（Tiling基类）、math_tiling_templates_registry.h（模板注册）等，避免各算子重复实现相同逻辑。

支持的芯片平台

ops-math紧跟昇腾硬件演进路线，当前支持以下芯片平台：

• Atlas A2训练系列产品/Atlas A2推理系列产品（soc_version: ascend910b）
• Atlas A3训练系列产品/Atlas A3推理系列产品（soc_version: ascend910_93）
• 950系列Products（soc_version: ascend950）

不同芯片平台的指令集和内存层次结构存在差异，ops-math通过统一的编译框架和Tiling策略，实现算子在不同平台间的高效迁移。

深度实践：从零开发自定义数学算子

本节以add_example算子为实践载体，完整展示在ops-math中开发、编译、调试和验证算子的全流程。选择这个例子是因为它覆盖了算子开发的核心要素：核函数实现、Tiling策略、主机端调用接口，且代码简洁易懂。

环境准备与源码获取

开发昇腾NPU算子前，需要准备CANN软件包和配套的项目源码。CANNLab云开发环境或Docker容器是最快捷的入门方式，它们默认提供了最新商发版CANN包和配套源码。

对于自定义版本需求，需要根据CANN版本下载配套的分支源码：

# 查看当前环境CANN版本
cat ${ASCEND_HOME_PATH}/version.info

# 下载9.0.0版本配套的ops-math源码
git clone -b 9.0.0 https://atomgit.com/cann/ops-math.git
cd ops-math

CANN算子与软件版本强绑定，因为算子内核依赖特定的运行时API和指令集支持。使用配套版本能避免API不兼容导致的编译或运行错误。git clone时指定-b参数检出对应分支，确保源码与环境中CANN版本一致。

算子内核实现解析

add_example算子展示了最基础的双输入加法运算，其核函数代码位于examples/add_example/op_kernel/add_example.h。理解这段代码是掌握Ascend C编程的关键。

template<typename T>
class AddExample {
public:
    __aicore__ inline AddExample() {}
    __aicore__ inline void Init(AddExampleTilingData* tilingData, int32_t blockIdx);
    __aicore__ inline void Compute(int32_t progress);
    
private:
    // 管道队列，用于输入输出数据的流水并行
    TPipe pipe;
    TQue<QuePosition::VECIN, BUFFER_NUM> inputQueueX;
    TQue<QuePosition::VECIN, BUFFER_NUM> inputQueueY;
    TQue<QuePosition::VECOUT, BUFFER_NUM> outputQueueZ;
    
    // Tiling参数
    int32_t blockLength_;
    int32_t tileNum_;
    int32_t tileLength_;
};

template<typename T>
__aicore__ inline void AddExample<T>::Compute(int32_t progress)
{
    // 从输入队列取出LocalTensor
    AscendC::LocalTensor<T> xLocal = inputQueueX.DeQue<T>();
    AscendC::LocalTensor<T> yLocal = inputQueueY.DeQue<T>();
    AscendC::LocalTensor<T> zLocal = outputQueueZ.AllocTensor<T>();
    
    // 调用Ascend C API执行矢量加法
    AscendC::Add(zLocal, xLocal, yLocal, tileLength_);
    
    // 将结果入队，释放输入Tensor
    outputQueueZ.EnQue<T>(zLocal);
    inputQueueX.FreeTensor(xLocal);
    inputQueueY.FreeTensor(yLocal);
}

这段代码展示了Ascend C编程的核心范式——流水并行和LocalTensor管理。TPipe和TQue实现了DMA传输与计算的重叠，提升硬件利用率。Compute函数每次处理一个tile的数据，通过DeQue获取输入、AllocTensor分配输出、Add调用矢量计算指令、EnQue送回输出，形成完整的数据流。这种设计充分匹配昇腾NPU的Vector Core执行模型。

Tiling策略与任务划分

高效的算子实现必须将大数据集合理划分到多个AI Core上并行执行，这由Tiling策略完成。add_example的Tiling实现位于examples/add_example/op_host/add_example_tiling.h。

Tiling的核心任务是根据输入张量形状和硬件资源限制，计算出每个AI Core处理的数据量和分块策略。对于一维加法算子，Tiling逻辑相对简单：将总数据量均匀分配到所有AI Core，每个AI Core内部再按Cache大小分tile。

class AddExampleTilingFunc {
public:
    explicit AddExampleTilingFunc(int32_t totalLength, int32_t tileNum) 
        : totalLength_(totalLength), tileNum_(tileNum) {}
    
    void RunKernelTiling() {
        // 计算每个AI Core处理的数据长度
        blockLength_ = (totalLength_ + GetBlockNum() - 1) / GetBlockNum();
        // 计算每个tile处理的数据长度
        tileLength_ = (blockLength_ + tileNum_ - 1) / tileNum_;
        // 修正边界，确保不越界
        if (tileLength_ * tileNum_ * GetBlockNum() > totalLength_) {
            // 边界处理逻辑
        }
    }
    
private:
    int32_t totalLength_;
    int32_t tileNum_;
    int32_t blockLength_;
    int32_t tileLength_;
};

Tiling是算子性能优化的关键。合理的Tiling能最大化AI Core利用率，减少同步开销，隐藏DMA传输延迟。GetBlockNum()获取可用的AI Core数量，tileNum_控制每个AI Core内部的流水深度。Tiling参数会通过AddExampleTilingData结构体从主机端传递到设备端核函数。

编译与部署流程

ops-math提供统一的编译脚本build.sh，支持单算子编译和全量编译两种模式。对于开发调试阶段，推荐使用单算子编译以缩短迭代周期。

# 单算子编译，仅构建add_example算子
bash build.sh --pkg --soc=ascend910b --ops=add_example -j16

# 编译成功后生成的运行包位于build_out目录
ls build_out/cann-ops-math-custom_linux-aarch64.run

# 安装自定义算子包
./build_out/cann-ops-math-custom_linux-aarch64.run

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

单算子编译通过--ops参数指定目标算子，大幅减少编译时间，适合开发阶段快速验证。-j16开启16线程并行编译加速构建。--pkg参数生成可自行安装的run包，安装后算子库会被部署到${ASCEND_HOME_PATH}/opp/vendors路径下。运行时通过LD_LIBRARY_PATH指定自定义算子库的搜索路径。

调用与验证

ops-math为每个算子提供了标准的调用样例，位于examples/add_example/examples/test_aclnn_add_example.cpp。这个样例展示了如何通过ACLNN接口调用昇腾NPU算子。

int main() {
    // 定义输入张量形状
    std::vector<int64_t> shape = {32, 4, 4, 4};
    int64_t totalElements = 32 * 4 * 4 * 4;
    
    // 分配主机端内存并初始化数据
    std::vector<float> hostX(totalElements, 1.0f);
    std::vector<float> hostY(totalElements, 2.0f);
    std::vector<float> hostZ(totalElements, 0.0f);
    
    // 通过ACLNN接口调用算子
    aclnnAddExampleGetWorkspaceSize(shape, shape, shape, &workspaceSize, &executor);
    aclnnAddExample(workspace, workspaceSize, executor, stream);
    
    // 拷贝结果回主机并验证
    // 预期输出：每个元素值为 1.0 + 2.0 = 3.0
    std::cout << "result[0] = " << hostZ[0] << std::endl;
    
    return 0;
}

ACLNN是CANN提供的标准算子调用接口，屏蔽了底层设备管理和内存管理的复杂性。GetWorkspaceSize查询算子执行所需的临时工作空间大小，aclnnAddExample执行实际计算。通过提供完整的调用样例，ops-math降低了算子使用门槛，开发者可以参考样例快速集成算子到自己的应用中。

算子性能调试与优化

当算子功能正确但性能不达预期时，需要通过调试手段定位瓶颈。ops-math集成了多种调试方法，帮助开发者深入理解算子执行过程。

核函数内打印调试

Ascend C提供了PRINTF和DumpTensor两个调试接口，用于在核函数执行过程中输出关键信息和张量内容。

在add_example.h的Init函数中添加打印，可以确认Tiling参数计算是否正确：

__aicore__ inline void AddExample<T>::Init(AddExampleTilingData* tilingData, int32_t blockIdx) {
    blockLength_ = tilingData->blockLength;
    tileNum_ = tilingData->tileNum;
    tileLength_ = tilingData->tileLength;
    
    // 打印当前AI Core的Tiling信息
    AscendC::PRINTF("BlockIdx=%d, blockLength=%u, tileNum=%u, tileLength=%u\n", 
                    blockIdx, blockLength_, tileNum_, tileLength_);
}

PRINTF是核函数内的打印接口，类似于主机端的printf，但运行在设备端。通过打印Tiling参数，可以验证任务划分是否符合预期。如果某个AI Core的blockLength为0，说明Tiling计算有误，导致部分核心空闲。

性能数据采集

msprof是昇腾平台提供的性能采集工具，能够对算子执行过程进行细粒度的性能分析，包括AI Core利用率、DMA传输效率、指令流水等关键信息。

# 先编译生成可执行文件
bash build.sh --run_example add_example eager cust --vendor_name=custom

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

# 查看性能报告
ls profiling_output/
# 包含 timeline文件（可视化时间线）和 op_summary（算子执行统计）

性能优化的前提是找到瓶颈。msprof采集的数据可以导入MindStudio Profiler进行可视化分析，帮助识别是计算瓶颈、访存瓶颈还是同步开销过大。对于add这类简单算子，如果AI Core利用率低，通常是Tiling不合理或数据搬运开销占比过高。

使用前vs使用后

ops-math为昇腾NPU提供了系统化的数学算子支持。通过引入ops-math，开发者在算子开发效率、代码质量和跨平台兼容性方面获得显著提升。下表从多个维度对比使用ops-math前后的差异。

对比维度	使用前	使用后
算子开发方式	从零编写Ascend C核函数，手动处理Tiling、内存管理、接口适配	基于ops-math模板和公共库快速开发，复用TilingBaseClass等基础设施
编译构建	手写CMakeLists.txt，手动管理算子依赖和编译选项	使用统一build.sh脚本，支持单算子编译和全量编译，自动处理依赖
调试手段	缺乏系统化调试方法，依赖猜测和反复试错	集成PRINTF、DumpTensor、msprof等工具，形成完整的调试工具链
代码质量	各算子头文件引用混乱，命名空间污染风险高	通过重构统一引用base仓头文件，消除重复依赖，提升代码可维护性
芯片适配	每款芯片需要手动修改代码适配指令集差异	通过soc_version编译参数自动适配不同芯片，代码复用率高
算子覆盖	需要手动实现每个数学运算，开发周期长	直接调用ops-math提供的丰富算子库（abs、acos、add、matmul等），专注业务逻辑
贡献流程	无标准化流程，代码合并冲突频发	遵循CONTRIBUTING.md规范，通过MR流程进行代码审查和平滑合并
错误处理	错误码定义不统一，问题定位困难	使用规范化EZ0008-EZ0034系列错误码，结合OP_LOGE日志快速定位问题

算子贡献与社区协作

ops-math是一个活跃的开源项目，欢迎开发者贡献新算子和性能优化。项目维护了清晰的贡献指南和代码规范，确保社区代码质量。

贡献流程

1. Fork与分支 - 在AtomGit上Fork ops-math项目，基于master分支创建特性分支
2. 开发与自验 - 按照项目规范开发算子，完成二级冒烟测试和泛化测试
3. 提交MR - 填写MR描述模板，关联对应的Issue，等待代码审查
4. CI验证 - 自动化CI流水线会执行编译检查、功能测试、性能回归
5. 合并发布 - 审查通过后由cann-robot或Maintainer合并到主分支

代码质量保障

ops-math项目高度重视代码质量，近期完成了多项重构工作：

• 消除math和random算子中的重复头文件依赖，统一引用base仓的tiling_base_class.h和math_tiling_templates_registry.h
• 移除using namespace全局命名空间引用，改用显式命名空间限定，降低符号冲突风险
• 规范化错误码上报，将分散的OP_LOGE替换为统一的EZ系列错误码
• 完善每个算子的README文档，提供清晰的使用说明和参数描述

这些持续改进确保ops-math在快速演进的同时保持代码可维护性。

ops-math在科学计算中的价值

ops-math的价值不仅限于深度学习框架的后端算子支持，它为整个昇腾AI生态提供了基础数学计算能力。在科学计算领域，ops-math提供的矩阵运算、三角函数、指数对数等算子，可以直接支撑NumPy风格的数值计算库在昇腾NPU上的实现。与传统CPU实现相比，昇腾NPU的SIMD向量计算能力能够大幅加速大规模数值计算任务。

在推理部署场景，ops-math与CANN的图编译引擎深度集成，支持算子融合、内存复用等优化技术，提升端到端推理性能。开发者通过ACLNN接口调用的每个算子，都经过了Ascend C层面的精细优化。

结语

ops-math作为昇腾CANN生态中的数学算子库，通过系统化的架构设计、完善的开发工具和活跃的社区协作，为开发者在昇腾NPU上实现高性能数学计算提供了坚实支撑。从环境准备、算子开发、编译部署到性能调试，ops-math覆盖了算子开发的全生命周期。掌握ops-math的使用和开发方法，是深入理解昇腾AI软件栈的重要一步。通过实践本文介绍的完整流程，开发者能够快速上手昇腾NPU算子开发，为各类AI和科学计算应用注入硬件加速能力。

---

仓库地址：https://atomgit.com/cann/ops-math