catlass：昇腾算子模板库的设计哲学

前言

你有没有想过，为什么每个算子都要手写tiling（分块）？明明都是矩阵乘，为什么GEMM要写一遍tiling，Conv2D又要写一遍tiling，Transformer的Attention还要再写一遍？

我刚接触Ascend C算子开发时，就是这样的——写一个MatMul算子，tiling逻辑写了200行，后来写Conv2D，发现tiling逻辑几乎一样，但又得重写一遍。后来发现了catlass这个仓库，它把通用tiling逻辑做成了模板，你只要填几个参数（矩阵大小、数据类型、计算精度），它自动生成高效的tiling代码。

这篇文章不是catlass的API文档翻译，是我实际使用过程中对"算子模板库"这个设计理念的思考，以及怎么用catlass把算子开发效率提升3-5倍。

为什么需要算子模板库？

痛点一：重复造轮子（tiling逻辑每个算子都要写）

Tiling（分块）是算子开发的核心——NPU的片上内存（Local Memory）只有192 KB，存不下整个矩阵，必须把矩阵分成小块（tile），一块一块地算。

问题：每个算子都要写tiling逻辑，而且大同小异。比如：

// MatMul算子的tiling逻辑（手写版）voidMatMul::Tiling(){// 分块参数inttile_m=128;// 每次算128行inttile_k=64;// 每次算64列inttile_n=128;// 每次算128列// 双层循环，按块计算for(inti=0;i<M;i+=tile_m){for(intj=0;j<N;j+=tile_n){// 1. 把A_tile和B_tile搬到片上内存LocalTensor<fp16>a_tile=A.Slice(i,tile_m,0,tile_k);LocalTensor<fp16>b_tile=B.Slice(0,tile_k,j,tile_n);// 2. 调Matrix单元算矩阵乘MatMul(a_tile,b_tile,c_tile);// 3. 把结果写回HBMC.Slice(i,tile_m,j,tile_n)=c_tile;}}}

// Conv2D算子的tiling逻辑（手写版）voidConv2D::Tiling(){// 分块参数（跟MatMul不一样！）inttile_n=64;// 每次算64个输出通道inttile_c=128;// 每次算128个输入通道inttile_h=7;// 每次算7行输出特征图inttile_w=7;// 每次算7列输出特征图// 四层循环，按块计算（比MatMul复杂！）for(intn=0;n<N;n+=tile_n){for(intc=0;c<C;c+=tile_c){for(inth=0;h<H;h+=tile_h){for(intw=0;w<W;w+=tile_w){// 1. 把输入tile和权重tile搬到片上内存LocalTensor<fp16>input_tile=Input.Slice(n,tile_n,c,tile_c,h,tile_h,w,tile_w);LocalTensor<fp16>weight_tile=Weight.Slice(n,tile_n,c,tile_c,...);// 2. 调Matrix单元算卷积Conv2D(input_tile,weight_tile,output_tile);// 3. 把结果写回HBMOutput.Slice(n,tile_n,h,tile_h,w,tile_w)=output_tile;}}}}}

关键洞察：tiling逻辑虽然每个算子都不一样，但模式是一样的——都是"分块参数 + 多层循环 + 搬数据 + 算 + 写回"。catlass把这个模式抽象成了模板，你只要填参数，它自动生成tiling代码。

痛点二：性能不一致（不同人写的算子性能差30-50%）

算子性能主要靠tiling参数调优（tile_m/tile_k/tile_n怎么设才能让HBM读写最少、计算单元利用率最高）。不同人写的算子，tiling参数调优程度不一样，性能差30-50%很常见。

示例：同样的MatMul算子，我写的只能跑287 GFLOPS，catlass模板生成的能跑412 GFLOPS，差了43%。

原因：catlass的模板内置了自动调优逻辑（根据矩阵大小、数据类型、NPU型号自动选最优tiling参数），我没这个能力（也不可能每个算子都手调tiling参数）。

痛点三：硬件感知难（不同NPU型号的Local Memory大小不一样）

Ascend 910的Local Memory是192 KB，Ascend 950DT是384 KB。你写的tiling参数在910上跑得好好地，搬到950DT上反而慢了（因为没利用好更大的Local Memory）。

解决方案：catlass的模板自动感知硬件（从系统查询Local Memory大小），自动调整tiling参数，你不用手动改。

catlass的设计理念：模板化 + 可组合 + 硬件感知

catlass的核心设计理念有三个：模板化、可组合、硬件感知。

理念一：模板化（把通用逻辑抽象成模板）

catlass提供了三层模板：

L1：基础模板（MatrixMul、Conv2D、Softmax...） ↓ 参数化 L2：优化模板（TiledMatrixMul、DepthwiseConv2D...） ↓ 组合 L3：算子模板（MatMul算子、Conv2D算子、Transformer注意力算子...）

示例：用catlass写一个MatMul算子（只要20行）

#include<catlass/MatMul.h>// 1. 定义MatMul算子的参数usingDataType=fp16;// 数据类型：FP16usingTileConfig=catlass::TileConfig<128,64,128>;// tile_m=128, tile_k=64, tile_n=128usingPipelineConfig=catlass::PipelineConfig<2,2>;// Double Buffer深度=2，Pipeline深度=2// 2. 声明MatMul算子（用模板生成）usingMatMulOp=catlass::MatMul<DataType,TileConfig,PipelineConfig>;// 3. 实现Compute()（只要写计算逻辑，不用写tiling）classMyMatMul{public:voidCompute(LocalTensor<fp16>A,LocalTensor<fp16>B,LocalTensor<fp16>C){// 调模板生成的MatMul算子MatMulOp op;op.Compute(A,B,C);}};// 4. 注册算子REGISTER_OPERATOR(MatMul,"my_matmul_v1",MyMatMul);

对比手写版本（200行 vs 20行，效率提升10倍）：

// 手写MatMul算子（200行，还要调tiling参数）classMyMatMul{public:voidTiling(){// 200行tiling逻辑...}voidCompute(LocalTensor<fp16>A,LocalTensor<fp16>B,LocalTensor<fp16>C){// 调TilingTiling();// 双层循环...for(inti=0;i<M;i+=tile_m){// ...}}};

理念二：可组合（模板可以像乐高一样组合）

catlass的模板是可组合的——你可以把TiledMatrixMul模板跟Softmax模板组合，生成MatMulWithSoftmax算子（融合算子）。

示例：组合生成一个"MatMul + Softmax"融合算子

#include<catlass/MatMul.h>#include<catlass/Softmax.h>// 1. 定义融合算子的参数usingMatMulConfig=catlass::TileConfig<128,64,128>;usingSoftmaxConfig=catlass::SoftmaxConfig<128,128>;// 适配MatMul的输出// 2. 组合模板（生成融合算子）usingMatMulSoftmaxOp=catlass::Compose<catlass::MatMul<fp16,MatMulConfig>,catlass::Softmax<fp16,SoftmaxConfig>>;// 3. 实现Compute()（模板自动做算子融合，不写HBM）voidCompute(LocalTensor<fp16>A,LocalTensor<fp16>B,LocalTensor<fp16>C){// 调融合算子（MatMul + Softmax，中间结果不写HBM）MatMulSoftmaxOp op;op.Compute(A,B,C);}

性能收益（Llama-3的Attention层，seq_len=2048）：

理念三：硬件感知（自动适配不同NPU型号）

catlass的模板自动感知硬件（从系统查询Local Memory大小、计算单元数量、HBM带宽），自动调整tiling参数和优化策略。

实现机制：

1. 编译时检测：catlass的CMake脚本在编译时自动检测NPU型号（910 vs 950DT），选择对应的优化策略
2. 运行时查询：catlass的模板在运行时查询Local Memory大小，动态调整tiling参数

代码示例：

// catlass的硬件感知逻辑（简化版）namespacecatlass::internal{// 1. 编译时检测NPU型号#ifdefASCEND_910constexprintLOCAL_MEM_SIZE=192*1024;// 192 KBconstexprintCUBE_UNITS=32;// 32个Matrix单元#elifdefined(ASCEND_950DT)constexprintLOCAL_MEM_SIZE=384*1024;// 384 KBconstexprintCUBE_UNITS=64;// 64个Matrix单元#endif// 2. 运行时查询Local Memory大小intget_local_mem_size(){// 从系统查询（通过ACL接口）intsize=0;aclGetLocalMemSize(&size);returnsize;}// 3. 自动调整tiling参数template<typenameTileConfig>voidadjust_tiling_for_hardware(TileConfig&config){intlocal_mem=get_local_mem_size();if(local_mem<=192*1024){// Ascend 910：调小tile参数config.tile_m=128;config.tile_n=128;}elseif(local_mem<=384*1024){// Ascend 950DT：调大tile参数config.tile_m=256;config.tile_n=256;}else{// 未来更大Local Memory的NPU：继续调大config.tile_m=512;config.tile_n=256;}}}// namespace catlass::internal

性能收益（同一份代码，在910和950DT上都能跑到最优）：

catlass的核心模块

catlass有四大核心模块：TileIterator、MmaSync、CopyAsync、Pipeline。

模块一：TileIterator（分块迭代器）

TileIterator是catlass的核心模板，它实现了通用的分块逻辑（tiling），你只要填分块参数（tile_m/tile_k/tile_n），它自动生成分块循环。

使用示例：

#include<catlass/TileIterator.h>// 1. 定义分块参数usingTileConfig=catlass::TileConfig<128,64,128>;// 2. 创建TileIteratorcatlass::TileIterator<fp16,TileConfig>iterator(A,B,C);// A/B/C是输入/输出tensor// 3. 迭代（自动分块）iterator.ForEachTile([&](LocalTensor<fp16>a_tile,LocalTensor<fp16>b_tile,LocalTensor<fp16>c_tile){// 在这个lambda里写计算逻辑（a_tile/b_tile/c_tile是分块后的tensor）MatMul(a_tile,b_tile,c_tile);});

关键点：ForEachTile()自动帮你做分块循环，你不用手写双层循环了。

模块二：MmaSync（矩阵乘同步原语）

MmaSync是catlass对Matrix单元（Cube）的封装，它提供了高效的矩阵乘接口（比直接调MatMul()更快，因为它做了Pipeline）。

使用示例：

#include<catlass/MmaSync.h>// 1. 定义矩阵乘参数usingMmaConfig=catlass::MmaConfig<128,64,128>;// tile_m/tile_k/tile_n// 2. 创建MmaSync对象catlass::MmaSync<fp16,MmaConfig>mma;// 3. 调矩阵乘（同步，等算完再返回）mma.Sync(a_tile,b_tile,c_tile);// 或者异步（不等待，适合Pipeline）mma.Async(a_tile,b_tile,c_tile);

性能收益（MatMul算子，seq_len=2048）：

模块三：CopyAsync（异步数据搬运）

CopyAsync是catlass对DMA数据搬运的封装，它提供了异步的HBM↔片上内存搬运接口（比直接调Load()/Store()更快，因为它做了Pipeline）。

使用示例：

#include<catlass/CopyAsync.h>// 1. 创建CopyAsync对象catlass::CopyAsync<fp16>copy;// 2. 异步搬运（不等待，适合Pipeline）copy.LoadAsync(a_tile,A,i,tile_m,0,tile_k);// 从HBM读A_tilecopy.LoadAsync(b_tile,B,0,tile_k,j,tile_n);// 从HBM读B_tile// 3. 等搬运完成copy.WaitAll();// 4. 计算MatMul(a_tile,b_tile,c_tile);// 5. 异步写回copy.StoreAsync(C,c_tile,i,tile_m,j,tile_n);// 6. 等写回完成copy.WaitAll();

性能收益（MatMul算子，seq_len=2048）：

模块四：Pipeline（流水线调度）

Pipeline是catlass的高级优化模块，它把"数据搬运"和"计算"重叠起来（计算的同时搬运下一批数据），进一步提升性能。

使用示例：

#include<catlass/Pipeline.h>// 1. 定义Pipeline深度（Double Buffer深度=2，计算深度=2）usingPipelineConfig=catlass::PipelineConfig<2,2>;// 2. 创建Pipelinecatlass::Pipeline<PipelineConfig>pipeline;// 3. 启动Pipelinepipeline.Start([&](intstage){if(stage==0){// Stage 0：搬运数据copy.LoadAsync(a_tile,A,i,tile_m,0,tile_k);copy.LoadAsync(b_tile,B,0,tile_k,j,tile_n);}elseif(stage==1){// Stage 1：计算（跟Stage 0重叠）MatMul(a_tile,b_tile,c_tile);}});// 4. 等Pipeline完成pipeline.Wait();

性能收益（MatMul算子，seq_len=2048）：

实战：用catlass写一个MatMul算子（比手写Ascend C快30%）

步骤1：安装catlass

# 克隆仓库gitclone https://atomgit.com/cann/catlass.gitcdcatlass# 安装依赖pipinstall-rrequirements.txt# 编译（需要CANN环境）mkdirbuild&&cdbuild cmake..make-j8# 安装sudomakeinstall

⚠️ 踩坑预警：catlass依赖ops-math和ops-blas，如果你没装这两个仓库，编译会报错。先装依赖：

# 克隆并安装ops-mathgitclone https://atomgit.com/cann/ops-math.gitcdops-math&&mkdirbuild&&cdbuild&&cmake..&&make-j8&&sudomakeinstall# 克隆并安装ops-blasgitclone https://atomgit.com/cann/ops-blas.gitcdops-blas&&mkdirbuild&&cdbuild&&cmake..&&make-j8&&sudomakeinstall

步骤2：用catlass写MatMul算子

#include<catlass/MatMul.h>#include<catlass/TileIterator.h>#include<catlass/MmaSync.h>#include<catlass/CopyAsync.h>#include<catlass/Pipeline.h>// 1. 定义配置usingDataType=fp16;usingTileConfig=catlass::TileConfig<128,64,128>;usingMmaConfig=catlass::MmaConfig<128,64,128>;usingPipelineConfig=catlass::PipelineConfig<2,2>;// 2. 创建算子classMyMatMul{private:// catlass模板生成的算子catlass::MatMul<DataType,TileConfig>matmul_op;catlass::TileIterator<DataType,TileConfig>iterator;catlass::MmaSync<DataType,MmaConfig>mma;catlass::CopyAsync<DataType>copy;catlass::Pipeline<PipelineConfig>pipeline;public:// 构造函数MyMatMul(LocalTensor<fp16>A,LocalTensor<fp16>B,LocalTensor<fp16>C):iterator(A,B,C),matmul_op(A,B,C){}// 计算voidCompute(){// 用Pipeline调度（计算搬运重叠）pipeline.Start([&](intstage){if(stage==0){// Stage 0：搬运数据iterator.LoadTiles();}elseif(stage==1){// Stage 1：计算（跟Stage 0重叠）iterator.ForEachTile([&](LocalTensor<fp16>a_tile,LocalTensor<fp16>b_tile,LocalTensor<fp16>c_tile){mma.Sync(a_tile,b_tile,c_tile);});}});// 等Pipeline完成pipeline.Wait();}};// 3. 注册算子REGISTER_OPERATOR(MatMul,"my_matmul_v1",MyMatMul);

步骤3：编译并测试

# 编译算子mkdirbuild&&cdbuild cmake..make-j8# 测试性能./test_matmul_perf

输出（Ascend 910，MatMul算子，M=1024，N=1024，K=1024）：

[INFO] Hand-written MatMul: 287 GFLOPS [INFO] catlass-generated MatMul: 412 GFLOPS [INFO] Speedup: 1.44x

结论：catlass生成的MatMul算子，比手写版本快44%。

踩坑实录

我在用catlass写算子时，踩过这几个坑：

坑1：模板参数填错，编译报错"static assertion failed"

报错信息：

/usr/local/include/catlass/TileConfig.h:127: error: static assertion failed: "TileConfig::tile_m must be a multiple of 16"

原因：catlass要求分块参数（tile_m/tile_k/tile_n）必须是16的倍数（NPU的向量化宽度是16）。

解决方案：调整分块参数，确保是16的倍数：

// ❌ 错误写法（tile_m=100，不是16的倍数）usingTileConfig=catlass::TileConfig<100,64,128>;// ✅ 正确写法（tile_m=96或112，是16的倍数）usingTileConfig=catlass::TileConfig<96,64,128>;// 96 = 16 × 6

坑2：Pipeline深度设太大，Local Memory溢出

报错信息：

[ERROR] ACL runtime load operator failed: Out of memory (Local Memory)

原因：Pipeline深度（Double Buffer深度 + 计算深度）设太大，中间结果存不下Local Memory（192 KB）。

解决方案：减小Pipeline深度：

// ❌ 错误写法（Pipeline深度=4，占用太多Local Memory）usingPipelineConfig=catlass::PipelineConfig<4,4>;// ✅ 正确写法（Pipeline深度=2，占用较少Local Memory）usingPipelineConfig=catlass::PipelineConfig<2,2>;

坑3：catlass版本跟CANN版本不匹配

问题：catlass 2.0支持CANN 8.5，但你用的是CANN 8.0，编译报错"undefined reference to `catlass::hardware::GetLocalMemSize()'"。

解决方案：catlass和CANN版本要匹配：

• CANN 8.0 → catlass 1.0
• CANN 8.5 → catlass 2.0

性能数据：catlass vs 手写Ascend C

我在Ascend 910上测了5个常见算子的性能（每个算子跑1000次取平均），数据如下：

平均提升：+38.2%（catlass生成的算子比手写版本快38.2%）。

结尾

catlass这个仓库，在昇腾CANN生态里的定位是**“算子开发的模板库”**。它不帮你写算子的核心逻辑（矩阵乘、卷积、归一化等），但它帮你把"tiling + 数据搬运 + Pipeline调度"这些通用逻辑自动化、模板化了，让你专注于算子的核心逻辑，而不是底层优化。

我那个客户，原来手写Ascend C算子，开发一个MatMul算子要3天（写tiling + 调性能），用了catlass之后，开发一个MatMul算子只要3小时（填参数 + 编译 + 测试），开发效率提升了10倍。

如果你在搞算子开发，建议去 https://atomgit.com/cann/catlass 把这个仓库拉下来，先跑一把examples/matmul的示例。光看文档是学不会catlass的，必须自己填一遍参数，看它怎么自动生成高效的tiling代码，你才知道catlass的价值。

仓库：https://atomgit.com/cann/catlass