在 Windows 系统上借助 WSL2与 NVIDIA GPU 运行 vLLM

vLLM 无法直接在 Windows 上运行。目前推荐的方案是借助 WSL2与 Docker 以及 NVIDIA 容器工具包，这样既能实现完整的 GPU 直通，又能直接调用 Linux 端的各类推理工具，无需进行双系统配置。本指南将详细介绍如何在配备 NVIDIA GPU 的 Windows 11系统上完成整个部署流程。

最近测试时间：七月 2026。目前已有社区贡献的补丁试图实现 Windows 原生支持，但该补丁尚未被纳入正式版本。在此之前，WSL2搭配 Docker 仍是最稳妥的部署方案。

前置条件

Windows 11 系统（版本需为 22H2 或更高），且需启用 WSL2 功能
1 块或更多 NVIDIA GPU，驱动版本 ≥535
已安装并启用 WSL2后端的 Docker Desktop for Windows
至少 16 GB 系统内存（建议 32 GB，适用于 ≥13B 的模型）

步骤 1：安装支持 GPU 的 WSL2

以管理员身份打开 PowerShell 并执行 WSL2安装指令：

wsl --install

此操作会默认安装 Ubuntu。重启后，请确认 WSL 内核版本：

uname -r

要实现 GPU 直通功能，内核版本需达到 ≥5.15。如有需要，请执行更新操作：

sudo apt update && sudo apt upgrade -y

请确认在 WSL2 环境中能够检测到您的 GPU：

nvidia-smi

此时您应能看到带有正确驱动版本的 GPU 信息。若 nvidia-smi 未检测到任何设备，请将 Windows 下的 NVIDIA 驱动更新至 ≥535 版本并重启 WSL：

wsl --shutdown

步骤 2：安装带有 NVIDIA Container Toolkit 的 Docker

在 Windows 系统中安装 Docker Desktop。
打开 Docker Desktop 设置界面，确保 Use the WSL 2 based engine 选项已被勾选。
在 Resources → WSL Integration 页面中，启用您所使用的 Ubuntu 发行版。

进入 WSL2 环境后，安装 NVIDIA Container Toolkit：

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

安装完成后，请重启 Docker 服务：

sudo service docker restart

步骤 3：利用 Docker Compose 启动 vLLM

创建一个 docker-compose.yml 格式的文件：

docker-compose.yml

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    ports:
      - "8000:8000"
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    command: >
      --model Qwen/Qwen2.5-7B-Instruct
      --gpu-memory-utilization 0.9
      --max-model-len 8192

启动容器：

docker compose up -d

在模型下载与加载期间请留意日志信息：

docker compose logs -f vllm

当看到 Uvicorn running on http://0.0.0.0:8000 时，说明服务器已准备就绪。

步骤 4：验证功能是否正常

从 WSL2 内部发送测试请求：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-7B-Instruct",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

预期响应内容为一个 JSON 对象，其中含有包含模型回复内容的 choices 数组。

多 GPU 配置（MCDM）

WSL2 借助微软计算驱动模型实现了多 GPU 张量并行运算。该模式取代了旧版的 TCC 模式，且要求 NVIDIA 驱动版本不低于 535。

切换至 MCDM 模式

在 Windows 主机上打开管理员权限的命令提示符：

nvidia-smi -g 0 -dm 0

针对每台 GPU 重复上述操作（将 0 替换为对应 GPU 编号），随后重启系统。重启后请确认所有 GPU 均能在 WSL2 中被识别：

nvidia-smi

启用张量并行运算模式启动

更新您的 docker-compose.yml 命令以启用多 GPU 支持：

    command: >
      --model Qwen/Qwen2.5-72B-Instruct
      --tensor-parallel-size 2
      --gpu-memory-utilization 0.9
      --max-model-len 4096

张量并行机制可将各层计算任务分配到多个 GPU 上执行；在单节点多 GPU 环境中，该机制比流水线并行更为适用，且能显著提升解码阶段的处理效率。

从 Windows 主机发起连接

WSL2 运行于一个具备独立网络环境的轻量级虚拟机中。借助 Docker 的端口映射功能，localhost:8000 端口会被自动从 WSL2 虚拟机转发至 Windows 主机，如此您便能从各类 Windows 应用程序访问 vLLM 服务：

curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d "{\"model\": \"Qwen/Qwen2.5-7B-Instruct\", \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}]}"

若 localhost 端口转发未能生效，可查询 WSL2 的 IP 地址并直接通过该地址进行访问：

hostname -I

随后在 Windows 端执行相应操作：

curl http://<WSL2_IP>:8000/v1/chat/completions ...

每次重启后 WSL2 的 IP 地址均会发生变化。若您直接依赖该 IP 地址，则每次重启后都需重新配置相关设置。因此只要条件允许，请优先采用 localhost 端口转发方案。

利用 Tokios 连接器公开您的服务端点

在 WSL2 环境中运行 vLLM 虽可实现本地推理，但仅限本机访问。建议在 WSL2 环境中将 Tokios 连接器与 vLLM 容器一同部署，如此即可通过安全隧道对外发布模型服务，任何设备均可访问而无需配置端口转发或防火墙规则：

# Inside WSL2, install and pair the connector
curl -fsSL https://install.tokios.com | bash
tokios-connector pair

完成配对后，在 Models 选项卡中注册您的 vLLM 部署实例并生成相应的 API 密钥。自此您的模型服务即可通过 https://api.tokios.com/v1 地址供全球用户调用。完整操作流程可参阅连接器安装指南。

故障排查

在 WSL 环境中未能检测到 GPU2

您的 NVIDIA 驱动版本过旧，或者 WSL2 内核已过时。请将 Windows 端的 NVIDIA 驱动更新至 ≥535 版本，随后在 PowerShell 中执行 wsl --update 命令，最后通过 wsl --shutdown 命令重启 WSL。

找不到 CUDA 内核映像

特定版本的 vLLM（v0.22/v0.23）所附带的 CUDA 内核无法适配所有 WSL2 版本的 CUDA 工具包。建议将 Docker 镜像固定至经过验证的标签，例如 vllm/vllm-openai:v0.21.0，而不要使用 latest。

多 GPU 环境下出现内存不足情况

vLLM 为 CUDA 计算图预留的显存容量高于 Ollama。若某个 32B 模型在 2x 型号的 RTX 3090 显卡上出现内存不足问题，可尝试将 --gpu-memory-utilization 的数值调低至 0.85，或者减少 --max-model-len 的设置值。

Docker 容器随即退出

请确认 Docker Desktop 已为您的发行版启用了 WSL2 集成功能。执行 docker compose logs vllm 命令可查看容器退出的具体原因，通常是因为缺少 GPU 驱动或模型路径配置有误。

多 GPU 动态负载均衡功能未启用

如果 WSL2 内的 nvidia-smi 在多 GPU 系统上仅显示 1 块 GPU，则 MCDM 可能未启用。请在 Windows 主机上针对每块 GPU 运行 nvidia-smi -g <GPU_ID> -dm 0，然后重启。

Windows 原生支持情况说明

SystemPanic 社区成员开发的分支版本让 vLLM 能够在 Windows 原生环境下运行，无需依赖 WSL2 或 Docker。该代码提交于 2025 年初，但尚未被合并至正式版本中。您可前往 vLLM GitHub 代码库查看相关进展。在稳定版本正式提供原生支持之前，在 Windows 系统上部署生产环境的最佳方案便是使用 WSL2 搭配 Docker。

后续步骤

vLLM 远程访问

借助 Tokios 即可让任何设备都能访问你的 vLLM 服务器，完全无需配置端口转发。

模型适配性

了解哪些模型能够适配你所用 GPU 的显存容量，以及预期能达到的处理效率。

硬件与适配

服务与连接运行时

连接客户端或应用

对比

在 Windows 系统上借助 WSL2与 NVIDIA GPU 运行 vLLM

前置条件

步骤 1：安装支持 GPU 的 WSL2

步骤 2：安装带有 NVIDIA Container Toolkit 的 Docker

步骤 3：利用 Docker Compose 启动 vLLM

步骤 4：验证功能是否正常

多 GPU 配置（MCDM）

切换至 MCDM 模式

启用张量并行运算模式启动

从 Windows 主机发起连接

利用 Tokios 连接器公开您的服务端点

故障排查

Windows 原生支持情况说明

后续步骤

vLLM 远程访问

模型适配性

​前置条件

​步骤 1：安装支持 GPU 的 WSL2

​步骤 2：安装带有 NVIDIA Container Toolkit 的 Docker

​步骤 3：利用 Docker Compose 启动 vLLM

​步骤 4：验证功能是否正常

​多 GPU 配置（MCDM）

​切换至 MCDM 模式

​启用张量并行运算模式启动

​从 Windows 主机发起连接

​利用 Tokios 连接器公开您的服务端点

​故障排查

​Windows 原生支持情况说明

​后续步骤

vLLM 远程访问

模型适配性

前置条件

步骤 1：安装支持 GPU 的 WSL2

步骤 2：安装带有 NVIDIA Container Toolkit 的 Docker

步骤 3：利用 Docker Compose 启动 vLLM

步骤 4：验证功能是否正常

多 GPU 配置（MCDM）

切换至 MCDM 模式

启用张量并行运算模式启动

从 Windows 主机发起连接

利用 Tokios 连接器公开您的服务端点

故障排查

Windows 原生支持情况说明

后续步骤