zzh/vllm-npu-plugin
1
0
Fork 0
mirror of https://github.com/handsomezhuzhu/vllm-npu-plugin.git synced 2026-02-20 11:42:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: 添加环境安装指南、验证与基准测试文档

Browse Source
This commit is contained in:
handsomezhuzhu
2026-02-11 00:13:26 +08:00
parent ae10ce68f0
commit c00c47a5b2
3 changed files with 635 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

207
ARCHITECTURE.md Normal file
View 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 注册插件

253
BENCHMARK.md Normal file
View File

@@ -0,0 +1,253 @@
# vllm-npu-plugin 验证与基准测试指南
## 一、功能验证（先确认能正常工作）
### 1.1 离线推理测试
```bash
cd /workspace/mnt/vllm_ascend/vllm-npu-plugin
python -c "
from vllm import LLM
llm = LLM(
model='/workspace/mnt/vllm_ascend/Qwen2.5-7B-Instruct',
dtype='float16',
trust_remote_code=True,
)
outputs = llm.generate(['你好，请简单介绍一下自己'])
for out in outputs:
print(out.outputs[0].text)
"
```
预期：模型正常加载，输出合理的中文回复。✅ 已验证通过。
### 1.2 OpenAI API 服务测试
```bash
# 终端 1：启动服务
python -m vllm.entrypoints.openai.api_server \
--model /workspace/mnt/vllm_ascend/Qwen2.5-7B-Instruct \
--dtype float16 \
--trust-remote-code \
--host 0.0.0.0 \
--port 8000
# 终端 2：发送请求
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "/workspace/mnt/vllm_ascend/Qwen2.5-7B-Instruct",
"messages": [{"role": "user", "content": "什么是大语言模型？"}],
"max_tokens": 256
}'
```
### 1.3 流式输出测试
```bash
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "/workspace/mnt/vllm_ascend/Qwen2.5-7B-Instruct",
"messages": [{"role": "user", "content": "用Python写一个快速排序"}],
"max_tokens": 512,
"stream": true
}'
```
---
## 二、性能基准测试
vLLM v0.11.0 内置了基准测试工具，通过 `vllm bench` 命令调用。
### 2.1 延迟测试（Latency）
测量单次请求从输入到输出的端到端延迟：
```bash
vllm bench latency \
--model /workspace/mnt/vllm_ascend/Qwen2.5-7B-Instruct \
--dtype float16 \
--trust-remote-code \
--input-len 128 \
--output-len 128 \
--batch-size 1 \
--num-iters 10
```
**关注指标**：
- `avg latency` — 平均延迟（秒）
- `p99 latency` — P99 延迟
### 2.2 吞吐量测试（Throughput）
测量批量处理的总吞吐量：
```bash
vllm bench throughput \
--model /workspace/mnt/vllm_ascend/Qwen2.5-7B-Instruct \
--dtype float16 \
--trust-remote-code \
--input-len 256 \
--output-len 256 \
--num-prompts 100
```
**关注指标**：
- `Throughput: X.XX requests/s`
- `Throughput: X.XX tokens/s`（输出 tokens/秒）
### 2.3 在线服务测试（Serving Benchmark）
模拟真实在线服务场景（需先启动 API 服务）：
```bash
# 终端 1：启动服务（同 1.2）
# 终端 2：运行压测
vllm bench serve \
--model /workspace/mnt/vllm_ascend/Qwen2.5-7B-Instruct \
--base-url http://localhost:8000 \
--dataset-name random \
--random-input-len 256 \
--random-output-len 128 \
--num-prompts 200 \
--request-rate 5
```
**关注指标**：
- `Request throughput` — 请求吞吐 (req/s)
- `Output token throughput` — 输出 token 吞吐 (tok/s)
- `TTFT (Time to First Token)` — 首 token 延迟（反映 prefill 性能）
- `TPOT (Time per Output Token)` — 每 token 生成时间（反映 decode 性能）
- `ITL (Inter-Token Latency)` — token 间延迟
### 2.4 不同批量大小对比
```bash
# 批量 1（延迟优先）
vllm bench latency --model /workspace/mnt/vllm_ascend/Qwen2.5-7B-Instruct \
--dtype float16 --trust-remote-code --input-len 128 --output-len 128 --batch-size 1
# 批量 8（吞吐优先）
vllm bench latency --model /workspace/mnt/vllm_ascend/Qwen2.5-7B-Instruct \
--dtype float16 --trust-remote-code --input-len 128 --output-len 128 --batch-size 8
# 批量 32（高吞吐）
vllm bench latency --model /workspace/mnt/vllm_ascend/Qwen2.5-7B-Instruct \
--dtype float16 --trust-remote-code --input-len 128 --output-len 128 --batch-size 32
```
---
## 三、建议的测试矩阵
### 3.1 基础性能摸底
| 测试项 | input_len | output_len | batch_size | 目的 |
|--------|-----------|------------|------------|------|
| 单请求延迟 | 128 | 128 | 1 | 基线延迟 |
| 小批量延迟 | 128 | 128 | 8 | 批量效率 |
| 长输入 | 1024 | 128 | 1 | prefill 性能 |
| 长输出 | 128 | 1024 | 1 | decode 性能 |
| 高吞吐 | 256 | 256 | 32 | 最大吞吐 |
### 3.2 和老方案对比（如果老环境还在）
如果旧的 vllm_0.2.7_ascend 环境还可用，可以用相同参数对比：
```bash
# 在旧环境中运行（0.2.7 使用旧的脚本）
cd /path/to/vllm_0.2.7_ascend
python benchmarks/benchmark_latency.py \
--model /workspace/mnt/vllm_ascend/Qwen2.5-7B-Instruct \
--dtype float16 --input-len 128 --output-len 128 --batch-size 1
# 在新环境中运行
vllm bench latency \
--model /workspace/mnt/vllm_ascend/Qwen2.5-7B-Instruct \
--dtype float16 --trust-remote-code --input-len 128 --output-len 128 --batch-size 1
```
> **注意**：由于 vLLM 从 0.2.7 → 0.11.0 本身有大量架构升级（V1 引擎、Continuous Batching 改进等），
> 新方案在吞吐量方面应该有显著优势，尤其是并发场景。
### 3.3 稳定性测试
```bash
# 长时间压测（600 秒 = 10 分钟）
vllm bench serve \
--model /workspace/mnt/vllm_ascend/Qwen2.5-7B-Instruct \
--base-url http://localhost:8000 \
--dataset-name random \
--random-input-len 256 \
--random-output-len 256 \
--num-prompts 1000 \
--request-rate 10
```
关注：
- 是否有请求失败
- 延迟是否随时间增长（内存泄漏）
- NPU 显存是否稳定（`npu-smi info` 监控）
---
## 四、监控工具
```bash
# 实时监控 NPU 使用率和显存
watch -n 1 npu-smi info
# 查看 NPU 详细信息
npu-smi info -t usages -i 0
# Python 中获取显存信息
python -c "
import torch
import torch_npu
print(f'Total: {torch.npu.get_device_properties(0).total_memory / 1024**3:.1f} GB')
print(f'Allocated: {torch.npu.memory_allocated(0) / 1024**3:.1f} GB')
print(f'Cached: {torch.npu.memory_reserved(0) / 1024**3:.1f} GB')
"
```
---
## 五、下一步工作建议
### 短期（验证阶段）
1. ✅ 跑通基础推理（已完成）
2. 🔲 运行 latency benchmark，记录基线数据
3. 🔲 运行 throughput benchmark，评估吞吐
4. 🔲 运行 serving benchmark，评估在线服务性能
5. 🔲 如有旧环境，做新旧对比
### 中期（优化阶段）
6. 🔲 测试量化模型（W8A8），对比精度和性能
7. 🔲 测试 Torchair 图编译模式是否可用
8. 🔲 测试 chunked prefill 对长文本的效果
9. 🔲 测试更大模型（如 Qwen2.5-72B，需多卡 TP）
### 长期（生产部署）
10. 🔲 稳定性长跑测试（24h+）
11. 🔲 多卡 Tensor Parallel 验证
12. 🔲 集成到业务 API 网关
13. 🔲 编译 C++ 扩展（`vllm_npu_C`）获取完整性能
---
## 六、参考命令速查
```bash
# 延迟测试
vllm bench latency --model <MODEL> --dtype float16 --trust-remote-code --input-len 128 --output-len 128 --batch-size 1
# 吞吐测试
vllm bench throughput --model <MODEL> --dtype float16 --trust-remote-code --input-len 256 --output-len 256 --num-prompts 100
# 服务压测（需先启动 API 服务器）
vllm bench serve --model <MODEL> --base-url http://localhost:8000 --dataset-name random --random-input-len 256 --random-output-len 128 --num-prompts 200 --request-rate 5
```

175
INSTALL.md Normal file
View File

@@ -0,0 +1,175 @@
# vllm-npu-plugin 环境安装指南
## 一、环境概览
| 组件 | 版本要求 | 说明 |
|------|---------|------|
| **OS** | Linux aarch64 | 昇腾 NPU 服务器 |
| **Python** | ≥ 3.9（推荐 3.11） | 当前验证版本 3.11.10 |
| **NPU 驱动** | Ascend HDK 驱动 | 需提前安装好 |
| **CANN Toolkit** | **8.3.RC2** | 昇腾计算架构核心套件 |
| **NNAL (ATB)** | **8.3.RC2** | 神经网络加速库，**必须与 CANN 同版本** |
| **PyTorch** | 2.7.1 | CPU 版本即可（torch_npu 提供 NPU 支持） |
| **torch_npu** | 2.7.1 | 华为 NPU 版 PyTorch 后端 |
| **vLLM** | 0.11.0 分支 | 自定义分支 `feat/ascend-npu-adapt-v0.11.0` |
> **核心原则：CANN、NNAL、torch_npu 三者的大版本必须匹配。**
> 例如 CANN 8.3.RC2 + NNAL 8.3.RC2 + 对应 torch_npu。版本不匹配会导致 ATB 算子（如 LinearOperation）初始化失败。
---
## 二、安装步骤
### Step 1：安装 CANN Toolkit 8.3.RC2
```bash
# 下载（从昇腾社区 https://www.hiascend.com/software/cann ）
wget <CANN_8.3.RC2_URL> -O Ascend-cann-toolkit_8.3.RC2_linux-aarch64.run
# 安装
chmod +x Ascend-cann-toolkit_8.3.RC2_linux-aarch64.run
./Ascend-cann-toolkit_8.3.RC2_linux-aarch64.run --install
# 设置环境变量
source /usr/local/Ascend/ascend-toolkit/set_env.sh
```
### Step 2：安装 NNAL 8.3.RC2（关键！）
```bash
# 下载（从昇腾社区 https://www.hiascend.com/software/nnal ）
wget <NNAL_8.3.RC2_URL> -O Ascend-cann-nnal_8.3.RC2_linux-aarch64.run
# 安装
chmod +x Ascend-cann-nnal_8.3.RC2_linux-aarch64.run
./Ascend-cann-nnal_8.3.RC2_linux-aarch64.run --install
# 设置环境变量（大模型场景用 atb）
source /usr/local/Ascend/nnal/atb/set_env.sh
```
> ⚠️ **常见坑**：如果 CANN 升级了但 NNAL 没有升级，会导致 `LinearOperation setup failed!` 错误。
> 验证方法：`ls /usr/local/Ascend/nnal/atb/` 查看版本目录，确保与 CANN 一致。
### Step 3：安装 PyTorch + torch_npu
```bash
# 安装 PyTorch 2.7.1
pip install torch==2.7.1
# 安装 torch_npu（必须与 PyTorch 版本对应）
pip install torch_npu==2.7.1
```
### Step 4：安装 vLLM（自定义分支）
```bash
cd /workspace/mnt/vllm_ascend/vllm
git checkout feat/ascend-npu-adapt-v0.11.0
pip install -e .
```
### Step 5：安装 vllm-npu-plugin
```bash
cd /workspace/mnt/vllm_ascend/vllm-npu-plugin
pip install -e .
```
---
## 三、环境变量配置
在 `~/.bashrc` 或启动脚本中添加：
```bash
# CANN Toolkit
source /usr/local/Ascend/ascend-toolkit/set_env.sh
# NNAL / ATB（大模型场景）
source /usr/local/Ascend/nnal/atb/set_env.sh
# 指定可见 NPU 设备（单卡示例）
export ASCEND_VISIBLE_DEVICES=0
# ATB 性能调优（可选，已在容器中默认设置）
export ATB_OPERATION_EXECUTE_ASYNC=1
export ATB_CONTEXT_HOSTTILING_RING=1
export ATB_CONTEXT_HOSTTILING_SIZE=102400
export ATB_OPSRUNNER_KERNEL_CACHE_LOCAL_COUNT=1
export ATB_OPSRUNNER_KERNEL_CACHE_GLOABL_COUNT=16
export ATB_WORKSPACE_MEM_ALLOC_GLOBAL=1
export ATB_USE_TILING_COPY_STREAM=0
```
---
## 四、安装验证
```bash
# 1. 验证 CANN 版本
cat /usr/local/Ascend/ascend-toolkit/latest/version.cfg
# 2. 验证 NNAL/ATB 版本（应该只有当前版本）
ls /usr/local/Ascend/nnal/atb/
# 3. 验证 torch_npu
python -c "import torch_npu; print(torch_npu.__version__)"
# 4. 验证 NPU 可用
python -c "
import torch
import torch_npu
print('NPU available:', torch.npu.is_available())
print('NPU count:', torch.npu.device_count())
print('NPU name:', torch.npu.get_device_name(0))
"
# 5. 验证 ATB 算子（关键！）
python -c "
import torch
import torch_npu
x = torch.randn(2, 4, dtype=torch.float16).npu()
w = torch.randn(4, 4, dtype=torch.float16).npu()
c = torch.zeros(2, 4, dtype=torch.float16).npu()
torch_npu._npu_matmul_add_fp32(x, w, c)
print('ATB matmul OK')
"
# 6. 验证插件加载
python -c "
import vllm
from vllm.platforms import current_platform
print('Platform:', current_platform.device_name)
"
```
---
## 五、快速启动
```bash
# 离线推理测试
cd /workspace/mnt/vllm_ascend/vllm-npu-plugin
python demo.py
# OpenAI 兼容 API 服务
python -m vllm.entrypoints.openai.api_server \
--model /workspace/mnt/vllm_ascend/Qwen2.5-7B-Instruct \
--dtype float16 \
--trust-remote-code \
--host 0.0.0.0 \
--port 8000
```
---
## 六、常见问题
| 错误 | 原因 | 解决 |
|------|------|------|
| `LinearOperation setup failed!` | NNAL/ATB 版本与 CANN 不匹配 | 升级 NNAL 到与 CANN 同版本 |
| `ReshapeAndCacheOperation setup failed!` | 同上 | 同上 |
| `Cannot re-initialize NPU in forked subprocess` | NPU 在 fork 前被初始化 | 插件代码已修复（延迟初始化） |
| `vllm._C not found` | 正常警告，vLLM 的 CUDA C++ 扩展在 NPU 环境不需要 | 忽略 |
| `vllm_npu_C not found` | 正常警告，需编译 C++ 扩展才有 | 忽略，不影响功能 |