2. 环境搭建

这是什么：环境搭建 = 把显卡驱动、CUDA、Python 环境和 vLLM 一次配齐，让第一个模型在显卡上跑起来。

为什么用：vLLM 不是纯 Python 库，它要直接指挥显卡和 CUDA 驱动，版本不对会一路红灯。上一章讲了原理，这一章把它真正跑起来。

如何用：本章按「查硬件 → 建虚拟环境 → 装 vLLM → 跑第一次推理」四步走，最后给出 Docker 这条省事路子。

2.1 第一步：确认显卡和驱动

nvidia-smi

你会看到（示意）：

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 550.54.14   Driver Version: 550.54.14   CUDA Version: 12.4      |
|-------------------------------+---------------------+----------------------+
|   0  NVIDIA A100-SXM4-80GB    |  81920MiB / 81920MiB |  54 C  |  100%  |
+-----------------------------------------------------------------------------+

顶部那行 CUDA Version 是驱动支持的最高 CUDA 版本，不是你要装的 Toolkit 版本。vLLM 的 pip wheel 自带编译好的 CUDA 内核，一般不用手动装 CUDA Toolkit。

官方环境要求：Linux（不原生支持 Windows）、Python 3.11~3.14、显卡算力 ≥ 7.5（T4、RTX 20 系、L4、A100、H100 等都算）。

2.2 第二步：Python 版本必须踩对

vLLM 0.32.0 要求 Python >= 3.11 且 < 3.15。3.15 目前不受支持，装不上或者装上跑不起来。

版本说明

安装包名：vllm，命令是 pip install vllm

Python：>=3.11,<3.15

0.32.0 的预编译 wheel 内含 CUDA 12.9 的二进制

校验方式：python -c "import sys; print(sys.version)" 看 Python 版本，pip show vllm 看安装版本

建一个干净的虚拟环境（官方推荐 uv，用 venv 也行）：

python3 -m venv .venv
source .venv/bin/activate
python --version

你会看到（示意）：

Python 3.12.9

小提醒：vLLM 编译了大量 CUDA 内核，跟别的 CUDA / PyTorch 版本可能二进制不兼容。强烈建议用全新的虚拟环境，别往已有项目环境里硬塞。

2.3 第三步：装 vLLM

pip install vllm

你会看到（示意）：

Collecting vllm
  Downloading vllm-0.32.0-cp38-abi3-manylinux_2_28_x86_64.whl (451.2 MB)
Successfully installed vllm-0.32.0

装完检查一下版本：

python -c "import vllm; print(vllm.__version__)"

你会看到（示意）：

0.32.0

本阶段用到的命令速查：

命令	作用
`nvidia-smi`	看显卡型号、驱动版本、显存占用
`python --version`	确认 Python 落在 3.11 ~ 3.14
`pip install vllm`	安装 vLLM（名字就是 `vllm`）
`pip show vllm`	看装的是哪个版本、在哪个环境
`python -c "import vllm; print(vllm.__version__)"`	验证能不能 import

2.4 第四步：跑起第一个模型

vLLM 有两种用法：离线 Python API（本节）和 HTTP 服务（第 3 章）。先用离线 API 确认环境和模型都没问题。

from vllm import LLM, SamplingParams

llm = LLM(model="Qwen/Qwen3-0.6B", gpu_memory_utilization=0.85)

params = SamplingParams(temperature=0.7, max_tokens=64)
outputs = llm.generate(["用一句话介绍你自己"], params)

for out in outputs:
    print(out.outputs[0].text)

你会看到（示意）：

INFO 06-01 10:20:31 [gpu_model_runner.py:2412] GPU KV cache size: 190,080 tokens
INFO 06-01 10:20:31 [gpu_model_runner.py:2413] Maximum concurrency for 40,960 tokens per request: 4.64x
我是通义千问团队研发的语言模型 Qwen3，很高兴为你效劳！

第一次跑会先从 Hugging Face 下载权重（Qwen/Qwen3-0.6B 约 1.2 GB）。国内网络下载慢，可以先设镜像：

export HF_ENDPOINT=https://hf-mirror.com

2.5 省事方案：Docker

不想折腾 Python 环境，就用官方镜像 vllm/vllm-openai：

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model Qwen/Qwen3-0.6B

你会看到（示意）：

INFO:     Started server process [1]
INFO:     Application startup complete.

两个参数要记住：--gpus all 把显卡交给容器，--ipc=host 给容器足够的共享内存（多卡时进程间要传张量）。挂载 ~/.cache/huggingface 是为了让模型只下载一次、反复复用。

动手改

把模型换成 Qwen/Qwen3-1.7B，观察启动日志里 GPU KV cache size 怎么变
把 gpu_memory_utilization 从 0.85 调到 0.5 再跑一次，看能装下多少 KV cache
用 pip show vllm 确认安装版本，再去 PyPI 上翻翻 0.32.0 的 release notes 写了什么

小结

vLLM 需要 Linux + NVIDIA 显卡 + CUDA 驱动，没显卡跑不起来
Python 必须 >=3.11,<3.15，3.15 不受支持
pip install vllm 装进全新的虚拟环境，别污染已有项目
离线 API 是 from vllm import LLM, SamplingParams
Docker 路线：vllm/vllm-openai 镜像 + --gpus all + --ipc=host

下一章：启动服务 🐸