企业官网建设流程全解析

• 人工智能
• 大模型
• 模型推理服务
• Ascend
• CANN

本文基于 vllm-ascend 仓库的官方 Quick Start 文档（quick_start.md），讲解如何在已就绪的 Ascend 主机上，使用预构建的 vLLM Ascend Docker 镜像跑通第一个离线推理任务、部署第一个vllm serve在线服务。读完本文，你将掌握五类硬件（A2、A3、950DT Products、Atlas 300I DUO、Atlas 200I Pro）各自的镜像拉取与容器启动方式、容器环境验证方法，以及两条硬件路径（标准路径与 310p 路径）的离线/在线推理配置差异，并能理解这些配置背后的源码实现。

一、开始之前：环境要求与硬件支持矩阵

快速上手的前置条件很明确：

• 操作系统：Linux；
• Python：>= 3.10, < 3.13（这是宿主机/源码安装口径，预构建镜像内实际使用 Python 3.12，见 mkdocs.yml 中release_python_version与release_image_python_version两个变量的区分）；
• Docker（用于容器方式）；
• 支持硬件，官方矩阵如下：

预构建镜像内已经包含一套经过整体验证的 Python 与 Ascend 用户态软件栈，包括 CANN、NNAL、PyTorch、TorchNPU、vLLM 和 vLLM Ascend。按 mkdocs.yml 记录的当前发布文档栈，验证组合为：Ascend HDK26.0.RC1、CANN Toolkit + Ops9.1.0、NNAL9.1.0、PyTorch2.10.0、TorchNPU2.10.0.post4、Triton Ascend3.2.2、vLLM Ascendv0.23.0。需要特别注意：A2、A3 和 950DT Products 的镜像还包含对应版本的 Triton Ascend 运行时，而 Atlas 300I DUO 和 Atlas 200I Pro 不使用 Triton Ascend——这一差异会直接影响后文的镜像 tag 与运行时配置。

各镜像对应的版本组合是作为一个整体验证的，不要自行混用不同发布的版本；如需其他发布版本，可参考 Installation Guide 中“Hardware and software stack”一节的完整兼容性表格。

镜像 tag 规则与下载加速

镜像统一发布在quay.io，四类硬件对应不同 tag 后缀（以{{ vllm_ascend_version }}=v0.23.0为例）：

如果直接访问quay.io下载缓慢，可以只替换注册中心前缀、完整保留原镜像 tag 的后缀（如-a3、-310p、-openeuler）来加速拉取。例如原始地址为quay.io/ascend/vllm-ascend:<TAG>时，文档给出了两个替代前缀：m.daocloud.io/quay.io/ascend/vllm-ascend:$TAG或quay.nju.edu.cn/ascend/vllm-ascend:$TAG。

二、拉取镜像并启动容器

不同硬件的docker run参数差异主要在三处：挂载的 NPU 设备节点数量、网络模式、以及宿主机配置文件的挂载清单。以下命令均需在宿主机执行，进入容器后再做后续验证。

A2（单设备节点）

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0 # openEuler 使用 -openeuler 后缀 docker pull "$IMAGE" 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

参数要点：--shm-size=1g提供共享内存；--device逐项放行 NPU 设备节点（/dev/davinci0）与管理节点（davinci_manager、devmm_svm、hisi_hdc）；-v挂载驱动库、npu-smi与安装信息文件，保证容器内能识别 NPU；$MODEL_CACHE挂到容器内/root/.cache，使模型权重缓存在宿主机上、跨容器复用；-p 8000:8000为后文在线服务预留端口。

A3（双 DIE，需要两个设备节点）

A3 采用双 DIE 设计，启动前需要确认/dev/davinci0和/dev/davinci1两个设备节点都存在，并在docker run中同时放行：

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-a3 # openEuler 使用 -a3-openeuler 后缀 docker pull "$IMAGE" 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

Atlas 300I DUO（单设备节点）

镜像使用-310p后缀，启动命令与 A2 基本一致（同样只放行/dev/davinci0等单个设备节点），此处不再重复完整命令，可对照 atlas-300i-duo.inc.md 与 A2 小节逐参数比对。

Atlas 200I Pro（需要额外设备节点与宿主机文件）

Atlas 200I Pro 要求更多：--privileged权限、--shm-size=10g的共享内存，以及一批额外的驱动库和宿主机配置文件。启动前必须确认命令中挂载的所有宿主机路径真实存在：

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-310p # openEuler 使用 -310p-openeuler 后缀 docker pull "$IMAGE" 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

注意 Ubuntu 与 openEuler 的挂载清单略有差异：openEuler 版本额外挂载libsemanage.so.2，并且 yaml 库的实际文件名是libyaml-0.so.2.0.9（映射到容器内的libyaml-0.so.2），npu-smi位于/usr/local/sbin/而非/usr/local/bin/。

950DT Products（host 网络 + hccn_tool）

950DT 使用-a5后缀镜像。与其他硬件最大的区别是：不映射 8000 端口，改用--net=host，并且额外挂载hccn_tool工具目录：

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-a5 # openEuler 使用 -a5-openeuler 后缀 docker pull "$IMAGE" 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

这条验证逻辑是两段式的：npu-smi info确认驱动层面能看到 NPU 设备；Python 断言则确认 TorchNPU 设备后端真正可用（torch.npu.is_available()），同时确认vllm与vllm_ascend两个包都能被导入——这也是仓库 CI 中 doctest 的验证点之一（见下文“第七节”）。

四、模型来源：Hugging Face 与 ModelScope

如果运行环境无法稳定访问 Hugging Face，模型下载可能因连接超时、DNS 错误等网络问题失败，可以切换到 ModelScope：

export VLLM_USE_MODELSCOPE=True pip install "modelscope>=1.18.1,<1.38"

如果模型已经下载到本地，则无需设置该环境变量，只需把下文示例中的模型 ID（Qwen/Qwen3-0.6B）替换为本地目录路径即可。仓库中同样保留了 offline_inference_npu.py 这类示例脚本，其开头就设置了VLLM_USE_MODELSCOPE=True，可直接参考。

五、离线推理

离线推理分两条硬件路径，两条路径的 Qwen3-0.6B 示例均经过官方验证（validated）。

路径一：A2 / A3 / 950DT Products（默认加载配置）

在容器内创建example.py：

from vllm import LLM, SamplingParams prompts = [ "Hello, my name is", "The future of AI is", ] sampling_params = SamplingParams( temperature=0.0, max_tokens=32, ) llm = LLM(model="Qwen/Qwen3-0.6B") outputs = llm.generate(prompts, sampling_params) assert len(outputs) == len(prompts) for output in outputs: generated_text = output.outputs[0].text assert generated_text.strip() print(f"Prompt: {output.prompt!r}, Generated text: {generated_text!r}")

运行：

python3 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 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

路径二：Atlas 300I DUO / Atlas 200I Pro（310p 运行时要求）

310p 路径有三个硬性运行时要求：

• 使用float16；
• 使用FULL_DECODE_ONLY图模式并限制图捕获尺寸；
• enable_npugraph_ex不受支持，需显式关闭。

对应的example.py如下（相比标准路径多传了dtype、max_num_seqs、compilation_config和additional_config四组参数）：

from vllm import LLM, SamplingParams MODEL = "Qwen/Qwen3-0.6B" prompts = [ "Hello, my name is", "The future of AI is", ] llm = LLM( model=MODEL, dtype="float16", max_num_seqs=8, compilation_config={ "cudagraph_mode": "FULL_DECODE_ONLY", "cudagraph_capture_sizes": [1, 2, 4, 8], }, additional_config={ "ascend_compilation_config": { "enable_npugraph_ex": False, }, }, ) sampling_params = SamplingParams( temperature=0.0, max_tokens=32, ) outputs = llm.generate(prompts, sampling_params) assert len(outputs) == len(prompts) for output in outputs: generated_text = output.outputs[0].text assert generated_text.strip() print(f"Prompt: {output.prompt!r}, Generated text: {generated_text!r}")

python3 example.py

运行成功后的平台检测日志、生成结果与无害退出日志，与标准路径完全相同，此处不再重复。

源码视角：这些 310p 配置项是如何生效的

enable_npugraph_ex是 vLLM Ascend 编译配置的字段，定义在 ascend_config.py 的AscendCompilationConfig中（默认值为True）。该数据类的after校验器会调用get_current_hardware_profile()检查硬件能力：当当前硬件 profile 不支持HardwareCapability.NPUGRAPH_EX时，npugraph_ex、static_kernel、super_kernel会被级联禁用并打印 warning。能力枚举本身定义在 hardware_profile.py。

另外，platform.py 中有一段与cudagraph_mode相关的处理逻辑：当模式为NONE或走 piecewise 编译（分段编译）时，会把ascend_compilation_config中的enable_npugraph_ex、enable_static_kernel、enable_super_kernel一并置为False；对于不支持的 cudagraph 模式则回退到NONE。从源码结构看，310p 路径要求FULL_DECODE_ONLY且关闭enable_npugraph_ex，正是为了让图捕获只覆盖 decode 阶段、并绕开该硬件上不支持的 npugraph 扩展优化，这也解释了为什么cudagraph_capture_sizes要显式限定为[1, 2, 4, 8]这样的小尺寸集合。

六、在线服务（vllm serve）

路径一：A2 / A3 / 950DT Products

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)

查询模型列表：

curl --fail http://localhost:8000/v1/models

发送一条补全请求：

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

判断成功的关键标准：响应中choices[0].text包含非空的生成文本；错误响应或空补全都不算推理成功。

路径二：Atlas 300I DUO / Atlas 200I Pro

310p 路径把离线示例中的参数映射到了命令行参数上，与第五节的一一对应关系是：dtype="float16"→--dtype float16；max_num_seqs=8→--max-num-seqs 8；compilation_config→--compilation-configJSON；additional_config→--additional-configJSON：

vllm serve Qwen/Qwen3-0.6B \ --dtype float16 \ --max-num-seqs 8 \ --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY","cudagraph_capture_sizes":[1,2,4,8]}' \ --additional-config '{"ascend_compilation_config":{"enable_npugraph_ex":false}}' &

启动成功日志、模型列表查询与补全请求的验证方式与标准路径相同。

优雅停止服务

vLLM 以后台进程方式运行时，可以用kill -2（即 SIGINT）优雅停止，效果等价于前台进程按Ctrl+C：

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

⚠️ 如果当前环境还有其他vllm serve进程，pgrep -f "vllm serve"可能匹配到那些服务，执行kill前务必确认VLLM_PID是本示例启动的服务，避免误杀。正常停止会输出：

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

最后按Ctrl+D退出容器。

七、这些步骤如何被自动验证

快速上手文档并不是“写完即止”的静态文本：仓库的 doctest 框架会把文档中带<!-- doctest: ... -->标记的代码块提取出来，在真实硬件上逐块执行。001-quickstart-test.sh 的run_quickstart函数按硬件选择标记前缀（a2→quickstart-standard，310p→quickstart-300i-duo），依次执行模型源配置（quickstart-modelscope）、容器环境验证（quickstart-container-verify）、离线示例（*-offline/*-offline-run）与在线示例（*-online-serve→ 轮询localhost:8000/v1/models就绪 →*-online-model-list→*-online-completion→*-online-stop，最后等待进程退出）。这意味着本文引用的每一条命令、每段 Python 代码，在对应硬件上都是被 CI 反复跑通的，可复制性有测试背书。

八、下一步

• Supported Models：选择其他受支持模型；
• Model Tutorials：具体模型的部署教程；
• Installation Guide：pip、CANN 环境与源码安装三种路径的软件环境搭建；
• Feature Tutorials：分布式部署与高级特性；
• FAQ：常见部署问题的排查。

• 人工智能
• 大模型
• 模型推理服务
• Ascend
• CANN