vLLM Ascend · 注意力模块 API 参考

attention 子包的包标记文件。attention 包收录 NPU 上全部注意力后端实现：通用 FlashAttention（attention_v1）、MLA、SFA 稀疏注意力、DSA（DeepSeek-V4）、FA3、KV offload，以及 context_parallel 下的 DCP/PCP 上下文并行变体。

注意力掩码构建器（70 行）。AttentionMaskBuilder 按最大序列长度生成并缓存下三角掩码（_generate_attn_mask），提供普通掩码（get_attn_mask）、splitfuse 掩码（get_splitfuse_attn_mask）与统一入口 get_attention_mask，供不走 fused 算子的注意力路径使用。

NPU 通用注意力后端（2223 行，attention 包核心）。AscendAttentionBackend 定义后端元信息（名称/KV cache 形状/支持 PCP）与 swap/copy blocks；AscendAttentionMetadataBuilder 把 vLLM 的 CommonAttentionMetadata 转成 AscendMetadata（含 decode/prefill 拆分、批重排、PCP 元数据、graph capture 支持）；AscendAttentionBackendImpl 实现前向：full graph FIA（fused infer attention）/PA（paged attention）路径、chunked prefill 分段、编码器注意力、KV cache 写入（do_kv_cache_update/reshape_and_cache 及 PCP 变体）；AscendC8AttentionBackendImpl 为 INT8 KV cache（C8/QuaRot）模型提供独立实现：分页 KV 反量化到稠密、激活量化、专用 decode/chunked prefill 前向。

DeepSeek-V4 DSA 注意力-KV 执行方案的中心化决策（182 行）。根据硬件（A5/Ascend950）与配置决定 KV cache dtype（resolve_dsv4_cache_dtype/get_dsv4_attn_kv_dtype）、是否启用 BF16 SparseFlashMla（is_a5_bf16_kv_enabled）；DsaAttnKvPlan 封装一套执行参数：稀疏注意力算子与元数据算子的选择、slot_mapping 是否需拆成（块号,块内偏移）二维格式、压缩 KV 的 scatter 写入路径（SparseFlashMla 走 npu_scatter_nd_update_，量化 epilogue 走 kv_compress_epilog 算子）。get_dsa_attn_kv_plan 返回 A5 BF16 或上游兼容 FP8 方案。

DSA（DeepSeek 稀疏注意力）后端族（1709 行）。定义 5 个后端变体：AscendDSABackend（基类）、C4/C128（不同压缩比缓存）、SWA（滑窗）、C4State/C128State（带 state 缓存）。AscendDSAMetadataBuilder 构建统一请求元数据（AscendDSAReqMetadata）：SAS 稀疏元数据、QLI 量化 lightning indexer 元数据、DSpark 滑窗可见 slot 索引、Hadamard 旋转初始化、draft 模式支持；AscendDSAImpl 实现前向：MLA prolog 单流/多流、压缩器 topk 选择、稀疏注意力计算、o_proj 输出（含 A5 FP8 量化路径、oproj TP 权重切换路径，用静态 buffer 保证 ACL graph 重放时 HCCL 通信地址稳定）。

FA3（FlashAttention v3 接口）后端的轻量封装（144 行）。AscendFABackend 提供后端元信息与 KV cache 形状；AscendFAImpl 把 vLLM 的 flash_attn_with_kvcache 调用适配到 NPU 实现（_flash_attn_with_kvcache）并在 forward_impl 中按元数据分发，适用于直接使用 FA 接口的模型。

SFA indexer 缓存独立分层的占位后端（93 行）。当 SFA 的 indexer K/scale 缓存作为独立 KV cache group 分层管理时使用：AscendSFAIndexerBackend 提供后端元信息（实际计算由主 SFA 后端完成），AscendSFAIndexerMetadataBuilder 只构建缓存写入所需的元数据（build 填充 slot 映射），不做注意力计算。

MLA（Multi-head Latent Attention）后端（2087 行，DeepSeek 系列模型主力路径）。元数据体系：ChunkedContextMetadata（chunked prefill 上下文）、AscendMLAPrefillMetadata/AscendMLADecodeMetadata/AscendMLAMetadata、PCP 专用元数据；AscendMLAMetadataBuilder 处理 chunked prefill workspace 估算、MTP 场景 q 长度填充、prefill/decode 元数据分别构建；AscendMLAImpl 实现前向：fused 融合预处理（_process_weights_for_fused 把 fused_qkv_a_proj/q_proj 权重转成 prolog 消耗的 FRACTAL_NZ 格式并处理量化 scale）、mla_preprocess_decode/prefill（q/kv 投影 + RoPE + KV 写入）、FA3 与 PA 两条前向路径、chunked prefill 上下文重组织（_reorg_kvcache/_compute_prefill_context）；AscendMLAPCPImpl 支持 prefill 上下文并行（保留完整 PCP cache 写槽位）。

Sparse KV offload 专用 SFA 后端（470 行）。把主 MLA 的 K/V 经 CPU 内存池中转以支持超大上下文：AscendSFAKVOffloadMetadataBuilder 填充 offload 专属元数据（decode 拆分 + 请求 ID）；AscendSFAKVOffloadImpl 在 decode-only 且不在 graph 捕获/重放状态时把 K/V 路由到 CPU 池（_cpu_cache_pair/_resident_views 管理 topk buffer 的常驻视图），强制使用 native 预处理路径（sfa_prolog_v3/mlapo 被禁用），sparse flash attention 主计算在 _execute_sparse_flash_attention_process 中执行。

SFA（Sparse Flash Attention）后端（1742 行）。面向 DeepSeek-V3.2 等稀疏注意力模型：AscendSFAMetadataBuilder 构建稀疏注意力元数据（支持 DSA-CP token 分片、DCP KV 视图的并行元数据准备）；AscendSFAImpl 按量化方法选择融合预处理路径——PROLOG_V3（W8A8 dynamic/MXFP8，走 npu_mla_prolog_v3 系算子）或 MLAPO（W8A8，权重转 FRACTAL_NZ + trans_rope_weight 重排），否则回退 native；indexer 选择前后处理（indexer_select_pre/post_process）完成 lightning indexer 的 K 缓存写入与 topk 选择；_execute_sparse_flash_attention_process 执行稀疏主计算；_v_up_proj 用 batch_matmul_transpose/npu_transpose_batchmatmul 完成 V 上投影；custom_kv_rmsnorm_rope 为融合 RMSNorm+RoPE+FP8 量化的自定义算子入口。

SparseFlashMla BF16 KV 适配层（62 行）。惰性加载 SparseFlashMla 算子（不引入对 vllm_ascend.ops 的依赖），把现有 DSA 元数据 kwargs（sparse_flash_mla_metadata）和注意力 kwargs（sparse_flash_mla）适配为 SparseFlashMla BF16 KV 所需格式（附加压缩 KV 长度参数），供 A5 平台 BF16 DSA 路径调用。

注意力模块共享工具集（565 行）。包含：共享 buffer 注册（get_or_register_attention_buffer）、SFA topk 掩码构建、graph workspace 缓存与 PA/FIA 共图重放参数（PagedAttentionGraphParam/update_paged_attention_graph_param）、chunked prefill workspace 尺寸估算；AscendCommonAttentionMetadata 定义跨层共享的批次级注意力元数据，split_decodes_and_prefills 按阈值拆分 decode/prefill 段；KV connector 协作钩子（wait_for_kv_layer_from_connector/maybe_save_kv_layer_to_connector/notify_kv_cache_written）；权重变换工具 trans_rope_weight（RoPE 维度重排）与 transdata（FRACTAL_NZ 分块重排）；DCP/PCP 开关（enable_dcp/enable_pcp）与 AscendDCPMetadata。

attention.context_parallel 子包标记。该子包实现 NPU 注意力的上下文并行：DCP（decode context parallel，序列分片 decode）与 PCP（prefill context parallel，prefill 上下文并行），覆盖 GQA/MLA/SFA/DSA 四类后端。

GQA 注意力的 DCP 实现（610 行）。AscendAttentionDCPMetadataBuilder 拆分 decode/prefill 并构建 DCP 专属元数据（AscendAttentionDCPMetadata）；AscendAttentionDCPImpl 的 decode 路径（_forward_decode_dcp）在 rank 本地 KV 分片上计算；prefill chunked 路径：all-gather query（_prefill_query_all_gather）、按 chunk 用 DeviceOperator.kv_cache_load 从分页缓存加载 K/V（_load_kv_for_chunk）、本地注意力输出经 all_to_all 汇聚（_gather_global_context_output）、各 rank 输出与 LSE 在 _update_global_context_output 中用 log-sum-exp 合并，_update_chunk_attn_out_lse_with_current_attn_out_lse 处理 chunk 间增量合并。

DCP 共享基础设施（233 行）。get_dcp_local_seq_lens 按 interleave 布局计算每个 DCP rank 持有的 KV 长度；DCPMetadataBuilderMixin 提供元数据构建器对 DCP 元数据的访问与本地/rank 上下文长度提取；DCPImplMixin 封装组生命周期与集合通信（_dcp_all_gather、_dcp_all_gather_fragments 多张量异步 all-gather、_merge_dcp_attention_output）；_process_attn_out_lse/_npu_attention_update/_npu_attn_out_lse_update 处理带掩码/无掩码两路输出与 LSE 的合并（npu_attention_update 算子），_update_out_and_lse 实现 LSE=log(sum(exp(LSE_i))) 的数值稳定合并。

DSA 上下文并行实现（2291 行，子包最大文件）。覆盖两种并行：DSA-CP（TP 组内 token 分片）与 DCP/PCP（序列分片）。AscendDSACPMetadataBuilder 在共享 SFA builder 上叠加 token 分片元数据（compressor 行数计算、SAS/QLI 元数据、比较 seqlens）；AscendDSACPImpl 实现核心逻辑：o_proj 的 TP 全量权重切换（_enable_o_proj_tp_full_weight_switch/_switch_o_proj_to_full_weight，配合 TPWeightSwitchMixin 在计算期临时切全量权重）、隐藏层恢复布局（_restore_tp_head_layout）、indexer 缓存更新与 topk 选择（_update_indexer_cache/_indexer_select_topk）、Hadamard 激活旋转（rotate_activation）；PCP 侧：AscendDSAPCPMetadataBuilder 构建本地元数据 + 全局规范缓存元数据，AscendDSAPCPImpl 先做批量全局 DSA 缓存更新（SWA/compressor/indexer 三类缓存）再做 rank 本地注意力。from_local_metadata 把本地元数据映射为带规范 cache 写视图的全局元数据。

MLA 的 DCP 实现（529 行）。DCPChunkedContextMetadata 维护 DCP 本地上下文分片的 chunk 元数据（含 padding 后的 NPU seq lens）；AscendMlaDCPMetadataBuilder 构建 chunked/decode 元数据；AscendMlaDCPImpl 的 decode 前向先 all-gather q（reorg_decode_q 聚合 nope/pe 两段），再在本地 KV 分片上执行 _forward_decode，get_context_seq_len_npu 返回 padding 后的 chunk 长度，_reorg_kvcache 处理 KV 重组织。

SFA 的上下文并行全家桶（1315 行）。三条路径按两个独立开关组合：DSA-CP（TP token 分片）× DCP（序列分片）。AscendSFADSACPMetadataBuilder/AscendSFADSACPImpl：token 分片下 KV 异步 all-gather（_prepare_kv_for_parallel/_store_parallel_kv，含 indexer K/scale）、o_proj 全量权重切换（复用 TPWeightSwitchMixin + 权重池）、query 聚合；AscendSFADCPMetadataBuilder/AscendSFADCPImpl：序列分片下构建复制视图（block table/slot mapping 的 replicated view）、稀疏索引从全局视图重映射到本地视图（_remap_sparse_indices，Triton kernel 或 fp32 回退实现，无效索引置无效值后按 topk 序紧凑排列）、输出与 LSE 合并；AscendSFADSADCPMetadataBuilder/Impl 把两者复合；resolve_sfa_metadata_builder/resolve_sfa_impl 按开关解析出唯一实现。AscendSFAPCPImpl 处理 PCP 的 KV slot 映射与 indexer 缓存写入。