vLLM安装部署与快速入门指南
项目地址: https://gitcode.com/GitHub_Trending/vl/vllm 1. 引言：为什么选择vLLM？
你是否还在为大语言模型（LLM）部署时的低吞吐量和高内存占用而困扰？vLLM（Very Large Language Model Serving Engine）作为一款高性能、内存高效的LLM推理和服务引擎，通过创新性的PagedAttention技术，实现了比传统方法高出10-20倍的吞吐量，同时保持了良好的推理质量。本文将详细介绍vLLM的安装部署流程和快速入门指南，帮助你在各种硬件环境下轻松搭建高效的LLM服务。
读完本文后，你将能够：
- 在不同硬件环境（NVIDIA GPU、CPU等）下正确安装vLLM
- 掌握vLLM的基本使用方法，包括离线批量推理和在线服务部署
- 了解vLLM的核心特性和高级配置选项
- 通过实际案例快速上手vLLM的各项功能
2. 安装准备与环境要求
2.1 硬件要求
vLLM支持多种硬件平台，不同平台的要求如下：
| 硬件类型 | 最低要求 | 推荐配置 |
|---|---|---|
| NVIDIA GPU | 计算能力7.0以上（如V100、T4、RTX20xx系列） | A100、H100、L4等 |
| CPU | x86_64或ARM架构，8核以上 | 16核以上，支持AVX2指令集 |
| 内存 | 至少16GB | 32GB以上 |
| 存储 | 至少10GB可用空间 | SSD，100GB以上可用空间 |
2.2 软件要求
| 软件 | 版本要求 |
|---|---|
| 操作系统 | Linux（推荐Ubuntu 20.04+） |
| Python | 3.9 - 3.12 |
| CUDA（GPU版本） | 11.8以上，推荐12.6或12.8 |
| PyTorch | 1.13.1以上 |
3. 安装vLLM
3.1 NVIDIA GPU环境安装（推荐）
3.1.1 使用预编译wheels（推荐方法）
vLLM提供了预编译的wheels，支持不同的CUDA版本。使用uv工具可以自动选择合适的PyTorch版本：
# 安装uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 创建虚拟环境并安装vLLM
uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto
如果使用pip，可以按以下方式安装特定CUDA版本的vLLM：
# 安装CUDA 12.8版本的vLLM
pip install vllm --extra-index-url https://download.pytorch.org/whl/cu128
# 安装CUDA 12.6版本的vLLM
pip install vllm --extra-index-url https://download.pytorch.org/whl/cu126
# 安装CUDA 11.8版本的vLLM
pip install vllm --extra-index-url https://download.pytorch.org/whl/cu118
3.1.2 从源码构建
如果需要修改vLLM的源代码或适配特定环境，可以从源码构建：
# 克隆仓库
git clone https://github.com/vllm-project/vllm.git
cd vllm
# 使用uv从源码安装
uv pip install -e .
对于频繁的C++/CUDA内核修改，推荐使用增量编译工作流以加快构建速度：
# 首次完整构建
uv pip install -e .
# 后续修改C++/CUDA代码后，仅重新编译修改的部分
cd csrc
make -j$(nproc)
cd ..
3.2 CPU环境安装
对于没有GPU的环境，可以安装CPU版本的vLLM：
uv pip install vllm[cpu] --extra-index-url https://download.pytorch.org/whl/cpu
或使用pip：
pip install vllm[cpu] --extra-index-url https://download.pytorch.org/whl/cpu
3.3 Docker容器安装
vLLM提供了预构建的Docker镜像，方便快速部署：
# 拉取最新的CUDA版本镜像
docker pull vllm/vllm-openai:latest
# 运行容器
docker run --gpus all -p 8000:8000 -it --rm vllm/vllm-openai:latest \
--model Qwen/Qwen2.5-1.5B-Instruct \
--port 8000
如需构建自定义Docker镜像：
git clone https://github.com/vllm-project/vllm.git
cd vllm
docker build -t vllm-custom -f docker/Dockerfile .
4. 快速入门：vLLM基础使用
4.1 离线批量推理
vLLM提供了简洁的Python API，用于离线批量推理任务。以下是一个基本示例：
from vllm import LLM, SamplingParams
# 定义输入提示
prompts = [
"Hello, my name is",
"The head of the United States is",
"The capital of France is",
"The future of AI is",
]
# 定义采样参数
sampling_params = SamplingParams(
temperature=0.8, # 控制输出随机性，0表示确定性输出
top_p=0.95, # 核采样概率阈值
max_tokens=128 # 最大生成token数
)
# 创建LLM实例，加载模型
llm = LLM(
model="facebook/opt-125m", # 模型名称或本地路径
tensor_parallel_size=1, # 张量并行数量，根据GPU数量调整
gpu_memory_utilization=0.9 # GPU内存利用率
)
# 生成文本
outputs = llm.generate(prompts, sampling_params)
# 打印结果
for output in outputs:
prompt = output.prompt
generated_text = output.outputs[0].text
print(f"Prompt: {prompt!r}")
print(f"Generated text: {generated_text!r}\n")
4.1.1 聊天模型使用示例
对于聊天模型，需要应用相应的聊天模板：
from vllm import LLM, SamplingParams
from transformers import AutoTokenizer
# 加载模型和tokenizer
model_name = "Qwen/Qwen2.5-1.5B-Instruct"
tokenizer = AutoTokenizer.from_pretrained(model_name)
llm = LLM(model=model_name)
# 定义对话历史
messages_list = [
[{"role": "user", "content": "推荐一部科幻电影"}],
[{"role": "system", "content": "你是一个电影推荐专家。"},
{"role": "user", "content": "推荐一部喜剧片，适合家庭观看的"}]
]
# 应用聊天模板
texts = tokenizer.apply_chat_template(
messages_list,
tokenize=False,
add_generation_prompt=True
)
# 生成回复
sampling_params = SamplingParams(temperature=0.7, max_tokens=200)
outputs = llm.generate(texts, sampling_params)
# 打印结果
for i, output in enumerate(outputs):
print(f"对话 {i+1}:")
print(f"用户: {messages_list[i][-1]['content']}")
print(f"助手: {output.outputs[0].text}\n")
4.2 启动OpenAI兼容服务器
vLLM可以部署为兼容OpenAI API的服务器，方便集成到现有应用中：
# 启动服务器，加载Qwen2.5-1.5B-Instruct模型
vllm serve Qwen/Qwen2.5-1.5B-Instruct --port 8000
服务器启动后，可以通过HTTP请求与其交互：
4.2.1 使用curl测试
# 测试聊天补全API
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen/Qwen2.5-1.5B-Instruct",
"messages": [
{"role": "system", "content": "你是一个 helpful 的助手。"},
{"role": "user", "content": "什么是人工智能？用简单的语言解释一下。"}
],
"temperature": 0.7,
"max_tokens": 200
}'
4.2.2 使用Python客户端测试
from openai import OpenAI
# 配置客户端
client = OpenAI(
api_key="EMPTY", # vLLM服务器默认不需要API密钥
base_url="http://localhost:8000/v1"
)
# 测试聊天补全
response = client.chat.completions.create(
model="Qwen/Qwen2.5-1.5B-Instruct",
messages=[
{"role": "system", "content": "你是一个编程助手。"},
{"role": "user", "content": "用Python写一个快速排序算法。"}
],
temperature=0.5
)
print(response.choices[0].message.content)
5. 高级配置与优化
5.1 关键启动参数
vLLM提供了丰富的配置参数，以优化性能和适应不同场景：
# 常用参数示例
vllm serve Qwen/Qwen2.5-7B-Instruct \
--port 8000 \ # 服务器端口
--host 0.0.0.0 \ # 绑定的主机地址
--tensor-parallel-size 2 \ # 张量并行数量（使用2块GPU）
--gpu-memory-utilization 0.9 \ # GPU内存利用率
--max-num-batched-tokens 8192 \ # 批处理的最大token数
--max-num-seqs 256 \ # 最大并发序列数
--quantization awq \ # 使用AWQ量化
--load-format auto \ # 自动选择最佳加载格式
--enable-prefix-caching \ # 启用前缀缓存
--generation-config vllm # 使用vllm默认生成配置
5.2 量化配置
为节省显存并提高性能，可以使用量化技术：
# 使用GPTQ量化
vllm serve TheBloke/Llama-2-7B-Chat-GPTQ \
--quantization gptq \
--gptq-bits 4 \
--gptq-group-size 128 \
--gptq-act-order
# 使用AWQ量化
vllm serve TheBloke/Llama-2-7B-Chat-AWQ \
--quantization awq \
--awq-bits 4 \
--awq-group-size 128
# 使用SqueezeLLM量化
vllm serve facebook/opt-13b \
--quantization squeeze_llm \
--squeeze-llm-bits 4
5.3 多GPU和分布式部署
对于大型模型，可以使用多GPU进行部署：
# 单机多GPU部署（2块GPU）
vllm serve Qwen/Qwen2.5-14B-Instruct \
--tensor-parallel-size 2 \
--gpu-memory-utilization 0.85
# 多机多GPU部署（使用torchrun）
torchrun --nnodes=2 --node_rank=0 --nproc_per_node=2 --master_addr="192.168.1.100" --master_port=29500 \
-m vllm.entrypoints.api_server Qwen/Qwen2.5-70B-Instruct \
--tensor-parallel-size 4 \
--port 8000
6. 常见问题与故障排除
6.1 安装问题
问题1：CUDA版本不匹配
症状：安装后导入vllm时出现CUDA版本不匹配错误。
解决方案：
# 卸载现有vllm和pytorch
pip uninstall -y vllm torch torchvision torchaudio
# 安装与CUDA版本匹配的版本
pip install vllm --extra-index-url https://download.pytorch.org/whl/cu128 # 替换为你的CUDA版本
问题2：编译失败
症状：从源码构建时编译失败。
解决方案：
# 确保安装了必要的依赖
sudo apt-get install -y build-essential cmake git libopenmpi-dev
# 安装CUDA工具包（如果尚未安装）
sudo apt-get install -y cuda-toolkit-12-8 # 替换为你的CUDA版本
# 设置CUDA环境变量
export CUDA_HOME=/usr/local/cuda
export PATH=$CUDA_HOME/bin:$PATH
# 重新构建
cd vllm
rm -rf build/ dist/
uv pip install -e .
6.2 运行时问题
问题1：内存不足
症状：运行时出现"out of memory"错误。
解决方案：
- 减少批处理大小：
--max-num-batched-tokens - 降低GPU内存利用率：
--gpu-memory-utilization 0.8 - 使用量化：
--quantization awq - 增加张量并行度：
--tensor-parallel-size
问题2：性能不佳
症状：吞吐量低于预期。
解决方案：
- 调整批处理参数：
--max-num-batched-tokens和--max-num-seqs - 启用前缀缓存：
--enable-prefix-caching - 检查是否使用了正确的注意力后端：
# 设置注意力后端为FlashAttention
export VLLM_ATTENTION_BACKEND=FLASH_ATTN
vllm serve ...
7. 总结与进阶学习
通过本文，你已经掌握了vLLM的安装部署和基本使用方法。vLLM作为一款高性能的LLM服务引擎，凭借其创新的PagedAttention技术和优化的批处理策略，能够显著提高LLM的服务吞吐量和降低内存占用。
7.1 进阶学习资源
- 官方文档：详细了解vLLM的所有功能和配置选项（https://docs.vllm.ai）
- GitHub仓库：查看源代码和最新更新（https://github.com/vllm-project/vllm）
- 研究论文：了解vLLM背后的技术原理（https://arxiv.org/abs/2309.06180）
7.2 后续步骤
- 尝试部署更大规模的模型，如Llama 3、Qwen2.5-70B等
- 探索vLLM的高级功能，如LoRA微调、工具调用等
- 进行性能基准测试，优化你的部署配置
- 集成vLLM到你的应用系统中，提供高效的LLM服务
vLLM生态系统正在快速发展，定期查看官方更新以获取新功能和性能优化。祝你在vLLM的使用过程中取得成功！
附录：常用命令参考
| 功能 | 命令 |
|---|---|
| 安装vLLM（GPU，CUDA 12.8） | pip install vllm --extra-index-url https://download.pytorch.org/whl/cu128 |
| 启动OpenAI兼容服务器 | vllm serve Qwen/Qwen2.5-1.5B-Instruct --port 8000 |
| 启动带量化的服务器 | vllm serve TheBloke/Llama-2-7B-Chat-AWQ --quantization awq |
| 多GPU部署 | vllm serve Qwen/Qwen2.5-14B-Instruct --tensor-parallel-size 2 |
| 运行离线批量推理示例 | python examples/offline_inference/basic/basic.py |
| 运行聊天服务器示例 | python examples/online_serving/gradio_webserver.py |
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
