【vLLM 工程实践】大模型高效部署全流程

文章目录vLLM 工程实践大模型高效部署全流程一、引言二、核心机制vLLM 为什么快2.1 PagedAttention像操作系统管理内存一样管理 KV Cache2.2 连续批处理Continuous Batching2.3 其他关键能力一览三、环境搭建3.1 硬件与驱动前置条件3.2 用 pip 安装最简路径3.3 用 Docker 部署生产推荐四、快速上手离线推理与在线服务4.1 离线批量推理Offline Inference4.2 启动 OpenAI 兼容 API 服务五、分布式部署单机多卡与多机多卡5.1 张量并行Tensor Parallelism单机多卡5.2 流水线并行Pipeline Parallelism跨机扩展5.3 分布式相关核心参数六、量化与性能调优6.1 量化方案对比6.2 关键调优参数6.3 投机解码进一步压缩解码延迟七、生产部署实践7.1 容器化 环境变量管理7.2 监控Prometheus Grafana7.3 多 LoRA 服务一个基座模型服务多个业务场景7.4 Kubernetes 部署要点八、横向对比vLLM 与主流推理框架九、常见问题速查表十、总结vLLM 工程实践大模型高效部署全流程一、引言亲爱的朋友们创作不容易若对您有帮助的话请点赞收藏加关注哦您的关注是我持续创作的动力谢谢大家有问题请私信或联系邮箱jasonai.fngmail.com同样一张 A100同样的 70B 模型有的团队跑出每秒几十个 token 的可用吞吐有的团队却发现 GPU 显存被 KV Cache 撑爆、并发一高就 OOM、单个长请求能把整个服务卡死。差别往往不在模型而在推理引擎——原生 HuggingFacetransformers的generate()是为研究场景设计的从来没考虑过数百个用户同时排队请求这种生产负载。vLLM 的出现解决的正是这个问题。它由 UC Berkeley Sky Computing Lab 团队在 2023 年提出核心论文《Efficient Memory Management for Large Language Model Serving with PagedAttention》把操作系统虚拟内存分页的思想搬进了 KV Cache 管理配合连续批处理Continuous Batching调度把显存利用率和吞吐量都推到了新的量级。本文不重复讲 PagedAttention 论文里的公式推导而是聚焦工程落地从环境安装到离线推理从单机多卡到多机分布式从量化压缩到生产环境的监控与 LoRA 多租户服务给出一套可以直接照做的部署流程。二、核心机制vLLM 为什么快在动手部署之前先搞清楚 vLLM 快在哪里——这决定了后面每一个参数该怎么调。2.1 PagedAttention像操作系统管理内存一样管理 KV Cache传统推理引擎给每个请求的 KV Cache 分配一段连续显存且必须按最大可能长度预留。一个请求实际只用了 200 个 token却按max_model_len4096预留显存中间全是浪费——这种浪费在传统方案里能达到 60%~80%。PagedAttention 把 KV Cache 切分成固定大小的block默认 16 个 token 一块像操作系统的分页内存一样按需分配、非连续存储用一张页表记录每个请求的 block 映射关系。显存碎片浪费被压到 4% 以内同样的显存能塞进多得多的并发请求。传统方式每个请求预留 max_length 显存大量浪费 ┌────────────────────────────────────┐ │ 请求A实际使用 ███░░░░░░░░░░░░░░░░░░░ │ ← 浪费 │ 请求B实际使用 █████░░░░░░░░░░░░░░░░ │ ← 浪费 └────────────────────────────────────┘ PagedAttention按需分配非连续 block用完即还 ┌───┬───┬───┬───┬───┬───┬───┬───┬───┐ │A-1│A-2│B-1│C-1│A-3│B-2│C-2│ 空闲块池 │ └───┴───┴───┴───┴───┴───┴───┴───┴───┘2.2 连续批处理Continuous Batching静态批处理static batching要等一批请求全部生成完才能换下一批长短请求混在一起时短请求生成完了也要陪着长请求陪跑GPU 利用率忽高忽低。vLLM 采用迭代级调度每完成一次前向计算就检查一次批次结束的请求立刻让位新请求随时插入GPU 几乎不存在空闲等待。这是 vLLM 相对原生transformers.generate()吞吐提升可达一个数量级的关键原因之一官方论文给出的对比场景中吞吐提升可达 24 倍具体倍数因模型和负载而异。2.3 其他关键能力一览能力作用前缀缓存Prefix Caching相同系统提示词/上下文的请求复用已计算的 KV Cache多轮对话场景收益明显分块预填充Chunked Prefill把长 prompt 的预填充拆成小块与解码阶段交替执行避免长请求卡住其他请求投机解码Speculative Decoding用小模型或 n-gram 提前猜多个 token大模型一次验证减少解码轮数量化推理支持 AWQ、GPTQ、FP8、INT4/INT8 等用精度换显存和速度多 LoRA 服务同一基座模型加载多个 LoRA 适配器按请求动态切换单实例服务多租户三、环境搭建3.1 硬件与驱动前置条件项目要求GPUNVIDIA 计算能力 ≥ 7.0V100 及以上AMD ROCm、Intel XPU、CPU 也有对应支持CUDA建议 12.1 及以上与 vLLM 发行版对应的 PyTorch CUDA 版本一致显存经验值模型参数量B× 2FP16/BF16 字节数 KV Cache 预留例如 32B 模型 FP16 权重约占 64GB还需预留 KV Cache 空间Python3.9–3.12以官方发行版说明为准3.2 用 pip 安装最简路径# 建议使用独立虚拟环境避免依赖冲突python-mvenv vllm-envsourcevllm-env/bin/activate# 安装 vLLM会自动匹配对应版本的 PyTorch CUDApipinstallvllm# 验证安装python-cimport vllm; print(vllm.__version__)3.3 用 Docker 部署生产推荐官方维护了开箱即用的镜像避免本地 CUDA 版本与依赖冲突dockerrun--runtimenvidia--gpusall\-v~/.cache/huggingface:/root/.cache/huggingface\--envHUGGING_FACE_HUB_TOKEN你的HF Token\-p8000:8000\--ipchost\vllm/vllm-openai:latest\--modelQwen/Qwen2.5-7B-Instruct关键参数说明--ipchost避免多进程共享内存不足导致的 crash-v挂载 HuggingFace 缓存目录避免容器重启后重新下载模型--gpus all暴露全部 GPU多卡场景可用--gpus device0,1精确指定。四、快速上手离线推理与在线服务4.1 离线批量推理Offline Inference适合跑评测集、批量生成等无需常驻服务的场景fromvllmimportLLM,SamplingParams# 初始化引擎加载模型llmLLM(modelQwen/Qwen2.5-7B-Instruct,dtypebfloat16)sampling_paramsSamplingParams(temperature0.7,top_p0.9,max_tokens512)prompts[用一句话解释什么是量子纠缠。,写一个 Python 快速排序函数。,]outputsllm.generate(prompts,sampling_params)foroutputinoutputs:print(output.outputs[0].text)vLLM 会自动把这批 prompt 组织成批次并行计算不需要手动写 batching 逻辑。4.2 启动 OpenAI 兼容 API 服务生产场景更常见的是常驻服务vLLM 内置了与 OpenAI API 完全兼容的接口现有基于openaiSDK 的代码几乎不用改vllm serve Qwen/Qwen2.5-7B-Instruct\--host0.0.0.0\--port8000\--dtypebfloat16\--max-model-len8192\--gpu-memory-utilization0.9客户端调用方式fromopenaiimportOpenAI clientOpenAI(base_urlhttp://localhost:8000/v1,api_keynot-needed)responseclient.chat.completions.create(modelQwen/Qwen2.5-7B-Instruct,messages[{role:user,content:介绍一下 vLLM 的核心优势}],temperature0.7,)print(response.choices[0].message.content)也可以直接用 curl 验证服务是否正常curlhttp://localhost:8000/v1/chat/completions\-HContent-Type: application/json\-d{ model: Qwen/Qwen2.5-7B-Instruct, messages: [{role: user, content: 你好}] }五、分布式部署单机多卡与多机多卡5.1 张量并行Tensor Parallelism单机多卡当单卡显存放不下模型权重时用张量并行把每一层的矩阵运算切分到多张卡上并行计算--tensor-parallel-size需等于参与计算的 GPU 数量vllm serve Qwen/Qwen2.5-72B-Instruct\--tensor-parallel-size4\--gpu-memory-utilization0.9\--max-model-len163845.2 流水线并行Pipeline Parallelism跨机扩展当单机 GPU 数量不够需要跨节点扩展时流水线并行把模型按层切段分布到不同节点配合张量并行组合使用# 假设 2 节点 × 每节点 4 卡 8 卡vllm serve Qwen/Qwen2.5-72B-Instruct\--tensor-parallel-size4\--pipeline-parallel-size2多节点部署依赖Ray做跨机进程管理需要先手动启动 Ray 集群# 主节点ray start--head--port6379# 其他节点加入集群ray start--address主节点IP:6379# 确认集群节点数ray status5.3 分布式相关核心参数参数说明--tensor-parallel-size单节点内张量并行的 GPU 数--pipeline-parallel-size跨节点流水线并行的阶段数--distributed-executor-backend并行后端ray或mp单机多进程--max-num-seqs单批次最大并发请求数显存充足时可调大提升吞吐--swap-space显存不足时 KV Cache 换出到 CPU 内存的空间大小GB六、量化与性能调优6.1 量化方案对比显存不够、想用更小的卡跑更大的模型时量化是最直接的手段量化方案精度显存节省适用场景FP16/BF16全精度基准显存充足、追求最佳效果AWQINT4约 4 倍权重量化精度损失小社区预量化模型多GPTQINT4约 4 倍需要针对性校准推理速度与 AWQ 接近FP88 位浮点约 2 倍依赖 HopperH100/H800等新架构硬件加速INT8 (bitsandbytes)INT8约 2 倍无需额外校准兼容性好但速度提升有限启用量化模型只需在启动时指定量化方式和使用已量化的模型权重vllm serve TheBloke/Qwen2.5-72B-Instruct-AWQ\--quantizationawq\--dtypefloat166.2 关键调优参数参数默认值调优建议--gpu-memory-utilization0.9单卡多服务共享时调低如 0.6避免抢占其他进程显存--max-model-len模型默认上下文按实际业务需求设置越大 KV Cache 占用越多不要设置远超实际需求的值--enable-chunked-prefill视版本而定长短请求混合负载建议开启避免长 prompt 阻塞短请求--enable-prefix-caching关闭多轮对话、固定 system prompt 场景强烈建议开启--block-size16一般无需调整特殊硬件场景可尝试 32--max-num-batched-tokens自动限制单批次总 token 数防止显存瞬时占用过高6.3 投机解码进一步压缩解码延迟投机解码用一个小模型先草拟多个候选 token大模型一次性并行验证命中率高时能显著减少解码轮数vllm serve Qwen/Qwen2.5-72B-Instruct\--speculative-model Qwen/Qwen2.5-1.5B-Instruct\--num-speculative-tokens5也可以用无需额外模型的 n-gram 投机适合重复模式明显的生成任务如代码补全vllm serve Qwen/Qwen2.5-72B-Instruct\--speculative-model[ngram]\--num-speculative-tokens5\--ngram-prompt-lookup-max4七、生产部署实践7.1 容器化 环境变量管理生产环境建议用docker-compose统一管理配置密钥不写进命令行services:vllm:image:vllm/vllm-openai:latestruntime:nvidiaipc:hostports:-8000:8000environment:-HUGGING_FACE_HUB_TOKEN${HF_TOKEN}volumes:-~/.cache/huggingface:/root/.cache/huggingfacedeploy:resources:reservations:devices:-driver:nvidiacount:allcapabilities:[gpu]command:--model Qwen/Qwen2.5-7B-Instruct --gpu-memory-utilization 0.9 --max-model-len 8192 --enable-prefix-caching7.2 监控Prometheus GrafanavLLM 内置/metrics端点暴露请求吞吐、排队时长、KV Cache 使用率等核心指标可直接接入 Prometheus# prometheus.yml 片段scrape_configs:-job_name:vllmstatic_configs:-targets:[vllm-host:8000]生产环境重点关注的指标包括vllm:num_requests_running正在处理的请求数、vllm:num_requests_waiting排队请求数、vllm:gpu_cache_usage_percKV Cache 显存使用率——排队数持续增长通常意味着需要扩容或调大并发参数。7.3 多 LoRA 服务一个基座模型服务多个业务场景不需要为每个微调版本单独起一个服务实例vLLM 支持在同一基座模型上动态挂载多个 LoRA 适配器vllm serve meta-llama/Llama-3.1-8B-Instruct\--enable-lora\--lora-modules customer-service/path/to/lora-cs sql-agent/path/to/lora-sql\--max-lora-rank32调用时通过model字段指定使用哪个 LoRAresponseclient.chat.completions.create(modelcustomer-service,messages[{role:user,content:我的订单还没到货}],)7.4 Kubernetes 部署要点大规模生产环境通常用 K8s 管理多副本核心是把 GPU 资源声明和存活探针配置正确resources:limits:nvidia.com/gpu:1readinessProbe:httpGet:path:/healthport:8000initialDelaySeconds:60# 模型加载耗时较长探针延迟需放宽periodSeconds:10initialDelaySeconds是最容易踩的坑大模型加载动辄几十秒到几分钟探针延迟设置过短会导致 Pod 被误判为不健康而反复重启。八、横向对比vLLM 与主流推理框架vLLM 不是唯一的推理引擎选择工程选型时通常会和以下几个框架放在一起比较维度vLLMHuggingFace TGINVIDIA TensorRT-LLMSGLang核心技术PagedAttention 连续批处理连续批处理 Flash Attention编译期算子融合与内核优化RadixAttention前缀树式缓存复用易用性高pip install即用HF 模型基本开箱即用高与 HF 生态深度绑定较低需要针对模型做引擎编译中API 设计与 vLLM 接近极致性能优秀通用场景表现均衡良好同硬件下单点吞吐/延迟往往最优代价是编译成本和灵活性复杂结构化生成、多轮对话场景有优势生态与模型覆盖覆盖面最广社区迭代快与 HF Hub 集成紧密主要覆盖 NVIDIA 官方适配的模型覆盖主流模型增长中典型选择理由通用生产服务的默认选项已重度使用 HF 生态的团队极致压榨 NVIDIA 硬件性能、愿意投入编译调优成本的场景结构化输出、Agent 类复杂调用模式对于本地单机、轻量场景如个人开发、小规模私有部署Ollama是更轻的选择——底层基于 llama.cpp安装和模型切换比 vLLM 简单得多但吞吐和并发能力明显弱于 vLLM不适合高并发生产服务。简单结论追求通用性 社区活跃度 开箱即用的高吞吐vLLM 是当前的默认项追求单硬件极限性能且能承担工程投入可以评估 TensorRT-LLM结构化/Agent 类复杂调用场景可以关注 SGLang本地轻量场景用 Ollama。九、常见问题速查表问题原因解决方案启动时 OOMgpu-memory-utilization设置过高或max-model-len远超实际需求调低--gpu-memory-utilization收紧--max-model-len多卡启动报错找不到设备--tensor-parallel-size与实际可见 GPU 数量不一致检查CUDA_VISIBLE_DEVICES与参数是否匹配长 prompt 请求拖慢其他请求未开启分块预填充添加--enable-chunked-prefill多轮对话重复计算浪费算力未开启前缀缓存添加--enable-prefix-cachingK8s 中 Pod 反复重启存活探针延迟过短模型还没加载完就被判定失败调大initialDelaySeconds多机部署互相找不到节点Ray 集群未正确加入检查ray status确认所有节点已加入同一集群量化模型效果明显下降量化方式或校准数据集不适配当前模型优先使用社区已验证的预量化权重或更换量化方案十、总结维度核心要点核心原理PagedAttention 按需分页管理 KV Cache连续批处理消除批次间的空闲等待快速上手LLM类做离线批量推理vllm serve一行命令起 OpenAI 兼容服务分布式扩展单机多卡用张量并行跨机扩展叠加流水线并行多节点依赖 Ray量化调优AWQ/GPTQ/FP8 按硬件和精度需求选择gpu-memory-utilization、max-model-len是最先要调的两个参数生产实践Docker 容器化 Prometheus 监控 多 LoRA 服务 K8s 探针延迟放宽横向定位通用高吞吐场景的默认选择极限性能看 TensorRT-LLM结构化生成看 SGLang本地轻量场景用 OllamavLLM 把如何让一张卡多装几个请求如何让长短请求互不拖累这些原本需要团队自研的推理优化封装成了几个命令行参数。工程落地的关键不在于记住每个参数的默认值而在于理解 PagedAttention 和连续批处理解决的是什么问题——理解了这一点无论是调显存利用率、开前缀缓存还是排查排队请求为什么突然暴涨都有了判断的依据。参考资料vLLM 官方文档Efficient Memory Management for Large Language Model Serving with PagedAttention (SOSP 2023)vLLM GitHub 仓库vLLM Production StackRay 官方文档 — 分布式计算框架