2-node TP: MambaModelConfig’s derived mamba_cache_mode never reaches the remote rank — cross-worker KV-spec assert with –enable-prefix-cach

快速结论：这个报错通常出现在多节点 TP 部署 hybrid GDN/mamba 模型并开启 --enable-prefix-caching 时：head 节点在进程内把 mamba_cache_mode 从 "none" 派生为 "align"，但该派生值没有传达到远端 worker，导致两个 rank 对同一层的 KV-spec 不一致并触发断言。优先排查远端 worker 实际使用的 config 是否绕过了派生逻辑（pickle 反序列化绕过 VllmConfig.__post_init__）。

适用环境：vLLM；2×NVIDIA DGX Spark (GB10)，TP2 over RoCE，--distributed-executor-backend mp，--nnodes 2；hybrid 线性注意力 (GDN) + full-attention 模型（Qwen3-Next 类架构及衍生模型）；mamba hybrid KV cache；MTP speculative decoding k=3；enforce-eager。Issue 未提供 Python/CUDA/PyTorch 具体版本。

最快修复方案：在启动命令中显式传入派生值，让两个 rank 都从 CLI 解析到同一配置（Issue 中已验证可用）：--enable-prefix-caching --mamba-cache-mode align

注意事项：该 workaround 是绕过派生逻辑而非修复它，适用于可显式指定 --mamba-cache-mode 的场景；Issue 中指出该 bug 应影响任何在 multi-node TP + prefix caching 下运行的 mamba/GDN hybrid 模型。根因（远端 worker 使用的 config 是否经 pickle 反序列化绕过 __post_init__）尚未最终确认，属“可能原因”。

问题场景

用户在 2 节点 TP 部署（--nnodes 2，mp backend）下运行 vLLM，加载 hybrid GDN/mamba 模型（Qwen3-Next 衍生架构，如 qwen4_exp），并开启 --enable-prefix-caching。在 engine 初始化阶段即崩溃，无法完成启动。

报错原文

AssertionError: The KV cache specs for the same layer are different across workers. This is not supported yet.

原因分析

开启 prefix caching 时，MambaModelConfig.verify_and_update_config 会在 head 进程内把 mamba_cache_mode 从 "none" 升级为 "align"（调用链：VllmConfig.try_verify_and_update_config → HybridAttentionMambaModelConfig.verify_and_update_config → MambaModelConfig.verify_and_update_config）。

该变更值经 IPC 能到达 head 的本地 worker，但远端节点不会看到这个派生值——其 config 从 CLI args 重建，mamba_cache_mode 仍停留在 "none"，mamba block size 因此回退到 max_model_len。

实测中两个 rank 对同一层报告的 spec 仅有两个字段不同（其余完全一致）：

layer=language_model.model.layers.0.linear_attn
rank 0: MambaSpec(block_size=1600,   ..., mamba_cache_mode='align', ...)
rank 1: MambaSpec(block_size=262144, ..., mamba_cache_mode='none',  ...)
                                                        # 262144 == max_model_len

进一步排查：在远端节点单独运行其 arg 路径（argparse → AsyncEngineArgs.from_cli_args → create_engine_config()，不加载权重）时，mamba_cache_mode 能正确派生为 'align'，enable_prefix_caching=True。但实际运行时 rank 1 的 spec 却是 mamba_cache_mode='none'、block_size=262144，正好对应 config.py:656-657 在 enable_prefix_caching 为 False 时走的 else 分支。

因此可能原因是：远端 worker 实际使用的 config 是 head 序列化（pickled）传输过来的，反序列化绕过了 VllmConfig.__post_init__（try_verify_and_update_config 就在这里），且 head 在 in-place 派生运行之前（或传输的是 __post_init__ 之前的副本）就序列化了该对象。该假设尚未最终确认。

环境排查

确认两边节点使用完全一致的启动 flags，尤其 --enable-prefix-caching 是否在 node-2 命令中携带（Issue 确认该场景下 flags 一致，但排查时仍需核对）。
确认 --nnodes、--node-rank、--distributed-executor-backend mp 配置。
确认模型为 hybrid GDN/mamba（Qwen3-Next 类）架构，is_hybrid=True，模型不在 MODELS_CONFIG_MAP 中。
确认是否使用 MTP speculative decoding、--enforce-eager、Model Runner V2。
确认 vLLM 版本 / main commit（Issue 排查基于 7ee8a6dd01）。Issue 未提供 Python/CUDA/PyTorch 版本，无需逐一比对。

解决步骤

在两个节点的启动命令中都显式加上 --mamba-cache-mode align，与 --enable-prefix-caching 同时传入，使两个 rank 都从 CLI 直接解析到派生值，绕过有问题的派生链路。
例如在原有命令基础上追加：--enable-prefix-caching --mamba-cache-mode align，其余 flags 保持不变。
重启 2 节点部署，观察 engine init 是否还触发 KV cache specs ... different across workers 断言。

验证方法

确认 engine 能干净启动（不再触发 AssertionError: The KV cache specs for the same layer are different across workers），并通过 vllm:prefix_cache_hits_total 指标确认 prefix-cache 命中（在重复前缀上表现为 align-mode 的 block-granularity 命中）。