执行摘要

• 一句话：OffloadConnector 新增 max_offload_tokens 参数
• 推荐动作：该 PR 设计清晰，参数校验严格，测试覆盖全面。建议合并，并鼓励用户按需使用该参数优化卸载量。合并前注意处理合并冲突（PR 历史上曾出现 merge conflict，需要 rebase）。

功能与动机

见 RFC #39305。目前 OffloadConnector 会卸载整个 prompt 的 KV cache，但在某些场景下只需前缀即可复用，后续部分是冗余的。新增 max_offload_tokens 参数允许用户控制卸载范围，减少不必要的 I/O 和存储开销。

实现拆解

1. 字段与解析：在 RequestOffloadState 类中新增 max_offload_tokens: int | None 字段，并在 __post_init__ 方法中解析 kv_transfer_params 的 max_offload_tokens 参数。解析时使用 type(raw) is int and raw >= 0 严格校验类型（避免 bool 误判），非合法值时记录警告并忽略。

2. 应用上限：在 SchedulerOffloadConnector._build_store_jobs 方法中，计算 num_offloadable_tokens 后，如果 max_offload_tokens 不为 None，则取两者最小值作为最终可卸载 token 数。

3. 测试覆盖：新增 test_max_offload_tokens_validation 单元测试，使用 request_runner fixture 验证 None、字符串、浮点、负数、布尔、零和正整数等各种输入下的行为，确保类型校验和 capping 逻辑正确。

关键文件：

• vllm/distributed/kv_transfer/kv_connector/v1/offloading/scheduler.py（模块 卸载调度；类别 source；类型 core-logic；符号 RequestOffloadState, _build_store_jobs）: 选择性卸载的核心逻辑：字段定义、参数解析、以及在 _build_store_jobs 中的应用
• tests/v1/kv_connector/unit/offloading_connector/test_scheduler.py（模块 卸载调度；类别 test；类型 test-coverage；符号 test_max_offload_tokens_validation, make_runner, setup）: 新增测试函数 test_max_offload_tokens_validation，全面覆盖参数验证的各类输入

关键符号：RequestOffloadState.post_init, _build_store_jobs, test_max_offload_tokens_validation

评论区精华

Review 中主要讨论了以下要点：

• 参数命名：offload_prompt_tokens 改为 max_offload_tokens，更具自解释性。
• 解析位置：将参数解析从 _build_store_jobs 移至 RequestOffloadState.__post_init__，避免重复解析。
• 类型安全检查：使用 type(raw) is int 而非 isinstance(val, int)，防止 True/False 被误认为 int 类型。
• 实验性标注：添加注释说明该字段为实验性，可能在未来变更或移除。

• 单元测试：应 reviewer 要求，添加了完整的边界测试。

• 参数命名：从 offload_prompt_tokens 改为 max_offload_tokens (design): 接受建议，改为 max_offload_tokens

• 解析逻辑应移至 RequestOffloadState 创建时 (design): 接受建议，将解析移至 post_init
• 类型检查：严格排除 bool 类型 (correctness): 接受建议，使用 type(raw) is int
• 需要单元测试覆盖各种输入边界 (testing): 已添加 test_max_offload_tokens_validation，覆盖 None、str、float、负值、bool、0、正整数等场景

风险与影响

• 风险：风险较低。如果用户传入非法值（如字符串、浮点、负数），会回退到无上限行为，不影响原有功能。单元测试覆盖了主流边界情况。唯一潜在风险是用户设置过小值导致未命中可复用的 KV 前缀，但这由用户自行控制。
• 影响：用户侧：新增 max_offload_tokens 参数，用户可在 API 请求的 kv_transfer_params 中设置，控制卸载的前缀 token 数。对有选择性卸载需求的场景（如只关心 prompt 前 N 个 token 的 KV cache）可显著减少通信与存储。

系统侧：参数只影响 OffloadConnector 的调度行为，不影响其他组件。当设置值低于实际前缀命中长度时，可能降低前缀复用收益，但不会导致错误。

团队侧：代码简洁，单元测试完整，维护成本低。

• 风险标记：实验性功能, 配置参数解析

关联脉络

• PR #39305 RFC: Max offload tokens for prefix KV connector: 该 RFC 是此 PR 的动机和设计基础，虽未直接关联为 issue，但 PR body 中引用了 RFC #39305