vLLM启动参数介绍

前言

vllm serve 的启动参数，可以分为 所有模型通用参数 和 其他（进阶 / 特性）参数 两部分。

启动方式

启动命令	请求格式	是否 OpenAI 兼容
vllm serve ... 或 python -m vllm.entrypoints.openai.api_server ...	✅ OpenAI 格式	✔️ 是（推荐）
python -m vllm.entrypoints.api_server ...	❌ vLLM 自定义格式	✖️ 否（旧版，不推荐）

注意

强烈推荐使用 vllm serve，它默认启用 OpenAI 兼容接口，这也是当前社区和文档主推的方式。

所有模型通用参数

这些参数在大多数模型上都适用，主要影响服务地址、显存占用和并行策略等。

环境变量

• VLLM_USE_MODELSCOPE=true：让 vLLM 从 ModelScope 源拉取模型/权重，适用于国内网络环境或镜像中已有的 ModelScope 集成。

模型名称

• MODEL_NAME（位置参数）：指定要加载的模型仓库/路径，如 taoxiaoxin/DeepSeek-V3.2-w4a8。
• --served-model-name：对外暴露的模型名字，一般与 MODEL_NAME 保持一致即可。

服务地址相关

• --host 0.0.0.0：监听地址，0.0.0.0 表示对所有网卡开放，一般用于容器/服务器环境。
• --port ${MODEL_PORT}：服务端口，由环境变量 MODEL_PORT 控制，默认 8001。

显存与内存控制

• --gpu-memory-utilization 0.85：单卡显存使用上限比例，0.85 表示最多用到 85% 显存，避免完全打满导致 OOM。
• --swap-space 16：为 KV cache 预留的 CPU 内存（GiB），在显存不足时可将部分缓存放到 CPU 内存中。

并行与性能相关

• --tensor-parallel-size ${GPU_NUM}：张量并行的 GPU 数，通常设置为实际 GPU 数量（例如 8 卡则填 8），决定模型在多卡上的拆分方式。
• --pipeline-parallel-size 1：管线并行阶段数，1 表示关闭管线并行，大多数场景可保持为 1。
• --max-num-seqs 8：单次可并行处理的最大请求（序列）数量，数值越大吞吐潜力越高，但显存压力也越大。
• --enable-chunked-prefill：开启分块 prefill，可在长输入时提升吞吐与显存利用率。

上下文与批处理

• --max-model-len 32768：模型最大上下文长度（token 数），支持的最大输入+输出长度上限。

如果显存不够调整这个最有效

场景	推荐 max-model-len
普通对话 / RAG	4096 或 8192
长文档问答	16384
极长上下文（必须 32K）	保留 32768，但需配合其他优化

• --max-num-batched-tokens 4096：单批次最大 token 数，多请求合并计算时，用于控制显存占用和批处理大小。

代码信任相关

• --trust-remote-code：允许加载模型仓库中自定义代码（modeling_xxx.py 等），很多定制模型需要开启，否则无法正常加载。

其他（进阶 / 特性）参数

这些参数与工具调用、多专家模型、分布式后端等高级特性相关，可按需开启。

工具调用 / 推理风格

• --enable-auto-tool-choice：开启自动选择工具的能力，适合有“函数调用 / 工具调用”能力的模型。
• --tool-call-parser deepseek_v3：指定工具调用解析器，这里使用 deepseek_v3 风格。
• --reasoning-parser deepseek_r1：指定推理过程解析器（如类似 DeepSeek-R1 的推理格式）。

前缀缓存与编解码优化

• --no-enable-prefix-caching：关闭 prefix caching。默认开启可在多请求共享前缀时节省计算；如遇到兼容性问题可显式关闭。

分布式执行 / 多机多卡

• --distributed_executor_backend ray：指定分布式执行后端为 ray，用于多机多卡或复杂分布式场景，需要 Ray 正确安装和配置。

量化与模型格式

• gptq：GPTQ 量化，支持多种架构（Volta 及以上、部分 CPU / Intel GPU），通常用于加载已 GPTQ 量化好的权重。
• awq（或 autoawq）：AWQ 量化，适合 Turing 及以上架构以及 Intel GPU / x86 CPU，常见于 AutoAWQ 量化的模型。
• bnb-nf4 / bnb-int8 等 bitsandbytes 方案：依赖 bitsandbytes 库，可在加载时直接做 4/8 bit 量化。
• int4 / w4a16 / w8a8 等：权重/激活的低比特量化（如 INT4 W4A16），对显存节省明显，但对硬件有要求（一般需要 Ampere 及以上）。
• 其他厂商 / 硬件相关值（如ascend）：通常对应特定 NPU / 加速卡的定制量化实现，需要参考该硬件或镜像的文档。

专家并行（MoE 等）

• --enable-expert-parallel：启用专家并行，用于多专家（MoE）模型的多卡分布式推理。只有在模型本身是 MoE 且官方文档建议开启时才需要使用。

使用建议

实际使用时，建议：

• 先只调整通用参数（端口、显存比例、tensor-parallel-size 等），确保服务能正常启动。
• 确认模型支持的特性后，再按需打开 工具调用、专家并行、分布式后端、量化 等进阶参数。