Expose `max_soft_tokens` (image token budget) as a runtime parameter for Gemma 4 models

快速结论：当你在 Ollama 上运行 Gemma 4 系列模型做 OCR、文档解析或读取小字号文本时，如果发现识别结果缺字、串字、准确率明显下降，通常不是模型本身质量问题，而是 Ollama 把图像 token 预算 max_soft_tokens 硬编码为 280，导致高分辨率视觉任务细节丢失。优先排查方向是：确认当前 Ollama 版本是否已支持通过运行时参数调整该预算。

适用环境：Issue 中涉及的场景为 Ollama 运行 Gemma 4 视觉模型（如 gemma4-e4b、gemma4:12b-it-q8_0、27B 等变体），并用于 OCR / 车牌识别 / 文档解析。涉及代码路径为 model/models/gemma4/process_image.go。Issue 中提到的实验版本为 ollama/ollama:0.30.0-rc15。未确认其他操作系统、CUDA、PyTorch、显卡等具体信息。

最快修复方案：暂无确认的一步修复方案。该 Issue 为 feature request，正文和评论中用户的自定义构建、修改源码、拦截 llama-server 传参等均属于实验性/黑客式变通，Issue 中未给出官方已验证的运行时参数或 Modelfile PARAMETER。可优先尝试关注后续 Ollama 版本是否暴露 max_soft_tokens 相关参数。

注意事项：用户反馈在自定义构建中把 min/max tokens 调高（如 40/1120、560/1120）虽能显著改善 OCR，但会出现部分图片崩溃、竞态条件、大批量图片（20–50 张）崩溃等问题；修改 Sliding Window 参数也未彻底解决。这些均不是官方确认的稳定方案，存在风险，不建议在生产环境直接套用。

问题场景

用户在 Ollama 上调用 Gemma 4 视觉模型执行 OCR、车牌识别、文档解析等需要较高图像分辨率的任务时触发该问题。具体表现为识别结果出现缺字或错误，例如使用 gemma4-e4b 做车牌识别时，Ollama 默认输出 YRSGNB，而期望结果是 YRSGNBY。用户希望通过 API 或 ollama-python 库在运行时覆盖图像 token 预算，但 Ollama 未提供该入口，导致无法在不改源码的情况下调高预算。

报错原文

Expose `max_soft_tokens` (image token budget) as a runtime parameter for Gemma 4 models

原因分析

可能原因是 Ollama 在 Gemma 4 的图像处理代码中把 max_soft_tokens 硬编码为 280（位于 model/models/gemma4/process_image.go），且没有通过 API、Modelfile PARAMETER 或 ollama-python 暴露运行时覆盖方式。Google 官方 Gemma 4 文档指出，OCR 等细粒度视觉任务需要更高的可变分辨率 token 预算（如 560 或 1120），而默认 280 仅适合通用多模态对话。因此，在需要更高图像分辨率的任务中，280 的预算不足以保留足够视觉细节，造成可测量的准确率下降。用户实测同一模型在 HuggingFace Transformers 下设置 max_soft_tokens=560 即可得到正确结果，说明问题主要来自 token 预算限制，而不是模型权重质量本身。

环境排查

确认当前使用的 Ollama 版本，Issue 中提到 v0.30.0-rc15 引入了直接构建自上游的 llama-server 包装。
确认调用的 Gemma 4 模型变体，例如 gemma4-e4b、gemma4:12b-it-q8_0、27B 等。
确认任务类型是否为 OCR、文档解析或小字号文本读取等需要高视觉分辨率预算的场景。
确认是否已尝试通过 Modelfile PARAMETER、API 参数或 ollama-python 传入图像 token 预算相关参数（当前 Issue 表明这些入口不存在）。
如需对比验证，可确认 HuggingFace Transformers 下设置 max_soft_tokens=560 或 1120 的结果是否与 Ollama 默认结果存在差异。

解决步骤

Issue 中没有官方确认的一步修复方案。以下为用户在讨论中尝试过的变通路径，仅作为排查参考，均未获官方验证，请谨慎评估风险：

关注 Ollama 后续版本是否将 max_soft_tokens 暴露为 Modelfile PARAMETER 或 API 选项；Issue 中多位用户明确请求该能力，但截至关闭时未确认官方实现。
如果只是本地验证，可参考用户做法尝试自定义构建：在 process_image.go 中调整 min/max tokens（例如用户提到 minTokens := 40、maxTokens := 1120），但该做法会在部分图片上崩溃，且大批量图片时稳定性差。
用户还尝试修改 model.go 中的 Sliding Window 参数，例如 kvcache.NewSWAMemCache(slidingWindowLen, 8192, m.Shift) 或 kvcache.NewSWAMemCache(2048, 8192, m.Shift)，能修复部分问题，但引入竞态条件，偶发崩溃，重试同一图片又可能正常，未彻底解决。
另一条用户提出的思路是在 v0.30.0-rc15 中，由于 Ollama 已内置 llama-server 二进制，可通过包装/拦截方式向其传递 --image-min-tokens 与 --image-max-tokens 等 flag。用户给出的 hacky workaround 是在容器内重命名原 llama-server 为 llama-server-bin，再创建同名 shell 脚本转发参数。该方式属于非官方干预，升级或重装后可能失效，且存在稳定性风险。
用户还提出希望有 OLLAMA_LLAMA_SERVER_EXTRA_FLAGS 之类的环境变量来注入 llama-server CLI flags，但这只是建议，Issue 中没有确认已实现。

验证方法

若后续 Ollama 版本或你的变通方案生效，可用同一张测试图片（例如 Issue 中的车牌图片）在相同模型下重新推理：默认 280 预算下输出 YRSGNB，调高预算后应能得到 YRSGNBY 等更完整结果。同时建议在多张图片、批量输入以及不同模型变体上重复验证，确认不再出现缺字、串字或崩溃。若仍复现原始错误，说明预算参数未真正生效或当前版本仍未暴露该能力。