通过 vLLM 为 NVIDIA DGX Spark 部署 Qwen3.5-122B 模型

记录在 NVIDIA DGX Spark 中使用 [[vLLM]] 部署 [[Qwen3.5]] 大模型时的环境配置和在国内网络下的资源下载，以防忘记。

另外在写的时候才发现 uv 也有 uvx 命令了，这样一些临时脚本直接用 uvx 执行就行了，方便许多。

环境准备

显卡驱动

等开机配置和更新完成进入桌面后，先通过 [[nvidia-smi]] 命令查看显卡驱动是否已经安装（默认都已经安装）：

1
nvidia-smi

如果正确返回表示正常：

1
+-----------------------------------------------------------------------------------------+
2
| NVIDIA-SMI 580.82.09              Driver Version: 580.82.09      CUDA Version: 13.0     |
3
+-----------------------------------------+------------------------+----------------------+
4
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
5
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
6
|                                         |                        |               MIG M. |
7
|=========================================+========================+======================|
8
|   0  NVIDIA GB10                    Off |   0000000F:01:00.0 Off |                  N/A |
9
| N/A   60C    P0             12W /  N/A  | Not Supported          |      2%      Default |
10
|                                         |                        |                  N/A |
11
+-----------------------------------------+------------------------+----------------------+
12

13
+-----------------------------------------------------------------------------------------+
14
| Processes:                                                                              |
15
|  GPU   GI   CI              PID   Type   Process name                        GPU Memory |
16
|        ID   ID                                                               Usage      |
17
|=========================================================================================|
18
|    0   N/A  N/A           62018      C   VLLM::EngineCore                      70109MiB |
19
+-----------------------------------------------------------------------------------------+

如果报错 Command 'nvidia-smi' not found，则先通过 apt 命令安装 NVIDIA 显卡驱动：

1
# 先查看可用版本
2
apt search nvidia-driver | grep "nvidia-driver-5"
3

4
# 然后执行安装
5
sudo apt install nvidia-driver-570

待安装完成后重启系统：

1
sudo reboot

Docker 环境

[[docker]] 同样如此，先确认是否安装：

1
docker --version
2
# 正常返回：Docker version 28.3.3, build 980b856
3

4
# 再查看 Compose 是否安装
5
docker compose version
6
# 正常返回：Docker Compose version v2.39.1

如果没有安装参考笔记 [[docker]]，如果已安装直接修改 docker 权限：

1
sudo usermod -aG docker $USER

操作完成后退出终端重新进入，就可以用普通用户的权限执行 docker 命令了。

修改镜像源

在国内使用还需要额外修改 Docker 镜像源：

1
sudo mkdir -p /etc/docker
2
sudo tee /etc/docker/daemon.json <<-'EOF'
3
{
4
    "registry-mirrors": [
5
        "https://docker.1ms.run"
6
    ]
7
}
8
EOF

修改完成后执行 sudo systemctl restart docker 让配置生效。

安装运行时库

为了 Docker 能正确识别到显卡，还需要额外安装 [[nvidia-container-toolkit]]，先配置存储库:

1
curl -fsSL https://mirrors.ustc.edu.cn/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
2
  && curl -s -L https://mirrors.ustc.edu.cn/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
3
    sed 's#deb https://nvidia.github.io#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://mirrors.ustc.edu.cn#g' | \
4
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

然后更新软件包并安装 nvidia-container-toolkit：

1
sudo apt update && sudo apt install nvidia-container-toolkit -y

如果 apt update 时出现以下报错：

W: GPG 错误：https://workbench.download.nvidia.com/stable/linux/debian default InRelease: 下列签名无效： EXPKEYSIG CD63F8B21266DE3C svc-workbench [email protected] E: 仓库 “https://workbench.download.nvidia.com/stable/linux/debian default InRelease” 没有数字签名。 N: 无法安全地用该源进行更新，所以默认禁用该源。 N: 参见 apt-secure(8) 手册以了解仓库创建和用户配置方面的细节。

先更新密钥，然后再重新运行 sudo apt update && sudo apt install nvidia-container-toolkit -y：

1
curl -fsSL https://workbench.download.nvidia.com/stable/linux/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/ai-workbench-desktop-key.gpg

集成到 Docker 配置中：

1
sudo nvidia-ctk runtime configure --runtime=docker

重启 Docker 并验证：

1
sudo systemctl restart docker
2
docker info | grep -i runtime

正常返回 Default Runtime: runc。

资源下载

无论是镜像还是模型都比较大，下载耗时，建议在 [[tmux]] 中执行对应命令。

vLLM 镜像

对于 Qwen 3.5 模型，必须使用 nightly 镜像（截止 2026-03 月）：

1
docker pull vllm/vllm-openai:nightly

镜像有 20 G，会比较花时间。

下载 Qwen3.5 模型

安装 [[uv]] 包管理器用于执行 [[huggingface_hub]] 下载模型：

1
# 安装 uv
2
curl -LsSf https://astral.sh/uv/install.sh | sh

安装完成后先设置环境变量加速下载：

1
export HF_HUB_DOWNLOAD_TIMEOUT=300
2
export HF_ENDPOINT=https://hf-mirror.com

然后直接通过 uvx 执行 hf 命令下载 Qwen 3.5 模型：

1
uvx hf download Qwen/Qwen3.5-122B-A10B-GPTQ-Int4

hf 是 huggingface-hub 最新的命令行工具，替代原有的 huggingface-cli 命令。

模型下载完成后默认保存在 ~/.cache/huggingface 目录（与下文 Docker 挂载路径一致），非必要不建议修改。

部署 Qwen

因为实际使用中不需要太长的上下文，而且也不需要 thinking，因为对这两方面都进行了限制：

1
services:
2
  vllm:
3
    container_name: vllm
4
    restart: unless-stopped
5
    image: vllm/vllm-openai:nightly
6
    runtime: nvidia
7
    ports:
8
      - "8000:8000"
9
    volumes:
10
      - ${HOME}/.cache/huggingface:/root/.cache/huggingface
11
    environment:
12
      - HF_HUB_OFFLINE=1
13
      - CUDA_VISIBLE_DEVICES=0
14
    command:
15
      - Qwen/Qwen3.5-122B-A10B-GPTQ-Int4
16
      - --tensor-parallel-size=1
17
      - --quantization=moe_wna16
18
      - --api-key=${VLLM_API_KEY}
19
      - '--default-chat-template-kwargs={"enable_thinking": false}'
20
      - --enable-prefix-caching
21
      - --max-num-batched-tokens=16384
22
      - --max-model-len=8192
23
      - --gpu-memory-utilization=0.93
24
      - --mm-encoder-tp-mode=data
25
      - --mm-processor-cache-type=shm
26
    ipc: host
27
    shm_size: "16gb"
28
    logging:
29
      driver: json-file
30
      options:
31
        max-size: "100m"

DGX Spark 如果在使用过程中如果 OOM，可以先尝试加上 swap，如果不行再降 --gpu-memory-utilization：

1
sudo fallocate -l 32G /swapfile
2
sudo chmod 600 /swapfile
3
sudo mkswap /swapfile
4
sudo swapon /swapfile

也是出问题才发现 Spark 默认是没配置 swap 的。