vLLM Ascend · Worker 执行器模块 API 参考

KV cache 块表管理（458 行）。BlockTable 把每个请求的逻辑块序列映射到物理块：行级操作（append/add/clear/move/swap row）、slot mapping 计算（含 draft 模式与 DCP 变体 _compute_dcp_slot_mapping）、提交（commit_block_table 把 host 表同步到 device）、物理/逻辑块转换，并提供 device tensor/CPU tensor/numpy 三种视图供不同消费者使用；MultiGroupBlockTable 为多个 KV cache 组（如 MLA 主缓存 + indexer 缓存）各维护一张 BlockTable 并统一转发行操作。

Decode Context Parallel（DCP）工具集（696 行）。DCPManager 负责按 DCP 切分 decode 批次的元数据与可复用缓冲：classify_decode_request_mask 分类可迁移请求、init_batch_info 初始化批信息、generate_dcp_metadata 生成本地元数据、_get_dcp_local_seq_lens 按 interleave 布局计算本地 KV 长度；投机解码支持：prepare_spec_decode_first_pass_inputs（首趟 draft 的 DCP 元数据）、prepare_spec_decode_mtp_drafting_inputs（MTP draft 输入与 slot）、rebuild_async_spec_decode_inputs（异步调度下重建投机输入）、generate_mtp_attention_mask_for_decode（MTP decode 掩码）。DCPSpecDecodeMTPInputs/DCPSpecDecodeFirstPassInputs/DCPAsyncSpecDecodeRebuildResult 为配套设备侧数据类。

视觉编码器的 ACL graph 支持（374 行）。EncoderGraphParams 按 token budget 键控的图参数（镜像 LLM 侧 GraphParams）；EncoderForwardContext 携带重放时的运行标志与 host 侧 FIA 参数（每次重放必须传入长度）；EncoderAclGraphManager 把编码器的 capture/replay 挂到 Ascend FIA graph-task 基础设施上（按 budget 分别捕获/执行）；update_encoder_graph_params 在 graph 重放时重绑 fused infer attention 的 host 张量；maybe_compute_actual_seq_lengths 把 cu_seqlens 转成 FIA 需要的 actual_seq_lengths。

V1 模型运行器 NPUModelRunner（5368 行，全仓最大文件）。继承 GPUModelRunner 并适配 NPU：设备属性初始化、drafter（投机起草器）装配、Eagle3 辅助层解析、ACL graph 启用判定、DP rank 间元数据同步、PD 分离架构 prefill worker 判定、PP 场景采样 token 后处理；graph_capture 上下文管理器包围图捕获过程。模块级工具：_post_process_cudagraph_mode 在 DP ranks 间取最小 cudagraph 模式保证一致、_get_gpu_model_runner_module_name 定位 MRO 中的 GPUModelRunner 模块、_replace_gpu_model_runner_function_wrapper 对其函数做 NPU 替换包装、update_pass_config 更新编译 pass 配置。

NPUInputBatch（258 行）：V1 运行器的输入批次扩展，在 vLLM InputBatch 基础上增加 NPU 专用的批状态字段，构造时按 NPU 需求初始化。

KV 块清零工具（184 行）。AscendKVBlockZeroer 用一个 Triton kernel（_zero_kv_blocks_kernel）单次 launch 清零多个 KV cache 块的全部段（segments）：init_meta 预计算地址元数据，zero_block_ids 按块 ID 列表批量清零，用于抢占/释放时快速复位缓存，避免逐块循环。

V2 ACL graph 管理工具（299 行）。ModelAclGraphManager 是 Ascend NPU 的 ACL 图管理器：init_breakable_cg_runner 初始化可中断图运行器、run_fullgraph 全图执行、capture 按桶捕获；_prepare_pcp_inputs_to_capture 以与重放一致的 PCP 本地布局构建捕获输入；collect_sorted_captured_token_sizes 收集每张图实际捕获的 token 数；ModelWithContext 包装模型注入 forward context（含 compute_logits/draft logits/Markov embed 等接口转发）；model_capture_wrapper 在投机解码捕获期间临时替换 speculator 的模型。

V2 运行器注意力工具箱（936 行）。get_kv_cache_spec 构建 Ascend 专属 KV cache 规格；build_attn_metadata/build_attn_state 构建注意力元数据与执行状态；DSV4 布局支持：_adjust_dsv4_kv_layout 调整 KV 布局、_view_dsv4_cache 不做 MLA K/V 切分直接建 DSA 缓存视图、_allocate_sparse_c8_indexer_tensors 从单一对齐 int8 raw 分配中切出 dsa_k 与 dsa_k_scale；_allocate_kv_cache 按配置初始化 KV 缓存大缓冲；_reshape_mamba_kv_cache 为 Mamba 混合模型建连续 per-state 视图；build_attn_metadata_wrapper/build_draft_attn_metadata_factory 为 draft 块包装元数据构建（转发旋转位置编码）。

AscendBlockTables（61 行）：V2 运行器的块表集合，按 KV cache 组组织各请求的块表，是 v2/block_table.py 对 V1 BlockTable 的轻量替换。

专家并行负载均衡（EPLB）控制器 V2（97 行）。AscendEPLBController 在标准 EPLB 状态上叠加按阶段过滤的负载收集：is_eplad_load_collection_phase_matched 判断当前批次是否属于配置的收集阶段（prefill/decode），prepare_load/set_batch_phase/prepare_forward/setup_from_mapping 管理负载统计与专家映射应用；_unwrap_moe 解包获取真实 MoE 模块。

V2 输入批（142 行）。AscendInputBatch 在 vLLM V2 InputBatch 基础上增加 NPU 字段；AscendInputBuffers 预分配输入缓冲（positions/seq_lens 等 device 张量），减少每步分配开销。

V2 模型运行器 NPUModelRunner（995 行）。全新架构的执行核心：execute_model 驱动每步推理、sample_tokens/sample 采样、profile_run/_dummy_run 性能剖析与形状探测、initialize_kv_cache 初始化 KV 缓存、_lmhead_tp_max_num_logits 计算 LM head TP 分片下的最大 logits 数、_pad_query_start_loc_for_fia 为 FIA 填充 query start loc；pcp_manager_cls 集成 AscendPCPManager，_use_ascend_pcp_manager_for_vllm_0271 兼容 vLLM 0.27.1 的 legacy PCP builder；graph_manager_wrapper 上下文用于替换图管理器。

V2 模型状态工厂（71 行）。init_asecnd_model_state 按模型类型/配置选择并实例化对应的 AscendModelState（默认或 Mamba 混合），把模型、encoder cache、设备绑定到状态对象。

默认模型状态 AscendModelState（106 行）：V2 运行器中封装模型前向的注意力准备逻辑（prepare_attn 构建并注入注意力元数据），是大多数模型的标准状态。

Mamba 混合模型状态 AscendMambaHybridModelState（106 行）：在默认状态基础上，为 Mamba-Attention 混合架构定制 prepare_attn——注意力元数据构建需区分 Mamba 层与注意力层的 KV 组。

Prefill Context Parallel（PCP）管理器 V2（218 行）。AscendPCPManager 在 PCP 各 rank 间切分 prefill 批次：validate_config 校验配置、partition_batch 做批次切分、prepare_slot_mappings 生成本地 KV 写入的 slot 映射、build_attention_context 产出规范全局视图 AscendPCPAttentionContext（供注意力后端构建本地元数据与全局缓存写视图，如 DSA-PCP 的 from_local_metadata）。

V2 流水线并行工具（196 行）。解决投机解码 × PP 的兼容：SpecPPSupport 描述每种投机方法在 PP 下的能力、resolve_spec_pp_support 按配置解析、bypass_upstream_spec_pp_guard 让上游 runner 以 PP=1 初始化绕过其 Spec+PP 守卫、restore_pp_after_upstream_init 再恢复真实 PP 状态；PPTransportDataType 定义 PP rank 间经 IntermediateTensors 传输的数据类型，make_empty_intermediate_tensors 包装张量工厂附加接收缓冲，get/add_pp_transport_tensors/buffers 管理按类型的传输张量与预分配接收缓冲。

V2 采样的 top-k/top-p 过滤入口（14 行）：apply_top_k_top_p_npu 对 logits 应用 NPU 实现的 top-k/top-p 截断，是 vLLM 采样管线中该步骤的 Ascend 替换点。

违禁词过滤（185 行）。Triton kernel _bad_words_kernel 按请求展开索引查其已生成 token 序列并屏蔽命中的违禁词末 token；apply_bad_words 组织输入（违禁词 token ID、偏移、数量、全 token 序列）并 launch kernel，逐请求把违禁续写位置的 logits 置 -inf。

Gumbel 采样（219 行）。apply_temperature 用 Triton kernel 按请求温度缩放 logits；gumbel_sample 先做温度处理，再用 _gumbel_sample_kernel 对处理后的 logits 做 Gumbel 扰动并取 argmax（支持种子与位置偏移保证可复现），是解码期随机采样的 NPU 路径。

logprob 计算（169 行）。compute_token_logprobs 用 _topk_log_softmax_kernel 对采样 token 计算对数概率；compute_topk_logprobs 用 _ranks_kernel 等 kernel 计算每个请求 top-k 候选的 logprob 与 token ID（写入预分配的 state 缓冲），服务 logprobs 请求参数。

min_p 过滤（91 行）。apply_min_p 用 Triton kernel 对每请求计算概率阈值（最大概率×min_p），低于阈值的 logits 置 -inf，避免逐请求 host 循环。

采样惩罚（225 行）。apply_penalties 用 Triton kernel 应用重复惩罚（repetition_penalty）与频率惩罚（frequency_penalty）：按已生成 token 计数调整 logits；bincount kernel 统计 prompt+生成 token 的出现次数（prompt 与生成段分别掩码），为惩罚计算提供计数输入。

V2 投机解码入口（58 行）。init_speculator 覆盖 vLLM GPU 版本的 speculator 工厂：按 vllm_config 中的投机方法（Eagle/MTP/DFlash/DSpark/自回归等）实例化对应的 Ascend speculator 并完成设备初始化。

自回归投机解码的 ACL graph 管理器（179 行）。AutoRegressiveAclGraphManager 管理draft 模型多步解码图的捕获（capture）与全图执行（run_fullgraph），按 token 数分桶以覆盖 draft 循环的不同形状。

自回归投机解码共享循环（507 行）。AscendAutoRegressiveSpeculator 是 AscendEagle/AscendMTPSpeculator 共用的 NPU 投机循环：_create_draft_vllm_config 构建 draft 模型配置、propose 驱动 propose-verify 流程、_prefill 处理 draft prefill、_multi_step_decode 多步 draft 解码、_build_draft_attn_metadata 系列构建/更新 draft 注意力元数据（含 decode 期增量更新与 seq lens CPU 计算）；init_cudagraph_manager 接 ACL graph；torch_gather_wrapper 上下文替换 torch.gather 以适配 NPU 算子行为差异。

DFlash 投机解码的 ACL graph 管理器（122 行）。DFlashAclGraphManager 管理 DFlash draft 路径的图捕获与全图重放，参数与桶策略对齐 DFlash 的分组卷积候选生成流程。

DFlash 投机解码器 AscendDFlashSpeculator（452 行）：基于分组卷积多 token 预测的投机路径。propose 驱动候选生成与验证；build_draft_attn_metadatas/_update_draft_attn_metadata 管理 draft 注意力元数据；init_cudagraph_manager 接入 DFlashAclGraphManager；set_attn 绑定目标模型注意力后端。

DSpark 投机解码器 AscendDSparkSpeculator（196 行）：基于 Markov/置信度头的 draft 路径。load_draft_model 加载 draft 权重、propose 生成候选序列、build_draft_attn_metadatas/_update_draft_attn_metadata 维护 draft 元数据、init_cudagraph_manager 接图管理器。

Eagle 投机解码器 AscendEagleSpeculator（44 行）：复用 AscendAutoRegressiveSpeculator 的完整 NPU 循环，仅定制 _create_draft_vllm_config 以加载 Eagle 风格 draft 模型配置。

拒绝采样工具（507 行）。rejection_sample 实现投机解码的验证采样：对目标/草稿 logits 逐位置比较，接受概率内的 draft token、拒绝处从目标分布重采样；配套 Triton kernel：_npu_gumbel_block_argmax（分块 Gumbel argmax）、_resample_kernel（重采样）、_probabilistic_rejection_kernel（概率拒绝判定），全部在设备端完成避免 host 往返。

V2 请求状态 AscendRequestState（71 行）：在 vLLM 请求状态上扩展 NPU 字段，add_request 完成请求级状态初始化，供运行器跟踪每个请求的执行上下文。

V2 运行器上下文包装（61 行）。提供三个上下文管理器/函数：torch_cuda_wrapper 把 torch.cuda 调用映射到 torch.npu、communicator_switch 切换通信器实现、torch_npu_graph_wrapper 适配 graph 相关 API，是 V2 运行器 GPU→NPU 兼容层的组成部分。

NPUWorker（1152 行）：V1 worker 本体，vLLM Worker 的 NPU 实现。设备生命周期：init_device/_init_device 初始化 NPU 与设备属性、initialize_cache 初始化 KV 缓存、sleep/wake_up 睡眠唤醒（释放/恢复显存）；权重传输引擎：_check_weight_transfer_engine/init_weight_transfer_engine/start_weight_update/update_weights/finish_weight_update 支持训练侧增量权重拉取更新；_apply_kv_offload_decode_memory_constraints 应用 KV offload 场景的 decode 内存约束；uninstall_static_kernel 卸载静态 kernel；parse_text_output 解析设备端文本输出。