vLLM 安装与部署

二、安装与部署

先说最重要的前提：vLLM 官方主要支持 Linux 与 NVIDIA GPU。Windows 原生环境不是官方支持路径，Windows 用户要么走 WSL2，要么用容器。另外它对 GPU 计算能力有门槛，太老的卡会因为缺少算子而报 no kernel image is available。

1. 检查硬件与驱动。nvidia-smi 确认卡型号、显存、驱动版本。显存决定能跑多大的模型，驱动决定能装哪个 CUDA 版本组合。
2. 建独立 Python 环境。用 venv 或 conda 隔离，Python 版本跟着官方要求走。
3. 装 vLLM。官方推荐用 uv pip 安装以获得更快的解析速度；pip install vllm 也可以。安装会自动带上匹配的 PyTorch 与 CUDA 运行时。
4. （可选）装量化后端。要跑 AWQ / GPTQ 权重时需要额外的 kernel 支持，通常已经包含在默认安装里，但特定组合要按官方文档单独装。
5. 准备权重。可以从模型仓库在线拉取，也可以提前下载到本地目录后用本地路径启动。内网部署必须提前同步。
6. 启动服务。用 vllm serve 起 OpenAI 兼容服务；也可以只用 Python 里的 LLM 类做离线批量推理。
7. 验证。用 curl 打一次 /v1/models 与 /v1/chat/completions，确认模型名与返回结构。

# 1) 硬件确认
nvidia-smi

# 2) 环境
python -m venv .venv && source .venv/bin/activate
pip install -U pip

# 3) 安装（uv 更快，pip 也可）
pip install uv
uv pip install vllm
python -c "import vllm; print(vllm.__version__)"

# 4) 启动 OpenAI 兼容服务
vllm serve <模型名或本地路径> \
  --served-model-name qwen-local \
  --host 0.0.0.0 --port 8000 \
  --tensor-parallel-size 2 \
  --gpu-memory-utilization 0.90 \
  --max-model-len 8192 \
  --enable-prefix-caching

# 5) 验证
curl -s http://127.0.0.1:8000/v1/models | head

curl -s http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen-local",
    "messages": [{"role":"user","content":"用一句话解释什么是 KV cache"}],
    "temperature": 0.7,
    "max_tokens": 128
  }'

依赖与环境要求

• 操作系统：Linux（Ubuntu 系最常见）。Windows 走 WSL2 或容器。
• GPU：NVIDIA 数据中心或消费级卡，计算能力要满足引擎要求；太老的架构不支持。
• 驱动：驱动需支持所装 CUDA 运行时；驱动过旧会在加载 kernel 时失败。
• 共享内存：容器部署时 /dev/shm 太小会导致张量并行初始化失败，需调大。
• 磁盘：权重文件体积大，加上编译缓存，建议预留充足空间并单独挂盘。
• 网络：多机部署要保证节点间高速互联，NCCL 走错网卡会明显拖慢甚至卡死。

常见报错与排查