零基础搞定vLLM：Windows+WSL2+Ubuntu24.04+Docker全流程实录
最近身边不少朋友开始尝试本地部署大语言模型，但一看到Linux、Docker这些词就头疼。作为从Windows一路摸爬滚打过来的开发者，我完全理解这种感受。今天这篇记录，就是为你准备的——如果你是完全没接触过Linux环境的Windows用户，想在自己的电脑上跑起vLLM这个高效的推理框架，那么跟着下面的步骤走，大概率能避开我踩过的那些坑。
整个过程我会从最基础的WSL2安装讲起，包括如何把Ubuntu系统从默认的C盘迁移到其他盘（这个对C盘空间紧张的朋友至关重要），再到Docker的配置和vLLM容器的启动。每个命令我都会解释清楚，遇到可能卡住的地方也会提前预警。咱们不追求理论深度，目标就一个：让你能亲手在自己的机器上把服务跑起来。
1. 基础环境搭建：WSL2与Ubuntu 24.04
在Windows上运行Linux应用，WSL2（Windows Subsystem for Linux）是目前最顺畅的方案。它不是一个完整的虚拟机，性能损耗小，和Windows系统的文件互访也很方便。我们的第一步就是把它装好。
打开Windows PowerShell（不是命令提示符CMD）。在开始菜单搜索“PowerShell”，右键选择“以管理员身份运行”。这是后续所有系统级操作的基础。
在闪烁的光标处，输入以下命令并回车：
wsl --install
这个命令会默认安装WSL2和Ubuntu发行版。但这里有个小问题：默认的Ubuntu版本可能不是最新的，且安装位置不可控。我更喜欢明确指定版本和后续的安装路径，所以更推荐下面这个流程。
首先，只安装WSL2的基础功能，不附带任何Linux发行版：
wsl --install --no-distribution
执行后系统可能会提示重启，按照要求操作即可。重启后再次以管理员身份打开PowerShell，查看可用的Linux发行版列表：
wsl --list --online
你会看到一个列表，其中应该包含“Ubuntu-24.04”。接下来安装它：
wsl --install -d Ubuntu-24.04
安装过程中，系统会提示你创建Unix用户名和密码。这个密码在后续使用sudo命令时会经常用到，请务必记住。
安装完成后，你可以在开始菜单找到“Ubuntu 24.04 on Windows”并启动它。第一次启动会进行初始化，稍等片刻就会看到一个Linux终端窗口。恭喜，你的Windows里已经有一个完整的Linux子系统了。
提示：如果你在安装或更新过程中遇到网络速度极慢的问题，可能是因为系统服务访问网络的方式受限。这个问题我们会在后续配置中解决，暂时可以先跳过。
1.1 迁移Ubuntu安装位置，释放C盘空间
WSL默认将Linux发行版安装在C盘用户目录下。随着我们后续安装软件、拉取Docker镜像和模型文件，这个虚拟磁盘文件会变得非常庞大，很容易挤占宝贵的C盘空间。因此，在开始深入使用前，我强烈建议你先把它迁移到其他盘符。
迁移的原理是：将当前系统导出为一个备份文件，然后从备份文件导入到一个新的位置。以下是详细步骤：
-
关闭WSL：首先，我们需要停止正在运行的Ubuntu子系统。在刚才的管理员PowerShell中执行：
wsl --shutdown这个命令会终止所有WSL实例的运行。
-
确认状态：输入以下命令，查看所有WSL分发版的状态。
wsl -l -v如果看到Ubuntu-24.04的
STATE显示为Stopped，说明已经成功关闭。 -
准备新位置：在你的目标盘（比如D盘、E盘）创建一个文件夹，例如
D:\WSL\Ubuntu24。这个路径将作为新系统的家。 -
导出系统：将现有的Ubuntu系统导出为一个压缩包。在PowerShell中执行（请将路径替换为你刚才创建的实际路径）：
wsl --export Ubuntu-24.04 D:\WSL\Ubuntu24\ubuntu_backup.tar这个过程可能需要几分钟，时间取决于你已安装系统的大小。
-
注销原系统：导出成功后，就可以移除旧的、仍在C盘的系统了。
wsl --unregister Ubuntu-24.04系统会提示确认，输入
y并回车。再次运行wsl -l -v，如果列表为空，说明卸载成功。 -
导入到新位置：现在，从备份文件在新位置创建一个全新的Ubuntu实例。
wsl --import Ubuntu-24.04 D:\WSL\Ubuntu24 D:\WSL\Ubuntu24\ubuntu_backup.tar --version 2这里的
--version 2指定使用WSL2。导入完成后，你可以再次用wsl -l -v查看，新的Ubuntu-24.04应该已经出现在列表中，其STATE是Stopped。 -
设置默认用户：导入的系统默认以root用户启动。我们需要将其恢复到你之前创建的那个普通用户。首先，启动一次这个新导入的系统：
wsl -d Ubuntu-24.04进入系统后，编辑WSL配置文件：
sudo nano /etc/wsl.conf在文件中添加以下内容（如果文件不存在就创建）：
[user] default=你的用户名按
Ctrl+X，然后按Y，再回车保存退出。最后，退出WSL（输入exit），并再次关闭WSL：wsl --shutdown之后，当你从开始菜单启动“Ubuntu 24.04”，它就会以你指定的用户身份登录了。
-
清理备份文件：确认新系统运行无误后，可以安全删除
D:\WSL\Ubuntu24\ubuntu_backup.tar文件以节省空间。
2. 配置WSL2与安装Docker Desktop
系统位置搞定后，我们来优化一下WSL2的网络和基础配置，然后安装关键的Docker环境。
2.1 WSL2基础配置优化
为了让WSL2更好用，有几个设置值得调整。在Ubuntu终端内，首先更新软件包列表并升级现有软件：
sudo apt update && sudo apt upgrade -y
安装一些常用的工具，比如用于下载的wget和curl：
sudo apt install -y wget curl git
关于网络访问：如果你在Windows主机上运行了一些本地服务（比如开发用的后端），并希望从WSL2内部访问它们，你会发现直接用localhost不行。这是因为WSL2有自己的虚拟网络。解决方法是使用主机IP。可以在WSL2中通过以下命令获取主机IP：
cat /etc/resolv.conf | grep nameserver | awk '{print $2}'
通常这个IP是172.x.x.x。在WSL2中访问Windows服务时，就用这个IP替换localhost。
2.2 安装Docker Desktop for Windows
vLLM官方推荐使用Docker进行部署，这能省去大量配置Python环境、CUDA驱动依赖的麻烦。我们在Windows上安装Docker Desktop，并让它集成WSL2。
-
下载安装包：访问Docker官网的下载页面，获取Docker Desktop for Windows的安装程序。安装过程基本就是一路“Next”，但有两个关键点需要注意：
- 安装时会询问是否使用WSL2代替Hyper-V，务必勾选。
- 安装完成后，建议重启电脑。
-
配置Docker Desktop：启动Docker Desktop，在系统托盘找到鲸鱼图标，右键进入“Settings”。
- General：确保“Use the WSL 2 based engine”选项已勾选。
- Resources -> WSL Integration：在这里，启用对你刚安装的“Ubuntu-24.04”发行版的集成。这个操作允许你在Ubuntu终端里直接使用
docker命令。
-
验证安装：打开Ubuntu 24.04终端，输入：
docker --version如果正确显示版本号（如
Docker version 26.x.x），说明Docker已经成功集成到WSL2环境中。 -
配置镜像加速器（可选但强烈推荐）：从Docker Hub拉取镜像速度可能较慢。我们可以配置国内镜像源。在Windows上，右键点击Docker托盘图标，选择“Settings”，进入Docker Engine选项卡。编辑其中的JSON配置，在
registry-mirrors部分添加国内镜像地址。例如：{ "registry-mirrors": [ "https://docker.mirrors.ustc.edu.cn", "https://hub-mirror.c.163.com" ] }点击“Apply & Restart”保存并重启Docker服务。
3. 拉取并运行vLLM OpenAI API服务器
环境准备就绪，现在进入核心环节：部署vLLM服务。vLLM项目提供了预构建的Docker镜像，里面包含了所有必要的依赖，我们直接使用即可。
3.1 拉取vLLM Docker镜像
在Ubuntu终端中，执行拉取命令：
docker pull vllm/vllm-openai:latest
这个镜像包含了vLLM框架以及兼容OpenAI API格式的服务器。由于镜像体积较大（几个GB），根据你的网络情况，下载可能需要一段时间。如果速度不理想，可以确认上一步的Docker镜像加速器是否生效。
3.2 准备模型文件
vLLM本身不包含模型，它需要一个加载好的模型路径。你需要提前下载好你想运行的大模型权重文件。这里以一个小尺寸的模型为例，比如Qwen2.5-0.5B，方便快速测试。
- 在Windows文件系统中找一个空间充足的盘符，创建存放模型的文件夹，例如
E:\AI_Models\Qwen2.5-0.5B。 - 从模型发布页面（如Hugging Face Model Hub）下载模型的所有文件到这个文件夹。你可以使用
git lfs，或者一些下载工具。 - 记住这个Windows路径，我们需要在Docker命令中将它“映射”到容器内部。
3.3 启动vLLM容器
这是最关键的一步命令。在Ubuntu终端中，切换到你有权限的目录，然后执行一个长命令，我会拆解每个参数的含义：
docker run -d \
--gpus all \
-p 8000:8000 \
--name my-vllm-server \
-v /mnt/e/AI_Models/Qwen2.5-0.5B:/models \
vllm/vllm-openai:latest \
--model /models \
--host 0.0.0.0 \
--port 8000 \
--tensor-parallel-size 1
让我们逐一解释：
-d：让容器在后台运行（daemon模式）。--gpus all：将宿主机的所有GPU暴露给容器使用。这要求你的Windows已安装正确的NVIDIA显卡驱动，并且WSL2内已安装NVIDIA CUDA驱动（通常Docker Desktop会处理）。-p 8000:8000：端口映射。将容器内的8000端口映射到宿主机的8000端口。这样我们就能通过localhost:8000访问服务。--name my-vllm-server：给容器起个名字，方便后续管理。-v /mnt/e/AI_Models/Qwen2.5-0.5B:/models：这是卷挂载，至关重要。/mnt/e/是WSL2中访问Windows E盘的方式。我们将Windows上的模型文件夹映射到容器内的/models目录。vllm/vllm-openai:latest：指定使用的镜像。--model /models：告诉vLLM，模型权重在容器内的/models路径下。--host 0.0.0.0：服务监听所有网络接口。--port 8000：服务在容器内监听的端口。--tensor-parallel-size 1：对于小模型，通常设置为1（单GPU）。如果你有多个GPU并想进行张量并行推理，可以调整此值。
执行命令后，Docker会开始创建并启动容器。你可以使用以下命令查看容器日志，确认启动是否成功：
docker logs -f my-vllm-server
当你在日志中看到类似“Uvicorn running on http://0.0.0.0:8000”以及“Model weights loaded.”的信息时，说明服务已经就绪。
4. 验证服务与基础使用
服务跑起来后，我们得确认它工作正常，并且学会怎么调用它。
4.1 基础验证方法
有几种简单的方法可以验证vLLM服务器是否在正常运行：
-
访问API文档：打开你的Windows浏览器，访问
http://localhost:8000/docs。你应该能看到一个自动生成的OpenAI兼容API的交互式文档页面（Swagger UI）。这本身就能证明HTTP服务是活的。 -
使用简单的curl命令测试：在Ubuntu终端或Windows PowerShell中，可以发送一个测试请求：
curl http://localhost:8000/v1/completions \ -H "Content-Type: application/json" \ -d '{ "model": "/models", "prompt": "法国的首都是哪里？", "max_tokens": 20 }'如果返回一个包含生成文本的JSON响应，那就大功告成了。
-
检查GPU使用情况：在Windows上，打开“任务管理器”，切换到“性能”选项卡，选择你的GPU。在vLLM容器运行并处理请求时，你应该能看到GPU利用率、显存占用等指标有显著变化。
4.2 使用Python客户端调用
更实际的方式是用Python代码调用。在你的开发环境中（可以是Windows下的Python，也可以是WSL2里的Python），确保安装了openai库（注意，vLLM兼容OpenAI的客户端协议）。
# test_vllm.py
from openai import OpenAI
# 注意，这里的基础URL指向我们本地启动的服务
client = OpenAI(
base_url="http://localhost:8000/v1",
api_key="token-abc123" # vLLM默认不需要验证，但客户端要求提供，任意字符串即可
)
# 测试补全接口
completion = client.completions.create(
model="/models", # 模型名称，与启动命令中的--model参数一致
prompt="请用一句话介绍人工智能。",
max_tokens=50
)
print("补全结果:", completion.choices[0].text)
# 测试聊天接口（如果模型支持）
chat_completion = client.chat.completions.create(
model="/models",
messages=[
{"role": "system", "content": "你是一个乐于助人的助手。"},
{"role": "user", "content": "你好，请自我介绍一下。"}
]
)
print("聊天回复:", chat_completion.choices[0].message.content)
运行这个脚本，你应该能得到模型生成的回复。
4.3 理解显存占用与关键参数
很多朋友第一次运行vLLM时，会惊讶地发现即使加载一个很小的模型，任务管理器里显示的GPU显存占用也接近爆满。这通常是正常现象，而非内存泄漏。原因主要在于vLLM的两个设计：
- PagedAttention与KV Cache：vLLM的核心优化技术需要预留空间来高效管理注意力机制的键值缓存（KV Cache），这部分内存是预分配的，以提高吞吐量。
- CUDA Graphs：为了极致推理性能，vLLM会使用CUDA Graphs来“预编译”计算图，这也会额外占用一部分显存作为缓存。
启动命令中有一个关键参数--gpu-memory-utilization（在最新版本中可能为--gpu-memory-utilization或在服务器启动后通过配置设定），它默认为0.9（即90%）。这意味着vLLM会尝试使用90%的可用显存。对于拥有大显存的显卡，这个绝对数值就会显得很大。
| 参数 | 默认值 | 说明 | 调整建议 |
|---|---|---|---|
--gpu-memory-utilization | 0.9 | vLLM尝试使用的最大显存比例。 | 如果你的显存较小，或需要同时运行其他GPU应用，可以调低，如0.7。 |
--tensor-parallel-size | 1 | 张量并行度，用于多GPU拆分模型。 | 单GPU保持为1。多GPU时可增大，但需模型支持且不超过GPU数量。 |
--max-model-len | 无特殊限制 | 模型能处理的最大上下文长度（tokens）。 | 设置过低影响长文本能力，设置过高会增加显存占用。根据需求调整。 |
--dtype | auto | 模型权重加载的数据类型，如float16, bfloat16。 | float16通用性好；bfloat16在某些新硬件上性能更佳，但兼容性需验证。 |
如果你想在启动时控制显存占用，可以在Docker启动命令的最后加上这个参数，例如：
... vllm/vllm-openai:latest --model /models ... --gpu-memory-utilization 0.7
5. 日常管理与故障排查
服务部署好之后，还有一些日常操作和常见问题的解决方法。
5.1 容器管理命令
掌握几个基本的Docker命令，方便管理你的vLLM服务：
- 查看运行中的容器：
docker ps - 查看所有容器（包括已停止的）：
docker ps -a - 停止容器：
docker stop my-vllm-server - 启动已停止的容器：
docker start my-vllm-server - 重启容器：
docker restart my-vllm-server - 进入容器内部（调试用）：
docker exec -it my-vllm-server /bin/bash - 删除容器：先停止，再
docker rm my-vllm-server - 查看容器日志：
docker logs my-vllm-server（加-f参数可以实时跟踪日志输出）
5.2 常见问题与解决思路
-
启动失败：
docker: Error response from daemon: could not select device driver...- 原因：Docker无法访问GPU。通常是NVIDIA容器工具包未安装或WSL2的NVIDIA驱动有问题。
- 解决：确保Windows已安装最新版NVIDIA Game Ready或Studio驱动。然后在WSL2的Ubuntu中，尝试安装
nvidia-container-toolkit（但更常见的是，Docker Desktop的WSL2集成应该自动处理了）。重启Docker Desktop和WSL2。
-
启动失败：
Failed to load model ...- 原因：模型路径错误或模型文件不完整、格式不对。
- 解决：检查Docker命令中
-v参数映射的路径是否正确。确认Windows模型文件夹内的文件是否完整下载（应包含config.json,pytorch_model.bin或safetensors文件等）。可以在Ubuntu中通过ls -la /mnt/e/...检查路径是否存在和可读。
-
服务启动成功，但API调用返回错误或超时
- 原因：可能是模型加载失败但服务进程未退出，或者端口冲突。
- 解决：首先查看容器日志
docker logs my-vllm-server，看是否有ERROR信息。检查端口8000是否被Windows上的其他程序占用。可以尝试将启动命令中的-p 8000:8000改为-p 8001:8000，然后通过localhost:8001访问。
-
拉取镜像或模型下载速度极慢
- 原因：网络连接问题。
- 解决：确保Docker镜像加速器配置正确。对于模型下载，可以考虑在网络条件好的环境中先下载好，再拷贝到本地。或者寻找国内镜像站。
整个流程走下来，你可能花了几个小时，但收获的是一套在个人Windows电脑上运行现代大模型推理服务的完整能力。这套组合（WSL2 + Docker）的价值远不止于vLLM，它为你打开了一扇门，让你能够几乎无痛地使用绝大多数为Linux生态设计的开发工具和开源项目。下次再遇到“仅支持Linux”的软件时，你大可以自信地说：我的Windows，也能行。
797
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
