vLLM 解决什么问题
vLLM 是 GPU 上的大模型推理与服务引擎。它的核心贡献是把 KV 缓存按固定大小的块管理（PagedAttention），思路类似操作系统分页：显存不再要求连续，块可以在请求之间复用，碎片浪费从整块级降到块内。它自带 OpenAI 兼容的 HTTP 服务，把开源权重变成在线 API 只需要一条命令。
基本信息
| 定位 | 高吞吐 LLM 与多模态模型推理、服务引擎 |
|---|---|
| 关键机制 | PagedAttention、连续批处理、前缀缓存 |
| 接口 | OpenAI 兼容 /v1/*，默认监听 8000 |
| 依赖 | NVIDIA GPU + 匹配的驱动与 CUDA 运行时 |
| 安装方式 | pip 安装匹配版本的 wheel，或官方镜像 vllm/vllm-openai |
典型使用场景
- 把开源权重（Qwen、Llama 等）封装成团队内部可用的在线接口
- 替换按量计费的云 API：本地卡跑满后单位 token 成本显著下降
- 承接高并发对话服务：连续批处理让多请求共享同一次权重读取
- 多轮对话与固定系统提示：前缀缓存复用公共 KV，降低首 token 延迟
- 批量离线任务：用离线接口一次喂多条提示，不需要起 HTTP 服务
- 同一基座挂载多个 LoRA 适配器，按请求切换不同微调变体
安装与启动
安装与启动
# 安装：优先官方预编译 wheel，源码编译容易踩 CUDA 工具链
pip install vllm
# 新版统一入口，拉起 OpenAI 兼容服务
vllm serve <模型名或本地路径> --host 0.0.0.0 --port 8000
# 旧版等价入口，历史脚本里常见
python -m vllm.entrypoints.openai.api_server --model <模型名或本地路径>
# 验证服务与对外模型名
curl http://127.0.0.1:8000/v1/models离线批量推理
离线批量推理
from vllm import LLM, SamplingParams
sp = SamplingParams(temperature=0.2, max_tokens=256)
llm = LLM(model="/models/Qwen", tensor_parallel_size=1) # 单卡加载
outs = llm.generate(["介绍一下 KV 缓存", "什么是张量并行"], sp)
for o in outs:
print(o.outputs[0].text) # 逐条输出生成结果关键参数与端点
| 项 | 说明 |
|---|---|
| --host / --port | 服务监听地址与端口，公网暴露前须经网关 |
| --tensor-parallel-size | 张量并行卡数，单卡装不下权重时按卡切分 |
| --gpu-memory-utilization | 显存占用上限比例，同时决定 KV 池大小 |
| --max-model-len | 单请求上下文上限，KV 池按此预留 |
| --quantization | 量化内核，如 awq / gptq / fp8，需与权重格式一致 |
| /v1/chat/completions | 主对话端点，请求体兼容 OpenAI 协议 |
vLLM 迭代较快：同一参数在不同大版本里可能改名或改默认值。上生产前固定版本号，并用 vllm serve --help 核对本机参数表，不要照抄半年前的教程。
显存不足时 vLLM 不总是直接报错：调度器会抢占部分序列重算，表现为个别请求延迟突然变长。看到这种抖动先查 KV 池水位与 --max-num-seqs，而不是只怀疑网络。
上线前核对命令
上线前核对命令
# 固定版本：pip 与镜像都要能查到具体版本号
pip show vllm | grep -i version
nvidia-smi --query-gpu=name,driver_version --format=csv # 驱动与卡型是否在支持范围
# 服务起来后先核对对外模型名与最大并发设置
curl -s http://127.0.0.1:8000/v1/models
ss -lntp | grep 8000 # 确认监听地址是内网而非 0.0.0.0 公网口
# 压测前后各看一次显存，确认没有持续上涨
nvidia-smi --query-gpu=index,memory.used --format=csv多实例共享一张卡时先算总账：两个引擎各自按百分比申请显存，比例之和超过 1 就会在启动或压测中途失败，规划时按单卡容量乘各自比例相加核对。
上线前核对项
- 权重目录是否完整：config.json、tokenizer 相关文件与分片索引文件缺一不可，缺索引会在加载阶段直接失败
- 对外模型名是否固定：客户端写死别名之后，换权重、换量化都不需要改业务代码
- 显存是否留余量：KV 池按 P95 上下文长度核算，不要用平均长度估算并发上限
- 是否由网关暴露：鉴权、限流、日志与请求编号都放在网关层，引擎只监听内网地址
- 版本是否固定：镜像 tag 与 pip 版本都写具体号，避免重建时被静默升级