当前位置： 首页 > news >正文

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

news 2026/4/5 3:30:55

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。

http://www.jsqmd.com/news/264316/

相关文章：

  • 导师严选！专科生必看8款AI论文平台测评
  • 基于51/STM32单片机智能水杯保温杯恒温温度控制防干烧水质设计(设计源文件+万字报告+讲解)（支持资料、图片参考_相关定制）_文章底部可以扫码
  • 文明十字路口的协同创生：《人类命运共同体》文明逻辑与“AI元人文”构想的思想共鸣
  • 【LGR-262-Div.2】洛谷 1 月月赛 III 题解
  • 2026国产制动卡钳优质产品推荐榜全场景适配 - 改装小龙
  • 数据清洗：大数据领域的必备技能
  • 致敬：国家有突出贡献电影艺术家、中华人民共和国电影电视艺术家大典入选者陶玉玲
  • 提示工程架构师实操指南：Agentic AI在医疗健康领域从0到1落地全流程
  • STM32单片机语音识别智能家居系统99X(设计源文件+万字报告+讲解)（支持资料、图片参考_相关定制）_文章底部可以扫码
  • Flash了解学习
  • 到06结束 10（） 11 12 【1看了】
  • Storm资源调度策略：提升大数据处理集群效率
  • 2026年真空防爆烘箱厂家实力推荐：专业定制工业级防爆烘箱，高效安全烘烤设备源头工厂精选 - 企业推荐官【官方】
  • Qt UDP通信：缓冲区大小设置技巧
  • sdkman同时存在多个jdk的方式
  • 亲测好用8个AI论文写作软件，继续教育学生轻松搞定毕业论文！
  • 2026年10款免费降ai率工具实测：还有免费ai查重！从降ai到aigc免费降重，总有一款适合你
  • 12种智能写作工具测评：数学建模论文高效重现与专业格式优化指南
  • 论文AIGC率高怎么降？2026最新10个免费降ai率工具测评（附3个免费降低ai率方法）
  • 英特尔掌门陈立武力荐极摩客，国产迷你主机凭什么？
  • 救命神器！10款一键生成论文工具测评：研究生开题报告全攻略
  • 论文AIGC率高怎么降？2026最新10个免费降ai率工具测评（附不花一分钱降ai率技巧）
  • 12款AI辅助论文工具测评：数学建模论文高效复现与格式精细调整方案
  • 论文AIGC率高怎么降？2026最新10个免费降ai率工具测评（亲测降至5%以下！附方法）
  • 12款智能写作软件深度评估：数学建模论文快速还原与专业排版解决方案
  • 跟着Datawhale动手学Agent - TASK4: 大作业-实现一个Agent
  • 2026必备！专科生论文难题TOP8AI论文网站测评
  • 论文AIGC痕迹太重怎么降？2026最新10个免费降ai率工具测评（还有免费ai查重福利）
  • 凭据获取——windows单机凭据获取
  • 超算AI任务调度：架构师的动态资源分配策略