从零开始：在 Windows 10 + WSL2 + RTX 2080 Ti 上用 vLLM 部署 Qwen3-4B

本文按“新 Windows 环境 → WSL2 → GPU → Python/vLLM → 本地模型 → API 验收”组织，采用当前机器已经跑通的原生 Python 虚拟环境方案。最终得到一个监听 8000 端口的 OpenAI-compatible 服务。

已验证环境：Windows 10、WSL2 Ubuntu、NVIDIA GeForce RTX 2080 Ti（约 22 GB，compute capability 7.5）、Python 3.12.3、vLLM 0.24.0、Qwen3-4B、本地 FP16 推理。

0. 开始前先确认边界

这篇文档只解决单机单卡部署。

准备事项：

• Windows 10 版本至少为 2004（Build 19041）且已开启硬件虚拟化。
• 安装适用于 Windows 的 NVIDIA 驱动；不要在 WSL2 内另装 Linux NVIDIA 驱动。
• 预留足够磁盘空间给模型、Python 环境和 Hugging Face 缓存。
• 以下 Linux 命令均在 Ubuntu 的 WSL2 终端执行；标为“PowerShell（管理员）”的命令则在 Windows 执行。

1. 安装 WSL2 与 Ubuntu

以管理员身份打开 PowerShell，安装 WSL 与 Ubuntu：

wsl --install -d Ubuntu

安装完成后重启 Windows。首次打开 Ubuntu 时，按提示创建 Linux 用户名和密码。

回到 PowerShell，确认发行版确实运行在 WSL 2：

wsl --update
wsl --status
wsl -l -v

wsl -l -v 中 Ubuntu 的 VERSION 应为 2。如果不是，执行：

wsl --set-version Ubuntu 2

wsl --install 会安装所需组件及默认的 Ubuntu；新安装默认使用 WSL 2。较旧的 Windows 10 如未识别 -d 参数，可先执行 wsl --install，再用 wsl --list --online 查询可安装发行版。

2. 初始化 Ubuntu

进入 Ubuntu 后，先更新系统并安装常用依赖：

sudo apt update
sudo apt upgrade -y
sudo apt install -y build-essential ca-certificates curl git

建议在 Linux 家目录中存放模型与环境，不要把大模型放在 /mnt/c/... 这类 Windows 挂载盘中：

mkdir -p ~/llm/models

3. 安装 Windows NVIDIA 驱动并验证 WSL2 GPU

从 NVIDIA 驱动下载页 安装与你的显卡和 Windows 版本匹配的驱动，重启后在 Windows PowerShell 中检查：

nvidia-smi

再进入 Ubuntu，执行同一命令：

nvidia-smi

两处都应识别出 GPU。当前机器的实测结果是 NVIDIA GeForce RTX 2080 Ti，显存约 22 GB、compute capability 7.5。

这里不需要额外在 WSL2 内安装 Linux NVIDIA 驱动。若 Ubuntu 中的 nvidia-smi 不可用，先解决 Windows 驱动或 WSL 更新问题，再继续安装 vLLM。

4. 安装 uv，创建独立的 vLLM 环境

本机使用 uv 管理 Python 和虚拟环境。安装它：

curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"
uv --version

创建工作目录和 Python 3.12 虚拟环境：

mkdir -p ~/llm/vllm-nightly
cd ~/llm/vllm-nightly

uv venv --python 3.12 .venv
source .venv/bin/activate

为避免终端或环境迁移后残留旧路径，显式修正环境变量：

export VIRTUAL_ENV="$HOME/llm/vllm-nightly/.venv"
export PATH="$VIRTUAL_ENV/bin:$PATH"
hash -r

5. 安装 vLLM 与模型下载工具

以下命令复现的是当前环境使用的 nightly wheel 安装方式；记录中最终可用版本为 vLLM 0.24.0：

uv pip install -U vllm \
  --torch-backend=auto \
  --extra-index-url https://wheels.vllm.ai/nightly

uv pip install -U huggingface_hub

安装后不要直接启动模型，先确认 Python 能找到正确的 vLLM 和 CUDA：

python -c "import vllm; print('vllm', vllm.__version__, vllm.__file__)"
python -c "import torch; print('cuda', torch.cuda.is_available(), torch.cuda.get_device_name(0))"

预期现象是 cuda True，并显示 NVIDIA GeForce RTX 2080 Ti。如果激活环境后 python 或 vllm 不可用，重新执行第 4 节中的 VIRTUAL_ENV、PATH 和 hash -r 三行。

6. 下载 Qwen3-4B 到本地目录

将模型提前下载到本地，服务启动时只读取本地文件，便于排查下载与推理两类问题：

mkdir -p ~/llm/models/Qwen3-4B

hf download Qwen/Qwen3-4B \
  --local-dir ~/llm/models/Qwen3-4B

下载中断时，直接重试同一命令即可；--local-dir 会在目标目录创建 .cache/huggingface/ 元数据，用于避免重复下载已完成的文件。下载完成后，至少确认目录不是空的：

test -f ~/llm/models/Qwen3-4B/config.json && echo "model files ready"

如果模型仓库需要授权，先执行 hf auth login，再下载；不要把访问令牌写入命令行、笔记或 Git 仓库。

7. 启动 Qwen3-4B 服务

每次启动前都进入并激活环境。当前 WSL2 环境还需要设置 pinned-memory 兼容变量；此前缺失它时出现过 Engine core initialization failed。

cd ~/llm/vllm-nightly
source .venv/bin/activate

export VIRTUAL_ENV="$HOME/llm/vllm-nightly/.venv"
export PATH="$VIRTUAL_ENV/bin:$PATH"
export VLLM_WSL2_ENABLE_PIN_MEMORY=1
hash -r

然后启动服务：

python -m vllm.entrypoints.openai.api_server \
  --model ~/llm/models/Qwen3-4B \
  --served-model-name qwen3-4b \
  --host 0.0.0.0 \
  --port 8000 \
  --dtype float16 \
  --max-model-len 4096 \
  --gpu-memory-utilization 0.75 \
  --trust-remote-code

这组参数的设计是先稳定运行，再谈优化：

参数	当前取值	为什么这样设置
--model	~/llm/models/Qwen3-4B	服务端加载的本地模型路径。
--served-model-name	qwen3-4b	客户端 API 请求中填写的模型名；它不是 Hugging Face 仓库名。
--dtype	float16	RTX 2080 Ti 不支持 BF16，FP16 是本机已验证路径。
--max-model-len	4096	单请求输入与输出合计的上限；长度越大，对 KV Cache 的显存需求越高。
--gpu-memory-utilization	0.75	vLLM 的显存规划预算比例；它不是 GPU-Util，调高可能引发 OOM。

启动成功时，本机记录中可看到 Using V1 LLM engine (v0.24.0)、Using TRITON_ATTN attention backend 与 Application startup complete.。RTX 2080 Ti 未走 FlashAttention-2 而选择 TRITON_ATTN 是预期兼容行为。

8. 验收 API

保持服务进程运行，在另一个 WSL2 终端执行：

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/v1/models

再发送一条 Chat Completions 请求：

curl http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3-4b",
    "messages": [
      {"role": "user", "content": "用一句话介绍 vLLM。"}
    ],
    "temperature": 0
  }'

当前记录已验证 /health、/v1/models 与 /v1/chat/completions 可用，且模型被识别为 Qwen3ForCausalLM。

9. 常见问题

现象	原因	处理
WSL2 中没有 nvidia-smi	Windows 驱动、WSL 更新或 GPU 透传未就绪	回到第 3 节逐层检查；不要在 WSL2 内另装 Linux 驱动。
python / vllm 指向错误或不可用	.venv 留下旧绝对路径	重设 VIRTUAL_ENV、PATH，执行 hash -r。
Engine core initialization failed	本机 WSL2 缺少 pinned-memory 兼容设置	导出 VLLM_WSL2_ENABLE_PIN_MEMORY=1 后重启服务。
请求提示 Connection refused	服务还未完成模型加载或未监听 8000	先检查服务终端日志，再访问 /health。
看到 TRITON_ATTN 而不是 FlashAttention-2	RTX 2080 Ti 的硬件能力不满足 FA2 路径	保持 FP16 与 Triton 后端；这是本机的正常回退。
压测时访问 Hugging Face 并报 401	把 qwen3-4b 服务别名误当作模型或 tokenizer 路径	在压测命令中显式传 ~/llm/models/Qwen3-4B 给 --model 和 --tokenizer。

10. 部署成功后再做什么

基础服务稳定后再进行性能测试。当前机器在 512 → 128 tokens 的短请求负载下已有基线：2 RPS 输出吞吐 234.90 tok/s，4 RPS 为 413.61 tok/s。这些数字只适用于本文环境、FP16、max-model-len=4096、gpu-memory-utilization=0.75 及对应压测负载；修改模型、版本或参数后应重新测量。

vLLM 当前也提供 vllm serve 作为 OpenAI-compatible 服务的 CLI 入口；本文保留已验证的 python -m vllm.entrypoints.openai.api_server 启动方式，以便与已有环境和记录保持一致。vLLM CLI 文档

资料与版本依据

• WSL 安装指南
• uv 安装指南
• Hugging Face CLI 下载说明