执行摘要
本 PR 为 vLLM 多模态模块引入了可选的媒体 URL 磁盘缓存功能，通过环境变量 VLLM_MEDIA_CACHE 启用。核心变更包括在 MediaConnector 中添加缓存读写逻辑，支持 SHA-256 哈希、原子写、LRU 和 TTL 驱逐，旨在优化推理期间媒体获取性能，减少网络延迟。经过多次 review 讨论和修复，代码已成熟合并，值得关注其并发处理设计。
功能与动机
该功能旨在解决重复下载相同媒体文件导致的性能瓶颈。PR body 中明确说明：“Introduces VLLM_MEDIA_CACHE environment variable for opt-in disk caching of media fetched from URLs”，Issue 评论中提到“Addressed both concerns from RFC”，表明该优化是为了提升多模态推理效率，减少外部依赖。
实现拆解
实现分为三个关键部分：
- 环境配置：在
vllm/envs.py 中新增 VLLM_MEDIA_CACHE、VLLM_MEDIA_CACHE_MAX_SIZE_MB 和 VLLM_MEDIA_CACHE_TTL_HOURS 环境变量，用于控制缓存目录、最大大小（默认 5 GB）和 TTL（默认 24 小时）。
- 缓存逻辑：在
vllm/multimodal/media/connector.py 的 MediaConnector 类中添加私有方法：
_get_cached_bytes(url)：读取缓存，检查 TTL 并更新 LRU 时间戳。_put_cached_bytes(url, data)：写入缓存，使用临时文件原子写，并触发驱逐。_maybe_evict(exclude)：扫描缓存目录，先移除过期文件，再按 LRU 驱逐超出大小的文件。
- 测试覆盖：在
tests/multimodal/media/test_connector.py 中添加单元测试，验证缓存基本操作、TTL 过期和 LRU 驱逐。
评论区精华
Review 讨论中涌现了多个技术洞察：
- 异步阻塞风险：gemini-code-assist[bot] 指出：“The calls to
self._get_cached_bytes(url) and self._put_cached_bytes(url, data) are synchronous file I/O operations... will block the event loop”，作者通过 loop.run_in_executor 修复。
- 竞态条件修复：claude[bot] 发现两个 bug：
_put_cached_bytes 中未初始化变量导致 UnboundLocalError，以及 _get_cached_bytes 中 TOCTOU 可能创建空文件，作者均通过异常处理和原子操作解决。
- 迭代器安全：DarkLight1337 提问：“Is it really safe to delete files while still using the
iterdir() iterator?”，作者重构为先收集再删除，避免文件系统竞态。
- 测试完整性：ywang96 要求：“can we add some simple unit tests for the eviction & TTL functionality?”，作者补充了全面测试。
风险与影响
技术风险：虽然主要竞态问题已修复，但缓存驱逐在高并发下可能成为瓶颈；磁盘 I/O 可能影响异步性能，需监控实际负载。影响范围：用户可显著减少媒体下载时间，提升推理速度，但需管理磁盘空间；系统增加配置项，团队需维护缓存逻辑和测试。
关联脉络
本 PR 与仓库中多个多模态和安全相关 PR 呼应：
- PR #38482 修复 SSRF 漏洞，强调 URL 获取的安全性，与本 PR 的媒体获取功能互补。
- PR #38253 处理多模态图像输入错误，共享同一模块，反映多模态功能的持续优化。
- 依赖 PR #36951（未在历史分析中详述）可能涉及底层媒体处理基础，建议结合查看以理解完整上下文。
参与讨论