执行摘要

本 PR 为 vllm 项目中的 CPU Encoder Cache (EC) 连接器（ECCPUConnector）新增了一份全面的使用指南文档。文档详细阐述了该组件如何通过 CPU 层扩展 GPU 编码器缓存以支持多模态处理，并重点介绍了其在 E/PD 分离推理场景下基于 NIXL 的点对点（P2P）传输能力。文档内容覆盖了配置、使用示例、协议细节和故障恢复，填补了该重要功能的文档空白。

功能与动机

该 PR 的核心动机是为新实现的 ECCPUConnector 提供必要的用户文档，以降低采用门槛并确保正确部署。正如 PR body 所述，文档旨在涵盖“功能标志、环境变量、基本设置、NIXL-based EC sharing setup、protocol description”。这对于在生产环境中使用多模态模型进行高效推理的用户尤为重要。

实现拆解

1. 文档结构设计：变更入口是新建文件 docs/features/ec_cpu_connector.md。文档结构从基础到高级，依次覆盖前置条件、本地用法、P2P NIXL 用法、详细协议和配置参考。
2. 内容撰写与细化：
   • 前置条件：明确指出了对 V2 模型运行器的强制要求，并解释了本地模式与 P2P 模式对软件依赖（如 nixl 包）的不同需求。
   • 用法示例：提供了具体的 vllm serve 命令行参数，演示了如何配置 ec_connector、ec_role 和 ec_connector_extra_config 来启动不同模式的实例。
   • 协议深入解析：文档详细描述了控制平面（ZMQ 握手与状态同步）和数据平面（NIXL 数据拉取）的工作流程，包括关键的数据结构（XferReq/XferAck）、状态码（如 NACK_NOT_READY）和超时机制，这对理解系统可靠性至关重要。
   • 配置参考表：以结构化表格形式列出了所有配置项，便于开发者快速查阅。
3. 基于审阅的修正：在 gty111 的审阅过程中，根据反馈修正了两处与代码实现不符的描述：
   • 将 mmap 文件名的来源从 ec_transfer_config.engine_id 更正为 vllm_config.instance_id。
   • 将 vllm_config.is_mm_encoder_only 确认为正确的属性名。

关键源码片段

本 PR 为纯文档变更，不涉及源码修改，因此无需提供源码片段。

评论区精华

审阅讨论完全围绕确保文档的技术准确性展开，体现了团队对文档质量的重视。

Reviewer gty111: “The mmap filename now uses vllm_config.instance_id, not ec_transfer_config.engine_id. The latter is still used for the NIXL agent name.”

该评论精准指出了一个关键的实现细节，确保了文档描述与代码行为完全一致。作者迅速响应并修正，展示了高效的协作流程。

风险与影响

• 技术风险：极低。本 PR 仅新增文档，不修改任何可执行代码，因此不会引入回归、性能或安全风险。
• 维护风险：存在固有风险，即未来代码变更可能导致文档内容过时。但本次文档在合并前已由核心维护者审阅，且描述了相对稳定的协议和配置，短期内过时的可能性较低。
• 影响范围：正面且直接。文档为用户提供了权威的使用参考，显著降低了理解和部署 ECCPUConnector 的难度，特别是其复杂的 P2P 模式。

关联脉络

在提供的近期历史 PR 中，未发现与本 PR 直接关联的实现 PR。本 PR 独立地为已存在或并行开发的 ECCPUConnector 功能补充文档。从历史 PR 列表（如 #53780 NIXL per-region transfer geometry）可以看出，NIXL 和分布式 KV/EC 传输是仓库近期活跃的功能线，本 PR 的文档是对这一生态的重要补充。