https://docs.vllm.ai/en/stable/configuration/engine_args/#loraconfig

下面按部署时最常用的类别整理。不同 vLLM 版本参数会有差异，最准的方法是看当前环境：

vllm serve --help
vllm serve --help=max
vllm serve --help=SchedulerConfig
vllm serve --help=CacheConfig

官方也建议用 vllm serve --help=<参数或分组> 查版本内真实可用参数。

服务入口参数

--host 0.0.0.0
--port 8000
--api-key xxx
--served-model-name my-model
--uvicorn-log-level info

作用：

--host：监听地址
--port：监听端口
--api-key：开启 API key 校验
--served-model-name：对外暴露的模型名
--uvicorn-log-level：服务日志级别 

模型加载参数

--model /path/to/model
--tokenizer /path/to/tokenizer
--trust-remote-code
--dtype bfloat16
--revision main
--tokenizer-revision main
--load-format auto

作用：

--model：模型路径或 Hugging Face 模型名
--tokenizer：单独指定 tokenizer
--trust-remote-code：允许执行模型自定义代码
--dtype：权重/计算精度，如 auto、float16、bfloat16
--revision：模型版本
--load-format：加载格式，如 auto、safetensors、pt、gguf 等

显存和上下文参数

--max-model-len 32768
--gpu-memory-utilization 0.85
--kv-cache-dtype auto
--swap-space 4
--cpu-offload-gb 0 

作用：

--max-model-len：单次请求最大上下文 token 数
--gpu-memory-utilization：vLLM 可用 GPU 显存比例
--kv-cache-dtype：KV cache 精度，如 auto、fp8 等，版本/硬件相关
--swap-space：每张 GPU 可用的 CPU swap 空间，单位 GB
--cpu-offload-gb：把部分权重 offload 到 CPU，省显存但会变慢

并行参数

--tensor-parallel-size 4
--pipeline-parallel-size 1
--data-parallel-size 1

作用：

--tensor-parallel-size：张量并行，把模型切到多张 GPU
--pipeline-parallel-size：流水线并行，把不同层切到不同 GPU
--data-parallel-size：数据并行，多副本服务

常见单机多卡部署一般先用：

--tensor-parallel-size 4 

调度和吞吐参数

--max-num-seqs 32
--max-num-batched-tokens 8192
--enable-chunked-prefill
--enable-prefix-caching

作用：

--max-num-seqs：一次调度最多处理多少条序列
--max-num-batched-tokens：一次调度最多处理多少 token
--enable-chunked-prefill：长 prompt 分块 prefill
--enable-prefix-caching：相同前缀复用 KV cache

这几个非常影响速度。一般在线服务可以从：

--max-num-seqs 16 \
--max-num-batched-tokens 8192 \
--enable-chunked-prefill \
--enable-prefix-caching

开始压测。

量化参数

--quantization awq
--quantization gptq
--quantization bitsandbytes

作用：

--quantization：加载量化模型，降低显存占用 

例如 AWQ/GPTQ 模型通常需要对应的量化格式。量化可以省显存，但速度不一定总是更快，要看 GPU 和量化 backend。

LoRA 参数

--enable-lora
--lora-modules name=/path/to/lora
--max-lora-rank 32
--max-loras 4
--max-cpu-loras 8

作用：

--enable-lora：启用 LoRA
--lora-modules：启动时加载 LoRA
--max-lora-rank：允许的最大 LoRA rank
--max-loras：单批次最多同时使用多少个 LoRA
--max-cpu-loras：CPU 中最多缓存多少个 LoRA

多模态参数

--limit-mm-per-prompt '{"image": 2}'
--allowed-local-media-path /data/images/
--mm-processor-cache-type shm
--mm-encoder-tp-mode data

作用：

--limit-mm-per-prompt：限制每个请求最多几张图/几个视频
--allowed-local-media-path：允许读取的服务端本地媒体路径
--mm-processor-cache-type：多模态预处理缓存类型
--mm-encoder-tp-mode：多模态 encoder 的并行方式

传 base64 图片时通常不需要 --allowed-local-media-path。

推测解码参数

--speculative-config '{"model": "/path/to/draft", "num_speculative_tokens": 4}'

作用：

启用 draft 模型提前猜 token，主模型验证，用来加速生成 

注意：推测解码不一定必然加速。draft 模型太大、命中率低、配置不适配时可能变慢。

Chat Template / Qwen3 工具调用

--chat-template /path/to/template.jinja
--default-chat-template-kwargs '{"enable_thinking": false}'
--reasoning-parser qwen3
--enable-auto-tool-choice
--tool-call-parser qwen3_coder

作用：

--chat-template：指定聊天模板
--default-chat-template-kwargs：模板默认参数，比如关闭 thinking
--reasoning-parser：解析 reasoning/thinking 输出
--enable-auto-tool-choice：允许 tool_choice=auto
--tool-call-parser：解析模型输出为 OpenAI tool_calls

日志和观测

--disable-log-stats
--enable-request-id-headers

作用：

--disable-log-stats：关闭周期性统计日志
--enable-request-id-headers：支持 X-Request-Id 请求头

--enable-request-id-headers 在高 QPS 下可能有性能影响，官方也建议高并发场景可放到网关层处理。

常用在线服务模板

如果是 4 卡 27B，普通聊天/工具调用，先用这个方向比较稳：

python -m vllm.entrypoints.openai.api_server \
  --model /hy-tmp/hz/models-hub/Qwen3.5-27B \
  --host 0.0.0.0 \
  --port 8005 \
  --dtype bfloat16 \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.85 \
  --max-model-len 32768 \
  --max-num-batched-tokens 8192 \
  --max-num-seqs 16 \
  --enable-chunked-prefill \
  --enable-prefix-caching \
  --default-chat-template-kwargs '{"enable_thinking": false}' \
  --reasoning-parser qwen3 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder \
  --trust-remote-code

你最需要重点调的通常是这几个：

--max-model-len
--max-num-batched-tokens
--max-num-seqs
--gpu-memory-utilization
--tensor-parallel-size
--enable-chunked-prefill
--enable-prefix-caching
--speculative-config

参考官方文档： ​编辑vLLM Engine Arguments ​编辑vLLM CLI Reference ​编辑vLLM OpenAI-Compatible Server

vLLM 引擎（vLLM Engine）的所有配置参数。vLLM 是一个用于大语言模型（LLM）高性能推理的库。

这些参数用于控制 vLLM 的行为，无论是在离线推理（使用 LLM 类）还是在线服务（使用 vllm serve 命令）中。

为了便于理解，我将这些参数按功能分组，并解释其核心作用。

1. 核心模型与运行模式

• --model: 指定要使用的模型，例如 meta-llama/Llama-2-7b-hf。默认是一个小模型 Qwen/Qwen3-0.6B。

• --tokenizer: 指定分词器。通常与模型相同，但也可以单独指定。

• --dtype: 模型的数据类型，如 float16（半精度）、bfloat16、float32（单精度）。选择 auto 会让 vLLM 自动决定。正确的数据类型可以节省显存并加速计算。

• --quantization (-q): 量化方法，如 awq、gptq、squeezellm。量化可以大幅减小模型体积和显存占用，常用于在消费级 GPU 上运行大模型。

• --max-model-len: 模型的最大上下文长度（输入 + 输出）。如果设置太小，长文本会被截断；设置太大，可能会耗尽显存。支持 1k（1000）、25.6k 等人类可读格式。

• --trust-remote-code: 是否信任并执行模型仓库中的自定义代码。出于安全考虑，默认为 False，但某些模型（如 Qwen）需要开启。

2. 分布式与并行策略

• --tensor-parallel-size (-tp): 张量并行度。将单个模型层切分到多个 GPU 上。适合单个 GPU 显存放不下整个模型的情况。

• --pipeline-parallel-size (-pp): 流水线并行度。将模型的不同层分配到不同 GPU 上。通常与 TP 结合使用。

• --data-parallel-size (-dp): 数据并行度。复制多份完整的模型，每份处理不同的请求。主要用于提高吞吐量，尤其适合 MoE（混合专家）模型。

• --distributed-executor-backend: 分布式后端，可选 ray 或 mp（多进程）。Ray 适合复杂、多节点的场景，mp 适合单机多卡。

• --nnodes, --node-rank: 在多节点分布式推理中，指定总节点数和当前节点的编号。

3. 性能优化与显存管理

• --gpu-memory-utilization: GPU 显存利用率。vLLM 最多使用多少比例的 GPU 显存。默认为 0.9 (90%)。调低可以为其他程序留出空间，调高可能提高性能但增加 OOM 风险。

• --block-size: KV Cache 的块大小（token 数）。KV Cache 是 vLLM 高效推理的核心机制，用于缓存已生成的键值对。

• --enable-prefix-caching: 启用自动前缀缓存。如果多个请求有相同的前缀（如系统提示词），可以共享 KV Cache，大幅减少重复计算，提升吞吐量。

• --max-num-batched-tokens: 单次迭代（Step）中最多处理的 token 数量。影响吞吐量和延迟。

• --max-num-seqs: 单次迭代中最多同时处理的序列（请求）数量。

• --enforce-eager: 是否强制使用 Eager 模式（而非 CUDA Graph）。CUDA Graph 可以大幅减少 kernel 启动开销，提升性能，但会增加显存占用。关闭（设为 False）通常性能更好。

• --enable-chunked-prefill: 启用分块预填充。将一个长的用户输入（Prompt）分成多个块处理，可以防止长输入阻塞其他请求，降低首 token 延迟。

4. 解码与输出控制

• --max-logprobs: 最多返回多少个 token 的对数概率（logprobs）。默认 20。

• --seed: 随机种子。必须设置以保证多卡并行时结果可复现。

• --served-model-name: 在 API 服务中暴露的模型名称。可以不同于 --model 的路径。

5. 高级特性与插件

• --enable-lora: 启用 LoRA 适配器支持。允许在不重新加载整个模型的情况下，动态切换微调后的 LoRA 权重。

• --max-loras: 一批次中最多同时处理多少个不同的 LoRA 适配器。

• --speculative-config (-sc): 配置推测解码。使用一个小的 draft 模型加速主模型的生成。

• --compilation-config (-cc): 配置 torch.compile 和 CUDA Graph 的详细行为。用于深度性能调优。

• --attention-backend: 手动选择 Attention 算子后端，如 FlashAttention、FlashInfer 等。通常让 vLLM 自动选择即可。

6. 多模态与结构化输出

• --limit-mm-per-prompt: 限制每个 prompt 中多模态数据（如图片、视频）的数量。

• --reasoning-parser: 为支持推理过程的模型（如 DeepSeek-R1）选择解析器，将其内部思考过程解析为 OpenAI API 的格式。

• --structured-outputs-config: 配置结构化输出（如 JSON Schema），确保模型输出符合预定义的格式。

7. 监控与调试

• --disable-log-stats: 禁用统计日志记录。

• --otlp-traces-endpoint: 发送 OpenTelemetry 追踪数据的目标 URL，用于性能监控。

• --enable-log-requests (AsyncEngineArgs 部分): 在服务器模式下，打印每个请求的详细信息（ID、参数等）。

如何理解和使用

• 默认值通常很合理：vLLM 旨在开箱即用。对于许多模型，只需要设置 --model 就能运行。

• 显存不足（OOM）：可以调低 --gpu-memory-utilization (如 0.8)，或开启 --quantization，或减小 --max-model-len。

• 速度慢：可以尝试增加 --max-num-batched-tokens 和 --max-num-seqs，并确保 --enforce-eager 为 False (默认)。

• 多卡运行：根据模型大小和你的卡数设置 --tensor-parallel-size。

• 详细配置：文末提到的 vllm.config 中的各个配置类（如 ModelConfig, ParallelConfig）是这些参数的最终来源，如果你需要开发或深度调优，可以直接查阅那些文档。

总结：这份文档是 vLLM 的使用手册。核心参数集中在模型选择、数据类型、并行策略和显存管理上。根据模型大小、硬件资源和性能需求，调整这些参数即可。