介绍在 Ubuntu 系统上部署 vLLM 大模型推理框架的三种方案。方案一通过 pip 快速安装，适合有 GPU 环境；方案二使用 Docker 容器化部署，避免污染宿主机；方案三支持 CPU 源码编译，适用于无 GPU 场景。文章涵盖环境准备、安装步骤、进阶用法及故障排查，帮助开发者根据硬件条件选择合适的部署方式。
vLLM 是目前社区里最快、最省显存的大模型推理框架之一。本文提供三种安装路径——零配置的 pip 一行命令、开箱即用的 Docker 镜像、极端场景的 CPU/源码构建。
| 组件 | 最低要求 | 检查命令 |
|---|---|---|
| 操作系统 | 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。
适合：有 GPU、想 5 分钟跑起来。
sudo apt update && sudo apt install -y nvidia-driver-550 cuda-toolkit-12-4 && sudo reboot
官方推荐用 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。）
pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple # 国内镜像
vllm --help # 出现子命令列表即成功
适合：不想污染宿主机 Python、CI/CD、K8s 场景。
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
以 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 接口。
适合：只有 CPU、需要改源码、研究量化算子。
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
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
VLLM_TARGET_DEVICE=cpu vllm --help
vllm serve /data/models/DeepSeek-R1-Distill-Qwen-7B \
--host 0.0.0.0 --port 8000 \
--tensor-parallel-size 2 \
--max-model-len 8192
export VLLM_USE_MODELSCOPE=True # 用 ModelScope 自动下载
| 参数 | 说明 |
|---|---|
--tensor-parallel-size | 张量并行 GPU 数 |
--max-model-len | 最大序列长度（显存杀手） |
--quantization awq | 4-bit AWQ 量化 |
--gpu-memory-utilization 0.9 | 显存占用比例，默认 0.9 |
| 现象 | 原因 | 解决 |
|---|---|---|
ImportError: libcudart.so.12 找不到 | CUDA 版本不匹配 | 检查 nvidia-smi 与 pip 安装的 CUDA wheel 是否一致 |
容器启动报 failed to initialize NVML | nvidia-docker 没装好 | 重新跑 3.1 节 |
| CPU 方案内存爆炸 | 未设置 --max-model-len | 显式指定一个较小值，如 2048 |
| 方案 | 耗时 | 适用场景 |
|---|---|---|
| pip 一行命令 | 5 min | 有 GPU，快速体验 |
| Docker | 3 min | 生产、CI、K8s |
| CPU 源码 | 20 min | 无 GPU、二次开发 |
根据硬件条件选择合适的部署方式，即可让大模型快速运行。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online