vLLM 在Win11+WSL上的安装与部署技术报告

环境： Windows 11 + WSL2 (Ubuntu 22.04.5 LTS)
日期： 2026-05-02 ~ 2026-05-03
目标模型： Qwen/Qwen3-0.6B
GPU： NVIDIA Quadro RTX 3000 with Max-Q Design（6 GiB VRAM，Compute Capability 7.5）

---

一、环境准备

1.1 系统更新

sudo apt update && sudo apt upgrade -y

升级了 41 个软件包，包括 systemd、nodejs 22.22.2、openssh-client、snapd 等，新增 netplan-generator、python3-netplan。

1.2 安装 Python 基础工具

sudo apt install python3 python3-pip python3-venv git -y

系统已有 Python 3.10.6、pip、git，本步骤补充安装了 python3-venv、python3.10-venv。

1.3 创建虚拟环境

python3 -m venv vllm_env
source vllm_env/bin/activate

---

二、安装 vLLM

2.1 安装 uv（包管理加速工具）

pip install uv
# 成功安装 uv-0.11.8

2.2 使用 uv 安装 vLLM

uv pip install vllm --torch-backend=auto

安装耗时约 51 分钟（依赖解析 2min41s，下载编译 30min57s，安装 20min03s），共安装 181 个包，关键依赖包括：

包名	版本
vllm	0.20.0
torch	2.11.0+cu130
transformers	5.7.0
flashinfer-python	0.6.8.post1
cuda-toolkit	13.0.2
huggingface-hub	1.13.0

---

三、首次启动失败排查

3.1 网络不通（无法下载模型）

错误：

[Errno 101] Network is unreachable
OSError: Can't load the configuration of 'Qwen/Qwen3-0.6B'

原因： WSL2 默认 NAT 模式不继承 Windows 的 localhost 代理。

解决方案： 使用局域网 IP 设置代理（将 192.168.2.7 替换为实际代理机 IP）：

export http_proxy=http://192.168.2.7:7890
export https_proxy=http://192.168.2.7:7890

验证：

curl -I https://huggingface.co
# HTTP/2 200 ✓

3.2 GPU 显存不足

错误：

ValueError: Free memory on device cuda:0 (4.99/6.0 GiB) on startup is less than
desired GPU memory utilization (0.92, 5.52 GiB).

原因： 6 GiB 显卡在系统空闲后仍只有约 4.99 GiB 可用，默认 gpu-memory-utilization=0.92 要求 5.52 GiB，超出可用量。

解决方案： 降低显存利用率并限制上下文长度：

vllm serve Qwen/Qwen3-0.6B \
  --max-model-len 128 \
  --max-num-batched-tokens 128 \
  --max-num-seqs 1 \
  --gpu-memory-utilization 0.80

3.3 缺少 nvcc（CUDA 编译器）

错误：

RuntimeError: Could not find nvcc and default cuda_home='/usr/local/cuda' doesn't exist

原因： FlashInfer 的 JIT 编译需要 nvcc，WSL2 中未安装 CUDA Toolkit。

解决方案： 下载并安装 CUDA Toolkit 12.4.1（仅 Toolkit，不安装驱动）：

wget https://developer.download.nvidia.com/compute/cuda/12.4.1/local_installers/cuda_12.4.1_550.54.15_linux.run
sudo sh cuda_12.4.1_550.54.15_linux.run
# 选择仅安装 Toolkit，跳过 Driver

设置环境变量：

export CUDA_HOME=/usr/local/cuda
export PATH="${CUDA_HOME}/bin:$PATH"
export LD_LIBRARY_PATH="${CUDA_HOME}/lib64:$LD_LIBRARY_PATH"

# 写入 ~/.bashrc 持久化
echo 'export CUDA_HOME=/usr/local/cuda' >> ~/.bashrc
echo 'export PATH="${CUDA_HOME}/bin:$PATH"' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH="${CUDA_HOME}/lib64:$LD_LIBRARY_PATH"' >> ~/.bashrc

---

四、成功启动

4.1 启动命令

vllm serve Qwen/Qwen3-0.6B \
  --max-model-len 128 \
  --max-num-batched-tokens 128 \
  --max-num-seqs 1 \
  --gpu-memory-utilization 0.80

4.2 启动过程日志摘要

阶段	耗时	说明
模型权重下载	~505 秒	从 HuggingFace 下载 1.40 GiB
模型加载到 GPU	~20 秒	占用 1.12 GiB 显存
torch.compile 编译	~92 秒	Dynamo 变换 + Inductor 编译
CUDA graph 捕获	~190 秒	profile + warmup + capture
总计	~约 6 分钟（二次启动）	首次因权重下载约 20 分钟

注： 首次启动因需下载模型约 505 秒，后续启动利用缓存仅需约 20 秒加载权重。

4.3 关键运行参数

模型架构：   Qwen3ForCausalLM
数据类型：   float16（bfloat16 降级，RTX 3000 不支持 bf16）
注意力后端：  FLASHINFER（FlashAttention 2 不支持 cc<8，自动回退）
KV Cache：   27,600 tokens 可用
最大并发：   215.62x（基于 128 token/请求）

4.4 服务端点

服务成功启动于 http://0.0.0.0:8000，提供以下主要 API：

• GET /health — 健康检查
• GET /v1/models — 模型列表
• POST /v1/chat/completions — Chat 接口（兼容 OpenAI）
• POST /v1/completions — 补全接口
• POST /v1/messages — Anthropic 格式接口

4.5 CURL测试

curl http://localhost:8000/v1/models

# 输出：
{"object":"list","data":[{"id":"Qwen/Qwen3-0.6B","object":"model","created":1777772833,"owned_by":"vllm","root":"Qwen/Qwen3-0.6B","parent":null,"max_model_len":128,"permission":[{"id":"modelperm-ba7693fe67cc0a5a","object":"model_permission","created":1777772833,"allow_create_engine":false,"allow_sampling":true,"allow_logprobs":true,"allow_search_indices":false,"allow_view":true,"allow_fine_tuning":false,"organization":"*","group":null,"is_blocking":false}]}]}

# -------------------------------------------------------------------------

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [{"role": "user", "content": "你好"}],
    "temperature": 0.6,
    "top_p": 0.95
  }'
  
curl http://localhost:8000/v1/chat/completions -H "Content-Type:application/json" -d '{"model":"Qwen/Qwen3-0.6B","messages":[{"role":"user","content":"你好"}]}'

# 输出：
{"id":"chatcmpl-a03d2af83d046f5b","object":"chat.completion","created":1777772911,"model":"Qwen/Qwen3-0.6B","choices":[{"index":0,"message":{"role":"assistant","content":"<think>\n好的，用户发来一条消息：“你好”。我需要先确认用户的身份，然后进行适当回应。首先，用户可能是在打招呼，或者测试我的反应。考虑到用户可能只是简单地回应，我应该保持友好和开放的态度。可以简单地回应“你好！”或者询问更多信息，以促进进一步的互动。同时，要确保回应符合语言规范，避免使用可能引起误解的措辞。最后，保持自然和亲切，让用户感到被重视和欢迎。\n</think>\n\n你好！有什么可以帮到你的吗？😊","refusal":null,"annotations":null,"audio":null,"function_call":null,"tool_calls":[],"reasoning":null},"logprobs":null,"finish_reason":"stop","stop_reason":null,"token_ids":null}],"service_tier":null,"system_fingerprint":null,"usage":{"prompt_tokens":9,"total_tokens":123,"completion_tokens":114,"prompt_tokens_details":null},"prompt_logprobs":null,"prompt_token_ids":null,"kv_transfer_params":null}

---

五、注意事项与经验总结

问题	根因	解决方案
WSL2 无法访问 HuggingFace	NAT 模式不继承代理	使用宿主机 LAN IP 设置 http_proxy
显存不足	默认 gpu-memory-utilization=0.92 过高	设置为 0.80，同时限制 max-model-len
找不到 nvcc	WSL2 无 CUDA Toolkit	安装 CUDA Toolkit 12.4.1（跳过驱动）
FA2 不可用警告	RTX 3000 compute capability=7.5，FA2 需要≥8	自动回退至 FlashInfer，无需手动处理
bfloat16 不支持	同上，cc=7.5	自动降级为 float16，性能略有影响
pin_memory=False 警告	WSL2 限制	已知限制，性能略降，可接受

推荐的持久化启动脚本

#!/bin/bash
source ~/vllm_env/bin/activate
export http_proxy=http://192.168.2.7:7890
export https_proxy=http://192.168.2.7:7890
export CUDA_HOME=/usr/local/cuda
export PATH="${CUDA_HOME}/bin:$PATH"
export LD_LIBRARY_PATH="${CUDA_HOME}/lib64:$LD_LIBRARY_PATH"

vllm serve Qwen/Qwen3-0.6B \
  --max-model-len 128 \
  --max-num-batched-tokens 128 \
  --max-num-seqs 1 \
  --gpu-memory-utilization 0.80

---