vLLM 完整部署指南（Windows 11 + WSL2 + CUDA 13.0）

原创已于 2026-03-31 14:58:11 修改 · 1.9k 阅读

9 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#vllm #windows

于 2026-03-31 14:45:12 首次发布

一、系统环境准备

1. Windows 主机配置

# 以管理员身份打开 PowerShell
wsl --install -d Ubuntu-22.04
wsl --set-default-version 2

重启电脑完成 WSL2 安装

2. 安装 NVIDIA 驱动

前往 NVIDIA 官网下载最新 Game Ready 驱动
版本需 ≥ 550（支持 CUDA 13.0）
安装后重启

二、WSL2 内部配置

1. 启动 Ubuntu 并更新

# 从开始菜单打开 Ubuntu
sudo apt update && sudo apt upgrade -y
sudo apt install -y python3-pip python3-venv build-essential curl wget git git-lfs

2. 安装 CUDA Toolkit 13.0(注意，不安装驱动，只装toolkit)

# 安装 CUDA 13.0 Toolkit（WSL2 专用）
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.0-1_all.deb
sudo dpkg -i cuda-keyring_1.0-1_all.deb
sudo apt-get update
sudo apt-get install -y cuda-toolkit-13-0

# 验证安装
nvcc --version  # 应显示 13.0
nvidia-smi      # 应显示 GPU 信息和 CUDA 13.0

三、Python 环境配置

1. 创建项目目录

mkdir -p ~/vllm-server && cd ~/vllm-server

2. 创建虚拟环境（我没有安装虚拟环境，可以跳过）

python3 -m venv venv
source venv/bin/activate

3. 升级 pip

python3 -m pip install --upgrade pip

四、安装 PyTorch 和 vLLM

1. 安装 PyTorch（CUDA 13.0 专用）

# CUDA 13.0 对应 cu130
python3 -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130

#注意，当前vllm=0.18.1 对应的版本应该如下，可以指定，也可以自动匹配
pip3 install torch==2.10.0 torchvision==0.25.0 torchaudio==2.10.0 --index-url https://download.pytorch.org/whl/cu130

2. 验证 PyTorch

python3 -c "import torch; print('PyTorch版本:', torch.__version__); print('CUDA可用:', torch.cuda.is_available())"
# 预期输出: CUDA可用: True

3. 安装 vLLM

python3 -m pip install vllm

五、模型部署与启动

1. 创建模型存储目录

mkdir -p ~/my-ai-models

2. 设置环境变量（关键）

# 设置 HuggingFace 国内镜像（加速下载）
export HF_ENDPOINT=https://hf-mirror.com
# 可选：设置模型缓存目录
export HF_HOME=/home/用户名/my-ai-models

建议将这两行添加到 ~/.bashrc永久生效

3. 启动 vLLM 服务

# 激活虚拟环境
source ~/vllm-server/venv/bin/activate

# 启动 Embedding 模型服务
python3 -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen3-Embedding-4B \
    --served-model-name qwen3-embedding \
    --host 0.0.0.0 --port 8000 \
    --download-dir /home/用户名/my-ai-models \
    --max-model-len 8192 \
    --dtype half \
    --gpu-memory-utilization 0.9

参数说明：

--model: HuggingFace 模型路径，自动下载
--download-dir: 指定模型下载保存位置
--dtype half: 使用半精度节省显存
--max-model-len 8192: 最大上下文长度
--gpu-memory-utilization 0.9: GPU 显存利用率

六、服务验证

1. 检查服务状态

# 在另一个终端执行
curl http://localhost:8000/v1/models

预期返回：

{"object":"list","data":[{"id":"qwen3-embedding","object":"model","owned_by":"vllm"}]}

2. 测试 Embedding API

curl http://localhost:8000/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token-abc123" \
  -d '{
    "model": "qwen3-embedding",
    "input": "测试文本"
  }'

3. 查看 GPU 使用情况

# 在另一个终端监控
watch -n 1 nvidia-smi

七、便捷脚本

1. 启动脚本 `start_vllm.sh`

#!/bin/bash
# 设置环境变量
export HF_ENDPOINT=https://hf-mirror.com
export HF_HOME=/home/用户名/my-ai-models

# 激活环境
source /home/anjingbo/vllm-server/venv/bin/activate

# 启动服务
python3 -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen3-Embedding-4B \
    --served-model-name qwen3-embedding \
    --host 0.0.0.0 --port 8000 \
    --download-dir /home/用户名/my-ai-models \
    --max-model-len 8192 \
    --dtype half \
    --gpu-memory-utilization 0.9

2. 设置脚本权限并运行

chmod +x start_vllm.sh
./start_vllm.sh

3. 创建 Windows 快捷方式

在 Windows 桌面创建 start_vllm.bat：

@echo off
wsl -d Ubuntu-22.04 --cd ~/vllm-server ./start_vllm.sh
pause

双击即可启动服务。

八、故障排查

1. 端口被占用

# 查找占用 8000 端口的进程
sudo lsof -i:8000
# 或更换端口
python3 -m vllm.entrypoints.openai.api_server ... --port 8001

2. 显存不足

减小 --max-model-len到 4096
降低 --gpu-memory-utilization到 0.8
添加 --enable-prefix-caching启用前缀缓存

3. 下载失败

# 尝试不同镜像源
export HF_ENDPOINT=https://hf-mirror.com
# 或
export HF_ENDPOINT=https://mirrors.aliyun.com/huggingface

4. Windows 无法访问

检查 Windows 防火墙，确保端口 8000 开放。

九、后续使用

1. 停止服务

在 vLLM 运行终端按 Ctrl+C

2. 查看下载的模型

ls -la ~/my-ai-models/models--Qwen--Qwen3-Embedding-4B/

3. 下次启动（使用本地缓存）

# 直接使用本地路径，无需下载
python3 -m vllm.entrypoints.openai.api_server \
    --model /home/anjingbo/my-ai-models/models--Qwen--Qwen3-Embedding-4B \
    --served-model-name qwen3-embedding \
    --host 0.0.0.0 --port 8000