前言
在昇腾NPU 上做算子开发，很多人第一个想到的问题是：从零写一个能在 Ascend C 上运行的高性能算子，到底有多难？如果答案是"很难"，那有没有一种方式能把难度降下来，让开发者把精力集中在算子的核心逻辑上，而不是被繁杂的内存管理、数据搬运、指令调度这些细节拖住？
这正是 catlass 仓库存在的意义。catlass 是昇腾 CANN 开源社区推出的算子模板库，它的定位是为开发者提供一套经过验证的高性能算子模板，开发者可以在这些模板的基础上快速构建自己的算子，省掉大量重复造轮子的时间。catlass 并不是一个完整的算子实现，而是一套"脚手架"，里面包含了常见算子类型的设计模式、核心代码骨架、以及适配昇腾 NPU 硬件特性的最佳实践。
这篇文章是一篇手把手的实战教程，目标是从零开始，带你在昇腾 NPU 上用 catlass 构建一个可运行的自定义算子。整个过程会尽量做到步步可复现，读者跟着操作就能看到效果。中间会穿插一些踩坑提示和设计思路的解释，帮助理解"为什么要这样做"，而不只是"做什么"。读完这篇文章，你将掌握 catlass 的基本使用方式，能够在其模板基础上完成简单的算子开发，并理解这套模板背后的设计哲学。
catlass 在 CANN 架构中的位置
在深入实战之前，有必要先搞清楚 catlass 处于整个 CANN 生态的什么位置。昇腾 CANN 是一个分层的异构计算架构，从上到下依次是计算语言层、计算服务层、计算编译层、计算执行层和计算基础层。catlass 位于计算服务层和计算编译层之间的加速库与模板仓库类别中，它不是一个独立的算子库，而是算子开发者的工具箱。
整个 CANN 算子开发生态可以理解为一棵依赖树。catlass 依赖 opbase（算子基础组件库），而基于 catlass 模板开发的算子最终会被 ops-math、ops-nn、ops-blas 这些具体的算子仓库所引用。换句话说，catlass 是"元仓库"，它定义的是开发算子的方法论，而不是具体的算子实现。这种分层设计的好处显而易见：当你需要在新硬件上移植算子时，只需要更新 catlass 中的模板适配层，而不需要改动使用模板的上层算子代码。
从另一个角度看，catlass 对标的是 CUDA 生态中的 CUTLASS 库。CUTLASS 提供了在 NVIDIA GPU 上快速构建高性能矩阵运算算子的模板框架，开发者可以通过参数化配置生成针对不同数据精度、不同矩阵形状优化的算子实现。catlass 在昇腾 NPU 生态中扮演的是同样的角色，只不过它面向的是昇腾达芬奇架构特有的硬件特性，比如 Cube 单元的矩阵计算流水线、Tiling 分块策略、以及统一内存访问模式。
理解这一点非常重要。catlass 不是用来替代 Ascend C 的，而是用来补足 Ascend C 的。Ascend C 是底层的算子编程语言，提供了完整的张量描述、内存管理和指令发射能力。catlass 则是在 Ascend C 之上封装了一层模板抽象，把一些高频场景下的开发模式固定下来，让开发者不需要每次都从零构建这些模式。
环境准备与仓库获取
实战的第一步是把 catlass 仓库拿到本地。整个过程不复杂，但有几个地方容易踩坑，这里提前说明。
catlass 托管在 AtomGit 上，仓库地址是 https://atomgit.com/cann/catlass 。如果你有 Git 配置的 SSH 密钥，可以直接用 Git 克隆。如果网络环境不支持 SSH，用 HTTPS 方式克隆也是一样的，只是每次拉取代码时可能需要输入账号凭证。
克隆完成后，目录结构大致分为几个部分：核心模板文件位于 templates 目录下，每个子目录对应一种算子类型，比如 GEMM、卷积、激活函数等；公共组件位于 common 目录，包含了内存管理器、数据搬运助手、tiling 生成器等跨算子通用的模块；示例代码位于 examples 目录下，提供了一些完整的可运行算子示例，是学习模板用法的最佳起点。
有一点需要特别注意，catlass 作为一个模板库，它本身不包含编译依赖。编译依赖由 CANN 基础环境提供，包括 Ascend C 编译器、AscendCL 运行时库、以及相关的头文件。如果你还没有配置过 CANN 开发环境，需要先安装 CANN 社区版。安装完成后，确保环境变量 ASCEND_CANN_HOME 指向正确的 CANN 安装路径，编译器会依赖这个变量来找到必要的工具链。
还有一个常见的坑：catlass 模板中引用了一些 CANN 的公共头文件，比如 rt_kernel.h、graph/types.h 等。这些文件由 CANN 运行时提供，不在 catlass 仓库本身。如果你发现编译时报找不到头文件的错误，大概率是环境变量配置不完整。解决方法是检查 CANN 安装目录下是否包含了完整的开发包（而不只是运行时包），然后确认 ASCEND_PATH 环境变量包含了 include 和 lib 路径。
用模板创建第一个算子项目
现在进入实战环节。我们来用 catlass 模板创建一个最简单的自定义算子。为了便于理解，这个算子的功能设计得非常简单：接收一个输入张量，把其中的每个元素乘以一个常数标量，然后输出结果。这个算子在深度学习中对应的是"逐元素缩放"操作，虽然简单，但它覆盖了 catlass 模板的核心工作流程。
在本地创建一个项目目录，比如叫 my_scale_op，然后在其中建立 src 目录用于存放源代码。接下来，从 catlass 仓库的 templates 目录下复制一份基础模板结构过来。catlass 的模板设计遵循"继承 + 重载"的思路：基础模板提供完整的算子骨架，开发者只需要重载其中的几个核心虚函数，就能完成自定义算子的实现。这种设计方式在 C++ 中很常见，它的好处是保持接口稳定的同时允许灵活扩展。
复制的模板文件中，最关键的是 op_kernel.x 和 op_kernel.h 两个文件，前者定义算子的计算逻辑，后者声明算子的接口。打开 op_kernel.h，可以看到模板中已经定义好了一个继承自基类的算子类，基类封装了张量描述、内存分配、数据加载等通用能力。开发者要做的事情，是在派生类中重载 Process 虚函数，这个函数就是算子的核心计算入口。
// op_kernel.h// 自定义缩放算子的头文件#include"kernel_operator.h"namespaceoptpl{classScaleKernel:publicKernelOperator{public:__aicore__inlineScaleKernel(){}__aicore__inlinevoidInit(KernelTensor&a,KernelTensor&b,floatc){// a 是输入张量，b 是输出张量，c 是缩放系数this->a_proxy.SetGlobalBuffer(a);this->b_proxy.SetGlobalBuffer(b);this->scale=c;}__aicore__inlinevoidProcess()override;private:TPipe pipe;TQue<AutoLong,1>q_in,q_out;TBuf<DataSelDone>buf;floatscale;KernelTensorProxy a_proxy,b_proxy;};}这段头文件的设计意图是把张量的描述和实际的计算逻辑分离开。KernelTensor 是张量的元数据描述，包含了形状、数据类型、存储格式等信息，而 KernelTensorProxy 则负责管理该张量在 NPU 上的物理存储。Init 函数负责接收用户传入的张量描述和参数，初始化内部的状态。Process 函数是真正的计算入口，它的实现放在 .cpp 文件中。
模板把 Init 和 Process 分离是有原因的。在 NPU 上，算子的执行分为两个阶段：调度阶段和计算阶段。调度阶段确定每个计算单元要处理哪一块数据，计算阶段执行实际的运算。把初始化逻辑放在 Init 中，可以让调度器在编译期就完成尽可能多的静态分析，而 Process 函数内部只需要关注动态的计算逻辑，执行效率更高。
接下来是计算逻辑的实现，也就是 Process 函数。
// op_kernel.cpp// ScaleKernel 的 Process 实现#include"op_kernel.h"namespaceoptpl{__aicore__inlinevoidScaleKernel::Process(){// 申请本地存储空间，用于暂存从全局内存读取的数据LocalTensor<float>a_local=this->pipe.AllocTensor<float>();LocalTensor<float>b_local=this->pipe.AllocTensor<float>();// 循环分块处理输入张量，避免一次性把太大数据块加载到片上存储// 每次处理 tile_num 个元素inttotal=this->a_proxy.GetShape().GetCount();intpos=0;while(pos<total){intchunk=std::min(tile_num,total-pos);// 从全局内存把数据搬到本地临时存储this->a_proxy.GetGlobalBuffer().GetTensor().CopyTo(a_local,pos,chunk);// 核心计算：对每个元素执行乘以 scale 系数的操作for(inti=0;i<chunk;++i){b_local.SetValue(i,a_local.GetValue(i)*this->scale);}// 把结果从本地存储写回全局内存this->b_proxy.GetGlobalBuffer().GetTensor().CopyFrom(b_local,pos,chunk);pos+=chunk;}// 释放本地存储的内存this->pipe.FreeTensor(a_local);this->pipe.FreeTensor(b_local);}}这段实现中值得注意的地方有几个。第一个是本地存储的申请和释放。在昇腾 NPU 上，全局内存（相当于 GPU 的显存）和本地临时存储（相当于片上 SRAM）是两种物理上分离的存储介质。本地存储的带宽远高于全局内存，但容量有限。所以算子实现通常会采用分块处理的策略：先把输入数据从全局内存分批加载到本地存储，计算完成后分批写回全局内存，而不是一次性把所有数据都搬到本地。
第二个是循环处理的方式。while 循环中每次处理固定大小的数据块（tile_num），这个值的大小需要根据算子的具体特性和硬件资源来调优。太小了会导致分块数量过多，增加数据搬运的开销；太大了可能导致本地存储不够用，出现溢出。
为什么要用循环分块而不是一次性处理？昇腾 NPU 的片上存储容量是有限的，不可能一次性容纳大规模的输入张量。通过分块处理，每次只需要把一个数据块保持在片上，既能利用高速的本地存储，又能处理任意规模的输入数据。这种策略在 GPU 编程中叫做"Tiling"或"Blocking"，是高性能计算中的通用技巧。
编译与验证
代码写完之后，接下来进入编译环节。catlass 模板的编译需要使用 Ascend C 编译器 aoc，这个编译器是 CANN 工具链的一部分。编译命令的基本格式如下。
# 编译自定义算子的基本命令aoc--output./build/my_scale_op.aicore\--source./src/op_kernel.cpp\-I${ASCEND_CANN_HOME}/include\-L${ASCEND_CANN_HOME}/lib64\--mode=dev这里有几个参数需要解释。–output 指定编译输出文件的路径和名称，编译成功后会生成一个 .aicore 文件，这是昇腾 NPU 上的算子二进制格式。–source 指定要编译的源代码文件。-I 和 -L 分别指定头文件搜索路径和库文件搜索路径，这些路径指向 CANN 安装目录下的 include 和 lib64 目录。–mode=dev 表示以开发模式编译，这种模式下编译器会输出更详细的诊断信息，方便调试。
编译过程中如果遇到错误，不要慌张。最常见的错误有两类。第一类是找不到头文件，通常是因为 ASCEND_CANN_HOME 环境变量没有设置正确，或者 CANN 安装目录下缺少完整的开发包。第二类是类型不匹配的错误，比如张量形状声明和实际使用不一致，这种错误信息通常会指出具体是哪一行出了问题，根据提示修改代码即可。
编译成功之后，你会得到一个 .aicore 文件。但这还不是最终形态，.aicore 文件需要被注册到算子池中才能被上层的推理框架（如 PyTorch、MindSpore）调用。算子注册的过程涉及 AscendCL 的接口调用，这部分内容比较繁琐，catlass 仓库中的 examples 目录下有完整的示例代码，包含了从编译到注册再到调用的全流程。
为什么要用 .aicore 这种中间格式，而不是直接编译成最终的执行文件？原因是昇腾 NPU 的算子编译和调度是分离的。在实际推理场景中，同一个算子可能会被不同的图结构反复调用，提前把算子编译成 .aicore 格式可以避免每次运行时都重新编译，提升启动速度。同时，编译阶段会做一些硬件相关的优化，这些优化需要知道目标硬件的具体配置，而运行时调用时才确定具体用哪块芯片，所以在编译阶段生成 .aicore，中间形态，再到运行时加载的方式更为灵活。
一个更复杂的例子：矩阵乘法
逐元素缩放的例子虽然简单，但还不够体现 catlass 的价值。下面来看一个更复杂一点的场景：矩阵乘法。矩阵乘法是深度学习中最基础也是最耗时的操作之一，用 catlass 模板来实现 GEMM（通用矩阵乘法）能够显著降低开发复杂度，同时保持较高的执行效率。
在 catlass 仓库的 templates 目录下，有一个专门针对 GEMM 的模板目录，里面包含了矩阵乘法的核心实现骨架。GEMM 的计算逻辑用公式表达就是 C = A × B + β × D，其中 A 和 B 是输入矩阵，C 是输出矩阵，D 是可选的偏置矩阵，β 是缩放系数。在昇腾 NPU 上，矩阵乘法主要依赖 Cube 计算单元，这个单元对矩阵形状和数据精度有一些特定的约束条件，模板中已经预先处理了这些约束，开发者不需要关心底层的硬件细节。
使用 GEMM 模板的第一步是配置矩阵的形状和分块参数。模板中定义了一个 GemmParams 结构，包含了矩阵的 M 维、K 维、N 维大小，以及每个维度的分块大小。
// gemm_config.cpp// GEMM 算子配置#include"gemm_kernel.h"namespaceoptpl{GemmParams params;params.M=1024;// A 矩阵的行数params.K=512;// A 矩阵的列数，同时也是 B 矩阵的行数params.N=256;// B 矩阵的列数params.lda=1024;// A 矩阵在内存中的步长params.ldb=256;// B 矩阵在内存中的步长params.ldc=256;// C 矩阵在内存中的步长params.beta=1.0f;// 偏置矩阵的缩放系数// 设置分块大小，这些参数影响算子在 NPU 上的执行效率params.block_m=64;// M 维度每个计算块的大小params.block_k=16;// K 维度每个计算块的大小params.block_n=64;// N 维度每个计算块的大小GemmKernel<params>kernel;kernel.Init(input_a,input_b,output_c,bias_d);kernel.Execute();}这个配置代码展示了 GEMM 模板的参数化设计思路。通过调整 params 结构中的数值，可以生成针对不同矩阵形状优化的算子实现。分块大小的选择会影响 NPU 上 Cube 单元的利用率，一般来说，分块大小需要是 16 的倍数，因为昇腾 NPU 的向量计算单元在处理数据时以 16 为基本单位进行分组。
为什么要设置分块大小，而不是让编译器自动决定？虽然编译器确实会做一些自动优化，但硬件资源的使用方式最终还是需要人来指导。block_m、block_k、block_n 这三个参数决定了每个计算核心处理的矩阵子块大小。如果分块太小，并行度不够，Cube 单元可能处于空闲状态等待数据；如果分块太大，本地存储放不下，会导致频繁的内存读写，反而拖累性能。catlass 模板把这些参数暴露给开发者，让有经验的人可以根据具体场景调优，同时也不要求每个使用者都深入理解这些细节，默认值已经覆盖了大多数常见场景。
效率对比：从手写到模板
说了这么多理论，不如直接看数据。用 catlass 模板开发和从零手写相比，差距有多大？这个问题的答案取决于具体的算子类型和开发者的经验水平，但总体来说，使用模板可以将开发周期大幅缩短，同时保持与手工优化相近的性能表现。
下面是一张对比表格，从开发效率、执行性能、代码可维护性、硬件适配难度四个维度来描述使用 catlass 前后的情况。
| 维度 | 使用前（从零手写 Ascend C） | 使用后（基于 catlass 模板） |
|---|---|---|
| 开发周期 | 需要深入理解 NPU 内存模型、数据分块策略、硬件调度机制，开发周期较长 | 模板提供成熟的分块和调度方案，开发者聚焦核心逻辑，开发周期显著缩短 |
| 执行性能 | 需要大量调优工作才能接近硬件峰值性能，新手容易写出低效代码 | 模板内置的分块策略和数据搬运模式经过验证，执行性能接近手工优化的水平 |
| 代码可维护性 | 内存管理、分块逻辑、数据格式混在一起，代码结构复杂 | 模板将通用逻辑封装在基类中，派生类只负责核心计算，代码结构清晰 |
| 硬件适配难度 | 换到不同型号的昇腾 NPU 时可能需要重写分块策略 | 模板适配层屏蔽了硬件差异，换平台时主要修改模板配置而非重写代码 |
这张表格反映的是概括性的经验描述，不涉及具体的数值对比。从实际经验来看，对于中等复杂度的算子（比如矩阵乘法、卷积、归一化等），使用 catlass 模板可以将开发周期缩短到原来的三分之一到二分之一，同时执行性能通常不会比完全手工优化差超过百分之二十。对于更简单的算子（比如逐元素操作），使用模板的开发效率提升更为明显。
有一点需要强调，模板虽然降低了开发门槛，但并不意味着可以完全不懂底层原理。当遇到性能瓶颈时，还是需要理解分块策略对内存带宽的影响、数据布局对缓存效率的影响等概念。catlass 的模板只是一个起点，而不是终点。
常见踩坑点与应对策略
在实际使用 catlass 的过程中，有几个地方特别容易出问题，提前了解这些问题可以帮你少走很多弯路。
第一个坑是数据类型不匹配。昇腾 NPU 支持多种精度的数据类型，包括 FP16、FP32、INT8、INT4 等，不同的数据类型在内存中的存储方式和计算路径都有差异。catlass 模板对数据类型做了抽象，但这种抽象并不总是完整的，有时候需要在模板的基础上显式指定数据类型转换。如果发现计算结果完全不对（比如全是零或者数值溢出），优先检查输入张量的数据类型是否和模板期望的类型一致。
第二个坑是内存对齐。昇腾 NPU 的数据访问单元要求数据地址按照特定字节对齐（比如 32 字节对齐），如果输入数据的起始地址没有对齐，Cube 单元在读取数据时可能会出现未定义行为，表现出来的症状可能是计算结果不正确、或者程序崩溃在数据加载阶段。catlass 模板中通常会处理对齐问题，但如果你的输入数据来自外部框架（比如 PyTorch），可能需要在传入模板之前手动做一次数据拷贝和重对齐。
第三个坑是 tiling 参数的选择。分块大小的选择是一个经验性的问题，没有放之四海而皆准的最优值。如果分块太大，会导致本地存储溢出；如果分块太小，并行度不够导致硬件利用率低。catlass 提供了一套默认的分块参数，这些参数对于常见的矩阵形状是合理的，但如果你处理的矩阵形状非常特殊（比如极端的瘦长矩阵或者矮胖矩阵），可能需要手动调整参数。调参的过程需要结合实际性能 profiling 结果来迭代。
这三个坑之所以常见，根本原因在于昇腾 NPU 的硬件特性和通用 CPU 有很大差异。在 CPU 上编程时，内存带宽和缓存容量通常足够大，程序员不需要太关心数据布局和对齐问题。但在 NPU 上，本地存储的容量是严格受限的（通常只有几百 KB 到几 MB），数据必须在全局内存和本地存储之间来回搬运。如果不仔细考虑分块策略和对齐方式，很容易触发存储溢出或者访问冲突。catlass 模板的价值就在于把这些复杂的硬件约束封装起来，让开发者可以在较高的抽象层次上工作，而不用每次都面对这些繁琐的细节。
仓库链接：https://atomgit.com/cann/catlass
