4、vLLM安装与部署：从pip安装到Docker部署的完整流程

说实话，vLLM的安装部署是我在实际项目中踩坑最多的环节之一。不是因为它难，而是因为环境差异太大——你想想看，同样的代码，在A100上跑得飞起，换到4090上就各种报错。今天我就把从pip安装到Docker部署的完整流程掰开揉碎了讲清楚。

4.1 环境准备：先把地基打牢

我个人习惯在开始之前先确认三件事：Python版本、CUDA版本、PyTorch版本。这三者但凡有一个不匹配，后面就是无穷无尽的报错。

嗯，这里要注意：千万别用Python 3.12。我在项目里试过一次，vLLM的某些C扩展直接编译失败，折腾了两天才发现是Python版本的问题。

4.2 pip安装：最直接的方式

对于大多数场景，pip安装就够了。但这里有个坑——直接 pip install vllm 可能会装到CPU版本。为什么？因为PyPI上的包名不带CUDA标识，它默认装的是你当前环境匹配的版本。

# 推荐做法：先确认CUDA版本
nvcc --version  # 查看CUDA版本

# 然后安装对应版本
pip install vllm==0.4.0

# 如果你需要特定CUDA版本
pip install vllm-cuda118  # CUDA 11.8
pip install vllm-cuda121  # CUDA 12.1

我曾经在客户的服务器上遇到过一个问题：明明装了CUDA 12.1，但vLLM一直报错说找不到GPU。后来发现是系统里同时装了多个CUDA版本，环境变量指向了11.8。解决办法很简单：

export CUDA_HOME=/usr/local/cuda-12.1
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH

4.3 从源码编译：当pip满足不了你时

有些场景下pip安装不够用。比如你想用最新的特性，或者需要针对特定硬件做优化。这时候就得从源码编译了。

说实话，编译vLLM是我最头疼的部分。它依赖FlashAttention、Triton这些底层库，编译一次少说20分钟。我第一次编译时没看文档，直接 git clone 就开始，结果卡在FlashAttention的编译上整整一下午。

# 正确的编译姿势
git clone https://github.com/vllm-project/vllm.git
cd vllm

# 创建干净的虚拟环境
python -m venv vllm_env
source vllm_env/bin/activate

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

# 开始编译（这里会很久，建议泡杯咖啡）
pip install -e .

# 验证安装
python -c "from vllm import LLM; print('编译成功')"

4.4 Docker部署：生产环境的首选

我个人强烈建议在生产环境中用Docker。为什么？因为环境一致性。你想想看，开发环境是Ubuntu 22.04 + CUDA 12.1，生产环境是CentOS 7 + CUDA 11.8，光依赖冲突就能让你崩溃。

vLLM官方提供了Docker镜像，但说实话，我更喜欢自己写Dockerfile。因为官方镜像里装了很多我用不到的包，而且版本更新太慢。

# 我的生产级Dockerfile
FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04

# 安装Python和基础工具
RUN apt-get update && apt-get install -y \
    python3.10 \
    python3-pip \
    git \
    && rm -rf /var/lib/apt/lists/*

# 设置工作目录
WORKDIR /app

# 安装vLLM
RUN pip install vllm==0.4.0

# 复制模型文件（建议挂载卷，不要打包进镜像）
COPY ./models /app/models

# 暴露API端口
EXPOSE 8000

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

构建和运行：

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

# 运行容器（注意挂载GPU和模型目录）
docker run --gpus all \
    -v /path/to/models:/app/models \
    -p 8000:8000 \
    vllm-server:latest

4.5 部署后的验证与调优

部署完了不代表就万事大吉了。我每次部署完都会做三件事：

1. 验证推理正确性：用几个标准测试用例跑一遍，确认输出和预期一致
2. 压力测试：用 locust 或 wrk 模拟并发请求，看看吞吐量
3. 监控资源：用 nvidia-smi 看GPU利用率，用 htop 看CPU和内存

这里分享一个我常用的测试脚本：

# test_vllm.py
from vllm import LLM, SamplingParams

# 加载模型
llm = LLM(model="meta-llama/Llama-2-7b-chat-hf")

# 设置采样参数
sampling_params = SamplingParams(
    temperature=0.7,
    top_p=0.9,
    max_tokens=512
)

# 测试推理
prompts = ["什么是vLLM？", "请解释一下Transformer"]
outputs = llm.generate(prompts, sampling_params)

for output in outputs:
    print(f"Prompt: {output.prompt}")
    print(f"Generated: {output.outputs[0].text}")
    print("-" * 50)

4.6 常见问题与解决方案

问题	原因	解决方案
ImportError: libcuda.so.1 not found	CUDA驱动未安装或路径不对	安装NVIDIA驱动，或设置LD_LIBRARY_PATH
RuntimeError: CUDA out of memory	显存不足	减小模型尺寸，或降低gpu_memory_utilization
ValueError: The model's max seq len is too large	模型配置的max_position_embeddings过大	在加载时指定max_model_len参数
Docker容器内无法识别GPU	未安装nvidia-container-toolkit	安装并配置nvidia-container-runtime

嗯，最后说一句：安装部署这件事，说白了就是环境匹配的问题。只要Python、CUDA、PyTorch这三个版本对上了，vLLM基本不会出大问题。如果真遇到奇怪的报错，先去GitHub的Issues里搜一下——我敢说，90%的问题别人都遇到过。