执行摘要

• 一句话：移除 PaliGemma 遗留的图像 embedding 逆缩放，修复数值量级偏差
• 推荐动作：这是一个值得快速浏览的 PR，核心逻辑简单但在设计上有一个值得注意的教训：当上游模型（Gemma）调整 embedding 缩放策略后，下游多模态变体（PaliGemma）需要同步清理遗留的兼容代码。建议关注两点：(1) 仓库中是否还有其他基于 Gemma 的多模态模型存在类似遗留缩放；(2) 维护者删除测试文件的决定意味着该修复缺少长期回归保护，后续可考虑在仓库的多模态通用测试框架中补充 embedding 量级断言。

功能与动机

Issue #52667 报告：Gemma 此前将 sqrt(hidden_size) 缩放从外部移入 text embedding lookup 路径后，PaliGemma 的 embed_multimodal 仍保留了对 vision_embeddings 的 hidden_size**-0.5 缩放。这导致图像 embedding 被额外缩小约 1/sqrt(hidden_size) 倍，与 HuggingFace Transformers 的 PaliGemma 实现不一致，直接影响多模态推理质量。PR body 明确说明这是聚焦的 bug 修复，不涉及视觉投影、tokenizer、调度器或 kernel 行为变更。

实现拆解

变更入口与核心逻辑

唯一变更文件为 vllm/model_executor/models/paligemma.py，修改集中在 PaliGemmaForConditionalGeneration.embed_multimodal 方法。

1. 删除陈旧缩放行：在 embed_multimodal 方法中，移除了 vision_embeddings = vision_embeddings * (self.config.hidden_size**-0.5) 以及对应的 Transformers 源码引用注释。该缩放原用于匹配 Gemma 早期版本对 text+image 统一施加的 sqrt(hidden_size) 归一化，但 Gemma 后来将 text 侧缩放内嵌到 embedding lookup 中，PaliGemma 的 image 侧缩放变为冗余且错误。
2. 保持投影链路不变：_process_image_input → multi_modal_projector 的视觉投影逻辑完全不动，图像特征经投影后直接返回，量级与 Transformers modeling_paligemma.py 对齐。

测试与配套

• PR body 中作者描述了本地运行的回归测试计划，包括 tests/models/multimodal/processing/test_paligemma.py 的 CPU 模式验证。
• 但在第二个 commit 中，维护者 hmellor 删除了该测试文件（Delete tests/models/multimodal/processing/test_paligemma.py），最终 PR 净变更为 0 增 2 删，无新增测试覆盖。

关键文件：

• vllm/model_executor/models/paligemma.py（模块 多模态模型；类别 source；类型 core-logic；符号 PaliGemmaForConditionalGeneration.embed_multimodal）: 唯一变更文件，删除 embed_multimodal 中遗留的 hidden_size**-0.5 图像 embedding 缩放，修复与 Gemma 缩放迁移后的量级不一致

关键符号：PaliGemmaForConditionalGeneration.embed_multimodal, PaliGemmaForConditionalGeneration._process_image_input

关键源码片段

vllm/model_executor/models/paligemma.py

唯一变更文件，删除 embed_multimodal 中遗留的 hidden_size**-0.5 图像 embedding 缩放，修复与 Gemma 缩放迁移后的量级不一致

def embed_multimodal(self, **kwargs: object) -> MultiModalEmbeddings:
    image_input = self._parse_and_validate_image_input(**kwargs)
    if image_input is None:
        return []
    vision_embeddings = self._process_image_input(image_input)
    # 原先此处对 vision_embeddings 乘以 hidden_size ** -0.5，
    # 用于匹配 Gemma 早期版本对 text+image 统一施加的 sqrt(hidden_size) 归一化。
    # 但 Gemma 后续将该缩放移入 text embedding lookup 路径后，
    # 此处对 image 侧的缩放变为冗余，导致图像 embedding 量级
    # 约为预期的 1 / sqrt(hidden_size)，与 Transformers 实现不一致。
    # 删除该缩放后，图像特征以原始投影量级直接返回，与 HF 对齐。
    return vision_embeddings

评论区精华

PR 描述清晰度争议

hmellor 初始提交 CHANGES_REQUESTED，指出：

~This doesn't seem right.~ ~The scaling that you are deleting is specifically on the vision embeddings only, not the text embeddings. So any changes to how the text embeddings are scaled should have no effect here.~
edit: after reading the original issue this makes more sense. But the PR description is not clear at all

核心困惑在于：被删除的缩放仅作用于 vision embeddings，表面上看与 text embedding 的缩放变更无关。只有结合 Issue #52667 的完整上下文——即 Gemma 将缩放内移后，PaliGemma 的图像路径不应再有任何额外缩放——才能理解为何删除是正确的。

决策结论

hmellor 阅读原始 issue 后批准：

Approving based on the description in the original issue

测试文件删除

第二个 commit 由 hmellor 直接删除了作者新增的测试文件，说明维护者认为该测试不符合仓库标准或已有其他覆盖路径。最终 PR 不含测试变更。

• PR 描述清晰度与变更正确性 (documentation): hmellor 基于原始 issue 描述批准 PR，未要求修改 PR body 本身。
• 测试文件删除 (testing): 最终 PR 不含测试变更，该修复缺少专门的回归测试覆盖。

风险与影响

• 风险：### 回归风险
• 无测试覆盖：最终 PR 删除了作者新增的回归测试，当前无专门测试验证图像 embedding 量级正确性。若未来 Gemma embedding 路径再次调整，PaliGemma 可能重新出现量级偏差而无法被 CI 拦截。
• 数值影响范围：删除缩放后，所有 PaliGemma 模型的图像 embedding 量级将增大约 sqrt(hidden_size) 倍（如 hidden_size=2048 时约 45 倍）。虽然这是正确的修复方向，但已缓存或微调过基于旧量级的下游组件可能受到影响。

兼容性风险

• 低风险：变更仅影响 PaliGemma 模型，不触及其他多模态模型的投影或合并逻辑。
• 影响：
  • 用户影响：使用 PaliGemma 模型的用户将获得与 HuggingFace Transformers 一致的图像 embedding 量级，多模态推理质量（图像理解、图文匹配）将改善。但已基于旧行为做 prompt 工程或后处理调优的用户可能需要重新校准。
  • 系统影响：仅限 PaliGemma 模型执行路径，不涉及调度器、KV cache、kernel 或分布式逻辑。
  • 团队影响：极小，单文件 2 行删除，无需协调多模块变更。
  • 风险标记：缺少测试覆盖, 多模态数值量级变更

关联脉络

• 暂无明显关联 PR