Windows 11 + WSL2 + vLLM 本地部署 Qwen3 8B AWQ 指南
目录
- 系统要求
- 环境准备
- WSL2 Ubuntu 安装配置
- NVIDIA 驱动配置
- CUDA 环境安装
- Python 环境搭建
- vLLM 安装
- Qwen3 8B AWQ 模型下载（国内加速）
- 启动 vLLM 服务
- API 测试验证
- 常见问题解决
- 性能优化建议
系统要求
硬件要求
- 操作系统: Windows 11
- GPU: NVIDIA 显卡，8GB 显存或以上
- 内存: 16GB RAM 或以上（建议）
- 存储: 至少 20GB 可用空间（模型文件约 10GB）
软件要求
- WSL2: Windows Subsystem for Linux 2
- Ubuntu: 建议 Ubuntu 22.04 LTS
- NVIDIA 驱动: 适用于 WSL2 的驱动
- Python: 3.10 - 3.12
- CUDA: 12.1+（建议 12.6）
环境准备
1. 启用 WSL2 功能
以管理员身份打开 PowerShell 或 CMD，执行：
# 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
# 启用虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
# 设置 WSL2 为默认版本
wsl --set-default-version 2
重启系统后，继续安装。
2. 下载并安装 Ubuntu 22.04 LTS
打开 Microsoft Store，搜索 “Ubuntu 22.04 LTS”，点击安装。
或者使用命令行：
# 安装 Ubuntu 22.04
wsl --install -d Ubuntu-22.04
安装完成后，启动 Ubuntu，设置用户名和密码。
WSL2 Ubuntu 安装配置
1. 更新系统软件包
# 更新软件包列表
sudo apt update && sudo apt upgrade -y
# 安装必要工具
sudo apt install -y wget curl git build-essential software-properties-common
2. 配置 WSL2 内存和处理器限制
在 Windows 家目录下创建 .wslconfig 文件：
# 在 Windows PowerShell 中执行
notepad $env:USERPROFILE\.wslconfig
添加以下内容：
[wsl2]
memory=12GB
processors=4
swap=8GB
重启 WSL 使配置生效：
wsl --shutdown
然后重新启动 Ubuntu。
NVIDIA 驱动配置
1. 在 Windows 上安装 NVIDIA 驱动
确保 Windows 上已安装最新的 NVIDIA 显卡驱动（版本 520+）。
访问 NVIDIA 官方驱动页面 下载驱动。
2. 为 WSL2 安装 NVIDIA CUDA 驱动
访问 NVIDIA WSL2 CUDA 驱动页面，下载适用于 WSL2 的 CUDA 驱动。
或者使用命令行：
# 添加 NVIDIA 包仓库
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
# 安装 NVIDIA 驱动（WSL2 专用）
sudo apt-get install -y nvidia-cuda-toolkit
3. 验证 GPU 识别
# 检查 nvidia-smi 是否可用
nvidia-smi
# 预期输出应显示 GPU 信息，包括显存使用情况
如果 nvidia-smi 不可用，尝试：
# 设置 CUDA 路径
export PATH="/usr/local/cuda-12.6/bin:$PATH"
export LD_LIBRARY_PATH="/usr/local/cuda-12.6/lib64:$LD_LIBRARY_PATH"
CUDA 环境安装
1. 安装 CUDA Toolkit
# 添加 CUDA 包仓库
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
# 安装 CUDA 12.6
sudo apt-get install -y cuda-toolkit-12-6 cuda-libraries-dev-12-6
2. 配置环境变量
编辑 ~/.bashrc 文件：
nano ~/.bashrc
在文件末尾添加：
# CUDA 配置
export CUDA_HOME=/usr/local/cuda-12.6
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH
export PATH=$CUDA_HOME/bin:$PATH
export NVIDIA_VISIBLE_DEVICES=all
export CUDA_VISIBLE_DEVICES=0
使配置生效：
source ~/.bashrc
3. 验证 CUDA 安装
# 检查 nvcc 版本
nvcc --version
# 预期输出：
# nvcc: NVIDIA (R) Cuda compiler driver
# Cuda compilation tools, release 12.6, V12.6.xx
Python 环境搭建
1. 安装 Python 和 pip
# 安装 Python 3.10+
sudo apt install -y python3.10 python3-pip python3-venv python3-dev
# 升级 pip
pip install --upgrade pip
# 设置 pip 镜像源（国内加速）
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn
2. 创建虚拟环境
# 创建项目目录
mkdir -p ~/qwen3-deployment
cd ~/qwen3-deployment
# 创建 Python 虚拟环境
python3 -m venv venv
# 激活虚拟环境
source venv/bin/activate
3. 安装依赖包
# 升级 pip
pip install --upgrade pip
# 安装 PyTorch（CUDA 版本）
pip install torch==2.7.1+cu126 torchvision==0.22.1+cu126 torchaudio==2.7.1+cu126 --index-url https://download.pytorch.org/whl/cu126
# 安装 transformers（>=4.36.0）
pip install transformers>=4.36.0
# 安装其他必要包
pip install accelerate tiktoken einops scipy
vLLM 安装
方法一：通过 pip 安装（推荐）
# 安装最新稳定版 vLLM
pip install vllm
# 或者安装特定版本
pip install vllm==0.6.6
方法二：从源码编译安装
# 克隆 vLLM 仓库
git clone https://github.com/vllm-project/vllm.git
cd vllm
# 安装构建依赖
pip install -r requirements-build.txt
# 编译安装（需要较长时间，约 15-30 分钟）
pip install -e . --no-build-isolation
3. 验证 vLLM 安装
python -c "import vllm; print(f'vLLM 版本: {vllm.__version__}')"
预期输出：vLLM 版本: 0.6.6 或更高版本。
Qwen3 8B AWQ 模型下载（国内加速）
方案一：Hugging Face 镜像站（推荐）
1. 安装 huggingface_hub
pip install -U huggingface_hub
2. 设置镜像环境变量
# 临时设置（每次下载前执行）
export HF_ENDPOINT=https://hf-mirror.com
# 永久设置（添加到 ~/.bashrc）
echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc
3. 下载模型
# 创建模型目录
mkdir -p ~/models
cd ~/models
# 下载 Qwen3-8B-AWQ 模型
huggingface-cli download --resume-download Qwen/Qwen3-8B-AWQ --local-dir Qwen3-8B-AWQ
# 如果下载失败，尝试使用 HF_TOKEN
# export HF_TOKEN=your_token_here
# huggingface-cli download --resume-download Qwen/Qwen3-8B-AWQ --local-dir Qwen3-8B-AWQ --token $HF_TOKEN
方案二：ModelScope 镜像站
# 安装 modelscope
pip install modelscope
# 下载模型
from modelscope import snapshot_download
model_dir = snapshot_download('qwen/Qwen3-8B-AWQ')
方案三：阿里云盘/百度网盘分享
如果 Hugging Face 下载速度仍然较慢，可以：
- 从阿里云盘搜索 “Qwen3-8B-AWQ”
- 从百度网盘搜索 “Qwen3-8B-AWQ”
- 下载后上传到 WSL2
4. 验证模型文件
# 检查模型文件完整性
ls -lh ~/models/Qwen3-8B-AWQ/
# 预期看到以下文件：
# - config.json
# - modeling.pt / modeling.safetensors
# - tokenizer.json
# - generation_config.json
# - awq_model-00001-of-00002.safetensors
# - awq_model-00002-of-00002.safetensors
启动 vLLM 服务
1. 创建启动脚本
nano ~/qwen3-deployment/start_vllm.sh
添加以下内容：
#!/bin/bash
# vLLM 服务启动脚本
# 激活虚拟环境
source ~/qwen3-deployment/venv/bin/activate
# 设置环境变量
export CUDA_VISIBLE_DEVICES=0
export VLLM_WORKER_MULTIPROC_METHOD=spawn
# 启动 vLLM 服务
python -m vllm.entrypoints.openai.api_server \
--model ~/models/Qwen3-8B-AWQ \
--host 0.0.0.0 \
--port 8000 \
--trust-remote-code \
--quantization awq \
--dtype half \
--gpu-memory-utilization 0.85 \
--max-model-len 4096 \
--tensor-parallel-size 1 \
--enforce-eager
2. 设置执行权限
chmod +x ~/qwen3-deployment/start_vllm.sh
3. 启动服务
cd ~/qwen3-deployment
./start_vllm.sh
4. 首次启动说明
首次启动时，vLLM 会：
- 加载模型权重（约 5-10 分钟）
- 编译优化内核（约 2-5 分钟）
- 完成后显示服务就绪信息
5. 后台运行（可选）
如果需要后台运行：
# 使用 nohup
nohup ./start_vllm.sh > vllm.log 2>&1 &
# 或使用 screen
sudo apt install -y screen
screen -S vllm
./start_vllm.sh
# 按 Ctrl+A+D 分离 screen
# 重新连接: screen -r vllm
API 测试验证
1. 检查服务状态
# 检查服务是否运行
curl http://localhost:8000/health
# 预期输出：{"status":"ok"}
2. OpenAI 兼容 API 测试
使用 curl 测试
curl -X POST "http://localhost:8000/v1/chat/completions" \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen/Qwen3-8B-AWQ",
"messages": [
{
"role": "user",
"content": "你好，请介绍一下你自己"
}
],
"max_tokens": 512,
"temperature": 0.7,
"top_p": 0.9
}'
使用 Python 测试
import openai
client = openai.OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
response = client.chat.completions.create(
model="Qwen/Qwen3-8B-AWQ",
messages=[
{"role": "user", "content": "你好，请介绍一下你自己"}
],
max_tokens=512,
temperature=0.7
)
print(response.choices[0].message.content)
安装测试依赖
pip install openai
3. 流式输出测试
curl -X POST "http://localhost:8000/v1/chat/completions" \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen/Qwen3-8B-AWQ",
"messages": [
{
"role": "user",
"content": "写一首关于春天的诗"
}
],
"max_tokens": 512,
"stream": true
}'
4. 模型信息查询
curl http://localhost:8000/v1/models
常见问题解决
问题 1：NVIDIA 驱动未识别
错误信息：nvidia-smi: command not found
解决方法：
# 重新安装 NVIDIA 驱动
sudo apt update
sudo apt install -y nvidia-driver-535+
# 重启 WSL
wsl --shutdown
问题 2：CUDA 版本不匹配
错误信息：CUDA error: no kernel image is available for architecture
解决方法：
# 检查 CUDA 版本
nvcc --version
nvidia-smi
# 确保 PyTorch 版本与 CUDA 版本匹配
# CUDA 12.6 对应 PyTorch 2.7.1
pip install torch==2.7.1+cu126 torchvision==0.22.1+cu126 -f https://download.pytorch.org/whl/cu126.html
问题 3：显存不足
错误信息：CUDA out of memory
解决方法：
# 降低 gpu-memory-utilization
--gpu-memory-utilization 0.7
# 降低 max-model-len
--max-model-len 2048
# 启用量化
--quantization awq
问题 4：模型下载失败
错误信息：ConnectionError 或下载速度极慢
解决方法：
# 方案 1：使用镜像站
export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download --resume-download Qwen/Qwen3-8B-AWQ --local-dir ~/models/Qwen3-8B-AWQ
# 方案 2：使用 aria2 加速
sudo apt install -y aria2
aria2c -x 8 -s 8 "https://huggingface.co/Qwen/Qwen3-8B-AWQ/resolve/main/awq_model-00001-of-00002.safetensors" -d ~/models/Qwen3-8B-AWQ -o awq_model-00001-of-00002.safetensors
# 方案 3：使用代理
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"
问题 5：vLLM 启动失败
错误信息：ImportError: libcuda.so.1 cannot open shared object file
解决方法：
# 查找 libcuda.so
sudo find /usr -name "libcuda.so*"
# 创建软链接
sudo ln -sf /usr/lib/wsl/lib/libcuda.so.1 /usr/lib/libcuda.so.1
# 或者添加到 LD_LIBRARY_PATH
export LD_LIBRARY_PATH=/usr/lib/wsl/lib:$LD_LIBRARY_PATH
问题 6：WSL2 内存占用过高
错误信息：系统变卡，内存不足
解决方法：
# 在 Windows 上编辑 .wslconfig
notepad $env:USERPROFILE\.wslconfig
[wsl2]
memory=8GB
processors=4
swap=4GB
然后重启 WSL。
问题 7：端口不通
错误信息：curl: (7) Failed to connect to localhost port 8000
解决方法：
# 检查服务是否运行
ps aux | grep vllm
# 检查端口监听
netstat -tuln | grep 8000
# 关闭防火墙（如果需要）
sudo ufw disable
# 或者开放端口
sudo ufw allow 8000
问题 8：AWQ 量化支持问题
错误信息：ValueError: AWQ is not supported on this hardware
解决方法：
# 确保使用正确版本的 vLLM
pip install vllm>=0.6.0
# 检查 CUDA 版本
nvcc --version
# 重新编译 vLLM
cd vllm
pip install -e . --no-build-isolation
性能优化建议
1. 内存和显存优化
# 降低显存占用
--gpu-memory-utilization 0.8 \
--max-model-len 4096 \
# 使用更小的批处理大小
--max-batch-size 32 \
2. 吞吐量优化
# 启用多批处理
--enable-auto-chunking \
--max-num-batched-tokens 4096 \
3. 延迟优化
# 降低延迟
--enforce-eager \
--disable-log-requests \
4. 完整优化启动脚本
#!/bin/bash
source ~/qwen3-deployment/venv/bin/activate
export CUDA_VISIBLE_DEVICES=0
python -m vllm.entrypoints.openai.api_server \
--model ~/models/Qwen3-8B-AWQ \
--host 0.0.0.0 \
--port 8000 \
--trust-remote-code \
--quantization awq \
--dtype half \
--gpu-memory-utilization 0.85 \
--max-model-len 4096 \
--tensor-parallel-size 1 \
--enforce-eager \
--disable-log-requests \
--max-batch-size 64 \
--max-num-batched-tokens 4096
监控和维护
1. GPU 监控
# 实时监控 GPU 使用情况
watch -n 1 nvidia-smi
# 查看显存使用
nvidia-smi -q -d MEMORY
2. 服务日志
# 查看服务日志
tail -f ~/qwen3-deployment/vllm.log
3. API 性能监控
# 查看 API 延迟统计
curl http://localhost:8000/stats
卸载和清理
1. 停止服务
# 查看进程
ps aux | grep vllm
# 停止进程
kill <PID>
2. 清理环境
# 删除虚拟环境
rm -rf ~/qwen3-deployment/venv
# 删除模型文件（如果需要）
rm -rf ~/models/Qwen3-8B-AWQ
# 卸载 vLLM
pip uninstall vllm
参考资料
附录：常用命令速查
# WSL 相关
wsl --shutdown # 关闭 WSL
wsl --list # 列出 WSL 发行版
wsl -d Ubuntu-22.04 # 启动特定发行版
# GPU 相关
nvidia-smi # 查看 GPU 状态
nvcc --version # 查看 CUDA 版本
# Python 相关
pip install <package> # 安装包
pip list # 列出已安装包
python -m venv venv # 创建虚拟环境
# vLLM 相关
python -m vllm.entrypoints.openai.api_server --help # 查看帮助
注意：8GB 显存运行 Qwen3 8B AWQ 模型时，建议：
- 设置
gpu-memory-utilization为 0.8-0.85 - 设置
max-model-len为 2048-4096 - 避免同时运行其他 GPU 密集型应用
如有问题，请参考常见问题解决部分或提交 Issue。
扫一扫
6687
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
