#vLLM 完整教程

欢迎来到 vLLM 完整教程。本教程基于 vLLM 官方文档 与开源项目 vllm-project/vllm 整理，帮你把 Hugging Face 上的开源模型，变成一台 高吞吐、OpenAI 兼容 的 GPU 推理服务。

vLLM 解决的是「很多请求同时打过来，怎么把 GPU 吃满、又不把显存浪费在 KV 缓存上」。核心手段是 PagedAttention 与 连续批处理（continuous batching）。它不是桌面聊天客户端——本机交互、一键换模型请走 Ollama；权重、模型卡、Tokenizer 请走 Hugging Face。

CLI、CUDA 轮子与量化枚举更新很快。文中会写清「以当前文档为准」的地方；动手前对照 docs.vllm.ai 与 vllm serve --help。

---

#教程目录

#基础篇

1. vLLM 简介 — 推理引擎定位、PagedAttention、连续批处理
2. 安装与环境 — Linux + NVIDIA CUDA、pip install vllm、Windows 用 WSL2
3. 快速上手 — vllm serve、小模型、第一条 /v1 请求

#接口与生成篇

4. OpenAI 兼容 API — http://localhost:8000/v1、chat/completions、SDK
5. 采样与生成参数 — SamplingParams、temperature / top_p、贪婪 vs 采样

#性能与部署篇

6. 量化 — AWQ / GPTQ / FP8、--quantization、何时不必手写标志
7. 生产服务 — --tensor-parallel-size、显存、鉴权边界
8. 对比 Ollama — 桌面 DX vs 生产吞吐，以及和 Hub 的分工
9. Docker 部署 — 官方镜像 vllm/vllm-openai

#实践篇

10. 实战案例 — 离线批推理、兼容客户端、并发冒烟
11. 资源与延伸阅读 — 官方文档与本站相关课

---

#学习路径

#本教程约定

• 主路径：Linux + NVIDIA CUDA。 CPU 后端不是本课重点；没有 NVIDIA GPU 请先看 Ollama。
• Windows： 官方不原生支持，用 WSL2（Ubuntu）+ GPU 直通。
• 演示模型（未门控、体积小）： Qwen/Qwen2.5-0.5B-Instruct（对话）或 facebook/opt-125m（补全）。不要把 Llama-2 当唯一示例——它常要许可证墙。
• 服务基址： http://localhost:8000/v1；对话走 /v1/chat/completions。
• 启动命令： 新版本用 vllm serve <model>；旧资料里的 python -m vllm.entrypoints.openai.api_server --model ... 仍可能可用，但正在弃用。以当前文档与 --help 为准。

#前置知识

• Python 3.10+（官方常见范围为 3.10–3.13，以当前文档为准）
• 会用终端、虚拟环境、pip 或 uv
• 知道 Chat Completions 长什么样（messages、role）
• 一块计算能力足够的 NVIDIA GPU（文档常写 7.5+，如 T4 / RTX 20 系及以上 / A100 / L4 / H100；以当前文档为准）
• 磁盘：Hub 缓存会占数 GB 到数十 GB

#学完你能做到

• 说明 vLLM 相对 Ollama / Transformers generate() 的分工
• 在 Linux（或 WSL2）上安装并 vllm serve 一个小 Instruct 模型
• 用 curl / OpenAI Python SDK 打通 localhost:8000/v1
• 用 SamplingParams 区分贪婪与采样
• 读懂 AWQ / GPTQ / FP8 的选型，并知道 --quantization 何时需要
• 用 --tensor-parallel-size 和 Docker 镜像起一份可给同事打的服务

#相关教程

---

#下一步

• vLLM 简介
• 安装与环境
• 快速上手