Atlas 300I DUO 上快速部署 vLLM Ascend：官方镜像拉取与容器启动全流程详解

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

本文聚焦 vLLM Ascend 官方预构建镜像在 Atlas 300I DUO（Atlas 推理系列 Ascend 硬件）上的快速部署路径：从选择并拉取带-310p后缀的镜像，到通过docker run完成设备与驱动目录的挂载启动，再到容器内环境验证。读完后，你可以在一台已装好 Ascend 驱动的主机上，独立完成从镜像获取到容器就绪的全过程，并理解镜像内部软件栈与该硬件专属运行时路径的设计。

硬件背景与镜像选型：为什么是-310p标签

vLLM Ascend 面向多种 Ascend 硬件产品线提供不同的官方镜像。根据仓库内的受支持硬件清单（supported_hardware.inc.md），Atlas 300I DUO 与 Atlas 200I Pro 同属 “Atlas inference series products”（Atlas 推理系列），二者共享同一套运行时路径，即310p路径，对应的 SoC 版本为ascend310p1（参见 安装指南 中 CPU-only 构建验证一节的SOC_VERSION说明）。

在官方镜像列表（prebuilt_image.inc.md）中，Atlas 300I DUO / Atlas 200I Pro 对应两个标签：

当前仓库中记录的发布版本为v0.23.0（见 mkdocs.yml 中的vllm_ascend_version变量），文档模板中的{{ vllm_ascend_version }}占位符在渲染时会替换为该版本号。拉取镜像时请保留完整标签后缀（-310p、-310p-openeuler），只替换 registry 前缀。

前置条件：宿主机准备

使用预构建镜像路径时，宿主机只需要两样东西：

• 可用的 Ascend 驱动与固件；
• 已安装并运行正常的 Docker。

先执行以下命令确认 NPU 固件和驱动安装正确，能够识别 Atlas 300I DUO 设备：

npu-smi info

预构建镜像内置了经过验证的完整用户态软件栈，包括 CANN、NNAL、PyTorch、TorchNPU、vLLM 和 vLLM Ascend（见 Quick Start 的 Requirements 一节）。需要注意一个硬件差异：A2、A3 和 950DT 产品的镜像还包含 Triton Ascend 运行时，而Atlas 300I DUO 和 Atlas 200I Pro 不使用 Triton Ascend，-310p镜像中不会安装它。

第一步：拉取镜像

根据宿主机操作系统选择对应标签（以下与 atlas-300i-duo.inc.md 中的命令一致）：

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

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

镜像下载加速

vLLM Ascend 镜像默认从quay.io下载。如果直连速度较慢，可以按 镜像加速说明 使用 registry 镜像站。例如原始地址为：

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

可替换为（只替换 registry 前缀，完整保留原标签）：

# 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

官方明确提醒：只替换 registry 前缀，必须完整保留包括-310p、-openeuler在内的标签后缀，否则拉取到的将不是针对 Atlas 300I DUO 验证过的镜像。

第二步：启动容器

Atlas 300I DUO 是板卡形态的推理卡，容器启动时需要把 NPU 设备节点和宿主机上的驱动文件挂载进容器。Ubuntu 与 openEuler 两套命令完全一致：

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

关键参数逐项解析

DEVICE变量默认指向/dev/davinci0，表示使用第一块 Atlas 300I DUO；如果宿主机插有多块推理卡，可按需调整该值。MODEL_CACHE指定模型权重缓存位置，挂进容器后，首次下载的模型在后续重启容器时无需重复拉取。

第三步：容器环境验证

进入容器后执行以下命令完成环境验证（来自 verify_container.inc.md）。当输出包含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 设备；import vllm_ascend触发平台插件注册——vLLM 启动时会扫描vllm.platform_plugins插件组，日志中出现Platform plugin ascend is activated即表示vllm_ascend的NPUPlatform已被激活；torch.npu.is_available()断言 TorchNPU 与设备后端已连通。

深入镜像内部：-310p镜像是如何构建的

从 Dockerfile.310p（openEuler 版本为 Dockerfile.310p.openEuler）可以看到官方镜像的组装方式，这也解释了上文几个关键特性：

• 基础镜像：quay.io/ascend/cann:9.1.0-310p-ubuntu22.04-py3.12，即 CANN 9.1.0 的 310p 专用底座，Python 3.12；
• vLLM 版本：默认克隆 vLLMv0.30.0标签（VLLM_TAG），支持用VLLM_COMMIT指定精确 commit；
• SOC 版本：构建期固定SOC_VERSION=ascend310p1，用于编译 310p 专属自定义算子（COMPILE_CUSTOM_KERNELS=1）；
• 移除 x86 版 Triton：Dockerfile 中显式pip uninstall -y triton与triton-ascend——因为 Ascend 设备上标准 Triton 无法正常工作，这正对应了文档中 “310p 不使用 Triton Ascend” 的说明；
• 驱动守护进程：镜像内的entrypoint.sh会启动/var/slogd（日志）与/var/dmp_daemon（驱动管理）等守护进程，并按驱动规范创建HwHiAiUser、HwDmUser等用户与/var/driver、/var/dmp、/usr/slog目录。

因此宿主机侧只需驱动 + Docker，容器内即获得完整且版本互验过的 CANN/NNAL/PyTorch/TorchNPU/vLLM/vLLM Ascend 栈——这套版本组合是作为整体兼容性集合验证发布的，不建议跨版本混配（见 安装指南 的 “Validated hardware and software stack” 表格）。

容器内的 310p 运行时路径

进入容器后，vLLM Ascend 如何感知 Atlas 300I DUO 这块硬件？从源码结构看，vllm_ascend/platform.py 中定义的NPUPlatform是 vLLM 的 OOT（out-of-tree）平台插件，device_name为npu，设备控制环境变量为ASCEND_RT_VISIBLE_DEVICES，dispatch key 使用 PyTorch 的PrivateUse1。而在 hardware_profile.py 中，310p 硬件路径默认绑定了专属 worker：vllm_ascend._310p.worker_310p.NPUWorker310；platform.py 中还注册了 310p 专用的 attention 后端vllm_ascend._310p.attention.attention_v1.AscendAttentionBackend310。也就是说，Atlas 300I DUO 上运行的不是 A2/A3 的通用代码路径，而是仓库内_310p子包提供的独立实现，这正是镜像需要按硬件区分标签（-310p）的底层原因。

这些命令示例并非只存在于文档中：仓库的 doctest 脚本 001-quickstart-test.sh 会针对310p设备（marker_prefix=quickstart-300i-duo）自动执行容器验证、离线推理与在线服务全流程，保证 Quick Start 文档中的命令持续可用。

下一步：310p 路径的推理注意事项

容器就绪后，可以继续 Quick Start 中 Atlas 300I DUO 对应的 Qwen3-0.6B 离线推理与在线服务示例。该硬件路径有明确的运行时约束（310p 专属，务必遵守）：

• 使用float16数据类型；
• 使用FULL_DECODE_ONLY模式并限制图捕获规模，例如"cudagraph_capture_sizes": [1, 2, 4, 8]；
• 不支持enable_npugraph_ex，需通过additional_config显式关闭：{"ascend_compilation_config": {"enable_npugraph_ex": false}}。

以在线服务为例：

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}}' &

服务启动后（日志出现Uvicorn running on http://0.0.0.0:8000），即可用之前映射的 8000 端口访问/v1/models、/v1/completions等 OpenAI 兼容接口；如需更换模型或深入分布式部署，可参考 支持模型列表 与 常见问题。若 Hugging Face 访问受限，可在容器内设置VLLM_USE_MODELSCOPE=True并安装modelscope切换模型下载源。

附：自行构建 310p 镜像

如果需要对镜像做定制（例如固定 vLLM commit、调整依赖），可以用仓库内的 Dockerfile 手动构建（见 prebuilt_image.inc.md 对应章节的正确路径为 docs/source/getting_started/installation/prebuilt_image.inc.md）：

# Ubuntu git clone --depth 1 --branch v0.23.0 \ https://gitcode.com/gh_mirrors/vl/vllm-ascend.git cd vllm-ascend docker build -t vllm-ascend-dev:latest -f Dockerfile.310p .

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

构建参数均可通过docker build --build-arg覆盖，常用项包括VLLM_COMMIT（精确 vLLM commit）、VLLM_TAG（vLLM 标签）、SOC_VERSION（默认ascend310p1）与COMPILE_CUSTOM_KERNELS（默认1，控制是否编译自定义 Ascend 算子）。构建完成后，后续启动与验证流程与前文完全一致。

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