📚 课程目录第1章 vLLM环境搭建与基本推理

1. vLLM环境搭建与基本推理

任务目标

本案例完成 vLLM 推理框架的最小可用环境搭建，并基于公开的 facebook/opt-125m 模型执行一次完整的文本生成推理，验证 vLLM 的离线批量推理接口可用。最终通过打印生成的文本序列确认推理链路（模型加载 → 张量并行调度 → 采样解码）已打通。

环境依赖

操作系统：Ubuntu 20.04+ / CentOS 7+（需支持 CUDA）
GPU：NVIDIA 显卡，显存 ≥ 4GB（用于 125M 参数模型）
Python：3.9 ~ 3.12
CUDA：11.8 或 12.1（需与 PyTorch 版本匹配）

安装命令

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

# 安装 vLLM（CPU 版本仅用于导入检查，实际推理需 GPU）
pip install vllm==0.6.3.post1

# 验证安装
python -c "import vllm; print(vllm.__version__)"

完整实现代码

以下代码保存为 vllm_basic_inference.py，使用离线批量推理接口完成文本生成：

from vllm import LLM, SamplingParams

def main():
    # 1. 初始化推理引擎（自动下载模型权重）
    llm = LLM(
        model="facebook/opt-125m",  # 轻量模型，便于快速验证
        dtype="float16",            # 半精度推理，降低显存占用
        gpu_memory_utilization=0.6  # 控制 GPU 显存使用比例
    )

    # 2. 配置采样参数
    sampling_params = SamplingParams(
        temperature=0.8,    # 控制随机性
        top_p=0.95,         # 核采样
        max_tokens=64,      # 最大生成  数
        stop=["\n"]         # 遇到换行符停止生成
    )

    # 3. 输入提示词（批量推理示例）
    prompts = [
        "The capital of France is",
        "The future of AI lies in"
    ]

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

    # 5. 打印结果
    for i, output in enumerate(outputs):
        generated_text = output.outputs[0].text
        print(f"Prompt {i+1}: {prompt}")
        print(f"Generated: {generated_text}\n")

if __name__ == "__main__":
    main()

运行与验证

启动推理：python vllm_basic_inference.py
预期输出（首次运行需下载模型，约 500MB）：
Prompt 1: The capital of France is
Generated: Paris, the city of light and love.
Prompt 2: The future of AI lies in
Generated: the development of more advanced algorithms.
通过条件：程序无报错退出，且每个 Prompt 后均打印出非空的 Generated 文本。若显存不足（OOM），可降低 gpu_memory_utilization 至 0.4 或更换更小模型（如 sshleifer/tiny-）。

常见问题排查

CUDA 版本不匹配：运行 python -c "import torch; print(torch.version.cuda)" 检查 PyTorch 的 CUDA 版本，与 nvidia-smi 驱动支持的 CUDA 版本需兼容。
模型下载失败：设置环境变量 export HF_ENDPOINT=https://hf-mirror.com 使用国内镜像。
显存不足：将 dtype 改为 "float32" 会增大显存占用，建议保持 float16 并调低 gpu_memory_utilization。