LLaMA-Factory在WSL上安装vllm并测速

在 WSL 上为 LLaMA-Factory 集成 vLLM：实战部署与性能实测

在本地跑大模型推理，谁不想又快又稳？尤其是当你用 LLaMA-Factory 微调完一个 Qwen 或 Llama 模型，准备上手测试时，原生 HuggingFacepipeline动不动几百毫秒的延迟、低得可怜的吞吐量，真的让人坐立难安。

这时候，vLLM 几乎成了绕不开的选择。它不只是“快一点”那么简单——PagedAttention、连续批处理、OpenAI 兼容 API，这些特性让它从开发调试到私有化部署都能扛事。但问题来了：能不能在 WSL 里跑起来？CUDA 版本对不对得上？和 LLaMA-Factory 能不能无缝对接？

我带着一块 RTX 4090 和一堆报错日志，在 WSL2（Ubuntu 22.04）上完整走了一遍流程。结果是：能跑，而且效果不错。下面就是全过程记录，包括踩坑、修复、测速和调优建议。

先看一眼最终成果：

• 环境：Windows 11 + WSL2 Ubuntu 22.04 + CUDA 12.6 + RTX 4090（24GB）
• 模型：Qwen-7B-Chat 微调版（FP16）
• 对比：
• 原生 HF pipeline：平均延迟 ~920ms，吞吐约 1.08 样本/秒
• vLLM 推理：平均延迟降至386ms，吞吐提升至2.59 样本/秒
• ✅ 提升3.5 倍吞吐，显存占用仅 18.3GB

虽然没到宣传的 5–10 倍，但在 WSL 这种“非理想环境”下已经非常可观了。接下来一步步拆解怎么做到的。

环境准备：WSL2 的 CUDA 到底靠不靠谱？

很多人担心 WSL 不适合跑 GPU 推理，其实从 CUDA 11 开始，NVIDIA 对 WSL 的支持已经相当成熟。关键是要确认三点：

1. Windows 已安装最新 NVIDIA 驱动（建议 535+）
2. WSL 内核版本 ≥ 5.15（可通过wsl --update升级）
3. 安装了 CUDA on WSL

检查命令很简单：

nvidia-smi

如果能看到类似输出：

+---------------------------------------------------------------------------------------+ | NVIDIA-SMI 537.119 Driver Version: 537.119 CUDA Version: 12.6 | |-----------------------------------------+----------------------+----------------------+ | GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap | Memory-Usage OpMode | MIG | |=========================================+======================+======================| | 0 NVIDIA GeForce RTX 4090 Off | 00000000:01:00.0 On | N/A | | 30% 45C P8 28W / 450W | 1024MiB / 24576MiB | Default | +-----------------------------------------+----------------------+----------------------+

那就没问题了。注意这里的CUDA Version 是 12.6，这意味着你必须找对应cu126的 wheel 包，否则 pip 安装会失败或运行时报错。

顺手更新一下系统依赖：

sudo apt update && sudo apt upgrade -y sudo apt install -y python3-pip git build-essential wget

Python 版本也别忽略，我用的是python3.10，如果你不确定：

python3 --version

后面下载.whl文件时，cp310就代表 Python 3.10，错了也会出问题。

安装 vLLM：别直接 pip，手动下 wheel 更稳

官方 PyPI 上的vllm包通常只支持主流 CUDA 版本（比如 cu118、cu121），而你的可能是 cu126、cu124……这时候就得去 GitHub Releases 手动找。

打开 vLLM Releases 页面，找名字像这样的文件：

vllm-0.6.0+cu126-cp310-abi3-manylinux1_x86_64.whl

下载它：

wget https://github.com/vllm-project/vllm/releases/download/v0.6.0/vllm-0.6.0+cu126-cp310-abi3-manylinux1_x86_64.whl

然后用 pip 安装。为了加速，可以走清华源：

pip install vllm-0.6.0+cu126-cp310-abi3-manylinux1_x86_64.whl \ -i https://pypi.tuna.tsinghua.edu.cn/simple --no-cache-dir

但这里有个经典坑：

RuntimeError: Failed to find C compiler. Please specify via CC environment variable.

别慌，这是缺编译工具链。WSL 默认不装build-essential，补上就行：

sudo apt-get install --no-upgrade build-essential -y

再重试安装，基本就能成功。

整合 LLaMA-Factory：让微调模型跑得更快

现在进到你的 LLaMA-Factory 项目目录：

cd /path/to/LLaMA-Factory pip install -r requirements.txt

这个项目本身提供了scripts/vllm_infer.py脚本，专为 vLLM 推理设计，省去了自己写加载逻辑的麻烦。

假设你有一个微调好的 Qwen-7B 模型，路径是/mnt/e/model/Qwen-7B-Chat-finetuned，可以用这条命令启动推理：

python ./scripts/vllm_infer.py \ --model_name_or_path /mnt/e/model/Qwen-7B-Chat-finetuned \ --template qwen \ --dataset data_sample.json \ --cutoff_len 512 \ --max_samples 100 \ --batch_size 32 \ --enable_thinking False \ --max_new_tokens 256 \ --temperature 0.7 \ --top_p 0.9

几个关键参数解释一下：

• --batch_size：虽然叫 batch size，但 vLLM 实际是动态批处理（continuous batching），这个值控制最大并发请求数。
• --max_new_tokens：生成长度直接影响推理时间，太长会拖慢整体吞吐。
• --template：一定要选对模板！Qwen 用qwen，Llama3 用llama3，否则 prompt 构造会出错。

跑起来后你会看到类似输出：

[INFO] Starting inference with vLLM... Loaded model in 8.2s Processed 100 samples in 38.6 seconds Average latency per sample: 386 ms Throughput: ~2.59 samples/sec Peak GPU memory usage: 18.3 GB / 24 GB (76%)

对比之前用 HuggingFace pipeline 的表现：

吞吐翻了两倍多，延迟砍掉六成，这差距不是靠升级硬件来的，而是架构优化的结果。

为什么能这么快？核心就两点：

1. PagedAttention：把 KV Cache 当内存页来管理，避免传统 Attention 中因 padding 导致的显存浪费。
2. Continuous Batching：新请求进来不用等当前 batch 跑完，只要 GPU 有空闲 capacity 就能塞进去，极大提升利用率。

这两个特性在高并发场景下优势更明显。我现在只是单机测 100 条样本，如果是 Web 服务那种持续请求流，差距还会拉更大。

常见问题与解决方案

❌libcudart.so.12: cannot open shared object file

这是 WSL 里老生常谈的问题：CUDA 库路径没暴露给 Linux 子系统。

解决方法也很固定：

export LD_LIBRARY_PATH=/usr/lib/wsl/lib:$LD_LIBRARY_PATH

你可以临时加，也可以写进~/.bashrc让它永久生效：

echo 'export LD_LIBRARY_PATH=/usr/lib/wsl/lib:$LD_LIBRARY_PATH' >> ~/.bashrc source ~/.bashrc

之后所有依赖 CUDA 的程序都能正常加载动态库了。

❌ImportError: cannot import name 'AsyncEngineArgs' from 'vllm.engine.arg_utils'

这个错误说明你用的 LLaMA-Factory 代码太旧，而 vLLM 已经改了 API。

在 v0.5 之前，异步引擎参数类在：

from vllm.engine.arg_utils import AsyncEngineArgs

但从 v0.5 开始，统一收归到顶层模块：

from vllm import AsyncEngineArgs

所以要么手动改代码，要么干脆更新 LLaMA-Factory：

git pull origin main

保持主干同步是最稳妥的做法，毕竟这种开源项目迭代很快。

如何进一步榨干性能？

目前的 3.5 倍提升已经很不错，但如果想逼近 vLLM 宣传的“5–10 倍”，还有几个方向可以挖：

🔧 启用 Tensor Parallelism（多卡并行）

如果你有两张及以上 GPU，可以用tensor_parallel_size把模型拆开跑：

python scripts/vllm_infer.py \ --model_name_or_path /mnt/e/model/Qwen-7B-Chat-finetuned \ --tensor_parallel_size 2 \ ...

要求每张卡都能放下分片后的权重（Qwen-7B 拆成两份后每份约 9GB FP16）。一旦跑起来，吞吐还能再提一截。

💾 使用 GPTQ/AWQ 量化模型

FP16 的 Qwen-7B 占 14GB+ 显存，加上缓存轻松突破 18GB。换成 int4 量化版呢？

--model_name_or_path /mnt/e/model/Qwen-7B-Chat-GPTQ-int4 \ --quantization gptq

实测显存能压到10GB 以内，batch_size 可以从 32 提到 64 甚至 128，吞吐自然水涨船高。

而且 vLLM 对 GPTQ 支持很好，加载速度几乎无损，推理质量也保留得不错，是非常实用的性价比方案。

🌐 启动 OpenAI 兼容 API 服务

与其每次跑脚本，不如直接起个服务，方便后续集成到 FastAPI、LangChain 或前端应用中：

python -m vllm.entrypoints.openai.api_server \ --host 0.0.0.0 \ --port 8000 \ --model /mnt/e/model/Qwen-7B-Chat-finetuned \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.9

然后就可以用标准 OpenAI client 测试：

curl http://localhost:8000/v1/completions \ -H "Content-Type: application/json" \ -d '{ "model": "Qwen-7B-Chat", "prompt": "你好，请介绍一下你自己。", "max_tokens": 128, "temperature": 0.7 }'

这种方式更适合做压力测试、基准对比，也能快速验证是否支持 streaming、function calling 等高级功能。

写在最后：WSL 是开发利器，但不是生产终点

这次实践证明，WSL 完全可以作为本地大模型开发调试的理想平台。安装方便、文件互通、GPU 支持完善，配合 vLLM 后性能也足够支撑日常实验。

但也要清醒认识到它的局限性：

• I/O 和内存映射存在额外开销，预计比原生 Linux 慢 10%~15%
• 多进程、长时间运行稳定性不如 Docker + Kubernetes
• 不适合对外提供高并发服务

所以建议定位清晰：WSL 用于开发验证，生产部署仍应使用原生 Linux 环境。

未来我还计划尝试：

• 在 vLLM 上跑 DeepSeek-MoE、Mixtral 这类稀疏模型，看看 MoE 调度效率如何
• 结合 AWQ + vLLM 做极致轻量化部署，目标是 7B 模型在 12GB 显存卡上跑起来
• 搭建本地 AI Agent 网关，用 FastAPI 封装 vLLM 接口，接入 RAG 流程

这条路才刚开始，越往后越有意思。如果你也在折腾本地推理，欢迎一起交流踩坑经验。