bug: context usage estimator counts base64 image data URIs in message files as text, causing spurious auto-compaction

快速结论：当 Open WebUI 中的多模态 Agent 通过 Open Terminal 的 read_file 查看图片时，上下文计量器会把持久化消息里的 base64 图片数据当作文本按“字符数 ÷ 4”来估算 token，结果单条 tool 消息被算成约 1M “token”，远超引擎实际上下文，从而在下一轮请求触发非必要的自动压缩（spurious auto-compaction）。优先确认你的会话里是否包含工具读取的 base64 图片数据，以及是否开启了 context compaction。

适用环境：Open WebUI 0.11.3（Docker 镜像 ghcr.io/open-webui/open-webui@sha256:3e52522170dea0b587a976a7429f8fa6edf7be7d32cc3a1404b9087abb131f69）；Linux Fedora（kernel 7.1.4-204.fc44.x86_64）；浏览器 Brave；后端为 SGLang（OpenAI 兼容），图片 token 注册小于 8k/图；Issue 中未提供 Ollama 版本。

最快修复方案：暂无确认的一步修复方案。Issue 中提到 PR #29765 被请求用于测试，但截至该讨论链没有明确结论表明它已合入并修复此计量/持久化行为；可优先尝试升级到包含该修复的版本，或临时关闭 context compaction / 避免让 Agent 通过 read_file 查看大图。

注意事项：关闭自动压缩只是绕过触发点，不能解决 base64 被重复持久化导致的数据库膨胀与浏览器标签页内存增长；图片 base64 被存了两次（chat_message 行与 chat 行 history map 各一份），约每 3 MB 图片产生 8.4 MB 数据库占用。合成测试图命令依赖终端环境中有 pillow，缺失时无法生成。

问题场景

在 Open WebUI 中使用多模态 Agent，并接入 Open Terminal 的 read_file 工具，让 Agent 直接查看约 2–3 MB 的图片。此时引擎侧按正常的视觉编码处理（每张图 <8k token），但 Open WebUI 的上下文计量器会把持久化到消息文件里的 base64 data URI 当作普通文本累加，下一次请求就会触发自动压缩。Issue 中复现场景为：全新会话、Agent 具备 Open Terminal + read_file、使用具备视觉能力的模型、开启 context compaction（示例配置 token_threshold = 350,000，后端上下文 450k）。

报错原文

bug: context usage estimator counts base64 image data URIs in message files as text, causing spurious auto-compaction

原因分析

最可能的原因：该会话中每条消息的 chat_message.usage 为空，没有真实用量数据，因此 get_chat_context_usage 回退到 len ÷ 4 的估算路径。被持久化的 base64 图片字符串长度达数百万字符，按此路径估算即得到约 1,049,420 “token”，而该后端整个 KV 池只有 450,560 token，属于物理上不可能的估算值。由于估算值越过阈值，自动压缩被误触发。

另外，Issue 观察到底层 base64 被存了两份（chat_message 行与 chat 行 history map），这也是数据库体积和浏览器标签页内存膨胀的来源。

环境排查

确认 Open WebUI 版本是否为 0.11.3 的对应镜像摘要（ghcr.io/open-webui/open-webui@sha256:3e52522170dea0b587a976a7429f8fa6edf7be7d32cc3a1404b9087abb131f69）。
确认后端类型与上下文规模：Issue 使用 SGLang（OpenAI 兼容），上下文 450k，图片 token 注册 <8k/图。
确认是否开启 context compaction，以及 token_threshold 设置（示例为 350,000）。
确认 Agent 是否接入 Open Terminal 与 read_file，并且查看过 2–3 MB 级别的图片。
检查 Repro 会话中每条消息的 chat_message.usage 是否为空（为空时会走估算路径）。
检查 chat_message 行与 chat 行 history map 中是否各存了一份 base64 图片数据。

解决步骤

先复现并确认估算路径：在开启 context compaction 的会话中，让 Agent 通过 read_file 查看一张约 3 MB 图片，随后发送任意后续消息（如 “ping”）。
观察上下文计量器是否跳到约 1M “token”，并在下一次请求触发自动压缩；同时确认引擎侧 prompt token 仍保持正常。
可优先尝试的处理：升级到包含相关修复的构建（Issue 讨论中请求测试 PR #29765），因为当前讨论链未给出该 PR 已合入并验证的明确证据。
若无法立即升级，可临时关闭 context compaction，或避免让 Agent 通过 read_file 读取大图，以规避误触发。

如需稳定复现用于对比，可在终端环境中生成合成图（需要 pillow）：

python3 -c "from PIL import Image; import numpy as np; Image.fromarray(np.random.randint(0,255,(1024,1024,3),dtype='uint8')).save('/tmp/big.png')"

然后让 Agent 对 /tmp/big.png 调用 read_file。

处理已膨胀的会话数据：检查对应 chat_message 行与 chat 行 history map 中的 base64 内容，评估是否清理历史会话以减少数据库与内存占用。

验证方法

在相同条件下重新让 Agent 通过 read_file 查看图片并发送后续消息：上下文计量器不应再跳到约 1M “token”，下一次请求不应触发非必要的自动压缩，引擎侧 prompt token 保持正常范围。同时可检查单条消息的估算值是否反映引擎实际的视觉 token 成本（<8k/图），以及 chat_message 行与 chat 行 history map 中是否不再重复持久化同一份 base64 图片数据。