PaliGemma 2 ignores final_logit_softcapping

问题场景

用户通过 transformers 加载 PaliGemma 2（文本侧为 Gemma 2 配置，final_logit_softcapping=30.0），执行前向计算、带温度采样、beam search、获取 logprobs 或计算训练 loss 时触发该问题。用户使用真实权重 google/paligemma2-3b-mix-224 在 CPU、fp32、transformers 5.21.1 下复现：给定 COCO cats 图像和提示词“caption en”，对比模型返回的 logits 与对同一 logits 手动应用 tanh(x / 30) * 30 后的结果，发现二者不一致。用 tiny 配置对比 Gemma2ForCausalLM 时，PaliGemma 的最大 |logit| 为 72.03，应用 cap 后为 29.51，loss 为 65.31 对 31.77。

报错原文

PaliGemma 2 ignores final_logit_softcapping

# forward 中仅执行：
logits = self.lm_head(hidden_states)

# 真实权重验证输出：
Caption: "Two cats are sleeping on a pink blanket."
Max |logit| over the 10 generated steps is 13.0
Log-prob of the caption: -5.83 now, -7.93 with the cap
First token "Two": p = 0.65 now, 0.52 with the cap
Total variation between the first-step sampling distributions: 0.06 at T=0.7, 0.13 at T=1.0

# tiny 配置对比：
print(a.logits.abs().max(), b.logits.abs().max())  # 72.03 vs 29.51
print(torch.allclose(torch.tanh(a.logits / 30) * 30, b.logits, atol=1e-4))  # True
print(a.loss, b.loss)  # 65.31 vs 31.77

原因分析

最可能的原因是 PaliGemmaForConditionalGeneration.forward 在调用 self.lm_head(hidden_states) 之后没有应用文本配置中的 final_logit_softcapping。Issue 指出，PaliGemma 2 检查点使用 Gemma 2 文本配置并带有 final_logit_softcapping=30.0；在 v4.51 及之前，语言模型通过 AutoModelForCausalLM 构建，因此 Gemma2ForCausalLM 会应用该 cap。自 v4.52 起，PaliGemma 改为 AutoModel 加独立的 lm_head，这一 cap 因此丢失。Gemma3n 和 T5Gemma 在 lm_head 之后应用了 cap，而 PaliGemma 没有应用。维护者在查看 Google big_vision 仓库后确认确实应用了 softcapping，且 hub 上保存的检查点中 softcap=30，时间线与 PG2 发布时仍使用 CausalLM 的情况吻合。greedy decoding 由于 tanh 是单调函数不受影响，这可能是集成测试未发现该问题的原因。

环境排查

• 确认 transformers 版本是否为 5.21.1 或 main；Issue 已确认这两个版本存在该问题。
• 确认加载的 PaliGemma 2 模型配置中 text_config.final_logit_softcapping 是否为 30.0（真实权重实测为 30.0）。
• 确认是否涉及采样（temperature 大于 0）、beam search、返回 logprobs 或训练 loss；这些场景受该问题影响。
• 如需对照，可检查 Gemma2ForCausalLM（在相同权重下应用 cap）或 Gemma3n 的 logits 行为。
• 确认运行平台与依赖：Windows-11、Python 3.14.6、PyTorch 2.15.0+cpu，且在该环境下可复现。
• PaliGemma 1 使用 GemmaConfig，该配置没有 final_logit_softcapping；排查时注意不要将其与 PaliGemma 2 混为同一问题。

解决步骤

1. 确认当前 transformers 版本：若为 5.21.1 或 main，按 Issue 结论视为受影响版本。
2. 可优先尝试使用包含 PR #50156 的 transformers 版本；该 PR 是在 PaliGemmaForConditionalGeneration 的 lm_head 之后应用文本配置中的 final_logit_softcapping，并附带与 Gemma2ForCausalLM 对比的测试。
3. 如果暂时无法升级，可核对 v4.51 及之前的行为：那时语言模型通过 AutoModelForCausalLM 构建，Gemma2ForCausalLM 会应用 cap。是否回退到该版本需自行评估，Issue 未将其列为已验证修复。
4. 若自行修改代码，应在 lm_head 输出之后、计算 loss 或采样之前，根据 text_config.final_logit_softcapping 应用 tanh(x / cap) * cap，并对没有该字段的 PaliGemma 1（GemmaConfig）做 getattr 兼容处理。
5. 不要用 greedy 生成是否变化来判断问题是否修复；greedy 不受 tanh 单调性影响。

验证方法

用 tiny 配置或真实权重对比 PaliGemma 的输出与对同样 logits 手动应用 tanh(x / 30) * 30 的结果：修复后 a.logits 应与 torch.tanh(a.logits / 30) * 30 对应一致（Issue 中 tiny 复现的 allclose 检查为 True），且与相同权重的 Gemma2ForCausalLM 输出一致。真实权重下可检查 caption log-prob（未 cap 为 -5.83，应用 cap 后为 -7.93）、首 token 概率（0.65 对 0.52）以及 T=1.0 时首步采样分布的总变差（0.13）。另外，greedy caption 仍应保持“Two cats are sleeping on a pink blanket.”，不能仅凭生成文本不变来确认修复。

参考来源

huggingface/transformers #50119

AI 工具推荐

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

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

了解 GamsGo AI

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