在当今AI快速发展的时代，大模型推理性能直接影响着应用的用户体验和成本效益。vLLM作为一个高性能的大模型推理引擎，为开发者提供了快速、高效的模型服务解决方案。本文将详细介绍如何使用vLLM进行离线推理和在线服务部署，特别是如何利用uv工具进行快速环境管理，以及如何部署兼容OpenAI API的模型服务。

什么是vLLM

vLLM（Very Large Language Model）是由UC Berkeley开发的高性能大语言模型推理和服务引擎。它具有以下特点：

  • 高吞吐量：通过PagedAttention等技术优化，显著提升推理速度
  • 内存效率：动态内存管理，减少显存占用
  • 易于使用：提供简洁的Python API和OpenAI兼容接口
  • 灵活部署：支持批量推理和在线服务两种模式

环境准备与安装

系统要求

  • 操作系统：Linux
  • Python版本：3.9 - 3.12
  • 硬件：NVIDIA GPU（推荐）

使用uv工具快速安装

uv是一个超快的Python环境管理器，可以显著加速环境创建和包安装过程。

1. 安装uv工具

1
2
3
4
5
# 在Linux/macOS上安装uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用pip安装
pip install uv

2. 创建Python环境并安装vLLM

1
2
3
4
# 创建Python 3.12环境并安装vLLM
uv venv myenv --python 3.12 --seed
source myenv/bin/activate
uv pip install vllm

3. 一键运行方式（推荐）

如果您只是想快速测试vLLM，可以使用uv的--with选项直接运行，无需创建虚拟环境：

1
2
3
4
5
# 直接运行vLLM命令
uv run --with vllm vllm --help

# 启动vLLM服务
uv run --with vllm vllm serve Qwen/Qwen2.5-1.5B-Instruct

传统conda安装方式

如果您更习惯使用conda管理环境：

1
2
3
conda create -n vllm-env python=3.12 -y
conda activate vllm-env
pip install vllm

常用模型下载与本地存放位置说明

在使用vLLM进行推理或服务部署前，需先准备好大模型权重文件。vLLM支持直接加载HuggingFace Hub上的主流模型，常见模型包括：

  • Qwen/Qwen2.5-1.5B-Instruct
  • meta-llama/Llama-2-7b-chat-hf
  • baichuan-inc/Baichuan2-7B-Chat
  • internlm/internlm2-chat-1_8b
  • deepseek-ai/deepseek-llm-7b-chat

下载模型命令示例

以Qwen2.5-1.5B-Instruct为例，可使用如下命令提前下载模型：

1
2
3
# 使用huggingface-cli下载模型
pip install huggingface_hub
huggingface-cli download Qwen/Qwen2.5-1.5B-Instruct --local-dir ./models/Qwen2.5-1.5B-Instruct

或直接在vLLM加载时自动下载：

1
vllm serve Qwen/Qwen2.5-1.5B-Instruct

模型本地存放路径

  • 默认情况下，HuggingFace Hub会将模型文件缓存到 ~/.cache/huggingface/hub 目录。
  • 你也可以通过 HUGGINGFACE_HUB_CACHE 环境变量自定义缓存路径，例如：
1
export HUGGINGFACE_HUB_CACHE=/data/models/hf_cache
  • 若使用huggingface-cli download，可通过--local-dir参数指定下载目录。

注意事项

注意：首次加载大模型时需保证磁盘空间充足，部分模型体积较大（数GB至数十GB不等）。

安全建议：请从官方或权威渠道下载模型，避免使用来历不明的第三方模型文件。

离线批量推理

vLLM的离线推理功能适用于批量处理大量文本的场景，如数据分析、内容生成等。

基础使用示例

创建一个Python脚本offline_inference.py：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
from vllm import LLM, SamplingParams

# 定义输入提示列表
prompts = [
    "你好，我的名字是",
    "人工智能的未来是",
    "深度学习最重要的突破是",
    "请解释一下什么是Transformer架构",
]

# 配置采样参数
# temperature: 控制生成文本的随机性，值越高越随机
# top_p: 核采样参数，控制候选词汇的范围
# max_tokens: 生成文本的最大长度
sampling_params = SamplingParams(
    temperature=0.8, 
    top_p=0.95,
    max_tokens=256
)

# 初始化vLLM引擎
# 这里使用较小的模型作为示例，您可以替换为其他支持的模型
llm = LLM(model="facebook/opt-125m")

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

# 处理并显示结果
for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text
    print(f"输入: {prompt}")
    print(f"输出: {generated_text}")
    print("-" * 50)

高级配置选项

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
from vllm import LLM, SamplingParams

# 创建更详细的采样配置
sampling_params = SamplingParams(
    temperature=0.7,           # 生成温度
    top_p=0.9,                # 核采样
    top_k=40,                 # Top-K采样
    repetition_penalty=1.1,    # 重复惩罚
    max_tokens=512,           # 最大生成长度
    stop=["</s>", "\n\n"]     # 停止符号
)

# 配置模型加载参数
llm = LLM(
    model="Qwen/Qwen2.5-1.5B-Instruct",
    tensor_parallel_size=1,    # 张量并行大小
    dtype="float16",           # 数据类型
    max_model_len=4096,       # 最大模型长度
    gpu_memory_utilization=0.8 # GPU内存使用率
)

部署OpenAI兼容API服务

vLLM最强大的功能之一是能够部署为兼容OpenAI API的服务，让您可以无缝替换OpenAI的API端点。

启动vLLM服务

1
2
3
4
5
6
7
8
9
10
# 启动基础服务
vllm serve Qwen/Qwen2.5-1.5B-Instruct

# 启动带自定义配置的服务
vllm serve Qwen/Qwen2.5-1.5B-Instruct \
    --host 0.0.0.0 \
    --port 8000 \
    --api-key your-api-key \
    --max-model-len 4096 \
    --tensor-parallel-size 1

使用curl测试API

1. 测试模型列表

1
curl http://localhost:8000/v1/models

2. 文本补全API

1
2
3
4
5
6
7
8
curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen2.5-1.5B-Instruct",
        "prompt": "人工智能的发展趋势是",
        "max_tokens": 100,
        "temperature": 0.7
    }'

3. 聊天补全API

1
2
3
4
5
6
7
8
9
10
11
curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen2.5-1.5B-Instruct",
        "messages": [
            {"role": "system", "content": "你是一个有用的AI助手。"},
            {"role": "user", "content": "请解释一下什么是机器学习？"}
        ],
        "max_tokens": 200,
        "temperature": 0.7
    }'

Python客户端使用

1. 使用OpenAI Python库

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
from openai import OpenAI

# 配置客户端连接到vLLM服务
client = OpenAI(
    api_key="your-api-key",  # 如果设置了API密钥
    base_url="http://localhost:8000/v1"
)

# 文本补全
completion = client.completions.create(
    model="Qwen/Qwen2.5-1.5B-Instruct",
    prompt="深度学习的核心概念包括",
    max_tokens=150,
    temperature=0.7
)

print("补全结果:", completion.choices[0].text)

# 聊天补全
chat_response = client.chat.completions.create(
    model="Qwen/Qwen2.5-1.5B-Instruct",
    messages=[
        {"role": "system", "content": "你是一个专业的技术顾问。"},
        {"role": "user", "content": "请推荐一个适合初学者的机器学习框架。"}
    ],
    max_tokens=200,
    temperature=0.7
)

print("聊天回复:", chat_response.choices[0].message.content)

2. 流式响应处理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="http://localhost:8000/v1"
)

# 流式聊天补全
stream = client.chat.completions.create(
    model="Qwen/Qwen2.5-1.5B-Instruct",
    messages=[
        {"role": "user", "content": "请详细介绍一下Transformer架构的工作原理。"}
    ],
    stream=True,
    max_tokens=500
)

print("流式响应:")
for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="", flush=True)
print()

生产环境部署建议

1. 服务配置优化

1
2
3
4
5
6
7
8
9
10
# 生产环境启动脚本
vllm serve Qwen/Qwen2.5-7B-Instruct \
    --host 0.0.0.0 \
    --port 8000 \
    --api-key $(cat /path/to/api-key) \
    --tensor-parallel-size 2 \
    --max-model-len 8192 \
    --gpu-memory-utilization 0.85 \
    --disable-log-requests \
    --max-num-seqs 64

2. Docker部署

创建Dockerfile：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
FROM nvidia/cuda:12.1-devel-ubuntu20.04

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    python3 python3-pip curl \
    && rm -rf /var/lib/apt/lists/*

# 安装uv和vLLM
RUN curl -LsSf https://astral.sh/uv/install.sh | sh
ENV PATH="/root/.cargo/bin:$PATH"
RUN uv pip install --system vllm

# 设置工作目录
WORKDIR /app

# 暴露端口
EXPOSE 8000

# 启动命令
CMD ["vllm", "serve", "Qwen/Qwen2.5-1.5B-Instruct", "--host", "0.0.0.0", "--port", "8000"]

构建并运行：

1
2
3
4
5
# 构建镜像
docker build -t vllm-server .

# 运行容器
docker run --gpus all -p 8000:8000 vllm-server

3. 负载均衡和监控

使用Nginx进行负载均衡：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
upstream vllm_backend {
    server 127.0.0.1:8000;
    server 127.0.0.1:8001;
    server 127.0.0.1:8002;
}

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://vllm_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 300s;
        proxy_connect_timeout 30s;
    }
}

性能优化技巧

1. 显存优化

1
2
3
4
5
6
# 启用KV缓存量化
llm = LLM(
    model="your-model",
    kv_cache_dtype="fp8",  # 使用FP8量化KV缓存
    quantization="awq"      # 使用AWQ量化
)

2. 并行策略

1
2
3
4
5
# 多GPU张量并行
vllm serve your-model --tensor-parallel-size 4

# 流水线并行（适用于超大模型）
vllm serve your-model --pipeline-parallel-size 2

3. 批处理优化

1
2
3
4
5
6
7
# 动态批处理配置
sampling_params = SamplingParams(
    temperature=0.7,
    max_tokens=256,
    # 启用连续批处理
    use_beam_search=False
)

常见问题和解决方案

1. 内存不足错误

1
2
3
4
5
# 降低GPU内存使用率
vllm serve your-model --gpu-memory-utilization 0.7

# 启用CPU卸载
vllm serve your-model --cpu-offload-gb 4

2. 模型加载失败

1
2
3
4
5
# 使用ModelScope镜像（国内用户）
import os
os.environ["VLLM_USE_MODELSCOPE"] = "true"

llm = LLM(model="qwen/Qwen2.5-1.5B-Instruct")

3. API响应超时

1
2
3
4
5
# 增加超时时间
curl -X POST http://localhost:8000/v1/chat/completions \
    --max-time 300 \
    -H "Content-Type: application/json" \
    -d '{"model": "your-model", "messages": [...]}'

总结

vLLM作为一个高性能的大模型推理引擎，为开发者提供了强大的工具来部署和使用大语言模型。通过本文的介绍，您应该能够：

  1. 快速环境搭建：使用uv工具高效管理Python环境和依赖
  2. 离线批量推理：处理大规模文本生成任务
  3. 在线API服务：部署兼容OpenAI API的模型服务
  4. 生产环境优化：通过各种配置提升性能和稳定性

vLLM的优势在于其出色的性能表现和易用性，特别是在需要高吞吐量推理的场景下。随着大模型技术的不断发展，vLLM将继续是一个值得关注和使用的重要工具。

相关资源

本文由 AI 辅助生成，如有错误或建议，欢迎指出。