vLLM 是用于 LLM 高效推理和服务的高性能框架。以下是其关键启动参数（vllm serve 或 python -m vllm.entrypoints.openai.api_server）的分类详解：

模型与推理基础配置

• --model：指定模型路径或 HuggingFace 模型名称（如 meta-llama/Llama-2-7b-chat-hf）。
• --tokenizer：指定分词器名称或路径，默认与 --model 一致。
• --trust-remote-code：允许执行来自 HuggingFace 的自定义代码（如加载部分新推出的开源模型时必填）。
• --download-dir：指定 HuggingFace 模型权重的本地缓存与下载目录。
• --revision：指定 HuggingFace 模型的具体分支、标签或 Commit ID。

GPU 资源与并行度

• --tensor-parallel-size (-tp)：张量并行（Tensor Parallelism）的 GPU 数量。跨卡切分单模型时使用（如 8 卡单机设为 8）。
• --pipeline-parallel-size (-pp)：流水线并行（Pipeline Parallelism）的 GPU 数量。通常优先增加 -tp，在跨节点或卡数极多时配合使用。
• --gpu-memory-utilization：指定 vLLM 可调用的 GPU 显存比例，范围 0.0 到 1.0（默认约为 0.9）。预留显存给 KV Cache，若出现 OOM 可调小至 0.85 或 0.8。
• --max-model-len：模型最大上下文序列长度（包含输入与输出）。若显存不足，降低此参数可大幅减少 KV Cache 显存占用。
• --cpu-offload-gb：从 GPU 卸载到 CPU 内存的权重规模（以 GB 为单位），适用于显存严重不足的单卡环境。

量化与数据类型

• --dtype：模型计算与权重的精度数据类型。可选 auto、float16、bfloat16、float32。Ampere 架构（如 A100/H100/3090/4090）建议设为 bfloat16 或 auto。
• --quantization (-q)：指定量化方法。可选 awq、gptq、squeezellm、fp8、bitsandbytes 等。若模型已提前量化，传入对应类型即可。
• --kv-cache-dtype：指定 KV Cache 的数据类型。支持 auto、fp8（如 fp8_e4m3），使用 FP8 储存 KV 缓存可减少显存占用并显著提升并发能力。

性能与调度调优

• --max-num-seqs：单次批处理（Batch）中处理的最大并发序列数（默认 256）。
• --max-num-batched-tokens：单次批处理中处理的最大 Token 数量（默认 2048）。
• --enforce-eager：强制禁用 CUDA Graph 并使用 Eager 执行模式。虽稍微降低推理性能，但能省下 CUDA Graph 占用的显存，且便于 Debug。
• --swap-space：CPU 内存中分配用于 KV Cache 抢占交换的空间大小（以 GB 为单位，默认 4）。

服务与 API 配置

• --host：绑定的服务 IP 地址，例如 0.0.0.0（对外开放）或 127.0.0.1（仅本地访问）。
• --port：服务监听端口，默认 8000。
• --api-key：设置访问 API 所需的密钥，提升服务安全性。
• --served-model-name：在 API 响应（如 /v1/models 接口）中显示的替代模型名称，方便客户端识别。

典型启动命令示例

• 单卡运行 7B/13B 模型： bash vllm serve meta-llama/Llama-2-7b-chat-hf \ --host 0.0.0.0 \ --port 8000 \ --gpu-memory-utilization 0.9 \ --max-model-len 4096
• 多卡张量并行 + 量化运行大模型： bash vllm serve Qwen/Qwen2.5-72B-Instruct-AWQ \ --tensor-parallel-size 4 \ --quantization awq \ --dtype bfloat16 \ --host 0.0.0.0 \ --port 8000 ## 张量并行参数取值范围

--tensor-parallel-size（简称 -tp）的取值主要受以下 3 个核心规则限制：

这是最硬性的数学限制。张量并行会将模型的 Attention 头（Attention Heads）均匀切分到各个 GPU 上。

• 单头切分限制：模型的 num_attention_heads 必须能被 -tp 整除。例如：若模型的注意力头数为 32，-tp 可以设为 1、2、4、8、16、32；但不能设为 3、5、6、7。
• GQA / MQA 模型特别注意：对于采用了分组查询注意力（Grouped-Query Attention）的模型（如 Llama 3、Qwen 2 等），-tp 的取值还必须能被 Key-Value 头数（num_key_value_heads）整除。

*例子*：若某模型的 KV Heads 为 8，则 `-tp` 最大只能设为 8（即便总 Head 数是 64），且只能取 1、2、4、8。

虽然理论上只要能整除头数即可（如 6 或 12），但在实际硬件通信中：

• 通信环路与拓扑：NCCL（NVIDIA 集合通信库）对 2 的幂次方（1、2、4、8）做了极大的传输优化（如 Tree / Ring 算法）。
• 非 2 的幂次方后果：使用 3、5、6、7 等卡数会导致显存不均匀分布和严重的跨卡通信开销，推理延迟反而可能比少用一张卡更高。

-tp 在每生成一个 Token 时，跨卡之间都需要进行多次 All-Reduce 集合通信，对传输带宽极度敏感。

• 最佳实践：-tp 的最大值不要超过单台服务器的物理 GPU 卡数（通常单机最多 8 卡）。跨卡走 NVLink（如 900 GB/s - 3.2 TB/s）性能极佳。