vLLM-Ascend 全模块源码架构分析

2.2 设计问题 2：为什么需要 5 种 Attention 变体

"模型结构 × NPU 硬件特性"的笛卡尔积。MLA 的 KV cache 存 latent [num_blocks, block_size, kv_lora_rank]；DSA 叠加 compressor + indexer + SWA 三级缓存；SFA 的 indexer 是独立虚拟 AttentionLayer。每种变体的 get_kv_cache_shape() 返回不同 shape，物理分配无法统一。

2.3 设计问题 3：NPU Roofline 决定 Scheduler 策略

NPU 算力/带宽比（~200-267 FLOPS/byte）显著高于 GPU（~156-295），使得 cost(recompute) < cost(swap)。RecomputeScheduler 把 preemption 从"swap to CPU"改为"drop-and-recompute"。ProfilingChunkScheduler 用二次公式 a·x²+(2aL+b)·x=T 解出等时 chunk 大小，消除 PP 气泡。

2.4 设计问题 4：KV Cache 从 cache 进化为 Memory Tier

PD 分离场景下多对多 KV 共享需求迫使引入 Pool 路径（Ascend Store）。三级 tier：L1 HBM P2P → L2 跨节点 Pool（Mooncake/Memcache/Yuanrong 三后端）→ L3 NVMe SSD offload。与 OS cache→DRAM→swapfile 同构。

2.5 设计问题 5：MoE Expert 负载不均衡

DeepSeek-V3/R1 的 routed expert 引入负载不均衡——hot expert 所在 NPU 成为瓶颈。EPLB 在推理阶段动态调整 expert 到 NPU 的物理映射：把 hot expert 复制到多个 NPU，让 gate 路由到空闲副本。这是 Ascend 对 vLLM 生态的唯一净新增子系统。

3. 工程实现的关键挑战

3.1 310P 变体的 6659 行独立代码

5 个不可参数化的差异迫使独立子类：

• 无 Triton（Atlas 300I DUO 不支持）→ CPU numpy slot_mapping + copy_to_gpu
• RC 共享内存（host/device 共享物理内存）→ get_device_total_memory 语义不存在
• 5D KV cache（head_dim 按 16 对齐切分）→ 独立 attention 实现
• NZ 权重布局（fractal_z 格式 + transpose）→ 独立 fused_moe
• CPU RNG sampler（无 Triton）→ 独立 sample 路径

is_310p() 在全库被调用 30+ 次，形成隐式分派网——可维护性瓶颈。增加第 5 种芯片变体必须在所有分派点添加新分支。

3.2 Patch 系统的工程约束

33 个 patch 文件遵循"Less is more / 写移除计划 / 随时清理"三原则，通过 vllm_version_is() / is_310p() 条件导入实现版本隔离。

3.3 量化方案选择的工程逻辑

W4A4∧EPLB 不兼容：W4A4 权重被 pack 成 int4pack 格式，无法运行时按 expert 粒度拆分（w4a4_flatquant.py:161）。

3.4 EPLB 的跨进程设计

FlashLB 的 numba JIT 编译 + 树搜索耗时可达数十 ms，不能阻塞 forward pipeline。EplbProcess 跑在独立子进程中，通过 Manager().dict() 做跨进程数据交换。三段式状态机：Heat Collection (600 步) → Algorithm Execution (50 步) → Weight Update (逐层 D2D)。

3.5 ACL Graph 的精细工程

• GC 禁用：piecewise 模式下每层 capture 一个 graph，反复 gc 极慢
• ExternalEvent 排序：graph stream 等待 host update_stream 上的 metadata 写入完成
• weak_ref 内存优化：capture 后立即释放 output 和 workspaces 强引用
• 双后端编译：npugraph_ex（首选）vs torch._inductor + fusion_pass_compile（fallback）

4. 软件架构设计 — 6 层 Overlay 模型

4.1 六层 Overlay 架构

4.2 为什么是"extension not fork"

• NPUPlatform 继承 Platform（不复制修改）
• _fix_incompatible_config 只重置不存在的参数，不添加新字段到 VllmConfig
• register() 返回字符串路径——vLLM 主仓完全不知道 NPU 存在
• AscendConfig 挂在 additional_config 上
• worker_cls 是 vLLM 原生扩展点
• EPLB 全部通过 if self.dynamic_eplb: 条件分支注入

4.3 五种适配机制分类学

5. Platform + Device + 310P 变体

5.1 入口与注册体系

vllm_ascend/__init__.py 定义 5 个注册入口：register()（Platform）、register_connector()（KV + weight connector）、register_model_loader()（netloader/rforkloader）、register_service_profiling()、register_model()。除 register() 和 register_model() 外，其余都在调用前触发 _ensure_global_patch()。

5.2 worker_cls 三路分派

# platform.py:612-623
if is_310p():
    worker_cls = "vllm_ascend._310p.worker_310p.NPUWorker310"
elif ascend_config.xlite_graph_config.enabled:
    worker_cls = "vllm_ascend.xlite.xlite_worker.XliteWorker"
else:
    worker_cls = "vllm_ascend.worker.worker.NPUWorker"

5.3 Device Op Adaptor 策略模式

device_op.py:1964 的 get_device_adaptor() 在运行时根据芯片类型返回 BaseDeviceAdaptor / A5DeviceAdaptor / Ascend310PDeviceAdaptor。三种 adaptor 覆盖 20+ 个算子接口（attention score、MoE routing、softmax 等）。

5.4 Sleep 内存优化三层管理

SleepWakeupManager（sleep_mem_optimized.py:34）组合：

• AclGraphSleepWakeupManager：释放 attention workspace、重置 graph params、清空 graph pool
• HcclSleepWakeupManager：destroy HCCL process groups（释放通信显存）
• CaMemAllocator（camem.py）：CANN-mem pluggable allocator，按 tag 选择性 offload

6. Attention 全栈 — 5 种变体 + Context Parallel

6.1 5 种变体的唯一职责

6.2 DSA index → paged attention 数据流

hidden_states
  ├─ _mla_prolog_multistream() → q, qr (dual-stream overlap)
  ├─ _indexer_qkv_prepare() → indexer QKV
  │     └─ npu_quant_matmul + inplace_partial_rotary_mul + hadamard rotate
  ├─ compressor() → compressed_kv + compress_slot_mapping
  ├─ _indexer_qli() → topk_indices
  │     └─ npu_vllm_quant_lightning_indexer(layout_key="PA_BSND")
  │        ← 直接在 paged block 上做 score 计算
  └─ dsa_sparse_attn(q, ori_kv, sparse_count=index_topk)

6.3 Context Parallel：NPU ≠ GPU Ring-Attention

6.4 Registry / Dispatch 机制

不是 subclass polymorphism，是 registry pattern：platform.py:791 的 backend_map 根据 (use_mla, use_sparse, use_compress) 三元组查表返回 backend 类路径。CP 是 backend 的透明扩展——get_impl_cls() 内部通过 enable_cp() 开关返回 CP 变体，上层无感。

7. Scheduler + Core — 三种调度创新

7.1 三种 Scheduler 对比

7.2 三种挂载点

8. 分布式通信 + KV 传输 + EPLB

8.1 通信层架构

PyHcclCommunicator（pyhccl.py:37）是轻量 shim：ctypes 加载 libhccl.so，构造时 rank 0 生成 UniqueId、broadcast 给所有 rank。NPUCommunicator（npu_communicator.py:23）暴露 vLLM 兼容接口。all2all_manager 是 no-op stub——NPU 用 MC2 + all_gather 走 MoE 通信。

8.2 KV 传输三级 Memory Tier

8.3 EPLB 五层流水线

EplbUpdator (主进程)
  ├─ forward_before(): 取 update_info → D2D 异步启动
  ├─ forward_end(): gather load → wakeup worker
  │
  ├─ [shared_dict] → EplbProcess (子进程)
  │     └─ EplbWorker.do_update()
  │           ├─ fetch load_info
  │           ├─ policy.rebalance_experts() → 新 placement
  │           └─ compose_expert_update_info_greedy()
  │
  ├─ [Queue] → D2DExpertWeightLoader
  │     └─ generate_expert_d2d_transfer_task()
  │     └─ asyn_expert_weight_transfer()
  │
  └─ VllmEplbAdaptor
        └─ 注册 MoE layer + 管理 expert_param

8.4 FlashLB 算法（type=3，生产级）

1. 统计建模：μ + z·√σ 风险调整负载（z=0.674 对应 75% 置信度）
2. 树搜索：depth=4 层，neighbor_search width=8 局部搜索
3. LPT 部署：greedy 放到 risk 最低 device
4. Hungarian 最小化迁移：scipy.optimize.linear_sum_assignment 对齐新旧部署
5. numba JIT：核心循环 @njit(fastmath=True, cache=True)

8.5 EPLB 四策略对比

9. 编译 + ACL Graph + 70+ Fusion Pass

9.1 ACL Graph vs CUDA Graph

9.2 GraphParams 四元组

@dataclass
class GraphParams:
    events: dict[int, list[ExternalEvent]]        # 每 size 每 layer
    workspaces: dict[int, Tensor]                 # attention 间接参数
    handles: dict[int, list[NPUTaskGroupHandle]]  # task group handle
    attn_params: dict[int, list[tuple]]           # 已捕获 attn 元数据

9.3 70+ Fusion Pass 分类学

9.4 双后端编译

AscendCompiler 通过 enable_npugraph_ex 开关分派：

• npugraph_ex 路径（首选）：自带 pattern matcher，不经过 GraphFusionPassManager
• fusion_pass_compile 路径（fallback）：torch._inductor + GraphFusionPassManager

BasePattern.register() 同时向两者注册，保证 pass 在两个后端都能匹配。

10. 模型支持 + 量化 + 自定义算子 + Patch + Xlite

10.1 模型注册三目录枚举

10.2 Xlite — 图运行时而非 edge runtime

Xlite 是华为 openEuler GVirt 项目下的图编译运行时，作为 ACL Graph 的替代路径。三层结构：

• XliteModel（抽象基类，子类按架构注册到 _architecture_strategy_map）
• XliteWrapper（持有 C++ Runtime，dispatch 在 xlite graph 和原始 runnable 之间）
• XliteModelRunner / XliteWorker（替换 NPU 默认 runner）

10.3 量化方案选择逻辑

AscendModelSlimConfig.get_quant_method()（modelslim_config.py:637）是核心路由。NZ format 是硬约束（ACL_FORMAT_FRACTRAL_NZ），msModelSlim 生态兼容（三种布局），MXFP 系列是 OCP 标准落地。

10.4 MoE 通信四维度动态路由

select_moe_comm_method(num_tokens, vllm_config):
  A2 + EP → MC2 (tokens ≤ capacity) / AllGather
  A3 + EP → FUSED_MC2 (w8a8 + small EP) / MC2 / AlltoAll
  A5 + EP → MC2 / AllGather / AlltoAll
  310P    → AllGather
  no EP   → AllGather

10.5 Patch 分类学

10.6 Spec Decode 在 NPU 上的复杂性

AscendSpecDecodeBaseProposer（2156 行）承载三大复杂性：

• TP-patch：draft/target 不同 TP size 时 patch TP group
• ACL Graph：GLM 系列不支持 draft graph mode，FULL mode 需 _pad_query_start_loc_for_fia
• PCP/DP 集成：PCP 需独立 block table 拷贝，DP 需 allgather + reduce

11. 横向架构评估与洞察

11.1 "变化速率不同"原则在 vllm-ascend 的体现

11.2 最脆弱的架构决策

11.3 最有价值的架构决策

11.4 与 vLLM 统一报告的关联

本报告与 vllm_architecture_unified.html（vLLM upstream 12 章分析）互补：

• 统一报告回答"vLLM 为什么这样设计"（软件架构第一性原理）
• 本报告回答"vLLM-Ascend 为什么需要 overlay"（硬件差异 + 工程约束）
• 统一报告的 §7 (Ascend Overlay) 和 §9 (Playbook) 与本报告 §4 重叠，但本报告提供了更深的源码证据

12. References & File Index

12.1 关键文件全索引

12.2 外部引用

• vllm-project/vllm-ascend — 代码仓库
• Ascend 官方文档
• Introducing vLLM Hardware Plugin (2025/05)
• RFC: Hardware Pluggable (#11162)
• vllm_architecture_unified.html — vLLM upstream 12 章统一报告
• hbm_index_architecture.html — HBM 索引专题

12.3 Agent 报告原件