AttributeError: ‘head_dim’ is a per-layer attribute and may vary across layers.

问题场景

用户使用官方发布镜像 vllm/vllm-openai:latest（内含 vLLM 0.27.0 与 Transformers 5.15.0）启动 Gemma 4 系列模型，例如 yasu-oh/gemma-4-31B-it-qat-NVFP4。在 vLLM 启动、尚未加载任何权重之前，ModelConfig 初始化阶段就抛出异常并终止。同样的问题也出现在 CPU 镜像 vllm/vllm-openai-cpu:v0.27.0 运行 google/gemma-4-26B-A4B-it，以及 vllm/vllm-openai:v0.27.1 运行 RedHatAI/gemma-4-26B-A4B-it-FP8-dynamic 时，后者的复现无论是否带 --speculative-config 都会发生。评论中也有用户在 google/gemma-4-12B-it-qat-w4a16-ct 上遇到相同报错。

报错原文

transformers.integrations.heterogeneity.configuration_utils.AmbiguousGlobalPerLayerAttributeError:
'head_dim' is a per-layer attribute and may vary across layers.
Access it via config.per_layer_config[i].head_dim.

CPU 镜像上的完整提示还包含：

transformers.integrations.heterogeneity.configuration_utils.AmbiguousGlobalPerLayerAttributeError: 'head_dim' is a per-layer attribute and may vary across layers. Access it via the individual layer configs instead (e.g. config.per_layer_config[i].head_dim). To read the global config value from config.head_dim anyway, set `allow_global_per_layer_attribute_access` to `True` on the config. Warning: only do this if the caller can safely handle heterogeneous configs; code that assumes a homogeneous model may use the global value incorrectly.

原因分析

最可能的原因是 Transformers 5.15.0 为 Gemma 4 引入了异构逐层配置（heterogeneous per-layer config），head_dim 变成逐层属性，不再保证全局一致，因此直接读取全局 head_dim 会被 Transformers 拒绝并抛出 AmbiguousGlobalPerLayerAttributeError。vLLM 的 vllm/transformers_utils/model_arch_config_convertor.py 中 Gemma4ModelArchConfigConvertor.get_head_size() 仍在访问全局 head_dim，与 Transformers 5.15 的新配置模型不兼容。

Issue 中维护者认为这不是 Gemma 模型本身的问题，而是 vLLM 侧需要适配 Transformers 5.15 的 Gemma4 schema，对应修复为 #49797 与 #49959。该异常发生在 ModelConfig 初始化早期、权重加载之前，与 #51737 在 MTP QKV 参数加载阶段失败的位置不同。

环境排查

• 确认 vLLM 版本：Issue 中报告的受影响版本为 0.27.0 与 0.27.1；v0.24.0 在相同 checkpoint 和参数下仍可正常启动和提供服务。
• 确认镜像内 Transformers 版本，可用 Issue 提供的方式查询：

docker run --rm \
  --entrypoint python3 \
  vllm/vllm-openai:latest \
  -c 'import vllm, transformers; print("vLLM:", vllm.__version__); print("Transformers:", transformers.__version__)'

• 确认模型标识与量化格式，例如 yasu-oh/gemma-4-31B-it-qat-NVFP4、google/gemma-4-26B-A4B-it、google/gemma-4-12B-it-qat-w4a16-ct、RedHatAI/gemma-4-26B-A4B-it-FP8-dynamic。
• 记录启动参数，包括 Tensor parallel size、KV cache dtype，以及是否使用 --speculative-config。
• 在 aarch64 平台（如 DGX Spark / GB10）上同样需要确认镜像与 Transformers 版本组合。
• 确认目标镜像是否已包含 #49797 的修复；Issue 中 0.27.0 与 0.27.1 均未包含。

解决步骤

1. 优先尝试降级 Transformers。基于原镜像构建自定义 Dockerfile，仅把 Transformers 固定到 5.14.1：

   FROM vllm/vllm-openai:latest
   
   RUN /usr/bin/python3 -m pip install --no-cache-dir 'transformers==5.14.1'

2. 保持原有的模型 id、Tensor parallel size、KV cache dtype 等启动配置不变，用上述镜像重新启动服务。
3. 如果不想改造镜像，可等待或换用包含 #49797 修复的 vLLM 版本；该 PR 已合并进 main，但不在 0.27.0 / 0.27.1 镜像中。
4. 不建议通过设置 allow_global_per_layer_attribute_access=True 来绕过：报错原文已提示，只有调用方能安全处理异构配置时才应这样做，假设模型同构的代码可能错误使用全局值。

验证方法

降级到 Transformers 5.14.1 后，按 Issue 中验证过的标准逐项确认：同一模型能成功加载，vLLM 引擎能完成初始化，API 服务能正常启动，/v1/chat/completions 返回 HTTP 200，并能并发跑通 32 个请求。如果仍看到 AmbiguousGlobalPerLayerAttributeError，说明 Transformers 版本未真正降级或镜像未被重新构建。

参考来源

vllm-project/vllm #51744

AI 工具推荐

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

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

了解 GamsGo AI

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