重庆电子商务网站建设合江县住房和城乡规划建设局网站
关键词：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 |
7. 小结
| 方案 | 耗时 | 适用场景 |
|---|---|---|
| pip 一行命令 | 5 min | 有 GPU，快速体验 |
| Docker | 3 min | 生产、CI、K8s |
| CPU 源码 | 20 min | 无 GPU、二次开发 |
把这篇博客收藏起来，下次无论是新机器还是旧服务器，都能 5 分钟让大模型跑起来！
作者：@yourname
转载请注明出处，欢迎留言交流。