2、vLLM安装与配置：环境要求、pip安装、源码编译、配置文件详解

好，咱们正式开始动手了。

这一章，我带你把vLLM装起来，再把配置文件捋一遍。说实话，安装这一步看着简单，但坑是真不少。我见过太多人卡在CUDA版本不对、Python版本不兼容这种问题上，一卡就是半天。

所以，咱们先把环境要求搞清楚，再选一种安装方式，最后把配置文件吃透。这样你后面部署模型的时候，心里才有底。

2.1 环境要求：先把地基打好

vLLM对底层环境的要求，说白了就三个核心：CUDA、Python、PyTorch。这三样但凡有一个版本对不上，安装就会报错。

2.1.1 CUDA版本

vLLM依赖CUDA来做GPU加速。我个人习惯用CUDA 11.8或12.1，这两个版本目前兼容性最好。

  • CUDA 11.8：稳定，兼容老卡（如V100、A100）
  • CUDA 12.1：新特性多，适合H100、L40S等新卡
⚠️ 注意： 我曾经在CUDA 11.4上试过，编译直接报错。建议别低于11.8。

2.1.2 Python版本

vLLM官方推荐Python 3.10或3.11。我个人建议直接用3.10，因为3.11在某些旧版PyTorch上会有兼容问题。

你想想看，如果Python版本不对，pip install的时候可能直接给你来个「找不到匹配的发行版」，那多闹心。

2.1.3 PyTorch版本

vLLM需要PyTorch 2.0以上。我建议用2.1或2.2，这两个版本对Flash Attention的支持最好。

组件 最低版本 推荐版本
CUDA 11.8 12.1
Python 3.8 3.10
PyTorch 2.0 2.1.2

2.2 pip安装：最快的方式

如果你只是想快速体验vLLM，pip安装是最省事的。直接一行命令搞定：

pip install vllm

嗯，这里要注意。这个命令会从PyPI拉取预编译的wheel包。但前提是你的CUDA版本和系统架构得匹配。如果匹配不上，它会尝试源码编译，那时间就长了。

💡 小技巧： 我建议先创建一个干净的虚拟环境，再装vLLM。避免跟其他项目的依赖打架。 
python -m venv vllm_env
source vllm_env/bin/activate
pip install vllm

装完之后，你可以跑个简单的测试：

python -c "from vllm import LLM; print('vLLM installed successfully')"

如果没报错，恭喜你，装好了。

2.3 源码编译：定制化需求

有些场景下，pip安装满足不了你。比如你想用最新的commit、或者想针对自己的GPU做优化编译。这时候就得源码编译了。

我记得有一次，客户要在A10卡上跑vLLM，但pip安装的版本对A10的优化不够好。我直接拉源码编译，把CUDA架构参数改成sm_86，性能提升了将近15%。

源码编译的步骤：

  1. 克隆仓库
git clone https://github.com/vllm-project/vllm.git
cd vllm
  1. 安装依赖
pip install -r requirements.txt
  1. 编译安装
pip install -e .

这个过程会比较久，大概10到30分钟，取决于你的机器性能。编译的时候CPU会跑满，别慌，正常现象。

⚠️ 注意： 编译前确保你的gcc版本在9以上。我曾在gcc 7上编译，报了一堆模板错误。

2.4 配置文件详解：vLLM的灵魂

vLLM的配置，主要通过命令行参数或者Python API来传递。没有单独的配置文件，但参数很多，我挑几个核心的讲。

2.4.1 模型加载参数

  • --model：模型名称或路径。比如meta-llama/Llama-2-7b-chat-hf
  • --dtype：数据类型。推荐auto或bfloat16。我一般用bfloat16，精度够，显存省。
  • --tensor-parallel-size：张量并行度。如果你有4张卡，设成4，模型会被切分到4张卡上。

2.4.2 推理服务参数

  • --port：服务端口，默认8000
  • --max-model-len：最大输入长度。默认4096，但如果你显存够，可以设到8192
  • --gpu-memory-utilization：GPU显存利用率。默认0.9，意思是留10%给其他进程。我建议设0.95，除非你还要跑别的任务。

2.4.3 性能调优参数

  • --block-size：KV cache的块大小。默认16，显存充足时可以设32，减少碎片。
  • --swap-space：CPU交换空间大小。默认4GB，如果你的显存不够用，可以设大一点，但会影响速度。
🔑 核心经验： 我一般先设--gpu-memory-utilization 0.95和--max-model-len 4096，跑起来看看显存占用，再微调。别一上来就设8192，显存爆了服务直接挂。

2.5 知识体系图

下面这张图，帮你把本章的知识结构串起来：

vLLM安装与配置 环境要求 CUDA ≥ 11.8 Python 3.10 / 3.11 PyTorch ≥ 2.0 安装方式 pip install vllm 源码编译 (pip install -e .) 配置文件 模型参数 (model, dtype) 服务参数 (port, max_len) 性能参数 (block_size) 核心原则：环境匹配 → 选择安装方式 → 按需调参 避坑：CUDA版本、gcc版本、显存利用率

2.6 避坑指南

最后，分享几个我踩过的坑：

  • CUDA版本不匹配：我曾经在CUDA 11.7上装vLLM 0.4.0，编译到一半报错。后来换成11.8，一次过。
  • 显存爆了：有次我设了--max-model-len 8192，结果7B模型在A10上直接OOM。后来改成4096，配合--gpu-memory-utilization 0.9，稳了。
  • gcc版本太低：源码编译时，gcc 7会报internal compiler error。升级到gcc 9就好了。

嗯，安装和配置这块，其实没那么复杂。只要环境对了，剩下的就是调参的艺术。你先把环境搭好，后面咱们再聊怎么把模型跑起来。

专注资料整理
← 上一章 📖 返回目录 下一章 →