[RFC]: Opt-in Media URL Cache for `MediaConnector`

[RFC]: Opt-in Media URL Cache for MediaConnector

快速结论：每次 vLLM 处理包含媒体 URL（图片、音频、视频）的请求时，MediaConnector 都会重新下载整个文件，即使同一 URL 刚刚被请求过。该 RFC 提议通过一个 opt-in 的环境变量 VLLM_MEDIA_CACHE 添加 URL 级别缓存，以解决 CI 测试中网络不可靠导致的重复下载和测试失败问题。优先排查是否启用了缓存环境变量以及文件系统权限。

问题场景

在使用 vLLM 进行推理时，尤其是 CI 测试环境或生产环境（如 AMD CI 构建、NFS 共享存储、Kubernetes 持久卷），MediaConnector 会为每个包含媒体 URL 的请求重新发起 HTTP 下载，导致：

• CI 测试环境：重复下载相同媒体文件导致测试随机失败、运行时间膨胀。
• 生产环境/气隙环境：网络受限或防火墙后的机器上，重复下载导致 HTTP 连接拒绝错误。
• 批量推理：同一图片 URL 在 100 个请求中被下载 100 次，浪费网络和存储。

报错原文

[RFC]: Opt-in Media URL Cache for MediaConnector

Every time vLLM processes a request containing a media URL (image, audio, video), MediaConnector.load_from_url() performs a fresh HTTP download, even if that exact URL was fetched seconds ago in a previous request. There is no deduplication or caching layer for URL-based media.

This creates real problems in two areas:
* CI / testing infrastructure: On CI machines with limited or unreliable network access, repeated downloads of the same media across test runs cause flaky tests and inflated runtimes.
* Production / on-prem deployments: Many organizations run vLLM on infrastructure behind firewalls, in air-gapped environments, or on machines with constrained egress. Repeated identical downloads is likely to result in HTTP conn refusal errors.

原因分析

最可能的原因是 MediaConnector.load_from_url() 缺乏 URL 级别的缓存机制，每次调用都执行完整的 HTTP 下载，导致重复请求。对于 CI 和受限网络环境，这种设计不合理。

环境排查

• 确认 vLLM 版本（该 RFC 配套的 PR #36951 和 #37123 是解决该问题的实现）。
• 确认 VLLM_MEDIA_CACHE 环境变量是否被设置。
• 确认缓存路径的磁盘权限（写保护测试在 _maybe_evict() 中执行）。
• 确认缓存目录的磁盘空间（默认最大 5 GB，LRU 淘汰策略）。

解决步骤

1. 设置环境变量：添加 VLLM_MEDIA_CACHE=/path/to/cache/dir 来启用缓存。默认未设置即不启用，行为与之前一致。
2. 配置缓存参数（可选）：
   • VLLM_MEDIA_CACHE_MAX_SIZE_MB：默认 5 GB，超限后 LRU 淘汰。
   • VLLM_MEDIA_CACHE_TTL_HOURS：默认 24 小时，超期自动淘汰。
3. 处理权限问题：如果缓存路径不可写，vLLM 会记录警告并自动禁用缓存，回退到默认行为，不会崩溃。
4. 预填充缓存（气隙环境）：可以将常用媒体文件预填充到缓存目录中，vLLM 会直接从磁盘加载，绕开 HTTP 请求。
5. CI 集成：在 CI 中挂载宿主目录到容器（类似 HF_HOME、VLLM_CACHE_ROOT 模式），避免跨测试运行重复下载。

验证方法

确认一个简单方法：启动 vLLM 后，发送一个包含媒体 URL 的请求，观察首次和第二次请求的 HTTP 请求日志。启用缓存后，第二次请求不应产生新的 HTTP 下载操作。另一种方式：检查 VLLM_MEDIA_CACHE 指定目录下是否生成了文件（文件名是基于 URL 的 SHA-256 哈希值）。

参考来源

vllm-project/vllm #37075