Clarify Gemma4 vision bidirectional mask behavior for full vs sliding attention

快速结论：此问题场景下，用户发现 HuggingFace Transformers 中 Gemma4 视觉双向掩码（bidirectional mask）的行为与官方 google-deepmind/gemma 实现存在差异：Transformers 将双向掩码同时应用于全局注意力（full/global）和滑动注意力（sliding）层，而官方实现仅在滑动注意力层应用双向掩码，且双向可见性在滑动窗口边界内生效。目前该问题已由 Gemma 团队通过 PR #46850 修复。

问题场景

用户在 HuggingFace Transformers 库中使用 Gemma4 视觉语言模型（VLM）时，关注到 use_bidirectional_attention="vision" 配置下，图像 token 的双向注意力掩码在全局（full）与滑动（sliding）注意力层中的应用方式与官方 google-deepmind/gemma 代码库不一致。此问题在 HuggingFace Transformers 的 transformers.models.gemma4 模型实现中被触发。

报错原文

Transformers:
  full_attention = causal OR vision_blockwise_overlay
  sliding_attention = sliding_causal OR vision_blockwise_overlay

Official google/gemma:
  full/global = causal
  local_sliding = (causal OR vision_bidirectional) AND sliding_window

此外，Issue 中引用了 Google Gemma4 配置文档说明：

# Bidirectional attention for image tokens in the text backbone.
# None: purely causal for all layers (used by E2B, E4B).
# 'vision': bidirectional for image tokens in sliding layers only,
#   causal for global layers (used by 26B_A4B, 31B).
use_bidirectional_attention: str | None = None

原因分析

可能原因：HuggingFace Transformers 中的 create_masks_for_generate 函数将 block_sequence_ids（标识图像 token 块）同时传递给了 full_attention 和 sliding_attention 掩码创建函数，并通过对每个掩码函数应用 blockwise_overlay 来叠加双向可见性。这导致：

在 Transformers 中，全局（full）注意力层内的图像 token 块也获得了双向可见性，而官方实现中这些层保持因果（causal）。
在 Transformers 中，同一图像块内的 token 可以跨滑动窗口边界进行双向关注，而官方实现中双向可见性受滑动窗口范围约束。

根据官方配置注释，use_bidirectional_attention='vision' 的本意是“仅在滑动层中为图像 token 启用双向注意力，全局层保持因果”。因此 Transformers 的实现可能是一个偏差。

环境排查

Python 版本：无特定限制
PyTorch 版本：无特定限制
CUDA 版本：无特定限制
Transformers 版本：涉及 Gemma4 模型实现的版本（例如 4.x 及以上）
影响模型：Gemma4 系列中所有使用 use_bidirectional_attention="vision" 的视觉语言模型（如 26B_A4B, 31B）
对比参考：google-deepmind/gemma 代码库（commit ab5a660）中的实现

解决步骤

确认你使用的 Transformers 版本是否低于修复 PR #46850 的合并时间（2026-06-30 前）。如果版本较老，请升级到最新版本。
如果无法升级，可优先尝试在模型加载或生成时手动覆盖注意力掩码，即：参考官方 google-deepmind/gemma 实现，在全局层强制使用因果掩码，并在滑动层附加双向掩码后与滑动窗口取交集。
如果你是开发者，可在 HuggingFace Transformers 的 create_masks_for_generate 函数（位于 transformers/models/gemma4/modeling_gemma4.py 或类似位置）中，将 full_attention 的 blockwise_overlay 移除，或仅对 sliding_attention 进行掩码叠加。
参考 Issue 评论区中的 PR #46850 的详细代码更改，进行手动补丁。

验证方法

对于修复后的模型，可以执行以下验证：

使用相同输入（包含图像 token 块），分别运行 Transformers 和官方 google-deepmind/gemma 推理，比较两个模型输出 logits 的一致性。
手动检查生成过程中全局层和滑动层的注意力掩码：确认全局层中图像 token 之间无跨位置的双向可见性；确认滑动层中图像 token 的双向可见性被限制在滑动窗口范围内。
使用单元测试验证：在修复版本下，对于特定输入（如多图像、不同图像块尺寸），模型生成不应出现之前描述的行为差异。