时间可能不存在

本页面只读。您可以查看源文件，但不能更改它。如果您觉得这是系统错误，请联系管理员。
# vllm


## 🧾一、参数解读

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 个核心规则限制：

### 1. 必须能被模型的注意力头数整除

这是最硬性的数学限制。张量并行会将模型的 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。



### 2. 强烈建议为 2 的幂次方（Power of 2）

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

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

### 3. 尽量控制在单个 NUMA 节点 / 单机（Single Node）内

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

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


## 🤴三、注意力头（Attention Head）


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

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

---

### 1. 为什么张量并行（`-tp`）与头数绑定？

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

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

---

### 2. 如何获取模型的注意力头数？

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

#### 方法一：直接查看模型的配置文件（最快、最常用）

在 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` 截取）：*

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

```

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

---

#### 方法二：使用 Python 代码读取 Config

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

```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 启动日志查看

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

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