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

问题场景

用户在 Ollama 中运行 Gemma 4 系列视觉模型进行 OCR、车牌识别、文档解析、小字阅读等需要较高图像分辨率的任务。Issue 正文给出的具体案例是用 gemma4-e4b 做车牌识别：Ollama 默认（280 token 预算）输出 YRSGNB，而 HuggingFace Transformers 在 max_soft_tokens=560 下输出正确的 YRSGNBY。相同退化在未量化模型上也复现，27B 等更大参数变体同样受影响。Issue 评论补充，在 gemma4:12b-it-q8_0 上做 OCR 时，硬编码 280 预算会持续产生错字、乱码，而同样模型在 Transformers 中把预算提到 1120 后结果正确。

报错原文

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

Gemma 4's vision encoder supports a variable-resolution token budget via `max_soft_tokens`, but this value is currently hardcoded to `280` in `model/models/gemma4/process_image.go` (see L25–31). There is no way to override it at runtime through the API or via ollama-python library.

该 Issue 本质是 feature request，并不伴随传统异常堆栈。讨论中出现的异常现象包括：在 process_image.go 中把 minTokens/maxTokens 改成 40/1120 后部分图片崩溃；调整滑动窗口为 kvcache.NewSWAMemCache(...) 后仍存在间歇性竞态崩溃；一次性提交 20–50 张图通常会导致崩溃。Issue 未提供这些崩溃的完整日志文本。

原因分析

可能原因：Gemma 4 的 vision encoder 支持可变分辨率 token 预算（max_soft_tokens），但 Ollama 在 model/models/gemma4/process_image.go 第 25–31 行附近把该值硬编码为 280，且没有通过 API、Modelfile 参数或 ollama-python 暴露任何覆盖入口。因此对于 OCR、文档解析、小字识别等需要更高分辨率的任务，280 的预算不足以保留细节，结果表现为漏字、字符错误、文本乱码。Issue 作者将其描述为“token 预算限制，而非模型质量问题”，因为同一模型在 Transformers 中提高预算后即可得到正确输出。Google 官方 Gemma 4 文档推荐的更高预算（560/1120）在 Ollama 默认路径下无法使用。

环境排查

• 确认 Ollama 版本：Issue 中验证过的可行绕过路径基于 ollama/ollama:0.30.0-rc15，该版本会拉取上游 llama-server 二进制并用 Go 封装，因此具备注入 CLI 参数的前提。
• 确认当前运行器：ollama pull gemma4:e4b 在 0.30.0-rc15 下会触发走 llama-server 的代码路径；更早版本或不同渠道构建可能不会，需实测确认。
• 确认模型标签与量化：Issue 中涉及 gemma4:e4b、gemma4:12b-it-q8_0、未量化模型以及 27B 变体，不同标签走相同硬编码预算。
• 确认容器内是否存在 /usr/lib/ollama/llama-server 路径，否则拦截方案不适用。
• Issue 未提供操作系统、Python、CUDA、PyTorch、显卡型号信息，无需补测这些项即可复现问题。

解决步骤

1. 先停止正在运行的模型，避免替换二进制时被占用：ollama stop <model>。
2. 进入 Ollama 容器（例如 ollama/ollama:0.30.0-rc15），根据需要安装编辑器，Issue 中使用 apt install nano。
3. 把原 llama-server 二进制改名，保留为真正的执行体：mv /usr/lib/ollama/llama-server /usr/lib/ollama/llama-server-bin。
4. 在原路径创建拦截脚本 /usr/lib/ollama/llama-server，内容为：

   #!/bin/sh
   exec /usr/lib/ollama/llama-server-bin "--image-min-tokens" "1120" "--image-max-tokens" "1120" "--reasoning" "on" "$@"

   脚本会把额外参数拼在调用方传入参数之前，再转发给真正的 llama-server。

5. 按需替换为自己想要的 flag 值。Issue 评论中提到，使用 llama.cpp 时把 --image-max-tokens 提到 2240 对该用户效果更好，但这属于他人经验，不是 Issue 作者验证结论。
6. 赋予脚本可执行权限（Issue 未明确写出，但保留原二进制权限即可）：确保 /usr/lib/ollama/llama-server 可执行。
7. 启动任意 Gemma 4 gguf 模型进行 OCR 测试。Issue 指出，在 0.30.0-rc15 下 ollama pull gemma4:e4b 也会走同一 llama-server 代码路径，因此不必强制自行加载 gguf；Issue 评论中给出的 Modelfile 写法（FROM + ADAPTER）属于可选项。

验证方法

用同一个之前在 280 预算下识别错误的图片（例如 Issue 中的车牌图片）重跑，比较输出是否从 YRSGNB 之类的缺字结果变为完整正确结果（如 YRSGNBY）。也可以在批量 20–50 张图的场景下观察是否有改善。Issue 中另一条已验证的对照是：同样模型在 HuggingFace Transformers 中设置 max_soft_tokens=560 即可输出正确结果，可作为 token 预算是否生效的参照。注意，拦截脚本会让本机所有走 llama-server 的模型都带上这些 flag，验证时应确认没有对其他模型造成非预期影响。Issue 中尚未合并官方修复，也没有确切的发布时间线。

参考来源

ollama/ollama #15626

AI 工具推荐

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

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

了解 GamsGo AI

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