1. 为什么 vLLM 的 Online Serving 值得单独写一篇导读vLLM 这个项目从 2023 年开源到现在推理引擎的迭代速度一直很快但真正让它在生产环境站稳脚跟的其实是Online Serving这条链路。很多人第一次接触 vLLM 是从vllm serve这条命令开始的觉得它就是个起个 OpenAI 兼容接口的工具但真到线上跑起来尤其是部署 DeepSeek-V4 这类 MoE 大模型的时候才会发现 EngineCore、调度器、KV Cache 管理、CLI 参数之间的耦合关系远比想象中复杂。这篇导读笔记针对的是 vLLM v0.29 这个版本节点重点放在 Online Serving 的整体架构和实操细节上。适合三类人看第一类是刚把 vLLM 跑起来、准备往生产推的工程师第二类是已经在用 vLLM 但遇到吞吐上不去、首 token 延迟抖动、显存 OOM 这些问题的运维同学第三类是想搞清楚 vLLM 内部 EngineCore 到底怎么调度请求、为什么它比朴素实现快这么多的技术爱好者。我不打算把这篇写成官方文档的复述而是按照我自己部署 DeepSeek-V4、Qwen 系列模型时踩过的坑把 Online Serving 这条链路拆开讲。包括 CLI 参数怎么选、EngineCore 的调度逻辑、KV Cache 的分配策略、多卡张量并行的配置、以及线上常见的排查思路。读完之后你应该能独立完成一次生产级别的 vLLM 部署并且知道每个参数背后的取舍逻辑。2. Online Serving 的整体架构与设计思路2.1 从离线推理到在线服务的范式转变离线推理和在线服务最大的区别在于请求到达模式。离线场景下你手里有一批固定的 prompt可以按 batch 一次性喂进去追求的是整体吞吐在线场景下请求是随机到达的每个请求的输入长度、输出长度都不一样还要保证首 token 延迟TTFT和 token 间延迟TPOT在可接受范围内。vLLM 的 Online Serving 就是为后者设计的。它的核心思路是把请求调度和模型执行解耦前端 API Server 负责接收 HTTP 请求、做 tokenize、管理请求生命周期后端 EngineCore 负责实际的调度和推理。两者之间通过消息队列通信这样前端可以横向扩展后端专注在 GPU 上跑推理。这个设计的好处是显而易见的。你可以起多个 API Server 进程共享一个 EngineCore也可以让 EngineCore 独立部署在一组 GPU 上前端做负载均衡。对于 DeepSeek-V4 这种参数量大、需要多卡张量并行的模型这种解耦几乎是必须的。2.2 EngineCore 在架构中的位置EngineCore 是 vLLM v0.29 里最核心的组件它承担了几件事请求排队、批次组装、KV Cache 分配、模型前向调度、输出回传。你可以把它理解成一个推理操作系统所有的请求都要经过它的调度才能上 GPU。它内部维护了一个调度器Scheduler调度策略直接决定了吞吐和延迟的平衡。v0.29 里默认用的是continuous batching加chunked prefill的组合。continuous batching 的意思是一个 batch 里的请求不需要同时开始同时结束某个请求生成完了立刻腾出位置给新请求GPU 利用率能拉满。chunked prefill 则是把长 prompt 的 prefill 阶段切成小块和 decode 阶段混在一起跑避免长 prompt 把整个 batch 卡住导致其他请求的 TTFT 飙升。这两个机制配合起来是 vLLM 能在高并发下保持低延迟的关键。但代价是调度逻辑复杂参数没调好反而会适得其反后面会细讲。2.3 为什么选择 CLI 作为主要入口vLLM 提供了 Python API 和 CLI 两种启动方式但生产环境里我强烈建议用 CLI。原因有三个一是 CLI 的参数是显式声明的部署脚本里一眼能看出配置方便 review 和版本管理二是 CLI 启动的进程模型更清晰API Server 和 EngineCore 的进程关系是确定的出问题好排查三是 CLI 天然适合容器化Dockerfile 里一行vllm serve就搞定不需要写额外的 Python 启动脚本。v0.29 的 CLI 相比早期版本做了不少改进参数分组更合理--help的输出也清晰多了。但参数数量确实多第一次看容易懵所以下面我会按功能分组来讲。3. 核心参数解析与实操配置3.1 模型加载相关参数启动一个 Online Serving 最基础的命令长这样vllm serve deepseek-ai/DeepSeek-V4 \ --tensor-parallel-size 8 \ --dtype bfloat16 \ --max-model-len 32768 \ --gpu-memory-utilization 0.92 \ --port 8000这里几个参数值得展开说。--tensor-parallel-size是张量并行的卡数DeepSeek-V4 这种量级的模型单卡肯定放不下需要按 hidden dimension 切分到多卡。选 8 还是 4 取决于你的卡型和显存一般原则是能放下就尽量少切因为张量并行的通信开销随卡数增加而上升。8 卡 A100/H100 跑 DeepSeek-V4 是比较常见的配置。--dtype建议用bfloat16除非你的卡不支持比如 V100 就只能用 float16。bfloat16 的动态范围更大长序列推理时不容易溢出实测下来数值稳定性明显好于 float16。--max-model-len是模型支持的最大上下文长度。这个值直接影响 KV Cache 的预分配大小设太大浪费显存设太小长请求会被拒绝。我的经验是按实际业务的最长输入来设比如你的场景最长也就 16K那就设 16384没必要跟风设 128K。--gpu-memory-utilization控制 vLLM 能用多少比例的显存。默认 0.9我一般调到 0.92 到 0.95 之间。这个值不是越高越好留一点余量给 CUDA context 和临时 buffer否则容易在峰值时 OOM。0.95 以上就要小心了除非你非常确定显存曲线。3.2 调度与批处理参数调度相关的参数是调优的重灾区我列一个对照表参数默认值作用调优建议--max-num-seqs256单批次最大请求数高并发场景可提到 512但要看显存--max-num-batched-tokens自动单批次最大 token 数长 prompt 场景适当调大--enable-chunked-prefill视版本开启分块 prefill长输入必开--max-num-partial-prefills1并发 partial prefill 数混合负载可调到 2-4--scheduling-policyfcfs调度策略延迟敏感用 fcfs吞吐优先可试 priority--max-num-seqs是最影响吞吐的参数之一。它决定了同时有多少个请求在 GPU 上跑。设太小 GPU 吃不饱设太大 KV Cache 不够用会触发抢占preemption反而拖慢整体。我的做法是从 256 起步压测时逐步往上加观察 GPU 利用率和 preemption 次数找到拐点。--max-num-batched-tokens控制一个 batch 里所有请求的 token 总数上限。这个值和--max-num-seqs是联动的实际生效的是两者中先触发的那个。长 prompt 场景下这个参数往往是瓶颈需要调大但调大意味着单次前向的计算量增加TTFT 会变长要权衡。3.3 KV Cache 与显存管理KV Cache 是 vLLM 的看家本领 PagedAttention 的载体。v0.29 里 KV Cache 的管理更加精细了支持按 block 分配block size 默认 16。这个值一般不用改除非你有特殊需求。显存分配的大致逻辑是这样的vLLM 启动时会先加载模型权重然后根据--gpu-memory-utilization算出剩余可用显存全部拿来做 KV Cache。所以你能支持的并发数 KV Cache 总容量 / 单个请求的 KV 占用。单个请求的 KV 占用可以粗略估算KV bytes per token 2 * num_layers * num_kv_heads * head_dim * dtype_bytes以 DeepSeek-V4 为例假设 61 层、GQA 下 num_kv_heads 是 8、head_dim 128、bfloat16 占 2 字节那么每 token 的 KV 占用大约是2 * 61 * 8 * 128 * 2 250KB。一个 8K 上下文的请求就要占 2GB 左右。这个数字很吓人所以长上下文场景下并发数上不去是正常的不是配置问题。提示如果你的业务是长上下文为主考虑开启--kv-cache-dtype fp8能把 KV Cache 显存砍一半代价是轻微的质量损失。实测在多数任务上感知不明显。4. 完整部署流程与关键环节实现4.1 环境准备与依赖安装先说环境。CUDA 版本建议 12.4 以上v0.29 对 CUDA 12.8 的支持已经比较成熟新卡比如 H100、H200建议直接上 12.8。Python 版本 3.10 到 3.12 都行3.11 是比较稳的选择。安装 vLLM 有两种方式pip 和源码编译。生产环境我建议用 pip 装 release 版本稳定pip install vllm0.29.0如果你需要特定 commit 或者要改源码那就源码编译git clone https://github.com/vllm-project/vllm.git cd vllm git checkout v0.29.0 pip install -e .源码编译的好处是可以针对你的卡型做优化比如开启 FlashAttention 的特定 kernel。但编译时间长依赖多第一次搞可能要折腾一两个小时。注意Windows 上原生跑 vLLM 一直是个痛点社区版支持有限。生产环境强烈建议用 LinuxWindows 只适合本地体验。如果非要在 Windows 上跑WSL2 是相对靠谱的方案但性能有损耗。4.2 启动服务与验证环境好了之后启动服务。我习惯把参数写在一个 shell 脚本里方便复用#!/bin/bash MODEL_PATHdeepseek-ai/DeepSeek-V4 vllm serve $MODEL_PATH \ --tensor-parallel-size 8 \ --dtype bfloat16 \ --max-model-len 32768 \ --gpu-memory-utilization 0.92 \ --max-num-seqs 256 \ --enable-chunked-prefill \ --port 8000 \ --host 0.0.0.0 \ --api-key your-secret-key \ --served-model-name deepseek-v4启动过程会打印一堆日志重点看这几行模型加载耗时、KV Cache 分配了多少 block、支持的 max concurrency。如果 KV Cache 的 block 数很少比如几百说明显存不够要么减--max-model-len要么加卡。服务起来之后用 curl 验证curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer your-secret-key \ -d { model: deepseek-v4, messages: [{role: user, content: 你好}], max_tokens: 100 }能正常返回就说明链路通了。如果报错先看服务端日志再看是不是 API key 或者 model name 对不上。4.3 压测与性能基线部署完一定要压测不然你不知道这套配置能扛多少并发。我一般用vllm自带的 benchmark 脚本或者用locust、wrk这类工具打 HTTP 接口。压测关注三个指标吞吐tokens/s、TTFT首 token 延迟、TPOTtoken 间延迟。这三个指标是互相制约的吞吐上去了延迟往往就上去了。你要根据业务场景定优先级如果是聊天场景TTFT 更重要如果是批量生成吞吐更重要。我实测下来8 卡 H100 跑 DeepSeek-V4在 32K 上下文、并发 64 的情况下吞吐大概能到 2000 tokens/s 左右TTFT 在 500ms 到 1s 之间。这个数字仅供参考实际会受 prompt 长度分布、输出长度分布影响很大。压测的时候要盯着 GPU 显存和利用率。如果显存一直贴着上限说明 KV Cache 吃紧preemption 会频繁发生延迟抖动会很大。这时候要么降并发要么加卡。5. 常见问题与排查技巧实录5.1 启动阶段常见报错报错一CUDA out of memory这是最常见的。原因通常是--gpu-memory-utilization设太高或者--max-model-len设太大导致 KV Cache 预分配过多。解决思路是先把--gpu-memory-utilization降到 0.85 试试能起来再逐步往上加。如果降了还不行那就是模型本身放不下得加卡或者用量化版本。报错二tensor parallel size 不匹配多卡部署时--tensor-parallel-size必须等于实际使用的 GPU 数而且这些 GPU 要能被 vLLM 看到。用CUDA_VISIBLE_DEVICES指定卡的时候要小心别指定了 8 张卡但--tensor-parallel-size写了 4会报错。报错三模型权重加载失败多半是网络问题或者模型路径不对。国内环境拉 HuggingFace 的模型经常超时建议提前用huggingface-cli download把模型拉到本地然后用本地路径启动。5.2 运行阶段性能问题问题一吞吐上不去GPU 利用率低先看是不是--max-num-seqs设太小请求排队了。再看是不是 prefill 和 decode 没混起来如果--enable-chunked-prefill没开长 prompt 会把 batch 卡住。还有一种可能是请求的输入输出长度分布太极端比如全是超长输入那 GPU 时间都花在 prefill 上了吞吐自然低。问题二TTFT 抖动大TTFT 抖动通常和调度有关。如果开了 chunked prefill 但--max-num-partial-prefills设得太小长 prompt 会阻塞其他请求。可以试着调大这个值让多个 partial prefill 并发。另外如果 preemption 频繁也会导致 TTFT 抖动这时候要降并发或者加 KV Cache。问题三长上下文请求被拒绝检查--max-model-len是不是设小了。另外即使--max-model-len够大如果 KV Cache 不够长请求也会被拒绝或者排队很久。长上下文场景建议单独部署一套服务配置专门优化。5.3 排查速查表现象可能原因排查方向启动 OOM显存利用率过高/模型太大降 utilization加卡量化吞吐低并发不足/prefill 阻塞调 max-num-seqs开 chunked prefillTTFT 抖动preemption/调度策略降并发调 partial prefill 数请求被拒max-model-len 或 KV 不足调大 max-model-len加显存输出乱码dtype 不匹配/权重损坏换 bfloat16重新下载权重实操心得线上服务一定要开监控重点盯 GPU 显存、GPU 利用率、请求队列长度、preemption 次数这四个指标。前两个反映资源够不够后两个反映调度健不健康。我见过太多案例是显存悄悄涨上去某天流量高峰直接 OOM 挂掉有监控就能提前发现。6. 多卡与分布式部署的进阶配置6.1 张量并行与流水线并行的选择单机多卡用张量并行TP就够了跨机才需要考虑流水线并行PP。TP 的通信量大对 NVLink 依赖强所以同一台机器内的卡最好用 NVLink 互联。如果卡之间只有 PCIeTP 的扩展效率会打折扣这时候可以考虑 TP 加 PP 的组合。vLLM v0.29 对 PP 的支持已经比较完善启动时加--pipeline-parallel-size就行。但 PP 会引入 pipeline bubble吞吐不一定比纯 TP 好除非你的模型大到单机放不下。我的建议是能单机 TP 解决就别上 PP。6.2 多实例部署与负载均衡如果单实例扛不住流量可以起多个 vLLM 实例前面挂一个负载均衡。每个实例用不同的端口Nginx 或者 HAProxy 做转发。这种方案的好处是隔离性好一个实例挂了不影响其他坏处是显存利用率低因为每个实例都要独立加载一份模型权重。对于超大模型多实例意味着要多份权重显存成本高。这时候可以考虑用 vLLM 的multi-node部署把模型切到多台机器上对外还是一个服务。配置起来复杂一些需要配 Ray 集群但资源利用率高。6.3 量化部署的取舍显存不够的时候量化是最直接的方案。vLLM 支持 AWQ、GPTQ、FP8 等多种量化格式。FP8 是 H100 之后的新卡才支持精度损失小推荐优先考虑。AWQ 和 GPTQ 是权重量化4bit 能把显存砍到原来的四分之一但质量损失要看具体模型和任务。我的经验是能上 FP8 就上 FP8不行再考虑 4bit 量化。4bit 量化在代码生成、数学推理这类任务上质量损失比较明显聊天场景相对好一些。量化之前一定要做质量评估别为了省显存把效果搞崩了。7. 我个人的一些实操体会部署 vLLM 这几年最大的感受是参数没有万能配置只有适合你场景的配置。网上抄来的参数直接用到生产十有八九要出问题。因为每个业务的请求模式、长度分布、延迟要求都不一样必须自己压测、自己调。另外一个体会是监控比调优更重要。调优是锦上添花监控是保命。线上服务最怕的不是性能不够而是悄无声息地劣化等到用户投诉才发现。把关键指标监控起来设置告警阈值比事后救火强太多。最后分享一个小技巧vLLM 的日志级别可以调--disable-log-requests能关掉每个请求的日志高并发下能省不少 IO。但排查问题的时候记得打开不然啥都看不到。日志和性能之间要按场景权衡。这个内容后续还可以往几个方向扩展一是结合具体的业务场景做端到端的性能优化案例二是深入 PagedAttention 的实现细节讲讲 block 管理和内存碎片三是多机多卡的部署实战包括 Ray 集群的配置和调优。有机会再单独写。