执行摘要

• 一句话：修复KVConnectorFactory中外部连接器优先级低于内部注册表的问题，确保用户自定义模块优先加载。
• 推荐动作：该PR值得精读，虽然变更规模小，但揭示了KVConnectorFactory设计中的一个重要权衡：内部注册表与外部扩展的优先级管理。关注点：1. 设计决策：选择优先级调整而非禁止重复名称的权衡；2. 防御性编程：添加空字符串验证的细节处理；3. 实际应用场景：KuntaiDu分享的协作问题展示了该修复的实际价值。

功能与动机

根据PR描述，修复目的是解决KVConnectorFactory中连接器解析优先级的问题。原本当外部指定的connector_name与内部注册表名称匹配时，系统会静默使用内部连接器，忽略用户提供的kv_connector_module_path。现在修改为外部模块路径优先于内部注册表，这是预期的行为。KuntaiDu在review中提到实际遇到过此问题：当修复需要同时修改vLLM内部组件和外部组件的bug时，由于PR合并顺序不确定，很难保证两边CI都通过，这个修复有助于解决此类协作问题。

实现拆解

该PR只修改了一个文件vllm/distributed/kv_transfer/kv_connector/factory.py中的_get_connector_class_with_compat方法。主要改动包括：1. 调整逻辑顺序，先检查外部模块路径，再检查内部注册表；2. 添加对空字符串路径的验证，避免importlib.import_module('')引发未处理的ValueError；3. 保持向后兼容性，当外部路径不存在时仍回退到内部注册表。

关键文件：

• vllm/distributed/kv_transfer/kv_connector/factory.py（模块 distributed/kv_transfer）: 这是唯一修改的文件，包含了KVConnectorFactory的核心连接器加载逻辑，优先级调整和空字符串验证都在此实现。

关键符号：_get_connector_class_with_compat

评论区精华

review中主要有两个核心讨论：1. gemini-code-assist[bot]指出原始实现中空字符串路径会导致未处理的ValueError，建议添加显式检查。作者在后续提交中采纳了这一建议。2. chaunceyjiang提出更好的解决方案是禁止重复名称，但最终团队接受了当前优先级的修复方案。KuntaiDu分享了实际遇到此问题的场景：当需要同时修改vLLM内部和外部组件时，由于PR合并顺序不确定，很难保证CI通过，这个修复有助于解决此类协作问题。

• 空字符串路径验证 (correctness): 作者采纳建议，在后续提交中添加了if not connector_module_path: raise ValueError(...)验证。
• 优先级调整方案选择 (design): 团队决定采用优先级调整方案，外部模块路径优先于内部注册表。

风险与影响

• 风险：风险较低：1. 逻辑变更较小，仅调整优先级顺序，不影响核心功能；2. 添加了空字符串验证，避免了潜在的ValueError异常；3. 保持向后兼容性，当外部路径不存在时仍回退到内部注册表；4. 变更集中在单个文件的单个方法中，影响范围有限。潜在风险：如果用户依赖旧的优先级行为（即内部注册表优先），此变更可能导致其自定义连接器被意外加载，但根据PR描述，新行为才是预期行为。
• 影响：影响范围：1. 对用户：修复后用户自定义的KV连接器模块路径将正确优先加载，解决了之前可能被内部注册表静默覆盖的问题，提升了自定义扩展的可靠性。2. 对系统：确保KV连接器加载逻辑符合预期，避免因优先级问题导致的调试困难。3. 对团队：解决了KuntaiDu提到的实际协作问题，当需要同时修改内外组件时，加载优先级明确，减少CI不确定性。影响程度：中等，主要影响使用自定义KV连接器的用户和开发者。
• 风险标记：优先级逻辑变更, 向后兼容性影响

关联脉络

• PR #37636 [KVConnector] Support 3FS KVConnector: 同属KVConnector模块，涉及连接器扩展和工厂模式，展示了KVConnector系统的演进。
• PR #39053 [ROCm][CI] Fix test repo-root assumptions: 同属KVConnector相关测试基础设施，涉及CI环境中的连接器测试。