vLLM 三卡启动报 attention heads 不能被 tensor parallel size 整除

vLLM 启动时报 Total number of attention heads (...) must be divisible by tensor parallel size (...)，还没进入请求处理。多放一张 GPU 不一定能使用任意 TP 数：张量并行需要按模型维度切分。

例如 vLLM 0.6.3.post1 加载 Llama 3.1 70B-Instruct 时，64 个注意力头无法按 TP=6 等分。下面用于解释三卡选择的是另一份 40 头假设配置，不能把这两个头数混用。

vLLM 0.6.6 的 ModelConfig.verify_with_parallel_config 检查总注意力头数对 TP 数取余，0.31.0 的 ModelConfig 仍有这项检查。选合法并行度是配置约束，不是等待某个升级版本放开任意切分。不同架构、量化和其他层维度仍需分别核对。

读取模型自己的 config.json

不用加载权重，也能检查常见 Transformer 的候选并行度：

import json
from pathlib import Path
config = json.loads(Path("./model/config.json").read_text())
heads = config["num_attention_heads"]
print("heads:", heads)
print("candidates:", [tp for tp in range(1, 9) if heads % tp == 0])
print("kv heads:", config.get("num_key_value_heads"))

多模态模型可能把文本配置放在嵌套字段里；要读取服务实际使用的文本骨干，不能把视觉头数拿来计算。这个脚本只检查一个必要条件，还要满足 GPU 数量、其他层维度、量化实现及执行后端的约束。GQA 的 KV 头处理也不能简单套同一公式：0.6.6 的相关代码存在复制 KV 头的分支。

假设实际配置有 40 个查询头，TP=3 不通过，TP=2 或 4 通过这一项检查。三张卡的机器可先只选两张建立基线：

CUDA_VISIBLE_DEVICES=0,1 vllm serve ./model --tensor-parallel-size 2

这会只使用指定的两张卡。GPU 在进程里的编号经过重映射，部署脚本、容器 GPU 配置和启动日志必须一致。不要把 num_attention_heads 改成 42 来让除法成立；权重矩阵仍是原结构，改 config 会导致形状不匹配或错误解释权重。

若合法的 TP 数装不下模型，可评估该版本及模型支持的 pipeline parallel、其他合法 TP 配置或合适的量化模型。换一种并行方式也需要单独验收，不能假设 TP 与 PP 相乘就覆盖所有架构。

启动后先确认日志中的 TP 数和 worker 数，再跑短请求；随后用业务上下文长度验证 KV cache 和显存预算。头数整除只说明通过配置检查，不证明模型一定能装下，也不说明更多卡就一定更快。