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原地更新。 - 默认确定性实现