从第一次部署vLLM到现在前前后后折腾过小半年。最开始的动机很简单公司内网要跑一个大模型服务OpenAI接口得兼容吞吐量还不能太难看。当时先在Ollama和LM Studio上试了一轮简单场景确实够用但一上并发显存就被打爆响应延迟也跟着失控。后来切到vLLM才真正感受到“页面缓存从显存里省出来”是什么体验——同样的显卡单并发变多并发显存占用反而更可控吞吐直接翻了几倍。这篇文章就是给想从零上手vLLM的同学写的。我会从安装、启动、显存调优到常见问题完整过一遍实操过程尽量把每个参数背后的“为什么”也讲清楚。适合两类人一类是刚接触大模型推理服务、想快速搭一个能用的OpenAI兼容API的人另一类是用Ollama跑过但觉得显存效率不够想换vLLM来压榨显卡性能的人。读完你至少能自己部署一个vLLM服务并且知道该从哪里去调显存、调吞吐。1. 安装前先摸清家底1.1 硬件与系统版本要求vLLM本质上是个PyTorch推理框架对GPU和驱动的要求比较明确。先把家底查清楚能省掉后面一大堆莫名其妙的报错。NVIDIA显卡显存至少8GB起步。8GB能跑7B模型做量化读完本篇的调优内容后勉强能承载几个并发如果要跑13B甚至更大的模型老老实实上24GB以上。驱动建议450CUDA Toolkit版本根据你装的PyTorch来定。vLLM目前主流支持CUDA 12.1/12.4装之前先看官方文档对应的版本矩阵。Python版本3.9到3.12都行推荐3.10或3.11兼容性最稳。检查命令就三条nvidia-smi python --version nvcc --versionnvidia-smi里能看到显存和驱动版本nvcc --version看的是CUDA编译器版本。注意一点nvidia-smi显示的驱动对应CUDA版本和系统里的nvcc版本可以不一样vLLM实际使用的是从PyTorch带过来的CUDA runtime所以只要驱动够新CUDA Toolkit版本低一点也没关系。1.2 用pip安装和常见坑我的建议是先建虚拟环境别直接在base环境里装。大模型依赖多、版本敏感虚拟环境能让你在翻车后一键回到解放前。python -m venv vllm_env source vllm_env/bin/activate # Windows下用 vllm_env\Scripts\activate pip install vllm装完之后验证一下import vllm print(vllm.__version__)这里有几个高频坑提前给你们打个预防针网络慢导致安装超时。建议配置国内镜像源实测中科大和清华的都稳。torch和vllm版本冲突。vLLM对PyTorch版本有要求直接pip install vllm一般会自动装匹配版本但如果你之前手动装过别的PyTorch版本很容易出现torch._C相关报错。解决办法是先卸载重装pip uninstall torch torchvision torchaudio -y pip install vllm内存不够编译报错。如果安装过程中卡在building wheel注意看是不是内存满了。vLLM有些算子需要编译内存最好留8GB以上实在不行加swap也能缓解。1.3 Docker方式安装及为什么推荐它如果不想折腾Python环境Docker是最省心的方式。vLLM官方镜像vllm/vllm-openai已经把运行环境打包好了。这里有个版本需要注意比如vllm/vllm-openai:v0.27.1这类特定版本在跑Embedding模型时表现稳定。拉镜像和启动容器docker pull vllm/vllm-openai:v0.27.1 docker run --runtime nvidia --gpus all \ -v /data/models:/models \ -p 8000:8000 \ --shm-size 16g \ vllm/vllm-openai:v0.27.1 \ --model /models/qwen3-embedding-0.6b \ --port 8000--shm-size一定别漏默认64MB会导致多进程之间共享数据失败这是Docker跑vLLM最容易忽略的隐藏雷。挂载模型目录也建议用-v做好这样调试模型时不用重新打镜像。多版本管理时我给每个镜像打了tagdocker tag vllm/vllm-openai:v0.27.1 vllm-local:27通过Docker跑还有一个好处就是容器内的CUDA环境固定不会因为宿主机上装了不同版本的CUDA库而互相污染。生产环境我目前都是容器方案本地开发才用pip虚拟环境。2. 启动一个OpenAI兼容服务2.1 一条命令把服务跑起来vLLM最常用的启动方式就是vllm serve它会直接起一个兼容OpenAI接口的HTTP服务。这里以保底能跑通的Qwen2.5-7B-Instruct为例vllm serve Qwen/Qwen2.5-7B-Instruct \ --host 0.0.0.0 \ --port 8000 \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.9 \ --max-model-len 8192启动成功的日志里会出现类似Uvicorn running on http://0.0.0.0:8000的字样。看到这个就算成了。--host设为0.0.0.0是为了方便局域网内其他机器访问如果只是本机调试可以写成127.0.0.1。--port默认8000冲突就换。--tensor-parallel-size单卡就填1多卡再做张量并行。2.2 启动参数逐项解析很多朋友上来就是抄一个命令出了问题也不知道改哪里。我做了个参数速查表都是高频使用的参数作用建议值备注--model模型名称或路径必填可以用HuggingFace模型名也可以用本地路径--served-model-name对外暴露的模型名自定义客户端调用时用的名字和--model可以不同--host监听IP0.0.0.0局域网访问用这个--port监听端口8000被占用时换别的--tensor-parallel-size张量并行显卡数1或卡数多卡时设置需确保卡间通信带宽足够--gpu-memory-utilization显存利用率上限0.85~0.95调小能稳调大能提升吞吐--max-model-len最大序列长度4096或8192长度越短显存留给KV cache越多--dtype推理精度auto/bfloat16Ampere及以上建议bfloat16--quantization量化方式awq/gptq/fp8配合对应模型使用--enforce-eager关闭图模式可选开启显存紧张时能省一点但性能下降--kv-cache-dtypeKV cache精度auto/fp8部分显卡支持fp8能省显存这里重点解释两个--max-model-len控制上下文窗口。它直接决定KV cache能缓存多少历史token。如果你只做短对话设成2048或4096就能腾出大量显存给并发如果要处理长文档就要给足否则请求一长就直接报ContextLengthExceededError。--gpu-memory-utilization是显存调优的核心旋钮。它表示vLLM最多能占用多少比例的显存。设0.9代表只用到90%显存留10%给CUDA context和其他零碎开销。如果启动就OOM优先把它降到0.85甚至0.8。2.3 用curl和Python测试服务是否正常服务起来后先做健康检查curl http://localhost:8000/health返回{status:ok}才说明模型加载完成。接着测试对话接口curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen/Qwen2.5-7B-Instruct, messages: [{role: user, content: 你好介绍一下你自己}], max_tokens: 256 }Python侧用openai库也行from openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keyEMPTY) resp client.chat.completions.create( modelQwen/Qwen2.5-7B-Instruct, messages[{role: user, content: 你好}], max_tokens256 ) print(resp.choices[0].message.content)注意base_url是/v1结尾api_key随便填。vLLM只检查这个字段是否存在不校验值。2.4 通过Python代码加载模型做离线推理如果只是想在脚本里跑推理不打算起HTTP服务可以直接用LLM类from vllm import LLM, SamplingParams llm LLM(modelQwen/Qwen2.5-7B-Instruct, gpu_memory_utilization0.9) params SamplingParams(temperature0.7, max_tokens512) outputs llm.generate([请用一句话介绍你自己], params) print(outputs[0].outputs[0].text)这个方式适合批量处理文本、本地实验。但要注意LLM类实例化时会加载全部模型权重到显存而且默认也会预留KV cache所以如果你要起多个实例显存分配要提前算好否则第二个实例直接OOM。3. 显存调优从入门到压榨3.1 显存到底被谁吃了调优之前先要知道显存的去向。跑一个大模型的显存占用大致分为四块模型权重这是基础7B模型bf16精度大约是14GB权重FP16也差不多INT4量化后可以压到4GB以下。KV cache推理过程中存储历史token的Key和Value是动态变化的也是调优空间最大的部分。激活值前向传播过程中的中间张量激活值在长序列下会比较大但vLLM已经优化得比较好了。CUDA contextCUDA启动时的固定开销通常几百MB到1GB。vLLM最核心的优化就是通过PagedAttention管理KV cache像操作系统管理内存一样按页分配减少碎片让显存利用率大幅提升。这也就是它能比Ollama和LM Studio在同显卡上支撑更多并发的原因。Ollama更适合单用户快速体验LM Studio适合图形界面调试模型真要上生产、扛并发还是vLLM这一路最靠谱。SGLang和vLLM思路相似但生态和兼容性目前vLLM更成熟。3.2 KV Cache与gpu-memory-utilization的关系KV cache的作用你可以理解成“对话的历史笔记”。每次推理都要看之前所有token的Key和Value笔记留得越多后续生成速度越快。但笔记占用的显存也越多。vLLM在加载完模型权重后会计算剩余显存按你指定的--gpu-memory-utilization比例给KV cache分配空间。比如显存48GB模型权重占14GBgpu_memory_utilization0.9那么KV cache大概能用(48-14)*0.9约30GB。这部分空间除以每个token需要的KV cache大小就能估算出最大并发数和最大上下文长度。调优思路就一句话找到模型权重之外的显存提高到KV cache的利用率同时留出足够冗余避免OOM。3.3 实操从OOM到稳定的参数组合我拿一张24GB的RTX 3090跑Qwen2.5-7B-Instruct举例。第一次启动直接默认参数结果OOM登录日志里报CUDA out of memory。排查过程是这样的第一轮调整先降--gpu-memory-utilization到0.85同时把--max-model-len降到4096vllm serve Qwen/Qwen2.5-7B-Instruct \ --gpu-memory-utilization 0.85 \ --max-model-len 4096这轮能启动了但并发上来后还是报KV cache不足。日志里有明显提示No available memory for the cache blocks in the memory pool说明KV cache分配得不够。第二轮的思路是既然GPU显存就24GB模型权重14GB那KV cache理论上能拿(24-14)*0.85约8.5GB。如果4096长度下单个序列的KV cache开销大约0.5GB那并发数理论上能做到十几个但实际还受激活值影响。我继续调优时发现把--max-model-len再降到2048并发能力显著提升因为每个序列占用的KV cache减半了。如果你跑长文档场景比如max-model-len32768那KV cache占用会暴涨同样的显存能支撑的并发就会少很多。所以生产环境我通常是先确认业务主路径的上下文长度再决定max_model_len而不是一味给大。3.4 量化让权重瘦身给KV cache腾地方如果模型权重太大剩余显存所剩无几KV cache也就没空间了。解决办法是量化。以Qwen2.5-7B为例用AWQ量化版vllm serve Qwen/Qwen2.5-7B-Instruct-AWQ \ --quantization awq \ --gpu-memory-utilization 0.9量化后权重从14GB降到5GB左右24GB的卡上KV cache能多出9GB并发能力大幅提升。代价是生成质量有轻微下降但在业务场景里完全可接受。另一种是FP8量化需要显卡支持比如L20、H20这类。命令vllm serve /models/qwen2.5-7b-fp8 \ --kv-cache-dtype fp8 \ --dtype float16--kv-cache-dtype fp8是把KV cache本身也压成FP8显存进一步节省。实测下FP8精度损失很小但注意只有部分模型和显卡能吃到这个红利跑之前查一下支持列表。3.5 多卡张量并行如何分配显存单卡实在塞不下时再加一张卡。vLLM用--tensor-parallel-size做张量并行把模型权重切到多张卡上。比如两张24GB卡跑14GB权重的7B模型vllm serve Qwen/Qwen2.5-7B-Instruct \ --tensor-parallel-size 2 \ --gpu-memory-utilization 0.9张量并行的逻辑是每张卡只存一部分权重前向传播时需要卡间通信。但要提醒的是如果模型权重单卡能装下没必要为了追求更大KV cache强行多卡并行因为通信开销可能吃掉增益。我有个32B模型场景单卡80GB A100能承载但我为了更高的并发上限拆成2卡吞吐不升反降。多卡更适用于单卡完全放不下的情况。多卡并行还有一个容易踩的坑两张卡的显存如果不一样以小的那张为准。之前我在一张24G和一张48G的机器上跑双卡显存直接崩后来把两张卡换成了同型号问题消失。3.6 显存监控和动态观察调优不能靠猜要会看监控。启动vLLM之后日志里会直接打出KV cache池大小单位是块。比如Maximum concurrency for 8192 tokens per request: 8这个数字就是当前配置下的理论最大并发。然后你可以同时开另一个窗口看显存watch -n 1 nvidia-smi重点看MiB和Volatile GPU-Util。推理过程中显存会稳步上升如果一直顶着上限说明KV cache分配得太满可以考虑降gpu_memory_utilization或缩短max_model_len。如果利用率长期在70%以内说明还有调大并发或长度的空间。还能通过日志开头的模型加载时间判断性能。加载时间长不一定是坏事vLLM正在对算子做图优化。4. 常见问题与排查实录4.1 启动报CUDA Out of Memory这个报错出现最多基本是显存不够。排查顺序如下先看是不是别的进程占了显存nvidia-smi看PIDkill掉无关进程。确认显卡驱动能看到卡跑python -c import torch; print(torch.cuda.device_count())如果输出0说明PyTorch和显卡之间没打通重装匹配的CUDA版本。手动降低--gpu-memory-utilization和--max-model-len。如果降到0.6还是OOM说明模型超过显存物理上限考虑量化或换小模型。4.2 端口被占用启动时报[Errno 98] Address already in use。查看端口占用lsof -i :8000 kill -9 PID如果不想杀进程直接改启动端口最省事。4.3 Docker里看不到GPU容器启动后nvidia-smi报错大概率是没用--gpus all参数。检查一下docker run --gpus all --rm nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi这个测试镜像能跑通再来看vLLM。另外新版Docker要用--runtime nvidia老版本只需要--gpus。4.4 模型下载卡住或一直转圈首次启动会在HuggingFace下载模型。如果网络不稳定最靠谱的方案是先把模型下到本地再通过--model /本地路径启动。比如# 先在机器上下载好然后指定路径 vllm serve /data/models/qwen2.5-7b-instruct这样启动快也方便离线环境部署。注意本地路径的模型结构要和vLLM预期一致就是有config.json、tokenizer.json那套目录结构。4.5 Embedding模型如何加载热搜词里提到vllm/vllm-openai:v0.27.1加载qwen3-embedding-0.6b这个正好是Embedding场景。命令docker run --gpus all \ -v /data/models:/models \ -p 8000:8000 \ vllm/vllm-openai:v0.27.1 \ --model /models/qwen3-embedding-0.6b \ --task embedding \ --max-model-len 8192调用时走/v1/embeddings接口curl http://localhost:8000/v1/embeddings \ -H Content-Type: application/json \ -d { model: /models/qwen3-embedding-0.6b, input: vLLM部署Embedding模型 }返回的向量数组就是结果。注意Embedding模型的--task参数很关键不同版本可能叫embedding或embed老版本里不设置会默认走对话模型逻辑导致接口404。4.6 生成速度慢或请求报长度超限如果单请求生成很慢先看是不是max_model_len设太大。模型加载时KV cache是按最大长度规划的你设了32768实际每条请求只用了很少的token等于白白浪费了显存配额并发也被压缩了。日志里通常会有提示说当前配置最多支持几个并发。要把长度收敛到业务实际值附近。另一种情况是ContextLengthExceededError说明max_model_len小于输入加输出的总长度。这时只能调大长度同时接受并发下降或者改用量化释放显存。4.7 常见问题速查表现象常见原因解决方式启动即OOM显存不足或utilization过高降gpu_memory_utilization降max_model_len并发一多就报KV cache不足max_model_len设置过长缩短长度或量化、加卡容器内无GPU少了--gpus all补参数并验证容器内nvidia-smi端口冲突已有进程占用换端口或kill旧进程Embedding接口404缺--task embedding启动时指定--task推理结果重复或为空温度设置不当调temperature、top_p检查prompt格式加载模型巨慢网络下载或本地磁盘IO提前下到本地放SSD5. 一些实操心得和补充建议如果你是在生产环境用我建议把模型、vLLM版本、启动参数这三样一起锁死。同一个模型配不同vLLM版本行为差异可能很大尤其是KV cache管理和量化策略。我踩过最直观的坑就是升级vLLM后发现并发上限莫名其妙缩水排查半天才意识到是新版本默认预留的显存比例变了。参数调优时遵守“一次只改一个变量”的原则。先固定模型和长度单独调gpu_memory_utilization再固定利用率调max_model_len最后用并发压测脚本验证。这个顺序能帮你快速定位瓶颈。还有一个小技巧日志里每次启动都会打印KV cache的分配情况和最大并发数这行信息我建议保留到监控里。它是最好的调优标尺比在界面上猜要准确得多。对于已经跑熟Ollama、想继续深挖的人来说vLLM的Learning Curve没有想象中陡。装一次环境、起一次服务、跑一轮并发压测基本就上手了。如果只是个人日常使用Ollama确实更方便没必要为了技术指标折腾自己但如果你要面对多用户、多请求、生产环境vLLM这一套迟早要学。两者之间切换的成本很低模型是通用的启动命令也差不多。这篇文章写到这核心内容基本覆盖了安装、启动、显存调优、问题排查四个环节。在实际操作中我最大的体会是vLLM调优不是一个固定数值而是一个动态寻找平衡点的过程——你的业务上下文长度、并发量、显卡规格都会改变最优参数。下次再遇到显存不够或并发上不去的场景希望你能带着这篇文章里的排查思路一步步找到自己的最优解。