2 Windows + WSL2 用 vLLM 部署 Qwen2.5-VL-3B 完整指南（GTX 1650 4GB 极限版）

本文定位：本机（Win10 22H2 + WSL2 + GTX 1650 4GB 显存）从 0 到 1 跑通 vLLM 部署多模态模型 Qwen2.5-VL-3B 的完整实测记录。 每一步命令都标注了在哪个终端执行，照抄即可复现。 记录时间：2026-08-09（本机实测，全部命令已验证）

目录

• ⚡ 快速上手（三步走）
• 第 1 部分：前置准备（适用环境 + WSL2 + 显卡驱动）
• 第 2 部分：安装 vLLM 运行环境
• 第 3 部分：下载模型（AWQ 量化版）
• 第 4 部分：启动并验证 vLLM 服务
• 第 5 部分：从 Windows 调用测试
• 第 6 部分：踩坑全记录（重点）
• 第 7 部分：已知限制
• 第 8 部分：命令速查

⚡ 快速上手（三步走）

整篇文档其实就是这三件事，其余都是补充。① ② 只做一次，③ 每次使用都做。

唯一前置：显卡驱动 ≥ 610.88（第 1 部分），否则 torch 起不来。

卡住时先看：第 6 部分踩坑全记录——4GB 显存的所有坑都在那里。

全文路径约定（每条命令处另有就地注释，按命令旁的注释改即可）：/root/ 是 root 用户家目录，非 root 用户统一换成 echo $HOME 的结果；WSL 侧路径别放 /mnt/…（那是 Windows 盘，走 9P 桥接，模型会加载不动）。

你会得到什么（成果速览）

Windows 侧直接访问 http://localhost:8000 即可调用（WSL2 自动转发端口），无需任何额外配置。

第 1 部分：前置准备（适用环境 + WSL2 + 显卡驱动）

这部分的活只干一次：确认机器达标 → 装好 WSL2 和 Ubuntu → 升级显卡驱动。

1.1 适用环境

• Windows 10 22H2（19045）或 Windows 11，已开启 WSL2
• NVIDIA 独显：本文实测为 GTX 1650（Turing，compute capability 7.5，4GB 显存）
• 显卡驱动：610.88 及以上（支持 CUDA 14，torch cu130 需要）
• 磁盘：模型权重 ~3.4 GB + 虚拟环境 ~6 GB，建议放非 C 盘

⚠️ 4GB 显存是本文最大的坑：AWQ 权重 3.32 GiB 几乎占满整张卡，全靠第 6.7 节的技巧才塞进去。显存 ≥ 6GB 的机器可跳过极限压榨部分，直接加大 –max-model-len。

1.2 WSL2 + Ubuntu 24.04

详细安装流程见同目录《WSL-Ubuntu-Docker-安装全流程.md》，这里只列结论：

• Ubuntu 虚拟磁盘在 E:\\WSL\\Ubuntu\\ext4.vhdx（Linux 的"物理存储"，/ 根目录）
• Windows 的 D 盘在 Linux 里挂在 /mnt/d，C 盘在 /mnt/c
• 打开 Ubuntu：PowerShell 里敲 wsl 回车

[PowerShell]
wsl —status # 确认默认分发是 Ubuntu、版本 2
wsl # 进入 Ubuntu

1.3 显卡驱动（关键前提）

vLLM 的 torch 2.11+cu130 需要较新驱动。旧驱动（如 526.56）会报：

RuntimeError: The NVIDIA driver on your system is too old (found version 12000)

升级到 610.88（实测通过）：

1.4 确认 WSL 里 CUDA 可用

[WSL]
nvidia-smi # 应显示和 Windows 一样的 610.88

第 2 部分：安装 vLLM 运行环境

2.1 创建虚拟环境

[WSL]
sudo apt update && sudo apt install -y python3-venv python3-pip

python3 -m venv /root/venv-vllm # 虚拟环境路径可改：换成 ~/venv-vllm 等任意 WSL 目录，但下文所有 /root/venv-vllm/ 前缀要同步改

/root/venv-vllm/bin/pip install –upgrade pip

💡 想让命令短写？激活 venv 即可：执行 source /root/venv-vllm/bin/activate 后，pip / python 直接可用（不用再写 /root/venv-vllm/bin/ 前缀）。但激活只对当前终端窗口有效，换窗口要重新激活；想自动激活就执行 echo 'source /root/venv-vllm/bin/activate' >> ~/.bashrc。 本文后续命令仍写全路径，是为了不依赖激活状态、保证一定装进 venv（直接 pip install 会调用系统 pip，可能装错地方）。你激活后把 /root/venv-vllm/bin/ 前缀去掉即可。

2.2 安装 vLLM

[WSL]
/root/venv-vllm/bin/pip install vllm==0.26.0
# 已激活 venv 的话直接: pip install vllm==0.26.0

会自动装 torch 2.11.0+cu130。装完验证：

/root/venv-vllm/bin/python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
# 期望: 2.11.0+cu130 True

若 cuda.is_available() 是 False，几乎都是驱动问题，回 1.3。

第 3 部分：下载模型（AWQ 量化版）

3.1 为什么选 AWQ 版

3.2 下载（本机实测：hf-mirror + curl 逐个下载）

模型仓库：Qwen/Qwen2.5-VL-3B-Instruct-AWQ（HF 镜像：hf-mirror.com）

需要下载 14 个文件（含 model.safetensors 3.17 GB 主权重），共 ~3.4 GB：

.gitattributes LICENSE README.md added_tokens.json chat_template.json
config.json generation_config.json merges.txt model.safetensors (3.17 GB)
preprocessor_config.json special_tokens_map.json tokenizer.json (11 MB)
tokenizer_config.json vocab.json (2.7 MB)

下载脚本（Windows 侧执行，存到 E:\\WSL\\downloads\\models\\）：

# download_model.ps1
$files = @(
".gitattributes", "LICENSE", "README.md", "added_tokens.json",
"chat_template.json", "config.json", "generation_config.json",
"merges.txt", "model.safetensors", "preprocessor_config.json",
"special_tokens_map.json", "tokenizer.json", "tokenizer_config.json", "vocab.json"
)
$dest = "E:\\WSL\\downloads\\models\\Qwen2.5-VL-3B-Instruct-AWQ" # 下载目录可改：任意 Windows 目录，但 3.3 的 cp 源路径要跟着改
New-Item –ItemType Directory –Path $dest –Force | Out-Null
$base = "https://hf-mirror.com/Qwen/Qwen2.5-VL-3B-Instruct-AWQ/resolve/main/"
foreach ($f in $files) {
$out = Join-Path $dest $f
if ((Test-Path $out) -and ((Get-Item $out).Length -gt 0)) { Write-Host "SKIP $f"; continue }
curl.exe –sL –C – –A "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" –o $out "$base$f"
Write-Host "$f -> $((Get-Item $out –ErrorAction SilentlyContinue).Length) bytes"
}
Write-Host "ALL DONE"

[PowerShell]
powershell –ExecutionPolicy Bypass –File .\\download_model.ps1

⚠️ model.safetensors 下载完后必须确认后 5 个小文件也下载成功（本机曾因流程提前报完成漏掉 tokenizer 等 5 个文件，导致启动报 vocab and merges must be both be from memory or both filenames）。检查：

[PowerShell]
Get-ChildItem "E:\\WSL\\downloads\\models\\Qwen2.5-VL-3B-Instruct-AWQ" | Select Name, Length # 路径随上面脚本的 $dest

3.3 复制进 WSL

WSL 直接读 /mnt/e（9P 桥接）极慢，必须复制到 Linux 原生目录：

[WSL]
# 源路径 = 你在 3.2 下载脚本里设的 $dest（Windows 盘，经 /mnt 访问）
# 目标路径 = 你选的模型运行目录：任意 WSL 原生路径都行（如 ~/models/…），但 4.1 启动脚本里的模型路径要同步改
mkdir -p /root/models/Qwen2.5-VL-3B-Instruct-AWQ
cp /mnt/e/WSL/downloads/models/Qwen2.5-VL-3B-Instruct-AWQ/* /root/models/Qwen2.5-VL-3B-Instruct-AWQ/
ls -la /root/models/Qwen2.5-VL-3B-Instruct-AWQ/

3.4 GB 复制约需 5 分钟。复制期间 WSL 可能报资源不足崩溃（见 6.8），崩溃后 wsl –shutdown 重启再继续。

第 4 部分：启动并验证 vLLM 服务

起服务 → 确认在线 → 跑两个测试（OCR + 真实图片），一气呵成。

4.1 启动脚本（最终版，已调通）

把下面内容存为 /root/start_vllm.sh：

#!/bin/bash
export VLLM_WSL2_ENABLE_PIN_MEMORY=1
# GTX 1650 4GB 极限压榨: AWQ 权重 3.32GiB 用 weights 专用池加载
# KV cache 手动指定 128MiB 绕过 vLLM 的显存计算 bug (free-weights 为负)
# 路径可改: venv 随 2.1, 模型目录随 3.3, 日志重定向路径见下方 > /root/vllm.log 处
source /root/venv-vllm/bin/activate
cd /root/models

# 模型路径换成你在 3.3 复制到的目录；–port / –served-model-name 也可自定义
exec vllm serve /root/models/Qwen2.5-VL-3B-Instruct-AWQ \\
–served-model-name qwen2.5-vl-3b \\
–quantization awq \\
–gpu-memory-utilization 0.80 \\
–kv-cache-memory-bytes 134217728 \\
–max-model-len 512 \\
–max-num-seqs 1 \\
–limit-mm-per-prompt '{"image": 1}' \\
–enforce-eager \\
–host 0.0.0.0 \\
–port 8000 \\
> /root/vllm.log 2>&1 # 日志路径可改，4.3/4.4 的查看命令要同步改

4.2 启动

[WSL]
chmod +x /root/start_vllm.sh
bash /root/start_vllm.sh # 脚本路径可改：若你在 4.1 另存了位置，这里和速查表都要跟着改

启动耗时约 1.5~2 分钟（权重加载 17s + 编译/profile 10s + API 就绪）。

4.3 常用配套命令

[WSL]
tail -f /root/vllm.log # 实时看日志（路径随 4.1 的重定向）
pgrep -af "vllm serve" # 确认进程活着

若想让服务在 Windows 后台常驻，在 PowerShell 用后台任务启动：

[PowerShell]
wsl –e bash –c "bash /root/start_vllm.sh" # 保持这个窗口开着即可；脚本路径同 4.2

4.4 确认 API 就绪

日志出现以下行即成功：

[WSL]
grep -E "Application startup complete|Uvicorn" /root/vllm.log
# 期望输出: Application startup complete.

4.5 查询模型列表

[PowerShell]
curl.exe http://localhost:8000/v1/models
# 期望返回: {"object":"list","data":[{"id":"qwen2.5-vl-3b",…}]}

4.6 OCR 实测（生成本机测试图）

把下面脚本存为 /root/test_ocr.py 并执行（脚本路径可改，保存位置和下面执行命令保持一致即可）：

from PIL import Image, ImageDraw, ImageFont
import base64, io, json, urllib.request

img = Image.new("RGB", (224, 224), "white")
d = ImageDraw.Draw(img)
try:
font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf", 28)
except Exception:
font = ImageFont.load_default()
d.text((20, 40), "HELLO VLLM", fill="black", font=font)
d.text((20, 90), "Qwen2.5-VL-3B", fill="black", font=font)
d.text((20, 140), "GTX 1650 4GB", fill="black", font=font)
d.text((20, 190), "12345", fill="black", font=font)
img.save("/root/test_ocr.png")

buf = io.BytesIO(); img.save(buf, format="PNG")
b64 = base64.b64encode(buf.getvalue()).decode()
payload = {
"model": "qwen2.5-vl-3b",
"messages": [{"role": "user", "content": [
{"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}},
{"type": "text", "text": "请逐行读出图片里的所有文字。"}
]}],
"max_tokens": 200,
}
req = urllib.request.Request("http://127.0.0.1:8000/v1/chat/completions",
data=json.dumps(payload).encode(), headers={"Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=180) as resp:
print(json.loads(resp.read().decode())["choices"][0]["message"]["content"])

[WSL]
/root/venv-vllm/bin/python /root/test_ocr.py # 路径随你保存的位置；venv 前缀随 2.1

实测输出（基本全对）：

HELLO VLLM
Qwen2.5-VL-1 # "3B" 读成 "1"，小图分辨率低所致，可忽略
GTX 1650 4G
12345

4.7 真实图片测试

用任意真实图片（如 D:\\数据存储\\Pictures\\情头\\男生.jpeg）：

[WSL]
cp "/mnt/d/数据存储/Pictures/情头/男生.jpeg" /root/real.jpg

注意：原图必须先缩放到 ≤448px 再传（原因见 6.9），缩放用 Windows 侧脚本最方便（见第 5 部分）。

第 5 部分：从 Windows 调用测试

vLLM 在 WSL 里监听 0.0.0.0:8000，WSL2 自动把端口转发到宿主机，所以 Windows 直接访问 http://localhost:8000。

5.1 方式一：一键测试脚本（推荐）

把 test_vllm.ps1（见附录）放在任意目录，PowerShell 进入该目录执行（下面 \\.\\ 换成你的实际路径）：

[PowerShell]
# .\\ 表示当前目录：先 cd 到 test_vllm.ps1 所在目录，或直接写完整路径 C:\\…\\test_vllm.ps1
.\\test_vllm.ps1 # 纯文本对话
.\\test_vllm.ps1 –Image "D:\\数据存储\\Pictures\\情头\\男生.jpeg" # 图片识别（自动缩放 448px）
.\\test_vllm.ps1 –Image "…\\图.jpg" –Prompt "这张图是什么风格?" # 图片 + 自定义问题

脚本内置：服务健康检查、图片自动缩放、UTF-8 中文输出修复。实测输出：

== 4. 结果 (用时 1.7s) ==
这张图片的主角是一只棕色的小狗。

5.2 方式二：浏览器 Swagger 调试页

浏览器打开 http://localhost:8000/docs —— vLLM 自带的可视化 API 页面，填参数点按钮即可发请求。

5.3 方式三：curl 命令行

[PowerShell]
# 方式一：内联（单引号包裹，JSON 内部的双引号必须写成 \\" 转义形式）
curl.exe http://localhost:8000/v1/chat/completions –H "Content-Type: application/json" –d '{\\"model\\":\\"qwen2.5-vl-3b\\",\\"messages\\":[{\\"role\\":\\"user\\",\\"content\\":\\"你好，用一句话介绍自己\\"}]}'

# 方式二：文件方式（最稳，绕开所有引号/编码问题）
$body = '{"model":"qwen2.5-vl-3b","messages":[{"role":"user","content":"你好，用一句话介绍自己"}]}'
[IO.File]::WriteAllText("$env:TEMP\\vllm_body.json", $body, (New-Object System.Text.UTF8Encoding($false)))
curl.exe http://localhost:8000/v1/chat/completions –H "Content-Type: application/json" –d "@$env:TEMP\\vllm_body.json"

⚠️ PowerShell 5.1 引号坑（实测）：PowerShell 5.1 调原生程序时不转义参数内部的双引号，-d '{"model":…}'（纯单引号）会把 JSON 拆碎，vLLM 报 JSON decode error / Expecting property name enclosed in double quotes。

• 方式一必须把 JSON 里的 " 写成 \\"（单引号包裹 + 反斜杠转义），curl 会把它还原成正常 JSON。这是本机实测唯一能一行跑通的内联写法。
• 方式二文件方式最稳：UTF-8 无 BOM 的 JSON 文件（WriteAllText + UTF8Encoding($false)），绕开命令行引号与编码的一切问题。
• 中文实测正常：curl.exe 按 UTF-8 处理命令行，vLLM 返回干净 UTF-8；若响应中文在 GBK 控制台显示乱码，只是显示问题——改用 .\\test_vllm.ps1 查看即可。
• 如果用的是 PowerShell 7.3+，纯单引号 '{"model":…}' 也可以直接工作。

5.4 接口速查

完全兼容 OpenAI SDK，任何语言/工具（Python、Node、Postman）都能调。

第 6 部分：踩坑全记录（重点）

按遇到顺序排列，每条含：现象 → 原因 → 解决。本部分是最有价值的经验。

6.1 驱动太老：found version 12000

• 现象：torch.cuda.is_available() 返回 False，报驱动太老
• 原因：旧驱动 526.56 只支持 CUDA 12.0，而 torch 2.11+cu130 需要新驱动
• 解决：升级到 610.88（见 1.3）

6.2 FA2 报错：FA2 is only supported on devices with compute capability >= 8

• 现象：日志大量 ERROR，但不影响启动
• 原因：GTX 1650 是 Turing 架构（7.5），vLLM 想用 FlashAttention-2（需 8.0+）失败后自动回退
• 解决：忽略即可

6.3 UVA 不可用：RuntimeError: UVA is not available

• 现象：引擎初始化直接失败
• 原因：vLLM 0.26 的 staged-writes 需要 CUDA pinned memory，而 vLLM 在 WSL2 下默认禁用 pinned memory
• 解决：启动脚本加环境变量：export VLLM_WSL2_ENABLE_PIN_MEMORY=1

6.4 KV cache 负内存：Available KV cache memory: -0.09 GiB

• 现象：权重加载成功（Model loading took 3.32 GiB），但 KV cache 内存为负数，启动失败
• 原因：vLLM 用 初始化后剩余显存(3.22GiB) – 权重(3.32GiB) 计算 KV cache 空间——4GB 卡上权重本身就超了"初始化后可用"，公式结果为负
• 解决：见 6.7（–kv-cache-memory-bytes 绕过）

6.5 –cpu-offload-gb 无效（AWQ 模型）

• 现象：加 –cpu-offload-gb 1.2 后，Model loading took 3.32 GiB 不变，KV cache 依旧负数
• 原因：vLLM 0.26 的 offloader 在模型构建时（make_layers）wrap 模块，此时参数还在 CPU 上直接被跳过；真正的权重在后续 load_weights 阶段直接进显存，offload 根本没机会生效。实测对 AWQ/多模态模型无效
• 解决：放弃 offload，改用 6.7 的方案

6.6 GGUF 方案否决

• 现象：Qwen2.5-VL-3B-Instruct-GGUF 的 Q4 版最小（~2.3GB）
• 原因：vLLM 0.26 不支持多模态模型的 GGUF（–quantization gguf 对 VL 模型直接报错）；hf-mirror 也没有该仓库的 GGUF 文件
• 解决：回到 AWQ 路线，用 6.7 极限压榨

6.7 ⭐ 最终突破：–kv-cache-memory-bytes 手动指定

• 原理：vLLM 0.26 加载权重用的是专用 weights 内存池（_maybe_get_memory_pool_context），能用到接近 4GB 全部；加载后实际剩余 ~143 MB。但 KV cache 计算仍用 初始化后free – 权重 的错误公式 → 负数
• 解决：手动指定 KV cache 大小，跳过这个公式：–kv-cache-memory-bytes 134217728 # 128 MiB
  同时把 –max-model-len 降到 512、–max-num-seqs 1、–enforce-eager（省 CUDA graph 显存），把显存全部让给权重
• 效果：init engine (profile, create kv cache, warmup model) took 23.50 s 成功，API 正常服务

6.8 WSL 崩溃：0x800705aa（系统资源不足）

• 现象：复制 3.4GB 模型文件或服务运行时，WSL 突然挂掉，所有 wsl 命令报 Wsl/Service/CreateInstance/CreateVm/HCS/0x800705aa
• 原因：WSL2 虚拟机瞬时资源不足（大文件复制 + 多进程同时进行）
• 解决：[PowerShell]
  wsl —shutdown # 彻底重启 WSL 虚拟机
  等 10 秒后再用 wsl 即恢复。注意：这会杀掉 WSL 里所有进程（包括 vLLM），需要重新启动服务

6.9 图片 token 超限：Input length (767) exceeds model's maximum context length (512)

• 现象：传真实图片（1000×968）报 400 Bad Request
• 原因：Qwen2.5-VL 把图切成 28×28 的 patch，每 patch = 1 token。1000×968 的图缩放 768px 后 = ~760 token，超 512 上限
• 解决：图片缩放 ≤448px（448/28 = 16 列 × 16 行 = 256 token，留足文本余量）。test_vllm.ps1 已内置自动缩放

6.10 PowerShell 脚本中文乱码（两个坑）

• 坑 1：.ps1 文件里有中文注释，直接运行报语法错误
  • 原因：Windows PowerShell 5.1 按 GBK 解析无 BOM 的 UTF-8 文件，中文乱码导致引号配对错乱
  • 解决：文件存为 UTF-8 with BOM（VSCode 右下角编码选"UTF-8 with BOM"）
• 坑 2：脚本里 Invoke-RestMethod 拿到的中文回答变乱码
  • 原因：PowerShell 5.1 对无 charset 的 JSON 响应默认按 Latin-1 解码
  • 解决：改用 Invoke-WebRequest 拿原始字节手动按 UTF-8 解码：$rawResp = Invoke-WebRequest –Uri $url –Method Post –ContentType "application/json; charset=utf-8" –Body $body
    $resp = [System.Text.Encoding]::UTF8.GetString($rawResp.RawContentStream.ToArray()) | ConvertFrom-Json

6.11 漏下载小文件：vocab and merges must be both be from memory or both filenames

• 现象：启动时 tokenizer 加载报错
• 原因：下载流程在 model.safetensors 完成后提前报"完成"，漏了最后 5 个小文件（tokenizer.json、vocab.json 等）
• 解决：检查 Windows 侧文件清单（3.2），缺哪个补哪个，再复制进 WSL

第 7 部分：已知限制

第 8 部分：命令速查

附录：本机文件与脚本清单

虚拟环境：/root/venv-vllm（Python 3.12.3，vllm 0.26.0，torch 2.11.0+cu130）

最终启动参数摘要（一句话记住）：AWQ 权重 + VLLM_WSL2_ENABLE_PIN_MEMORY=1 + –kv-cache-memory-bytes 134217728 + –max-model-len 512 + –enforce-eager + –max-num-seqs 1。