RuntimeError: Worker failed with error ‘tokens_per_block=16 not divisible by tokens_per_hash=512.

这个报错通常出现在使用 pipeline parallelism(PP)运行混合模型(Mamba/KDA 线性注意力 + 普通注意力)时,某个 PP rank 的阶段内没有任何注意力层,导致该 rank 跳过了 hybrid block-size 对齐,最终在 KV cache 或 offloadi

快速结论:这个报错通常出现在使用 pipeline parallelism(PP)运行混合模型(Mamba/KDA 线性注意力 + 普通注意力)时,某个 PP rank 的阶段内没有任何注意力层,导致该 rank 跳过了 hybrid block-size 对齐,最终在 KV cache 或 offloading 连接器处触发 RuntimeError: Worker failed with error 'tokens_per_block=16 not divisible by tokens_per_hash=512. 优先排查 PP 切分后是否存在“无注意力层”的 stage,以及 block size 是否在所有 rank 上一致。

适用环境:Issue 中已确认的环境:2 × NVIDIA RTX 3090(sm_86)、单节点;vLLM 分别验证过源码构建版本与 vllm==0.27.0(另在 0.26.1rc1.dev649 上做过无连接器验证);mp 分布式执行器,--pipeline-parallel-size 2 --tensor-parallel-size 1;模型为 Kimi-K3 的 hybrid 切片(KDA 线性注意力 + MLA),使用 --load-format dummy;开启 --enable-prefix-caching;使用 OffloadingConnector(CPU + fs 分层)时更易暴露。Python、CUDA、PyTorch 的具体版本 Issue 未列出。

最快修复方案:在启动命令中显式传入 --block-size N(Issue 验证通过的值:bf16 KV 用 512,fp8 KV 用 1024)。该参数在父进程创建 worker 之前设置 user_specified_block_size,使每个 rank 从相同值起步,从而不会再出现各 rank 各自对齐的分歧。

注意事项:--block-size 只是规避手段,并非根因修复:Issue 指出只有“fork 之前”的配置才有效,任何在 worker 创建之后再调整 block size 的方式都太晚。kv_connector_extra_config 中的 "blocks_per_chunk": 1 经实测不是替代方案,仍会以相同报错失败。另外,受影响的 rank 比例会随 PP 度上升(Issue 中按 Kimi-K3 93 层估算,PP=47 时 23/47 的 stage 无注意力层,PP=93 时达 69/93),所以 PP 越大越需要关注此问题。

问题场景

使用 vLLM 以 pipeline parallelism 部署混合注意力模型(如 Kimi-K3:KDA 线性注意力层 + MLA 注意力层),且 PP 切分后某个 rank 的阶段内只包含线性注意力/SSM 层、没有任何普通注意力层时触发。典型命令包含 --pipeline-parallel-size 2 --tensor-parallel-size 1、--enable-prefix-caching,并通过 --kv-transfer-config 启用 OffloadingConnector(CPU 层 + 文件系统层)。Issue 也确认,即使完全不配置 KV 连接器,block size 的分歧依然存在,只是连接器中的整除断言把它变成了启动失败。

报错原文

RuntimeError: Worker failed with error 'tokens_per_block=16 not divisible by tokens_per_hash=512.
Hybrid models (e.g. Mamba+Attention) need --enable-prefix-caching to align block sizes.'

Issue 正文中另外记录到断言本身的形式为:

AssertionError: tokens_per_block=16 not divisible by tokens_per_hash=512.
Hybrid models (e.g. Mamba+Attention) need --enable-prefix-caching to align block sizes.

原因分析

vLLM 会在每个 worker 进程中、load_model() 之后独立调用 Platform.update_block_size_for_backend。该函数入口通过 _find_non_ssm_backend 在“本 rank 实际实例化的层”(static_forward_context)中查找第一个非 SSM 后端;如果返回 None 就直接 return。

在 PP 下每个 rank 只构建自己 stage 的层,其余层是 PPMissingLayer,不会出现在上述上下文中。因此,一个只含线性注意力/SSM 层的 stage 会提前返回,跳过 _align_hybrid_block_size,cache_config.block_size 与 cache_config.mamba_block_size 保持在未对齐的 16;而拥有注意力层的 rank 会把它们改成对齐值(512)。之后没有任何机制在各 rank 之间调和这两个字段。

由于 KV cache spec 按层名合并、而 PP 各 stage 的层名互不重叠,通常的“各 worker spec 不一致”检查不会触发。分歧一路传到 resolve_kv_cache_block_sizes,回退到公共 block size,最后在 offloading 连接器的整除断言处报错。因此报错信息“需要 --enable-prefix-caching 对齐 block size”在此场景下具有误导性——Issue 每次运行都开启了 prefix caching,卡在 16 的是那个从未执行对齐的 attention-less rank 上的 mamba 组。可能原因即为上述 PP 下逐 rank 独立对齐的设计缺陷,Issue 已通过代码检查与插桩(interface.py:624 提前返回处、multiproc_executor.py:677 调用处)确认。

环境排查

  • 确认 vLLM 版本:Issue 在源码构建版本与 v0.27.0 上均复现,0.26.1rc1.dev649 上确认无连接器时也存在分歧。若版本包含修复,需另行确认。
  • 确认是否使用 pipeline parallelism 及 --pipeline-parallel-size 取值,并检查 PP 切分(get_pp_indices)后是否存在不包含任何注意力层的 stage。
  • 确认模型的层结构:以 Issue 中的 Kimi-K3 为例,93 层中 24 层为全注意力(每第 4 层,4…92,加上最后的 93 层),其余 69 层为 KDA 线性注意力;线性注意力层占比越高,越容易在较低 PP 度下出现无注意力层的 stage。
  • 确认是否显式设置了 --block-size,以及 kv_connector_extra_config 中是否设置了 blocks_per_chunk(后者不能规避此问题)。
  • 确认是否启用 OffloadingConnector:连接器不是根因,但其整除断言会让分歧显式暴露为启动失败。
  • Issue 未提供 Python、CUDA、PyTorch 的具体版本信息,排查时按实际部署自行核对。

解决步骤

  1. 在启动命令中显式加上 --block-size:Issue 验证 bf16 KV 使用 --block-size 512,fp8 KV 使用 --block-size 1024。它会在父进程创建 worker 前设置 user_specified_block_size,使所有 rank 从同一值开始,从而不再发生分歧的对齐修改。
  2. 不要依赖 "blocks_per_chunk": 1 等连接器侧配置作为替代方案:Issue 实测该配置仍以完全相同的报错失败,因为分歧发生在连接器看到任何数据之前。
  3. 如果已尝试在 worker 启动之后再修改 block size,应放弃该思路:Issue 明确指出只有 fork 之前的配置才有效。
  4. 可优先尝试:减小 --pipeline-parallel-size,使每个 stage 都包含至少一个注意力层,从而绕开无注意力层的提前返回路径。此做法 Issue 未明确验证,属于基于原因的推断,需结合实际显存与模型规模评估。
  5. 长期来看应关注 vLLM 上游针对“PP 下无注意力层 rank 跳过 hybrid block-size 对齐”的修复,升级到包含修复的版本后再去掉 --block-size 规避。

验证方法

带上 --block-size 后重新启动同一套配置(hybrid + PP=2 + CPU tier + 文件系统 NVMe tier),确认不再出现 tokens_per_block=16 not divisible by tokens_per_hash=512 报错且服务正常启动。Issue 中该组合启动成功,并且恢复结果是逐位精确的:在强制驱逐 GPU 缓存后从 offload 恢复,与全新运行的 max logprob delta 为 0.00000000(验证到 28k token 的 prompt)。如需进一步确认,可对 interface.py 的提前返回点与 multiproc_executor.py 的调用点插桩,观察各 rank 的 block_size 与 mamba_block_size 是否一致。

参考来源

vllm-project/vllm #51752

GamsGo AI

AI 工具推荐

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

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

了解 GamsGo AI

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

这个方案解决了吗?

celebrityanime
celebrityanime
文章: 36177

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注