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 注册：

```python
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 注册插件