用于推理的 vLLM

在 DGX Spark 上安装并使用 vLLM

概述

操作指令

故障排除

基本思路

vLLM 是一个推理引擎，旨在高效运行大型语言模型。其核心思想是：最大化吞吐量并最小化内存浪费为LLM提供服务时。

它使用了一种名为的内存高效注意力算法。PagedAttention 能够处理长序列而不会耗尽 GPU 内存。
可以通过以下方式将新请求添加到已在处理的批次中：continuous batching 保持GPU充分利用。
它有一个 OpenAI-compatible API 因此，为 OpenAI API 构建的应用程序可以切换到 vLLM 后端，几乎无需修改。

您将完成

您将使用 Blackwell 架构在 DGX Spark 上设置 vLLM 高吞吐量 LLM 服务，可以使用预构建的 Docker 容器，也可以从源代码构建，并为 ARM64 提供自定义的 LLVM/Triton 支持。

前置知识

具备使用 Docker 构建和配置容器的经验
熟悉 CUDA 工具包的安装和版本管理
了解 Python 虚拟环境和包管理
具备使用 CMake 和 Ninja 从源代码构建软件的知识
具备 Git 版本控制和补丁管理经验

先决条件

基于ARM64 处理器和 Blackwell GPU 架构的 DGX Spark 设备
已安装 CUDA 13.0 工具包：nvcc --version 可以显示 CUDA 工具包版本。
Docker 已安装并配置：docker --version 成功
已安装 NVIDIA 容器工具包
Python 3.12 可用：python3.12 --version 成功
Git 已安装：git --version 成功
通过网络访问下载软件包和容器镜像

模型支持矩阵

以下模型支持在 Spark 上使用 vLLM 。所有列出的模型均可用，包括：


模型	量化方案	Hugging Face 标识
Qwen3-8B	FP8	nvidia/Qwen3-8B-FP8
Qwen3-8B	NVFP4	nvidia/Qwen3-8B-FP4
Qwen3-14B	FP8	nvidia/Qwen3-14B-FP8
Qwen3-14B	NVFP4	nvidia/Qwen3-14B-FP4
Qwen3-32B	NVFP4	nvidia/Qwen3-32B-FP4
Qwen2.5-VL-7B-Instruct	NVFP4	nvidia/Qwen2.5-VL-7B-Instruct-FP4
Qwen3-VL-Reranker-2B	Base	Qwen/Qwen3-VL-Reranker-2B
Qwen3-VL-Reranker-8B	Base	Qwen/Qwen3-VL-Reranker-8B
Qwen3-VL-Embedding-2B	Base	Qwen/Qwen3-VL-Embedding-2B

注意：

您可以参考 NVFP4 量化文档，为自己喜爱的模型生成 NVFP4 量化检查点。这样，即使对于 NVIDIA 尚未发布的模型，您也能利用 NVFP4 量化带来的性能和内存优势。

提醒：并非所有模型架构都支持 NVFP4 量化。

时间和风险

预计时间：Docker 方法耗时 30 分钟
风险等级： 容器注册表访问需要内部凭据
回滚：容器式方法属于非破坏性方法。
最后更新时间：2026 年 1 月 22 日
- 新增对 Qwen3-VL-Reranker-2B、Qwen3-VL-Reranker-8B 和 Qwen3-VL-Embedding-2B 模型的支持
- 容器已更新至 2026 年 1 月版本 (26.01-py3)

第 1 步 – 配置 Docker 权限

要轻松管理容器而无需使用 sudo，您必须处于 docker 组中。如果您选择跳过此步骤，则需要使用 sudo 运行 Docker 命令。
打开一个新的终端并测试 Docker 访问权限。在终端中运行：

docker ps

如果您看到权限被拒绝错误（例如 permission denied while trying to connect to the Docker daemon socket），请将您的用户添加到 docker 组，这样就不再需要使用 sudo 命令。

sudo usermod -aG docker $USER
newgrp docker

第 2 步 – 拉取 vLLM 容器镜像

从以下位置查找最新的容器：https://catalog.ngc.nvidia.com/orgs/nvidia/containers/vllm

export LATEST_VLLM_VERSION=<latest_container_version>

# example
# export LATEST_VLLM_VERSION=26.01-py3

docker pull nvcr.io/nvidia/vllm:${LATEST_VLLM_VERSION}

docker pull nvcr.io/nvidia/vllm:26.01-py3

第 3 步 - 在容器中测试 vLLM

启动容器并使用测试模型启动 vLLM 服务器，以验证基本功能。

docker run -it --gpus all -p 8000:8000 \
nvcr.io/nvidia/vllm:${LATEST_VLLM_VERSION} \
vllm serve "Qwen/Qwen2.5-Math-1.5B-Instruct"

预期输出应包括：

Model loading confirmation
Server startup on port 8000
GPU memory allocation details

在另一个终端中，测试服务器：

curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
    "model": "Qwen/Qwen2.5-Math-1.5B-Instruct",
    "messages": [{"role": "user", "content": "12*17"}],
    "max_tokens": 500
}'

预期回复应包含"content": "204" 或类似的数学计算。

第 4 步 - 清理和回滚

对于容器式方法（非破坏性）：

docker rm $(docker ps -aq --filter ancestor=nvcr.io/nvidia/vllm:${LATEST_VLLM_VERSION})
docker rmi nvcr.io/nvidia/vllm

第 5 步 - 后续步骤

生产环境部署：根据您的具体模型要求配置 vLLM
性能调优：调整工作负载的批处理大小和内存设置
监控：设置生产环境的日志记录和指标收集
模型管理：探索其他模型和量化选项

在单个 Spark 上运行的常见问题


错误	原因	修复
CUDA 版本不匹配错误	CUDA toolkit 版本错误	使用正确的安装程序重装 CUDA 12.9
容器注册表身份验证失败	GitLab 令牌无效或已过期	生成新的身份验证令牌
SM_121a 架构无法识别	缺少 LLVM 补丁	验证 SM_121a 补丁是已应用于 LLVM 源码