如果你跟我一样第一次听说 vLLM 的时候脑子里全是问号——它是不是要写很多代码是不是只能在高端显卡上跑那我这篇内容刚好适合你。我自己也是从小白阶段一步步把 vLLM 跑通的整个过程比想象中直接很多。先把话说透vLLM 是一个高性能大模型推理引擎用来把已经训练好的大语言模型在 GPU 上高效跑成在线服务并且对外提供一套兼容常见接口的调用方式。适合的人群很明确刚接触大模型部署的开发者、想把本地模型快速提供给项目使用的同学以及被 OOM 逼疯的调优新手。标题里写成“VLLM”其实也没关系项目官方名是 vLLM读作“微-LM”。它解决的痛点很具体模型权重加载之后普通方式推理速度慢、显存浪费严重、并发请求一多就卡死。vLLM 的价值在于把推理过程中的显存管理、请求调度、接口暴露都优化了一遍让你用几行命令把模型变成一个真正能扛住业务流量的服务。下面按我实际踩坑的顺序来写尽量把每一步为什么这么做讲清楚。1. 先别急着装环境把 vLLM 的 3 个核心概念搞明白1.1 它和普通加载模型到底有什么区别很多新手之前用过推理框架或者直接加载模型权重调 API感觉“模型不都能跑吗为什么还要多一个 vLLM”区别在于普通加载模型是单请求串行来一个请求算一次GPU 经常闲着vLLM 是把一堆请求聚在一起动态调度让 GPU 一直在干活。打个比方普通方式像只有一个窗口的食堂每人打饭必须排队前面的人慢了后面全堵住。vLLM 的连续批处理像一个自助餐厅每个人随时进来、随时拿菜、随时走人窗口不再为已经离开的人保留位置。这个机制让资源利用率大幅提高也是 vLLM 和其他推理方案拉开差距的核心原因。所以如果你只是本机测试一条 prompt用不用 vLLM 差别不大但只要涉及多个用户、多个并发、长上下文vLLM 的优势立刻体现出来。新手最容易犯的错就是把 vLLM 当成“加速脚本”实际上它是一个完整的推理服务框架。1.2 PagedAttention 和 KV Cache 到底是怎么回事大模型生成每个新 token 时都要“回忆”之前所有 token 的中间计算结果这些中间结果缓存在显存里就叫 KV Cache。问题在于KV Cache 的大小和请求的上下文长度直接相关有时候请求还没结束显存先被缓存占满了。vLLM 借鉴了操作系统里虚拟内存的分页机制把 KV Cache 拆成固定大小的块用的时候按需申请不用时立刻释放。这就不需要为每个请求预留整块连续显存显存碎片和浪费都大幅减少。理解这点很重要因为你后面调显存参数时本质就是在控制这些“页”的分配策略。我第一次跑长文本任务时显存看着明明够但一上来就 OOM原因就是 KV Cache 预留太多。后来把gpu-memory-utilization调低一点反而稳定了。这个概念不搞清楚后面出了问题很难排查。1.3 连续批处理为什么并发高也不卡传统批处理是把一批请求凑齐后一起跑等这一批全部结束才接收新请求。如果其中有个请求特别长其他短请求就得陪跑GPU 利用率照样上不去。vLLM 的连续批处理更聪明每个 token 生成完后立刻判断这个请求是否结束结束后就把它的计算槽位让给新请求。也就是说GPU 每一刻都在处理“当下最该处理”的 token而不是被一个慢请求拖住。实际测试中并发从 1 提到 10吞吐量可能翻好几倍靠的就是这个机制。正是这几个机制的组合让 vLLM 在大模型推理服务化这条路上几乎是必学工具。理解完概念接下来是最容易被环境打败的阶段。2. 初上手前的环境自检显卡、系统、安装路线怎么选2.1 没有这些硬件条件后面全是泪vLLM 是 GPU 密集型方案纯 CPU 环境虽然能跑但意义不大新手不建议一开始就挑战极限。先看自己手头的条件GPU 显存建议至少 8GB跑 7B 级别模型加量化勉强能用想舒服一点就 16GB 以上。显存大小决定你最多能同时服务多少个请求也决定能塞下多长的上下文。系统优先选 Linux。Windows 原生跑 vLLM 坑很多不是不能跑是我试过之后建议你用 WSL 或者干脆装个 Linux 虚拟机。Python 版本要 3.9 以上太低版本连依赖都装不上。一句话总结显卡越新越省心显存越大越从容。如果你手里的显卡是几年前的入门卡建议先把卡升级或者用云主机否则装好也跑不动容易怀疑人生。2.2 三条安装路线pip 安装、Docker、源码编译安装 vLLM 有三条路难度递增我强烈建议小白直接走第一条。pip install vllm这是最简单的方式。pip install vllm会拉取预编译的 wheel 包自动装好依赖。注意安装前要把 PyTorch 版本对齐最好在干净的虚拟环境里装避免和项目里的其他依赖打架。第二条路是 Docker。如果你手里已经有一套深度学习镜像或者公司内部统一用容器部署用官方镜像也很省事docker pull vllm/vllm-openai docker run --runtime nvidia --gpus all \ -v /path/to/models:/models \ -p 8000:8000 \ vllm/vllm-openai \ --model /models/MyChat-7BDocker 的好处是环境隔离坏处是镜像体积大而且对初学者来说容器内外的文件路径映射容易搞混。第三条路是源码编译。官方仓库里提供了完整的编译脚本但它要装 CUDA 工具链、编译器和一堆系统依赖编译时间能从几十分钟到几小时。我看到很多新手被网上教程忽悠去源码编译最后卡在编译报错上白白浪费时间。如果你只是写业务代码完全没必要。2.3 安装完怎么确认没问题装完别急着跑模型先花一分钟确认环境是通的python -c import vllm; print(vllm.__version__)能输出版本号说明核心库没问题。再跑一条帮助命令python -m vllm.entrypoints.openai.api_server --help能看到参数列表说明命令行入口也可以用了。如果这两步就报错大概率是 PyTorch 和 CUDA 版本不匹配回到安装步骤重新核对齐版本不要硬着头皮继续。我见过太多人跳过验证直接跑模型最后出了问题搞不清楚是安装问题还是配置问题排查起来特别费劲。3. 第一次跑通 vLLM 服务从模型文件到接口调通的完整流程3.1 准备一份能用的模型权重vLLM 本身不生产模型它只负责加载别人训练好的权重。你需要提前把模型文件下载到本地比如一个 7B 级的对话模型目录里至少要包含这些文件config.json、tokenizer.json或tokenizer.model、以及模型权重文件通常是.safetensors格式。新手常犯的错是只下载了单个权重文件或者 URL 解析错误得到了一个软链文件看起来存在实际上没内容。下载完先看目录大小7B 模型 fp16 权重大约 14GB如果只有几十 GB 倒也正常但如果只有几百 MB大概率下的不是这个模型。对于命令行参数里的--model你可以填本地路径也可以填模型仓库里的模型标识。但新手阶段我强烈建议先填本地路径因为在线下载时如果网络不稳定启动过程会一直卡在“Loading model”上你不知道是在下载还是已经卡死。先把模型放到本地目录/data/models/MyChat-7B路径不对时错误信息会很快跳出来排查更直接。3.2 用一条命令把服务拉起来确认模型文件没问题后下面是启动服务的最小命令python -m vllm.entrypoints.openai.api_server \ --model /data/models/MyChat-7B \ --gpu-memory-utilization 0.8 \ --max-model-len 8192 \ --port 8000新版 vLLM 也支持更短的写法vllm serve /data/models/MyChat-7B \ --gpu-memory-utilization 0.8 \ --max-model-len 8192 \ --port 8000启动成功后你会在日志里看到类似INFO: Started server process、Uvicorn running on http://0.0.0.0:8000的输出表示服务已经对外可调用了。这个服务兼容 OpenAI 风格的接口也就是说很多现成的客户端代码可以无缝切换不用自己写底层协议。第一次看到这个日志说明最难的阶段已经过了。3.3 关键参数逐一说清先看这几个就够了第一次启动不需要把所有参数都背下来但下面这四个必须弄明白--gpu-memory-utilization允许 vLLM 使用的显存比例默认 0.9。不是越高越好如果设成 0.99CUDA context 和驱动预留的显存可能不够反而爆发 OOM。新手建议 0.8 起步。--max-model-len模型支持的最大上下文长度单位是 token。设得太大会额外占显存设得太小长文本直接报错。按你的实际场景来定平时最多用 4K就没必要设 32K。--dtype默认是auto会自动按模型配置选择精度。新手不用改除非你明确知道要用半精度float16。--enforce-eager加上这个参数会禁用 CUDA graph 优化显存占用会低一些但速度会慢。这个参数非常适合第一次跑通调试时用能把很多奇奇怪怪的显存错误暴露出来。服务启动时还会自动扫描同目录下的 tokenizer 和配置文件如果模型格式不标准日志会明确提示缺了什么。遇到报错不要慌先看最后 20 行日志大多数问题都写得很清楚。3.4 用 Python 客户端发起一次真实调用服务起来了怎么确定它真的能用直接在命令行里测试最直观curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: /data/models/MyChat-7B, messages: [{role: user, content: 你好简单介绍一下你自己}], max_tokens: 200 }如果返回一段 JSON里面choices数组有正常文本那说明整个链路已经通了。也可以用 Python 的requests库写段脚本方便以后改参数import requests resp requests.post( http://localhost:8000/v1/chat/completions, json{ model: /data/models/MyChat-7B, messages: [{role: user, content: 用一句话解释什么是 KV Cache}], max_tokens: 128, temperature: 0.7, }, ) print(resp.json()[choices][0][message][content])到这里vLLM 已经真正跑起来了。但“跑起来”和“跑得好”之间还有一段距离接下来是压测和调优。4. 让服务更快压测、显存参数与调优经验4.1 先搞清楚“快”到底指什么很多新手上来就问“怎么让 vLLM 变快”但“快”有三个不同的维度吞吐量单位时间能输出多少 token适合离线批量处理场景关注。首 token 延迟从请求发出去到收到第一个 token 的时间聊天场景用户感知最明显。并发能力同时能支撑多少请求而不崩。这三个指标经常互相制约。你把并发线程开大吞吐可能上升但每个请求的首 token 延迟也会变高。新手最容易犯的错是拿单请求的响应时间衡量整个服务性能然后得出“vLLM 也不快”的错误结论。4.2 压测工具怎么用vLLM 自带压测脚本不用自己写复杂的并发代码。老版本可以这样用python -m vllm.entrypoints.openai.benchmark_serving \ --model /data/models/MyChat-7B \ --tokenizer /data/models/MyChat-7B \ --num-prompts 200 \ --request-rate 10参数含义很简单--num-prompts是总共发送多少请求--request-rate是每秒发送多少请求。跑完会输出吞吐、TTFT、平均延迟等数据。第一次压测建议先做小规模比如 50 个请求、每秒 5 个跑通流程后再加量。我实际压测 7B 模型时单卡 24G 显存默认参数下吞吐可以达到每秒几百到上千 token具体数字和输入输出长度强相关。所以压测结果不要直接和别人比最要紧的是看自己调参前后的变化趋势。4.3 几个真正影响性能的参数组合调优不是把某个参数拉满就行而是要组合。我整理了一个经验表优化目标推荐调整原因降低首 token 延迟减小--max-num-seqs并发槽位越多每个请求被调度到的等待时间越长提高吞吐增大--max-num-seqs同时配合--max-num-batched-tokens让每批次塞进更多 token但要控制显存处理超长 prompt开启--enable-chunked-prefill把长 prompt 分块处理避免单个大请求占满整个批次显存吃紧降低--gpu-memory-utilization到 0.7留出余量防止 OOM追求极致吞吐考虑量化方案如 AWQ/GPTQ降低权重占用变相增加可用 KV Cache 空间这些参数没有标准答案换一个模型、换一张卡最优组合就变了。我的习惯是每次只调一个参数压测看三个指标再决定下一步。千万别同时调三四个参数否则出了问题你根本不知道是谁引起的。4.4 一个被很多人忽略的调优细节--max-model-len设得太大会白白浪费显存。因为 KV Cache 是按最大长度预分配的你即使每条请求只输入 100 token后台依然按照 32K 的长度准备缓存空间。我见过有人把 13B 模型配 32K 上下文结果显存直接爆掉降到 8K 就什么问题都没有了。调优时先看业务真实需求不要追求参数上的“大”。5. 新手最容易踩的 5 个坑现象、原因与排查方法5.1 CUDA out of memory优雅的方法不是换大卡新手遇到 OOM 的第一反应是“显存不够”但很多时候是配置问题。我遇到的问题是这样的模型权重明明只占 6GB跑并发时却 OOM。后面发现是 KV Cache 默认分配了剩余几乎所有显存加上 CUDA context 也要占用最后崩了。排查思路按顺序走nvidia-smi先看当前显存占用。然后确认 vLLM 进程的gpu-memory-utilization是不是设成了 0.9 以上如果是先降到 0.7 试试。再不行就减小--max-num-seqs减少同时处理的请求数。最后还不行才考虑量化模型或者换更大的显卡。5.2 模型加载报错日志里永远缺文件启动时看到config.json不存在、tokenizer缺失这类错误90% 是权重目录没拉完整。检查一下目录结构确认是否所有文件都下载完成。有些模型是分片存储的比如model-00001-of-00004.safetensors少了一个分片也会报错。另外一个坑是软链接。网上有很多教程让你用快捷方式把模型指过来新手照做后 vLLM 在加载时可能因为找不到真实路径而失败。最简单的处理方式是把模型文件完整复制到本地目录虽然占空间但省心。5.3 端口被占用服务反复起不来启动时报Address already in use非常常见尤其是一个服务崩了之后端口没释放。排查命令lsof -i :8000找到占用进程确认没用了直接杀掉或者换一个端口启动。这个坑不深但很容易让人误以为 vLLM 安装有问题白白浪费时间。5.4 长文本请求报“输入超过最大长度”这个报错信息一般会写得很清楚你的输入长度超过了--max-model-len。解决方式是调整参数但要注意不同模型对长文本的扩展能力不同强行拉长max-model-len可能导致生成质量下降。计算输入长度时也不要只看中文字符数模型里是按 token 算的一个英文单词可能拆成几个 token一个中文汉字可能是 1 到 2 个 token。5.5 数据格式不匹配不是所有模型开箱即用vLLM 对模型的支持已经非常广泛但仍然有部分模型需要额外处理比如需要信任远程代码或者需要指定专门的量化方式。如果你发现模型加载后就报ValueError先去看模型说明文档里是否写了 vLLM 兼容性。遇到不支持的模型可以镇上一个先试普通 transformers 方案等 vLLM 新版本支持后再换回来。我把这些坑整理成一个查错速查表现象常见原因解决动作启动即 OOM显存利用率设太高降到 0.7减小--max-num-seqs加载报缺 config 文件模型目录不完整重新下载完整权重端口冲突旧进程未退出lsof -i :端口并清理进程长文本报错上下文长度超限调大--max-model-len或精简输入模型不适配模型格式特殊看文档加量化或等待新版本6. 从跑通到用好下一步该往哪个方向走到这里你已经有能力把模型跑成 HTTP 服务也懂怎么压测和排查了。如果还想往深走我建议按下面几个方向选一个第一个方向是离线批量推理。如果你要一次性处理几万条数据不需要起服务直接用 vLLM 的 Python API 做离线推理更合适。调用LLM类和SamplingParams参数能自动批量处理效率比起服务再一个个并发调用更高。第二个方向是多卡部署。单卡放不下大模型时用--tensor-parallel-size 2就能在两张卡上并行切分模型推理。这里的坑是显存会翻倍占用而且跨卡通信有开销不是卡越多一定越快。第三个方向是模型量化。量化能让模型权重从 16 比特降到 8 比特甚至 4 比特显存占用骤降吞吐上升代价是效果有轻微损耗。把量化模型跑通之后你会发现很多之前跑不动的模型都能跑起来了。第四个方向是继续优化服务化能力比如接入鉴权、限流、监控指标采集。vLLM 原生支持输出 Prometheus 格式指标方便接入现有监控体系。我个人的建议是不要急着把每个方向都学会。先把一条主链路跑通比如“一个小模型从加载到接口调用成功”再在压测中观察显存和吞吐的变化。等你对显存分配、KV Cache、连续批处理这些概念有了直观体感再做深入学习就觉得一切都顺理成章了。新手阶段最重要的不是读多少文档而是亲手把一个服务跑起来看日志、压测、调参、再压测。这个过程走完你对 vLLM 的理解会比看十篇教程都深。 
长河君 · 2026/10/24 2:53:51 · 阅读 1.2k vLLM入门实战：从概念到跑通大模型推理服务
如果你跟我一样第一次听说 vLLM 的时候脑子里全是问号——它是不是要写很多代码是不是只能在高端显卡上跑那我这篇内容刚好适合你。我自己也是从小白阶段一步步把 vLLM 跑通的整个过程比想象中直接很多。先把话说透vLLM 是一个高性能大模型推理引擎用来把已经训练好的大语言模型在 GPU 上高效跑成在线服务并且对外提供一套兼容常见接口的调用方式。适合的人群很明确刚接触大模型部署的开发者、想把本地模型快速提供给项目使用的同学以及被 OOM 逼疯的调优新手。标题里写成“VLLM”其实也没关系项目官方名是 vLLM读作“微-LM”。它解决的痛点很具体模型权重加载之后普通方式推理速度慢、显存浪费严重、并发请求一多就卡死。vLLM 的价值在于把推理过程中的显存管理、请求调度、接口暴露都优化了一遍让你用几行命令把模型变成一个真正能扛住业务流量的服务。下面按我实际踩坑的顺序来写尽量把每一步为什么这么做讲清楚。1. 先别急着装环境把 vLLM 的 3 个核心概念搞明白1.1 它和普通加载模型到底有什么区别很多新手之前用过推理框架或者直接加载模型权重调 API感觉“模型不都能跑吗为什么还要多一个 vLLM”区别在于普通加载模型是单请求串行来一个请求算一次GPU 经常闲着vLLM 是把一堆请求聚在一起动态调度让 GPU 一直在干活。打个比方普通方式像只有一个窗口的食堂每人打饭必须排队前面的人慢了后面全堵住。vLLM 的连续批处理像一个自助餐厅每个人随时进来、随时拿菜、随时走人窗口不再为已经离开的人保留位置。这个机制让资源利用率大幅提高也是 vLLM 和其他推理方案拉开差距的核心原因。所以如果你只是本机测试一条 prompt用不用 vLLM 差别不大但只要涉及多个用户、多个并发、长上下文vLLM 的优势立刻体现出来。新手最容易犯的错就是把 vLLM 当成“加速脚本”实际上它是一个完整的推理服务框架。1.2 PagedAttention 和 KV Cache 到底是怎么回事大模型生成每个新 token 时都要“回忆”之前所有 token 的中间计算结果这些中间结果缓存在显存里就叫 KV Cache。问题在于KV Cache 的大小和请求的上下文长度直接相关有时候请求还没结束显存先被缓存占满了。vLLM 借鉴了操作系统里虚拟内存的分页机制把 KV Cache 拆成固定大小的块用的时候按需申请不用时立刻释放。这就不需要为每个请求预留整块连续显存显存碎片和浪费都大幅减少。理解这点很重要因为你后面调显存参数时本质就是在控制这些“页”的分配策略。我第一次跑长文本任务时显存看着明明够但一上来就 OOM原因就是 KV Cache 预留太多。后来把gpu-memory-utilization调低一点反而稳定了。这个概念不搞清楚后面出了问题很难排查。1.3 连续批处理为什么并发高也不卡传统批处理是把一批请求凑齐后一起跑等这一批全部结束才接收新请求。如果其中有个请求特别长其他短请求就得陪跑GPU 利用率照样上不去。vLLM 的连续批处理更聪明每个 token 生成完后立刻判断这个请求是否结束结束后就把它的计算槽位让给新请求。也就是说GPU 每一刻都在处理“当下最该处理”的 token而不是被一个慢请求拖住。实际测试中并发从 1 提到 10吞吐量可能翻好几倍靠的就是这个机制。正是这几个机制的组合让 vLLM 在大模型推理服务化这条路上几乎是必学工具。理解完概念接下来是最容易被环境打败的阶段。2. 初上手前的环境自检显卡、系统、安装路线怎么选2.1 没有这些硬件条件后面全是泪vLLM 是 GPU 密集型方案纯 CPU 环境虽然能跑但意义不大新手不建议一开始就挑战极限。先看自己手头的条件GPU 显存建议至少 8GB跑 7B 级别模型加量化勉强能用想舒服一点就 16GB 以上。显存大小决定你最多能同时服务多少个请求也决定能塞下多长的上下文。系统优先选 Linux。Windows 原生跑 vLLM 坑很多不是不能跑是我试过之后建议你用 WSL 或者干脆装个 Linux 虚拟机。Python 版本要 3.9 以上太低版本连依赖都装不上。一句话总结显卡越新越省心显存越大越从容。如果你手里的显卡是几年前的入门卡建议先把卡升级或者用云主机否则装好也跑不动容易怀疑人生。2.2 三条安装路线pip 安装、Docker、源码编译安装 vLLM 有三条路难度递增我强烈建议小白直接走第一条。pip install vllm这是最简单的方式。pip install vllm会拉取预编译的 wheel 包自动装好依赖。注意安装前要把 PyTorch 版本对齐最好在干净的虚拟环境里装避免和项目里的其他依赖打架。第二条路是 Docker。如果你手里已经有一套深度学习镜像或者公司内部统一用容器部署用官方镜像也很省事docker pull vllm/vllm-openai docker run --runtime nvidia --gpus all \ -v /path/to/models:/models \ -p 8000:8000 \ vllm/vllm-openai \ --model /models/MyChat-7BDocker 的好处是环境隔离坏处是镜像体积大而且对初学者来说容器内外的文件路径映射容易搞混。第三条路是源码编译。官方仓库里提供了完整的编译脚本但它要装 CUDA 工具链、编译器和一堆系统依赖编译时间能从几十分钟到几小时。我看到很多新手被网上教程忽悠去源码编译最后卡在编译报错上白白浪费时间。如果你只是写业务代码完全没必要。2.3 安装完怎么确认没问题装完别急着跑模型先花一分钟确认环境是通的python -c import vllm; print(vllm.__version__)能输出版本号说明核心库没问题。再跑一条帮助命令python -m vllm.entrypoints.openai.api_server --help能看到参数列表说明命令行入口也可以用了。如果这两步就报错大概率是 PyTorch 和 CUDA 版本不匹配回到安装步骤重新核对齐版本不要硬着头皮继续。我见过太多人跳过验证直接跑模型最后出了问题搞不清楚是安装问题还是配置问题排查起来特别费劲。3. 第一次跑通 vLLM 服务从模型文件到接口调通的完整流程3.1 准备一份能用的模型权重vLLM 本身不生产模型它只负责加载别人训练好的权重。你需要提前把模型文件下载到本地比如一个 7B 级的对话模型目录里至少要包含这些文件config.json、tokenizer.json或tokenizer.model、以及模型权重文件通常是.safetensors格式。新手常犯的错是只下载了单个权重文件或者 URL 解析错误得到了一个软链文件看起来存在实际上没内容。下载完先看目录大小7B 模型 fp16 权重大约 14GB如果只有几十 GB 倒也正常但如果只有几百 MB大概率下的不是这个模型。对于命令行参数里的--model你可以填本地路径也可以填模型仓库里的模型标识。但新手阶段我强烈建议先填本地路径因为在线下载时如果网络不稳定启动过程会一直卡在“Loading model”上你不知道是在下载还是已经卡死。先把模型放到本地目录/data/models/MyChat-7B路径不对时错误信息会很快跳出来排查更直接。3.2 用一条命令把服务拉起来确认模型文件没问题后下面是启动服务的最小命令python -m vllm.entrypoints.openai.api_server \ --model /data/models/MyChat-7B \ --gpu-memory-utilization 0.8 \ --max-model-len 8192 \ --port 8000新版 vLLM 也支持更短的写法vllm serve /data/models/MyChat-7B \ --gpu-memory-utilization 0.8 \ --max-model-len 8192 \ --port 8000启动成功后你会在日志里看到类似INFO: Started server process、Uvicorn running on http://0.0.0.0:8000的输出表示服务已经对外可调用了。这个服务兼容 OpenAI 风格的接口也就是说很多现成的客户端代码可以无缝切换不用自己写底层协议。第一次看到这个日志说明最难的阶段已经过了。3.3 关键参数逐一说清先看这几个就够了第一次启动不需要把所有参数都背下来但下面这四个必须弄明白--gpu-memory-utilization允许 vLLM 使用的显存比例默认 0.9。不是越高越好如果设成 0.99CUDA context 和驱动预留的显存可能不够反而爆发 OOM。新手建议 0.8 起步。--max-model-len模型支持的最大上下文长度单位是 token。设得太大会额外占显存设得太小长文本直接报错。按你的实际场景来定平时最多用 4K就没必要设 32K。--dtype默认是auto会自动按模型配置选择精度。新手不用改除非你明确知道要用半精度float16。--enforce-eager加上这个参数会禁用 CUDA graph 优化显存占用会低一些但速度会慢。这个参数非常适合第一次跑通调试时用能把很多奇奇怪怪的显存错误暴露出来。服务启动时还会自动扫描同目录下的 tokenizer 和配置文件如果模型格式不标准日志会明确提示缺了什么。遇到报错不要慌先看最后 20 行日志大多数问题都写得很清楚。3.4 用 Python 客户端发起一次真实调用服务起来了怎么确定它真的能用直接在命令行里测试最直观curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: /data/models/MyChat-7B, messages: [{role: user, content: 你好简单介绍一下你自己}], max_tokens: 200 }如果返回一段 JSON里面choices数组有正常文本那说明整个链路已经通了。也可以用 Python 的requests库写段脚本方便以后改参数import requests resp requests.post( http://localhost:8000/v1/chat/completions, json{ model: /data/models/MyChat-7B, messages: [{role: user, content: 用一句话解释什么是 KV Cache}], max_tokens: 128, temperature: 0.7, }, ) print(resp.json()[choices][0][message][content])到这里vLLM 已经真正跑起来了。但“跑起来”和“跑得好”之间还有一段距离接下来是压测和调优。4. 让服务更快压测、显存参数与调优经验4.1 先搞清楚“快”到底指什么很多新手上来就问“怎么让 vLLM 变快”但“快”有三个不同的维度吞吐量单位时间能输出多少 token适合离线批量处理场景关注。首 token 延迟从请求发出去到收到第一个 token 的时间聊天场景用户感知最明显。并发能力同时能支撑多少请求而不崩。这三个指标经常互相制约。你把并发线程开大吞吐可能上升但每个请求的首 token 延迟也会变高。新手最容易犯的错是拿单请求的响应时间衡量整个服务性能然后得出“vLLM 也不快”的错误结论。4.2 压测工具怎么用vLLM 自带压测脚本不用自己写复杂的并发代码。老版本可以这样用python -m vllm.entrypoints.openai.benchmark_serving \ --model /data/models/MyChat-7B \ --tokenizer /data/models/MyChat-7B \ --num-prompts 200 \ --request-rate 10参数含义很简单--num-prompts是总共发送多少请求--request-rate是每秒发送多少请求。跑完会输出吞吐、TTFT、平均延迟等数据。第一次压测建议先做小规模比如 50 个请求、每秒 5 个跑通流程后再加量。我实际压测 7B 模型时单卡 24G 显存默认参数下吞吐可以达到每秒几百到上千 token具体数字和输入输出长度强相关。所以压测结果不要直接和别人比最要紧的是看自己调参前后的变化趋势。4.3 几个真正影响性能的参数组合调优不是把某个参数拉满就行而是要组合。我整理了一个经验表优化目标推荐调整原因降低首 token 延迟减小--max-num-seqs并发槽位越多每个请求被调度到的等待时间越长提高吞吐增大--max-num-seqs同时配合--max-num-batched-tokens让每批次塞进更多 token但要控制显存处理超长 prompt开启--enable-chunked-prefill把长 prompt 分块处理避免单个大请求占满整个批次显存吃紧降低--gpu-memory-utilization到 0.7留出余量防止 OOM追求极致吞吐考虑量化方案如 AWQ/GPTQ降低权重占用变相增加可用 KV Cache 空间这些参数没有标准答案换一个模型、换一张卡最优组合就变了。我的习惯是每次只调一个参数压测看三个指标再决定下一步。千万别同时调三四个参数否则出了问题你根本不知道是谁引起的。4.4 一个被很多人忽略的调优细节--max-model-len设得太大会白白浪费显存。因为 KV Cache 是按最大长度预分配的你即使每条请求只输入 100 token后台依然按照 32K 的长度准备缓存空间。我见过有人把 13B 模型配 32K 上下文结果显存直接爆掉降到 8K 就什么问题都没有了。调优时先看业务真实需求不要追求参数上的“大”。5. 新手最容易踩的 5 个坑现象、原因与排查方法5.1 CUDA out of memory优雅的方法不是换大卡新手遇到 OOM 的第一反应是“显存不够”但很多时候是配置问题。我遇到的问题是这样的模型权重明明只占 6GB跑并发时却 OOM。后面发现是 KV Cache 默认分配了剩余几乎所有显存加上 CUDA context 也要占用最后崩了。排查思路按顺序走nvidia-smi先看当前显存占用。然后确认 vLLM 进程的gpu-memory-utilization是不是设成了 0.9 以上如果是先降到 0.7 试试。再不行就减小--max-num-seqs减少同时处理的请求数。最后还不行才考虑量化模型或者换更大的显卡。5.2 模型加载报错日志里永远缺文件启动时看到config.json不存在、tokenizer缺失这类错误90% 是权重目录没拉完整。检查一下目录结构确认是否所有文件都下载完成。有些模型是分片存储的比如model-00001-of-00004.safetensors少了一个分片也会报错。另外一个坑是软链接。网上有很多教程让你用快捷方式把模型指过来新手照做后 vLLM 在加载时可能因为找不到真实路径而失败。最简单的处理方式是把模型文件完整复制到本地目录虽然占空间但省心。5.3 端口被占用服务反复起不来启动时报Address already in use非常常见尤其是一个服务崩了之后端口没释放。排查命令lsof -i :8000找到占用进程确认没用了直接杀掉或者换一个端口启动。这个坑不深但很容易让人误以为 vLLM 安装有问题白白浪费时间。5.4 长文本请求报“输入超过最大长度”这个报错信息一般会写得很清楚你的输入长度超过了--max-model-len。解决方式是调整参数但要注意不同模型对长文本的扩展能力不同强行拉长max-model-len可能导致生成质量下降。计算输入长度时也不要只看中文字符数模型里是按 token 算的一个英文单词可能拆成几个 token一个中文汉字可能是 1 到 2 个 token。5.5 数据格式不匹配不是所有模型开箱即用vLLM 对模型的支持已经非常广泛但仍然有部分模型需要额外处理比如需要信任远程代码或者需要指定专门的量化方式。如果你发现模型加载后就报ValueError先去看模型说明文档里是否写了 vLLM 兼容性。遇到不支持的模型可以镇上一个先试普通 transformers 方案等 vLLM 新版本支持后再换回来。我把这些坑整理成一个查错速查表现象常见原因解决动作启动即 OOM显存利用率设太高降到 0.7减小--max-num-seqs加载报缺 config 文件模型目录不完整重新下载完整权重端口冲突旧进程未退出lsof -i :端口并清理进程长文本报错上下文长度超限调大--max-model-len或精简输入模型不适配模型格式特殊看文档加量化或等待新版本6. 从跑通到用好下一步该往哪个方向走到这里你已经有能力把模型跑成 HTTP 服务也懂怎么压测和排查了。如果还想往深走我建议按下面几个方向选一个第一个方向是离线批量推理。如果你要一次性处理几万条数据不需要起服务直接用 vLLM 的 Python API 做离线推理更合适。调用LLM类和SamplingParams参数能自动批量处理效率比起服务再一个个并发调用更高。第二个方向是多卡部署。单卡放不下大模型时用--tensor-parallel-size 2就能在两张卡上并行切分模型推理。这里的坑是显存会翻倍占用而且跨卡通信有开销不是卡越多一定越快。第三个方向是模型量化。量化能让模型权重从 16 比特降到 8 比特甚至 4 比特显存占用骤降吞吐上升代价是效果有轻微损耗。把量化模型跑通之后你会发现很多之前跑不动的模型都能跑起来了。第四个方向是继续优化服务化能力比如接入鉴权、限流、监控指标采集。vLLM 原生支持输出 Prometheus 格式指标方便接入现有监控体系。我个人的建议是不要急着把每个方向都学会。先把一条主链路跑通比如“一个小模型从加载到接口调用成功”再在压测中观察显存和吞吐的变化。等你对显存分配、KV Cache、连续批处理这些概念有了直观体感再做深入学习就觉得一切都顺理成章了。新手阶段最重要的不是读多少文档而是亲手把一个服务跑起来看日志、压测、调参、再压测。这个过程走完你对 vLLM 的理解会比看十篇教程都深。