[Feat][MM Cache] Skip media loading & decoding if UUID based cache lookup succeeds

docs/features/multimodal_inputs.md

@@ -1408,3 +1408,19 @@ Just like with offline inference, you can skip sending media if you expect cache
         },
 
     ```
+
+#### Early UUID Cache Lookups
+
+When using the HF renderer, vLLM probes the multi-modal processor cache before
+loading an image or video URL with a UUID. Use `skip_early_mm_lookup` to opt out per request.
+
+The first request with an image or video URL and UUID loads and processes the
+media as usual. Repeated requests probe multimodal cache first:
+* ***On a hit***  vLLM skips loading and decoding the URL.
+* ***On a cache miss*** vLLM uses the URL as a fallback and processes the media normally.
+
+If some cached items are evicted between the early lookup and multi-modal processing,
+vLLM loads the retained URLs and retries processing only the missing items.
+
+The UUID is authoritative on a cache hit; vLLM does not verify that the URL
+still identifies the cached media (see [Multimodal Media UUID Security](../usage/security.md#multimodal-media-uuid-security))

tests/entrypoints/openai/responses/test_protocol.py

@@ -5,6 +5,7 @@
 )
 
 from vllm.entrypoints.openai.responses.protocol import (
+    ResponsesRequest,
     serialize_message,
     serialize_messages,
 )
@@ -37,3 +38,12 @@ def test_serialize_messages() -> None:
     }
     msg = Message.from_dict(msg_value)
     assert serialize_messages([msg, dict_value]) == [msg_value, dict_value]
+
+
+def test_skip_early_mm_lookup_is_preserved_in_chat_params() -> None:
+    request = ResponsesRequest(input="hello", skip_early_mm_lookup=True)
+
+    chat_params = request.build_chat_params(None, "auto")
+
+    assert request.skip_early_mm_lookup is True
+    assert chat_params.skip_early_mm_lookup is True

tests/renderers/test_process_multi_modal_uuids.py

@@ -2,29 +2,50 @@
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
 
 from http import HTTPStatus
+from unittest.mock import Mock
 
 import pytest
+from PIL import Image
 
 from vllm.assets.image import ImageAsset
 from vllm.assets.video import VideoAsset
 from vllm.config import CacheConfig, ModelConfig, VllmConfig
 from vllm.entrypoints.serve import create_error_response
+from vllm.multimodal.media import MediaConnector
 from vllm.multimodal.parse import parse_mm_uuids
 from vllm.renderers.hf import HfRenderer
+from vllm.renderers.params import ChatParams
 from vllm.tokenizers.registry import cached_tokenizer_from_config
 
 cherry_pil_image = ImageAsset("cherry_blossom").pil_image
 stop_pil_image = ImageAsset("stop_sign").pil_image
 baby_reading_np_ndarrays = VideoAsset("baby_reading").np_ndarrays
+kimi_vision_chunk_image = {
+    "type": "image",
+    "image": cherry_pil_image,
+    "uuid": "test-image-uuid",
+}
+kimi_vision_chunk_video = {
+    "type": "video_chunk",
+    "video_chunk": [Image.fromarray(frame) for frame in baby_reading_np_ndarrays[:4]],
+    "uuid": "test-video-uuid",
+    "video_idx": 0,
+    "prompt": ("<|media_begin|>video<|media_content|><|media_pad|><|media_end|>"),
+}
 
 
 def _build_renderer(
-    *, mm_cache_gb: float = 4.0, enable_prefix_caching: bool = True
+    *,
+    model: str = "Qwen/Qwen2.5-VL-3B-Instruct",
+    mm_cache_gb: float = 4.0,
+    enable_prefix_caching: bool = True,
+    trust_remote_code: bool = False,
 ) -> HfRenderer:
     model_config = ModelConfig(
-        model="Qwen/Qwen2.5-VL-3B-Instruct",
+        model=model,
         max_model_len=128,
         mm_processor_cache_gb=mm_cache_gb,
+        trust_remote_code=trust_remote_code,
     )
 
     vllm_config = VllmConfig(
@@ -64,6 +85,152 @@ def test_text_only_model_mm_data_maps_to_bad_request():
     assert error_response.error.code == HTTPStatus.BAD_REQUEST
 
 
+@pytest.mark.parametrize(
+    ("modality", "media", "skip_early_mm_lookup"),
+    [
+        pytest.param("image", cherry_pil_image, False, id="image"),
+        pytest.param("video", baby_reading_np_ndarrays, False, id="video"),
+        pytest.param(
+            "video",
+            baby_reading_np_ndarrays,
+            True,
+            id="video-skip-early-mm-lookup",
+        ),
+    ],
+)
+def test_cached_uuid_skips_url_loading(
+    monkeypatch: pytest.MonkeyPatch,
+    modality: str,
+    media: object,
+    skip_early_mm_lookup: bool,
+):
+    renderer = _build_renderer()
+    media_url = f"https://example.com/test.{modality}"
+    media_uuid = f"test-{modality}-uuid"
+    fetch_media = Mock(return_value=media)
+    monkeypatch.setattr(MediaConnector, f"fetch_{modality}", fetch_media)
+
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": f"Describe this {modality}."},
+                {
+                    "type": f"{modality}_url",
+                    f"{modality}_url": {"url": media_url},
+                    "uuid": media_uuid,
+                },
+            ],
+        }
+    ]
+
+    params = ChatParams(skip_early_mm_lookup=skip_early_mm_lookup)
+    _, first_prompts = renderer.render_chat([messages], params)
+    _, second_prompts = renderer.render_chat([messages], params)
+
+    first_input = first_prompts[0]
+    second_input = second_prompts[0]
+    assert first_input["mm_hashes"] == second_input["mm_hashes"]
+    assert fetch_media.call_count == (2 if skip_early_mm_lookup else 1)
+
+
+@pytest.mark.parametrize(
+    ("modality", "media"),
+    [
+        pytest.param("image", cherry_pil_image, id="image"),
+        pytest.param("video", baby_reading_np_ndarrays, id="video"),
+    ],
+)
+def test_uuid_cache_eviction_falls_back_to_url(
+    monkeypatch: pytest.MonkeyPatch,
+    modality: str,
+    media: object,
+):
+    renderer = _build_renderer()
+    mm_processor_cache = renderer.mm_processor_cache
+    assert mm_processor_cache is not None
+
+    first_lookup = True
+
+    def is_cached_once(_mm_hash: str) -> bool:
+        nonlocal first_lookup
+        is_cached = first_lookup
+        first_lookup = False
+        return is_cached
+
+    is_cached_item = Mock(side_effect=is_cached_once)
+    monkeypatch.setattr(mm_processor_cache, "is_cached_item", is_cached_item)
+    fetch_media = Mock(return_value=media)
+    monkeypatch.setattr(MediaConnector, f"fetch_{modality}", fetch_media)
+
+    media_url = f"https://example.com/test.{modality}"
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": f"Describe this {modality}."},
+                {
+                    "type": f"{modality}_url",
+                    f"{modality}_url": {"url": media_url},
+                    "uuid": f"test-{modality}-uuid",
+                },
+            ],
+        }
+    ]
+
+    _, prompts = renderer.render_chat([messages], ChatParams())
+
+    assert len(prompts[0]["mm_hashes"][modality]) == 1
+    assert fetch_media.call_count == 1
+
+
+@pytest.mark.parametrize(
+    ("modality", "media"),
+    [
+        pytest.param("image", kimi_vision_chunk_image, id="image"),
+        pytest.param("video", kimi_vision_chunk_video, id="video"),
+    ],
+)
+def test_early_uuid_lookup_is_disabled_for_unified_vision_chunks(
+    monkeypatch: pytest.MonkeyPatch,
+    modality: str,
+    media: object,
+):
+    renderer = _build_renderer(
+        model="moonshotai/Kimi-K2.5",
+        trust_remote_code=True,
+    )
+    mm_processor_cache = renderer.mm_processor_cache
+    assert mm_processor_cache is not None
+
+    is_cached_item = Mock(return_value=True)
+    monkeypatch.setattr(mm_processor_cache, "is_cached_item", is_cached_item)
+    fetch_media = Mock(return_value=media)
+    monkeypatch.setattr(MediaConnector, f"fetch_{modality}", fetch_media)
+
+    media_url = f"https://example.com/test.{modality}"
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": f"Describe this {modality}."},
+                {
+                    "type": f"{modality}_url",
+                    f"{modality}_url": {"url": media_url},
+                    "uuid": f"test-{modality}-uuid",
+                },
+            ],
+        }
+    ]
+
+    conversation, prompt = renderer.render_messages(messages, ChatParams())
+
+    assert len(conversation) == 1
+    assert prompt["multi_modal_data"] == {"vision_chunk": [media]}
+    assert fetch_media.call_count == 1
+    is_cached_item.assert_not_called()
+
+
 def test_multi_modal_uuids_length_mismatch_raises():
     renderer = _build_renderer()