4、vLLM源码编译与安装：从源码编译、pip安装、Docker镜像构建

聊到vLLM的安装，很多新手第一反应就是pip install vllm。嗯，这确实是最快的方式。但说实话，在生产环境里，我很少直接用这个命令。为什么？因为生产环境对版本控制、依赖隔离、硬件适配的要求，远比开发环境要苛刻得多。

我个人习惯把安装方式分成三种：pip安装、源码编译、Docker镜像构建。每种方式都有它的适用场景。今天我就把这三种方式掰开揉碎了讲清楚。

核心观点：没有最好的安装方式，只有最适合你场景的安装方式。pip适合快速验证，源码编译适合定制优化，Docker适合生产部署。

vLLM 安装方式 pip 安装 快速验证 / 开发环境 源码编译 定制优化 / 性能调优 Docker 镜像 生产部署 / 标准化交付 pip install vllm 指定版本安装 git clone pip install -e . docker build docker pull 选择建议：开发环境 → pip | 性能调优 → 源码 | 生产部署 → Docker

4.1 pip安装：最快上手的方式

先说说最简单的。如果你只是想快速体验vLLM，或者在做一些原型验证，pip install vllm绝对够用。但这里有个坑——版本兼容性。

我记得有一次，团队里一个小伙伴直接pip install vllm，结果装了个0.2.0版本，跟我们的CUDA 11.8环境不兼容，跑起来各种报错。后来我让他指定版本安装，问题就解决了。

我的建议：永远指定版本号安装。比如：

pip install vllm==0.4.0

这样能确保你的环境是可复现的。生产环境最怕的就是「在我机器上能跑」这种问题。

pip安装的完整流程其实很简单：

  1. 检查环境：确认Python版本（3.8+）、CUDA版本（11.8或12.1）、PyTorch版本。
  2. 创建虚拟环境：我个人习惯用conda，隔离性更好。
  3. 安装依赖：先装PyTorch，再装vLLM。
  4. 验证安装：跑一个简单的推理测试。

你可能会问：为什么非要先装PyTorch？因为vLLM对PyTorch的版本有严格要求。我曾经遇到过因为PyTorch版本不对，导致vLLM的CUDA kernel编译失败的情况。说白了，这就是依赖管理的「蝴蝶效应」。

4.2 源码编译：定制化的必经之路

如果你需要做性能调优，或者想集成一些自定义的算子，那就得走源码编译这条路了。说实话，源码编译确实比pip安装要麻烦一些，但带来的灵活性也是pip无法比拟的。

源码编译的核心步骤：

# 1. 克隆代码
git clone https://github.com/vllm-project/vllm.git
cd vllm

# 2. 安装编译依赖
pip install -r requirements-build.txt

# 3. 编译安装（开发模式）
pip install -e .

# 4. 验证
python -c "import vllm; print(vllm.__version__)"

注意：源码编译对硬件有要求。我建议至少准备16GB内存和50GB磁盘空间。编译过程中会下载大量依赖，包括PyTorch、CUDA工具包等。如果你在服务器上编译，记得先检查网络和磁盘。

这里有个小技巧：编译时可以指定CUDA架构，只编译你需要的架构，能大大缩短编译时间。

export TORCH_CUDA_ARCH_LIST="8.0;8.6;8.9"  # 只编译A100、RTX 3090、RTX 4090
pip install -e .

我曾经在编译时没指定架构，结果它把所有架构都编译了一遍，等了快两个小时。后来我学乖了，每次都先查一下GPU的架构版本，再指定编译。

4.3 Docker镜像构建：生产环境的标配

说到生产部署，Docker绝对是首选。为什么？因为Docker能保证环境的一致性。你在开发机上跑得好好的，到了生产环境却出问题，这种经历我相信很多人都遇到过。

vLLM官方提供了Dockerfile，但说实话，我很少直接用官方的。为什么？因为生产环境往往有自己的一套基础镜像、安全策略、网络配置。直接拿官方的镜像，很多时候需要二次改造。

我个人习惯的做法是：

  1. 基于官方镜像做定制：从vllm/vllm-openai拉取基础镜像，然后添加自己的配置。
  2. 或者自己从头构建：基于nvidia/cuda:12.1.0-runtime-ubuntu22.04，一步步搭建。

下面是一个我常用的Dockerfile示例：

FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    python3.10 python3-pip git build-essential \
    && rm -rf /var/lib/apt/lists/*

# 设置工作目录
WORKDIR /app

# 安装vLLM
RUN pip install vllm==0.4.0

# 暴露端口
EXPOSE 8000

# 启动命令
CMD ["python3", "-m", "vllm.entrypoints.openai.api_server", \
     "--model", "/models/llama-2-7b", \
     "--port", "8000"]

避坑指南：我曾经在构建Docker镜像时，忘记设置--shm-size参数，结果容器启动后vLLM报共享内存不足的错误。后来我在docker run命令里加上了--shm-size=8g，问题就解决了。

构建和运行命令：

# 构建镜像
docker build -t vllm-server:0.4.0 .

# 运行容器
docker run --gpus all \
    --shm-size=8g \
    -p 8000:8000 \
    -v /path/to/models:/models \
    vllm-server:0.4.0

4.4 三种方式的对比与选择

说了这么多，到底该选哪种方式？我整理了一个对比表格，方便你决策：

维度 pip安装 源码编译 Docker镜像
安装速度 快（几分钟） 慢（30分钟+） 中等（取决于网络）
定制化程度 低 高 中
环境一致性 低 中 高
适用场景 开发、测试 性能调优、定制开发 生产部署、CI/CD
维护成本 低 高 中

你想想看，如果你的团队有10台GPU服务器，每台都要手动装一遍vLLM，那得多累？用Docker的话，一次构建，到处运行。这才是SRE该有的思维。

我的最终建议：

  • 个人开发机 → pip安装，省事
  • 需要改源码或做性能优化 → 源码编译
  • 生产环境 → Docker镜像，没有第二种选择

嗯，关于安装这部分，我就讲这么多。记住一点：安装只是开始，真正的挑战在于后续的配置、调优和运维。但如果你连安装都搞不定，后面的东西就更别谈了。

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