第 1 章什么是 vLLM1.1 定义vLLM是一个开源的大语言模型LLM推理和部署引擎旨在提供高性能、低成本的 LLM 服务解决方案。1.2 核心价值传统方案 vLLM 方案─────────────────────────────GPU 利用率低 → GPU 利用率高 (4% 浪费)响应速度慢 → 吞吐量提升 24 倍内存浪费严重 → 节省约 50% 显存成本高昂 → 更低的硬件成本1.3 应用场景离线批量推理一次性处理大量文本生成任务在线 API 服务为多个用户提供实时对话服务边缘设备部署在有限硬件上运行大模型研究实验快速验证不同模型的效果第 2 章环境准备与安装2.1 系统要求组件最低要求推荐配置Python3.83.10-3.12GPUNVIDIA (CUDA 11.8)RTX 3090/4090, A100, H100显存8GB24GB用于更大模型存储50GB100GB模型文件占用大2.2 安装方式一pip最简单# 基础安装 pip install vllm # 指定版本稳定版推荐 pip install vllm0.11.22.3 安装方式二uv更快# 先安装 uv现代 Python 包管理器 pip install uv # 使用 uv 安装 vLLM速度是 pip 的 10-100 倍 uv pip install vllm2.4 安装方式三conda pip# 创建 conda 环境 conda create -n vllm_env python3.10 -y conda activate vllm_env # 安装 vLLM pip install vllm2.5 Docker 安装隔离环境推荐# 拉取镜像 docker pull vllm/vllm-openai:latest # 运行容器支持 GPU docker run --gpus all \ -p 8000:8000 \ -v /path/to/models:/models \ vllm/vllm-openai:latest \ serve vllm/example_model2.6 验证安装python -c import vllm; print(vllm.__version__) # 应该输出类似0.11.22.7 测试运行创建一个测试文件test_vllm.pyfrom vllm import LLM, SamplingParams print(✅ vLLM 安装成功)第 3 章核心概念解析3.1 LLM大语言模型LLM Large Language Model本质一个能理解和生成人类语言的神经网络输入一段文字Prompt输出预测的最可能的后续文字常见模型Llama 3, Qwen, ChatGLM, Baichuan3.2 KV Cache 是什么问题背景在 LLM 生成过程中每个新 token 都需要用到之前所有 token 的计算结果。直接重复计算会导致极慢的速度巨大的内存浪费解决方案缓存将每一步计算的 Key 和 Value 保存下来后续直接使用称为KV Cache。时间步 t1: 输入今天天气真 → 计算 KV → 输出好 时间步 t2: 输入今天天气真好 → 复用之前的 KV 新增 KV → 输出的3.3 PagedAttention 技术原理这是 vLLM 的核心创新技术灵感来自操作系统管理内存的分页机制。传统 Attention vs PagedAttention【传统方法】连续内存分配 ┌──────────────────────────────────────┐ │ [Block 1][未用空间][未用空间... ] ← 浪费 └──────────────────────────────────────┘ 【PagedAttention】分页内存分配 ┌──────────────────────────────────────┐ │ [Page1]──┐ │ │ [Page2]──┼→ PageTable → 逻辑块 A │ │ [Page3]──┘ │ │ │ │ [Page4]──┐ │ │ [Page5]──┼→ PageTable → 逻辑块 B │ └──────────────────────────────────────┘ 非连续物理存储通过页表映射关键优势对比项传统方法PagedAttention内存碎片率30-60%4%吞吐量1x~24x显存需求高降低约 50%3.4 Continuous Batching连续批处理问题传统批处理方式等待一批中所有请求都完成才能开始下一批Continuous Batching 解决方式每个请求独立进行随时可以加入或离开批次最大化 GPU 利用率。时间 → 传统批处理[█ 批次 1 █] [空闲] [█ 批次 2 █] [空闲] ... Continuous: [█ 批次 1 ███ 批次 2 █] [███████...] 无空闲第 4 章第一个 vLLM 程序4.1 Hello World 示例from vllm import LLM, SamplingParams # Step 1: 初始化 LLM 引擎 llm LLM(modelQwen/Qwen2.5-0.5B-Instruct) # 小白建议用这个小模型 # Step 2: 设置采样参数 sampling_params SamplingParams( temperature0.8, # 创造性0.0机械1.0随机 top_p0.95, # 从最可能的前 95% 中选择 max_tokens100, # 最大生成 token 数 ) # Step 3: 准备输入提示 prompts [ 你好请介绍一下你自己, 中国的首都是哪里, 用一句话形容人工智能的未来 ] # Step 4: 执行推理 outputs llm.generate(prompts, sampling_params) # Step 5: 打印结果 for output in outputs: prompt output.prompt generated_text output.outputs[0].text print(f用户{prompt}) print(fAI:{generated_text}\n) print( * 60)4.2 参数说明SamplingParams 常用参数参数含义推荐值temperature温度控制创造性0.7-0.9top_p核采样概率阈值0.9-0.95max_tokens最大生成长度根据需求best_of并行生成样本数默认 1frequency_penalty频率惩罚0.0-0.5第 5 章API 详解与实践5.1 LLM 类高级 API推荐使用适合快速开发、简单场景from vllm import LLM, SamplingParams # 初始化 llm LLM( modelmeta-llama/Llama-2-7b-hf, # 模型名称或路径 tensor_parallel_size1, # 多 GPU 时设置 1 gpu_memory_utilization0.9, # GPU 显存使用比例 max_model_len4096 # 上下文长度 ) # 生成 outputs llm.generate( prompts[Hello], sampling_paramsSamplingParams(temperature0.8) ) # 关闭 llm.shutdown()5.2 AsyncLLMEngine异步 API生产推荐适合高并发、需要流式输出的场景import asyncio from vllm import SamplingParams from vllm.engine.async_llm_engine import AsyncLLMEngine async def main(): # 初始化异步引擎 engine AsyncLLMEngine.from_model_config( model_configmeta-llama/Llama-2-7b-hf ) sampling_params SamplingParams(temperature0.8) async for output in engine.generate( {prompt: Hello}, sampling_paramssampling_params, request_idrequest-1 ): print(output.outputs[0].text) await engine.end_request(request_idrequest-1) await engine.shutdown() # 运行 asyncio.run(main())5.3 流式输出from vllm import LLM, SamplingParams llm LLM(modelQwen/Qwen2.5-0.5B-Instruct) params SamplingParams( temperature0.8, max_tokens50, streamTrue, # 启用流式输出 stream_options{include_start_code: False} ) outputs llm.generate(请讲一段话, params) # 查看生成的片段 for token in outputs[0].outputs[0].tokens: print(token.text, end, flushTrue)第 6 章OpenAI API 兼容服务6.1 启动服务器# 本地运行默认端口 8000 python -m vllm.entrypoints.api_server \ --model Qwen/Qwen2.5-0.5B-Instruct \ --port 8000 # 后台运行 nohup python -m vllm.entrypoints.api_server \ --model Qwen/Qwen2.5-0.5B-Instruct \ --host 0.0.0.0 \ --port 8000 server.log 21 6.2 使用 OpenAI SDK 调用from openai import OpenAI # 配置客户端 client OpenAI( base_urlhttp://localhost:8000/v1, api_keynot-needed # vLLM 不需要真正的密钥 ) # 调用 response client.chat.completions.create( modelQwen/Qwen2.5-0.5B-Instruct, messages[ {role: user, content: 请用英文介绍 Python} ], temperature0.7, max_tokens200 ) print(response.choices[0].message.content)6.3 Stream 模式with client.chat.completions.create( modelQwen/Qwen2.5-0.5B-Instruct, messages[{role: user, content: 写一首诗}], streamTrue, ) as stream: for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end, flushTrue)第 7 章性能优化7.1 GPU 资源调优llm LLM( modelyour-model, gpu_memory_utilization0.95, # 提高显存使用率 max_num_batched_tokens8192, # 每批最大 token max_num_seqs256, # 每批最大序列数 swap_space16, # CPU 交换空间GB )7.2 批处理大小选择Batch Size适用场景1-4延迟敏感型任务8-32一般应用64-128离线批量推理7.3 监控工具# 添加日志 llm LLM( model..., enforce_eagerFalse, # 使用编译加速 disable_log_statsFalse, # 开启性能统计 ) # 观察控制台输出的性能指标 # tokens/s, throughput, GPU memory usage 等附录 A常见问题排查Q1: 安装失败# 检查 CUDA 版本 nvcc --version # 确保 Python 3.8 python --version # 清理缓存重装 pip cache purge pip install vllm --no-cache-dirQ2: 显存不足llm LLM( gpu_memory_utilization0.7, # 降低使用比例 max_model_len2048, # 减少上下文长度 )Q3: 找不到模型# 自动下载 python script.py # 第一次运行会自动下载 # 或手动下载后指定路径 llm LLM(model./local/path/to/model)附录 B参考资源官方文档文档类型URL快速开始https://docs.vllm.ai/en/latest/getting_started/quickstart/安装指南https://docs.vllm.ai/en/latest/getting_started/installation/API 文档https://docs.vllm.ai/en/stable/api/GitHubhttps://github.com/vllm-project/vllm中文资源vLLM 中文站https://vllm.hyper.ai/知乎教程https://zhuanlan.zhihu.com/p/691038809视频资源YouTube: A Beginners Guide to Understanding and Using vLLMBilibili: vLLM 实战教程 下一步学习建议✅ 完成本文档的所有代码示例 阅读 vLLM 官方设计文档PagedAttention 实践一个完整项目如聊天机器人、文章生成器 尝试修改配置参数观察性能变化 参与社区讨论和问题解答