vllm-project/vllm-ascend · 上手攻略

• 仓库：vllm-project/vllm-ascend
• 链接：https://github.com/vllm-project/vllm-ascend
• 分类：ai
• 作者：Tom
• 更新：2026-07-10

是什么

vllm-ascend 是华为昇腾（Ascend）NPU 的官方 vLLM 硬件插件，让 vLLM 高性能推理框架能跑在昇腾芯片上。它由 vLLM 社区维护，遵循 vLLM 的硬件可插拔接口（Hardware Pluggable RFC），是昇腾后端在 vLLM 生态的推荐方案。

通俗理解：vLLM 是 LLM 推理的"操作系统"，vllm-ascend 就是让这个 OS 支持华为昇腾 NPU 的驱动/插件。

解决什么问题

• 昇腾芯片上跑 vLLM：昇腾 NPU在中国市场有大量部署，但 vLLM 官方最初只支持 NVIDIA CUDA，需要社区插件才能在昇腾上运行
• 高性能推理：相比基于 Transformers 库的原始推理，vLLM 有 PagedAttention、异步执行等大量优化，vllm-ascend 把这些优化带到昇腾平台
• 统一推理接口：在昇腾上用 vLLM 相同的 Python API，降低从 NVIDIA 迁移到昇腾的学习成本

快速安装

环境要求

• 硬件：Atlas 800I A2（推理）、Atlas A2（训练）、Atlas 800I A3（推理）、Atlas A3（训练）、Atlas 300I Duo（实验性）
• 操作系统：Linux
• Python：>= 3.10

推荐版本组合

⚠️ 版本对应关系复杂，安装前务必确认与你的 vLLM 主版本匹配。最新稳定版本为 v0.18.0，对应 vLLM v0.18.x。

pip 安装（稳定版 v0.18.0）

pip install vllm==0.18.0
pip install vllm-ascend==0.18.0

从源码编译

# 克隆
git clone https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend

# 切到对应分支（以 v0.18.0 为例）
git checkout releases/v0.18.0

# 安装依赖并编译
pip install -e .

# 验证
python -c "import vllm; print(vllm.__version__)"

Docker 方式（推荐生产环境）

# 官方昇腾 Docker 镜像（已有 CANN + vLLM 环境）
docker pull ascendpro/vllm-ascend:v0.18.0

核心用法

基本推理调用

from vllm import LLM, SamplingParams

# 指定后端为昇腾
llm = LLM(
    model="meta-llama/Llama-2-7b-chat-hf",
    tensor_parallel_size=1,        # 单卡；多卡改为 2/4/8
    device="ascend",              # 关键：指定昇腾后端
    trust_remote_code=True,
)

sampling_params = SamplingParams(
    temperature=0.8,
    top_p=0.95,
    max_tokens=512,
)

outputs = llm.generate(["Hello, world!"], sampling_params)

for output in outputs:
    print(output.outputs[0].text)

支持的模型类型

• Dense Transformer：LLaMA、Qwen、Mistral 等常规模型
• MoE（混合专家）：Mixtral、Qwen-MoE 等
• Embedding 模型：用于向量检索场景
• 多模态 LLM：支持视觉语言模型（参考官方 Support Matrix 确认具体版本）

📖 完整支持列表见：Supported Models

大规模 Expert Parallelism（EP）部署

v0.9.1+ 支持多卡 Expert Parallelism：

# 多卡启动示例（4卡 EP）
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2-57B-A14B \
    --tensor-parallel-size 4 \
    --device-ptdc-plugin ascend \
    --numa-aware \
    --enforce-eager

⚠️ EP 是 MoE 模型专用特性，确认你的硬件和模型支持后再使用。

启动 OpenAI 兼容 API 服务

python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-2-7b-chat-hf \
    --device ascend \
    --port 8000 \
    --host 0.0.0.0

然后用标准 OpenAI API 格式调用：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-2-7b-chat-hf",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

典型适用场景

1. 昇腾服务器推理部署：在中国云/私有化环境有大量昇腾设备，需要高吞吐量 LLM 推理服务
2. 国产化替代：从 NVIDIA GPU 迁移到昇腾，需要保持 vLLM 的优化特性和 API 兼容性
3. 大规模 MoE 推理：Expert Parallelism 对 MoE 模型在昇腾多卡上的并行加速
4. fine-tuning + 推理联动：配合 LLaMA-Factory/verl/TRL 在昇腾上做训练，推理也用 vLLM Ascend

坑与注意

1. 版本强耦合：vllm-ascend 版本必须与 vLLM 主版本严格对应，混用会导致运行时错误。先查 Release 列表 确认对应关系。
2. CANN 版本依赖：昇腾芯片需要配套的 CANN（Compute Architecture for Neural Networks）驱动，版本要匹配；建议用官方 Docker 镜像避免环境问题。
3. Atlas 300I Duo 是实验性：生产环境推荐 Atlas 800I A2/A3。
4. v0.7.x 分支已停止维护：不要在生产环境使用 v0.7.x 系列。
5. 中文文档有限：主要文档是英文，配置问题可参考 vLLM Ascend 论坛。
6. 异步推理需开 enforce_eager=false：否则部分异步优化不会生效（但内存占用略高）。

与同类对比

vllm-ascend 是昇腾上最完整的 vLLM 方案，如果你同时用昇腾和 NVIDIA，推荐用同一个 vLLM API，只是换 --device 参数。

一句话推荐结论

在昇腾 NPU 上跑 LLM 推理，vllm-ascend 是目前官方认可、性能最优、生态最完整的方案——用 Docker 镜像快速上手，用 OpenAI 兼容 API 零改动迁移现有应用。