安装

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

环境要求

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

• 软件：

  软件	支持的版本	备注
  Ascend HDK	参考文档 CANN 9.0.1	CANN 必需
  CANN	== 9.0.1	vllm-ascend 和 torch-npu 必需
  torch-npu	== 2.10.0.post2	vllm-ascend 必需，无需手动安装，后续步骤将自动安装
  torch	== 2.10.0	torch-npu 和 vllm 必需，无需手动安装，以下步骤将自动安装
  NNAL	== 9.0.1	libatb.so 必需，支持高级张量运算

有两种安装方式：

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

配置昇腾 CANN 环境

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

配置硬件环境

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

npu-smi info

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

配置软件环境

使用 pip 之前使用 Docker 之前

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

Note

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:9.0.1-910b-ubuntu22.04-py3.12
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

点击此处查看'手动安装 CANN'

您也可以手动安装 CANN：

Warning

如果在运行时遇到“找不到 libatb.so”的错误，请确保按照下方手动安装步骤正确安装了 NNAL。

# Create a virtual environment.
python -m venv vllm-ascend-env
source vllm-ascend-env/bin/activate

# Install required Python packages.
python -m pip install --upgrade pip
pip3 install attrs numpy decorator sympy cffi pyyaml pathlib2 psutil protobuf scipy requests absl-py wheel typing_extensions

# Download and install the CANN package.
wget --header="Referer: https://www.hiascend.com/" https://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/CANN%209.0.1/Ascend-cann-toolkit_9.0.1_linux-"$(uname -i)".run
chmod +x ./Ascend-cann-toolkit_9.0.1_linux-"$(uname -i)".run
./Ascend-cann-toolkit_9.0.1_linux-"$(uname -i)".run --full
source /usr/local/Ascend/ascend-toolkit/set_env.sh

wget --header="Referer: https://www.hiascend.com/" https://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/CANN%209.0.1/Ascend-cann-910b-ops_9.0.1_linux-"$(uname -i)".run
chmod +x ./Ascend-cann-910b-ops_9.0.1_linux-"$(uname -i)".run
./Ascend-cann-910b-ops_9.0.1_linux-"$(uname -i)".run --install

wget --header="Referer: https://www.hiascend.com/" https://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/CANN%209.0.1/Ascend-cann-nnal_9.0.1_linux-"$(uname -i)".run
chmod +x ./Ascend-cann-nnal_9.0.1_linux-"$(uname -i)".run
./Ascend-cann-nnal_9.0.1_linux-"$(uname -i)".run --install

source /usr/local/Ascend/nnal/atb/set_env.sh

如果您使用 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, only versions 0.11.0 and earlier are supported, if using a version later than 0.11.0, do not execute this command
pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

[可选] 如果您在 x86 机器上工作或使用 torch-npu 开发版本，请配置 pip 的 extra-index：

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

然后，您可以通过以下任一方法从**预构建的 wheel 包**安装 vllm 和 vllm-ascend：

原始安装uv-wheelnext 安装

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

# Install vllm-project/vllm-ascend.
pip install \
--extra-index-url https://mirrors.huaweicloud.com/ascend/repos/pypi/variant \
vllm-ascend==0.22.1rc1

uv-wheelnext 安装仅下载 vllm 之上的增量部分，从而减小下载体积。首先安装 uv-wheelnext 以支持增量 wheel 包：

# install uv-wheelnext
curl -LsSf https://astral.sh/uv/install.sh | sed 's/verify_checksum "$_file"/true/' | INSTALLER_DOWNLOAD_URL=https://wheelnext.astral.sh sh
source $HOME/.local/bin/env

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

# Install vllm-project/vllm-ascend from wheelnext index.
uv pip install --system \
--extra-index-url https://mirrors.huaweicloud.com/ascend/repos/pypi/variant   \
--index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple \
vllm-ascend==0.22.1rc1

Note

如果在 uv pip install 过程中遇到错误（例如缓存损坏或包数据过期），请先清除 uv 缓存，然后重新运行安装命令：

uv cache clean

点击此处查看'从源代码构建'

或从**源代码**构建：

Note

要安装 triton-ascend，请运行：

pip install triton-ascend==3.2.1 --extra-index-url https://mirrors.huaweicloud.com/ascend/repos/pypi

如果通过 uv 安装，请确保在所有其他包安装完成**之后**再安装 triton-ascend，以避免依赖解析冲突。

# Install vLLM.
git clone --depth 1 --branch v0.22.1 https://github.com/vllm-project/vllm
cd vllm
VLLM_TARGET_DEVICE=empty pip install -e .
cd ..

# Install vLLM Ascend.
git clone --depth 1 --branch v0.22.1rc1 https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
git submodule update --init --recursive
pip install -e .
cd ..

如果为 Atlas A3 构建自定义算子，应手动运行 git submodule update --init --recursive，或确保环境可以访问互联网。

Note

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

如果在无法使用 npu-smi 的纯 CPU 环境中构建，需要在 SOC_VERSION 之前设置 pip install -e .，以便构建过程定位正确的芯片。您可以参考 Dockerfile* 中的默认值，例如：

• Atlas A2：export SOC_VERSION=ascend910b1
• Atlas A3：export SOC_VERSION=ascend910_9391
• Atlas 300I：export SOC_VERSION=ascend310p1
• Ascend 950 系列产品：export SOC_VERSION=<value starting with "ascend950">

Note

要启用批量不变性特性，请在构建 vllm-ascend 前设置 VLLM_BATCH_INVARIANT=1，以便在安装过程中安装批量不变性自定义算子库。 关于批量不变性特性的使用指南，请参见 https://github.com/vllm-project/vllm-ascend/blob/main/docs/source/user_guide/feature_guide/batch_invariance.md

使用 Docker 进行设置

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

支持的镜像如下：

镜像名称	硬件	操作系统
vllm-ascend:v0.22.1rc1	Atlas A2	Ubuntu
vllm-ascend:v0.22.1rc1-openeuler	Atlas A2	openEuler
vllm-ascend:v0.22.1rc1-a3	Atlas A3	Ubuntu
vllm-ascend:v0.22.1rc1-a3-openeuler	Atlas A3	openEuler
vllm-ascend:v0.22.1rc1-310p	Atlas 300I	Ubuntu
vllm-ascend:v0.22.1rc1-310p-openeuler	Atlas 300I	openEuler

点击此处查看'从 Dockerfile 构建'

或从**源代码**构建镜像：

git clone https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
docker build -t vllm-ascend-dev-image:latest -f ./Dockerfile .

# 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.22.1rc1
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/Qwen3-0.6B")

# 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' to load the files, and couldn't find them in the cached files.），请运行以下命令以使用 ModelScope 作为替代：

export VLLM_USE_MODELSCOPE=True
pip install modelscope
python example.py

此部分显示在 vllm 中成功检测到 ascend 平台：

INFO 05-27 11:40:38 [__init__.py:44] Available plugins for group vllm.platform_plugins:
INFO 05-27 11:40:38 [__init__.py:46] - ascend -> vllm_ascend:register
INFO 05-27 11:40:38 [__init__.py:49] All plugins in this group will be loaded. Set `VLLM_PLUGINS` to control which plugins to load.
INFO 05-27 11:40:38 [__init__.py:238] Platform plugin ascend is activated

此部分显示最终输出：

Prompt: 'Hello, my name is', Generated text: ' Lucy and I am an 8 year old who loves to draw and write stories'
Prompt: 'The president of the United States is', Generated text: " a key leader in the federal government, and the president's role in the executive"
Prompt: 'The capital of France is', Generated text: ' a city. What is the capital of France? The capital of France is Paris'
Prompt: 'The future of AI is', Generated text: ' a topic that is being discussed in various contexts. In the business world, AI'

此部分显示进程在离线推理后退出，不影响实际推理：

(EngineCore pid=970) INFO 05-12 11:36:00 [core.py:1201] Shutdown initiated (timeout=0)
(EngineCore pid=970) INFO 05-12 11:36:00 [core.py:1224] Shutdown complete
ERROR 05-12 11:36:01 [core_client.py:704] Engine core proc EngineCore died unexpectedly, shutting down client.
sys:1: DeprecationWarning: builtin type swigvarlink has no __module__ attribute

多节点部署

验证多节点通信

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

物理层要求

• 物理机器必须位于同一 LAN 中，且网络连通。
• 所有 NPU 均通过光模块连接，且连接状态必须正常。

每个节点验证

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

A2 系列A3 系列

 # 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

 # 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 系列A3 系列

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

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 系列A3 系列

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

# 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

# Update the vllm-ascend image
# openEuler:
# export IMAGE=quay.io/ascend/vllm-ascend:v0.22.1rc1-a3-openeuler
# Ubuntu:
# export IMAGE=quay.io/ascend/vllm-ascend:v0.22.1rc1-a3
export IMAGE=quay.io/ascend/vllm-ascend:v0.22.1rc1-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