Windows 11 + WSL2 + vLLM 本地部署 Qwen3 8B AWQ 指南

目录

1. 系统要求
2. 环境准备
3. WSL2 Ubuntu 安装配置
4. NVIDIA 驱动配置
5. CUDA 环境安装
6. Python 环境搭建
7. vLLM 安装
8. Qwen3 8B AWQ 模型下载（国内加速）
9. 启动 vLLM 服务
10. API 测试验证
11. 常见问题解决
12. 性能优化建议

系统要求

硬件要求

• 操作系统: 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.04wsl--install-d Ubuntu-22.04

安装完成后，启动 Ubuntu，设置用户名和密码。

WSL2 Ubuntu 安装配置

1. 更新系统软件包

# 更新软件包列表sudoaptupdate&&sudoaptupgrade -y# 安装必要工具sudoaptinstall-ywgetcurlgitbuild-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 包仓库wgethttps://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.debsudodpkg -i cuda-keyring_1.1-1_all.debsudoapt-getupdate# 安装 NVIDIA 驱动（WSL2 专用）sudoapt-getinstall-y nvidia-cuda-toolkit

3. 验证 GPU 识别

# 检查 nvidia-smi 是否可用nvidia-smi# 预期输出应显示 GPU 信息，包括显存使用情况

如果 nvidia-smi 不可用，尝试：

# 设置 CUDA 路径exportPATH="/usr/local/cuda-12.6/bin:$PATH"exportLD_LIBRARY_PATH="/usr/local/cuda-12.6/lib64:$LD_LIBRARY_PATH"

CUDA 环境安装

1. 安装 CUDA Toolkit

# 添加 CUDA 包仓库wgethttps://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.debsudodpkg -i cuda-keyring_1.1-1_all.debsudoapt-getupdate# 安装 CUDA 12.6sudoapt-getinstall-y cuda-toolkit-12-6 cuda-libraries-dev-12-6

2. 配置环境变量

编辑~/.bashrc文件：

nano~/.bashrc

在文件末尾添加：

# CUDA 配置exportCUDA_HOME=/usr/local/cuda-12.6exportLD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATHexportPATH=$CUDA_HOME/bin:$PATHexportNVIDIA_VISIBLE_DEVICES=allexportCUDA_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+sudoaptinstall-y python3.10 python3-pip python3-venv python3-dev# 升级 pippipinstall--upgrade pip# 设置 pip 镜像源（国内加速）pip configsetglobal.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip configsetglobal.trusted-host pypi.tuna.tsinghua.edu.cn

2. 创建虚拟环境

# 创建项目目录mkdir-p ~/qwen3-deploymentcd~/qwen3-deployment# 创建 Python 虚拟环境python3 -m venv venv# 激活虚拟环境sourcevenv/bin/activate

3. 安装依赖包

# 升级 pippipinstall--upgrade pip# 安装 PyTorch（CUDA 版本）pipinstalltorch==2.7.1+cu126torchvision==0.22.1+cu126torchaudio==2.7.1+cu126 --index-url https://download.pytorch.org/whl/cu126# 安装 transformers（>=4.36.0）pipinstalltransformers>=4.36.0# 安装其他必要包pipinstallaccelerate tiktoken einops scipy

vLLM 安装

方法一：通过 pip 安装（推荐）

# 安装最新稳定版 vLLMpipinstallvllm# 或者安装特定版本pipinstallvllm==0.6.6

方法二：从源码编译安装

# 克隆 vLLM 仓库gitclone https://github.com/vllm-project/vllm.gitcdvllm# 安装构建依赖pipinstall-r requirements-build.txt# 编译安装（需要较长时间，约 15-30 分钟）pipinstall-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

pipinstall-U huggingface_hub

2. 设置镜像环境变量

# 临时设置（每次下载前执行）exportHF_ENDPOINT=https://hf-mirror.com# 永久设置（添加到 ~/.bashrc）echo'export HF_ENDPOINT=https://hf-mirror.com'>>~/.bashrcsource~/.bashrc

3. 下载模型

# 创建模型目录mkdir-p ~/modelscd~/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 镜像站

# 安装 modelscopepipinstallmodelscope# 下载模型from modelscopeimportsnapshot_download model_dir=snapshot_download('qwen/Qwen3-8B-AWQ')

方案三：阿里云盘/百度网盘分享

如果 Hugging Face 下载速度仍然较慢，可以：

1. 从阿里云盘搜索 “Qwen3-8B-AWQ”
2. 从百度网盘搜索 “Qwen3-8B-AWQ”
3. 下载后上传到 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# 设置环境变量exportCUDA_VISIBLE_DEVICES=0exportVLLM_WORKER_MULTIPROC_METHOD=spawn# 启动 vLLM 服务python -m vllm.entrypoints.openai.api_server\--model ~/models/Qwen3-8B-AWQ\--host0.0.0.0\--port8000\--trust-remote-code\--quantization awq\--dtype half\--gpu-memory-utilization0.85\--max-model-len4096\--tensor-parallel-size1\--enforce-eager

2. 设置执行权限

chmod+x ~/qwen3-deployment/start_vllm.sh

3. 启动服务

cd~/qwen3-deployment ./start_vllm.sh

4. 首次启动说明

首次启动时，vLLM 会：

1. 加载模型权重（约 5-10 分钟）
2. 编译优化内核（约 2-5 分钟）
3. 完成后显示服务就绪信息

5. 后台运行（可选）

如果需要后台运行：

# 使用 nohupnohup./start_vllm.sh>vllm.log2>&1&# 或使用 screensudoaptinstall-yscreenscreen-S vllm ./start_vllm.sh# 按 Ctrl+A+D 分离 screen# 重新连接: screen -r vllm

API 测试验证

1. 检查服务状态

# 检查服务是否运行curlhttp://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 测试

importopenai 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)

安装测试依赖

pipinstallopenai

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. 模型信息查询

curlhttp://localhost:8000/v1/models

常见问题解决

问题 1：NVIDIA 驱动未识别

错误信息：nvidia-smi: command not found

解决方法：

# 重新安装 NVIDIA 驱动sudoaptupdatesudoaptinstall-y nvidia-driver-535+# 重启 WSLwsl --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.1pipinstalltorch==2.7.1+cu126torchvision==0.22.1+cu126 -f https://download.pytorch.org/whl/cu126.html

问题 3：显存不足

错误信息：CUDA out of memory

解决方法：

# 降低 gpu-memory-utilization--gpu-memory-utilization0.7# 降低 max-model-len--max-model-len2048# 启用量化--quantization awq

问题 4：模型下载失败

错误信息：ConnectionError或下载速度极慢

解决方法：

# 方案 1：使用镜像站exportHF_ENDPOINT=https://hf-mirror.com huggingface-cli download --resume-download Qwen/Qwen3-8B-AWQ --local-dir ~/models/Qwen3-8B-AWQ# 方案 2：使用 aria2 加速sudoaptinstall-y aria2 aria2c -x8-s8"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：使用代理exportHTTPS_PROXY="http://127.0.0.1:7890"exportHTTP_PROXY="http://127.0.0.1:7890"

问题 5：vLLM 启动失败

错误信息：ImportError: libcuda.so.1 cannot open shared object file

解决方法：

# 查找 libcuda.sosudofind/usr -name"libcuda.so*"# 创建软链接sudoln-sf /usr/lib/wsl/lib/libcuda.so.1 /usr/lib/libcuda.so.1# 或者添加到 LD_LIBRARY_PATHexportLD_LIBRARY_PATH=/usr/lib/wsl/lib:$LD_LIBRARY_PATH

问题 6：WSL2 内存占用过高

错误信息：系统变卡，内存不足

解决方法：

# 在 Windows 上编辑 .wslconfignotepad$env:USERPROFILE\.wslconfig

[wsl2] memory=8GB processors=4 swap=4GB

然后重启 WSL。

问题 7：端口不通

错误信息：curl: (7) Failed to connect to localhost port 8000

解决方法：

# 检查服务是否运行psaux|grepvllm# 检查端口监听netstat-tuln|grep8000# 关闭防火墙（如果需要）sudoufw disable# 或者开放端口sudoufw allow8000

问题 8：AWQ 量化支持问题

错误信息：ValueError: AWQ is not supported on this hardware

解决方法：

# 确保使用正确版本的 vLLMpipinstallvllm>=0.6.0# 检查 CUDA 版本nvcc --version# 重新编译 vLLMcdvllm pipinstall-e.--no-build-isolation

性能优化建议

1. 内存和显存优化

# 降低显存占用--gpu-memory-utilization0.8\--max-model-len4096\# 使用更小的批处理大小--max-batch-size32\

2. 吞吐量优化

# 启用多批处理--enable-auto-chunking\--max-num-batched-tokens4096\

3. 延迟优化

# 降低延迟--enforce-eager\--disable-log-requests\

4. 完整优化启动脚本

#!/bin/bashsource~/qwen3-deployment/venv/bin/activateexportCUDA_VISIBLE_DEVICES=0python -m vllm.entrypoints.openai.api_server\--model ~/models/Qwen3-8B-AWQ\--host0.0.0.0\--port8000\--trust-remote-code\--quantization awq\--dtype half\--gpu-memory-utilization0.85\--max-model-len4096\--tensor-parallel-size1\--enforce-eager\--disable-log-requests\--max-batch-size64\--max-num-batched-tokens4096

监控和维护

1. GPU 监控

# 实时监控 GPU 使用情况watch-n1nvidia-smi# 查看显存使用nvidia-smi -q -d MEMORY

2. 服务日志

# 查看服务日志tail-f ~/qwen3-deployment/vllm.log

3. API 性能监控

# 查看 API 延迟统计curlhttp://localhost:8000/stats

卸载和清理

1. 停止服务

# 查看进程psaux|grepvllm# 停止进程kill<PID>

2. 清理环境

# 删除虚拟环境rm-rf ~/qwen3-deployment/venv# 删除模型文件（如果需要）rm-rf ~/models/Qwen3-8B-AWQ# 卸载 vLLMpip uninstall vllm

参考资料

• vLLM 官方文档
• Qwen3 官方文档
• Hugging Face 镜像站
• NVIDIA WSL2 驱动
• PyTorch CUDA 版本

附录：常用命令速查

# WSL 相关wsl --shutdown# 关闭 WSLwsl --list# 列出 WSL 发行版wsl -d Ubuntu-22.04# 启动特定发行版# GPU 相关nvidia-smi# 查看 GPU 状态nvcc --version# 查看 CUDA 版本# Python 相关pipinstall<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。