[Bug]: [NIXL] Hetero TP assertion fails when tp > num_kv_heads (GQA replication)

快速结论：使用 NixlConnector 进行异 TP 大小的分离式推理时，当任意端 TP 大小大于模型 KV 头数时，`_validate_remote_agent_handshake` 中的比例校验会因 GQA 复制导致 `block_len` 无法继续线性缩放而失败。优先排查两端 TP 大小是否同时大于 KV 头数，并检查相关代码是否已包含 GQA 复制兼容逻辑。

问题场景

用户在运行 vLLM (版本 0.21.0) 的分离式推理 (disaggregated inference) 时，使用 NixlConnector 作为 KV 连接器，并配置了非同等的 TP 大小 (例如 Prefill TP=8, Decode TP=16，或 TP=8 对 TP=16)。问题触发于模型拥有较少的 KV 头数 (例如 LLama-3.2-1B-Instruct 有 8 个 KV 头，TinyLlama-1.1B-Chat-v1.0 有 4 个 KV 头)，且较大的 TP 大小超过了 KV 头数 (例如 16 > 8，或 8 > 4)。

报错原文

AssertionError: Remote P worker KV layer cache must be of shape [2, N, local_kv_heads*tp_ratio, page_size, head_dim] and same dtype.

原因分析

问题根因在于 `_validate_remote_agent_handshake` (位于 `worker.py` 约第 1498 行) 中的断言：

assert remote_block_len == (self.block_len_per_layer[0] * tp_ratio) // block_size_ratio

这个断言假设 `block_len` 与 `1/tp_size` 呈线性缩放关系。然而，当 `tp_size > num_kv_heads` 时，GQA 复制 (Grouped-Query Attention replication) 会将每个 rank 上的 KV 头数上限为 1 (即 `num_kv_heads_per_rank = max(1, num_kv_heads // tp) = 1`)，导致 `block_len` 停止缩放。两端虽然 TP 不同，但 `block_len` 相同，所以比例关系不成立，断言失败。

环境排查

模型：确认模型是否具有较少的 KV 头数 (如 4 或 8)。
TP 配置：确认 Prefill 端和 Decode 端的 `–tensor-parallel-size` 是否至少有一端大于 `num_key_value_heads`。
vLLM 版本：确认是否在 0.21.0 或更早版本 (修复 PR #45879 / #45860 尚未合入前)。
KV Connector：确认使用的是 `NixlConnector`。
测试硬件：例如 8× NVIDIA A100，用于复现 TinyLlama 的双 TP 场景 (Prefill TP=2, Decode TP=8)。

解决步骤

升级 vLLM 版本或手动合并修复代码：修复 (如 PR #45879 和 #45860) 的核心思路是在比例校验中加入 GQA 复制的容错判断，使用 `remote_heads // local_heads` 替换原始的 `tp_ratio`。
若无法升级，可手动修改 `_validate_remote_agent_handshake` 函数，在断言前增加检查：如果任一端 TP 大小大于总 KV 头数，则跳过严格的比例校验。
示例修复逻辑：在断言冲突处，检查 `max(self.transfer_topo.tp_size, remote_tp_size) > total_num_kv_heads` 条件，如果条件为真，则不触发断言错误 (因为 `block_len` 已到上限)。
使用修复后的代码重新运行分离式推理：确保 `curl` 请求能通过 KV 传输并返回合理结果。
运行 E2E 验证脚本：若环境支持多 GPU，可参考 Issue 中提供的测试脚本 (`tests/v1/kv_connector/nixl_integration/run_gqa_replication_accuracy_test.sh`) 进行端到端正确性验证，检查 Prefill TP=2, Decode TP=8 下 TinyLlama 模型的输出是否正常。

验证方法

使用以下 `curl` 命令测试分离式推理 API：

curl http://localhost:8300/v1/completions -d '{"model":"TinyLlama/TinyLlama-1.1B-Chat-v1.0","prompt":"The capital of France is","max_tokens":10}'

如果输出以 “Paris” 开头且内容合理，说明 KV 传输正确，问题已解决。如果仍报 `AssertionError` 或输出乱码，则问题未修复。同时，建议运行 Issue 中的精确性测试脚本来确认数据正确性。

参考来源

vllm-project/vllm #45330

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

[Bug]: [NIXL] Hetero TP assertion fails when tp > num_kv_heads (GQA replication)