2、环境搭建与基础使用：安装vLLM、配置GPU环境、运行第一个推理示例

vLLM 作为高性能 LLM 推理引擎，其核心优势在于 PagedAttention 显存管理机制与 Continuous Batching 动态调度策略。要真正发挥这些能力，必须先搭建一个正确、可复现的运行环境。本章将围绕 GPU 驱动与容器环境校验、vLLM 安装方式选择、以及首个推理示例的完整运行展开，帮助你在 30 分钟内建立起可投入生产实验的基础设施。

2.1 核心原理：为什么环境搭建决定批处理性能上限

vLLM 的批处理能力并非单纯依赖算法，而是建立在底层硬件资源被正确暴露和调度的基础之上。PagedAttention 需要 CUDA 驱动能够访问 GPU 的虚拟内存管理单元（MMU），Continuous Batching 需要 GPU 计算流（Stream）能够高效并发执行多个解码步骤。如果驱动版本过旧、CUDA 运行时与 PyTorch 不匹配，或者容器未正确挂载 GPU 设备，vLLM 会退化为串行推理模式，吞吐量可能下降 5-10 倍。

从工程角度看，环境搭建的核心目标有三个：让 GPU 设备对 vLLM 可见、让 CUDA 运行时与 PyTorch 版本对齐、让显存管理策略可配置。其中第三点尤为重要——vLLM 默认使用 GPU 可用显存的 90% 作为 KV Cache 池，如果环境未正确配置，这个比例可能被系统默认值覆盖，导致批处理规模受限。

2.2 操作流程：从裸机到可运行 vLLM 的完整步骤

2.2.1 第一步：校验 GPU 驱动与 CUDA 环境

在安装任何 Python 包之前，必须先确认 GPU 驱动支持 CUDA 12.x。执行以下命令：

# 检查驱动版本（需 ≥ 525.60.13）
nvidia-smi

# 检查 CUDA 编译器版本
nvcc --version

# 检查 GPU 计算能力（vLLM 要求 ≥ 7.0）
python -c "import torch; print(torch.cuda.get_device_capability())"

如果 nvidia-smi 显示驱动版本低于 525，需要先升级驱动。注意：驱动版本与 CUDA Toolkit 版本是独立的，驱动向下兼容。例如，驱动 535 可以支持 CUDA 12.2 及以下所有版本。

2.2.2 第二步：选择安装方式

vLLM 提供三种安装路径，适用场景不同：

对于大多数课程实验场景，推荐使用 pip 安装：

# 创建虚拟环境（推荐 Python 3.10）
python -m venv vllm_env
source vllm_env/bin/activate

# 安装 vLLM（自动拉取匹配的 PyTorch 和 CUDA 依赖）
pip install vllm

# 验证安装
python -c "from vllm import LLM; print('vLLM 安装成功')"

2.2.3 第三步：Docker 环境配置（生产推荐）

如果使用 Docker，需要额外配置 NVIDIA Container Toolkit：

# 安装 nvidia-container-toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

# 运行 vLLM 容器
docker run --gpus all -it --shm-size=8g \
  -v $(pwd):/workspace \
  vllm/vllm-openai:latest \
  python -c "from vllm import LLM; print('容器内 vLLM 可用')"

注意 --shm-size 参数：vLLM 的 tokenizer 和调度器会使用共享内存，默认 64MB 往往不够，建议设置为 8GB 以上。

2.3 案例拆解：从安装到跑通第一个批处理推理

下面通过一个完整案例，演示从零开始运行 vLLM 离线批处理推理。假设我们有一台配置了 NVIDIA A100 80GB 的服务器，目标是批量处理 100 条文本生成请求。

2.3.1 初始环境检查

$ nvidia-smi
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 535.104.05   Driver Version: 535.104.05   CUDA Version: 12.2     |
+-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|===============================+======================+======================|
|   0  A100-SXM4-80GB      On   | 00000000:00:04.0 Off |                    0 |
| N/A   32C    P0    45W / 400W |      0MiB / 81920MiB |      0%      Default |
+-------------------------------+----------------------+----------------------+

驱动 535.104.05 满足要求，CUDA 12.2 可用，GPU 显存 80GB 完全空闲。

2.3.2 安装与验证

# 创建并激活虚拟环境
python3.10 -m venv /opt/vllm_env
source /opt/vllm_env/bin/activate

# 安装 vLLM 0.6.0（课程固定版本）
pip install vllm==0.6.0

# 验证 GPU 可见性
python -c "
import torch
print(f'CUDA 可用: {torch.cuda.is_available()}')
print(f'GPU 数量: {torch.cuda.device_count()}')
print(f'GPU 名称: {torch.cuda.get_device_name(0)}')
"

输出应显示 CUDA 可用、GPU 数量为 1、名称为 NVIDIA A100-SXM4-80GB。

2.3.3 运行第一个批处理推理

# offline_batch_demo.py
from vllm import LLM, SamplingParams

# 初始化 LLM，指定模型和显存利用率
llm = LLM(
    model="facebook/opt-125m",  # 轻量模型，便于快速验证
    gpu_memory_utilization=0.85,  # 使用 85% 显存作为 KV Cache
    max_num_seqs=64,  # 最大并发序列数
)

# 构造 100 条请求
prompts = [f"Hello, my name is {i}. Please introduce yourself." for i in range(100)]

# 设置采样参数
sampling_params = SamplingParams(
    temperature=0.8,
    top_p=0.95,
    max_tokens=128,
)

# 执行批处理推理
outputs = llm.generate(prompts, sampling_params)

# 输出前 3 条结果
for output in outputs[:3]:
    prompt = output.prompt
    generated_text = output.outputs[0].text
    print(f"Prompt: {prompt!r}")
    print(f"Generated: {generated_text!r}")
    print("-" * 50)

执行结果：

$ python offline_batch_demo.py
Prompt: 'Hello, my name is 0. Please introduce yourself.'
Generated: ' Hi there! My name is 0, and I am a language model trained to assist...'
--------------------------------------------------
Prompt: 'Hello, my name is 1. Please introduce yourself.'
Generated: ' Hello! I am 1, a helpful AI assistant...'
--------------------------------------------------
Prompt: 'Hello, my name is 2. Please introduce yourself.'
Generated: ' Greetings! I am 2, an AI model designed to...'

2.3.4 性能指标观察

在运行过程中，vLLM 会输出关键性能日志：

INFO 06-10 10:23:45 scheduler.py:741] # GPU blocks: 45678, # CPU blocks: 1024
INFO 06-10 10:23:45 scheduler.py:746] Maximum concurrency for 128 tokens per request: 356
INFO 06-10 10:23:46 model_runner.py:612] Capturing the model for CUDA graphs...
INFO 06-10 10:23:48 model_runner.py:617] CUDA graph capture complete: 2.1s
INFO 06-10 10:23:48 engine.py:137] Avg prompt throughput: 1850.3 tokens/s
INFO 06-10 10:23:48 engine.py:138] Avg generation throughput: 4200.5 tokens/s

从日志可以看到：GPU blocks 45678 表示 KV Cache 被划分为 45678 个 block（每个 block 16 个 token），最大并发 356 表示在 128 token 输出长度下可同时处理 356 个请求。这验证了环境配置正确，批处理能力已完全释放。

2.4 常见误区与总结复盘

2.4.1 误区一：忽略 PyTorch 与 CUDA 版本匹配

vLLM 依赖 PyTorch 的 CUDA 扩展。如果 PyTorch 是 CPU 版本，或者 CUDA 版本不匹配，vLLM 会报错 CUDA error: no kernel image available。解决方法是使用 vLLM 官方要求的 PyTorch 版本：

# 查看 vLLM 依赖的 PyTorch 版本
pip show vllm | grep Requires
# 输出示例：Requires: torch==2.3.0, transformers>=4.40.0, ...

2.4.2 误区二：Docker 中未正确挂载 GPU

很多用户在 Docker 中运行 vLLM 时遇到 CUDA_VISIBLE_DEVICES 为空的问题。这通常是因为没有安装 nvidia-container-toolkit，或者 Docker 版本过旧。验证方法：

# 在容器内执行
docker run --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

如果容器内无法看到 GPU，需要重新安装 nvidia-container-toolkit 并重启 Docker。

2.4.3 误区三：盲目追求最新版本

vLLM 迭代速度极快，但新版本可能引入不兼容的 API 变更。对于生产环境，建议锁定版本并做好测试。课程实验统一使用 vLLM 0.6.0，该版本稳定且支持后续章节的批处理调优实验。

2.4.4 总结：环境验证清单