安装指南¶

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

要求¶

环境要求¶

操作系统：Linux
Python：>= 3.10, < 3.13
配备昇腾NPU的硬件。本指南支持以下设备：

Type	Common products
Atlas A2 Products	Atlas 800T A2, Atlas 900 A2 PoD, Atlas 200T A2 Box16, Atlas 300T A2, Atlas 800I A2, and others
Atlas A3 Products	Atlas 800T A3, Atlas 900 A3 SuperPoD, Atlas 9000 A3 SuperPoD, Atlas 800I A3, and others
Atlas inference series products	Atlas 300I DUO and Atlas 200I Pro
950DT Products	950DT

硬件和软件栈¶

vLLM Ascend 运行在分层的硬件和软件栈之上。以下概述展示了主要运行时组件如何协同工作。

硬件和软件栈概览

vLLM Ascend 硬件和软件栈

以下硬件和软件栈已针对此版本进行联合验证：

已验证的硬件和软件栈

层	组件	已验证版本/要求	作用
运行时环境	Python	`3.12`	已验证发布镜像使用的Python版本
主机使能	Ascend HDK	`26.0.RC1`	所选CANN版本的驱动和固件要求
昇腾运行时	CANN Toolkit + Ops	`9.1.0`	昇腾用户态运行时，包括CANN Toolkit和特定硬件的Ops包
昇腾运行时	NNAL	`9.1.0`	提供 `libatb.so` 和ATB运行时能力
框架	PyTorch	`2.10.0`	vLLM使用的张量框架
框架	TorchNPU	`2.10.0.post4`	将PyTorch连接到昇腾运行时
Kernel acceleration	Triton Ascend	`3.2.2`	Used on A2, A3, and 950DT Products; not used on Atlas 300I DUO or Atlas 200I Pro
推理引擎	vLLM	`0.23.0`	模型推理引擎
硬件插件	vLLM Ascend	`0.23.0`	将vLLM连接到昇腾软件栈

上表中的版本和要求作为一个兼容性集合进行验证。请勿随意混用不同发布版本的组件。

如需其他发布版本，请从版本策略 > 发布兼容性矩阵中选择完整的一行。

安装¶

设置硬件环境¶

首先，运行以下命令以确认昇腾NPU固件和驱动已正确安装：

npu-smi info

更多信息，请参阅CANN安装资源。

设置软件环境¶

根据您的需求选择一条完整的路径。基于容器的路径需要Docker；如有需要，请参阅Docker安装指南。

需求	推荐方法	目标用户
尽快获得可用的vLLM Ascend环境	使用预构建镜像	首次使用或希望快速部署的用户
在现有CANN环境中安装vLLM Ascend	在CANN环境中安装	使用CANN镜像或已安装CANN的主机/容器的用户
手动安装和管理完整的软件栈	从基础环境安装	需要自定义CANN或Python依赖、开发或调试的高级用户

按安装方法划分的组件

状态： ✓ 已可用 · ○ 在此路径中安装

组件	预构建镜像	CANN环境	基础环境
CANN Toolkit + Ops	✓	✓	○
NNAL	✓	✓	○
PyTorch + TorchNPU	✓	○	○
vLLM + vLLM Ascend	✓	○	○
Triton Ascend	✓	○	○

PyTorch and TorchNPU: Installed as dependencies during the Install vLLM and vLLM Ascend step; no separate installation step is required.
Triton Ascend: Installed only for A2, A3, and 950DT Products; it is not used on Atlas 300I DUO or Atlas 200I Pro.

预构建镜像CANN环境基础环境

宿主机仅需可用的Ascend驱动和固件，以及Docker。镜像中包含CANN用户态环境、PyTorch/TorchNPU、vLLM和vLLM Ascend。

选择官方镜像可快速完成部署，如需自定义镜像，则可手动构建。

选择官方镜像手动构建镜像

选择您的硬件和操作系统，然后拉取官方镜像、启动容器并验证环境。

官方vLLM Ascend镜像

镜像名称	硬件	操作系统
`vllm-ascend:v0.23.0`	Ascend A2系列产品	Ubuntu
`vllm-ascend:v0.23.0-openeuler`	Ascend A2系列产品	openEuler
`vllm-ascend:v0.23.0-a3`	Ascend A3系列产品	Ubuntu
`vllm-ascend:v0.23.0-a3-openeuler`	Ascend A3系列产品	openEuler
`vllm-ascend:v0.23.0-310p`	Atlas 300I DUO / Atlas 200I Pro	Ubuntu
`vllm-ascend:v0.23.0-310p-openeuler`	Atlas 300I DUO / Atlas 200I Pro	openEuler
`vllm-ascend:v0.23.0-a5`	950DT Products	Ubuntu
`vllm-ascend:v0.23.0-a5-openeuler`	950DT Products	openEuler

A2A3Atlas 300I DUOAtlas 200I Pro950DT Products

拉取镜像¶

如果镜像下载速度较慢

vLLM Ascend 镜像默认从 quay.io 下载。如果直接访问速度较慢，可以使用以下任一镜像仓库来加速下载。

例如，原始镜像地址为：

quay.io/ascend/vllm-ascend:<TAG>

您可以将其替换为：

# Replace with tag you want to pull
TAG=v0.23.0
# use
docker pull m.daocloud.io/quay.io/ascend/vllm-ascend:$TAG
# or
docker pull quay.nju.edu.cn/ascend/vllm-ascend:$TAG

仅替换镜像仓库前缀，并保留完整的原始镜像标签，包括诸如 -a3、-310p、-950dt 和 -openeuler 等后缀。

UbuntuopenEuler

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0
docker pull "$IMAGE"

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-openeuler
docker pull "$IMAGE"

启动容器¶

UbuntuopenEuler

export DEVICE=/dev/davinci0
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend \
    --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 "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

export DEVICE=/dev/davinci0
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend \
    --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 "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

验证容器环境¶

在容器中运行以下命令。当输出包含 vLLM Ascend environment: OK 时，表示容器已准备就绪。

npu-smi info

python3 - <<'PY'
import torch
import vllm
import vllm_ascend

assert torch.npu.is_available(), "No available Ascend NPU detected in the container"
print("vLLM Ascend environment: OK")
PY

拉取镜像¶

如果镜像下载速度较慢

vLLM Ascend 镜像默认从 quay.io 下载。如果直接访问速度较慢，可以使用以下任一镜像仓库来加速下载。

例如，原始镜像地址为：

quay.io/ascend/vllm-ascend:<TAG>

您可以将其替换为：

# Replace with tag you want to pull
TAG=v0.23.0
# use
docker pull m.daocloud.io/quay.io/ascend/vllm-ascend:$TAG
# or
docker pull quay.nju.edu.cn/ascend/vllm-ascend:$TAG

仅替换镜像仓库前缀，并保留完整的原始镜像标签，包括诸如 -a3、-310p、-950dt 和 -openeuler 等后缀。

UbuntuopenEuler

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-a3
docker pull "$IMAGE"

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-a3-openeuler
docker pull "$IMAGE"

启动容器¶

A3容器启动要求

A3采用双DIE设计，需要两个昇腾设备节点，例如 /dev/davinci0 和 /dev/davinci1。

UbuntuopenEuler

export DEVICE0=/dev/davinci0
export DEVICE1=/dev/davinci1
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend \
    --shm-size=1g \
    --device "$DEVICE0" \
    --device "$DEVICE1" \
    --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 "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

export DEVICE0=/dev/davinci0
export DEVICE1=/dev/davinci1
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend \
    --shm-size=1g \
    --device "$DEVICE0" \
    --device "$DEVICE1" \
    --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 "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

验证容器环境¶

在容器中运行以下命令。当输出包含 vLLM Ascend environment: OK 时，表示容器已准备就绪。

npu-smi info

python3 - <<'PY'
import torch
import vllm
import vllm_ascend

assert torch.npu.is_available(), "No available Ascend NPU detected in the container"
print("vLLM Ascend environment: OK")
PY

拉取镜像¶

如果镜像下载速度较慢

vLLM Ascend 镜像默认从 quay.io 下载。如果直接访问速度较慢，可以使用以下任一镜像仓库来加速下载。

例如，原始镜像地址为：

quay.io/ascend/vllm-ascend:<TAG>

您可以将其替换为：

# Replace with tag you want to pull
TAG=v0.23.0
# use
docker pull m.daocloud.io/quay.io/ascend/vllm-ascend:$TAG
# or
docker pull quay.nju.edu.cn/ascend/vllm-ascend:$TAG

仅替换镜像仓库前缀，并保留完整的原始镜像标签，包括诸如 -a3、-310p、-950dt 和 -openeuler 等后缀。

UbuntuopenEuler

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-310p
docker pull "$IMAGE"

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-310p-openeuler
docker pull "$IMAGE"

启动容器¶

UbuntuopenEuler

export DEVICE=/dev/davinci0
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend \
    --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 "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

export DEVICE=/dev/davinci0
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend \
    --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 "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

验证容器环境¶

在容器中运行以下命令。当输出包含 vLLM Ascend environment: OK 时，表示容器已准备就绪。

npu-smi info

python3 - <<'PY'
import torch
import vllm
import vllm_ascend

assert torch.npu.is_available(), "No available Ascend NPU detected in the container"
print("vLLM Ascend environment: OK")
PY

拉取镜像¶

如果镜像下载速度较慢

vLLM Ascend 镜像默认从 quay.io 下载。如果直接访问速度较慢，可以使用以下任一镜像仓库来加速下载。

例如，原始镜像地址为：

quay.io/ascend/vllm-ascend:<TAG>

您可以将其替换为：

# Replace with tag you want to pull
TAG=v0.23.0
# use
docker pull m.daocloud.io/quay.io/ascend/vllm-ascend:$TAG
# or
docker pull quay.nju.edu.cn/ascend/vllm-ascend:$TAG

仅替换镜像仓库前缀，并保留完整的原始镜像标签，包括诸如 -a3、-310p、-950dt 和 -openeuler 等后缀。

UbuntuopenEuler

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-310p
docker pull "$IMAGE"

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-310p-openeuler
docker pull "$IMAGE"

启动容器¶

Atlas 200I Pro 容器启动要求

Atlas 200I Pro 需要额外的设备节点、驱动库和主机配置文件。在启动容器之前，请确保以下命令挂载的所有主机路径均已存在。

UbuntuopenEuler

export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --privileged \
    --name vllm-ascend \
    --shm-size=10g \
    --device=/dev/davinci0:/dev/davinci0 \
    --device=/dev/davinci_manager \
    --device=/dev/ascend_manager \
    --device=/dev/user_config \
    -v /etc/sys_version.conf:/etc/sys_version.conf \
    -v /etc/ld.so.conf.d/mind_so.conf:/etc/ld.so.conf.d/mind_so.conf \
    -v /etc/hdcBasic.cfg:/etc/hdcBasic.cfg \
    -v /var/dmp_daemon:/var/dmp_daemon \
    -v /usr/lib64/libmmpa.so:/usr/lib64/libmmpa.so \
    -v /usr/lib64/libcrypto.so.1.1:/usr/lib64/libcrypto.so.1.1 \
    -v /usr/local/sbin/npu-smi:/usr/local/sbin/npu-smi \
    -v /usr/lib64/libstackcore.so:/usr/lib64/libstackcore.so \
    -v /usr/lib/aarch64-linux-gnu/libyaml-0.so.2:/usr/lib64/libyaml-0.so.2 \
    -v /etc/slog.conf:/etc/slog.conf \
    -v /var/slogd:/var/slogd \
    -v /usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64 \
    -v /usr/lib64/libtensorflow.so:/usr/lib64/libtensorflow.so \
    -v "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --privileged \
    --name vllm-ascend \
    --shm-size=10g \
    --device=/dev/davinci0:/dev/davinci0 \
    --device=/dev/davinci_manager \
    --device=/dev/ascend_manager \
    --device=/dev/user_config \
    -v /etc/sys_version.conf:/etc/sys_version.conf \
    -v /etc/ld.so.conf.d/mind_so.conf:/etc/ld.so.conf.d/mind_so.conf \
    -v /etc/hdcBasic.cfg:/etc/hdcBasic.cfg \
    -v /var/dmp_daemon:/var/dmp_daemon \
    -v /usr/lib64/libsemanage.so.2:/usr/lib64/libsemanage.so.2 \
    -v /usr/lib64/libmmpa.so:/usr/lib64/libmmpa.so \
    -v /usr/lib64/libcrypto.so.1.1:/usr/lib64/libcrypto.so.1.1 \
    -v /usr/lib64/libyaml-0.so.2.0.9:/usr/lib64/libyaml-0.so.2 \
    -v /usr/local/sbin/npu-smi:/usr/local/sbin/npu-smi \
    -v /usr/lib64/libstackcore.so:/usr/lib64/libstackcore.so \
    -v /etc/slog.conf:/etc/slog.conf \
    -v /var/slogd:/var/slogd \
    -v /usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64 \
    -v /usr/lib64/libtensorflow.so:/usr/lib64/libtensorflow.so \
    -v "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

验证容器环境¶

在容器中运行以下命令。当输出包含 vLLM Ascend environment: OK 时，表示容器已准备就绪。

npu-smi info

python3 - <<'PY'
import torch
import vllm
import vllm_ascend

assert torch.npu.is_available(), "No available Ascend NPU detected in the container"
print("vLLM Ascend environment: OK")
PY

拉取镜像¶

如果镜像下载速度较慢

vLLM Ascend 镜像默认从 quay.io 下载。如果直接访问速度较慢，可以使用以下任一镜像仓库来加速下载。

例如，原始镜像地址为：

quay.io/ascend/vllm-ascend:<TAG>

您可以将其替换为：

# Replace with tag you want to pull
TAG=v0.23.0
# use
docker pull m.daocloud.io/quay.io/ascend/vllm-ascend:$TAG
# or
docker pull quay.nju.edu.cn/ascend/vllm-ascend:$TAG

仅替换镜像仓库前缀，并保留完整的原始镜像标签，包括诸如 -a3、-310p、-950dt 和 -openeuler 等后缀。

UbuntuopenEuler

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-a5
docker pull "$IMAGE"

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-a5-openeuler
docker pull "$IMAGE"

启动容器¶

UbuntuopenEuler

export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend \
    --net=host \
    --shm-size=1g \
    --device /dev/davinci0 \
    --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 "$MODEL_CACHE:/root/.cache" \
    -it "$IMAGE" bash

export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend \
    --net=host \
    --shm-size=1g \
    --device /dev/davinci0 \
    --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 "$MODEL_CACHE:/root/.cache" \
    -it "$IMAGE" bash

验证容器环境¶

在容器中运行以下命令。当输出包含 vLLM Ascend environment: OK 时，表示容器已准备就绪。

npu-smi info

python3 - <<'PY'
import torch
import vllm
import vllm_ascend

assert torch.npu.is_available(), "No available Ascend NPU detected in the container"
print("vLLM Ascend environment: OK")
PY

根据您的硬件和操作系统运行相应命令：

A2A3Atlas 300I DUO / Atlas 200I Pro950DT Products

UbuntuopenEuler

git clone --depth 1 --branch v0.23.0 \
    https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
docker build -t vllm-ascend-dev:latest -f Dockerfile .

git clone --depth 1 --branch v0.23.0 \
    https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
docker build -t vllm-ascend-dev:latest -f Dockerfile.openEuler .

UbuntuopenEuler

git clone --depth 1 --branch v0.23.0 \
    https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
docker build -t vllm-ascend-dev:latest -f Dockerfile.a3 .

git clone --depth 1 --branch v0.23.0 \
    https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
docker build -t vllm-ascend-dev:latest -f Dockerfile.a3.openEuler .

UbuntuopenEuler

git clone --depth 1 --branch v0.23.0 \
    https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
docker build -t vllm-ascend-dev:latest -f Dockerfile.310p .

git clone --depth 1 --branch v0.23.0 \
    https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
docker build -t vllm-ascend-dev:latest -f Dockerfile.310p.openEuler .

UbuntuopenEuler

git clone --depth 1 --branch v0.23.0 \
    https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
docker build -t vllm-ascend-dev:latest -f Dockerfile.a5 .

git clone --depth 1 --branch v0.23.0 \
    https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
docker build -t vllm-ascend-dev:latest -f Dockerfile.a5.openEuler .

此路径适用于官方CANN基础镜像，或已安装在主机或现有容器中的CANN。

准备CANN环境¶

使用CANN基础镜像使用现有的CANN安装

推荐的CANN基础镜像

硬件	Ubuntu	openEuler
Ascend A2系列产品	`quay.io/ascend/cann:9.1.0-910b-ubuntu22.04-py3.12`	`quay.io/ascend/cann:9.1.0-910b-openeuler24.03-py3.12`
Ascend A3系列产品	`quay.io/ascend/cann:9.1.0-a3-ubuntu22.04-py3.12`	`quay.io/ascend/cann:9.1.0-a3-openeuler24.03-py3.12`
Atlas 300I DUO	`quay.io/ascend/cann:9.1.0-310p-ubuntu22.04-py3.12`	`quay.io/ascend/cann:9.1.0-310p-openeuler24.03-py3.12`
Atlas 200I Pro	`quay.io/ascend/cann:9.1.0-310p-ubuntu22.04-py3.12`	`quay.io/ascend/cann:9.1.0-310p-openeuler24.03-py3.12`
950DT Products	`quay.io/ascend/cann:9.1.0-950-ubuntu22.04-py3.12`	`quay.io/ascend/cann:9.1.0-950-openeuler24.03-py3.12`

CANN基础镜像已包含Toolkit、目标硬件的算子包和NNAL。您无需在容器中重新安装CANN。有关其他操作系统和标签，请参阅CANN容器镜像概述。

选择您的硬件和操作系统，然后启动CANN容器：

A2A3Atlas 300I DUOAtlas 200I Pro950DT

拉取镜像¶

UbuntuopenEuler

export IMAGE=quay.io/ascend/cann:9.1.0-910b-ubuntu22.04-py3.12
docker pull "$IMAGE"

export IMAGE=quay.io/ascend/cann:9.1.0-910b-openeuler24.03-py3.12
docker pull "$IMAGE"

启动容器¶

UbuntuopenEuler

export DEVICE=/dev/davinci0
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend-cann \
    --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 "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

export DEVICE=/dev/davinci0
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend-cann \
    --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 "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

拉取镜像¶

UbuntuopenEuler

export IMAGE=quay.io/ascend/cann:9.1.0-a3-ubuntu22.04-py3.12
docker pull "$IMAGE"

export IMAGE=quay.io/ascend/cann:9.1.0-a3-openeuler24.03-py3.12
docker pull "$IMAGE"

启动容器¶

A3容器启动要求

A3采用双DIE设计，需要两个昇腾设备节点，例如/dev/davinci0和/dev/davinci1。

UbuntuopenEuler

export DEVICE0=/dev/davinci0
export DEVICE1=/dev/davinci1
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend-cann \
    --shm-size=1g \
    --device "$DEVICE0" \
    --device "$DEVICE1" \
    --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 "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

export DEVICE0=/dev/davinci0
export DEVICE1=/dev/davinci1
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend-cann \
    --shm-size=1g \
    --device "$DEVICE0" \
    --device "$DEVICE1" \
    --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 "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

拉取镜像¶

UbuntuopenEuler

export IMAGE=quay.io/ascend/cann:9.1.0-310p-ubuntu22.04-py3.12
docker pull "$IMAGE"

export IMAGE=quay.io/ascend/cann:9.1.0-310p-openeuler24.03-py3.12
docker pull "$IMAGE"

启动容器¶

UbuntuopenEuler

export DEVICE=/dev/davinci0
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend-cann \
    --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 "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

export DEVICE=/dev/davinci0
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend-cann \
    --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 "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

拉取镜像¶

UbuntuopenEuler

export IMAGE=quay.io/ascend/cann:9.1.0-310p-ubuntu22.04-py3.12
docker pull "$IMAGE"

export IMAGE=quay.io/ascend/cann:9.1.0-310p-openeuler24.03-py3.12
docker pull "$IMAGE"

启动容器¶

Atlas 200I Pro 容器启动要求

Atlas 200I Pro 需要额外的设备节点、驱动库和主机配置文件。在启动容器之前，请确保以下命令挂载的所有主机路径均存在。

UbuntuopenEuler

export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --privileged \
    --name vllm-ascend-cann \
    --shm-size=10g \
    --device=/dev/davinci0:/dev/davinci0 \
    --device=/dev/davinci_manager \
    --device=/dev/ascend_manager \
    --device=/dev/user_config \
    -v /etc/sys_version.conf:/etc/sys_version.conf \
    -v /etc/ld.so.conf.d/mind_so.conf:/etc/ld.so.conf.d/mind_so.conf \
    -v /etc/hdcBasic.cfg:/etc/hdcBasic.cfg \
    -v /var/dmp_daemon:/var/dmp_daemon \
    -v /usr/lib64/libmmpa.so:/usr/lib64/libmmpa.so \
    -v /usr/lib64/libcrypto.so.1.1:/usr/lib64/libcrypto.so.1.1 \
    -v /usr/local/sbin/npu-smi:/usr/local/sbin/npu-smi \
    -v /usr/lib64/libstackcore.so:/usr/lib64/libstackcore.so \
    -v /usr/lib/aarch64-linux-gnu/libyaml-0.so.2:/usr/lib64/libyaml-0.so.2 \
    -v /etc/slog.conf:/etc/slog.conf \
    -v /var/slogd:/var/slogd \
    -v /usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64 \
    -v /usr/lib64/libtensorflow.so:/usr/lib64/libtensorflow.so \
    -v "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --privileged \
    --name vllm-ascend-cann \
    --shm-size=10g \
    --device=/dev/davinci0:/dev/davinci0 \
    --device=/dev/davinci_manager \
    --device=/dev/ascend_manager \
    --device=/dev/user_config \
    -v /etc/sys_version.conf:/etc/sys_version.conf \
    -v /etc/ld.so.conf.d/mind_so.conf:/etc/ld.so.conf.d/mind_so.conf \
    -v /etc/hdcBasic.cfg:/etc/hdcBasic.cfg \
    -v /var/dmp_daemon:/var/dmp_daemon \
    -v /usr/lib64/libsemanage.so.2:/usr/lib64/libsemanage.so.2 \
    -v /usr/lib64/libmmpa.so:/usr/lib64/libmmpa.so \
    -v /usr/lib64/libcrypto.so.1.1:/usr/lib64/libcrypto.so.1.1 \
    -v /usr/lib64/libyaml-0.so.2.0.9:/usr/lib64/libyaml-0.so.2 \
    -v /usr/local/sbin/npu-smi:/usr/local/sbin/npu-smi \
    -v /usr/lib64/libstackcore.so:/usr/lib64/libstackcore.so \
    -v /etc/slog.conf:/etc/slog.conf \
    -v /var/slogd:/var/slogd \
    -v /usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64 \
    -v /usr/lib64/libtensorflow.so:/usr/lib64/libtensorflow.so \
    -v "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

拉取镜像¶

UbuntuopenEuler

export IMAGE=quay.io/ascend/cann:9.1.0-950-ubuntu22.04-py3.12
docker pull "$IMAGE"

export IMAGE=quay.io/ascend/cann:9.1.0-950-openeuler24.03-py3.12
docker pull "$IMAGE"

启动容器¶

UbuntuopenEuler

export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend-cann \
    --net=host \
    --shm-size=1g \
    --device /dev/davinci0 \
    --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 "$MODEL_CACHE:/root/.cache" \
    -it "$IMAGE" bash

export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend-cann \
    --net=host \
    --shm-size=1g \
    --device /dev/davinci0 \
    --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 "$MODEL_CACHE:/root/.cache" \
    -it "$IMAGE" bash

验证NNAL环境

确认/usr/local/Ascend/nnal/atb/set_env.sh和libatb.so可用。如果CANN安装在其他位置，请source相应的set_env.sh。如果运行时出现"libatb.so not found"错误，请确保手动安装步骤正确安装了NNAL。

source /usr/local/Ascend/ascend-toolkit/set_env.sh

if [ -f /usr/local/Ascend/nnal/atb/set_env.sh ]; then
    source /usr/local/Ascend/nnal/atb/set_env.sh
fi

export ASCEND_TOOLKIT_HOME="${ASCEND_TOOLKIT_HOME:-/usr/local/Ascend/ascend-toolkit/latest}"
npu-smi info

安装vLLM和vLLM Ascend¶

首先，安装容器操作系统的系统依赖，并配置 pip 镜像源。

对于 Ubuntu：

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 ninja-build libnuma-dev wget git curl jq

pip config set global.index-url "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

对于 openEuler：

yum update -y && yum install -y gcc g++ cmake ninja-build numactl-devel wget git curl jq patch

pip config set global.index-url "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

选择以下方法之一来安装 vllm 和 vllm-ascend。在此步骤中，PyTorch 和 TorchNPU 将作为依赖项自动安装，并使用所选版本对应的兼容版本。

安装方法对比

方法	包类型	硬件处理	适用场景
pip	预构建 wheel	安装标准的 `vllm-ascend` wheel，目前针对 A2	希望最简单安装的 A2 用户
uv	预构建 wheel	使用 WheelNext wheel 变体，根据检测到的硬件选择兼容的构建	希望根据硬件选择预构建 wheel 的用户
源码	源代码	为当前环境构建并安装 vLLM Ascend	开发、定制或没有合适预构建 wheel 的环境

pip 安装uv 安装源码安装

This installation method currently supports only A2 builds and does not automatically support A3, Atlas 300I DUO, Atlas 200I Pro, or 950DT Products. For other hardware, use a prebuilt image, WheelNext, or a source installation.

pip install \
    --extra-index-url https://download.pytorch.org/whl/cpu/ \
    "vllm==0.23.0"

pip install \
    --extra-index-url https://download.pytorch.org/whl/cpu/ \
    --extra-index-url https://mirrors.huaweicloud.com/ascend/repos/pypi \
    "vllm-ascend==0.23.0"

如果 pip 无法验证华为云镜像证书

华为云软件包索引使用 HTTPS，因此通常不需要 --trusted-host。如果 pip 对 mirrors.huaweicloud.com 报告 SSL 证书验证或不受信任的主机错误，请先更新 pip 和操作系统的 CA 证书，或配置您的网络所需的 CA 捆绑包。

在可信网络上的临时解决方案是，使用 --trusted-host mirrors.huaweicloud.com 重试 vLLM Ascend 安装命令。

此选项告诉 pip 即使在 HTTPS 验证失败时也信任该主机，这会削弱对中间人攻击的保护。仅在您信任网络且无法修复证书配置时使用。

检查设备构建类型：

python - <<'PY'
from vllm_ascend._build_info import __device_type__

print("vLLM Ascend wheel device type:", __device_type__)
assert __device_type__ == "A2", __device_type__
PY

WheelNext 从变体索引中选择与硬件匹配的 vLLM Ascend wheel。首先，安装并验证 uv：

# 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.23.0.
pip install "vllm==0.23.0"

# 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 \
    --find-links https://mirrors.huaweicloud.com/ascend/repos/pypi/triton-ascend/ \
    "vllm-ascend==0.23.0"

如果 uv 安装失败，请清除缓存

如果 uv pip install 因缓存损坏或软件包数据过期而失败，请在再次运行安装命令之前清除 uv 缓存：

uv cache clean

检查设备构建类型：

python - <<'PY'
from vllm_ascend._build_info import __device_type__
print("vLLM Ascend wheel device type:", __device_type__)
PY

A3 源码安装

在为 A3 从源码安装 vLLM Ascend 时，请手动运行 git submodule update --init --recursive，或确保环境具有互联网访问权限，以便自动下载所需的子模块。

先安装 vLLM，然后安装 vLLM Ascend：

# Install vLLM.
git clone --depth 1 --branch v0.23.0 https://github.com/vllm-project/vllm
cd vllm
VLLM_TARGET_DEVICE=empty pip install -e . \
    --extra-index-url https://download.pytorch.org/whl/cpu/
cd ..

# Install vLLM Ascend.
git clone --depth 1 --branch v0.23.0 https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
# git submodule update --init --recursive
pip install -e . \
    --extra-index-url https://download.pytorch.org/whl/cpu/ \
    --extra-index-url https://mirrors.huaweicloud.com/ascend/repos/pypi
cd ..

最后，根据硬件处理 triton 和 triton-ascend：

A2 / A3 / 950DT ProductsAtlas 300I DUO / Atlas 200I Pro

为确保 Triton Ascend 与当前 vLLM Ascend 版本匹配，请在安装相应版本的 triton-ascend 之前，移除任何现有的 triton 和 triton-ascend 软件包：

pip uninstall -y triton triton-ascend

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

社区 Triton 和 Triton Ascend 可以共存吗？

对于 Triton Ascend 3.2.0 及更早版本，请在安装 Triton Ascend 之前卸载社区 Triton。

对于 Triton Ascend 3.2.1 及更高版本，安装 Triton Ascend 会先安装所需的社区 Triton 软件包，然后在共享安装路径上提供其 Ascend 特定实现。如果之后重新安装或升级 Triton，可能会覆盖 Triton Ascend 文件。在这种情况下，请卸载这两个软件包并重新安装 Triton Ascend。

有关更多 Triton Ascend 安装指南，请参阅 Triton-Ascend > FAQ。

当安装其他版本的 vllm-ascend 时，请检查仓库的 requirements.txt 以获取相应的 triton-ascend 版本。

Atlas 300I DUO 和 Atlas 200I Pro 不支持 triton 或 triton-ascend。如果环境中已安装任一软件包，请将其卸载，并且不要重新安装 triton-ascend：

pip uninstall -y triton triton-ascend

此路径适用于需要自行管理用户态软件栈的高级用户。您可以在现有的Linux主机上安装，或从最小的Linux容器开始。

手动安装CANN¶

The official CANN Installation Resources are the authoritative installation reference.

The example commands are for A2 only

The commands below are for reference and install 910B Ops, which applies only to A2. For other hardware, including 950DT Products, use the matching Ops package according to the official guide.

以下命令使用默认的CANN和NNAL安装路径。如果您将任一组件安装在非默认目录中，请从实际安装目录中source相应的 set_env.sh。

Code

# 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.1.0/Ascend-cann-toolkit_9.1.0_linux-"$(uname -i)".run
chmod +x ./Ascend-cann-toolkit_9.1.0_linux-"$(uname -i)".run
./Ascend-cann-toolkit_9.1.0_linux-"$(uname -i)".run --full
source /usr/local/Ascend/ascend-toolkit/set_env.sh
export ASCEND_TOOLKIT_HOME="${ASCEND_TOOLKIT_HOME:-/usr/local/Ascend/ascend-toolkit/latest}"

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

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

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

安装vLLM和vLLM Ascend¶

首先，安装容器操作系统的系统依赖，并配置 pip 镜像源。

对于 Ubuntu：

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 ninja-build libnuma-dev wget git curl jq

pip config set global.index-url "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

对于 openEuler：

yum update -y && yum install -y gcc g++ cmake ninja-build numactl-devel wget git curl jq patch

pip config set global.index-url "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

选择以下方法之一来安装 vllm 和 vllm-ascend。在此步骤中，PyTorch 和 TorchNPU 将作为依赖项自动安装，并使用所选版本对应的兼容版本。

安装方法对比

方法	包类型	硬件处理	适用场景
pip	预构建 wheel	安装标准的 `vllm-ascend` wheel，目前针对 A2	希望最简单安装的 A2 用户
uv	预构建 wheel	使用 WheelNext wheel 变体，根据检测到的硬件选择兼容的构建	希望根据硬件选择预构建 wheel 的用户
源码	源代码	为当前环境构建并安装 vLLM Ascend	开发、定制或没有合适预构建 wheel 的环境

pip 安装uv 安装源码安装

This installation method currently supports only A2 builds and does not automatically support A3, Atlas 300I DUO, Atlas 200I Pro, or 950DT Products. For other hardware, use a prebuilt image, WheelNext, or a source installation.

pip install \
    --extra-index-url https://download.pytorch.org/whl/cpu/ \
    "vllm==0.23.0"

pip install \
    --extra-index-url https://download.pytorch.org/whl/cpu/ \
    --extra-index-url https://mirrors.huaweicloud.com/ascend/repos/pypi \
    "vllm-ascend==0.23.0"

如果 pip 无法验证华为云镜像证书

华为云软件包索引使用 HTTPS，因此通常不需要 --trusted-host。如果 pip 对 mirrors.huaweicloud.com 报告 SSL 证书验证或不受信任的主机错误，请先更新 pip 和操作系统的 CA 证书，或配置您的网络所需的 CA 捆绑包。

在可信网络上的临时解决方案是，使用 --trusted-host mirrors.huaweicloud.com 重试 vLLM Ascend 安装命令。

此选项告诉 pip 即使在 HTTPS 验证失败时也信任该主机，这会削弱对中间人攻击的保护。仅在您信任网络且无法修复证书配置时使用。

检查设备构建类型：

python - <<'PY'
from vllm_ascend._build_info import __device_type__

print("vLLM Ascend wheel device type:", __device_type__)
assert __device_type__ == "A2", __device_type__
PY

WheelNext 从变体索引中选择与硬件匹配的 vLLM Ascend wheel。首先，安装并验证 uv：

# 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.23.0.
pip install "vllm==0.23.0"

# 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 \
    --find-links https://mirrors.huaweicloud.com/ascend/repos/pypi/triton-ascend/ \
    "vllm-ascend==0.23.0"

如果 uv 安装失败，请清除缓存

如果 uv pip install 因缓存损坏或软件包数据过期而失败，请在再次运行安装命令之前清除 uv 缓存：

uv cache clean

检查设备构建类型：

python - <<'PY'
from vllm_ascend._build_info import __device_type__
print("vLLM Ascend wheel device type:", __device_type__)
PY

A3 源码安装

在为 A3 从源码安装 vLLM Ascend 时，请手动运行 git submodule update --init --recursive，或确保环境具有互联网访问权限，以便自动下载所需的子模块。

先安装 vLLM，然后安装 vLLM Ascend：

# Install vLLM.
git clone --depth 1 --branch v0.23.0 https://github.com/vllm-project/vllm
cd vllm
VLLM_TARGET_DEVICE=empty pip install -e . \
    --extra-index-url https://download.pytorch.org/whl/cpu/
cd ..

# Install vLLM Ascend.
git clone --depth 1 --branch v0.23.0 https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
# git submodule update --init --recursive
pip install -e . \
    --extra-index-url https://download.pytorch.org/whl/cpu/ \
    --extra-index-url https://mirrors.huaweicloud.com/ascend/repos/pypi
cd ..

最后，根据硬件处理 triton 和 triton-ascend：

A2 / A3 / 950DT ProductsAtlas 300I DUO / Atlas 200I Pro

为确保 Triton Ascend 与当前 vLLM Ascend 版本匹配，请在安装相应版本的 triton-ascend 之前，移除任何现有的 triton 和 triton-ascend 软件包：

pip uninstall -y triton triton-ascend

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

社区 Triton 和 Triton Ascend 可以共存吗？

对于 Triton Ascend 3.2.0 及更早版本，请在安装 Triton Ascend 之前卸载社区 Triton。

对于 Triton Ascend 3.2.1 及更高版本，安装 Triton Ascend 会先安装所需的社区 Triton 软件包，然后在共享安装路径上提供其 Ascend 特定实现。如果之后重新安装或升级 Triton，可能会覆盖 Triton Ascend 文件。在这种情况下，请卸载这两个软件包并重新安装 Triton Ascend。

有关更多 Triton Ascend 安装指南，请参阅 Triton-Ascend > FAQ。

当安装其他版本的 vllm-ascend 时，请检查仓库的 requirements.txt 以获取相应的 triton-ascend 版本。

Atlas 300I DUO 和 Atlas 200I Pro 不支持 triton 或 triton-ascend。如果环境中已安装任一软件包，请将其卸载，并且不要重新安装 triton-ascend：

pip uninstall -y triton triton-ascend

验证安装¶

前往快速开始 > 推理并运行一个简单的推理测试以验证安装。

其他指南¶

仅CPU构建验证¶

仅CPU构建验证用于检查在无可见昇腾设备的情况下能否构建Python包。它不验证NPU运行时加载、推理示例、自定义内核或NPU特定测试。构建过程需要访问CANN Toolkit的头文件和库，因此仍必须安装CANN Toolkit。

首先，安装 Python 构建后端和原生构建工具。可编辑安装直接使用 setuptools-scm。如果没有可用的兼容 wheel，arctic-inference 还需要 CMake 和 Ninja：

python -m pip install --upgrade \
    pip "setuptools>=64" "setuptools-scm>=8" wheel \
    attrs googleapis-common-protos \
    "cmake>=3.26" ninja

此工作流仅验证构建，因此不会安装 vLLM。若要在主分支上继续联合测试 vLLM 和 vLLM Ascend，请使用 .github/vllm-main-verified.commit 中记录的精确 vLLM 提交，并按如下所述验证组合环境。

在 x86 环境中，请在安装其余 Ascend 依赖之前，先从 PyTorch CPU 索引安装 CPU 版本的 PyTorch：

python -m pip install \
    --index-url https://download.pytorch.org/whl/cpu/ \
    torch==2.10.0 torchvision==0.25.0 torchaudio==2.10.0
python -m pip install \
    --extra-index-url https://mirrors.huaweicloud.com/ascend/repos/pypi \
    torch-npu==2.10.0.post4 triton-ascend==3.2.2
python -m pip install \
    --extra-index-url https://mirrors.huaweicloud.com/ascend/repos/pypi \
    -r requirements.txt

在构建 vLLM Ascend 之前，请显式设置构建目标并禁用自动设备后端加载：

当无 NPU 可见时，设置正确的 SOC_VERSION

如果当前环境中没有 npu-smi，请在运行 pip install -e . 之前为目标硬件设置 SOC_VERSION：

A2: export SOC_VERSION=ascend910b1
A3: export SOC_VERSION=ascend910_9391
Atlas 300I DUO / Atlas 200I Pro: export SOC_VERSION=ascend310p1
950DT Products: export SOC_VERSION=ascend950dt_9582

启用批量不变性

批量不变性需要 batch_invariant_ops wheel。在构建 vLLM Ascend 之前设置 VLLM_BATCH_INVARIANT=1，以便在安装流程中构建并安装该 wheel。有关使用说明，请参阅批量不变性。

export ASCEND_TOOLKIT_HOME="${ASCEND_TOOLKIT_HOME:-/usr/local/Ascend/ascend-toolkit/latest}"
export TORCH_DEVICE_BACKEND_AUTOLOAD=0
export COMPILE_CUSTOM_KERNELS=0
export SOC_VERSION=ascend910b1  # A2
python -m pip install \
    --no-build-isolation \
    --no-deps \
    --extra-index-url https://mirrors.huaweicloud.com/ascend/repos/pypi \
    -e .

上述显式构建依赖和 requirements.txt 在非隔离可编辑构建开始之前提供了完整的构建系统依赖。--no-build-isolation 仅复用当前构建环境中的包；它无法使不兼容的 vLLM、PyTorch 和 TorchNPU 版本变得兼容。在将环境用于实际工作负载之前，请运行 python -m pip check 并解决所有报告的冲突。如果没有可用设备，请跳过推理示例和 NPU 特定测试。

Note

构建自定义算子需要 gcc/g++ 版本高于 8 且支持 C++17 或更高版本。如果在运行 pip install -e . 时遇到 TorchNPU 版本冲突，请改用 pip install --no-build-isolation -e . 在系统环境中进行构建。

如果遇到其他编译问题，可能是因为使用了意外的编译器。编译前，请将 CXX_COMPILER 和 C_COMPILER 分别设置为 g++ 和 gcc 的位置。

多节点部署¶

依次检查物理链路、各节点状态以及节点间连通性。

物理链路要求¶

物理机器必须位于同一局域网内，并且能够相互通信。
所有 NPU 必须通过光模块连接，且所有连接必须健康。

950DT Products server precheck

This precheck applies only to 950DT Products servers. Other server series can skip it.

准备 HiXLEP 配置路径：

When deploying a 950DT Products inference service, confirm on each server that /lib/route.conf, /etc/hccl_rootinfo.json, and the /etc/hixlep directory that describes the UB link topology exist and are configured correctly. If any item is missing or misconfigured, follow the HiXLEP configuration file generation guide to generate the required content. Select the "D2D scenario" when generating /etc/hixlep.

检查每个节点¶

在每个节点上依次运行以下命令。命令结果应为 success，链路状态应为 UP：

A2A3950DT Products

# 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

# 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

验证节点间连通性¶

获取 NPU IP 地址¶

A2A3950DT Products

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

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

运行跨节点 ping 测试¶

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

在每个节点上启动容器¶

使用快速开始 > 安装中描述的官方 vLLM Ascend 容器，快速准备一致的多节点运行时环境。
多节点模型服务的命令不在本安装指南的范围内。请继续参阅相关的功能教程或模型教程。