vLLM Ascend · 模型定义模块 API 参考

models 包注册入口（56 行）。register_model 把 Ascend 定制的模型架构（DeepSeek-V4、Kimi K3、MiniMax-M3 系列、各 draft 模型等）注册进 vLLM 的模型注册表，使平台加载模型时命中 NPU 实现而非上游版本。

DeepSeek MTP（Multi-Token Prediction）投机层适配（81 行）。AscendDeepSeekMTP 实现 MTP 模块：forward 前向、load_weights 加载（_rewrite_spec_layer_name 重写投机层权重名以对齐 checkpoint）、_maybe_set_own_lm_head 在需要时为 draft 设置独立输出头；AscendGlmMoeDsaForCausalLM 为 GLM-MoE-DSA 的权重加载适配。

Kimi K3 模型适配（871 行）。AscendKimiMoE 用 vLLM 标准 MoE 接口组装 Kimi K3 的专家层；AscendKimiMLAAttention 仅扩展 DSpark RoPE 元数据部分（其余沿用上游通用 Kimi MLA）；AscendKimiDecoderLayer 沿上游解码层结构接 Ascend 注意力后端（_run_self_attn/forward_attn_residual）；AscendKimiLinearModel 组装文本主体并处理权重加载；AscendKimiLinearForCausalLM/AscendKimiK3ForConditionalGeneration 分别为文本因果 LM 与多模态包装（保留 vLLM 0.27 状态/缓存接口、支持 DSpark 辅助捕获物化）；AscendKimiK3MultiModalProjector 多模态投影器（可选 ModelSlim 输出旋转）；_apply_ascend_attn_res 用原生算子实现 Kimi 规范的残差混合。

Kimi K3 DSpark draft 模型（364 行）。AscendK3DSparkModel 提供 precompute_and_store_context_kv 预计算并缓存上下文 KV 供 draft 多步复用，forward 执行 draft 前向；AscendK3DSparkDecoderLayer 为 draft 解码层；AscendK3DSparkForCausalLM 组织整体（get_draft_attn_causal 决定 draft 注意力因果性、load_weights、embed_input_ids）。

Kimi K3 MTP draft 模型（93 行）。AscendKimiK3MultiTokenPredictorLayer 为单层 MTP 预测层，AscendKimiK3MultiTokenPredictor 组装 MTP 模块，AscendKimiK3MTP 为对 vLLM 注册暴露的完整 draft 模型包装。

Llama Eagle3 draft 模型（140 行）。AscendEagle3LlamaForCausalLM 加载 Eagle3 draft 权重并执行 draft 前向；针对 QuaRot 旋转的 draft 训练方式：get_embedding_tensor 扫描目录找 embedding 张量、_find_safetensors_weight 定位目标张量避免加载无关分片、load_quarot_target_layer 把目标层词表分片装入 draft 的未旋转隐藏基、compute_rotation_matrix3 计算三层 hidden_states 的反旋转矩阵。

Llama Eagle3 的 VWN（vocab-未旋转网络）变体（257 行）。PreVwnLayerV1 为前置 VWN 层、VwnLlamaDecoderLayer/VwnLlamaModel 组成 VWN 主体（替代标准解码层栈）；Eagle3VwnLlamaForCausalLM 提供 compute_logits 与 combine_hidden_states（合并多源 hidden states 供 draft 使用），是 Eagle3 在 VWN 投影结构下的 Ascend 实现。

Qwen3 DFlash2 draft 模型（309 行）。DFlashGroupedConv 用分组卷积从 anchor hidden states 一次性卷出多步 draft 的 delta/base（prepare/finish 管理卷积前后状态）；DFlash2Qwen3DecoderLayer 为 draft 解码层；CandidateSelector 基于 _score_edges 对候选边打分（前驱/后继表 + unary logits + anchor token）选 top-k 候选路径；DFlash2Qwen3Model/DFlash2Qwen3ForCausalLM 组装模型并提供 compute_candidates 候选计算接口。

Qwen3 DSpark draft 模型（173 行）。DSparkConfidenceHead 为置信度头（对 draft 候选打置信分）；AscendQwen3DSparkForCausalLM 组织 draft 模型：compute_confidence 输出置信度、load_weights 处理 process_weight 的旋转权重合并（linear_weight+rotation_weight）。

models.deepseek_v4 子包标记。该包实现 DeepSeek-V4 在 Ascend 上的完整适配：主模型、lightning indexer、KV 压缩器、SWA 缓存、DSpark draft 与 MTP。

DeepSeek-V4 KV 压缩器（238 行）。Compressor 把长上下文 KV 压缩为低秩表示（_compute_metadata 构建压缩元数据、forward 执行压缩）；AscendCompressorMetadata 携带压缩 KV 与压缩器状态缓存的请求级元数据；AscendCompressorStateCache 管理压缩器状态的分页缓存：get_kv_cache_spec 定义缓存规格、get_attn_backend 选择配套后端。

DeepSeek-V4 DSpark draft 模型（547 行）。DSparkMarkovHead 实现 Markov 式候选头（embed/bias）；DSparkConfidenceHead 置信度头；DeepseekV4DSparkModel 组装 draft 主体：_project_shared_kv 投影共享 KV、_store_standard_swa_kv 存标准 SWA KV、precompute_and_store_context_kv 预计算上下文 KV、hc_head/Markov embed/bias 接口与 compute_logits；DSparkDeepseekV4ForCausalLM 为注册包装：set_moe_parameters、map_draft_to_target（draft→目标 token 映射）、compute_draft_logits、_remap_dspark_name 权重名重映射。

DeepSeek-V4 lightning indexer（718 行）。Hadamard 工具：hadamard_linear 快速 Hadamard 变换线性层、hadamard_scale/rotate_activation 激活旋转；AscendDeepseekV4IndexerCache 管理 indexer K/scale 分页缓存（get_kv_cache_spec/get_attn_backend）；IndexerOverlapPlan 把主注意力压缩器的工作安排在 indexer 选择周围重叠执行；AscendIndexerOps 封装设备算子序列：解包 indexer KV 缓存、量化 query/key、更新 scale 缓存、select_topk 及量化-更新-选择融合路径；DeepseekV4Indexer 为 indexer 层本体：多流路径（_cv_compute_query_and_update_cache_multistream/_select_topk_multistream）与串行路径（_select_topk_serial）、topk 索引缓存复用、forward 主入口。

DeepSeek-V4 主模型（1280 行）。AscendDeepseekV4SWACache 管理 SWA（滑窗注意力）层缓存（spec/forward/后端选择）；RoPE：precompute_freqs_cis_cpu 预计算复指数频率表、apply_rotary_emb 应用/逆变换；DeepseekV4Attention 注意力层、DeepseekV4MoE 专家层（DeepseekV2MLP 为共享专家 MLP）、DeepseekV2DecoderLayer（hc_pre/hc_post 挂钩）、DeepseekV4Model 主体（hc_head 接口）；yarn_get_mscale/_get_llama_4_scaling 支持 YaRN 与 Llama4 位置缩放；AscendDeepseekV4ForCausalLM 为完整包装（MTP 目标 hidden states、辅助隐藏层设置、专家映射、权重加载）。

DeepSeek-V4 MTP 投机模块（530 行）。DeepSeekMultiTokenPredictorLayer 单层 MTP（forward/hc_head）；DeepSeekMultiTokenPredictor 组装嵌入与前向；DeepSeekV4MTP 为注册包装：set_moe_parameters、embed_input_ids、compute_logits、load_weights（_rewrite_spec_layer_name 重写投机层名、no_mtp_block_in_name 判断）、SharedHead 共享输出头。

models.layer 子包标记。

models.layer.attention 子包标记。

DSA 注意力层定义（214 行）。DSAAttention 是 DeepSeek-V4 稀疏注意力的层封装（forward/process_weights_after_loading/get_attn_backend/get_kv_cache_spec）；dsv4_block_sizes 决定内核块大小表：显式请求 A5 BF16 KV 时用 A5 专用表，否则用上游表（get_dsv4_block_sizes 提供两套取值）。

models.minimax_m3 子包标记（21 行，含包初始化逻辑）。

MiniMax-M3 主模型（1368 行）。MiniMaxM3SparseAttention 实现块稀疏注意力 + lightning indexer（get_attn_backend/get_kv_cache_spec/_insert_kv 写入、_sparse_prepare/_run_sparse_attention 稀疏执行、_qk_norm/_index_qk_norm 归一化）；MiniMaxM3SwiGLUOAI 为 OAI 风格 SwiGLU 激活（gate/up 打包输入）；MLP/MoE（ebias_weight_loader 专家偏置加载）/Attention/DecoderLayer/Model 标准层级；MiniMaxM3SparseForCausalLM 完整包装（Eagle3 辅助隐藏层、专家映射、MTP 层名识别 get_spec_layer_idx_from_weight_name）；_scatter_index_cache 把 index key 写入分页缓存。

MiniMax-M3 多模态包装（453 行）。MiniMaxM3SparseForConditionalGeneration 处理图像/视频输入（_parse_and_validate_image/video_input、_process_image/video_input、embed_multimodal），同步 MoE 参数并暴露 lm_head；MiniMaxM3VLModel 为视觉语言主体；_install_fused_allreduce_norm_fallback 回退 vLLM 的 CUDA-only allreduce+norm 融合模块避免在 Ascend 上导入失败。

MiniMax-M3 稀疏注意力后端族（1316 行）。Indexer 侧：AscendMiniMaxM3IndexerBackend（后端元信息）、IndexerCache（K 缓存规格）、Prefill/Decode/Metadata 元数据、MetadataBuilder（含 TP 分片打分元数据 _build_tp_score_metadata）、IndexerImpl（decode topk TP 分片 _decode_topk_tp_sharded）、Indexer 层；Sparse 侧：AscendMiniMaxM3SparseBackend/Metadata/MetadataBuilder/Impl 稀疏注意力主计算；AscendMiniMaxM3QKVParallelLinearWithIndexer 融合 [Q|K|V|index_q|index_k] 列并行 GEMM（shard 校验/偏移映射/两种 weight_loader）、AscendMiniMaxM3IndexerLinear 合并 [index_q|index_k] 投影；minimax_m3_sparse_forward 注册为自定义算子（带 fake 实现）供 torch.compile 切图。

models.minimax_m3.ops 子包标记。

MiniMax-M3 NPU 稀疏算子集（639 行）。q2k→k2q CSR 索引转换（_k2q_csr_block_stats/_npu_k2q_csr）把查询主导的稀疏索引转为键主导 CSR 供 AscendC 算子消费；index 打分：_minimax_m3_index_score 调捆绑 AscendC 算子计算索引分、minimax_m3_index_prefill（prefill 打分 + 块 topk 收尾）、minimax_m3_index_decode（decode 打分 + 非融合局部 topk）、minimax_m3_index_tp_block_parallel_decode（TP 分块并行打包打分与 topk）；稀疏注意力：minimax_m3_sparse_attn 按 A3/A5 硬件分发（_minimax_m3_sparse_attn_a3/a5）、minimax_m3_sparse_attn_decode 走 AscendC 稀疏注意力算子；MiniMaxM3TPDecodeScoreMetadata 保证 TP decode 打分的图稳定输入。

MiniMax-M3 Triton kernel 集（1638 行，非 A5 平台）。index 打分：_prefill_index_score_kernel 对每个可见稀疏块算一个最大点积分、_decode_index_score_kernel decode 打分；topk：_mask_decode_topk_indices_kernel/_mask_prefill_topk_indices_kernel 失效块掩码、_prepare_prefill_topk_scores_kernel 应用 init/local 优先级填充无效尾部；稀疏注意力：_gqa_sparse_fwd_kernel（prefill，block_size_q==1）/_gqa_sparse_decode_kernel（decode split-K）+ _merge_topk_attn_out_kernel 合并多块输出与 LSE；包装函数 minimax_m3_index_score/topk/decode 与 minimax_m3_sparse_attn/decode 组织 kernel launch；_copy_topk_indices/values 复制并填充 topk 结果；_detected_aicore_count/_is_arch_support_pdl 做硬件适配。

MiniMax-M3 A5 平台 Triton kernel 集（1417 行）。与通用版对应但按 A5 特性调优：_decode_qk_score_kernel 单程序处理一个 query/chunk 的 decode QK 块打分、_index_block_score_kernel 索引块打分；topk 准备/掩码 kernel（prefill 与 decode 两套 init/local 掩码构建 _build_decode_index_score_masks）；稀疏注意力 _gqa_sparse_fwd_kernel/_gqa_sparse_decode_kernel + _merge_topk_attn_out_kernel；对外的 minimax_m3_index_score/topk/decode、minimax_m3_sparse_attn/decode 接口与通用版一致（torch.topk + 失效索引掩码）；_prune_decode_index_score_configs/_sparse_attn_num_stages_kwarg 做 kernel 配置裁剪与调优。