小狐狸与小道士1. vLLM离线推理基础入门
最近在部署大模型推理服务时，发现vLLM这个框架在性能和易用性上确实有不少亮点。作为一个专门为LLM推理优化的库，它在吞吐量和延迟方面相比原生transformers有显著提升。今天主要记录下最基础的离线推理使用方法，适合刚接触vLLM的同学快速上手。
vLLM的核心优势在于其创新的PagedAttention注意力机制，能够高效管理GPU内存中的KV Cache。在实际测试中，同样的A100显卡，用vLLM推理Qwen-7B模型时，吞吐量能达到transformers的3-4倍。这对于需要批量处理大量提示词(prompt)的场景特别有用。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与安装
2.1 系统要求
vLLM对运行环境有明确要求：
- 操作系统：Linux（推荐Ubuntu 20.04+）
- Python版本：3.9-3.12
- CUDA版本：11.8或12.x
- GPU：NVIDIA显卡（至少16GB显存）
注意：Windows系统可以通过WSL2运行，但官方不推荐生产环境使用
2.2 安装步骤
推荐使用uv管理Python环境（比venv更快）：
bash复制uv venv vllm-env --python 3.12
source vllm-env/bin/activate
uv pip install vllm
如果遇到libcudart.so缺失错误，需要检查CUDA安装：
bash复制# 确认CUDA版本
nvcc --version
# 若缺失库文件，建立软链接
sudo ln -s /usr/local/cuda-12.1/lib64/libcudart.so.12 /usr/lib/libcudart.so.12
对于国内用户，可以使用清华源加速安装：
bash复制pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple
3. 基础离线推理实现
3.1 核心类介绍
vLLM的离线推理主要涉及两个核心类：
LLM：推理引擎主类，负责加载模型和执行生成SamplingParams：控制生成过程的参数
基础使用示例：
python复制from vllm import LLM, SamplingParams
# 定义生成参数
sampling_params = SamplingParams(
temperature=0.8, # 控制随机性 (0-1)
top_p=0.95, # 核采样概率
max_tokens=256, # 最大生成token数
stop=["\n", "。"] # 停止生成符号
)
# 初始化模型 (首次运行会自动下载)
llm = LLM(model="Qwen/Qwen1.5-7B-Chat")
# 提示词列表
prompts = [
"请用中文解释量子计算的基本原理",
"写一首关于春天的七言绝句",
"用Python实现快速排序算法"
]
# 批量生成
outputs = llm.generate(prompts, sampling_params)
# 输出结果
for output in outputs:
print(f"输入：{output.prompt}")
print(f"输出：{output.outputs[0].text}\n")
3.2 关键参数解析
SamplingParams中几个重要参数：
temperature：值越大输出越随机（创意文本建议0.7-1.0，事实问答建议0.1-0.3）top_k：限制采样池大小（通常50-100）repetition_penalty：控制重复惩罚（1.0无惩罚，>1.0减少重复）length_penalty：控制生成长度（<1.0鼓励短输出，>1.0鼓励长输出）
实测发现，对于中文模型，设置repetition_penalty=1.1能有效减少重复内容。
4. 模型加载与配置技巧
4.1 模型指定方式
vLLM支持多种模型来源：
python复制# HuggingFace仓库
llm = LLM(model="Qwen/Qwen1.5-7B-Chat")
# 本地模型路径
llm = LLM(model="/path/to/model")
# 使用ModelScope镜像（国内加速）
import os
os.environ["VLLM_USE_MODELSCOPE"] = "True"
llm = LLM(model="qwen/Qwen1.5-7B-Chat")
4.2 高级加载参数
python复制llm = LLM(
model="Qwen/Qwen1.5-7B-Chat",
download_dir="/mnt/models", # 指定下载目录
tensor_parallel_size=2, # 多卡并行数
gpu_memory_utilization=0.9, # GPU内存利用率
enforce_eager=True, # 禁用图优化（调试用）
trust_remote_code=True # 信任自定义代码
)
注意：
tensor_parallel_size需要等于GPU数量，例如使用2张A100时设置为2
5. 性能优化实践
5.1 批处理技巧
vLLM的吞吐量优势主要来自高效的批处理：
python复制# 不推荐：逐个生成
for prompt in prompts:
output = llm.generate(prompt)
# 推荐：批量生成
outputs = llm.generate(prompts) # 吞吐量提升3-10倍
实测数据（A100 80GB）：
| 批大小 | QPS | 显存占用 |
|---|---|---|
| 1 | 12 | 15GB |
| 8 | 68 | 18GB |
| 32 | 142 | 35GB |
5.2 内存管理
当遇到OOM错误时，可以调整：
python复制llm = LLM(
model="Qwen/Qwen1.5-14B-Chat",
gpu_memory_utilization=0.85, # 降低利用率
swap_space=16, # 增加CPU交换空间(GB)
max_model_len=2048 # 限制上下文长度
)
6. 常见问题排查
6.1 典型错误解决方案
- CUDA版本不匹配
bash复制ImportError: libcudart.so.12: cannot open shared object file
解决方法：
bash复制conda install cuda -c nvidia/label/cuda-12.1.0
- 模型下载失败
设置环境变量：
bash复制export HF_ENDPOINT=https://hf-mirror.com
- 显存不足
尝试量化加载：
python复制llm = LLM(model="Qwen/Qwen1.5-7B-Chat",
quantization="awq")
6.2 调试技巧
启用详细日志：
python复制import logging
logging.basicConfig(level=logging.DEBUG)
llm = LLM(model="Qwen/Qwen1.5-7B-Chat")
检查GPU状态：
python复制from vllm.engine.llm_engine import LLMEngine
engine = LLMEngine.from_engine_args(llm.llm_engine.engine_args)
print(engine.get_gpu_stats())
7. 进阶功能扩展
7.1 自定义采样策略
实现温度调度：
python复制from vllm import SamplingParams
def dynamic_sampling(step: int):
# 随生成步数降低温度
temp = max(0.3, 1.0 - step * 0.02)
return SamplingParams(temperature=temp)
outputs = llm.generate(prompts, sampling_params=dynamic_sampling)
7.2 流式输出
虽然离线推理不直接支持流式，但可以模拟：
python复制for prompt in prompts:
for i in range(5): # 分段生成
chunk_params = SamplingParams(
max_tokens=50,
stop=["\n"]
)
chunk = llm.generate(prompt, chunk_params)
print(chunk.outputs[0].text)
prompt += chunk.outputs[0].text
在实际项目中，vLLM的批处理能力确实带来了显著的效率提升。特别是在处理客服问答、批量内容生成等场景时，相比单条推理可以节省大量成本。不过也需要注意，不同模型的最佳参数组合需要实际测试调整，特别是中文模型与原始LLaMA系列的表现差异较大。