快速入门

快速入门#

简介#

本节以Qwen3-0.6B离线单GPU推理脚本为例，指导您完成基于容器的环境搭建和大模型推理。

关于不同模型的使用详情，请参见"模型教程"目录中对应的模型教程，例如Qwen3-30B-A3B。
有关使用不同功能的详细信息，请参阅“功能教程”目录中相应的功能教程，例如，预填充-解码分离（DeepSeek）。

前提条件#

支持的设备#

Atlas A2训练系列（Atlas 800T A2、Atlas 900 A2 PoD、Atlas 200T A2 Box16、Atlas 300T A2）
Atlas 800I A2推理系列（Atlas 800I A2）
Atlas A3训练系列（Atlas 800T A3、Atlas 900 A3 SuperPoD、Atlas 9000 A3 SuperPoD）
Atlas 800I A3推理系列（Atlas 800I A3）
Atlas 950DT推理系列（Atlas 950DT）
Atlas 300I DUO
Atlas 200I Pro

要求#

Atlas A2/A3/950DT推理产品

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

软件：

软件	支持的版本	注意
Ascend HDK	请参阅 CANN 9.1.0 版本说明	CANN 所需
CANN	== 9.1.0	vllm-ascend 和 TorchNPU 所需
TorchNPU	== 2.10.0.post4	vllm-ascend 所需，无需手动安装，将在以下步骤中自动安装
torch	== 2.10.0	TorchNPU 和 vllm 所需，无需手动安装，将在以下步骤中自动安装
NNAL	== 9.1.0	libatb.so 所需，支持高级张量运算

备注

Atlas 300I DUO 使用 CANN 9.1.0 和 float16。对于 Ubuntu 使用 -310p 镜像后缀，对于 openEuler 使用 -310p-openeuler。Atlas 300I DUO 不支持 triton 或 triton-ascend。

Atlas 300I DUO 和 Atlas 200I Pro 不支持 enable_npugraph_ex。请设置 --additional-config '{"ascend_compilation_config": {"enable_npugraph_ex":false}}'。

Atlas 200I Pro需要额外的设备节点和驱动挂载。完整的容器命令请参见使用Docker设置。

Atlas 300I DUO

软件	支持的版本	注意
Ascend HDK	请参阅 CANN 9.1.0 版本说明	CANN 所需
CANN	== 9.1.0	vllm-ascend 和 TorchNPU 所需
TorchNPU	== 2.10.0.post4	vllm-ascend 所需，无需手动安装，将在以下步骤中自动安装
torch	== 2.10.0	TorchNPU 和 vllm 所需，无需手动安装，将在以下步骤中自动安装
NNAL	== 9.1.0	libatb.so 所需，支持高级张量运算
triton / triton-ascend	不支持	在 `Dockerfile.310p` 中未安装

使用容器搭建环境#

在使用容器之前，请确保您的系统已安装 Docker。如果尚未安装 Docker，请参阅 Docker 安装指南获取安装说明。

Ubuntu

# Update DEVICE according to your device (/dev/davinci[0-7])
export DEVICE=/dev/davinci0
# Update the vllm-ascend image
# Atlas A2:
# export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0
# Atlas A3:
# export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-a3
# Atlas 950DT:
# export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-950dt
export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0
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 /root/.cache:/root/.cache \
-p 8000:8000 \
-it $IMAGE bash
# Install curl
apt-get update -y && apt-get install -y curl

Ubuntu (Atlas 300I DUO)

以下命令适用于 Atlas 300I DUO。对于 Atlas 200I Pro，请使用安装中记录的额外设备节点和驱动挂载。

# Update DEVICE according to your device (/dev/davinci[0-7])
export DEVICE=/dev/davinci0
# Update the vllm-ascend image
export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-310p
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 /root/.cache:/root/.cache \
-p 8000:8000 \
-it $IMAGE bash
# Install curl
apt-get update -y && apt-get install -y curl

openEuler

# Update DEVICE according to your device (/dev/davinci[0-7])
export DEVICE=/dev/davinci0
# Update the vllm-ascend image
# Atlas A2:
# export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-openeuler
# Atlas A3:
# export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-a3-openeuler
# Atlas 950DT:
# export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-950dt-openeuler
export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-openeuler
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 /root/.cache:/root/.cache \
-p 8000:8000 \
-it $IMAGE bash
# Install curl
yum update -y && yum install -y curl

openEuler (Atlas 300I DUO)

以下命令适用于 Atlas 300I DUO。对于 Atlas 200I Pro，请使用安装中记录的额外设备节点和驱动挂载。

# Update DEVICE according to your device (/dev/davinci[0-7])
export DEVICE=/dev/davinci0
# Update the vllm-ascend image
export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-310p-openeuler
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 /root/.cache:/root/.cache \
-p 8000:8000 \
-it $IMAGE bash
# Install curl
yum update -y && yum install -y curl

默认工作目录为/workspace，vLLM和vLLM Ascend代码位于/vllm-workspace，并以开发模式（pip install -e）安装，帮助开发者即时生效更改，无需重新安装。

使用方法#

您可以使用ModelScope镜像加速下载：

export VLLM_USE_MODELSCOPE=True

在昇腾NPU上启动vLLM有两种方式：

离线批量推理

安装vLLM后，您可以开始为输入提示列表生成文本（即离线批量推理）。

创建并运行一个简单的推理测试。example.py可以如下所示：

from vllm import LLM, SamplingParams
prompts = [
    "Hello, my name is",
    "The future of AI is",
]
sampling_params = SamplingParams(temperature=0.8, top_p=0.95)
# The first run will take about 3-5 mins (10 MB/s) to download models
llm = LLM(model="Qwen/Qwen3-0.6B")

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

备注

如果在Atlas 950DT上运行推理时遇到自定义算子安全校验错误，请参考池化使能950DT和950PR的UB和UBoE并运行以下命令：

运行第一条命令时，每个NPU都会提示确认。您必须为所有NPU手动输入Y。

for i in {0..7}; do npu-smi set -t custom-op-secverify-enable -i $i -d 1; done;
for i in {0..7}; do npu-smi set -t custom-op-secverify-mode -i $i -d 0; done;

此部分显示vllm中成功检测到昇腾平台：

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

OpenAI Completions API

vLLM也可以部署为实现OpenAI API协议的服务器。运行以下命令，使用Qwen/Qwen3-0.6B模型启动vLLM服务器：

# Deploy vLLM server (The first run will take about 3-5 mins (10 MB/s) to download models)
vllm serve Qwen/Qwen3-0.6B &

如果您看到如下日志：

INFO:     Started server process [3594]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

恭喜，您已成功启动vLLM服务器！

您可以查询模型列表：

curl http://localhost:8000/v1/models | python3 -m json.tool

您也可以使用输入提示查询模型：

curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen3-0.6B",
        "prompt": "Beijing is a",
        "max_completion_tokens": 5,
        "temperature": 0
    }' | python3 -m json.tool

vLLM作为后台进程运行，您可以使用kill -2 $VLLM_PID优雅地停止后台进程，类似于使用Ctrl-C停止前台vLLM进程：

VLLM_PID=$(pgrep -f "vllm serve")
kill -2 "$VLLM_PID"

输出如下：

INFO:     Shutting down FastAPI HTTP server.
INFO:     Shutting down
INFO:     Waiting for application shutdown.
INFO:     Application shutdown complete.

最后，您可以使用ctrl-D退出容器。