vLLM【一、简介】

vLLM 完整详细教程：原理、功能、安装、部署实战

vLLM 是目前GPU 上部署大模型速度最快、吞吐最高的开源推理框架，由 UC Berkeley RISE Lab 开发，核心靠 PagedAttention 技术碾压传统 Transformers。

下面从原理 → 核心功能 → 安装 → 单卡/多卡部署 → API 调用 → 常见问题完整讲透。

一、vLLM 核心原理（一句话看懂）

1. 核心创新：PagedAttention

传统 Transformers 推理时：

每个请求的 KV Cache 是连续大块内存
上下文变长、并发多时，内存严重碎片化 → OOM、速度慢

vLLM 借鉴操作系统分页机制：

把 KV Cache 切成固定大小的页（Page）
按需分配、动态复用
显存利用率提升 3~5 倍
吞吐量提升 10~20 倍

2. 优势总结

极高并发、极低延迟
完美支持流式输出
支持多 GPU 张量并行 / 流水线并行
兼容 OpenAI API 格式
支持 GPTQ/AWQ/FP8 量化
支持 Prefix Caching（前缀缓存，对话场景巨快）

二、vLLM 核心功能

高吞吐推理：适合 API 服务、批量处理
流式生成（streaming）
张量并行（Tensor Parallelism）：多卡跑大模型
流水线并行（Pipeline Parallelism）
量化支持：GPTQ / AWQ / FP8 / INT4
OpenAI 兼容接口：/v1/completions、/v1/chat/completions
前缀缓存（Prefix Caching）：系统提示、长上下文复用
采样参数完整：temperature、top_p、top_k、frequency_penalty 等
支持主流模型：Llama、Qwen、GLM、DeepSeek、Llama 3、Mistral 等

三、环境与安装

1. 硬件要求

NVIDIA GPU（必须，AMD/CPU 不支持）
显存 ≥4GB（7B INT4）
显存 ≥10GB（7B FP16）
CUDA ≥11.8

2. 安装（推荐 Conda）

# 创建环境
conda create -n vllm python=3.10
conda activate vllm

# 安装 vLLM（自动匹配 CUDA）
pip install vllm

验证安装：

python -c "import vllm; print(vllm.__version__)"

四、部署方式 1：命令行启动 API 服务（最常用）

示例：部署 Qwen2.5-7B-Instruct

1. 基础启动（单 GPU）

python -m vllm.entrypoints.api_server \
  --model Qwen/Qwen2.5-7B-Instruct \
  --trust-remote-code \
  --dtype auto \
  --gpu-memory-utilization 0.9 \
  --port 8000

参数解释：

--model：模型名称（Hugging Face 或本地路径）
--trust-remote-code：国产模型必加
--dtype auto：自动选择 FP16/BF16
--gpu-memory-utilization 0.9：显存占用上限
--port 8000：API 端口

2. 带 INT4/AWQ/GPTQ 量化启动（省显存）

以 AWQ 量化为例（速度快、显存低）：

python -m vllm.entrypoints.api_server \
  --model Qwen/Qwen2.5-7B-Instruct-AWQ \
  --quantization awq \
  --trust-remote-code \
  --port 8000

3. 多 GPU 部署（张量并行）

2 块卡跑 7B/13B：

python -m vllm.entrypoints.api_server \
  --model Qwen/Qwen2.5-7B-Instruct \
  --tensor-parallel-size 2 \
  --trust-remote-code \
  --port 8000

4. 开启前缀缓存（对话场景加速）

--enable-prefix-caching

五、部署方式 2：Python 代码直接调用（开发集成）

适合写脚本、批量处理、嵌入项目。

from vllm import LLM, SamplingParams

# 1. 加载模型
llm = LLM(
    model="Qwen/Qwen2.5-7B-Instruct",
    trust_remote_code=True,
    gpu_memory_utilization=0.9,
)

# 2. 生成参数
sampling_params = SamplingParams(
    temperature=0.7,
    top_p=0.9,
    max_tokens=1024,
)

# 3. 推理
prompts = [
    "介绍一下vLLM",
    "写一个Python快速排序"
]

outputs = llm.generate(prompts, sampling_params)

# 输出结果
for output in outputs:
    prompt = output.prompt
    generated = output.outputs[0].text
    print(f"输入：{prompt}")
    print(f"输出：{generated}\n")

六、OpenAI 兼容 API 调用（对接前端/项目）

vLLM 启动后，完全兼容 OpenAI 格式，可以无缝对接 ChatGPT-Next-Web、Open WebUI 等。

1. CURL 测试

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen2.5-7B-Instruct",
    "messages": [
      {"role": "system", "content": "你是一个AI助手"},
      {"role": "user", "content": "讲个笑话"}
    ],
    "temperature": 0.7,
    "stream": true
  }'

2. Python 调用（openai 库）

pip install openai

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="dummy"
)

resp = client.chat.completions.create(
    model="Qwen2.5-7B-Instruct",
    messages=[
        {"role": "user", "content": "你好"}
    ],
    stream=True
)

for chunk in resp:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

七、部署更大模型示例（13B / 33B）

1. 部署 Qwen2.5-14B（2 卡）

python -m vllm.entrypoints.api_server \
  --model Qwen/Qwen2.5-14B-Instruct \
  --tensor-parallel-size 2 \
  --trust-remote-code \
  --port 8000

2. 部署 DeepSeek-R1 7B

python -m vllm.entrypoints.api_server \
  --model deepseek-ai/DeepSeek-R1-Distill-Llama-8B \
  --trust-remote-code \
  --port 8000

八、常用重要参数大全（必收藏）

--model                     模型路径或HF名称
--trust-remote-code         国产模型必须加
--tensor-parallel-size N    多GPU数量
--quantization awq/gptq/fp8 量化模式
--dtype auto/bf16/fp16      精度
--gpu-memory-utilization    显存占比（0~1）
--max-num-batched-samples   最大并发请求
--max-model-len             上下文窗口
--enable-prefix-caching     开启前缀缓存
--port                     API端口
--api-key                  设置API密钥

九、常见问题与排错

1. OutOfMemoryError

加 --quantization awq
降低 --gpu-memory-utilization 0.7
用 INT4 模型
多卡并行 --tensor-parallel-size 2

2. 国产模型加载报错

必须加：

--trust-remote-code

3. 端口被占用

换端口：

--port 8001

4. 速度慢

开启 --enable-prefix-caching
使用 AWQ/GPTQ 量化
提高 batch 配置

十、vLLM vs Ollama vs llama.cpp

框架	速度	GPU	易用性	适合场景
vLLM	极快	NVIDIA 专用	中	生产、高并发、API服务
Ollama	快	全平台	极易	个人快速部署
llama.cpp	快	CPU/低功耗	中	低配设备、边缘端

十一、你可以直接复制的“最佳实践启动命令”

个人开发（7B AWQ）

python -m vllm.entrypoints.api_server \
  --model Qwen/Qwen2.5-7B-Instruct-AWQ \
  --quantization awq \
  --trust-remote-code \
  --gpu-memory-utilization 0.85 \
  --enable-prefix-caching \
  --port 8000

生产高并发

python -m vllm.entrypoints.api_server \
  --model Qwen/Qwen2.5-7B-Instruct-AWQ \
  --quantization awq \
  --tensor-parallel-size 2 \
  --trust-remote-code \
  --max-num-batched-samples 32 \
  --enable-prefix-caching \
  --port 8000

posted @ 2026-03-31 16:07 蓝迷梦阅读(114) 评论(0) 收藏举报

刷新页面返回顶部

蓝迷梦