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）性能极佳。

注意力头（Attention Head） 是 Transformer 模型中 Self-Attention（自注意力机制）的核心组成模块。

如果把模型注意力机制比作“看文章”，单个注意力头只能从一种视角去理解文本（例如关注词语之间的语法关系）；而多头注意力（Multi-Head Attention） 允许模型并行使用多个“头”，同时从不同的维度观察上下文（例如头 A 关注主谓关系，头 B 关注代词指代，头 C 关注远距离语义关联）。最后将所有头的输出拼接在一起，形成对文本更全面的理解。

在 GPU 矩阵计算中，多头注意力机制的权重矩阵是按头（Head）切分并分配给不同 GPU 的。

• 每个 GPU 必须分到完整数量的头。
• 例如：模型有 32 个头，如果 -tp 4，则每张 GPU 分配得到 $32 \div 4 = 8$ 个头。
• 如果设置 -tp 3，32 无法被 3 整除，GPU 将无法对齐计算矩阵，因此启动会直接报错。

不需要加载完整模型权重，有以下几种快速获取方式：

在 Hugging Face 或本地模型目录中，找到 config.json 文件：

1. 打开 config.json。
2. 查找以下两个核心字段： * num_attention_heads（或 n_head）：模型的总注意力头数（Q 头数）。 * num_key_value_heads：KV 头数（针对 GQA/MQA 模型，-tp 必须能被此参数整除）。

例如（Llama-3-8B 的 config.json 截取）：

snippet.json

{
  "num_attention_heads": 32,
  "num_key_value_heads": 8
}

在此配置下，-tp 的取值必须能够被 8 整除（即可以取 1、2、4、8）。

无需下载几百吉字节的模型权重文件，只需加载配置对象即可：

snippet.python

from transformers import AutoConfig
 
# 替换为你的模型名称或本地路径
config = AutoConfig.from_pretrained("meta-llama/Meta-Llama-3-8B-Instruct")
 
# 获取总 Attention 头数 (Query Heads)
num_heads = getattr(config, "num_attention_heads", None)
 
# 获取 KV 头数 (Key/Value Heads, GQA 模型关键参数)
num_kv_heads = getattr(config, "num_key_value_heads", num_heads)
 
print(f"总注意力头数 (num_attention_heads): {num_heads}")
print(f"KV 注意力头数 (num_key_value_heads): {num_kv_heads}")

如果你直接运行 vllm serve 命令，当设置的 -tp 无法整除头数时，vLLM 会在终端控制台报错并直接打印出模型的头数信息：

`ValueError: Total number of attention heads (32) must be divisible by tensor parallel size (3).`