在 Ubuntu 上安装 vLLM：从 GPU 到 CPU 的三种方案
关键词：vLLM、Ubuntu、CUDA、Docker、LLM 推理
vLLM 是目前社区里最快、最省显存的大模型推理框架之一。本文把官方文档、踩坑经验整理成一篇可落地的技术博客，给出 三种安装路径——
- 零配置的 pip 一行命令
- 开箱即用的 Docker 镜像
- 极端场景的 CPU/源码构建
无论你手里是 A100、4090 还是纯 CPU 服务器，总有一款适合你。
1. 准备工作（所有方案通用）
| 组件 | 最低要求 | 检查命令 |
|---|---|---|
| 操作系统 | Ubuntu 20.04/22.04/24.04 x86_64 | lsb_release -a |
| NVIDIA 驱动 | ≥ 515 | nvidia-smi |
| CUDA | ≥ 12.1（方案 1/2） | nvcc --version |
| Python | 3.9–3.12 | python3 --version |
⚠️ CPU 方案无需 CUDA。
2. 方案一：pip 一行命令（最简）
适合：有 GPU、想 5 分钟跑起来。
2.1 安装驱动 & CUDA（如已装可跳过）
sudoapt update sudoaptinstall -y nvidia-driver-550 cuda-toolkit-12-4 sudoreboot# 重启生效2.2 建立隔离环境
官方推荐用 uv（比 conda 更快）：
curl -Ls https://astral.sh/uv/install.sh |bash uv venv vllm-env --python 3.12 --seed source vllm-env/bin/activate （老用户可以继续 conda create -n vllm python=3.12。）
2.3 安装 vLLM
pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple # 国内镜像2.4 验证
vllm --help # 出现子命令列表即成功3. 方案二：Docker 一行命令（零 Python 依赖）
适合：不想污染宿主机 Python、CI/CD、K8s 场景。
3.1 安装 nvidia-docker
sudoaptinstall -y docker.io distribution=$(. /etc/os-release;echo $ID$VERSION_ID)curl -fsSL https://nvidia.github.io/nvidia-docker/gpgkey |sudo gpg --dearmor -o /usr/share/keyrings/nvidia-docker-keyring.gpg curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list |\sed's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-docker-keyring.gpg] https://#'|\sudotee /etc/apt/sources.list.d/nvidia-docker.list sudoapt update &&sudoaptinstall -y nvidia-docker2 sudo systemctl restart docker 3.2 启动 vLLM 容器
以 Qwen/Qwen2.5-1.5B-Instruct 为例，映射 8000 端口并挂载 HuggingFace 缓存：
sudo docker run -d --name vllm \ --runtime nvidia --gpus all \ -p 8000:8000 --ipc=host \ -v ~/.cache/huggingface:/root/.cache/huggingface \ vllm/vllm-openai:latest \ --model Qwen/Qwen2.5-1.5B-Instruct 打开浏览器访问 http://localhost:8000/docs 即可看到与 OpenAI 100% 兼容的 REST 接口。
4. 方案三：CPU / 源码编译（无 GPU 也能跑）
适合：只有 CPU、需要改源码、研究量化算子。
4.1 系统依赖
sudoapt update sudoaptinstall -y gcc-12 g++-12 libnuma-dev python3-dev cmake ninja-build sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 10\ --slave /usr/bin/g++ g++ /usr/bin/g++-12 4.2 克隆 & 编译
git clone https://github.com/vllm-project/vllm.git cd vllm pip install --upgrade pip wheel packaging ninja numpy pip install -v -r requirements/cpu.txt \ --extra-index-url https://download.pytorch.org/whl/cpu VLLM_TARGET_DEVICE=cpu python setup.py install4.3 验证
VLLM_TARGET_DEVICE=cpu vllm --help 5. 进阶用法示例
5.1 本地模型离线推理
vllm serve /data/models/DeepSeek-R1-Distill-Qwen-7B \ --host 0.0.0.0 --port 8000\ --tensor-parallel-size 2\ --max-model-len 81925.2 国内镜像/ModelScope
exportVLLM_USE_MODELSCOPE=True # 用 ModelScope 自动下载5.3 常用参数速查
| 参数 | 说明 |
|---|---|
--tensor-parallel-size | 张量并行 GPU 数 |
--max-model-len | 最大序列长度（显存杀手） |
--quantization awq | 4-bit AWQ 量化 |
--gpu-memory-utilization 0.9 | 显存占用比例，默认 0.9 |
6. 故障排查 Top3
| 现象 | 原因 | 解决 |
|---|---|---|
ImportError: libcudart.so.12 找不到 | CUDA 版本不匹配 | 检查 nvidia-smi 与 pip 安装的 CUDA wheel 是否一致 |
容器启动报 failed to initialize NVML | nvidia-docker 没装好 | 重新跑 3.1 节 |
| CPU 方案内存爆炸 | 未设置 --max-model-len | 显式指定一个较小值，如 2048 |
7. 小结
| 方案 | 耗时 | 适用场景 |
|---|---|---|
| pip 一行命令 | 5 min | 有 GPU，快速体验 |
| Docker | 3 min | 生产、CI、K8s |
| CPU 源码 | 20 min | 无 GPU、二次开发 |
把这篇博客收藏起来，下次无论是新机器还是旧服务器，都能 5 分钟让大模型跑起来！
作者：@yourname
转载请注明出处，欢迎留言交流。
