VLLM部署大模型常用参数介绍

vLLM 的参数非常多，而且会随版本变化。最稳妥的方式是：在部署机器上执行 vllm serve --help 看当前版本真实支持的参数。

下面按生产部署常用维度整理一份，不是逐字枚举全部，但覆盖 vllm serve 核心参数。

参数介绍

1. 服务与 API 参数

表格

参数	说明
--host	API 监听地址，如 0.0.0.0
--port	API 端口，默认常用 8000
--api-key	开启 API Key 校验
--served-model-name	对外暴露的模型名，调用时 model 字段要用它
--ssl-certfile / --ssl-keyfile	HTTPS 证书和私钥
--uvicorn-log-level	服务日志级别，如 info、debug
--disable-log-requests	禁用请求日志
--disable-fastapi-docs	禁用 FastAPI 文档页面

2. 模型加载参数

表格

参数	说明
--model	模型路径或 HuggingFace 模型 ID，必填
--tokenizer	分词器路径，不填则默认使用模型自带分词器
--revision	模型版本，如分支、tag、commit id
--tokenizer-revision	分词器版本
--trust-remote-code	允许加载 HF 远程代码，Qwen 等模型常需要
--load-format	权重加载格式：auto、safetensors、pt、gguf、bitsandbytes 等
--download-dir	模型下载目录
--tokenizer-mode	分词器模式：auto、slow、mistral 等
--skip-tokenizer-init	跳过分词器初始化
--config-format	模型配置格式，如 auto、hf、mistral

3. 精度与量化参数

表格

参数	说明
--dtype	模型精度：auto、float16、bfloat16、float32 等
--kv-cache-dtype	KV Cache 精度：auto、fp8、fp8_e4m3、fp8_e5m2
--quantization	量化方式：awq、gptq、fp8、bitsandbytes 等
--quantization-param-path	量化参数文件路径，FP8 KV Cache 等场景可能需要

4. 显存与上下文参数

表格

参数	说明
--max-model-len	最大上下文长度
--gpu-memory-utilization	GPU 显存使用比例，默认 0.9
--swap-space	每张 GPU 的 CPU swap 空间，单位 GiB
--block-size	PagedAttention 块大小，如 16、32
--cpu-offload-gb	将部分权重卸载到 CPU，省显存但会变慢
--num-gpu-blocks-override	手动覆盖 GPU block 数量，多用于调试
--enable-prefix-caching	启用前缀缓存，适合多轮对话、RAG

5. 并行与分布式参数

表格

参数	说明
--tensor-parallel-size / -tp	张量并行，把模型切到多张 GPU
--pipeline-parallel-size / -pp	流水线并行，把层分布到不同 GPU
--data-parallel-size	数据并行副本数
--distributed-executor-backend	分布式后端：ray、mp 等
--enable-expert-parallel	启用专家并行，MoE 模型相关
--max-parallel-loading-workers	并行加载 worker 数，避免大模型 OOM

6. 调度与吞吐参数

表格

参数	说明
--max-num-seqs	每次调度最大并发序列数
--max-num-batched-tokens	每次 batch 最大 token 数
--enable-chunked-prefill	长 prompt 分块预填充
--scheduler-delay-factor	调度延迟因子，影响批处理等待策略
--max-num-partial-prefills	长请求分块预填充数量控制
--long-prefill-token-threshold	长预填充 token 阈值
--scheduling-policy	调度策略，如 fcfs、priority

7. 工具调用与结构化输出参数

表格

参数	说明
--enable-auto-tool-choice	允许模型根据 tools 自动选择工具调用上一轮回答
--tool-call-parser	工具调用解析器，如 hermes、llama3_json、mistral、qwen3_xml
--chat-template	聊天模板，工具调用常需要匹配模板
--guided-decoding-backend	结构化输出后端：outlines、lm-format-enforcer 等
--enable-reasoning	启用推理模式，部分模型支持
--reasoning-parser	推理输出解析器，如 qwen3、deepseek_r1

8. LoRA / 适配器参数

表格

参数	说明
--enable-lora	启用 LoRA
--max-loras	单批次最多同时使用的 LoRA 数量
--max-lora-rank	最大 LoRA rank
--lora-extra-vocab-size	LoRA 额外词表大小
--lora-dtype	LoRA 数据类型
--max-cpu-loras	CPU 缓存的 LoRA 数量
--enable-prompt-adapter	启用 Prompt Adapter

9. 多模态参数

表格

参数	说明
--limit-mm-per-prompt	每个 prompt 允许的多模态输入数量
--mm-processor-kwargs	多模态处理器参数
--allowed-local-media-path	允许读取的本地媒体文件路径
--image-input-type	图像输入类型

10. 可观测性参数

表格

参数	说明
--otlp-traces-endpoint	OTLP 追踪端点，接入链路追踪
--collect-detailed-traces	收集更详细的追踪数据
--disable-log-stats	禁用统计日志

11. 推理采样参数

这部分通常不在 vllm serve 启动命令里写死 ，而是每次请求时通过 OpenAI 兼容接口传入，例如 temperature、top_p、max_tokens。

表格

参数	说明
temperature	随机性，0 接近贪心，越大越发散
top_p	核采样阈值，如 0.9
top_k	只在前 K 个候选 token 中采样
max_tokens	最大生成 token 数
stop	停止词
repetition_penalty	重复惩罚
frequency_penalty	频率惩罚
presence_penalty	存在惩罚
seed	采样随机种子
logprobs	返回 top-N logprobs

一条典型部署命令

bash

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --served-model-name qwen2.5-7b \
  --host 0.0.0.0 \
  --port 8000 \
  --dtype bfloat16 \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.85 \
  --tensor-parallel-size 2 \
  --enable-prefix-caching \
  --enable-chunked-prefill \
  --max-num-seqs 64 \
  --max-num-batched-tokens 8192 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml \
  --trust-remote-code

模型文件部署

进入你下载好的模型目录，至少应该包含这些文件：

bash

ls /data/models/Qwen2.5-7B-Instruct/

正常会有：

text

config.json
model.safetensors 或 pytorch_model.bin
tokenizer.json
tokenizer_config.json
generation_config.json
special_tokens_map.json
vocab.json 或 tokenizer.model

如果只有一个 .tar、.zip、.gguf，需要先解压或确认格式。

vLLM 默认加载的是 HuggingFace 格式 ，也就是 safetensors / pytorch_model.bin 那一套。

2. 命令行直接部署

bash

vllm serve /data/models/Qwen2.5-7B-Instruct \
  --served-model-name qwen2.5-7b \
  --host 0.0.0.0 \
  --port 8000 \
  --dtype bfloat16 \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.9 \
  --trust-remote-code

这里 /data/models/Qwen2.5-7B-Instruct 就是你本地模型目录的绝对路径。

如果是 Qwen2.5 / Qwen3 / GLM / Yi 这类模型，通常要加：

bash

--trust-remote-code

如果要开工具调用，再加：

bash

--enable-auto-tool-choice \
--tool-call-parser qwen3_xml

具体用哪个 parser，要看模型版本。上一轮回答

3. 多卡部署

比如用 2 张卡：

bash

CUDA_VISIBLE_DEVICES=0,1 vllm serve /data/models/Qwen2.5-7B-Instruct \
  --served-model-name qwen2.5-7b \
  --tensor-parallel-size 2 \
  --gpu-memory-utilization 0.9 \
  --max-model-len 8192 \
  --trust-remote-code

--tensor-parallel-size 要和 CUDA_VISIBLE_DEVICES 里的卡数一致。

4. Docker 部署

bash

docker run --gpus all \
  -v /data/models:/models \
  -p 8000:8000 \
  vllm/vllm-openai:latest \
  /models/Qwen2.5-7B-Instruct \
  --served-model-name qwen2.5-7b \
  --host 0.0.0.0 \
  --port 8000 \
  --trust-remote-code

注意 -v 挂载的是宿主机目录，容器里要用容器内路径。

5. 启动后验证

bash

curl http://localhost:8000/v1/models

返回里有模型名，说明部署成功。

再测一次对话：

bash

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-7b",
    "messages": [{"role": "user", "content": "你好"}]
  }'

调整参数影响

1. 显存类：决定 vLLM 能吃多少 GPU 显存

表格

参数	影响	怎么调
--gpu-memory-utilization	控制 vLLM 可用 GPU 显存比例，默认约 0.9	调高 → KV Cache 更多，并发更高；太高 → 容易 OOM
--dtype	模型权重/激活精度，如 auto、float16、bfloat16	bfloat16 通常更稳；量化模型常用 float16
--kv-cache-dtype	KV Cache 精度，如 auto、fp8	fp8 可省显存，但要看 GPU 和版本支持
--swap-space	GPU 不够时把冷 KV 换到 CPU	能防 OOM，但延迟会变高
--cpu-offload-gb	把部分权重放 CPU	显存严重不足时用，推理会明显变慢

简单理解：显存越大，能放的 KV Cache 越多，同时处理的请求就越多。

2. 上下文类：决定单条请求能多长

表格

参数	影响	怎么调
--max-model-len	输入 + 输出最大 token 数	调大 → 单请求更长，但显存消耗更高
--block-size	PagedAttention 块大小，默认 16	一般不改；长文本可试 32

--max-model-len 是最容易被忽视的。比如模型支持 128K，但你业务只需要 8K，却设成 128K，就会浪费大量 KV Cache 空间。

3. 并发类：决定能同时处理多少请求

表格

参数	影响	怎么调
--max-num-seqs	同时并发的请求序列数	调高 → 吞吐更高；太高 → 显存压力大，vLLM V1 不建议直接沿用 256
--max-num-batched-tokens	每步最多处理多少 token	调高 → GPU 更饱和；太高 → 首 token 延迟可能变差

这两个参数要一起看：

• max-num-seqs 太大：并发高，但 KV Cache 容易不够。
• max-num-batched-tokens 太小：GPU 吃不饱，吞吐上不去。
• max-num-batched-tokens 太大：长 prompt 进来时，首 token 延迟会变差。

在线聊天场景通常把 max-num-batched-tokens 设得小一点，比如 2048-4096；离线批处理可以设大一点，比如 8192-16384。

4. 调度类：决定长请求会不会卡住别人

表格

参数	影响	怎么调
--enable-chunked-prefill	把长 prompt 拆块处理	长文本必开，能减少队头阻塞
--enable-prefix-caching	缓存相同前缀的 KV	RAG、固定 System Prompt 场景收益很大
--scheduling-policy	调度策略，如 fcfs、lof	混合负载下可改善尾延迟

enable-chunked-prefill 和 enable-prefix-caching 可以同时开，它们解决的不是同一个问题：

• Chunked Prefill：解决长 prompt 卡住其他请求。
• Prefix Caching：解决重复前缀反复算。

5. 并行、精度与功能类：决定能不能跑、跑多快、是否支持工具调用

表格

参数	影响	怎么调
--tensor-parallel-size	模型切到多张 GPU	单卡装不下时启用；卡数越多通信开销越高
--pipeline-parallel-size	按层拆分模型	超大模型或跨节点时用
--data-parallel-size	多副本提升吞吐	单卡能装下模型时优先用它扩展吞吐
--quantization	权重量化，如 awq、gptq、fp8	省显存、提吞吐，但要模型和硬件匹配
--enable-auto-tool-choice	允许模型自动选择工具	要 tools 能力必须开
--tool-call-parser	解析模型输出的工具调用	必须和模型匹配，比如 hermes、llama3_json、qwen3_xml
--chat-template	聊天/工具模板	工具调用失败时优先检查它

工具调用这里尤其注意：--enable-auto-tool-choice + --tool-call-parser 必须配对，而且 parser 要和模型一致。

推荐调参顺序

1. 先确认模型能不能跑：--model、--trust-remote-code、--tensor-parallel-size。
2. 再设 --gpu-memory-utilization，从 0.85 起步。
3. 再设 --max-model-len，按业务实际长度来，不要直接开模型最大。
4. 再调 --max-num-seqs、--max-num-batched-tokens。
5. 长文本/共享前缀场景开 --enable-chunked-prefill、--enable-prefix-caching。
6. 需要 tools 再加 --enable-auto-tool-choice、--tool-call-parser、--chat-template。

每次只改一个参数，压测看 首 token 延迟、吞吐、OOM、preemption 告警，比一次性全改更稳