使徒

Windows 下 Docker 使用 GPU 运行 vLLM 嵌入式模型

前言

最近需要在本地部署 Qwen3-Embedding-0.6B 模型，利用 vLLM 提供 OpenAI 风格的 Embeddings API。我的电脑是 Windows 系统，显卡为 NVIDIA GTX 1070，打算使用 Docker 容器运行模型以隔离环境。然而，Windows 上的 Docker 默认无法访问 GPU，需要经过一系列配置才能打通 WSL 2 + NVIDIA Container Toolkit 的链路。本文记录了从零开始到成功调用 API 的全部步骤及踩坑点，方便日后回忆。

环境概览

  • 操作系统：Windows 10/11（支持 WSL 2）

  • GPU：NVIDIA GeForce GTX 1070（8GB 显存）

  • Docker Desktop for Windows（使用 WSL 2 后端）

  • 目标模型：Qwen/Qwen3-Embedding-0.6B

  • 服务镜像：vllm/vllm-openai:latest

第一步：启用 WSL 2 并安装 Ubuntu 发行版

Docker Desktop 的 GPU 支持依赖于 WSL 2，因此首先需要确保 WSL 2 已正确安装。

  1. 以管理员身份打开 PowerShell，执行一键安装命令：

    powershell

    wsl --install

    该命令会自动启用 WSL 和虚拟机平台，并安装默认的 Ubuntu 发行版。

  2. 重启电脑。

  3. 重启后，在开始菜单中找到 Ubuntu 并启动，根据提示设置用户名和密码（本文使用用户名 administrator）。

  4. 确认 WSL 版本为 2：

    powershell

    wsl --list --verbose

    输出示例：

    text

      NAME              STATE           VERSION
* Ubuntu            Running         2
  docker-desktop    Running         2

注意：如果已安装 Docker Desktop，通常会自动出现 docker-desktop 发行版，这属于正常现象。

第二步：安装并配置 Docker Desktop

  1. 从 Docker 官网 下载 Docker Desktop for Windows 并安装。

  2. 安装完成后，右键系统托盘中的 Docker 图标，选择 Settings → General，确保勾选 Use the WSL 2 based engine。

  3. 进入 Resources → WSL Integration，打开你的 Ubuntu 发行版（例如 Ubuntu）的开关，并勾选 Enable integration with my default WSL distro。

  4. 点击 Apply & Restart。

此时，在 Ubuntu 终端中应该可以直接运行 docker --version 而不会报错。

第三步：在 WSL 2 中安装 NVIDIA Container Toolkit

Windows 主机上的 Docker 实际运行在 WSL 2 内部，因此需要在 WSL 的 Ubuntu 环境中安装 NVIDIA 容器工具包。

  1. 打开 Ubuntu 终端。

  2. 添加 NVIDIA 软件源并安装：

    bash

    # 更新包列表
sudo apt update

# 添加 NVIDIA GPG 密钥（新方法）
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

# 添加 apt 源（适用于 Ubuntu 22.04/24.04）
echo 'deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://nvidia.github.io/libnvidia-container/stable/deb/amd64 /' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# 安装 toolkit
sudo apt update
sudo apt install -y nvidia-container-toolkit

  3. 配置 Docker 运行时：

    bash

    sudo nvidia-ctk runtime configure --runtime=docker

  4. 生成 CDI 规范（可选，但建议执行）：

    bash

    sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

  5. 重启 Docker 守护进程（在 WSL 终端中执行）：

    bash

    sudo service docker restart

    如果提示 service not found，则直接在 Windows 任务栏中重启 Docker Desktop 图标即可。

第四步：验证 GPU 是否可用

在 Ubuntu 终端中运行以下测试命令：

bash

sudo docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu20.04 nvidia-smi

如果能看到类似下面的输出（显示你的 GPU 信息），说明 GPU 已成功挂载到容器中：

text

Thu Apr  2 13:44:36 2026
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 580.105.07             Driver Version: 581.80         CUDA Version: 13.0     |
|-------------------------------+----------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
|   0  NVIDIA GeForce GTX 1070        On  | 00000000:01:00.0  On |                  N/A |
+-----------------------------------------------------------------------------------------+

权限问题：如果遇到 permission denied while trying to connect to the docker API，请使用 sudo 执行 docker 命令，或者将当前用户加入 docker 组：

bash

sudo usermod -aG docker $USER
newgrp docker

第五步：编写 docker-compose.yml 启动 vLLM

在项目目录（例如 D:\dockerCompose）中创建 docker-compose.yml，内容如下：

yaml

version: "3.9"

services:
  vllm:
    image: vllm/vllm-openai:latest
    container_name: vllm-embedding
    ports:
      - "8080:8000"
    environment:
      - HF_ENDPOINT=https://hf-mirror.com   # 使用 Hugging Face 镜像加速下载
    volumes:
      - ./hf_cache:/root/.cache/huggingface  # 缓存模型文件
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    command: >
      --model Qwen/Qwen3-Embedding-0.6B
      --host 0.0.0.0
      --port 8000
      --gpu-memory-utilization 0.65 # 可选降低 GPU 显存占用比例
      --max-model-len 4096  # 限制最大序列长度
    restart: unless-stopped

关键点说明：

  • deploy.resources.reservations.devices 是声明使用 GPU 的标准方式。

  • command 中不要再写 serve 子命令，因为镜像的 ENTRYPOINT 已经默认为 vllm serve。

  • 模型名称通过 --model 指定（未来版本可能会改为位置参数，但当前可用）。

  • 使用 HF_ENDPOINT 环境变量指向国内镜像站，加快模型下载速度。

第六步：启动服务并测试

  1. 在 docker-compose.yml 所在目录执行：

    bash

    sudo docker-compose up -d

  2. 查看启动日志（模型首次下载可能需要几分钟）：

    bash

    sudo docker-compose logs -f

    当看到类似 Uvicorn running on http://0.0.0.0:8000 的输出时，表示服务已就绪。

  3. 测试 Embeddings API（使用 curl）：

    bash

    curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello world",
    "model": "Qwen/Qwen3-Embedding-0.6B"
  }'

    成功的话会返回一个 JSON，其中包含 embedding 向量数组和 usage 信息。

踩坑记录与解决方案

坑1：libcuda.so.1: cannot open shared object file

原因：未安装 NVIDIA Container Toolkit，或未正确配置 Docker 使用 GPU。

解决：按第三步安装 toolkit 并重启 Docker。

坑2：Unsupported distribution!（Ubuntu 24.04）

原因：NVIDIA 官方 apt 源尚未明确标记支持 Ubuntu 24.04。

解决：手动添加通用 deb 源（如上文中的 echo 命令），或使用 ubuntu22.04 版本源。

坑3：unrecognized arguments: serve

原因：镜像的 ENTRYPOINT 已经是 vllm serve，又在 command 中重复写了 serve。

解决：command 中只写模型名和参数，不写子命令。

坑4：permission denied 连接 Docker API

原因：当前用户不在 docker 组。

解决：使用 sudo 运行 docker 命令，或者 sudo usermod -aG docker $USER 后重新登录 WSL。

坑5：模型下载缓慢

原因：Hugging Face 默认外网访问慢。

解决：在 docker-compose.yml 中添加 HF_ENDPOINT=https://hf-mirror.com 环境变量，或手动挂载已下载的缓存目录。

坑6：GTX 1070 与 vLLM 不兼容

原因：CUDA error: no kernel image is available for execution on the device，vLLM 官方镜像中的 PyTorch 要求 Compute Capability ≥ 7.0（如 GTX 1080 Ti、RTX 20 系列及以上）

解决：换个电脑重新装，原本想废物利用呢...

总结

经过以上步骤，我们成功在 Windows + WSL2 + Docker 环境中实现了 GPU 加速的 vLLM 服务，可以对外提供 Embedding 能力。整个过程虽然有些曲折，但理解底层原理后并不复杂。核心就是：

  • Windows 的 Docker 实际运行在 WSL2 虚拟机中；

  • 要让容器使用 GPU，需要在 WSL2 中安装 NVIDIA Container Toolkit，并声明 --gpus 或 deploy.devices；

  • vLLM 镜像的入口参数有特定格式，需仔细阅读官方文档或错误提示。

希望这篇博客能帮助你在未来快速复现这套环境，也欢迎分享给遇到同样问题的朋友。如果有任何改进建议或新的踩坑经历，欢迎留言交流。

site logo

Hi,Friend

© 2026 使徒