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 接口）中显示的替代模型名称，方便客户端识别。典型启动命令示例
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。-tp 的取值还必须能被 Key-Value 头数（num_key_value_heads）整除。*例子*：若某模型的 KV Heads 为 8，则 `-tp` 最大只能设为 8（即便总 Head 数是 64），且只能取 1、2、4、8。
虽然理论上只要能整除头数即可（如 6 或 12），但在实际硬件通信中：
-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 的。
-tp 4，则每张 GPU 分配得到 $32 \div 4 = 8$ 个头。-tp 3，32 无法被 3 整除，GPU 将无法对齐计算矩阵，因此启动会直接报错。不需要加载完整模型权重，有以下几种快速获取方式：
在 Hugging Face 或本地模型目录中，找到 config.json 文件：
config.json。num_attention_heads（或 n_head）：模型的总注意力头数（Q 头数）。
* num_key_value_heads：KV 头数（针对 GQA/MQA 模型，-tp 必须能被此参数整除）。
例如（Llama-3-8B 的 config.json 截取）：
{
"num_attention_heads": 32,
"num_key_value_heads": 8
}
在此配置下，-tp 的取值必须能够被 8 整除（即可以取 1、2、4、8）。
无需下载几百吉字节的模型权重文件，只需加载配置对象即可：
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).