执行摘要

• 一句话：移除旧版 KVConnector 构造函数兼容层
• 推荐动作：值得精读，特别是对分布式 KV 传输子系统感兴趣的工程师。本次 PR 示范了如何有计划地清理技术债务——先发出废弃警告，等待合理窗口后移除兼容层。factory.py 中从 warning 到 error 的升级策略值得借鉴。

功能与动机

v0.12.0 版本为 KV Connector 构造函数增加了 KVCacheConfig 参数，并提供了向后兼容支持且附带了显式警告。该警告已发布超过 5 个月（见 #27887），外部连接器有充分时间迁移，因此可以安全删除兼容代码。

实现拆解

1. 接口强制化：在 vllm/distributed/kv_transfer/kv_connector/v1/base.py 中将 kv_cache_config 参数类型从 KVCacheConfig | None 改为必填的 KVCacheConfig，并移除对 None 的兼容处理与相关警告日志。
2. 工厂逻辑简化：在 vllm/distributed/kv_transfer/kv_connector/factory.py 中删除 _get_connector_class_with_compat 方法，将其功能合并到新 get_connector_class 方法；create_connector 不再返回兼容性标记，直接以统一方式传递 kv_cache_config；同时将外部检查失败时的 warning 改为 error + raise ValueError，使问题立即暴露。
3. 内部连接器适配：更新所有内部连接器（mooncake_connector.py、moriio_connector.py、offloading_connector.py、example_hidden_states_connector.py、decode_bench_connector.py）和示例连接器（load_recovery_example_connector.py），使其构造函数统一接受三个必需参数（vllm_config、role、kv_cache_config）。
4. 配套测试更新：删除整个向后兼容性测试文件 tests/v1/kv_connector/unit/test_backwards_compatibility.py，该文件仅测试旧签名；更新其余测试文件（如 test_mooncake_connector.py、test_moriio_connector.py、test_scheduler_kv_connector_override.py 等）中的实例化调用，传入 _make_test_kv_cache_config() 生成的占位 KVCacheConfig。

关键文件：

• vllm/distributed/kv_transfer/kv_connector/factory.py（模块 工厂；类别 source；类型 core-logic；符号 get_connector_class, create_connector）: 核心工厂类，消除了兼容性分支并简化了连接器实例化流程。
• vllm/distributed/kv_transfer/kv_connector/v1/base.py（模块 基类；类别 source；类型 core-logic；符号 init）: 基类构造函数签名变更，从可选变为必填，移除废弃警告。
• tests/v1/kv_connector/unit/test_backwards_compatibility.py（模块 测试；类别 test；类型 deletion；符号 OldStyleTestConnector, NewStyleTestConnector, test_external_old_signature_factory_instantiation）: 被删除的向后兼容性测试文件，移除了对旧签名的专门验证。
• tests/v1/kv_connector/unit/test_mooncake_connector.py（模块 Mooncake测试；类别 test；类型 test-coverage；符号 _make_test_kv_cache_config）: Mooncake 连接器测试更新，适配新签名，增加辅助函数 _make_test_kv_cache_config。
• examples/disaggregated/kv_load_failure_recovery_offline/load_recovery_example_connector.py（模块 示例；类别 source；类型 core-logic；符号 init）: 示例连接器更新构造函数以接受 kv_cache_config 参数，同步基类变更。

关键符号：KVConnectorFactory.get_connector_class, KVConnectorFactory.create_connector, KVConnectorBase_V1.init, MooncakeConnector.init, MoRIIOConnector.init

关键源码片段

vllm/distributed/kv_transfer/kv_connector/factory.py

核心工厂类，消除了兼容性分支并简化了连接器实例化流程。

# vllm/distributed/kv_transfer/kv_connector/factory.py
# 简化后的 get_connector_class 方法，不再返回兼容性标记
@classmethod
def get_connector_class(
    cls, kv_transfer_config: "KVTransferConfig"
) -> type[KVConnectorBaseType]:
    connector_name = kv_transfer_config.kv_connector
    if connector_name is None:
        raise ValueError("Connector name is not set in KVTransferConfig")
​
    connector_module_path = kv_transfer_config.kv_connector_module_path
    if connector_module_path is not None and not connector_module_path:
        raise ValueError("kv_connector_module_path cannot be an empty string.")
​
    if connector_module_path:
        # 外部模块路径优先于内部注册
        connector_module = importlib.import_module(connector_module_path)
        try:
            connector_cls = getattr(connector_module, connector_name)
        except AttributeError as e:
            raise AttributeError(
                f"Class {connector_name} not found in {connector_module_path}"
            ) from e
        connector_cls = cast(type[KVConnectorBaseType], connector_cls)
        # 检查是否支持新签名（kv_cache_config 参数）。
        # 若不支持，直接报错并退出，避免隐式失败。
        if not supports_kw(connector_cls, "kv_cache_config"):
            msg = (
                f"Connector {connector_cls.__name__} uses deprecated "
                "2-argument constructor signature. External v1 KV "
                "connectors must accept kv_cache_config as the third "
                "constructor argument and pass it to super().__init__()."
            )
            logger.error(msg)
            raise ValueError(msg)
    elif connector_name in cls._registry:
        connector_cls = cls._registry[connector_name]()
    else:
        raise ValueError(f"Unsupported connector type: {connector_name}")
    return connector_cls

vllm/distributed/kv_transfer/kv_connector/v1/base.py

基类构造函数签名变更，从可选变为必填，移除废弃警告。

# vllm/distributed/kv_transfer/kv_connector/v1/base.py
# 新的构造函数签名，kv_cache_config 成为必需参数，不再允许 None
class KVConnectorBase_V1:
    def __init__(
        self,
        vllm_config: "VllmConfig",
        role: KVConnectorRole,
        kv_cache_config: "KVCacheConfig", # 以前是 KVCacheConfig | None = None
    ):
        logger.warning(
            "Initializing KVConnectorBase_V1. This API is experimental and "
            "may change in the future."
        )
        if vllm_config.kv_transfer_config is not None:
            self._kv_transfer_config = vllm_config.kv_transfer_config
        else:
            raise ValueError("kv_transfer_config must be set for KVConnectorBase_V1")
        self._kv_cache_config = kv_cache_config
        # 不再需要兼容性检查：旧版本中当 kv_cache_config 为 None 时发出警告，现已完全移除
        self._role = role

评论区精华

• NickLucche 起初要求暂缓：不应该直接让外部连接器崩溃，至少需要一个版本提前警告。但随后根据已有警告已持续 6 个月这一事实，同意删除。
• markmc 建议将外部连接器不兼容的处理从 warning 提升为 error + raise ValueError，以便用户收到明确信息而不是难以理解的回溯；同时建议简化方法名，将 _get_connector_class_with_compat 改名为 get_connector_class。

• orozery 指出移除 None 检查后，base.py 中的额外 if kv_cache_config is None 守卫已冗余，作者据此删除。

• base.py 中冗余的 None 检查 (design): 作者同意并删除了该检查。

• 工厂方法重命名与简化 (design): 作者采纳，重构后工厂类只有一个公开入口 get_connector_class。
• 外部连接器不兼容应从 warning 升级为 error (correctness): 作者采纳，改用 logger.error + raise ValueError。
• 是否应保留向后兼容测试 (testing): 决定删除整个向后兼容测试文件。

风险与影响

• 风险：
  • 向后兼容性风险：任何仍在使用旧签名（仅两个参数）的外部 KV Connector 将在创建时立即抛出 ValueError。由于之前已有 6 个月警告期，预计风险可控。
  • 遗漏更新：如果存在未在本次 PR 中更新的内部或示例连接器，会导致运行时错误。所有已知内部连接器和官方示例已更新，但自定义派生可能漏改。
  • 测试覆盖丢失：删除了专门的向后兼容测试，这部分覆盖将由升级提示替代。
• 影响：
  • 用户影响：外部连接器开发者必须在升级 vLLM 前更新构造函数签名，否则应用崩溃。内部用户无影响，所有内部连接器已适配。
  • 系统影响：代码库更简洁，工厂逻辑复杂度降低，运行时不再执行废弃的兼容分支。
  • 团队影响：缩短了后续维护负担，统一了连接器构造方式。
  • 风险标记：向后兼容性破坏, 外部连接器适配风险

关联脉络

• PR #25712 Initial HMA support for KV Connectors: 引入 KVCacheConfig 参数并提前考虑向后兼容性的首次尝试。
• PR #27887 Add KVCacheConfig argument to KV connector constructors with compat warning: 以更清晰的方式增加了 KVCacheConfig 参数，并添加了废弃警告。本 PR 基于其警告周期结束而移除兼容代码。