mirror of
https://github.com/handsomezhuzhu/vllm-npu-plugin.git
synced 2026-02-20 11:42:30 +00:00
feat: 添加环境安装指南、验证与基准测试文档
This commit is contained in:
207
ARCHITECTURE.md
Normal file
207
ARCHITECTURE.md
Normal file
@@ -0,0 +1,207 @@
|
||||
# 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 注册插件
|
||||
Reference in New Issue
Block a user