RuntimeError: Number of heads in key and value must divide the number of heads in

快速结论：这个报错通常出现在用 GlmConfig 手动构造 GLM 因果语言模型、且 num_attention_heads 无法被 num_key_value_heads 整除时（例如 7 对 2）。配置校验和模型构建都会通过，直到第一次 forward 才在注意力实现里抛出 RuntimeError: Number of heads in key and value must divide the number of heads in。优先检查这两个头数的整除关系。

适用环境：Issue 已确认的环境为 Transformers v5.9.0 以及 main 上的 e7e8b7fa161c9d43a6ffab8feef3aa446df454a5；Python 3.11.15；PyTorch 2.13.0+cu126；平台为 Linux x86_64。最小复现可在 CPU 上运行，不需要数据集或分布式环境。相关 GLM 配置/建模文件在当前 main（945dac9117cb54196888c0e6c08035792a98c485）上未改动。

最快修复方案：暂无确认的一步修复方案。Issue 讨论中维护者表示可以评审一个统一修复此类校验缺口的 PR，作者计划用单个 PR 覆盖多个相关配置/运行时校验问题，但该统一 PR 仍为 Draft/WIP，未合入。可优先尝试的规避方式：把 num_attention_heads 改成能被 num_key_value_heads 整除的值（例如 8 对 2 可正常完成同一次 forward）。

注意事项：该问题目前只影响“新初始化模型 + 不常见头数设置”的场景，属于配置校验缺口，不是推理结果错误；Issue 中控制组（8/2）能正常跑通，说明不是所有 GQA 配置都受影响。整除规避只是临时手段，不等于官方修复；统一 PR 的最终行为和合入状态请以仓库为准。

问题场景

用户在自己的脚本中直接用 Transformers 的 GlmConfig 构造 GLM 因果语言模型（GlmForCausalLM），并传入一组分组查询注意力（GQA）头数配置：num_attention_heads=7、num_key_value_heads=2。此时 config.validate_architecture() 会通过，GlmForCausalLM(config).eval() 也能构建成功，但在第一次 forward（例如 model(input_ids=torch.randint(2, 128, (1, 8)))）时崩溃。同一复现无需数据集、无需分布式，可在 CPU 上跑。

报错原文

RuntimeError: Number of heads in key and value must divide the number of heads in

原因分析

模型内部会计算 self.num_key_value_groups = config.num_attention_heads // config.num_key_value_heads，但 GlmConfig 目前没有校验这个除法是否整除。因此当 num_attention_heads 不能被 num_key_value_heads 整除时，非法关系会被 validate_architecture() 放过，直到注意力实现在运行时拒绝它并抛出上述 RuntimeError。也就是说，配置校验与运行时约束不一致：配置层接受了 GQA 头数组合，注意力层却要求 key/value 头数必须整除 query 头数。

环境排查

确认 Transformers 版本：Issue 中为 v5.9.0，以及 main 的 e7e8b7fa161c9d43a6ffab8feef3aa446df454a5；并确认 GLM 配置/建模文件是否仍是当前 main（945dac9117cb54196888c0e6c08035792a98c485）上未改动的版本。
确认 Python 版本：Issue 中为 3.11.15。
确认 PyTorch 版本：Issue 中为 2.13.0+cu126。
确认平台/硬件：Issue 中为 Linux x86_64，复现不需要 GPU，CPU 即可。
确认模型配置中的 num_attention_heads 与 num_key_value_heads 是否能整除，这是本 Issue 的关键变量。

解决步骤

先用最小配置确认是否为同一问题：设置 num_attention_heads=7、num_key_value_heads=2，依次调用 config.validate_architecture()、构建 GlmForCausalLM，再执行一次 forward。
如果校验通过、构建成功，但 forward 报 RuntimeError: Number of heads in key and value must divide the number of heads in，即可判定为头数整除关系导致的配置问题，而非数据或环境故障。
临时规避：将 num_attention_heads 调整为能被 num_key_value_heads 整除的取值。Issue 中控制组用 num_attention_heads=8、num_key_value_heads=2 可完成同一次 forward。
关注官方统一修复进展。维护者在讨论中表示可以评审一个一次性修复整个问题类别（对所有适用模型架构做同样的整除校验）的 PR；作者计划提交覆盖多个相关校验缺口的单个 PR，并给出了统一 Draft PR #48645，但明确标记为 Draft/WIP，需人工评审。
如果不想等待官方修复，可在自己的配置流程里提前做断言/校验（例如在构建模型前检查 num_attention_heads % num_key_value_heads == 0）；注意这属于自行添加的保护，不是本 Issue 已验证的官方方案。

验证方法

把配置改成整除组合（如 8 对 2）后，用相同的输入执行一次 forward：如果不再出现 RuntimeError: Number of heads in key and value must divide the number of heads in 且输出正常，说明已避开该问题。反过来，7 对 2 仍会在 forward 阶段复现该报错，可作为回归验证用例。