Skip to content

Qwen3.8-Flash-Next on any consumer hardware: one-click install for Windows / Linux. Strata inference engine, OpenAI/Anthropic API on localhost, optional image input.

C++

vision: the image-token limit has a default and is enforced (I7, #3690)

Niko1221828a2559a9f1
diff --git a/serve/server.py b/serve/server.py
index 04f8beb97..171e68606 100644
--- a/serve/server.py
+++ b/serve/server.py
@@ -2592,12 +2592,28 @@ class Vision:
# opt-in (the vision section's "elastic": true, with the config's "vram_elastic"): the encoder starts with the
# first picture and stops after elastic_idle_s without one; while it runs, the engine's expert cache keeps
# elastic_mib of VRAM free for it (Service._vision_up / _vision_idle_down)
+ self.max_tokens = self.token_limit(cfg)
self.elastic = cfg.get("elastic") is True
self.elastic_mib = int(cfg.get("elastic_mib") or 2048)
self.elastic_idle_s = float(cfg.get("elastic_idle_s") or 120)
if not lazy and not self.elastic:
self._start()
+ # What a picture may become when the config does not say (setup writes the same numbers, setup.VISION): an old, hand-edited or migrated
+ # config without vision.max_tokens left the reader unclamped, and #3690 saw one picture become 93,700 image tokens (I7). A key that is
+ # there is the person's: 0 means no limit, as before.
+ DEFAULT_MAX_TOKENS = {"gpu": 1024, "cpu": 300}
+
+ @staticmethod
+ def token_limit(cfg: dict) -> int:
+ """The --max-tokens of a reader config: its max_tokens, else the default of its kind (GPU 1024, CPU 300)."""
+ if cfg.get("max_tokens") is not None:
+ try:
+ return max(0, int(cfg["max_tokens"]))
+ except (TypeError, ValueError):
+ pass
+ return Vision.DEFAULT_MAX_TOKENS["gpu" if cfg.get("gpu") else "cpu"]
+
@staticmethod
def reader_args(cfg: dict) -> list:
absolute = lambda p: os.path.abspath(p) if os.path.dirname(str(p)) else p # the encoder runs in its own dir (#480) # noqa: E731
@@ -2606,8 +2622,9 @@ class Vision:
args.append("--gpu")
if cfg.get("threads"):
args += ["--threads", str(cfg["threads"])]
- if cfg.get("max_tokens"):
- args += ["--max-tokens", str(cfg["max_tokens"])]
+ limit = Vision.token_limit(cfg)
+ if limit:
+ args += ["--max-tokens", str(limit)]
if cfg.get("min_tokens"): # #767: mtmd's image_min_tokens (a hand-edited key)
args += ["--min-tokens", str(cfg["min_tokens"])]
return args
@@ -2826,6 +2843,7 @@ class Vision:
raise ValueError("the image could not be read: " + (line[4:] if line.startswith("ERR") else
"the vision encoder stopped"))
self.cache[key] = (out, int(line.split()[1]))
+ self.warn_if_over_limit(self.cache[key][1])
held = {str(p) for p in keep} | {str(out)}
for old in list(self.cache): # oldest first, but never one still in use
if len(self.cache) <= 64:
@@ -2834,6 +2852,15 @@ class Vision:
self.cache.pop(old)[0].unlink(missing_ok=True)
return self.cache[key]
+ def warn_if_over_limit(self, tokens: int) -> None:
+ """I7: one picture that became more than 4 times the limit is logged with the numbers, so the next report has them (the reader's own
+ stderr has the warm-up line). A reader built before the limit was enforced inside it (strata-vision refuses these now) still lets them by."""
+ limit = getattr(self, "max_tokens", 0)
+ if limit and tokens > 4 * limit:
+ print(f"[strata] images: one picture became {tokens} image tokens, more than 4 times the limit of {limit} (vision.max_tokens); "
+ "the picture reader is not applying its limit. Update the engine, and send the line 'strata-vision: warmed up at N image "
+ "tokens' from the reader's log with the report", flush=True)
+
def close(self):
proc, self.proc = self.proc, None
if proc is None:
diff --git a/serve/test_vision_token_limit.py b/serve/test_vision_token_limit.py
new file mode 100644
index 000000000..5cb69d512
--- /dev/null
+++ b/serve/test_vision_token_limit.py
@@ -0,0 +1,71 @@
+"""I7 (tools and images review, 2026-10-22): a picture reader without vision.max_tokens in its config was unclamped, and #3690 saw one
+picture become 93,700 image tokens. The server gives every reader a limit (GPU 1024, CPU 300) unless the config names one, and logs a
+picture that came back over 4 times the limit.
+
+ python -m unittest serve.test_vision_token_limit
+"""
+import io
+import unittest
+from contextlib import redirect_stdout
+
+import serve.server as server
+
+BASE = {"exe": "strata-vision", "mmproj": "m.gguf", "model": "t.gguf"}
+
+
+def limit_of(cfg):
+ args = server.Vision.reader_args(cfg)
+ return int(args[args.index("--max-tokens") + 1]) if "--max-tokens" in args else None
+
+
+class TokenLimit(unittest.TestCase):
+ def test_a_config_without_max_tokens_gets_the_default_of_its_kind(self):
+ self.assertEqual(limit_of({**BASE, "gpu": True}), 1024)
+ self.assertEqual(limit_of({**BASE, "gpu": False}), 300)
+ self.assertEqual(limit_of(dict(BASE)), 300)
+
+ def test_a_limit_the_person_set_is_kept_not_capped(self):
+ self.assertEqual(limit_of({**BASE, "gpu": True, "max_tokens": 4096}), 4096)
+ self.assertEqual(limit_of({**BASE, "max_tokens": "512"}), 512)
+
+ def test_zero_still_means_no_limit(self):
+ self.assertIsNone(limit_of({**BASE, "gpu": True, "max_tokens": 0}))
+
+ def test_an_unreadable_value_falls_back_to_the_default(self):
+ self.assertEqual(limit_of({**BASE, "gpu": True, "max_tokens": "lots"}), 1024)
+
+ def test_min_tokens_is_unchanged(self):
+ args = server.Vision.reader_args({**BASE, "gpu": True, "min_tokens": 768})
+ self.assertEqual(args[args.index("--min-tokens") + 1], "768")
+
+
+class Warn(unittest.TestCase):
+ def reader(self, limit):
+ v = server.Vision.__new__(server.Vision)
+ v.max_tokens = limit
+ return v
+
+ def said(self, limit, tokens):
+ out = io.StringIO()
+ with redirect_stdout(out):
+ self.reader(limit).warn_if_over_limit(tokens)
+ return out.getvalue()
+
+ def test_93700_tokens_under_a_1024_limit_is_logged_with_the_numbers(self):
+ text = self.said(1024, 93700)
+ self.assertIn("93700 image tokens", text)
+ self.assertIn("limit of 1024", text)
+ self.assertIn("warmed up at N image tokens", text)
+
+ def test_a_picture_within_four_times_the_limit_is_quiet(self):
+ self.assertEqual(self.said(1024, 1024), "")
+ self.assertEqual(self.said(1024, 4096), "")
+
+ def test_no_limit_no_warning(self):
+ self.assertEqual(self.said(0, 93700), "")
+ v = server.Vision.__new__(server.Vision) # a reader object made without the attribute (older tests)
+ v.warn_if_over_limit(93700)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tools/vision/strata_vision.cpp b/tools/vision/strata_vision.cpp
index 9cc8d321f..feae41453 100644
--- a/tools/vision/strata_vision.cpp
+++ b/tools/vision/strata_vision.cpp
@@ -272,6 +272,11 @@ int main(int argc, char** argv) {
}
std::fprintf(stderr, "strata-vision: warmed up at %d image tokens in %.1f s\n", warm_tokens,
std::chrono::duration<double>(std::chrono::steady_clock::now() - warm_t0).count());
+ // I7 (#3690): a picture that became 93,700 image tokens under --max-tokens 1024. The limit is not applied by this build of mtmd for
+ // this model, and the log line above is the evidence to ask for.
+ if (max_tokens > 0 && warm_tokens > max_tokens + max_tokens / 8)
+ std::fprintf(stderr, "strata-vision: WARNING the warm-up picture became %d image tokens, over the limit of %d (--max-tokens): "
+ "the limit is not applied for this model; pictures over it are refused\n", warm_tokens, max_tokens);
mtmd_input_chunks_free(chunks);
if (bm) mtmd_bitmap_free(bm);
}
@@ -308,6 +313,10 @@ int main(int argc, char** argv) {
const mtmd_decoder_pos last = mtmd_image_tokens_get_decoder_pos(it, 0, (size_t) n - 1);
const int nx = (int) last.x + 1, ny = (int) last.y + 1;
if (nx * ny != n) err = "the image grid is not rectangular (" + std::to_string(n) + " tokens)";
+ // never silently produce many times the budget (I7, #3690): over the limit (a rounding margin of an eighth) the picture is refused
+ if (err.empty() && max_tokens > 0 && n > max_tokens + max_tokens / 8)
+ err = "the picture became " + std::to_string(n) + " image tokens, over the limit of " + std::to_string(max_tokens) +
+ " (vision.max_tokens); send a smaller picture or raise the limit";
const float* embd = mtmd_get_output_embd(ctx);
FILE* f = err.empty() ? std::fopen(out.c_str(), "wb") : nullptr;
if (err.empty() && !f) err = "cannot write " + out;