vLLM 是目前最流行的高吞吐大语言模型LLM推理服务引擎之一核心创新 PagedAttention 解决了 KV Cache 显存碎片化问题配合连续批处理Continuous Batching把 GPU 利用率拉到接近上限并通过 OpenAI 兼容 API 让任何 LLM 应用一行代码接入。1. 背景为什么需要 vLLM1.1 LLM 推理的三座大山把一个大模型跑起来不难难的是跑得快、跑得多、跑得省。LLM 推理天然有三个结构性难题显存Transformer 推理时每生成一个 token都要把历史的 Key/Value 缓存KV Cache留在显存里。上下文越长KV Cache 越大。比如 7B 模型 fp16 权重约 14GB而 8192 上下文的 KV Cache 也可能占掉 10GB 的量级。传统实现按“最大可能长度”一次性预留连续显存请求实际没用到那么长时预留即浪费多个请求并发时显存碎片化严重。吞吐解码是逐 token 自回归每个 step 只算一个 token计算强度低、访存密度高。单条请求推理时 GPU 算力利用率往往只有个位数百分比把多条请求打包成 batch 一起解码才是吃满 GPU 的关键。调度请求到达时间不均、长度参差。朴素做法是“攒一批再跑”先完成的请求要空等批尾称为 wave scheduling长 prompt 的 prefill 又会堵住所有正在解码的请求。1.2 vLLM 是什么vLLM 源于 UC BerkeleyLMSYS / Sky Computing Lab2022 年的论文Efficient Memory Management for Large Language Model Serving with PagedAttention后发展为独立开源项目Apache-2.0并快速成为 LLM 推理服务的事实标准之一。定位面向生产环境的 LLM 推理与 serving 引擎——不是训练框架也不是通用推理框架而是“把已经训练好的模型以最高吞吐、最低显存占用、标准协议对外服务”的引擎。形态自带 OpenAI 兼容 HTTP 服务vllm serve、离线批量推理 Python APILLM/AsyncLLM、可编程引擎LLMEngine。与同生态的横向对比引擎侧重点部署形态vLLM高吞吐 serving、PagedAttention、连续批处理GPU、中心化服务llama.cpp本地/边缘、CPU 优先、GGUF 单文件单机、嵌入式ONNX Runtime通用模型推理CNN/Transformer 等多后端、低延迟HuggingFace TGI生产 servingGPU 服务TensorRT-LLM极致性能、需编译优化GPU 服务SGLang结构化生成 调度优化GPU 服务2. 核心概念2.1 PagedAttention分页 KV CachePagedAttention 是 vLLM 的灵魂思想直接借自操作系统的虚拟内存分页传统实现为每个请求的 KV Cache连续预留一段显存按 max 长度导致内部碎片 预留浪费。vLLM 把 KV Cache 切成固定大小的块block默认 16 个 token每个请求维护一张“块表”block table把逻辑上连续的 token 序列映射到物理上分散的显存块。好处内存利用率大幅提升论文数据比 HF 实现吞吐高 1424 倍、显存利用接近极限实际场景因模型和请求而异通常吞吐提升 210 倍是常见量级。前缀共享多个请求共用同一段前缀如 system prompt、few-shot 示例时块通过 Copy-on-Write 共享不用重复存。支持并行采样同一 prompt 生成 n 条时天然复用 KV。2.2 连续批处理Continuous Batching传统 batch 是“请求到达时成批、批尾一起结束”的静态批先完成的请求空等新请求进不来。vLLM 在每个解码迭代动态决定 batch 成员某序列输出 EOS 或达到 max_tokens 立即腾出槽位新请求随时插入当前迭代。这样 GPU 每个 step 都满载吞吐接近理论上限。2.3 自动前缀缓存Prefix Caching相同 token 前缀system prompt、RAG 指令、few-shot 样例的 KV 块按内容哈希后缓存复用。命中时跳过 prefill直接进入 decode显著降低首 token 延迟TTFT并省显存。vLLM 的 cache_prefix_hit_rate 指标直接反映命中率。2.4 Chunked Prefill长 prompt 的 prefill 计算量很大若一次算完会阻塞其他请求的 decode队头阻塞。vLLM 把 prefill 切成小块与 decode 交错执行让延迟更平滑。代价是极端场景吞吐略降、TTFT 略升适合长文档/长上下文业务。2.5 投机解码Speculative Decoding用一个小 draft 模型一次性快速生成 k 个候选 token再由目标大模型并行验证接受则一次前进 k 步。典型加速 2~3 倍取决于 draft 模型质量与接受率draft 模型过大或不匹配反而会变慢。2.6 量化vLLM 支持 AWQ / GPTQ / SqueezeLLM / FP8 等多种量化还有 GGUF 的有限支持。量化后显存减半、吞吐提升但每种量化格式都有硬件 kernel 要求见第 6 章坑 4。2.7 分布式推理张量并行TP把单层权重切到多卡all-reduce 同步--tensor-parallel-size。流水线并行PP按层切分卡间流水。专家并行EPMoE 模型Qwen-MoE、DeepSeek 等把专家路由到不同卡。数据并行DP多份模型副本服务不同请求。2.8 OpenAI 兼容协议vLLM 服务端实现 OpenAI API 子集/v1/chat/completions、/v1/completions、/v1/embeddings、/v1/models另有 /health、/metrics、/tokenize。这意味着 openai SDK、LangChain 等客户端改一行 base_url 即可接入。3. API 说明3.1 CLIvllm servevllm serve 是官方推荐的启动方式替代早期的 python -m vllm.entrypoints.openai.api_server。核心参数参数作用示例值--model模型名或本地路径HF HubQwen/Qwen2.5-7B-Instruct--served-model-name对外暴露的模型名客户端 model 字段qwen-7b--tensor-parallel-size张量并行卡数2--max-model-len最大上下文长度决定 KV 预算8192--gpu-memory-utilizationGPU 显存利用率上限默认 0.90.85--max-num-seqs单 GPU 最大并发序列数默认 25664--max-num-batched-tokens单迭代最大 token 数配合 chunked prefill4096--enable-prefix-caching开启自动前缀缓存—--enable-chunked-prefill开启分块 prefill—--quantization量化格式awq / gptq / fp8--dtype推理精度auto / half / bfloat16--enforce-eager关闭 CUDA Graph调试用—--kv-cache-dtypeKV Cache 量化fp8--speculative-model / --num-speculative-tokens投机解码 draft 模型与步数--speculative-model Qwen/Qwen2.5-0.5B-Instruct --num-speculative-tokens 5--trust-remote-code允许模型仓自定义代码—--task任务类型auto / generate / embedding / classify--api-key服务端 API Key—--host / --port监听地址0.0.0.0 / 8000--download-dir模型缓存目录/data/models3.2 Python APILLM离线批量推理from vllm import LLM, SamplingParams llm LLM( modelQwen/Qwen2.5-7B-Instruct, gpu_memory_utilization0.85, # 显存预算 max_model_len8192, enable_prefix_cachingTrue, ) params SamplingParams( temperature0.2, top_p0.9, max_tokens512, stop[\n\n], # 停止符 ) results llm.generate(prompts, params) # prompts: str 或 list[str] for r in results: print(r.outputs[0].text) # CompletionOutput print(r.prompt, r.outputs[0].finish_reason)SamplingParams 核心字段字段含义temperature / top_p / top_k / min_p采样参数presence_penalty / frequency_penalty / repetition_penalty多样性惩罚max_tokens最大生成 token 数stop / stop_token_ids停止条件ignore_eos忽略 EOS 继续生成n / best_of并行采样条数use_beam_search束搜索seed固定随机种子可复现logprobs / prompt_logprobs输出/输入对数概率AsyncLLM异步并发适合在线服务中做“请求级并发”用法与 LLM 类似但方法是异步的from vllm import AsyncLLM, SamplingParams async def main(): llm AsyncLLM(modelQwen/Qwen2.5-7B-Instruct, gpu_memory_utilization0.85) out await llm.generate( 用一句话解释 PagedAttention 为什么省显存。, SamplingParams(max_tokens128), ) print(out.outputs[0].text) if __name__ __main__: import asyncio asyncio.run(main())注AsyncLLM 的接口在近几个版本持续演进新增 aclose 等正式接入前以当前版本官方文档为准。更底层的 LLMEngine / EngineArgs 面向自定义调度场景本文不展开。3.3 OpenAI 兼容 API 参数映射OpenAI 字段vLLM 行为model必须是 --served-model-name 指定的名字messageschat 模板自动应用可 --chat-template 覆盖temperature / top_p / max_tokens / stop / n透传至采样stream支持 SSE 流式logprobs支持top_logprobs 需额外配置response_format{type: json_object}支持引导式 JSON 输出tools / tool_choice需 --enable-auto-tool-choice --tool-call-parser4. 详细使用说明4.1 安装# Linux NVIDIA GPU官方主路径 pip install vllm # Docker推荐生产使用 docker pull vllm/vllm-openai:latest注意 pip wheel 与 CUDA 版本配套Windows 原生支持有限建议 WSL2 或 Docker Desktop NVIDIA Container Toolkit见坑 11。首次启动会从 HuggingFace 下载模型内网环境提前下载到 --download-dir 或 HF_HOME。4.2 离线批量推理from vllm import LLM, SamplingParams llm LLM(modelQwen/Qwen2.5-7B-Instruct, gpu_memory_utilization0.85) prompts [ 请用一句话解释什么是 KV Cache。, 以下设备日志中出现了什么异常请列出可能原因并给出排查建议。\n日志2026-10-12 03:15:22 ERROR fanuc[01] alarm 4015 spindle load 128%\n, ] params SamplingParams(temperature0.1, max_tokens256) for req in llm.generate(prompts, params): print(f[{req.prompt[:20]}...] - {req.outputs[0].text})离线批处理场景日报批量总结、历史日志分析应尽量一次传入多组 prompt让连续批处理把 GPU 吃满。4.3 流式输出vllm serve Qwen/Qwen2.5-7B-Instruct --served-model-name qwen-7b --port 8000客户端用 openai SDK 即可from openai import OpenAI client OpenAI(base_urlhttp://127.0.0.1:8000/v1, api_keyEMPTY) resp client.chat.completions.create( modelqwen-7b, messages[{role: user, content: 解释连续批处理}], streamTrue, ) for chunk in resp: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end)4.4 多卡 前缀缓存 分块 prefill 的生产启动vllm serve Qwen/Qwen2.5-14B-Instruct \ --served-model-name qwen-14b \ --tensor-parallel-size 2 \ --gpu-memory-utilization 0.90 \ --max-model-len 16384 \ --max-num-seqs 128 \ --enable-prefix-caching \ --enable-chunked-prefill \ --host 0.0.0.0 --port 80004.5 Docker 部署docker run --runtime nvidia --gpus all \ -v ~/.cache/huggingface:/root/.cache/huggingface \ -p 8000:8000 \ vllm/vllm-openai:latest \ --model Qwen/Qwen2.5-7B-Instruct \ --served-model-name qwen-7b4.6 工业数采场景RAG 设备日志分析链路与既有篇目无缝衔接典型链路CNC/PLC → 采集网关 → Kafka(104/143) → TDengine(110) ↓ 离线日志/工艺数据 → FAISS(131) 向量化索引 ↓ 业务应用 → FAISS 检索 → vLLM(本篇) 生成回答 ↓ 结果回流 Kafka / 展示层WebSocket 141 / Matplotlib 142工艺知识问答把设备手册、工艺卡、历史维修记录切片向量化进 FAISS用户提问先检索 top-k 再拼进 prompt 交给 vLLM。设备日志异常分析批量日志走 LLM.generate 离线总结结果写回 TDengine。指标自然语言查询FastAPI96 篇/ Gin97 篇业务服务内用 openai SDK 调 vLLM把“最近 1 小时三号机主轴负载超 120% 的次数”这类自然语言转成查询入口可加 Nginx140 篇做限流与 TLS 终结。监控/metrics 直接接 Prometheus136 篇 Grafana。5. 底层实现剖析5.1 PagedAttention 数据路径KV Cache 以固定大小块管理--block-size默认 16 tokenBlockManager 维护逻辑块 → 物理块的映射表。每步 decode 只需按块表把 KV 写入分散的物理块块表随序列增长动态追加。前缀共享时多个序列的块表指向同一物理块并加引用计数需要改写时才触发 Copy-on-Write 复制。并行采样n1共享同一前缀是 PagedAttention 收益最大的场景之一。5.2 调度器与连续批处理vLLM 的 Scheduler 维护三类序列队列含义running正在参与当前迭代解码的序列waiting等待进入的序列含新请求与 prefillswapped被抢占后换出到 CPU 的序列每个迭代先处理 waiting 中的 prefill受 max_num_batched_tokens 约束再对 running 集体 decode序列 finish 立即释放槽位新请求插入下一迭代。显存不足时按优先级抢占通常先抢最早到达的被抢占序列换出到 CPU swap 空间无 swap 则丢弃其 KV、之后重新计算recompute。这就是 vllm:num_requests_running/waiting/swapped 三个指标背后的机制。5.3 KV Cache 显存规划gpu_memory_utilization默认 0.9划定总预算模型权重 激活 KV Cache CUDA Graph 预留。KV Cache 分块池在启动时一次性按预算分配若 max_model_len 过大导致预算内放不下任何块会报 No available memory for the cache blocks —— 这时要调小 max_model_len 或调大 gpu_memory_utilization。显存预算公式直觉KV 预算 ≈ 显存 × 利用率 − 权重 − 激活 − CUDA Graph。5.4 前缀缓存实现每个前缀块以 token id 序列哈希为 key全局 PrefixCachingBlockAllocator 用 LRU 管理缓存块。命中块直接复用物理显存未命中的新块继续分配请求结束时未共享的缓存块按策略保留一段时间供后续请求命中。命中率取决于前缀稳定性system prompt 固定、few-shot 固定、RAG 指令模板固定则命中率高前缀里混入时间戳/随机数会显著拉低命中率。5.5 CUDA Graph为消除每 step 的 kernel launch 开销vLLM 默认把模型 forward 捕获为 CUDA Graphdecode 阶段直接重放。首次请求会触发 graph 捕获慢、显存占用上升--enforce-eager 可关闭调试/兼容用。5.6 服务端架构核心是 LLMEngine调度 模型执行外层 API ServerFastAPI 实现只做协议翻译。新版 vLLM 将引擎拆为独立 EngineCore 进程/线程与 API Server 通过异步消息通信避免 GIL 与调度抖动。/metrics 由 Prometheus 客户端暴露vllm:num_requests_running、vllm:num_requests_waiting、vllm:num_requests_swapped、vllm:cache_prefix_hit_rate、vllm:gpu_cache_usage_perc、vllm:generation_tokens_total、vllm:prompt_tokens_total 等。6. 常错点 / 坑24 条坑现象 / 后果对策1显存预算与 max_model_len 失衡启动报 No available memory for the cache blocks调小 max_model_len 或调大 gpu_memory_utilization2TP 卡数不匹配启动失败或显存翻倍--tensor-parallel-size ≤ 实际 GPU 数且能整除3忘 --served-model-name客户端 model 字段用错名报 404服务端显式指定客户端用同名4量化 kernel 与硬件不匹配报错或回退极慢AWQ/GPTQ 适合多数卡FP8 需 Ada/Hopper 及以上5GGUF 与 safetensors 混用加载失败或行为异常vLLM 主路径用 HF safetensorsGGUF 支持有限K-quants 等格式先转6未设 stop / max_tokens无限生成占满吞吐业务侧必设 max_tokens需要时配 stop7chat 模型裸文本直发输出风格失控chat 模型走 messages 默认/自定义 chat template8前缀不稳定cache_prefix_hit_rate 低、TTFT 高固定 system prompt 结构去掉时间戳/随机串9并发设太大大量抢占/换出吞吐反降max-num-seqs 与显存匹配客户端限流10流式客户端超时长输出连接断开客户端合理超时 服务端 stream 心跳11Windows 原生跑各种环境报错用 WSL2 / Docker NVIDIA Container Toolkit12CUDA/cuDNN 版本不配套CUDA error: no kernel image按官方 wheel 的 CUDA 版本装环境容器化规避13模型下载慢/离线环境启动卡在下载预下载到 --download-dir / HF_HOME离线内网部署14chat 与 embedding 任务混用端点行为错乱--task generate / --task embedding 按需指定15多卡 NCCL 通信失败all-reduce 卡死/超时检查防火墙、NCCL_P2P_DISABLE、容器共享内存16长 prompt 未开 chunked prefill一次长请求卡住全部 decode开 --enable-chunked-prefill17投机解码 draft 选错反而变慢draft 模型 vocab 一致、尺寸小、接受率高实测对比18一次 generate 塞太多 prompt排队 抢占按显存分批或用服务端排队指标观测19忘 --trust-remote-code部分模型加载报错模型仓有自定义代码时显式开启注意安全审计20服务无预热首个请求含权重加载graph 捕获极慢启动后发典型请求预热再放流量21监控缺失OOM/排队/命中率不可见接 /metrics Prometheus/Grafana22response_formatjson_object 理解偏差JSON 不合法属引导解码guided decoding需在 prompt 中说明输出 JSON 结构23模型路径含中文/特殊字符加载失败用英文路径、绝对路径24升级 vLLM 大版本参数/接口不兼容升级前读 release notes锁版本部署7. 性能优化与工程实践清单12 条显存预算权重 激活 KV Cache CUDA Graph 四部分统筹gpu_memory_utilization 0.85~0.95。连续批处理参数max-num-seqs、max-num-batched-tokens 与显存匹配避免抢占风暴。开启前缀缓存固定 system prompt命中率目标 50%。Chunked prefill长文档/长上下文业务必开平滑 TTFT。投机解码为生成类高并发场景配置小 draft 模型实测加速比后再上。量化选型Ampere 用 AWQ/GPTQAda/Hopper 用 FP8显存紧张优先量化。张量并行单卡放不下或要更高吞吐时用 TPMoE 模型用 EP。预热启动后打几轮典型请求完成 CUDA Graph 捕获与显存稳定。离线批量日报/批量总结用 LLM.generate 一次喂多 prompt。在线流式交互场景开 stream降低首包感知延迟。监控running/waiting/swapped、cache_prefix_hit_rate、gpu_cache_usage_perc 三组指标必盯。链路编排FastAPI/Gin 业务层 → Nginx 入口 → vLLM 服务结果回流 Kafka/TDengine 形成闭环。8. 总结五要点PagedAttention 是核心KV Cache 分页 块表解决显存碎片与浪费是 vLLM 吞吐优势的根基。连续批处理是引擎迭代级动态调度让 GPU 每个 step 满载。前缀缓存/Chunked Prefill/投机解码是加速器分别优化 TTFT、延迟稳定性和生成速度。OpenAI 兼容是生态一行 base_url 接入一切 LLM 应用降低集成成本。选型分层边缘/单机/CPU 用 llama.cppGGUF中心 GPU 高吞吐服务用 vLLMsafetensors 量化与 FAISS/FastAPI/Kafka/TDengine/Prometheus 组合成完整工业数采 AI 链路。9. FAQ 速查12 条问题速答1vLLM 和 llama.cpp 怎么选数据不出厂/单机/CPU → llama.cppGPU 高吞吐 API 服务 → vLLM2显存不足先调什么先降 max-model-len再降 max-num-seqs最后考虑量化3为什么第一请求特别慢权重加载 CUDA Graph 捕获用预热请求解决4怎么提高前缀缓存命中率固定 system prompt/few-shot避免前缀含动态内容5支持中文模型吗支持选对 tokenizer 与 chat templateQwen 系开箱即用6并发上不去怎么办检查 running/swapped 指标调 max-num-seqs 与客户端限流7服务端挂多个模型多个 vllm serve 进程/容器前端路由8支持 embedding 吗支持--task embedding/v1/embeddings9多卡怎么分单模型用 --tensor-parallel-size多副本用多个进程10离线批量怎么最快LLM.generate 一次喂多 prompt吃满连续批处理11如何接 Prometheus/metrics 端点直接 scrape指标名带 vllm: 前缀12Windows 能跑吗官方主支持 LinuxWindows 建议 WSL2/Docker
vLLM 是目前最流行的高吞吐大语言模型LLM推理服务引擎之一核心创新 PagedAttention 解决了 KV Cache 显存碎片化问题配合连续批处理Continuous Batching把 GPU 利用率拉到接近上限并通过 OpenAI 兼容 API 让任何 LLM 应用一行代码接入。1. 背景为什么需要 vLLM1.1 LLM 推理的三座大山把一个大模型跑起来不难难的是跑得快、跑得多、跑得省。LLM 推理天然有三个结构性难题显存Transformer 推理时每生成一个 token都要把历史的 Key/Value 缓存KV Cache留在显存里。上下文越长KV Cache 越大。比如 7B 模型 fp16 权重约 14GB而 8192 上下文的 KV Cache 也可能占掉 10GB 的量级。传统实现按“最大可能长度”一次性预留连续显存请求实际没用到那么长时预留即浪费多个请求并发时显存碎片化严重。吞吐解码是逐 token 自回归每个 step 只算一个 token计算强度低、访存密度高。单条请求推理时 GPU 算力利用率往往只有个位数百分比把多条请求打包成 batch 一起解码才是吃满 GPU 的关键。调度请求到达时间不均、长度参差。朴素做法是“攒一批再跑”先完成的请求要空等批尾称为 wave scheduling长 prompt 的 prefill 又会堵住所有正在解码的请求。1.2 vLLM 是什么vLLM 源于 UC BerkeleyLMSYS / Sky Computing Lab2022 年的论文Efficient Memory Management for Large Language Model Serving with PagedAttention后发展为独立开源项目Apache-2.0并快速成为 LLM 推理服务的事实标准之一。定位面向生产环境的 LLM 推理与 serving 引擎——不是训练框架也不是通用推理框架而是“把已经训练好的模型以最高吞吐、最低显存占用、标准协议对外服务”的引擎。形态自带 OpenAI 兼容 HTTP 服务vllm serve、离线批量推理 Python APILLM/AsyncLLM、可编程引擎LLMEngine。与同生态的横向对比引擎侧重点部署形态vLLM高吞吐 serving、PagedAttention、连续批处理GPU、中心化服务llama.cpp本地/边缘、CPU 优先、GGUF 单文件单机、嵌入式ONNX Runtime通用模型推理CNN/Transformer 等多后端、低延迟HuggingFace TGI生产 servingGPU 服务TensorRT-LLM极致性能、需编译优化GPU 服务SGLang结构化生成 调度优化GPU 服务2. 核心概念2.1 PagedAttention分页 KV CachePagedAttention 是 vLLM 的灵魂思想直接借自操作系统的虚拟内存分页传统实现为每个请求的 KV Cache连续预留一段显存按 max 长度导致内部碎片 预留浪费。vLLM 把 KV Cache 切成固定大小的块block默认 16 个 token每个请求维护一张“块表”block table把逻辑上连续的 token 序列映射到物理上分散的显存块。好处内存利用率大幅提升论文数据比 HF 实现吞吐高 1424 倍、显存利用接近极限实际场景因模型和请求而异通常吞吐提升 210 倍是常见量级。前缀共享多个请求共用同一段前缀如 system prompt、few-shot 示例时块通过 Copy-on-Write 共享不用重复存。支持并行采样同一 prompt 生成 n 条时天然复用 KV。2.2 连续批处理Continuous Batching传统 batch 是“请求到达时成批、批尾一起结束”的静态批先完成的请求空等新请求进不来。vLLM 在每个解码迭代动态决定 batch 成员某序列输出 EOS 或达到 max_tokens 立即腾出槽位新请求随时插入当前迭代。这样 GPU 每个 step 都满载吞吐接近理论上限。2.3 自动前缀缓存Prefix Caching相同 token 前缀system prompt、RAG 指令、few-shot 样例的 KV 块按内容哈希后缓存复用。命中时跳过 prefill直接进入 decode显著降低首 token 延迟TTFT并省显存。vLLM 的 cache_prefix_hit_rate 指标直接反映命中率。2.4 Chunked Prefill长 prompt 的 prefill 计算量很大若一次算完会阻塞其他请求的 decode队头阻塞。vLLM 把 prefill 切成小块与 decode 交错执行让延迟更平滑。代价是极端场景吞吐略降、TTFT 略升适合长文档/长上下文业务。2.5 投机解码Speculative Decoding用一个小 draft 模型一次性快速生成 k 个候选 token再由目标大模型并行验证接受则一次前进 k 步。典型加速 2~3 倍取决于 draft 模型质量与接受率draft 模型过大或不匹配反而会变慢。2.6 量化vLLM 支持 AWQ / GPTQ / SqueezeLLM / FP8 等多种量化还有 GGUF 的有限支持。量化后显存减半、吞吐提升但每种量化格式都有硬件 kernel 要求见第 6 章坑 4。2.7 分布式推理张量并行TP把单层权重切到多卡all-reduce 同步--tensor-parallel-size。流水线并行PP按层切分卡间流水。专家并行EPMoE 模型Qwen-MoE、DeepSeek 等把专家路由到不同卡。数据并行DP多份模型副本服务不同请求。2.8 OpenAI 兼容协议vLLM 服务端实现 OpenAI API 子集/v1/chat/completions、/v1/completions、/v1/embeddings、/v1/models另有 /health、/metrics、/tokenize。这意味着 openai SDK、LangChain 等客户端改一行 base_url 即可接入。3. API 说明3.1 CLIvllm servevllm serve 是官方推荐的启动方式替代早期的 python -m vllm.entrypoints.openai.api_server。核心参数参数作用示例值--model模型名或本地路径HF HubQwen/Qwen2.5-7B-Instruct--served-model-name对外暴露的模型名客户端 model 字段qwen-7b--tensor-parallel-size张量并行卡数2--max-model-len最大上下文长度决定 KV 预算8192--gpu-memory-utilizationGPU 显存利用率上限默认 0.90.85--max-num-seqs单 GPU 最大并发序列数默认 25664--max-num-batched-tokens单迭代最大 token 数配合 chunked prefill4096--enable-prefix-caching开启自动前缀缓存—--enable-chunked-prefill开启分块 prefill—--quantization量化格式awq / gptq / fp8--dtype推理精度auto / half / bfloat16--enforce-eager关闭 CUDA Graph调试用—--kv-cache-dtypeKV Cache 量化fp8--speculative-model / --num-speculative-tokens投机解码 draft 模型与步数--speculative-model Qwen/Qwen2.5-0.5B-Instruct --num-speculative-tokens 5--trust-remote-code允许模型仓自定义代码—--task任务类型auto / generate / embedding / classify--api-key服务端 API Key—--host / --port监听地址0.0.0.0 / 8000--download-dir模型缓存目录/data/models3.2 Python APILLM离线批量推理from vllm import LLM, SamplingParams llm LLM( modelQwen/Qwen2.5-7B-Instruct, gpu_memory_utilization0.85, # 显存预算 max_model_len8192, enable_prefix_cachingTrue, ) params SamplingParams( temperature0.2, top_p0.9, max_tokens512, stop[\n\n], # 停止符 ) results llm.generate(prompts, params) # prompts: str 或 list[str] for r in results: print(r.outputs[0].text) # CompletionOutput print(r.prompt, r.outputs[0].finish_reason)SamplingParams 核心字段字段含义temperature / top_p / top_k / min_p采样参数presence_penalty / frequency_penalty / repetition_penalty多样性惩罚max_tokens最大生成 token 数stop / stop_token_ids停止条件ignore_eos忽略 EOS 继续生成n / best_of并行采样条数use_beam_search束搜索seed固定随机种子可复现logprobs / prompt_logprobs输出/输入对数概率AsyncLLM异步并发适合在线服务中做“请求级并发”用法与 LLM 类似但方法是异步的from vllm import AsyncLLM, SamplingParams async def main(): llm AsyncLLM(modelQwen/Qwen2.5-7B-Instruct, gpu_memory_utilization0.85) out await llm.generate( 用一句话解释 PagedAttention 为什么省显存。, SamplingParams(max_tokens128), ) print(out.outputs[0].text) if __name__ __main__: import asyncio asyncio.run(main())注AsyncLLM 的接口在近几个版本持续演进新增 aclose 等正式接入前以当前版本官方文档为准。更底层的 LLMEngine / EngineArgs 面向自定义调度场景本文不展开。3.3 OpenAI 兼容 API 参数映射OpenAI 字段vLLM 行为model必须是 --served-model-name 指定的名字messageschat 模板自动应用可 --chat-template 覆盖temperature / top_p / max_tokens / stop / n透传至采样stream支持 SSE 流式logprobs支持top_logprobs 需额外配置response_format{type: json_object}支持引导式 JSON 输出tools / tool_choice需 --enable-auto-tool-choice --tool-call-parser4. 详细使用说明4.1 安装# Linux NVIDIA GPU官方主路径 pip install vllm # Docker推荐生产使用 docker pull vllm/vllm-openai:latest注意 pip wheel 与 CUDA 版本配套Windows 原生支持有限建议 WSL2 或 Docker Desktop NVIDIA Container Toolkit见坑 11。首次启动会从 HuggingFace 下载模型内网环境提前下载到 --download-dir 或 HF_HOME。4.2 离线批量推理from vllm import LLM, SamplingParams llm LLM(modelQwen/Qwen2.5-7B-Instruct, gpu_memory_utilization0.85) prompts [ 请用一句话解释什么是 KV Cache。, 以下设备日志中出现了什么异常请列出可能原因并给出排查建议。\n日志2026-10-12 03:15:22 ERROR fanuc[01] alarm 4015 spindle load 128%\n, ] params SamplingParams(temperature0.1, max_tokens256) for req in llm.generate(prompts, params): print(f[{req.prompt[:20]}...] - {req.outputs[0].text})离线批处理场景日报批量总结、历史日志分析应尽量一次传入多组 prompt让连续批处理把 GPU 吃满。4.3 流式输出vllm serve Qwen/Qwen2.5-7B-Instruct --served-model-name qwen-7b --port 8000客户端用 openai SDK 即可from openai import OpenAI client OpenAI(base_urlhttp://127.0.0.1:8000/v1, api_keyEMPTY) resp client.chat.completions.create( modelqwen-7b, messages[{role: user, content: 解释连续批处理}], streamTrue, ) for chunk in resp: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end)4.4 多卡 前缀缓存 分块 prefill 的生产启动vllm serve Qwen/Qwen2.5-14B-Instruct \ --served-model-name qwen-14b \ --tensor-parallel-size 2 \ --gpu-memory-utilization 0.90 \ --max-model-len 16384 \ --max-num-seqs 128 \ --enable-prefix-caching \ --enable-chunked-prefill \ --host 0.0.0.0 --port 80004.5 Docker 部署docker run --runtime nvidia --gpus all \ -v ~/.cache/huggingface:/root/.cache/huggingface \ -p 8000:8000 \ vllm/vllm-openai:latest \ --model Qwen/Qwen2.5-7B-Instruct \ --served-model-name qwen-7b4.6 工业数采场景RAG 设备日志分析链路与既有篇目无缝衔接典型链路CNC/PLC → 采集网关 → Kafka(104/143) → TDengine(110) ↓ 离线日志/工艺数据 → FAISS(131) 向量化索引 ↓ 业务应用 → FAISS 检索 → vLLM(本篇) 生成回答 ↓ 结果回流 Kafka / 展示层WebSocket 141 / Matplotlib 142工艺知识问答把设备手册、工艺卡、历史维修记录切片向量化进 FAISS用户提问先检索 top-k 再拼进 prompt 交给 vLLM。设备日志异常分析批量日志走 LLM.generate 离线总结结果写回 TDengine。指标自然语言查询FastAPI96 篇/ Gin97 篇业务服务内用 openai SDK 调 vLLM把“最近 1 小时三号机主轴负载超 120% 的次数”这类自然语言转成查询入口可加 Nginx140 篇做限流与 TLS 终结。监控/metrics 直接接 Prometheus136 篇 Grafana。5. 底层实现剖析5.1 PagedAttention 数据路径KV Cache 以固定大小块管理--block-size默认 16 tokenBlockManager 维护逻辑块 → 物理块的映射表。每步 decode 只需按块表把 KV 写入分散的物理块块表随序列增长动态追加。前缀共享时多个序列的块表指向同一物理块并加引用计数需要改写时才触发 Copy-on-Write 复制。并行采样n1共享同一前缀是 PagedAttention 收益最大的场景之一。5.2 调度器与连续批处理vLLM 的 Scheduler 维护三类序列队列含义running正在参与当前迭代解码的序列waiting等待进入的序列含新请求与 prefillswapped被抢占后换出到 CPU 的序列每个迭代先处理 waiting 中的 prefill受 max_num_batched_tokens 约束再对 running 集体 decode序列 finish 立即释放槽位新请求插入下一迭代。显存不足时按优先级抢占通常先抢最早到达的被抢占序列换出到 CPU swap 空间无 swap 则丢弃其 KV、之后重新计算recompute。这就是 vllm:num_requests_running/waiting/swapped 三个指标背后的机制。5.3 KV Cache 显存规划gpu_memory_utilization默认 0.9划定总预算模型权重 激活 KV Cache CUDA Graph 预留。KV Cache 分块池在启动时一次性按预算分配若 max_model_len 过大导致预算内放不下任何块会报 No available memory for the cache blocks —— 这时要调小 max_model_len 或调大 gpu_memory_utilization。显存预算公式直觉KV 预算 ≈ 显存 × 利用率 − 权重 − 激活 − CUDA Graph。5.4 前缀缓存实现每个前缀块以 token id 序列哈希为 key全局 PrefixCachingBlockAllocator 用 LRU 管理缓存块。命中块直接复用物理显存未命中的新块继续分配请求结束时未共享的缓存块按策略保留一段时间供后续请求命中。命中率取决于前缀稳定性system prompt 固定、few-shot 固定、RAG 指令模板固定则命中率高前缀里混入时间戳/随机数会显著拉低命中率。5.5 CUDA Graph为消除每 step 的 kernel launch 开销vLLM 默认把模型 forward 捕获为 CUDA Graphdecode 阶段直接重放。首次请求会触发 graph 捕获慢、显存占用上升--enforce-eager 可关闭调试/兼容用。5.6 服务端架构核心是 LLMEngine调度 模型执行外层 API ServerFastAPI 实现只做协议翻译。新版 vLLM 将引擎拆为独立 EngineCore 进程/线程与 API Server 通过异步消息通信避免 GIL 与调度抖动。/metrics 由 Prometheus 客户端暴露vllm:num_requests_running、vllm:num_requests_waiting、vllm:num_requests_swapped、vllm:cache_prefix_hit_rate、vllm:gpu_cache_usage_perc、vllm:generation_tokens_total、vllm:prompt_tokens_total 等。6. 常错点 / 坑24 条坑现象 / 后果对策1显存预算与 max_model_len 失衡启动报 No available memory for the cache blocks调小 max_model_len 或调大 gpu_memory_utilization2TP 卡数不匹配启动失败或显存翻倍--tensor-parallel-size ≤ 实际 GPU 数且能整除3忘 --served-model-name客户端 model 字段用错名报 404服务端显式指定客户端用同名4量化 kernel 与硬件不匹配报错或回退极慢AWQ/GPTQ 适合多数卡FP8 需 Ada/Hopper 及以上5GGUF 与 safetensors 混用加载失败或行为异常vLLM 主路径用 HF safetensorsGGUF 支持有限K-quants 等格式先转6未设 stop / max_tokens无限生成占满吞吐业务侧必设 max_tokens需要时配 stop7chat 模型裸文本直发输出风格失控chat 模型走 messages 默认/自定义 chat template8前缀不稳定cache_prefix_hit_rate 低、TTFT 高固定 system prompt 结构去掉时间戳/随机串9并发设太大大量抢占/换出吞吐反降max-num-seqs 与显存匹配客户端限流10流式客户端超时长输出连接断开客户端合理超时 服务端 stream 心跳11Windows 原生跑各种环境报错用 WSL2 / Docker NVIDIA Container Toolkit12CUDA/cuDNN 版本不配套CUDA error: no kernel image按官方 wheel 的 CUDA 版本装环境容器化规避13模型下载慢/离线环境启动卡在下载预下载到 --download-dir / HF_HOME离线内网部署14chat 与 embedding 任务混用端点行为错乱--task generate / --task embedding 按需指定15多卡 NCCL 通信失败all-reduce 卡死/超时检查防火墙、NCCL_P2P_DISABLE、容器共享内存16长 prompt 未开 chunked prefill一次长请求卡住全部 decode开 --enable-chunked-prefill17投机解码 draft 选错反而变慢draft 模型 vocab 一致、尺寸小、接受率高实测对比18一次 generate 塞太多 prompt排队 抢占按显存分批或用服务端排队指标观测19忘 --trust-remote-code部分模型加载报错模型仓有自定义代码时显式开启注意安全审计20服务无预热首个请求含权重加载graph 捕获极慢启动后发典型请求预热再放流量21监控缺失OOM/排队/命中率不可见接 /metrics Prometheus/Grafana22response_formatjson_object 理解偏差JSON 不合法属引导解码guided decoding需在 prompt 中说明输出 JSON 结构23模型路径含中文/特殊字符加载失败用英文路径、绝对路径24升级 vLLM 大版本参数/接口不兼容升级前读 release notes锁版本部署7. 性能优化与工程实践清单12 条显存预算权重 激活 KV Cache CUDA Graph 四部分统筹gpu_memory_utilization 0.85~0.95。连续批处理参数max-num-seqs、max-num-batched-tokens 与显存匹配避免抢占风暴。开启前缀缓存固定 system prompt命中率目标 50%。Chunked prefill长文档/长上下文业务必开平滑 TTFT。投机解码为生成类高并发场景配置小 draft 模型实测加速比后再上。量化选型Ampere 用 AWQ/GPTQAda/Hopper 用 FP8显存紧张优先量化。张量并行单卡放不下或要更高吞吐时用 TPMoE 模型用 EP。预热启动后打几轮典型请求完成 CUDA Graph 捕获与显存稳定。离线批量日报/批量总结用 LLM.generate 一次喂多 prompt。在线流式交互场景开 stream降低首包感知延迟。监控running/waiting/swapped、cache_prefix_hit_rate、gpu_cache_usage_perc 三组指标必盯。链路编排FastAPI/Gin 业务层 → Nginx 入口 → vLLM 服务结果回流 Kafka/TDengine 形成闭环。8. 总结五要点PagedAttention 是核心KV Cache 分页 块表解决显存碎片与浪费是 vLLM 吞吐优势的根基。连续批处理是引擎迭代级动态调度让 GPU 每个 step 满载。前缀缓存/Chunked Prefill/投机解码是加速器分别优化 TTFT、延迟稳定性和生成速度。OpenAI 兼容是生态一行 base_url 接入一切 LLM 应用降低集成成本。选型分层边缘/单机/CPU 用 llama.cppGGUF中心 GPU 高吞吐服务用 vLLMsafetensors 量化与 FAISS/FastAPI/Kafka/TDengine/Prometheus 组合成完整工业数采 AI 链路。9. FAQ 速查12 条问题速答1vLLM 和 llama.cpp 怎么选数据不出厂/单机/CPU → llama.cppGPU 高吞吐 API 服务 → vLLM2显存不足先调什么先降 max-model-len再降 max-num-seqs最后考虑量化3为什么第一请求特别慢权重加载 CUDA Graph 捕获用预热请求解决4怎么提高前缀缓存命中率固定 system prompt/few-shot避免前缀含动态内容5支持中文模型吗支持选对 tokenizer 与 chat templateQwen 系开箱即用6并发上不去怎么办检查 running/swapped 指标调 max-num-seqs 与客户端限流7服务端挂多个模型多个 vllm serve 进程/容器前端路由8支持 embedding 吗支持--task embedding/v1/embeddings9多卡怎么分单模型用 --tensor-parallel-size多副本用多个进程10离线批量怎么最快LLM.generate 一次喂多 prompt吃满连续批处理11如何接 Prometheus/metrics 端点直接 scrape指标名带 vllm: 前缀12Windows 能跑吗官方主支持 LinuxWindows 建议 WSL2/Docker
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
