执行摘要

• 一句话：content_parts 路径补传 cache_salt，修复前缀缓存键缺失
• 推荐动作：值得快速浏览而非精读：这是一个典型的『路径一致性』补全修复，展示了在多个等价构建路径间保持参数转发行一致性的维护模式；对关注前端入口与前缀缓存交互的读者有一定参考价值，但无复杂设计决策。

功能与动机

PR body 明确指出：/inference/v1/generate 接受顶层 cache_salt，但 content_parts 路径重建 TokensPrompt 时没有拷贝它，导致「otherwise-correct callers can reuse prefix-cache blocks created under a different model version」。作者在提交前核查了已合并的 content-parts PR #51478 及多个搜索词，确认该路径此前无人修复，属于前缀缓存键一致性的功能缺口。

实现拆解

1. 变更入口：仅修改 vllm/entrypoints/scale_out/token_in_token_out/serving.py 中的 serve_tokens 请求处理函数，对应 /inference/v1/generate 端点。
2. 核心变更：在 content_parts 分支中，TokensPrompt(prompt_token_ids=request.token_ids) 构建之后、multi_modal_data / multi_modal_uuids 写入之前，新增 if request.cache_salt is not None: prompt["cache_salt"] = request.cache_salt 两行，仅当 salt 非空时转发，保证 None 场景行为不变。
3. 路径对齐：该端点的 text 路径与 preprocessed-feature 路径（mm_input）此前已转发 cache_salt，本次补齐后三条路径在前缀缓存键语义上保持一致。
4. 测试与配套：未新增或修改测试；作者本地运行 tests/entrypoints/scale_out/token_in_token_out/test_generate_stream.py（12 passed）及 pre-commit 全部通过，CI 由维护者触发 Buildkite #86275，但最终 CI 结果未包含在本次材料中。

关键文件：

• vllm/entrypoints/scale_out/token_in_token_out/serving.py（模块 请求路由；类别 source；类型 core-logic；符号 serve_tokens, TokensPrompt）: 唯一变更文件，修复 content_parts 分支重建 TokensPrompt 时丢失顶层 cache_salt 的问题，是该 PR 的核心与全部改动所在。

关键符号：serve_tokens

关键源码片段

vllm/entrypoints/scale_out/token_in_token_out/serving.py

唯一变更文件，修复 content_parts 分支重建 TokensPrompt 时丢失顶层 cache_salt 的问题，是该 PR 的核心与全部改动所在。

# vllm/entrypoints/scale_out/token_in_token_out/serving.py
# serve_tokens 中 content_parts 分支的处理逻辑（仅展示与本次修复相关部分）
engine_input: EngineInput
if request.content_parts:
    tracker = AsyncMultiModalItemTracker(self.model_config)
    mm_parser = tracker.create_parser()
    for part in request.content_parts:
        ptype = part.get("type", "")
        url = part.get("url")
        uuid = part.get("uuid")
        if ptype == "image_url":
            mm_parser.parse_image(url, uuid)
        elif ptype == "audio_url":
            mm_parser.parse_audio(url, uuid)
        elif ptype == "video_url":
            mm_parser.parse_video(url, uuid)
    mm_data, mm_uuids = await tracker.resolve_items()
    prompt = TokensPrompt(prompt_token_ids=request.token_ids)
    # 关键修复：text 与 features 路径都会把顶层 cache_salt 写入 prompt，
    # 这里对齐行为，避免错误复用其他模型版本生成的 prefix-cache 块
    if request.cache_salt is not None:
        prompt["cache_salt"] = request.cache_salt
    if mm_data:
        prompt["multi_modal_data"] = mm_data
    if mm_uuids:
        prompt["multi_modal_uuids"] = mm_uuids
    (engine_input,) = await self.online_renderer.renderer.render_cmpl_async(
        [prompt]
    )

评论区精华

无实质技术评审交锋：claude[bot] 因 PR 来自 fork 自动跳过评审，维护者 ywang96 直接 APPROVED，说明改动无争议、审查成本低。

• 暂无高价值评论线程

风险与影响

• 风险：
  • 前缀缓存键行为变化：修复生效后，同时使用 content_parts 与 cache_salt 的请求其前缀缓存键将首次正确地纳入 salt，旧缓存条目可能短暂失效一次，之后命中恢复正确。
  • 缺少测试覆盖：PR body 明确 "No tests are changed"，该分支没有直接的单测断言 cache_salt 是否写入 TokensPrompt，回归依赖现有 serving 测试间接兜底。
  • 影响范围收敛：改动仅影响 content_parts 分支，text 与 features 路径行为完全不变，None 场景也保持原逻辑，整体回归面很小。
• 影响：
  • 用户影响：对 Rust 前端 scale_out 调用方，修复了跨模型版本前缀缓存误命中的正确性问题；未使用 cache_salt 的用户无感知。
  • 系统影响：2 行纯 Python 赋值，无性能与资源开销，不影响采样与模型计算。
  • 团队影响：消除了 content_parts 路径与其余两条路径的语义分叉，降低了后续维护者对缓存键行为的理解成本。
  • 风险标记：缺少测试覆盖, 前缀缓存键行为微变

关联脉络

• PR #51478 content-parts PR（标题未在上下文中提供）: PR body 明确引用：本 PR 修复的是 #51478 引入的 content_parts 路径中未转发顶层 cache_salt 的缺口，是对该功能的正确性补全。