安装

安装#

本文档介绍了如何手动安装 vllm-ascend。

要求#

操作系统：Linux
Python：>= 3.10, < 3.12
配备昇腾 NPU 的硬件设备，通常为 Atlas 800 A2 系列。

软件：

软件	支持的版本	说明
Ascend HDK	Refer to here 25.5 is recommended	CANN 运行必需
CANN	== 8.5.0	vllm-ascend 和 torch-npu 运行必需
torch-npu	== 2.8.0	vllm-ascend 必需，无需手动安装，后续步骤会自动安装。
torch	== 2.8.0	torch-npu 和 vllm 运行必需
NNAL	== 8.5.0	libatb.so 必需，用于启用高级张量算子加速

有两种安装方式：

使用 pip：首先手动或通过 CANN 镜像准备环境，然后使用 pip 安装 vllm-ascend。
使用 Docker：直接使用 vllm-ascend 预构建的 Docker 镜像。

配置昇腾 CANN 环境#

在安装之前，请确保固件/驱动和 CANN 已正确安装，更多详情请参考昇腾环境搭建指南。

配置硬件环境#

要验证 Ascend NPU 固件和驱动程序是否正确安装，请运行：

npu-smi info

更多详情请参考Ascend环境搭建指南。

配置软件环境#

在使用 pip 之前

准备软件环境最简单的方法是直接使用 CANN 官方镜像：

备注

CANN 预构建镜像已包含 NNAL（昇腾神经网络加速库），它为高级张量操作提供 libatb.so 支持。使用预构建镜像时无需额外安装。

# Update DEVICE according to your device (/dev/davinci[0-7])
export DEVICE=/dev/davinci7
# Update the vllm-ascend image
export IMAGE=quay.io/ascend/cann:8.5.0-910b-ubuntu22.04-py3.11
docker run --rm \
    --name vllm-ascend-env \
    --shm-size=1g \
    --device $DEVICE \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v /root/.cache:/root/.cache \
    -it $IMAGE bash

在使用 Docker 之前

如果您使用的是 vllm-ascend 预构建的 Docker 镜像，则无需额外步骤。

完成上述步骤后，即可开始安装 vllm 和 vllm-ascend。

使用 Python 安装#

首先安装系统依赖并配置 pip 镜像源：

# Using apt-get with mirror
sed -i 's|ports.ubuntu.com|mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list
apt-get update -y && apt-get install -y gcc g++ cmake libnuma-dev wget git curl jq
# Or using yum
# yum update -y && yum install -y gcc g++ cmake numactl-devel wget git curl jq
# Config pip mirror
pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

[可选] 如果您在 x86 架构机器上操作或使用 torch-npu 开发版本，请配置 pip 的额外索引 (extra-index)：

# For x86 machine
pip config set global.extra-index-url "https://download.pytorch.org/whl/cpu/"

接着，您可以从预构建的 wheel 包安装 vllm 和 vllm-ascend：

# Install vllm-project/vllm. The newest supported version is v0.13.0.
pip install vllm==0.13.0

# Install vllm-project/vllm-ascend from pypi.
pip install vllm-ascend==0.13.0

备注

构建自定义算子需要 gcc/g++ 版本高于 8 且支持 C++17 或更高标准。如果您在使用 pip install -e . 时遇到 torch-npu 版本冲突，请使用 pip install --no-build-isolation -e . 以在系统环境下构建。如果在编译过程中遇到其他问题，通常是因为使用了非预期的编译器，您可以在编译前导出 CXX_COMPILER 和 C_COMPILER 环境变量来指定 g++ 和 gcc 的具体路径。

使用 Docker 安装#

vllm-ascend 提供了用于部署的 Docker 镜像。您可以直接从镜像仓库 ascend/vllm-ascend 拉取预构建镜像并运行。

支持的镜像如下：

镜像名称	硬件	操作系统
镜像标签	Atlas A2	Ubuntu
image-tag-openeuler	Atlas A2	openEuler
image-tag-a3	Atlas A3	Ubuntu
image-tag-a3-openeuler	Atlas A3	openEuler
image-tag-310p	Atlas 300I	Ubuntu
image-tag-310p-openeuler	Atlas 300I	openEuler

# Update --device according to your device (Atlas A2: /dev/davinci[0-7] Atlas A3:/dev/davinci[0-15]).
# Update the vllm-ascend image according to your environment.
# Note you should download the weight to /root/.cache in advance.
export IMAGE=quay.io/ascend/vllm-ascend:v0.13.0
docker run --rm \
    --name vllm-ascend-env \
    --shm-size=1g \
    --net=host \
    --device /dev/davinci0 \
    --device /dev/davinci1 \
    --device /dev/davinci2 \
    --device /dev/davinci3 \
    --device /dev/davinci4 \
    --device /dev/davinci5 \
    --device /dev/davinci6 \
    --device /dev/davinci7 \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v /root/.cache:/root/.cache \
    -it $IMAGE bash

默认工作目录为 /workspace，vLLM 和 vLLM Ascend 源码位于 /vllm-workspace，并以开发模式 (pip install -e) 安装，方便开发者在不重新安装的情况下使更改立即生效。

额外信息#

验证安装#

创建并运行一个简单的推理测试。example.py 示例代码如下：

from vllm import LLM, SamplingParams

prompts = [
    "Hello, my name is",
    "The president of the United States is",
    "The capital of France is",
    "The future of AI is",
]

# Create a sampling params object.
sampling_params = SamplingParams(temperature=0.8, top_p=0.95)
# Create an LLM.
llm = LLM(model="Qwen/Qwen2.5-0.5B-Instruct")

# Generate texts from the prompts.
outputs = llm.generate(prompts, sampling_params)
for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text
    print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")

然后执行：

python example.py

如果您遇到 Hugging Face 连接错误（例如：We couldn't connect to 'https://huggingface.co'...），请运行以下命令改用 ModelScope 镜像源：

export VLLM_USE_MODELSCOPE=true
pip install modelscope
python example.py

The output is shown below, and it may change with version updates:

INFO 02-18 08:49:58 __init__.py:28] Available plugins for group vllm.platform_plugins:
INFO 02-18 08:49:58 __init__.py:30] name=ascend, value=vllm_ascend:register
INFO 02-18 08:49:58 __init__.py:32] all available plugins for group vllm.platform_plugins will be loaded.
INFO 02-18 08:49:58 __init__.py:34] set environment variable VLLM_PLUGINS to control which plugins to load.
INFO 02-18 08:49:58 __init__.py:42] plugin ascend loaded.
INFO 02-18 08:49:58 __init__.py:174] Platform plugin ascend is activated
INFO 02-18 08:50:12 config.py:526] This model supports multiple tasks: {'embed', 'classify', 'generate', 'score', 'reward'}. Defaulting to 'generate'.
INFO 02-18 08:50:12 llm_engine.py:232] Initializing a V1 LLM engine (vx.x.x) with config: model='./Qwen2.5-0.5B-Instruct', speculative_config=None, tokenizer='./Qwen2.5-0.5B-Instruct', skip_tokenizer_init=False, tokenizer_mode=auto, revision=None, override_neuron_config=None, tokenizer_revision=None, trust_remote_code=False, dtype=torch.bfloat16, max_seq_len=32768, download_dir=None, load_format=auto, tensor_parallel_size=1, pipeline_parallel_size=1, disable_custom_all_reduce=False, quantization=None, enforce_eager=False, kv_cache_dtype=auto,  device_config=npu, decoding_config=DecodingConfig(guided_decoding_backend='xgrammar'), observability_config=ObservabilityConfig(otlp_traces_endpoint=None, collect_model_forward_time=False, collect_model_execute_time=False), seed=0, served_model_name=./Qwen2.5-0.5B-Instruct, num_scheduler_steps=1, multi_step_stream_outputs=True, enable_prefix_caching=False, chunked_prefill_enabled=False, use_async_output_proc=True, disable_mm_preprocessor_cache=False, mm_processor_kwargs=None, pooler_config=None, compilation_config={"splitting_ops":[],"compile_sizes":[],"cudagraph_capture_sizes":[256,248,240,232,224,216,208,200,192,184,176,168,160,152,144,136,128,120,112,104,96,88,80,72,64,56,48,40,32,24,16,8,4,2,1],"max_capture_size":256}, use_cached_outputs=False,
Loading safetensors checkpoint shards:   0% Completed | 0/1 [00:00<?, ?it/s]
Loading safetensors checkpoint shards: 100% Completed | 1/1 [00:00<00:00,  5.86it/s]
Loading safetensors checkpoint shards: 100% Completed | 1/1 [00:00<00:00,  5.85it/s]
INFO 02-18 08:50:24 executor_base.py:108] # CPU blocks: 35064, # CPU blocks: 2730
INFO 02-18 08:50:24 executor_base.py:113] Maximum concurrency for 32768 tokens per request: 136.97x
INFO 02-18 08:50:25 llm_engine.py:429] init engine (profile, create kv cache, warmup model) took 3.87 seconds
Processed prompts: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 4/4 [00:00<00:00,  8.46it/s, est. speed input: 46.55 toks/s, output: 135.41 toks/s]
Prompt: 'Hello, my name is', Generated text: " Shinji, a teenage boy from New York City. I'm a computer science"
Prompt: 'The president of the United States is', Generated text: ' a very important person. When he or she is elected, many people think that'
Prompt: 'The capital of France is', Generated text: ' Paris. The oldest part of the city is Saint-Germain-des-Pr'
Prompt: 'The future of AI is', Generated text: ' not bright\n\nThere is no doubt that the evolution of AI will have a huge'

多节点部署#

验证多节点通信#

首先检查物理层连通性，然后验证单个节点，最后验证节点间的连通性。

物理层要求：#

物理机必须位于同一局域网内，且网络互通。
所有 NPU 均通过光模块连接，且连接状态必须正常。

单节点验证：#

在每个节点上依次执行以下命令，结果必须全部为 success 且状态为 UP：

A2 系列

 # Check the remote switch ports
 for i in {0..7}; do hccn_tool -i $i -lldp -g | grep Ifname; done 
 # Get the link status of the Ethernet ports (UP or DOWN)
 for i in {0..7}; do hccn_tool -i $i -link -g ; done
 # Check the network health status
 for i in {0..7}; do hccn_tool -i $i -net_health -g ; done
 # View the network detected IP configuration
 for i in {0..7}; do hccn_tool -i $i -netdetect -g ; done
 # View gateway configuration
 for i in {0..7}; do hccn_tool -i $i -gateway -g ; done
 # View NPU network configuration
 cat /etc/hccn.conf

A3 系列

 # Check the remote switch ports
 for i in {0..15}; do hccn_tool -i $i -lldp -g | grep Ifname; done 
 # Get the link status of the Ethernet ports (UP or DOWN)
 for i in {0..15}; do hccn_tool -i $i -link -g ; done
 # Check the network health status
 for i in {0..15}; do hccn_tool -i $i -net_health -g ; done
 # View the network detected IP configuration
 for i in {0..15}; do hccn_tool -i $i -netdetect -g ; done
 # View gateway configuration
 for i in {0..15}; do hccn_tool -i $i -gateway -g ; done
 # View NPU network configuration
 cat /etc/hccn.conf

互联验证：#

1.获取 NPU IP 地址#

A2 系列

for i in {0..7}; do hccn_tool -i $i -ip -g | grep ipaddr; done

A3 系列

for i in {0..15}; do hccn_tool -i $i -ip -g | grep ipaddr; done

2.跨节点 PING 测试#

# Execute on the target node (replace with actual IP)
hccn_tool -i 0 -ping -g address x.x.x.x

在每个节点运行容器#

使用 vLLM-ascend 官方容器可以更高效地运行多节点环境。

在每个节点运行以下命令启动容器（您应提前将模型权重下载到 /root/.cache）：

A2 系列

# Update the vllm-ascend image
# openEuler:
# export IMAGE=quay.io/ascend/vllm-ascend:v0.13.0-openeuler
# Ubuntu:
# export IMAGE=quay.io/ascend/vllm-ascend:v0.13.0
export IMAGE=quay.io/ascend/vllm-ascend:v0.13.0

# Run the container using the defined variables
# Note if you are running bridge network with docker, Please expose available ports
# for multiple nodes communication in advance
docker run --rm \
--name vllm-ascend \
--net=host \
--shm-size=1g \
--device /dev/davinci0 \
--device /dev/davinci1 \
--device /dev/davinci2 \
--device /dev/davinci3 \
--device /dev/davinci4 \
--device /dev/davinci5 \
--device /dev/davinci6 \
--device /dev/davinci7 \
--device /dev/davinci_manager \
--device /dev/devmm_svm \
--device /dev/hisi_hdc \
-v /usr/local/dcmi:/usr/local/dcmi \
-v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
-v /etc/ascend_install.info:/etc/ascend_install.info \
-v /root/.cache:/root/.cache \
-it $IMAGE bash

A3 系列

# Update the vllm-ascend image
# openEuler:
# export IMAGE=quay.io/ascend/vllm-ascend:v0.13.0-a3-openeuler
# Ubuntu:
# export IMAGE=quay.io/ascend/vllm-ascend:v0.13.0-a3
export IMAGE=quay.io/ascend/vllm-ascend:v0.13.0-a3

# Run the container using the defined variables
# Note if you are running bridge network with docker, Please expose available ports
# for multiple nodes communication in advance
docker run --rm \
--name vllm-ascend \
--net=host \
--shm-size=1g \
--device /dev/davinci0 \
--device /dev/davinci1 \
--device /dev/davinci2 \
--device /dev/davinci3 \
--device /dev/davinci4 \
--device /dev/davinci5 \
--device /dev/davinci6 \
--device /dev/davinci7 \
--device /dev/davinci8 \
--device /dev/davinci9 \
--device /dev/davinci10 \
--device /dev/davinci11 \
--device /dev/davinci12 \
--device /dev/davinci13 \
--device /dev/davinci14 \
--device /dev/davinci15 \
--device /dev/davinci_manager \
--device /dev/devmm_svm \
--device /dev/hisi_hdc \
-v /usr/local/dcmi:/usr/local/dcmi \
-v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
-v /etc/ascend_install.info:/etc/ascend_install.info \
-v /root/.cache:/root/.cache \
-it $IMAGE bash