Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

fix(rag): cache successful image batches with complete request identity

Bingxi Zhao (Frank)be2936873360
diff --git a/deeptutor/services/llm/image_caption_batch.py b/deeptutor/services/llm/image_caption_batch.py
index 930439144..e4fb03e9e 100644
--- a/deeptutor/services/llm/image_caption_batch.py
+++ b/deeptutor/services/llm/image_caption_batch.py
@@ -12,6 +12,7 @@ from .exceptions import (
LLMRateLimitError,
ProviderContextWindowError,
)
+from .image_caption_cache import complete_image_caption_batch
logger = logging.getLogger(__name__)
_BATCH_INSTRUCTIONS = (
@@ -71,6 +72,15 @@ class ImageCaptionBatcher:
async def describe(self, images: list[dict[str, str]]) -> list[str | None]:
if not images or self.halted:
return [None] * len(images)
+ return await complete_image_caption_batch(
+ self.client,
+ images,
+ prompt=self.prompt,
+ system_prompt=self.system_prompt + (_BATCH_INSTRUCTIONS if len(images) > 1 else ""),
+ generate=lambda: self._describe_uncached(images),
+ )
+
+ async def _describe_uncached(self, images: list[dict[str, str]]) -> list[str | None]:
try:
if len(images) == 1:
image = images[0]
diff --git a/deeptutor/services/llm/image_caption_cache.py b/deeptutor/services/llm/image_caption_cache.py
index 5cc909e0e..e51e286ab 100644
--- a/deeptutor/services/llm/image_caption_cache.py
+++ b/deeptutor/services/llm/image_caption_cache.py
@@ -1,4 +1,4 @@
-"""Best-effort, workspace-scoped caching for individual image descriptions.
+"""Best-effort, workspace-scoped caching for image descriptions.
Only successful, nonempty captions are cached. The digest covers the complete
request and model identity; only the digest and caption are written to disk,
@@ -9,6 +9,7 @@ never image bytes, prompts, endpoint URLs, headers, or credentials. Removing
from __future__ import annotations
import asyncio
+from collections.abc import Awaitable, Callable
import hashlib
import json
import logging
@@ -126,3 +127,72 @@ async def complete_image_caption(
if path is not None and caption:
await asyncio.to_thread(_write_caption, path, caption)
return caption
+
+
+def _read_batch_captions(path: Path, count: int) -> list[str] | None:
+ try:
+ payload = json.loads(path.read_text(encoding="utf-8"))
+ if not isinstance(payload, dict) or payload.get("version") != _CACHE_VERSION:
+ return None
+ captions = payload.get("captions")
+ if (
+ isinstance(captions, list)
+ and len(captions) == count
+ and all(isinstance(caption, str) and caption.strip() for caption in captions)
+ ):
+ return [caption.strip() for caption in captions]
+ except (OSError, ValueError, UnicodeError):
+ pass
+ return None
+
+
+def _write_batch_captions(path: Path, captions: list[str]) -> None:
+ try:
+ atomic_write_json(path, {"version": _CACHE_VERSION, "captions": captions})
+ except OSError:
+ logger.debug("Image caption batch cache write failed; retaining generated captions")
+
+
+async def complete_image_caption_batch(
+ client: Any,
+ images: list[dict[str, str]],
+ *,
+ prompt: str,
+ system_prompt: str,
+ generate: Callable[[], Awaitable[list[str | None]]],
+) -> list[str | None]:
+ """Cache complete successful groups using their exact request identity.
+
+ Image order and metadata, the structured prompt, and the bounded retry
+ policy are part of the digest. Batch entries remain separate from ordinary
+ single-image captions. Partial failures, errors and cancellation are never
+ cached; split groups can independently reuse their successful entries.
+ """
+ request = {
+ "prompt": prompt,
+ "system_prompt": system_prompt,
+ "image_data": json.dumps(
+ [{key: image[key] for key in ("base64", "mimetype", "filename")} for image in images],
+ sort_keys=True,
+ ensure_ascii=True,
+ separators=(",", ":"),
+ ),
+ "batch_format": "id_checked_v1",
+ "max_retries": "0",
+ "allow_image_fallback": "false",
+ }
+ path = await asyncio.to_thread(_cache_path, client, request)
+ if path is not None:
+ cached = await asyncio.to_thread(_read_batch_captions, path, len(images))
+ if cached is not None:
+ return cached
+ captions = await generate()
+ if (
+ path is not None
+ and len(captions) == len(images)
+ and all(isinstance(caption, str) and caption.strip() for caption in captions)
+ ):
+ await asyncio.to_thread(
+ _write_batch_captions, path, [caption.strip() for caption in captions]
+ )
+ return captions
diff --git a/docs-for-user/SOURCE_VISUALS.md b/docs-for-user/SOURCE_VISUALS.md
index 6a583dc65..9a9a00326 100644
--- a/docs-for-user/SOURCE_VISUALS.md
+++ b/docs-for-user/SOURCE_VISUALS.md
@@ -49,7 +49,10 @@ limits stop queued groups in the job; other API/transport errors do not split.
This only affects subsequently processed images in the existing LlamaIndex
description pass. It does not enable descriptions for structured source visuals
or alter reading-material captions. Batches use a different structured prompt
-and do not reuse the independent single-image caption cache. Setting the size
+and cache complete, successful groups separately from independent single-image
+captions. The digest includes ordered image contents and metadata, prompts,
+model identity, and retry policy. Failed, incomplete, or canceled groups are
+not cached; successful split groups can be reused. Setting the size
back to `1` restores the normal single-image path. The model must support
multiple image blocks; unsupported API responses are reported without a burst
of fallback requests.
diff --git a/tests/services/llm/test_image_caption_batch.py b/tests/services/llm/test_image_caption_batch.py
index b4905967d..ebc316fa9 100644
--- a/tests/services/llm/test_image_caption_batch.py
+++ b/tests/services/llm/test_image_caption_batch.py
@@ -161,3 +161,84 @@ async def test_settings_roundtrip_clamps_and_preserves_omitted_fields(tmp_path,
knowledge.LlamaIndexConfigUpdate(image_description_batch_size=0)
)
assert rag_config.image_description_batch_size() == 1
+
+
+def batch_cache(tmp_path, monkeypatch):
+ from types import SimpleNamespace
+
+ from deeptutor.services.llm import image_caption_cache
+
+ monkeypatch.setattr(
+ image_caption_cache,
+ "get_path_service",
+ lambda: SimpleNamespace(get_parse_cache_root=lambda: tmp_path),
+ )
+ return tmp_path
+
+
+def cached_client(mode="valid"):
+ from deeptutor.services.llm.config import LLMConfig
+
+ client = Client(mode)
+ client.config = LLMConfig(
+ model="vision", api_key="test-secret", base_url="https://example.test/v1"
+ )
+ return client
+
+
+async def test_batch_cache_preserves_request_identity_and_contains_only_captions(batch_cache):
+ client = cached_client()
+ group = images(2)
+ expected = ["IMAGE_0 caption", "IMAGE_1 caption"]
+ assert await batcher(client).describe(group) == expected
+ assert await batcher(client).describe(group) == expected
+ assert len(client.calls) == 1
+ for path in batch_cache.rglob("*.json"):
+ payload = path.read_text()
+ assert json.loads(payload) == {"version": 1, "captions": expected}
+ assert not any(
+ secret in payload + str(path)
+ for secret in ("test-secret", "example.test", "data0", "Be factual")
+ )
+ await batcher(client).describe(list(reversed(group)))
+ client.config.model = "other-vision"
+ await batcher(client).describe(group)
+ await ImageCaptionBatcher(client, prompt="Read labels", system_prompt="Be factual").describe(
+ group
+ )
+ assert len(client.calls) == 4
+
+
+async def test_successful_split_result_is_reused_without_new_provider_requests(batch_cache):
+ client = cached_client("invalid")
+ expected = [f"single {i}.png" for i in range(4)]
+ assert await batcher(client).describe(images(4)) == expected
+ assert len(client.calls) == 7
+ assert await batcher(client).describe(images(4)) == expected
+ assert len(client.calls) == 7
+
+
+ "error",
+ [
+ LLMAuthenticationError(),
+ LLMRateLimitError(),
+ LLMAPIError("down", status_code=503),
+ asyncio.CancelledError(),
+ ],
+)
+async def test_failed_or_canceled_batch_is_retried_on_next_job(batch_cache, error):
+ client = cached_client(error)
+ if isinstance(error, asyncio.CancelledError):
+ with pytest.raises(asyncio.CancelledError):
+ await batcher(client).describe(images(2))
+ else:
+ assert await batcher(client).describe(images(2)) == [None, None]
+ assert not list(batch_cache.rglob("*.json"))
+ client.mode = "valid"
+ assert await batcher(client).describe(images(2)) == ["IMAGE_0 caption", "IMAGE_1 caption"]
+ assert len(client.calls) == 2
diff --git a/tests/services/rag/test_llamaindex_image_description.py b/tests/services/rag/test_llamaindex_image_description.py
index 4838876d3..8db5c5303 100644
--- a/tests/services/rag/test_llamaindex_image_description.py
+++ b/tests/services/rag/test_llamaindex_image_description.py
@@ -274,3 +274,49 @@ async def test_batch_deadline_covers_split_fallback(tmp_path, monkeypatch):
assert len(calls) == 2 # canceled first single fallback; second is never sent
assert time.monotonic() - start < 0.8
assert progress == [1, 2]
+
+
+async def test_cached_batch_ingestion_keeps_source_alignment_and_reports_all_progress(
+ tmp_path, monkeypatch
+):
+ from types import SimpleNamespace
+
+ from deeptutor.services.llm import image_caption_cache
+ from deeptutor.services.llm.config import LLMConfig
+ from deeptutor.services.rag.pipelines.llamaindex import document_loader as loader_module
+
+ calls = []
+
+ async def complete(prompt, **kwargs):
+ calls.append(kwargs)
+ return json.dumps(
+ {
+ "captions": [
+ {"image_id": "IMAGE_1", "caption": "second"},
+ {"image_id": "IMAGE_0", "caption": "first"},
+ ]
+ }
+ )
+
+ _install_multimodal_clients(monkeypatch, complete_fn=complete)
+ client = loader_module.get_image_description_client()
+ client.config = LLMConfig(model="vision", api_key="test", base_url="https://example.test/v1")
+ monkeypatch.setattr(loader_module, "get_image_description_client", lambda: client)
+ monkeypatch.setattr(loader_module, "image_description_batch_size", lambda: 2)
+ monkeypatch.setattr(
+ image_caption_cache,
+ "get_path_service",
+ lambda: SimpleNamespace(get_parse_cache_root=lambda: tmp_path / "cache"),
+ )
+ paths = _make_images(tmp_path, ["a.png", "b.png"])
+ for _ in range(2):
+ progress = []
+ docs = await loader_module.LlamaIndexDocumentLoader().load(
+ [str(p) for p in paths],
+ image_progress_callback=lambda n, total: progress.append((n, total)),
+ )
+ assert [d.metadata["file_name"] for d in docs] == ["a.png", "b.png"]
+ assert [d.text for d in docs] == ["[Image] a.png\n\nfirst", "[Image] b.png\n\nsecond"]
+ assert progress == [(1, 2), (2, 2)]
+ assert len(calls) == 1