vllm-npu-plugin/ARCHITECTURE.md

vllm-npu-plugin 功能说明

一、项目背景

本项目将华为昇腾 NPU 的推理优化适配到 vLLM v0.11.0，采用插件化架构，无需修改 vLLM 主仓库代码。

演进路径

vllm_0.2.7_ascend（旧方案）    →    vllm-npu-plugin（当前方案）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

旧方案：直接 fork vLLM 0.2.7，
       全局替换 cuda → npu，
       侵入式修改核心代码

新方案：基于 vLLM V1 的 Hardware Pluggable 接口，
       独立 pip 包，通过 entry_points 注册，
       与 vLLM 主线解耦

---

二、旧方案（vllm_0.2.7_ascend）做了什么

vllm_0.2.7_ascend 是对 vLLM v0.2.7 的侵入式 fork，核心改动包括：

2.1 设备层替换

原始（CUDA）	替换后（NPU）
torch.cuda.*	torch.npu.*
device="cuda"	device="npu"
NCCL 通信后端	HCCL 通信后端
torch.cuda.CUDAGraph	torch_npu.npu.Graph

2.2 算子替换

所有 vLLM 的 CUDA C++ kernel 被替换为 torch_npu 提供的 NPU 原生算子：

功能	CUDA kernel	NPU 替换
RMSNorm	torch.ops._C.rms_norm	torch_npu.npu_rms_norm()
Fused Add+RMSNorm	torch.ops._C.fused_add_rms_norm	torch_npu.npu_add_rms_norm()
Rotary Embedding	torch.ops._C.rotary_embedding	torch_npu._npu_rotary_embedding()
SwiGLU 激活	CUDA silu_and_mul	torch_npu.npu_swiglu()
PagedAttention	CUDA paged_attention kernel	torch_npu._npu_paged_attention_splitfuse()
KV Cache 写入	CUDA reshape_and_cache	torch_npu._npu_reshape_and_cache()

2.3 自定义 Attention 后端

新增 AscendAttentionBackend，替代 FlashAttention/xFormers：

• 使用 torch_npu._npu_paged_attention_splitfuse() 做 prefill + decode
• 自行构造 attention mask（prefill 下三角，decode 全1）
• 管理 block table、sequence length 等元数据

2.4 旧方案的问题

• 无法升级：所有改动散布在 vLLM 核心代码中，无法跟随上游更新
• 代码质量：残留大量调试 print、注释掉的代码、未完成的 TODO
• 功能有限：仅单机推理，Ray 分布式被注释掉
• 架构过时：基于 vLLM V0 引擎

---

三、新方案（vllm-npu-plugin）做了什么

新方案基于社区开源的 vllm-ascend 插件架构，迁移到 vLLM v0.11.0 的 V1 引擎。

3.1 插件化架构

vllm (v0.11.0)                    vllm-npu-plugin
┌─────────────────────┐           ┌─────────────────────────┐
│  Platform Interface │◄──────────│  NPUPlatform            │
│  (pluggable)        │  register │  ├── set_device()       │
│                     │           │  ├── mem_get_info()      │
│  ModelRegistry      │◄──────────│  ├── check_config()     │
│  (pluggable)        │  register │  └── ...                │
│                     │           │                         │
│  KVConnectorFactory │◄──────────│  Ascend 优化模型        │
│  (pluggable)        │  register │  ├── Qwen2VL           │
│                     │           │  ├── DeepseekV3         │
│                     │           │  └── ...                │
└─────────────────────┘           │                         │
                                  │  NPUModelRunner         │
                                  │  NPUWorker              │
                                  │  AscendAttentionBackend │
                                  │  Custom Ops             │
                                  │  Quantization           │
                                  │  Patch System           │
                                  └─────────────────────────┘

通过 setup.py 的 entry_points 注册：

entry_points={
    "vllm.platform_plugins": ["npu = vllm_npu:register"],
    "vllm.general_plugins": [
        "npu_enhanced_model = vllm_npu:register_model",
        "npu_kv_connector = vllm_npu:register_connector",
    ],
}

3.2 主要功能模块

Attention 后端（3 种）

后端	适用场景
AscendAttentionBackend	通用注意力（Qwen、LLaMA 等标准模型）
AscendMLABackend	DeepSeek 系列的 Multi-Latent Attention
AscendSFABackend	稀疏 Flash Attention（DeepSeek V3.2 等）

自定义算子

• AscendSiluAndMul / AscendQuickGELU — 激活函数
• AscendRotaryEmbedding — 旋转位置编码
• RMSNorm / LayerNorm — 归一化层
• AscendUnquantizedLinearMethod — 线性层
• FusedMoE — MoE 专家混合层（含 MC2 通信优化）

Worker 与 Model Runner

• NPUWorker — NPU 设备管理、HCCL 通信初始化
• NPUModelRunner — 模型推理执行器，支持 chunked prefill
• ATB 扩展注册 + warmup 机制
• ACL Graph 捕获（等价于 CUDA Graph 的 NPU 实现）

量化支持

方案	说明
W8A8	INT8 权重 + INT8 激活，静态量化
W8A8_Dynamic	动态 per-channel/per-tensor 量化
W4A8_Dynamic	INT4 权重 + INT8 激活
W4A4_FlatQuant	Kronecker 量化

分布式

• HCCL 通信后端（替代 NCCL）
• Tensor Parallel / Expert Parallel
• EPLB 动态专家负载均衡
• PD 分离（Prefill-Decode Disaggregation）

高级特性

• Torchair 图编译 — NPU 图模式编译优化，缓存编译结果
• MultiStream 重叠 — Attention 和 FFN 计算/通信流水线并行
• 推测解码 — NGram / Eagle / DeepSeek MTP
• LoRA — NPU 上的 Punica LoRA 实现
• Sleep Mode — 设备内存动态释放

Patch 系统

通过运行时 monkey-patch 修复 vLLM 主线与 NPU 的兼容问题：

• 每个 patch 标注了对应的上游 PR 和计划移除时间
• 分为平台级 patch（注册时应用）和 Worker 级 patch（初始化时应用）

3.3 支持的模型

已注册优化版本的模型：

模型	类型
Qwen2.5-7B-Instruct	文本 LLM（已验证 ✅）
Qwen2VL / Qwen2.5_VL	视觉语言模型
Qwen3VL / Qwen3VLMoe	MoE 视觉语言模型
DeepseekV3.2	大规模 MoE 模型
PanguProMoE	华为盘古 MoE

未注册优化版本的标准模型（如 LLaMA、Baichuan 等）也可以运行，只是走通用代码路径。

---

四、新旧方案对比

维度	旧方案（0.2.7 fork）	新方案（npu-plugin）
架构	侵入式 fork	独立插件，entry_points
vLLM 版本	锁定 0.2.7	跟随 0.11.0（V1 引擎）
可升级性	❌ 无法跟随上游	✅ 独立升级
Attention	单一 AscendBackend	3 种后端（通用/MLA/SFA）
算子	手动替换 ~6 个	完整算子库 + ATB 扩展
量化	无	W8A8/W4A8/W4A4
分布式	单机（Ray 被注释）	TP/EP/EPLB/PD分离
图优化	基础 NPU Graph	Torchair 图编译 + ACL Graph
推测解码	无	NGram/Eagle/MTP
MoE 支持	无	MC2 通信 + 动态负载均衡
多模态	无	VL、Omni 模型支持

---

五、代码修改记录

在将 vllm-ascend 代码适配为 vllm-npu-plugin 的过程中，做了以下关键修改：

1. 全局命名空间替换：vllm_ascend → vllm_npu（93 个文件）
2. utils.py：
   • is_310p() — 延迟初始化，避免 fork 时 NPU 冲突
   • sleep_mode_enabled() — 异常安全的 fallback
   • vllm_version_is() — 兼容开发版本号
3. models/layers/mla.py：用 try/except 替代版本号检查，兼容 dev 版本
4. worker/worker_v1.py：将 init_ascend_soc_version() 从 __init__ 移到 init_device()，解决多进程 NPU 初始化冲突
5. setup.py：配置 entry_points 注册插件