执行摘要

• 一句话：重构评分API为IOProcessor模式，统一跨编码器、双编码器和延迟交互架构的在线和离线处理逻辑。
• 推荐动作：该PR是理解vLLM池化任务架构演进（特别是向统一IOProcessor模式迁移）的绝佳案例，值得核心开发者精读。重点关注ScoringIOProcessor的设计如何封装不同评分算法的差异，以及OfflineInputsContext/OfflineOutputsContext如何统一在线和离线处理的接口。同时，应留意review中提到的关于异常处理策略和抽象层次选择的讨论，这对设计类似的模块有借鉴意义。

功能与动机

根据PR正文，变更的主要目的是“改进评分池化入口点。准备集成jina-reranker-v3 #28557”。这表明重构是功能演进（集成新模型）的前置步骤，旨在清理和统一现有评分API的实现，使其架构能够更好地支持后续扩展。

实现拆解

重构围绕引入ScoringIOProcessor基类及其三个子类（BiEncoderIOProcessor， CrossEncoderIOProcessor， LateInteractionIOProcessor）展开，替代了原先单一的ServingScores类。核心改动点包括：

1. 架构统一：将评分逻辑从vllm/entrypoints/pooling/score/目录迁移并重组至vllm/entrypoints/pooling/scoring/，建立清晰的io_processor.py， serving.py， protocol.py， utils.py， typing.py模块。
2. 离线API集成：修改vllm/entrypoints/llm.py中的score方法，删除原先独立的_embedding_score， _late_interaction_score， _cross_encoding_score私有方法，改为通过io_processor_factories初始化的ScoringIOProcessor来统一处理。
3. 上下文对象引入：在vllm/entrypoints/pooling/typing.py中定义了OfflineInputsContext和OfflineOutputsContext，PoolingServeContext也支持了ScoringRequest，使预处理和后处理的接口更一致。
4. 多模态支持增强：在typing.py中定义了ScoreMultiModalParam等专门类型，并在测试中增加了图像与文本混合评分的验证用例（如新增的test_late_interaction_offline_vision.py）。
5. 依赖更新：全面更新了导入路径（从pooling.score改为pooling.scoring）和测试代码，确保重构后所有功能正确运行。

关键文件：

• vllm/entrypoints/pooling/scoring/io_processor.py（模块 entrypoints/pooling/scoring）: 新增的核心抽象层，定义了ScoringIOProcessor基类及其三个具体子类（BiEncoder， CrossEncoder， LateInteraction），统一了所有评分模式的前后处理逻辑。
• vllm/entrypoints/pooling/scoring/serving.py（模块 entrypoints/pooling/scoring）: 新的ServingScores类，替代了被删除的旧版本，作为评分API的在线服务入口，依赖于IOProcessor，结构更简洁。
• vllm/entrypoints/llm.py（模块 entrypoints）: 删除了大量旧的私有评分方法（_embedding_score等），改为通过init_pooling_io_processors获取并调用ScoringIOProcessor，是离线评分API重构的核心。
• vllm/entrypoints/pooling/typing.py（模块 entrypoints/pooling）: 引入了OfflineInputsContext和OfflineOutputsContext数据类，以及更新PoolingServeContext以支持ScoringRequest，是统一处理接口的关键改动。
• vllm/entrypoints/pooling/score/serving.py（模块 entrypoints/pooling/score）: 整个旧版ServingScores类被移除（删除667行），标志着架构的彻底迁移，是本次重构规模的直接体现。

关键符号：ScoringIOProcessor.pre_process_online, ScoringIOProcessor.post_process_online, ScoringIOProcessor.pre_process_offline, ScoringIOProcessor.post_process_offline, ServingScores._build_response, LLM.score (重构后的实现)

评论区精华

Review讨论主要集中在架构设计权衡上：

1. 异常处理策略：noooop提出希望在最高层统一捕获和处理异常，而不是在各个层级使用create_error_response。DarkLight1337回应指出应用层级已有异常处理器，并提及PR #31164曾尝试类似改进。
2. 抽象层次选择：noooop询问新建的Preprocessor类应与现有的renderer， io_processor， input_processor中哪一层对齐。DarkLight1337建议考虑在IO Processor中添加“hooks”来修改输入提示，并指出当前Preprocess抽象可能不适用于离线API（因为离线API没有固定的聊天模板）。
3. 具体实现问题：claude[bot]的自动化审查指出了两个潜在缺陷：一是Mistral分词器检查被错误地放在了所有评分处理器的基类中；二是多模态处理器参数（mm_processor_kwargs）在预处理流程中被静默丢弃。
4. 类型定义简化：DarkLight1337建议在协议中使用ScoreInput | list[ScoreInput]而不是单独的ScoreInputs类型别名，以保持一致性。

• 异常处理的统一策略 (design): 倾向于利用现有的应用级异常处理器，而非在每个服务层重复处理。
• Preprocess抽象的适用性与层级 (design): 需要更通用的、同时支持在线和离线API的抽象方式，“hooks”是一个潜在方向。
• 自动化审查发现的实现缺陷 (correctness): 指出了需要修复的潜在bug，尤其是多模态参数传递问题。

风险与影响

• 风险：风险主要集中在重构的彻底性和潜在回归：
  1. 功能回归风险：对vllm/entrypoints/llm.py中LLM.score()方法的大幅修改（删除252行）和vllm/entrypoints/openai/engine/serving.py中评分相关验证逻辑的移除，如果新的IOProcessor链路存在未覆盖的边界情况，可能导致现有评分功能出错。
  2. 多模态支持缺陷：如claude[bot]指出，mm_processor_kwargs参数未正确传递至_pre_process，这可能导致依赖此参数进行图像处理的多模态模型（如JinaVL reranker）产生错误结果。
  3. 条件检查错位：Mistral分词器的检查被放在ScoringIOProcessor基类的__init__中，这会错误地影响所有评分子类（包括双编码器和延迟交互），而该检查原本仅针对跨编码器。
  4. 测试覆盖不确定性：尽管新增和修改了大量测试文件，但如此大规模的重构仍需依赖现有测试套件的完整性来确保无回归。
     - 影响：
     1. 对用户的影响：对于直接使用LLM.score()离线API或通过HTTP/score， /rerank端口的用户，本次重构旨在保持接口不变，属于内部实现优化，理论上无感知。但内部逻辑的重组可能影响性能特征和错误信息。
     2. 对系统的影响：显著改善了代码库中评分功能的内聚性和可维护性。将三种评分模式统一到IOProcessor框架下，使其与池化任务的其他部分（分类、嵌入）架构对齐，降低了未来的扩展成本。
     3. 对团队的影响：为后续集成jina-reranker-v3（issue #28557）铺平了道路。新的架构要求开发者熟悉IOProcessor模式，但提供了更清晰、一致的扩展接口。
        - 风险标记：核心路径变更, 多模态支持缺陷, 缺少测试覆盖

关联脉络

• PR #31164 [Refactor] Unify top-level exception handling for serving requests: 在讨论异常处理策略时被DarkLight1337提及，是先前尝试统一顶层异常处理的PR，与本PR中关于错误处理设计的讨论直接相关。
• PR #28557 （推测，未在列表中给出具体信息）: PR正文中明确指出本次重构是为“集成jina-reranker-v3 #28557”做准备，因此该issue/PR是本次工作的直接驱动因素和后续目标。