# PR #37424 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[Responses API] Add kv_transfer_params for PD disaggregation
- 合并时间：2026-03-21 13:48
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/37424

---

# 执行摘要
本 PR 在 vLLM 的 Responses API 中添加了 `kv_transfer_params` 字段支持，使该 API 能够用于 PD disaggregation 场景，与 Chat Completions API 保持功能一致。变更遵循现有模式，已通过端到端测试，风险较低。

# 功能与动机
动机源于 Issue #37422，指出 Responses API 缺少 `kv_transfer_params` 字段，导致无法通过该 API 使用 PD disaggregation 功能。Chat Completions API 已支持此功能，因此需为 Responses API 添加对等支持以提升用户体验和系统一致性。

# 实现拆解
实现涉及三个关键文件：
- **protocol.py**: 在 `ResponsesRequest` 中添加 `kv_transfer_params` 字段，并在 `to_sampling_params` 方法中将其注入 `SamplingParams.extra_args`；在 `ResponsesResponse` 中添加对应字段，并在 `from_request` 方法中传递。
- **context.py**: 为 `SimpleContext`、`ParsableContext`、`HarmonyContext` 和 `StreamingHarmonyContext` 四个 context 类型添加 `kv_transfer_params` 属性，在 `append_output` 方法中从 `RequestOutput` 更新，并添加 guard 处理多回合场景。
- **serving.py**: 在 `responses_full_generator` 函数中将 `context.kv_transfer_params` 传递到响应构建中。

# 评论区精华
主要讨论聚焦于 `context.py` 中 `append_output` 方法内的 guard 条件：
> Reviewer chaunceyjiang: "It seems that this `if` is not necessary."
> 作者 bongwoobak: "The guard is intentional here. The Responses API supports multi-turn agentic loops... Only the first prefill turn returns valid `kv_transfer_params`... Without the guard, the `None` from a later turn would overwrite the valid value."
最终确认 guard 是确保多回合处理正确性的关键设计。

# 风险与影响
**风险**: 技术风险较低，因变更模式与现有 Chat Completions API 一致。但需注意 guard 逻辑在多回合场景下的正确性，避免值覆盖错误。
**影响**: 用户现在可通过 Responses API 使用 PD disaggregation，扩展了应用场景；系统 API 功能更加完整；团队维护因模式一致而简化。

# 关联脉络
与此 PR 相关的历史 PR 包括 #37498，后者修复了 Responses API 中 `arrival_time` 记录问题，两者共同完善 Responses API 功能。这表明 vLLM 项目正持续优化前端 API，以支持更复杂的部署场景如 PD disaggregation。