1.2 环境配置与安装

本节导读：手把手完成vLLM开发环境配置，从系统环境到最终验证的全流程实战，确保读者5分钟内跑通第一个vLLM推理任务。

学习目标

• 掌握vLLM运行所需的软硬件环境要求
• 熟练完成从Linux系统到Python环境的完整配置流程
• 能够独立部署vLLM并运行基础推理任务
• 了解常见环境问题的排查和解决方案
• 掌握Docker容器化部署的完整流程

核心概念

vLLM环境要求

vLLM作为高性能LLM推理引擎，对运行环境有特定要求：

硬件要求：

• GPU: NVIDIA GPU (RTX 20/30/40系列), 推荐8GB+显存
• CPU: 8核心+, x86_64架构
• 内存: 32GB+ (建议64GB)
• 存储: 100GB+可用空间(用于模型下载和缓存)

软件要求：

• 操作系统: Linux (Ubuntu 20.04/22.04), CentOS 7/8
• CUDA: 12.0+
• Python: 3.8+
• GPU驱动: 470+版本

部署模式对比

vLLM支持多种部署模式：

单机部署：

• 适合个人开发和小规模测试
• 一块GPU支持
• 配置简单，部署快速

多GPU并行：

• 适合中等规模应用
• 多块GPU支持
• 负载均衡和内存优化

容器化部署：

• 适合生产环境
• 环境一致性高
• 快速扩展和迁移

环境准备 / 前置知识

系统环境要求

# 系统要求
echo "=== 系统信息检查 ==="
cat /etc/os-release
uname -a

# GPU检查
nvidia-smi
nvcc --version

# 系统资源检查
free -h
df -h
lscpu | grep "CPU(s):"
​

系统要求详解：

• 操作系统: Ubuntu 20.04 LTS或CentOS 7.9
• GPU: NVIDIA显卡，RTX 20/30/40系列
• 内存: 建议32GB以上
• 存储: 至少100GB可用空间

基础依赖安装

# 更新系统包
sudo apt update && sudo apt upgrade -y

# 安装基础开发工具
sudo apt install -y build-essential git wget curl unzip

# 安装Python环境
sudo apt install -y python3 python3-pip python3-venv python3-dev

# 安装CUDA相关依赖
sudo apt install -y cuda-toolkit-12-1 libcudnn8 libcudnn8-dev

# 安装git LFS(大文件管理)
sudo apt install -y git-lfs
git lfs install
​

Python虚拟环境配置

# 创建虚拟环境
echo "=== 创建Python虚拟环境 ==="
python3 -m venv vllm-env
source vllm-env/bin/activate

# 升级pip
pip install --upgrade pip setuptools wheel

# 安装基础Python包
pip install numpy matplotlib pandas requests tqdm

# 验证安装
python -c "import sys; print(f'Python版本: {sys.version}')"
​

分步实战

步骤1：GPU环境配置

#!/usr/bin/env bash
# -*- coding: utf-8 -*-
"""
vLLM GPU环境配置脚本
"""

echo "=== GPU环境配置检查 ==="

# 检查GPU是否可用
echo "1. 检查GPU可用性..."
python3 -c "import torch; print(f'CUDA可用: {torch.cuda.is_available()}'); print(f'CUDA版本: {torch.version.cuda}'); print(f'GPU数量: {torch.cuda.device_count()}')"

# 获取GPU信息
echo "2. GPU详细信息..."
nvidia-smi --query-gpu=name,memory.total,memory.used,memory.free --format=csv,noheader,nounits

# 检查CUDA版本
echo "3. CUDA工具包版本..."
nvcc --version

# 检查cuDNN版本
echo "4. cuDNN版本..."
find /usr/include -name "cudnn_version.h" 2>/dev/null | xargs grep "define CUDNN_MAJOR" | head -1
​

常见问题排查：

1. GPU不可用：检查NVIDIA驱动安装
2. CUDA版本不匹配：确保CUDA >= 12.0
3. 权限问题：用户需在sudo组或配置docker

步骤2：vLLM核心依赖安装

#!/usr/bin/env bash
# -*- coding: utf-8 -*-
"""
vLLM核心依赖安装脚本
"""

echo "=== vLLM核心依赖安装 ==="

# 进入虚拟环境
source vllm-env/bin/activate

# 安装PyTorch
echo "1. 安装PyTorch (支持CUDA 12.0)..."
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 验证PyTorch安装
python3 -c "
import torch
print(f'PyTorch版本: {torch.__version__}')
print(f'CUDA版本: {torch.version.cuda}')
print(f'GPU可用: {torch.cuda.is_available()}')
if torch.cuda.is_available():
    print(f'GPU数量: {torch.cuda.device_count()}')
    print(f'GPU名称: {torch.cuda.get_device_name()}')
"

# 安装vLLM
echo "2. 安装vLLM..."
pip install vllm --torch-backend cuda

# 验证vLLM安装
python3 -c "
import vllm
print(f'vLLM版本: {vllm.__version__}')
print('vLLM安装成功!')
"

# 安装其他依赖
echo "3. 安装辅助依赖..."
pip install transformers sentencepiece accelerate
​

步骤3：模型下载与准备

#!/usr/bin/env bash
# -*- coding: utf-8 -*-
"""
vLLM模型下载准备脚本
"""

echo "=== vLLM模型准备 ==="

# 创建模型目录
mkdir -p ~/vllm-models
cd ~/vllm-models

# 下载Qwen1.5-7B模型(示例)
echo "1. 下载Qwen1.5-7B模型..."
# 使用Hugging Face的模型下载器
git clone https://huggingface.co/Qwen/Qwen1.5-7B-Chat

# 或者使用huggingface-hub下载
# pip install huggingface-hub
# huggingface-cli download Qwen/Qwen1.5-7B-Chat --local-dir Qwen1.5-7B-Chat

# 验证模型结构
echo "2. 验证模型结构..."
python3 -c "
import os
import json

model_path = 'Qwen1.5-7B-Chat'
if os.path.exists(model_path):
    config_path = os.path.join(model_path, 'config.json')
    if os.path.exists(config_path):
        with open(config_path, 'r') as f:
            config = json.load(f)
        print(f'模型名称: {config.get(\"model_name\", \"未知\")}')
        print(f'模型架构: {config.get(\"model_type\", \"未知\")}')
        print(f'隐藏层大小: {config.get(\"hidden_size\", \"未知\")}')
        print(f'注意力头数: {config.get(\"num_attention_heads\", \"未知\")}')
        print(f'层数: {config.get(\"num_hidden_layers\", \"未知\")}')
    else:
        print('未找到配置文件')
else:
    print('模型目录不存在')
"

# 检查磁盘使用情况
echo "3. 磁盘使用情况..."
du -sh ~/vllm-models/
df -h .
​

步骤4：基础推理测试

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
vLLM基础推理测试
"""

import sys
import os
sys.path.insert(0, os.path.expanduser('~'))

from vllm import LLM, SamplingParams
import time

def test_basic_inference():
    """基础推理测试"""
    print("=== vLLM基础推理测试 ===")
    
    # 初始化LLM
    try:
        llm = LLM(
            model="Qwen/Qwen1.5-7B-Chat",
            tensor_parallel_size=1,
            gpu_memory_utilization=0.9,
            max_model_len=4096
        )
        print("✅ LLM初始化成功")
    except Exception as e:
        print(f"❌ LLM初始化失败: {e}")
        return False
    
    # 测试提示
    prompts = [
        "你好，请简单介绍一下vLLM的主要特点",
        "vLLM相比传统LLM推理有什么优势？",
        "如何使用vLLM进行文本生成？"
    ]
    
    # 配置采样参数
    sampling_params = SamplingParams(
        temperature=0.7,
        max_tokens=256,
        repetition_penalty=1.1
    )
    
    # 执行推理
    try:
        print("开始执行推理测试...")
        start_time = time.time()
        
        outputs = llm.generate(prompts, sampling_params)
        
        end_time = time.time()
        total_time = end_time - start_time
        
        print(f"✅ 推理完成，耗时: {total_time:.3f}秒")
        
        # 分析结果
        print("\n=== 推理结果 ===")
        for i, (prompt, output) in enumerate(zip(prompts, outputs)):
            response = output.outputs[0].text
            print(f"\n{i+1}. 输入: {prompt}")
            print(f"输出: {response}")
            print(f"Token数: {len(output.outputs[0].token_ids)}")
        
        print(f"\n=== 性能统计 ===")
        print(f"平均每个请求耗时: {total_time/len(prompts):.3f}秒")
        print(f"平均吞吐量: {len(prompts)/total_time:.1f} req/s")
        
        return True
        
    except Exception as e:
        print(f"❌ 推理失败: {e}")
        return False

def test_memory_usage():
    """内存使用测试"""
    print("\n=== 内存使用测试 ===")
    
    try:
        import torch
        print(f"当前GPU内存使用: {torch.cuda.memory_allocated()/1024**3:.1f}GB")
        print(f"当前GPU内存缓存: {torch.cuda.memory_reserved()/1024**3:.1f}GB")
        
        # 获取GPU利用情况
        llm = LLM(
            model="Qwen/Qwen1.5-7B-Chat",
            tensor_parallel_size=1,
            gpu_memory_utilization=0.9
        )
        
        print("✅ 内存使用测试通过")
        return True
        
    except Exception as e:
        print(f"❌ 内存使用测试失败: {e}")
        return False

def run_full_test():
    """运行完整测试套件"""
    print("=== vLLM环境完整测试 ===\n")
    
    # 测试1：基础推理
    test1_result = test_basic_inference()
    
    # 测试2：内存使用
    test2_result = test_memory_usage()
    
    # 总结
    print("\n=== 测试总结 ===")
    if test1_result and test2_result:
        print("🎉 所有测试通过！vLLM环境配置成功")
        print("现在可以开始使用vLLM进行LLM推理任务了")
        return True
    else:
        print("❌ 部分测试失败，请检查环境配置")
        return False

if __name__ == "__main__":
    success = run_full_test()
    sys.exit(0 if success else 1)
​

常见问题 FAQ

Q1：vLLM对硬件要求很高吗？

A：vLLM对硬件要求相对较高，但具体取决于使用场景：

• 开发测试: RTX 3060 (12GB) 就可以运行小模型
• 生产环境: RTX 3090/4090 (24GB+) 适合大模型
• 内存: 建议32GB以上，模型越大需要越多内存
• 存储: 需要足够的磁盘空间存放模型文件

Q2：如何在Windows系统上部署vLLM？

A：Windows系统部署vLLM需要额外配置：

1. 安装WSL2 (Windows Subsystem for Linux)
2. 在WSL2中安装Ubuntu系统
3. 按照Linux环境配置步骤进行
4. 确保GPU驱动支持WSL2

Q3：vLLM启动时遇到内存不足怎么办？

A：内存不足的解决方案：

1. 减少模型大小: 使用更小的模型版本
2. 调整参数: 降低gpu_memory_utilization
3. 启用内存优化: 使用--swap-space参数
4. 增加虚拟内存: 配置swap文件

Q4：vLLM支持哪些模型？

A：vLLM支持多种主流模型：

• Qwen系列: Qwen1.5-7B, Qwen1.5-13B等
• LLaMA系列: LLaMA-2-7B, LLaMA-2-13B等
• ChatGLM: ChatGLM2-6B等
• 其他: Baichuan-7B, Falcon-7B等

Q5：如何在Docker中部署vLLM？

A：Docker部署vLLM的步骤：

# 拉取vLLM镜像
docker pull vllm/vllm-openai:v0.2.0

# 运行容器
docker run -d \\
  --gpus all \\
  -p 8000:8000 \\
  -v /path/to/models:/models \\
  vllm/vllm-openai:v0.2.0 \\
  --model /models/Qwen1.5-7B-Chat \\
  --host 0.0.0.0 \\
  --port 8000 \\
  --tensor-parallel-size 1
​

最佳实践与避坑

最佳实践

1. 环境隔离: 使用虚拟环境避免依赖冲突
2. 版本管理: 固定依赖版本，避免升级导致问题
3. 监控部署: 配置日志和监控，及时发现问题
4. 备份重要: 定期备份模型配置和环境配置
5. 性能优化: 根据硬件选择合适的参数配置

常见坑点

1. CUDA版本不匹配: 确保CUDA、cuDNN、PyTorch版本一致
2. 权限问题: 确保用户有GPU访问权限
3. 路径错误: 模型路径要正确，绝对路径更可靠
4. 内存溢出: 合理设置gpu_memory_utilization
5. 网络问题: 模型下载可能需要配置代理

本节小结

本节详细介绍了vLLM的完整环境配置流程，从系统环境准备到生产环境部署，涵盖了所有必要的步骤和注意事项。通过本节的学习，读者应该能够独立完成vLLM环境的搭建，并运行基础的推理任务。

下一节将详细介绍vLLM的核心架构原理，帮助读者深入理解vLLM的技术实现。

延伸阅读

• vLLM官方文档
• CUDA安装指南
• Docker部署指南
• 相关章节：1.3 核心架构原理

关键词：vLLM配置, 环境安装, GPU部署, 模型下载, 生产环境
难度：入门
预计阅读：35分钟