vLLM：高吞吐 LLM 推理引擎

为什么需要 vLLM：传统推理吞吐瓶颈 → 高吞吐方案

在 vLLM 出现前，主流推理方案有两种：直接调用 Hugging Face Transformers 的 generate，或使用简单的批处理服务。前者每个请求独占显存，KV 缓存按最大序列长度预分配，实际用不到的部分全部浪费，显存碎片化严重；后者要求同批次请求同时开始、同时结束，先完成的请求必须空等，GPU 大量时间在“空转”。结果是：单卡跑 7B 模型看似没问题，一上并发或长上下文，显存立刻爆炸，吞吐掉到每卡每秒几个 token。

vLLM 从操作系统内存管理获得启发，实现 PagedAttention：把 KV 缓存切成固定大小的“页”，按需分配，像虚拟内存一样消除碎片，显存利用率接近零浪费；配合底层调度器的连续批处理，请求一结束立刻腾出位置给新请求加入，GPU 从不空等。官方 README 披露，相比 Hugging Face Transformers，吞吐最高可提升 24 倍。

与同类工具的气质差异在于：vLLM 采取“调度器 + 运行时优化”路线，不做模型编译，因此对新模型（Hugging Face 上主流开源权重）开箱即用，不需要像 TensorRT-LLM 那样为每个模型构建 TensorRT 引擎；又比 llama.cpp 更面向服务化多用户场景。这也是它能成为社区默认推理框架的原因。

安装与环境配置：3 步就绪

步骤一 · 安装：vLLM 是 Python 包，最简方式直接 pip 安装。要求 Python 3.9–3.12、CUDA 11.8 或 12.1+（NVIDIA GPU 显存建议 16GB 以上跑 7B 级模型）。若机器没有预编译 wheel 匹配，pip 会尝试从源码编译，耗时较长，此时建议改用 Docker 镜像 vllm/vllm-openai，镜像内含完整预编译环境和模型服务入口。

步骤二 · 配置：默认从 Hugging Face 下载模型。若在离线环境，提前设置 HF_HOME 指向本地模型缓存目录，或用 HF_ENDPOINT=https://hf-mirror.com 指定下载镜像。

步骤三 · 验证：导入包并输出版本号，确认安装成功。

pip install vllm # 离线环境可选：指定模型缓存目录export HF_HOME=/data/models # 验证安装python -c "import vllm; print(vllm.__version__)" # Docker 方式（含预编译环境）docker run --gpus all -p 8000:8000 \  vllm/vllm-openai:latest \  --model Qwen/Qwen2.5-7B-Instruct

快速上手：10 分钟跑通 OpenAI 兼容服务

vLLM 最常用的方式是启动 OpenAI 兼容的 HTTP 服务。整套流程分三步：确认模型 ID → 启动服务 → 用 curl 或 OpenAI SDK 调用。服务启动时会先下载模型权重并做预热，7B 模型在 A100/H100 上通常 1–3 分钟即可就绪。

步骤一：在 Hugging Face 上确认目标模型的完整 ID（如 Qwen/Qwen2.5-7B-Instruct）。需要先登录 Hugging Face 账号并同意该模型的许可协议；也可使用本地已下载的模型路径。

步骤二：执行 vllm serve <model_id> 启动服务，默认监听 0.0.0.0:8000。访问官方 OpenAI 接口根路径 /v1 即可查看支持的路由。常用参数：--gpu-memory-utilization 控制显存占用上限，--max-model-len 限制最大上下文长度，--tensor-parallel-size 启用多卡张量并行。

步骤三：用 curl 发起 Chat Completions 请求验证服务。

进阶技巧：客户端直接使用 openai Python SDK，把 base_url 指向 http://localhost:8000/v1 即可无缝接入，无需改业务代码。

如果只做离线批量推理（如离线清洗数据、批量评测），vLLM 也提供 LLM 类 Python API，适合在脚本或 Notebook 中直接调用。示例代码如下：

vllm serve Qwen/Qwen2.5-7B-Instruct \  --gpu-memory-utilization 0.9 \  --max-model-len 8192 # 另开终端验证curl http://localhost:8000/v1/chat/completions \  -H "Content-Type: application/json" \  -d '{"model":"Qwen/Qwen2.5-7B-Instruct",       "messages":[{"role":"user","content":"介绍北京"}]}'

from vllm import LLM, SamplingParams llm = LLM(model="Qwen/Qwen2.5-7B-Instruct")params = SamplingParams(temperature=0.7, max_tokens=256)outputs = llm.generate(["介绍上海", "写一首诗"], params)for output in outputs:    print(output.outputs[0].text)

核心能力详解：4 大支柱

支柱一 · PagedAttention 分页 KV 缓存管理。生成式 LLM 每生成一个 token 都要读取此前所有 token 对应的 KV 缓存（即历史键值向量），传统实现按最大长度预分配连续显存，造成巨大浪费。PagedAttention 将缓存切分为固定大小的内存块（block），按需分配、按块索引，显存碎片率趋近于零。实测显存占用可降低 50% 以上，是 vLLM 吞吐优势的根基。

支柱二 · 连续批处理调度。vLLM 调度器以迭代（iteration）为粒度动态决定每步计算哪些请求：新请求可随时加入、完成的请求立即退出，同一步内不同请求可处于不同生成阶段。传统批处理需要整个 batch 同步开始和结束，而连续批处理让 GPU 始终在处理“有效生成”，吞吐成倍提升。

支柱三 · 执行层优化。包括 CUDA Graph 捕获（将算子启动开销从毫秒级降到微秒级，减少内核启动 overhead）、算子融合、FP8/INT8/INT4/AWQ/GPTQ 等量化支持、投机解码（Speculative Decoding，用小模型草稿+大模型验证的方式加速生成）。这些优化叠加，使单卡 token 吞吐达到每秒数千甚至上万。

支柱四 · OpenAI 兼容服务与多卡扩展。vllm serve 提供 OpenAI 原生接口（/v1/chat/completions、/v1/completions、/v1/embeddings），支持流式输出，兼容 LangChain、LlamaIndex 等生态。多卡部署用 --tensor-parallel-size N 把单模型切分到多卡并行推理；超过单机时可用 --pipeline-parallel-size 做流水线并行。vLLM 还支持 LoRA 多适配器动态加载、多模态模型（如 Qwen2-VL、Llama 3.2 Vision）和结构化输出，可直接接入 RAG、Agent 等上层应用。

生产部署与监控：从上线到运维

部署方式一 · Docker 单机部署：生产环境最推荐用官方 vllm/vllm-openai 镜像，避免源码编译与依赖冲突。注意挂载模型缓存目录以复用已下载权重，并设置 --ipc=host 避免多进程共享内存不足。启动后可用 systemd 或 supervisor 守护进程。

部署方式二 · Kubernetes 集群部署：生产环境通常用 K8s 编排，将 vLLM 封装为 Deployment + Service。关键点是给 Pod 声明 nvidia.com/gpu 资源、设置 --pipeline-parallel-size 跨节点时配合 hostNetwork 或 Headless Service 满足 NCCL 通信需求。前端加 Gateway/Ingress 做负载均衡与鉴权。这种方式适合需要弹性扩缩容的多副本场景。

可观测性：vLLM 内置 Prometheus 指标端点 /metrics，提供 vllm:num_requests_running（正在生成请求数）、vllm:num_requests_waiting（排队请求数）、vllm:generation_tokens_total（生成 token 总数）、vllm:time_to_first_token_seconds（首 token 时延）等关键指标。建议配合 Grafana 监控：首 token 时延（TTFT）上涨说明排队严重，应扩容副本或降低 --max-num-seqs 限制；GPU 利用率长期低于 80% 说明并发不足或模型在等 I/O。生产环境同时开启 --structured-logs（结构化 JSON 日志）和 --otlp-traces-endpoint（OpenTelemetry 链路追踪）以排查单请求瓶颈。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>坑 1：--gpu-memory-utilization 设太高（如 0.98）导致显存 OOM：它只预留了少量不参与缓存池的显存，上下文一长容易触发 OOM，生产建议 0.85–0.92。</li><li>坑 2：max-model-len 改大导致并发骤降：KV 缓存按 max-model-len 预留页数，设得越大单请求占显存越多、并发越低，应小于模型训练上下文长度且匹配真实业务。</li><li>坑 3：用 pip 在无预编译 wheel 的环境安装，源码编译要 20 分钟以上且易失败：优先用官方 Docker 镜像，或加装对应 CUDA 工具链再安装。</li><li>坑 4：多卡 NCCL 通信失败：容器内需 --ipc=host 并确保 GPU 拓扑可见；跨机时配置 NCCL_SOCKET_IFNAME 指向业务网卡。</li><li>坑 5：量化与硬件不匹配：FP8 需 Ada/Hopper 架构（如 L4、H100），旧卡跑 FP8 会回退到慢路径，部署前先确认文档里的硬件支持矩阵。</li></ul>

docker run -d --name vllm-serve --gpus all \  -v /data/models:/root/.cache/huggingface \  -p 8000:8000 --ipc=host \  vllm/vllm-openai:latest \  --model Qwen/Qwen2.5-32B-Instruct \  --tensor-parallel-size 2 \  --gpu-memory-utilization 0.9

版本迭代

vLLM 从 2023 年论文项目起步，v0.6 起完成引擎核心重构，v0.7 引入异步 EngineCore 与多步调度，v0.8 在调度、量化与多模态方面深度打磨，版本节奏约每月一个正式版（截至训练数据，后续可能有更新版本）。

AI 应用场景

常见误区

面试题