vLLM Ascend · 其余功能模块 API 参考

310P 注意力掩码构建器（186 行）。AttentionMaskBuilder310 生成因果加性掩码（gen_causal_additive_mask）、splitfuse 掩码（普通/压缩两种），is_compressed_mask_supported 判断硬件是否支持压缩掩码格式。

310P 注意力后端（345 行）。AscendAttentionBackend310 声明后端元信息与 KV cache 形状；AscendAttentionBackendImpl310 实现 prefill/decode/chunked prefill 三条前向（_flash_attention 走 FA、forward_paged_attention 走 PA）与编码器注意力。

310P 元数据构建器（158 行）。AscendAttentionMetadataBuilder310 构建 310P 专属注意力元数据；set/get_query_lens_cpu 在不扩展上游 AscendMetadata 的前提下挂载 host 侧 qLens（ATB splitfuse 需要）。

310P 块表（199 行）。BlockTable/MultiGroupBlockTable 的 310P 版本：slot mapping 计算（_compute_slot_mapping_numpy 走 NumPy 路径，310P 无 Triton）、块表索引获取与输入归一化。

310P MoE 方法（140 行）。AscendUnquantizedFusedMoEMethod310（非量化 MoE 方法）、AscendRoutedExperts310/AscendMoERunner310 的 310P 适配（无 MC2，走 all-gather 路径）。

310P 分组 top-k 路由器（64 行）。AscendGroupedTopKRouter310 用分块 softmax 实现 top-k 路由（310P 不支持融合门控算子的替代路径）。

310P MoE 通信（50 行）。AllGatherCommImpl310 用 all-gather + reduce-scatter 做 MoE 通信（_apply_mlp 应用 MLP、_get_token_dispatcher 返回 310P 分发器）。

310P MoE MLP（102 行）。quant_apply_mlp/unquant_apply_mlp 的 310P 实现（group_list_type 区分 AscendC 契约），unified_apply_mlp 统一入口。

310P token 分发器（88 行）。TokenDispatcherWithAllGather310 用 all-gather 实现 token 分发（无 all-to-all 的 310P 适配）。

310P KV 块清零器（82 行）。AscendKVBlockZeroer310 不依赖 Triton（310P 无 Triton-Ascend 时用 NPU 算子实现）：init_meta 预计算元数据、zero_block_ids 批量清零。

310P 模型运行器 V1（982 行）。NPUModelRunner310 与 910B 采用不同的 ACL graph 捕获/重放契约：批执行判定与填充（_determine_batch_execution_and_padding）、注意力元数据构建、uniform decode 查询长度临时修改、KV 缓存张量分配与清零元数据初始化。

310P 输入批（59 行）。NPUInputBatch310 的 310P 适配版本。

310P 激活算子（32 行）。AscendSiluAndMul310 用 310P 支持的 NPU 算子组合实现 SiluAndMul。

310P 因果卷积（297 行）。纯 PyTorch 实现（310P 无 Triton kernel）：causal_conv1d_fn（支持初始状态与激活）、causal_conv1d_update（decode 增量更新）、causal_conv1d_ref（参考实现）。

310P 3D 卷积（27 行）。AscendConv3dLayer310 适配视觉编码器卷积层。

310P GDN chunk 路径（586 行）。chunk_gated_delta_rule_310 由 AscendC fwd_h/fwd_o kernel 支撑（_require_ascend_chunk_ops 校验）；输入归一化支持 TND/变长（_normalize_chunk_inputs/_pad_varlen_to_chunk）、按 WY 前缀构造 kernel 输入（_compute_kernel_inputs_from_torch_wy）、输出 unpad（_unpad_chunk_output）；chunk_gated_delta_rule_pytorch 为参考实现。

因果卷积元数据计算（57 行）。compute_causal_conv1d_metadata 从 query_start_loc 推导 GDN causal conv1d 所需的元数据（序列偏移与状态索引）。

310P GDN 门控（62 行）。fused_gdn_gating_pytorch 用 PyTorch 实现 GDN 门控计算（A_log/a/b/dt_bias → beta），是 Triton 版的 310P 替代。

310P GDN 递归路径（227 行）。fused_recurrent_gated_delta_rule_pytorch 用 PyTorch 递归实现 GDN delta 规则（decode 期）；_expand_to_hv 支持 grouped-value-attention 语义、_infer_num_states/_state_index 管理状态索引。

310P GDN 注意力（432 行）。npu_recurrent_gated_delta_rule_310 递归路径、AscendGatedDeltaNetAttention310 组装（get_attn_backend/_forward_core）；_merge_spec_and_non_spec_outputs_310 把投机与非投机 GDN 输出合并回批次布局；_mask_padded_recurrent_accepted_tokens 掩蔽投机接受的填充 token。

310P chunk 索引工具（42 行）。prepare_chunk_indices_310/prepare_chunk_offsets_310 预计算变长序列的 chunk 索引与偏移。

310P L2 归一化（43 行）。l2norm_310p 用 310P 的 RMSNorm kernel 变通实现末维 L2 归一化（_l2norm_unit_weight 构造单位权重）。

310P GDN 元数据构建器（259 行）。GDNAttentionMetadataBuilder310 在通用构建器上做 310P 覆盖：prefill 初始状态与 causal conv 元数据、spec/non-spec 的 fallback 元数据、decode/spec 元数据填充。

310P 归一化算子（68 行）。AscendRMSNorm310/AscendGemmaRMSNorm310/AscendRMSNormGated310（_apply_activation 处理门控激活）的 310P 版本。

310P 多模态编码器注意力（161 行）。AscendMMEncoderAttention310（QKV 三维重排 + forward_oot）；is_approximate_calculation_supported 判断近似计算支持。

Qwen3-VL 310P 适配（35 行）。rot_pos_emb_310 替换 Qwen3-VL 视觉旋转位置编码的计算路径。

310P RoPE（273 行）。AscendMRotaryEmbedding310/AscendRotaryEmbedding310（set_rope_position_flag_310p 设置位置标志）；mrope 支持：merge_mrope_cos_sin_for_apply 合并三分量 cos/sin、set_mrope_apply_rotary_slices 按 positions 构建 cos/sin 视图（每 forward 一次）；_apply_rotary_mrope_torch 为对齐 vLLM native 的 PyTorch 路径。

310P 词嵌入（92 行）。AscendVocabParallelEmbedding310/AscendParallelLMHead310/AscendUnquantizedEmbeddingMethod310 的 310P 版本。

310P 量化 scheme 注册表（41 行）。register_scheme 装饰器按（quant_type, layer_type）注册；get_scheme_class 查询。

310P W8A8 基类（44 行）。AscendW8A8Linear310pScheme 定义权重与 per-tensor/per-channel 参数获取接口。

310P W8A8 动态量化（177 行）。AscendW8A8DynamicLinearMethod310（线性）与 AscendW8A8DynamicFusedMoEMethod310（MoE）：动态量化参数获取、apply、加载后权重处理。

310P W8A8 静态量化（98 行）。AscendW8A8LinearMethod310 的静态量化实现。

310P W8A8S 稀疏量化（66 行）。AscendW8A8SLinearMethod310 支持 W8A8S 稀疏线性 scheme。

310P W8A8SC 量化（104 行）。AscendW8A8SCLinearMethod310 支持 W8A8SC（sparse-compressed）静态线性 scheme。

310P ModelSlim 配置（140 行）。AscendModelSlimConfig310 为 ModelSlim 量化配置的 310P 覆盖（get_quant_method）；create_scheme_for_layer 按量化描述为层创建 scheme 实例。

310P 拒绝采样器（113 行）。AscendRejectionSampler310 用 PyTorch recovered-token 路径 + CPU RNG 实现（无 Triton 依赖）。

310P 采样器（187 行）。AscendSampler310/AscendTopKTopPSampler310：310P 不支持所需 NPU 随机数路径，随机采样改用 pinned CPU 内存生成均匀数（_prepare_cpu_generators_310p/_generate_request_uniforms_310p）再经 CDF 采样（_sample_from_cdf_310p，仅用 310P 支持的 NPU 算子）；fill_exponential_310p CPU 生成指数分布后搬运。

310P 分片状态加载器（80 行）。ShardedStateLoader310 保存分片模型（save_model）并生成量化描述（generate_quant_description）。

310P 投机解码 proposer 基类（122 行）。AscendSpecDecodeBaseProposer310 处理 NPU 特有 workaround：_run_merged_draft 合并 draft、set_inputs_first_pass 首趟输入设置。

310P V2 块表（169 行）。Ascend310PBlockTables：CPU 持有的 MRV2 块表（与 310P MRV1 数据路径一致），init_block_table_layout_tensors 布局张量初始化、append_block_ids/apply_staged_writes 增量更新、slot mapping 与 dummy 输出。

310P V2 块清零适配（38 行）。AscendKVBlockZeroer310V2 把 V2 的扁平 block-size 布局归一化后复用 V1 的 310P 清零器。

310P V2 运行器（755 行）。NPUModelRunner310V2：配置校验、310P 输入准备（_prepare_inputs_310p）、KV 规格与初始化、kernel 块大小调整、prefill 输入准备、draft token 合并、采样与注意力准备。

310P V2 模型状态（187 行）。_Ascend310PModelStateMixin 提供 310P RoPE/全图 seq_lens 辅助；Ascend310PModelState（dense/VL，无 Triton 采样器与 MRoPE、编码器支持）；Ascend310PMambaHybridModelState（hybrid/GDN，保持 Ascend hybrid 契约、换用非 Triton RoPE）。

310P V2 RoPE 状态（113 行）。Ascend310PRopeState 无 Triton 的 MRoPE 状态（Qwen3-VL/Qwen3.5）：prefill 位置初始化、CPU 位置准备、staged write 应用；get_310p_rope_state 工厂。

310P V2 采样器（66 行）。Ascend310PSampler 无 Triton 的采样器：add_request 登记请求 RNG、apply_staged_writes 应用暂存写、__call__ 执行采样。

310P V2 请求状态（137 行）。Ascend310PStagedWriteTensor 用 CPU 持有实现替代 vLLM 的 Triton staged writes（stage_write/stage_write_elem/apply_write）；Ascend310PRequestState 与 MRV1 310P 同款的 CPU 持有模型。

310P worker（187 行）。NPUWorker310：设备初始化（init_device/_init_device）、ATB 预热（_warm_up_atb）、可用显存判定、分片状态保存、创建 310P 专属 model runner。

设备配置运行时入口（77 行）。DeviceConfig 不可变硬件族配置；get_device_config 返回当前安装对应的配置；check_ascend_device_type 校验安装包与运行时 NPU 匹配；is_310p/is_950 快捷判断。

设备算子适配器（1596 行）。BaseDeviceAdaptor 定义全部设备算子接口：reshape_and_cache、npu_fused_infer_attention_score（FIA）、MoE 路由（npu_moe_init_routing/moe_gating_top_k）、分组乘（npu_grouped_matmul_swiglu_quant/gmm2）、动态量化、KV 加载（kv_cache_load）、indexer 后处理、稀疏注意力执行等；A5DeviceAdaptor 覆盖 A5（Ascend950）差异算子（MXFP scale 布局、indexer 量化 scatter 三段式等）；Ascend310PDeviceAdaptor 覆盖 310P 差异；get_device_adaptor 按硬件族返回适配器。

纯硬件识别（75 行）。AscendDeviceType 枚举内部硬件族；device_type_from_soc_version 把编译期 SOC_VERSION 解析为硬件族；device_type_from_runtime_soc 解析 torch-npu 报告的运行时 SOC 版本。

硬件能力档案（233 行）。HardwareCapability/AttentionBackendFamily/CPUBindingMode/DeviceAdaptorFamily/DeviceAddressingMode/QuantizationBackendFamily/WeightLayoutPolicy 定义正交能力维度；HardwareProfile 为一个 SoC 族的不可变能力与实现选择集合（supports 查询）；get_hardware_profile/get_current_hardware_profile 按设备类型取档案，供共享业务逻辑按硬件分派。

设备算子工具（139 行）。npu_large_head_prefill_attention 大头 prefill 注意力（KV 头多于 Q 头场景）：_gather_paged_kv_to_dense 把分页 KV 按块表聚成稠密张量后走普通注意力算子。

CANN 内存池分配器（310 行）。CaMemAllocator 单例管理 CANN 张量内存池：python_malloc/free_callback 对接可插拔分配器、use_memory_pool_with_allocator 启用池、sleep/wake_up 释放/恢复池内存（睡眠模式基础）、get_current_usage 用量统计；find_loaded_library 定位已加载的 C库；create_and_map/unmap_and_release 管理分配句柄。

睡眠唤醒管理器族（186 行）。SleepWakeupManager：sleep 时释放非持久显存（_measure_memory_released 实测释放量）、wakeup 恢复；AclGraphSleepWakeupManager 额外清理注意力 workspace 与重置图参数；HcclSleepWakeupManager 销毁/恢复 HCCL 通信组（iter_alive_group_coordinators/refresh_moe_hccl_groups）。

基于打分的编码器缓存管理器（522 行）。ScoreEncoderCacheManager 管理多模态编码器缓存的进出：score 为缓存项打分、should_promote 判断晋升 NPU、evict_from_npu 驱逐、check_and_update_cache 更新、allocate/free 管理配额（cal_theory_cost_storage_cost 理论存储成本）；ScoreEncoderCacheConfig 策略配置；_check_invariant 不变量检查。

EPLB 的 vLLM 适配器（222 行）。VllmEplbAdaptor 连接 EPLB 核心与 vLLM 模型：注册层（register_layer）、初始化专家参数与缓冲、读取 rank 专家负载（get_rank_expert_workload）、清除负载数（clear_all_moe_loads）、执行专家映射/权重/log2phy 更新（do_update_*）、导出张量到文件。

专家权重 D2D 搬运器（138 行）。D2DExpertWeightLoader 在设备间直接搬运专家权重：generate_expert_d2d_transfer_task 生成搬运任务、asyn_expert_weight_transfer 异步执行、update_expert_map_and_weight 更新映射与权重（ExpertWeightUpdateState 跟踪状态）。

EPLB 工具（145 行）。init_eplb_config 初始化 EPLB 配置（专家数/冗余数/共享专家）、generate_global_placement 生成全局部署、generate_log2phy_map 生成逻辑到物理映射、expert_file_to_tensor 从文件读专家映射。

EPLB worker（410 行）。EplbWorker 执行重均衡：fetch_and_sum_load_info 拉取并汇总负载、calculate_rebalance_experts 计算重均衡方案（compose_expert_update_info_greedy 贪心组合）、update_expert_map 应用映射、check_expert_placement 校验；_compute_imbalance/_calculate_hotness 计算不均衡度与热点；EplbProcess 管理独立 worker 进程。

EPLB 策略抽象（30 行）。EplbPolicy 定义 rebalance_experts 接口。

默认 EPLB 策略（350 行）。DefaultEplb 实现专家重均衡：add_redundant 添加冗余副本、compute_balanced_pack(_redundancy) 计算均衡打包、constraint_expert_local_exchange 限制本局交换、get_redundant_num 冗余数；DynamicTable 动态路由表。

EPLB 策略工厂（41 行）。PolicyFactory.generate_policy 按配置名创建策略实例（default/flashlb/swift/random）。

FlashLB 快速负载均衡策略（1026 行）。基于专家负载统计（mu/var/cov）的部署优化：副本数分配三算法（min_max_replica/max_delta_replica/percentage_replica）、LPT 部署（lpt_deployment）、设备方差增量更新（compute_updated_device_variance）、均衡评分（compute_score）；FlashTree 支持邻居搜索与均衡性优化；FlashLB 主类：滑动/增量统计更新（sliding_update_stats/incremental_update_stats）、热点注册（register_hotness）、更新必要性判断（need_update）、最小化重部署（minimize_redeploy_with_inner_permutation）；warm_up 用哑数据预热。

随机负载均衡策略（26 行）。RandomLoadBalance.rebalance_experts 随机重排专家部署（基线/测试用）。

SwiftBalancer 策略（751 行）。SwiftBalanceEplb 实现专家重部署：统计专家分布（statistics_expert_distribution）、冗余分配（compute_redundant_assignments/distribute_redundant_experts/redundancy_again）、未部署 rank 填充（fill_in_undeployed_ranks）、跨 rank 专家交换（swap_experts_between_ranks/expert_exchange_between_ranks）、层热度与不均衡计算。

EPLB 更新协调器（192 行）。EplbUpdator 驱动一次专家重均衡生命周期：forward_before/forward_end 挂钩前向、compute_and_set_moe_load 计算并设置 MoE 负载、update_iteration/update_expert_weight_flag 触发 worker 更新、wakeup_eplb_worker 唤醒 worker 进程、warm_up_eplb 预热。

MoE LoRA 执行器（396 行）。AscendFusedMoEWithLoRA 为 Ascend 原生 MoE-LoRA 包装（_build_lora_context 构建 LoRA 上下文、set_mapping）；AscendFusedMoE3DWithLoRA 支持 w1+w3 已融合为 3D 权重的 checkpoint；索引处理：prepare_lora_indices 截断/填充/TP 切分 token→LoRA 索引、preprocess/postprocess_lora_indices 为 AlltoAll 路径展开重排与还原、all2all_lora_indices 跨 EP 交换；路由恢复：_recover_moe_lora_routing_allgather/all2all 按 dispatch 路径恢复每行 (expert_id, lora_slot)；delta 注入：moe_lora_apply_w13/w2 在激活前/下采样后叠加 LoRA 增量；sync_lora_context 推送/清除通信单例上的上下文。

LoRA 核心算子（122 行）。BGMV/S GMV 两类 batched 分组乘：bgmv_shrink/expand/expand_slice（按 token 的 LoRA 索引）与 sgmv_shrink/expand/expand_slice（按序列段），调用 vllm_ascend_C 自定义算子完成 LoRA 下投影/上投影。

Punica LoRA 元数据管理（470 行）。PunicaWrapperNPU 管理同批多 LoRA 的元数据与执行：update_metadata 按批刷新索引；shrink/expand 各分 prefill/decode 两路径（_shrink_prefill/_shrink_decode/_expand_*）；add_shrink/add_expand 组合调用、add_lora_embedding/add_lora_linear 处理嵌入与普通线性层的 LoRA；_get_token_lora_indices 换算 token 级 LoRA 索引。

可扩展的量化 MoE LoRA（280 行）。register_quant_moe_lora_impl 按 quant_type 注册实现、quant_apply_mlp_with_moe_lora 把活跃的量化 MoE LoRA 批次分派到后端；_apply_dynamic_int8_moe_lora 在 INT8 基础专家上以 BF16/FP16 边界注入 LoRA（_validate_dynamic_int8_activations 校验激活）；_apply_moe_activation 对齐非量化路径的激活语义。

LoRA 类刷新工具（19 行）。refresh_all_lora_classes 按 vLLM 版本刷新全部 LoRA 相关类的基类绑定（多版本兼容）。

offloader 工厂（28 行）。create_offloader 按配置创建 Ascend 感知的 CPU offloader，同时保留 vLLM 默认行为。

预取式 CPU offload（201 行）。AscendPrefetchOffloader 复用 vLLM 行为但支持 NZ 静态缓冲：mark_prefetch_offload_nz_weight 标记需 NZ 格式的参数、_format_static_buffers_for_nz 把静态缓冲转型为 FRACTAL_NZ；_ModuleOffloader 包装模块 offload（_capture_static_buffer_formats_from_npu_params 从 NPU 参数捕获静态缓冲格式）；ParamInfo 携带格式要求。

kernel 预热调度（49 行）。kernel_warmup 在 ACL graph 捕获前预热模型执行用到的 Triton kernel（_run_warmup 逐项执行并容错）。

惩罚 kernel 预热（78 行）。penalties_triton_warmup 在首次带惩罚采样前 JIT bincount 与惩罚 Triton kernel（_make_history_tokens 构造哑 token 历史）。

拒绝采样 kernel 预热（416 行）。rejection_sampler_triton_warmup 在首个投机请求前按全部 constexpr 组合预热 kernel：collect_warmup_rejection_block_sizes/collect_warmup_batch_sizes 收集代表性 batch/BLOCK_SIZE、_warm_greedy/_warm_rejection_random/_warm_sample_recovered/_warm_expand/_warm_prepare_inputs 各分支预热、_collect_no_draft_probs_values 对齐在线路径参数。

QK RMS kernel 预热（87 行）。triton_rms_warmup 判断模型是否使用 triton_q_rms（_model_uses_triton_q_rms）并按 BLOCK_M 常量组合预热（collect_triton_rms_warmup_block_m_values）。

NetLoader 插件注册（20 行）。register_netloader 把弹性加载器注册为 vLLM 模型加载插件。

HCCL 弹性加载执行器（630 行）。P2PSend/P2PLoP2P 用 HCCL 后端分布式收发模型参数；张量收集：_collect_processed_layout_tensors 收集 int8_cache=no 的处理后布局张量、_iter_raw_send/recv_transfer_params 枚举收发参数；HCCL 传输的格式处理：_hccl_transfer_tensor 转连续 FRACTAL_ND、_cast_tensor_to_fractal_nz 传后恢复 NZ、W4A8 的 int32 打包 NZ 经 int8 底层导出（_cast_packed_int32_via_int8）；清单机制：build_transfer_shape_manifest/reshape_transfer_items_to_manifest/validate_transfer_items_numel_against_manifest 保证收发双方形状一致（HCCL 前 fail-fast）。

无状态进程组（180 行）。stateless_init_process_group 初始化不绑定全局状态的进程组（用于加载期通信）；destroy_stateless_process_group 销毁并手动 GC。

弹性加载 TCP 交互（527 行）。ElasticServer/ElasticClient 处理 Netloader 的服务端/客户端逻辑：TCP JSON 消息收发（_recv_json_message 完整读取）、传输清单注册（register_transfer_manifest/_parse_transfer_shape_manifest）、客户端注册与连接生命周期管理。

弹性加载入口（107 行）。elastic_load 跨多设备弹性加载模型权重（device_id/model_path/sources/tp/pp 参数组织加载拓扑）。

弹性加载器本体（581 行）。ModelNetLoaderElastic：load_model 驱动加载（draft 模型先同步目标加载器 _sync_target_netloader_before_draft）、load_weights 权重写入、download_model 下载；静态 forward context 快照与恢复（_snapshot/_remove_new_static_forward_context_keys）保证加载前后一致；revert_to_default 回退默认加载器；pre_transfer_weight_processing 解包 MoE 共享专家校验。

NetLoader 工具（63 行）。find_free_port 找空闲端口、is_valid_path_prefix 校验路径前缀。

RFork 加载器插件注册（20 行）。register_rforkloader 注册 RFork 模型加载器。

RFork 模型加载器（436 行）。RForkModelLoader 从种子实例（已加载同权重的运行实例）fork 加速加载：load_model 判断 draft/EP/PP rank（_is_draft_model/_get_ep_rank/_get_pp_rank）、_requires_processed_layout_transfer 决定布局、_ensure_rfork_worker 保证 worker 就绪；兼容处理：_reset_process_global_model_state 清理被丢弃模型的全局注册、_rfork_skip_unquantized_moe_post_load_processing 跳过非量化 MoE 后处理（dense 层照常）、动态 EPLB 判断。

RFork worker（145 行）。RForkWorker 执行种子传输：is_seed_available 检查种子、pre_transfer/transfer/post_transfer 三段传输、reset_transfer_state 重置、start_seed_service 作为种子方提供服务。

RFork 种子协议（242 行）。RForkSeedProtocol 管理种子实例的获取与归还：get_local_seed_key 构造本地种子键（按 PD 分离模式/node rank/TP rank/部署策略）、get_seed/release_seed/report_seed 与种子服务端交互（_request_timeout_sec 超时控制）。

RFork 种子服务端（141 行）。start_rfork_server/start_fastapi_server 启动 FastAPI 种子服务（健康检查超时、传输引擎信息注册），供其他实例拉取权重。

RFork 传输后端（625 行）。RForkTransferBackend 管理传输引擎：init_transfer_engine 初始化、register/unregister_memory_region 注册内存区、recv_from_source 从种子拉取；张量收集与对齐：_collect_processed_layout_tensors/_collect_checkpoint_layout_tensors 按布局收集可传张量、_reshape_tensor_to_seed_shape 对齐种子形状、_iter_transfer_chunks 按地址块切分传输块（_block_contains_weight_ptr 判断归属）；get_remote_instance_weight_shape_info 查询远端形状信息。

Ascend 指标处理器（95 行）。_register_eplb_metrics 注册 EPLB 指标；eplb_do_update_hotness_handler 记录 rank-0 worker 暴露的聚合专家热度。

指标提供者（21 行）。get_metric_provider 惰性返回 MS Service Metric 提供者（避免硬依赖）。

均衡调度 patch（912 行）。BalanceScheduler 按 DP rank 负载把请求均衡分派：balance_gather 汇聚各 rank 负载、schedule 重排请求；BalanceDPEngineCoreProc 提供 DP engine core 钩子（_has_global_unfinished_reqs）；_balance_run_engine_core 替换 engine core 主循环；_balance_scheduling_enabled 判断启用。

分布式 310P 适配 patch（89 行）。communication_adaptation_310p 调整 310P 的通信后端选择；NullHandle 提供空 wait 的异步句柄占位。

DP 设备 ID 解析 patch（71 行）。_patched_get_physical_gpu_ids_for_local_dp_rank 修正 vLLM 在 DP 下解析物理设备 ID 的逻辑（支持设备控制环境变量与用户指定 ID 列表）。

DyntraLB 引擎核 patch（547 行）。DyntraLBDPEngineCoreProc 在 DP engine core 中驱动负载均衡：run_balance_load 周期触发、_do_lb_allgather 全局汇聚、_balance_load 计算并应用迁移修改（_RequestItem/_CardData/_Modification 描述请求、卡与修改）；_has_global_unfinished_reqs_with_diagnostics 带诊断的全局未完成判断；_print_* 系列按诊断开关输出负载与修改详情；_dyntra_lb_run_engine_core 替换 engine core 主循环。

EPLB 构建 patch（138 行）。收窄 vLLM EPLB 在 Ascend 上的构建与提交：_wrap_communicator_factory 包装通信器工厂、_wrap_move_to_workspace 延迟 worker 确认直到 Ascend commit 钩子完成（_DeferredConsumedEvent）、_CudaAlikeEplbPlatformProxy 让 NPU 平台通过 EPLB 的 CUDA 类校验。

FusedMoE EPLB 接入 patch（192 行）。_adapt_eplb_router 只挂接 Ascend 的 EPLB 状态与映射操作（_ascend_apply_eplb_mapping）；_ascend_FusedMoE 替换 FusedMoE 构造以接入 Ascend 路由专家。

混合 KV 协调器 patch（654 行）。AscendHybridKVCacheCoordinator 处理多 KV 类型混合模型：verify_and_split_kv_cache_groups 校验并拆组、find_longest_cache_hit 找最长命中（_cache_hit_alignment_tokens 对齐 token、_get_effective_block_size 有效块大小）；_select_kv_token_budget 计算 KV token 预算；DSV4 spec 识别。

KV cache 工具 patch（392 行）。_ascend_resolve_kv_cache_block_sizes 解析 Ascend 兼容的块大小；group_and_unify_kv_cache_specs 把 KV spec 分组并统一为 UniformType（_get_kv_cache_groups_uniform_groups/uniform_page_size）；_get_kimi_k3_dspark_mixed_kv_cache_groups 构建拓扑无关的 Kimi K3 DSpark 调度组；_get_kv_cache_config_deepseek_v4 做 DSV4 的 KV 张量布局规划；_kv_cache_config_has_mamba_layers 识别嵌在 UniformType 组内的 Mamba 层。

Mamba 配置 patch（149 行）。verify_and_update_config 保证注意力层页大小不小于 Mamba 状态页大小；_using_kv_store 检查是否用 AscendStoreConnector。

310P Mamba 配置 patch（103 行）。verify_and_update_config 的 310P 变体（同样的页大小约束校验）。

Mamba 管理器 patch（88 行）。AscendMambaManager 提供 Mamba 状态的缓存命中查找（find_longest_cache_hit）与分配块数计算（get_num_blocks_to_allocate）。

MiniMax-M2 配置 patch（136 行）。_patched_verify_quantization 注入 ModelConfig 量化校验的中间行为：按模型类型判断并禁用 FP8（_should_disable_fp8/_disable_fp8）；_patched_verify_cuda_graph 校验 cudagraph 兼容性。

MLA prefill 后端 patch（48 行）。AscendMLAPrefillBackend 声明可用性（is_available）并实现 prefill 新 token 与上下文 chunk 两段执行（run_prefill_new_tokens/run_prefill_context_chunk）。

多进程执行器 patch（211 行）。AscendMultiprocExecutor 适配 Ascend 的多进程执行：_get_parallel_sizes 取并行规模、_is_driver_indentify driver worker；AscendWorkerProc.make_worker_process 定制 worker 进程创建。

PP+MTP 运行时支持 backport（349 行）。让 MTP 投机解码在流水线并行下工作：_patch_scheduler_update_after_schedule/update_from_output/make_cached_request_data 修调度器、_update_pp_mtp_spec_token_ids 维护跨 PP 的投机 token、_patch_model_runner_output/_patch_engine_core 修输出与引擎核；PD prefill 节点判断与 IPC 运行时 patch 变体。

profiling chunk patch（229 行）。_record_execution_timing 记录执行耗时供在线模型修正；_ensure_update_from_output_wrapped/_ensure_schedule_wrapped 包装调度器方法传递计时信号；_patched_run_engine_core 在 EngineCore 初始化时触发 profiling 与计时钩子。

投机配置 patch（54 行）。_normalize_legacy_qwen3_dspark_config 归一化旧版 Qwen3 DSpark 配置；_dspark_post_init 补充 DSpark 配置的后置初始化。

结构化输出 patch（134 行）。允许按请求选择结构化输出后端：_request_backend/_sampling_params_backend 解析请求级后端、_raise_mixed_backend 拒绝混用；_patch_sampling_params_validation/_patch_structured_output_manager 注入校验与管理器行为。

torch accelerator patch（23 行）。patch_empty_cache 修正空缓存调用在 NPU 上的行为。

V2 运行器开关 patch（45 行）。_patched_use_v2_model_runner 直接读 VLLM_USE_V2_MODEL_RUNNER 环境变量；_patched_get_unsupported_features/_patched_validate_v2_model_runner 放开 V2 特性校验。

视觉模型 patch（69 行）。_patched_fused_input_norm_forward 修正视觉 fused input norm 前向（按 grid_thw 与视觉 dtype）；install_patch 安装。

HCCL 进程组复用注册表（295 行）。HcclPgRegistry 以（ranks/backend/pg_options/reuse_domain）为键复用 HCCL 组：acquire/release/clear 管理生命周期；make_hccl_pg_key 构造哈希键、_normalize_hccl_pg_options 归一化选项、_is_non_group_member 处理非组成员哨兵。

KV cache 绑定 patch（50 行）。bind_kv_cache 把分配好的 KV cache 同时绑到 ModelRunner 与 forward context（处理注意力模块数与 runner 缓存数不一致的情况）。

cudagraph patch（38 行）。_create_padded_batch_descriptor 修正填充批描述符的构建（LoRA 活跃数等字段）。

DeepSeek-V2 patch（357 行）。_deepseek_v2_mla_attention_init 修正 MLA 注意力初始化（indexer 初始化跳过判断 _should_skip_indexer_init）；_patched_forward 替换模型前向以适配 NPU。

分布式 patch（254 行）。GroupCoordinatorPatch 扩展 vLLM GroupCoordinator：_init_device_groups/_init_device_communicator 初始化设备组与通信器、_release_hccl_resources/destroy_hccl/restore_hccl 支持睡眠模式的 HCCL 销毁与恢复；_create_device_group 创建设备组时经 HCCL 注册表复用组（_acquire_hccl_group，_resolve_reuse_domain 决定复用域）；_patch_destroy_distributed_environment 包装销毁流程。

Eagle3 初始化 patch（129 行）。修正 PP 下 Eagle3 draft 模型的 target_layer_num（_patched_eagle3_llama_init/_patched_eagle3_deepseek_v2_init 分别覆盖 Llama 与 DeepSeek-V2 版本）。

Eagle3 PP 辅助隐藏层 patch（238 行）。把 Eagle3 的 aux hidden states 经 PP 管线传播：_extract_aux_from_intermediate 从中间张量提取、_make_deepseek_v2_forward/_make_eagle_mixin_forward 生成带传播的前向、_patch_make_empty_intermediate_tensors 补缓冲、patch_eagle3_pp_aux_propagation 安装。

Kimi K2.5 patch（95 行）。AscendLearnable2DInterpPosEmbDivided_fixed 修正可学习二维插值位置编码的前向（get_rope_shape 计算形状）。

Mamba 工具 patch（512 行）。preprocess_mamba 把上一步 Mamba 状态拷到新块（抢占恢复）；拷贝实现双路径：Triton 批量拷贝（_can_launch_triton_batch_memcpy/_batch_memcpy_triton/_stage_mamba_copy_metadata/_do_mamba_copy_block_npu，指针元数据在预处理期暂存）与 PyTorch 回退（_collect_mamba_copy_meta_torch/_do_mamba_copy_block_torch）；层级拷贝：prepare_mamba_copy_by_layer/do_mamba_copy_block_for_layer/finish_mamba_copy_by_layer 服务层级执行；_postprocess_mamba_align_gpu_cpu_fallback 为 310P 的 CPU 回退。

MiniMax-M2 patch（54 行）。_patch_forward 替换其位置编码-隐藏层前向以适配 NPU。

Qwen3.5 patch（243 行）。AscendQwen3NextAttention/AscendQwen3_5DecoderLayer 替换前向（_uses_multimodal_rope 判断多模态 RoPE），适配 NPU 注意力路径。

Qwen3 DFlash patch（81 行）。precompute_and_store_context_kv 预计算并存储上下文 KV（draft 复用）；_patched_read_mask_embedding 修正 read mask 嵌入。

Qwen3-VL patch（105 行）。forward_with_split_qkv_rmsnorm_mrope 用融合 kernel 替换视觉 QKV+norm+mrope；_fast_pos_embed_interpolate 加速位置嵌入插值；tensor_parallel_wrap 包张量并行；patch_qwen3_vl_moe_pp_layer_range 修 PP 层范围。

专家路由捕获 patch（188 行）。capture 在 graph 捕获期为特定层捕获专家路由决策（topk_ids），供 EPLB 负载统计在图模式下工作。

Step3.5 patch（69 行）。_patched_attention_forward 替换 Step3.5 注意力前向以适配 NPU。

Triton patch（118 行）。修正 Triton-Ascend 在特定版本下的行为差异（kernel launch/编译选项适配）。

V2 注意力工具 patch（21 行）。_get_ascend_sfa_indexer_backend 返回 Ascend SFA indexer 后端（替换 vLLM V2 的默认选择）。

DSpark 加载 patch（94 行）。_load_dspark_model_with_target_quant 让 DSpark draft 继承目标模型的量化配置（避免 draft 用错量化方案）。

V2 PP 投机解码 patch（93 行）。install_spec_pp_token_broadcast 把已接受 token 与下一 draft token 经同一 V2 PP 槽位广播（投机解码在 PP 下的 token 传递）。

UVA 适配 patch（171 行）。NPU 不直接支持 UVA 张量：UvaBufferWrapper 包装 CPU 缓冲监控修改（MonitoredNumPyArray/MonitoredTorchVector 记录 __setitem__），按需同步；is_uva_available/check_triton_ascend_version_valid 探测特性可用性；get_row_indices_from_key 解析行索引。

torch_npu 性能分析器包装（86 行）。TorchNPUProfilerWrapper 继承 vLLM WorkerProfiler 接入 torch_npu.profiler：_create_profiler 创建、_start/_stop 启停、_profiler_step 步进。

量化包入口（57 行）。通过 __getattr__ 惰性导出各配置类与 scheme，避免循环导入。

LLM-Compressor 量化配置（415 行）。AscendCompressedTensorsConfig 解析 compressed_tensors 格式 checkpoint：_detect_quant_type 探测量化类型、_quantization_scheme_map_from_config 构建 scheme 映射、_add_fused_moe_to_target_scheme_map 补 MoE 目标、get_quant_method 按层返回方法（_get_linear_scheme/_get_moe_scheme）。

FP8 配置（144 行）。AscendFp8Config 服务通用 HF fp8 格式 checkpoint（_verify_block_quantization 校验块量化）；AscendDeepseekV4FP8Config 为 DSV4 变体。

ModelOpt MXFP8 配置（88 行）。AscendModelOptMxFp8Config 加载 ModelOpt 兼容的 MXFP8 checkpoint 并映射到 Ascend 方法。

ModelSlim 量化配置（1118 行，量化配置主文件）。AscendModelSlimConfig 解析华为 ModelSlim 格式：量化类型判定（get_linear_quant_type/get_quant_type_for_layer）、按层创建 scheme（create_scheme_for_layer）、打包模块映射（get_packed_modules_mapping 按模型类型）、MoE scale-bias 名称映射（_make_modelslim_moe_weight_loader）、Kimi K3 混合 KDA 投影识别（uses_kimi_k3_mixed_kda_projection）、前缀重映射（quant_prefix_mapper）、层跳过判断；_is_missing_v_shard 处理 Gemma4 重复 v_proj 缺失分片。

量化方法适配器（323 行）。AscendLinearMethod/AscendKVCacheMethod/AscendFusedMoEMethod/AscendEmbeddingMethod 把 vLLM 的量化方法接口桥接到 Ascend scheme 体系（create_weights/process_weights_after_loading/apply/get_computed_params；MoE 含 is_monolithic/maybe_make_prepare_finalize/get_eplb_weight_views/supports_eplb）。

量化 scheme 汇出（129 行）。is_mx_quant_type 判断是否 MX（microscaling）类量化。

量化 scheme 抽象基类（287 行）。AscendLinearScheme（权重与 per-tensor/per-channel/per-group 参数、apply）、AscendAttentionScheme（注意力量化）、AscendMoEScheme（MoE：动态量化参数/EPLB 权重视图）；get_moe_num_logical_experts 计算逻辑专家数。

C8 INT8 KV cache 量化（164 行）。AscendC8KVCacheAttentionMethod（稠密注意力如 Qwen3：scale/offset 权重加载 _c8_kv_scale_weight_loader）、AscendFAQuantAttentionMethod/AscendSFAQuantAttentionMethod（MLA/SFA 的 FAKQuant，_fa_quant_weight_loader）。

scheme 注册表（62 行）。register_scheme 装饰器按（quant_type, layer_type）注册 scheme 类；get_scheme_class 查询。

W4A4 FlatQuant（175 行）。AscendW4A4FlatQuantDynamicLinearMethod：Kronecker 分解量化（solve_kronecker_decompose 找 a²-b²=n、batched_kronecker_quant 批量量化）、pack_int4_weights 打包 int4。

W4A4 LAOS 动态量化（76 行）。AscendW4A4LaosDynamicLinearMethod 的 per-channel 参数与 apply。

W4A4 MXFP4（229 行）。AscendW4A4MXFP4DynamicLinearMethod（per-group 参数）与 AscendW4A4MXFP4DynamicFusedMoEMethod（MoE：动态量化参数/EPLB 视图）。

W4A4 MXFP4 FlatQuant（167 行）。AscendW4A4MXFP4FlatQuantDynamicLinearMethod 结合 Kronecker 分解与 MXFP4（get_decompose_dim 求分解维度）。

W4A8 动态量化（410 行）。AscendW4A8DynamicFusedMoEMethod：三种格式支持（compressed_tensors/modelslim）、int4→int8 打包（_pack_int4_to_int8/_pack_to_int32）、per-channel scale 压缩（maybe_squeeze_per_channel_weight_scale/_process_scale）、EPLB 权重视图。

W4A8 MXFP（245 行）。AscendW4A8MXFPDynamicLinearMethod/FusedMoEMethod（microscaling 量化）；AscendW4A8MXFPDSDynamicFusedMoEMethod 为 DeepSeek 原生 w4a8 mxfp（128×128 块）变体。

块状 FP8（364 行）。服务原生 fp8 checkpoint：resolve_block_scales 把块 scale 展开为稠密矩阵、_mx_quantize 再量化为 MXFP8（含 uint8 scale）；_supports_mx_regroup 检查 regroup 条件、_is_absorbed_by_attention 识别被 MLA/SFA 吸收的投影；AscendFp8BlockLinearMethod/AscendFp8BlockFusedMoEMethod（专家按需再量化 _requantize_experts_inplace/bf16 回退）。

W8A8 动态量化（350 行）。AscendW8A8DynamicLinearMethod/FusedMoEMethod：per-channel 权重 + 激活动态量化（scale_from_float_to_int64 做 int64 scale 转换）。

W8A8 MXFP8（472 行）。AscendW8A8MXFP8DynamicLinearMethod/FusedMoEMethod（microscaling FP8，restore_weights_for_rl_loading 支持 RL 权重重载）；AscendW8A8MXFP8DSDynamicLinearMethod 为 DeepSeek 原生 128×128 块变体。

W8A8 PD 混合量化（85 行）。AscendW8A8PDMixLinearMethod 支持 prefill-decode 混合精度量化（per-tensor + per-channel 参数并存）。

W8A8 静态量化（137 行）。AscendW8A8LinearMethod：静态 per-tensor/per-channel 参数，apply 走量化 GEMM。

W8A8FP8 动态量化（103 行）。AscendW8A8FP8DynamicLinearMethod/FusedMoEMethod：INT8 权重 + FP8 激活动态量化的组合 scheme。

W4A16（316 行）。AscendW4A16FusedMoEMethod：int4 权重 int32 打包/解包（pack_to_int32/unpack_from_int32）、MoE 动态激活量化参数。

W4A16 MXFP4（150 行）。AscendW4A16MXFP4FusedMoEMethod：FP4 打包解包（unpack_uint8_to_fp4_return_float32）与 MoE 集成。

W8A16（78 行）。AscendW8A16LinearMethod：INT8 权重 FP16 激活，per-channel 参数。

量化参数解析（68 行）。QuantTypeMapping.get_quant_settings 查询量化设置；get_rollback_quant_type 解析回退量化类型；parse_mxfp_quant_params/parse_quant_moe_down_proj_params 解析 MXFP 与 MoE 下投影量化参数。

TP 全量权重切换（296 行）。TPWeightSwitchMixin 为线性方法提供可选的 TP 分片↔全量切换：enable_tp_weight_switch 启用（分配可复用缓冲）、split_tensor_for_tp 切分、all_gather_tp_weight/wait_tp_weight_all_gather 异步 all-gather、switch_tp_weight 切换；TPWeightGatherSpec/TPWeightRepeatSpec 描述需要 gather/repeat 的张量属性；TPWeightSwitchState 管理缓冲与未完成集合通信。服务 DSA-CP/SFA-CP 的 o_proj 全量权重计算。

量化工具（276 行）。detect_quantization_method 从模型文件自动探测量化方法、maybe_auto_detect_quantization 应用到 vllm_config；is_fused_moe_layer 判断 MoE 层；get_dynamic_mx_quant_scale_alg 选择 MX scale 算法；get_model_file 获取模型文件（本地或远端）；enable_fa_quant 判断 FA 量化启用。

采样惩罚入口（45 行）。apply_all_penalties 用 Triton-Ascend 一次性施加出现/频率/重复三类惩罚（_convert_to_tensors 把 list-of-list 的输出 token 转填充张量）。

拒绝采样器（1737 行）。AscendRejectionSampler 为投机解码的 Ascend 优化实现：prepare_sampling 准备、apply_penalties/apply_logits_processors 应用惩罚与 logit 处理器、forward 主入口（含进出日志）；核心采样函数按贪婪/随机/block-verify 分派：rejection_sample（分布式场景）、rejection_greedy_sample_pytorch（含 spec_len_1 特例）、rejection_random_sample_pytorch/block_verify_pytorch、sample_recovered_tokens_pytorch（拒绝处从目标分布恢复采样）、expand_batch_to_tokens/expand_pytorch 批级到 token 级扩展、greedy_sample/apply_sampling_constraints 辅助。

采样器（274 行）。AscendSampler 组织完整采样流程（greedy_sample/apply_penalties/prepare_sampling）；AscendTopKTopPSampler 应用 top-k/top-p（_apply_top_k_top_p_torch_npu 走 NPU 算子、_apply_top_k_top_p_pytorch 回退）；random_sample 按概率随机采样（配合 CPU 生成器）。

投机解码入口（61 行）。get_spec_decode_method 按配置的投机方法创建对应的 Ascend proposer 实例。

DFlash2 proposer（107 行）。AscendDflash2Proposer：与 DFlash 相同输入布局但用选择器替代 argmax——greedy_select_path 从 anchor 沿候选表贪心走出最佳路径、compute_draft_token_ids 产出 draft 序列、_maybe_share_lm_head 共享输出头；is_dflash2_draft 判断配置。

DFlash proposer（311 行）。AscendDflashProposer：set_inputs_first_pass 首趟输入设置、build_model_inputs_first_pass 构建首趟模型输入、dummy_run 哑运行；_compute_num_programs 计算 copy_and_expand kernel 的启动程序数。

通用 draft 模型 proposer（17 行）。AscendDraftModelProposer 包装标准 draft 模型（Eagle 类通用骨架）。

DSpark proposer（389 行）。AscendDSparkProposer：_compute_confidence 计算置信度、initialize_attn_backend 初始化 draft 注意力后端、set_per_group_attn_metadata 按 KV 组设置元数据、set_inputs_first_pass/dummy_run。

Eagle proposer（12 行）。AscendEagleProposer 薄包装（复用基类能力）。

辅助隐藏层提取 proposer（198 行）。AscendExtractHiddenStatesProposer 提取并缓存目标模型中间层 hidden states 供 Eagle3 类 draft 使用：_determine_batch_execution_and_padding 批执行判定、prepare_next_token_ids_padded 准备填充后的下一 token ID。

proposer 基类（2417 行，投机解码最大文件）。AscendSpecDecodeBaseProposer 是全部 draft proposer 的基座：模型加载与共享（load_model/_maybe_share_embeddings/_maybe_share_lm_head/_maybe_share_topk_indices）、D2T 变换移除（_maybe_remove_d2t）、图参数更新（_update_full_graph_params_if_needed）、提议主流程（_propose/_sample_draft_from_logits）、多模态图像 token 索引（_get_multimodal_image_token_index）、GLM 系列判断与 padded drafter 批次守卫。

Medusa proposer（72 行）。AscendMedusaProposer 用 Medusa 头生成多 token 候选（propose/dummy_run）。

NGram proposer（60 行）。AscendNgramProposer 基于已生成文本的 n-gram 匹配生成 draft（propose/load_model/dummy_run）。

NGram proposer NPU 版（35 行）。AscendNgramProposerNPU 把 n-gram 匹配下推到设备端 Triton kernel（对应 ops/triton/spec_decode/ngram.py）。

Step3.5 MTP proposer（818 行）。AscendStep3p5MTPProposer 支持每个 MTP 层独立 KV cache 组：set_per_group_attn_metadata/_seed_graph_capture_per_group_metadata 按组设元数据与图捕获种子、_slot_mapping_buffer_for_group/_common_attn_metadata_for_group 组级缓冲与元数据、_build_step_attn_metadatas/_sample_draft_tokens_for_step 按步构建、_run_window_draft_steps 窗口式 draft 步进、_roll_window_inputs_only 滚动输入、_create_draft_vllm_config/validate_same_kv_cache_group 配置与校验。

后缀解码 proposer（37 行）。AscendSuffixDecodingProposer 基于后缀树匹配生成 draft（propose/dummy_run）。

投机解码工具（588 行）。异步漂移修正：update_num_computed_tokens_for_batch_change/correct_optimistic_seq_lens_cpu 修正异步投机解码的已计算 token 数与乐观 seq lens；SlidingWindowAdapter 为 draft 模型（EAGLE3/DFlash/DSpark）提供滑窗注意力（compute_sliding_window_block_table/apply）；patch_tensor_parallel_group 临时替换全局 TP 组；DynamicSpecScheduler 为 DFlash/DSpark 共享的动态验证调度器（token 概率更新、验证预算计算与分配）。

xlite 工具（449 行）。XModel/XModelConfig 提供安全属性设置的 xlite 运行时模型包装（向后兼容）；AttnMetadataRouter 路由不同类型注意力元数据（on_device/cu_query_lens/block_tables/seq_lens 等统一访问）；AttributeSetterMixin 安全属性混入；get_layer_weights 按 WeightGetterConfig 从层序列提取权重（支持二次展平与后处理）；get_nested_attr/get_dotted_attr 嵌套属性读取。

xlite 集成模块（886 行）。把 vLLM 模型转换为 xlite 图运行时表示：XliteModelBase 适配基座（KV cache 提取、模型配置构建、频率表预计算、NZ 张量判断、deq_scale 变换）；按架构派生：StandardXliteModel/QwenMoeXliteModel/Glm4MoeXliteModel/DeepseekV3XliteModel（MLA）/DeepseekV32XliteModel（DSA）/MiniMaxM2XliteModel；get_adapter_xlite_model 按配置选择适配器；XliteWrapper 图化包装器在 xlite 与原 runnable 路径间分派（register_kv_caches/__call__）。

xlite 模型运行器（95 行）。XliteModelRunner 覆盖 get_model/load_model 返回 xlite 包装模型、initialize_kv_cache 初始化 KV、_bypass_xlite_wrapper 判断绕过条件、_should_build_dummy_attn_metadata 判断哑元数据构建。

xlite worker（30 行）。XliteWorker 基于 NPUWorker，仅覆盖 init_device 加入 xlite 专属初始化。