torch_extension接口
使用说明
为简化算子调用,项目提供了一套兼容PyTorch原生风格的API。该API通过PyTorch的JIT机制(torch.utils.cpp_extension.load),在首次调用时即时编译C++ Kernel Wrapper,将PyTorch函数桥接到CANN的aclnn API,同时通过GE Converter支持TorchAir图模式,便于开发者构建模型与应用。
-
软件包说明
调用torch_extension接口时,请确保已安装CANN Toolkit包、ops-transformer包、Ascend for PyTorch包。
-
调用方式:
调用torch_extension接口时,依赖
cann-ops-transformer模块,定义在${INSTALL_DIR}/python/sitepackages/cann-ops-transformer,${INSTALL_DIR}表示CANN安装后文件路径。import torch import torch_npu import cann_ops_transformer -
V版本演进说明
请注意,部分API存在多个V版本,使用时选择最高V版本即可(高版本API已兼容低版本API的所有能力)。
接口列表
Note
- 算子特性介绍:调用API前,请先学习算子相关基础知识,包括确定性算法、Batch一致性、常见量化模式等,具体介绍参见算子基本概念。
- 符号说明:表格中“-”符号表示该接口暂不支持当前列产品。
| 接口名 | 说明 | 确定性说明(A2/A3) | 确定性说明(Ascend 950) |
|---|---|---|---|
| block_attn_res_prepare | 完成 Attention Residuals 历史残差注意力两阶段计算的第一阶段,返回 softmax 加权分子及统计量。 | - | 默认支持确定性计算 |
| block_attn_res_update | 将delta原地累加到partial_block,计算更新后partial_block的RMSNorm score,并与历史online softmax中间状态合并,返回当前层结果h。 |
- | 默认确定性实现 |
| block_attention_residuals | 将 partial_block 与 block_res 拼接后完成 RMS、投影打分与 Softmax 加权融合,输出 hidden_states。 |
默认支持确定性计算 | 默认支持确定性计算 |
| block_sparse_attention | 调用BlockSparseAttention完成块级稀疏注意力计算。 |
- | - |
| block_sparse_attention_grad | 调用BlockSparseAttentionGrad完成块级稀疏注意力计算。 |
- | - |
| apply_rotary_pos_emb | 融合query和key两路旋转位置编码计算,返回旋转位置编码后的query和key输出张量。 | 默认支持确定性计算 | 默认支持确定性计算 |
| apply_rotary_pos_emb_grad | 执行双路旋转位置编码的反向计算,将query和key两路梯度计算融合为一次kernel调用。 | - | 默认支持确定性计算 |
| attention_to_ffn | 将Attention节点上数据发往FFN节点。 | - | 默认支持确定性计算 |
| attention_worker_combine | 融合FFN侧返回的专家token,Ascend 950支持MXFP反量化。 | 默认支持确定性计算 | 默认支持确定性计算 |
| all_gather_quant_matmul | 完成AllGather通信与MX量化矩阵乘法的融合计算。 | - | 默认支持确定性计算 |
| all_to_all_quant_matmul | 完成All-to-All通信与MX量化矩阵乘法的融合计算。 | - | 默认支持确定性计算 |
| causal_conv1d_fn | 因果一维卷积前向计算(prefill/chunk-prefill),封装aclnnCausalConv1dFn。 | - | 默认支持确定性计算 |
| causal_conv1d_update | 因果一维卷积状态更新(decode/update),封装aclnnCausalConv1dUpdate。 | - | 默认支持确定性计算 |
| compressor | 将每4或128个token的KV cache压缩成一个,然后每个token与这些压缩的KV cache进行DSA计算。 | 默认支持确定性计算 | 默认支持确定性计算 |
| ElasticBuffer | 统一的分布式Engram存储与MoE dispatch/combine通信buffer管理;配套get_engram_storage_size_hint、engram_fetch/engram_fetch_grad等接口。 | - | - |
| dense_lightning_indexer_softmax_lse | dense场景DenseLightningIndexerGradKlLoss算子计算Softmax输入的一个分支算子。支持压缩注意力(Compressed Attention),并支持通过metadata前置算子进行分核负载均衡。需与dense_lightning_indexer_softmax_lse_metadata配套使用。 |
- | 默认确定性实现 |
| dense_lightning_indexer_softmax_lse_metadata | dense_lightning_indexer_softmax_lse接口的前置接口,用于计算dense_lightning_indexer_softmax_lse的负载均衡。 | - | 默认确定性实现 |
| ffn_worker_batching | 按专家聚合并重排 Attention 发送的 token,支持 NORM 和同步/异步 RECV。 | - | 固定输入及就绪快照下确定性计算;异步快照由生产者时序决定。 |
| flash_attn | 调用FlashAttn算子完成共享KV(Key和Value使用同一份输入)的非量化注意力计算,训练推理归一化。需与flash_attn_metadata配套使用。 |
- | 默认支持确定性计算 |
| flash_attn_grad | 调用FlashAttnGrad算子计算Flash Attention的反向梯度,根据前向softmax_lse、attn_out和上游梯度dout计算dq、dk、dv。需与flash_attn_metadata(is_grad_enabled=True)配套使用。 |
- | 默认支持确定性计算 |
| ffn_to_attention | 一个通信域内的FFN节点对Attention节点发送数据并写状态位,以检测通信链路是否正常。 | - | 默认支持确定性计算 |
| fused_causal_conv1d | 对序列执行因果一维卷积,沿序列维度使用缓存数据(长度为卷积核宽减1)对各序列头部进行padding,确保输出依赖当前及历史输入;卷积完成后,将当前序列部分数据更新到缓存;在因果一维卷积输出的基础上,将原始输入加到输出上以实现残差连接。支持APC(Automatic Prefix Caching)、MTP(投机解码)、残差连接等特性。 | - | 默认确定性实现 |
| fused_causal_conv1d_ | 对序列执行因果一维卷积,沿序列维度使用缓存数据(长度为卷积核宽减1)对各序列头部进行padding,确保输出依赖当前及历史输入;卷积完成后,将当前序列部分数据更新到缓存;在因果一维卷积输出的基础上,将原始输入加到输出上以实现残差连接。支持APC(Automatic Prefix Caching)、MTP(投机解码)、残差连接等特性,且支持原地更新。 | - | 默认确定性实现 |
| get_low_latency_ccl_buffer_size | 计算low_latency_dispatch/low_latency_combine所需的HCCL通信buffer_size(单位MB),为MoeDistributeBuffer的静态方法,可在初始化前调用。 | 默认支持确定性计算 | 默认支持确定性计算 |
| generic_block_sparse_attention | 调用GenericBlockSparseAttention完成任意粒度块稀疏注意力计算。 |
- | - |
| generic_block_sparse_attention_grad | 调用GenericBlockSparseAttentionGrad完成通用块稀疏注意力反向计算。 |
- | - |
| grouped_matmul_activation | 融合A4W4 WeightNZ分组矩阵乘与前后分半SwiGLU,直接输出BF16结果。 | - | 默认支持确定性计算 |
| grouped_matmul_activation_quant | 融合GMM、激活函数和量化算子,完成分组矩阵乘、激活和量化计算,输出量化结果及量化因子。 | - | 默认确定性实现 |
| grouped_matmul_swiglu_quant | 融合GMM、SwiGLU和MX量化,当前支持MXFP8 weightNZ的swiglu_mode=2场景。 |
- | 默认确定性实现 |
| indexer_quant_cache | 在Indexer注意力机制的Epilog阶段对KV Cache进行原地动态量化压缩更新,封装aclnnIndexerQuantCache。 | - | 默认确定性实现 |
| inplace_partial_rotary_mul | 执行单路旋转位置编码的Inplace计算,直接修改输入张量,不产生新的输出张量。 | 默认确定性实现 | 默认确定性实现 |
| inplace_partial_rotary_mul_backward | 执行inplace_partial_rotary_mul的反向计算,对输入梯度张量执行inplace更新,切片内替换为RoPE梯度,切片外保持不变。 |
- | 默认支持确定性计算 |
| key_pool | 推理场景下的Key压缩算子:对输入token做K/Gate投影,按cmp_ratio分组加权池化为Key,未完成组状态经state_cache跨调用保存。 | - | - |
| kv_compress_epilog | 在KV Cache的Epilog阶段对cache进行原地量化压缩更新,封装aclnnKvCompressEpilog。 | 默认确定性实现 | - |
| kv_quant_sparse_flash_attention | 调用KvQuantSparseFlashAttentionV2完成量化和稀疏场景下的注意力计算,支持Per-Token-Head-Tile-128量化输入。 |
- | 默认支持确定性计算 |
| lightning_indexer | 基于一系列操作得到每一个token对应的Top-k个位置。支持KV压缩场景。已融合candidate(两级 TopK)候选源模式:传入可选参数candidate_topk_blocks时额外返回候选块号两输出(供sparse_lightning_indexer消费),未传入时保持2输出不变。 |
默认确定性实现 | - |
| lightning_indexer_metadata | lightning_indexer接口的前置接口,用于计算lightning_indexer的负载均衡。 | 默认确定性实现 | 默认确定性实现 |
| lightning_indexer_kl_loss | 计算Lightning Indexer中teacher分布与student分布之间的KL散度损失。 | 默认非确定性,支持通过torch.use_deterministic_algorithms开启确定性计算。 |
- |
| low_latency_dispatch | 完成MoE并行部署下token的低时延dispatch分发,支持动态量化与EP域alltoallv通信,需与low_latency_combine配套使用。 | 默认支持确定性计算 | 默认支持确定性计算 |
| low_latency_combine | 与low_latency_dispatch配套,按dispatch原路返回完成token的低时延combine反向聚合;topk_weights非空时乘路由权重再相加,为None时直接相加。 | 默认支持确定性计算 | 默认支持确定性计算 |
| mega_moe | MoE端到端通算融合算子,将Dispatch+GroupMatmul1+SwiGLUQuant+GroupMatmul2+Combine融合为单算子;配套get_mega_moe_ccl_buffer_size、get_symm_buffer_for_mega_moe使用。 | - | 默认支持确定性计算 |
| mega_mhc | 融合 RMS0、Post、可选 Mid、Pre 和 RMS1,保留阶段舍入。 | - | 默认支持确定性计算 |
| mhc_post | 实现MHC Post组件的前向计算,用于Transformer模型中多层残差连接的后处理阶段。该算子将残差矩阵变换与输出状态投影融合为单次计算,避免多次独立算子调用带来的额外开销。 | 默认确定性实现 | - |
| mhc_pre_sinkhorn | 基于一系列计算得到MHC架构中hidden层的Hres′\mathbf{H}'_{\text{res}}和Hpost\mathbf{H}_{\text{post}}投影矩阵以及Attention或MLP层的输入矩阵hin\mathbf{h}_{\text{in}}。对Hres′\mathbf{H}'_{\text{res}}矩阵执行Sinkhorn迭代归一化变换,最终得到双随机矩阵Hres\mathbf{H}_{\text{res}};支持输出中间计算结果,用于反向梯度计算。其中,该接口在Cube中的计算模式为HF32。 | 默认确定性实现 | 默认确定性实现 |
| mixed_quant_sparse_flash_mla | 量化场景下基于共享KV完成MixedQuantSparseFlashMla稀疏注意力计算。需与mixed_quant_sparse_flash_mla_metadata配套使用。 |
默认确定性实现 | 默认确定性实现 |
| mla_prolog | 调用MlaPrologV4WeightNz完成MLA Decoder前向中Query/KV相关预处理。 |
默认支持确定性计算 | 默认支持确定性计算 |
| moe_finalize_routing | 将各专家FFN的输出结果按路由权重加权合并,还原为原始token序列。 | 默认支持确定性计算。 | 默认支持确定性计算。 |
| moe_finalize_routing_grad | moe_finalize_routing的反向接口,封装aclnnMoeFinalizeRoutingV2Grad。 |
默认支持确定性计算 | 默认支持确定性计算 |
| moe_init_routing | MoE的routing计算,根据moe_gating_top_k_softmax的计算结果做routing处理,支持不量化、静态量化和动态量化模式。 | 默认确定性实现 | 默认确定性实现 |
| moe_init_routing_grad | moe_init_routing的反向接口,封装aclnnMoeInitRoutingV2Grad。 |
默认支持确定性计算 | 默认支持确定性计算 |
| moe_re_routing | MoE网络中,进行AlltoAll操作从其他卡上拿到需要算的token后,将token按照专家顺序重新排列。支持对topkWeight重排。 | 默认确定性实现 | 默认确定性实现 |
| moe_token_permute | 根据专家索引扩展并排序token。 | - | 默认支持确定性计算。 |
| msa_index_score | 计算 MSA Index Branch 的 block score,对每个 query token 与 KV sparse block 做 matmul+maxpool 得到重要性分数。 | 默认确定性实现 | 默认确定性实现 |
| msa_index_score_v2 | 兼容 msa_index_score,支持指定 layout_query 与 pool_block_size。 | 默认确定性实现 | 默认确定性实现 |
| pool_key_indexer | 将多个连续token打包成一个pool(池),以pool为单位计算注意力相关性分数并选取top-k位置,从而在保持稀疏注意力优势的同时减少索引开销。 | 默认确定性实现 | 默认确定性实现 |
| qkv_rms_norm_rope_cache_with_k_scale | 融合Q/K/V拆分、Q/K RMSNorm、RoPE/M-RoPE、量化和KV Cache更新,支持原地与函数式接口及M-RoPE MX场景。 | - | 默认支持确定性计算。 |
| quant_all_reduce | 实现低比特数据的AllReduce通信,在通信的过程中对数据进行反量化,并输出通信结果。 | - | - |
| quant_compressor | Compressor的量化版本,将每4或128个token的KV cache压缩成一个,然后每个token与这些压缩的KV cache进行DSA计算。 | - | 默认支持确定性计算 |
| quant_flash_attn | 调用QuantFlashAttn算子完成MxFP8/HiF8/MxFP4量化场景下的全量化注意力计算,训练推理归一化。 |
- | 默认支持确定性计算。 |
| quant_flash_attn_grad | 调用QuantFlashAttnGrad算子完成HiF8量化场景下的全量化注意力计算,训练推理归一化。 |
- | 默认支持确定性计算。 |
| quant_lightning_indexer | 基于一系列操作得到每一个token对应的top-k个位置。 | - | 默认支持确定性计算。 |
| quant_reduce_scatter | 实现quant + reduceScatter融合计算。 | - | - |
| quant_sparse_flash_mla | 调用QuantSparseFlashMla算子完成共享KV(Key和Value使用同一份输入)的稀疏注意力计算。 |
- | 默认支持确定性计算。 |
| recurrent_kda | 完成KDA(Kimi Delta Attention)的递归前向计算,面向decode和MTP短序列场景。 | 默认确定性实现 | 默认确定性实现 |
| scatter_pa_kv_cache_with_k_scale | 训练场景下,更新KvCache中指定位置的key和value,同时更新key的scale值。 | - | 默认支持确定性计算 |
| sparse_flash_mla | 基于共享KV完成SparseFlashMla稀疏注意力计算。需与sparse_flash_mla_metadata配套使用。 |
默认确定性实现 | 默认确定性实现 |
| sparse_flash_mla_grad | 计算SparseFlashMla训练场景下注意力的反向输出,支持Sliding Window Attention、Compressed Attention以及Sparse Compressed Attention。需与sparse_flash_mla_grad_metadata配套使用。 |
- | 默认确定性实现 |
| sparse_lightning_indexer | lightning_indexer候选模式(candidate consumer)的torch接口,消费source输出的候选块索引,对候选外可达位置做leak降级TopK。需与lightning_indexer配对使用。 |
默认确定性实现 | - |
| sparse_lightning_indexer_kl_loss_grad | Lightning Indexer KL Loss训练场景下的反向输出。需与sparse_lightning_indexer_kl_loss_grad_metadata配套使用。 |
默认确定性实现 | 默认确定性实现 |
| stem_oam_prep_varlen_q | 完成Stem OAM block-sparse attention中Q侧预处理计算,将变长Q tensor转化为按stem block分组的flattened qFlat输出。 | - | 默认确定性实现 |
| dense_lightning_indexer_kl_loss_grad | Lightning Indexer KL Loss训练Dense场景下的反向输出。需与dense_lightning_indexer_kl_loss_grad_metadata配套使用。 |
- | 默认确定性实现 |
| sparse_flash_mla_softmax_l1_norm | dense_lightning_indexer_kl_loss_grad的前置接口,生成attn_softmax_l1_norm。需与sparse_flash_mla_softmax_l1_norm_metadata配套使用。 |
- | 默认确定性实现 |
| stem_oam_prep_paged_kv | 大模型推理动态稀疏注意力机制的前置评分模块,为block-sparse-attention提供前置评分。 | - | 默认确定性实现 |
| und_gen_qkv_rms_norm_rope_cache | 融合und/gen两段QKV的间接寻址拼接、Q/K RMSNorm、MRoPE和分页KV Cache更新,返回Q,k_cache/v_cache原地更新。 | - | 默认确定性实现 |