当前位置：首页 > news >正文

在 Ubuntu 上安装 vLLM：从 GPU 到 CPU 的三种方案

news 2025/7/15 9:43:33

关键词：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（如已装可跳过）

sudo apt update
sudo apt install -y nvidia-driver-550 cuda-toolkit-12-4
sudo reboot   # 重启生效

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

sudo apt install -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://#' | \sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt update && sudo apt install -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 系统依赖

sudo apt update
sudo apt install -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 install

4.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 8192

5.2 国内镜像/ModelScope

export VLLM_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