From c00c47a5b2d6623838adec7d5401cda55f4b25cb Mon Sep 17 00:00:00 2001 From: handsomezhuzhu <2658601135@qq.com> Date: Wed, 11 Feb 2026 00:13:26 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E7=8E=AF=E5=A2=83?= =?UTF-8?q?=E5=AE=89=E8=A3=85=E6=8C=87=E5=8D=97=E3=80=81=E9=AA=8C=E8=AF=81?= =?UTF-8?q?=E4=B8=8E=E5=9F=BA=E5=87=86=E6=B5=8B=E8=AF=95=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ARCHITECTURE.md | 207 +++++++++++++++++++++++++++++++++++++++ BENCHMARK.md | 253 ++++++++++++++++++++++++++++++++++++++++++++++++ INSTALL.md | 175 +++++++++++++++++++++++++++++++++ 3 files changed, 635 insertions(+) create mode 100644 ARCHITECTURE.md create mode 100644 BENCHMARK.md create mode 100644 INSTALL.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..cbc3e0c --- /dev/null +++ b/ARCHITECTURE.md @@ -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 注册插件 diff --git a/BENCHMARK.md b/BENCHMARK.md new file mode 100644 index 0000000..f711834 --- /dev/null +++ b/BENCHMARK.md @@ -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 --dtype float16 --trust-remote-code --input-len 128 --output-len 128 --batch-size 1 + +# 吞吐测试 +vllm bench throughput --model --dtype float16 --trust-remote-code --input-len 256 --output-len 256 --num-prompts 100 + +# 服务压测（需先启动 API 服务器） +vllm bench serve --model --base-url http://localhost:8000 --dataset-name random --random-input-len 256 --random-output-len 128 --num-prompts 200 --request-rate 5 +``` diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..891fce8 --- /dev/null +++ b/INSTALL.md @@ -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 -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 -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++ 扩展才有 | 忽略，不影响功能 |