执行摘要

• 一句话：重置 vLLM 多模态和编码器缓存
• 推荐动作：值得阅读。本 PR 修复了多模态 rollout 中一个实用的缓存一致性 Bug，设计上通过扩展现有方法而非引入新入口点，保持了架构整洁。虽然版本检查方式有争议，但当前实现对于已知 vLLM 版本是安全的。

功能与动机

PR body 指出：此前更新权重后只对 prefix/KV 缓存执行 reset，但对于多模态 rollout，vLLM 还会缓存多模态输入和编码器输出。权重更新后复用这些缓存会导致 stale features（过时特征）被使用，影响生成结果的正确性。

实现拆解

本 PR 的核心变更是在 verl/workers/rollout/vllm_rollout/vllm_async_server.py 的 clear_kv_cache 方法中新增对多模态缓存和编码器缓存的清理，并根据版本进行条件调用。

1. vllm_async_server.py — 增强 clear_kv_cache：在原有 reset_prefix_cache 调用之后，添加两个版本条件判断：

   • 如果 _VLLM_VERSION >= version.parse('0.9.0')，则调用 self.engine.reset_mm_cache() 清理多模态缓存；
   • 如果 _VLLM_VERSION >= version.parse('0.16.0')，则调用 self.engine.reset_encoder_cache() 清理编码器缓存。
     该设计使得旧版本 vLLM 在未支持对应 API 时自动跳过，保证了向后兼容性。

2. vllm_rollout.py — 更新注释：将 update_weights 方法中原有的注释 # reset prefix cache after updating weights 改为 # reset caches after updating weights，以反映缓存清理范围已扩大。调用链路不变，仍为 self.server_handle.clear_kv_cache.remote()，因此无需修改调用逻辑。

3. 测试与配置：本 PR 未添加专门的测试或配置文件，但通过 review 评论确认了实现细节，并在提交记录中反映了对 review 评论的响应。

关键文件：

• verl/workers/rollout/vllm_rollout/vllm_async_server.py（模块 rollout；类别 source；类型 core-logic）: 核心变更文件，在 clear_kv_cache 方法中新增多模态缓存和编码器缓存的清理逻辑。
• verl/workers/rollout/vllm_rollout/vllm_rollout.py（模块 rollout；类别 source；类型 core-logic）: 更新 update_weights 方法中的注释以反映缓存清理范围扩大，调用入口不变。

关键符号：clear_kv_cache, update_weights

关键源码片段

verl/workers/rollout/vllm_rollout/vllm_async_server.py

核心变更文件，在 clear_kv_cache 方法中新增多模态缓存和编码器缓存的清理逻辑。

async def clear_kv_cache(self):
    if self.node_rank == 0:
        # reset_connector=True drops any attached external KV store
        # (e.g. MooncakeStoreConnector) whose entries were computed
        # against the previous model weights. With no connector it
        # is a no-op success, so we can pass it unconditionally.
        await self.engine.reset_prefix_cache(**_RESET_PREFIX_CACHE_KWARGS)
​
        # 清理多模态缓存（vLLM >= 0.9.0 支持）
        if _VLLM_VERSION >= version.parse("0.9.0"):
            await self.engine.reset_mm_cache()
        # 清理编码器缓存（vLLM >= 0.16.0 支持）
        if _VLLM_VERSION >= version.parse("0.16.0"):
            await self.engine.reset_encoder_cache()

评论区精华

Review 中主要有两个讨论点：

• 设计决策（wuxibin89 评论）：建议将 reset_mm_cache / reset_encoder_cache 合并到 clear_kv_cache 方法中，而非新增 clear_all_caches 方法。作者 s-isaev 接受了建议，直接将逻辑移至 clear_kv_cache 内。

• 版本检查的健壮性（gemini-code-assist[bot] 评论）：指出使用硬编码版本号 0.16.0 脆弱，因为当前 vLLM 发布在 0.7.x 范围，该检查可能永远为 False。作者选择继续使用版本检查，但 reviewer 并未进一步硬性要求改为 hasattr，最终以 APPROVED 状态合并。

• 将多模态/编码器缓存清理合并到 clear_kv_cache (design): 作者接受建议，直接将逻辑嵌入 clear_kv_cache，并删除了 clear_all_caches 方法。

• 硬编码版本检查的健壮性 (design): 维持当前版本检查方式，PR 仍获批准合并。

风险与影响

• 风险：主要风险来自版本检查的准确性：
  • 硬编码的版本号 0.9.0 和 0.16.0 可能在未来 vLLM 版本中失效（如 API 名称变化或版本号跳跃），导致缓存清理遗漏或错误。
  • 如果 reset_mm_cache 或 reset_encoder_cache 在旧版本中不存在，当前代码通过版本条件避免调用，但如果版本检查不匹配实际 API 存在性，仍可能引发 AttributeError。
  • 影响范围仅限于多模态 rollout 场景，且仅影响权重更新后的缓存清理行为，回归风险较低。
  • 影响：影响范围中等，主要影响使用 vLLM 进行多模态训练的用户。在权重更新后，缓存清理更彻底，避免因过期特征导致的生成错误（正确性提升）。对单模态用户无行为变化，因为 reset_mm_cache 和 reset_encoder_cache 在无多模态输入时是空操作。由于仅改动 2 个文件共 6 行代码，且链路清晰，开发成本低。
  • 风险标记：硬编码版本检查

关联脉络

• 暂无明显关联 PR