执行摘要

• 一句话：校验 BGE-M3 组合任务所有权：无插件时给出可操作报错
• 推荐动作：值得精读。虽然源码改动很小，但它是“前端错误处理 + 任务所有权设计”的完整案例：如何避免用 pass-through 掩盖语义缺失、如何把特化逻辑收敛到工厂层保持 serving 层 task-agnostic、以及如何在评审中处理 diff 可评审性（CRLF）与热路径性能问题。对理解 vLLM pooling IO processor 插件架构有直接帮助。

功能与动机

Issue #51801 报告：BGE-M3 default pooling task 'embed&token_classify' has no IO processor, causing an uncaught KeyError on /pooling。PR body 进一步说明：注册 generic pass-through 处理器虽然能避免原 KeyError，但不会执行稀疏响应转换，会暴露未格式化的内部输出；因此必须保持组合任务归插件所有，在无插件时以可操作错误拒绝，有插件时仅注册插件处理器。

实现拆解

实现分五步（源码、测试、文档联动）：

1. 确认任务所有权（设计决策）。review 中 noooop 指出 embed&token_classify 只被 bge_m3_sparse_io_processor_plugins 使用，尝试过 pass-through 方案后作者在 7824b11 改为校验所有权，避免把内部输出直接暴露给用户。

2. 新增拒绝型处理器。在 vllm/entrypoints/pooling/pooling/io_processor.py 中新增 UnsupportedCombinedTaskIOProcessor，name = "embed&token_classify"，create_pooling_params 抛出带指引的 ValueError，提示改用插件请求（带 data 字段）或通过 --pooler-config.task 选择具体任务。这是请求路径上的唯一拦截点。

3. 工厂注册。vllm/entrypoints/pooling/factories.py 的 init_pooling_io_processors 增加分支：pooling_task == "embed&token_classify" 时注册拒绝型处理器；随后独立判断 has_io_processor，插件存在时额外注册 PluginWithIOProcessorPlugins，从而让 ServingPooling 保持 task-agnostic，只在工厂层做任务特化。

4. 测试覆盖。tests/entrypoints/pooling/test_factories.py 新增 94 行三个用例：无插件时工厂返回拒绝处理器；有插件时同时注册 embed&token_classify 与 plugin 两个处理器；有插件时普通 pooling 请求经拒绝处理器抛出含“plugin request with a 'data' field”的 ValueError。测试用 Monkeypatch 隔离 has_io_processor 与 get_io_processor，并构造真实 PoolingCompletionRequest 走 ServingPooling.get_io_processor 全链路。

5. 文档契约。docs/models/pooling_models/specific_models.md 新增三任务映射表（dense → embed、lexical/sparse → token_classify、ColBERT → token_embed），并补充参考插件 bge_m3_sparse_plugin 的安装与请求示例，明确组合任务不是通用 API 的第四种输出格式。

6. Review 驱动的演进。过程中经历三次关键变化：① avm-trev 指出 CRLF 行尾导致 diff 不可评审，作者归一化为 LF（+90/-4）；② avm-trev 指出插件已安装时普通请求仍触发 KeyError，作者补请求级 guard；③ noooop 反对在 get_io_processor 每请求热路径做字符串判断，作者先移到初始化、最终收敛到工厂注册。

关键文件：

• vllm/entrypoints/pooling/pooling/io_processor.py（模块 池化处理器；类别 source；类型 core-logic；符号 UnsupportedCombinedTaskIOProcessor, create_pooling_params）: 核心逻辑所在：新增 UnsupportedCombinedTaskIOProcessor，在 create_pooling_params 阶段给出可操作错误，避免未捕获 KeyError。
• vllm/entrypoints/pooling/factories.py（模块 处理器工厂；类别 source；类型 dependency-wiring；符号 init_pooling_io_processors）: 组合任务的分发入口：init_pooling_io_processors 新增 embedding&token_classify 分支并保持 ServingPooling task-agnostic。
• tests/entrypoints/pooling/test_factories.py（模块 单元测试；类别 test；类型 test-coverage；符号 _bge_m3_config, test_combined_task_without_plugin_uses_rejection_processor, test_combined_task_with_plugin_uses_plugin_processor, test_combined_task_plain_pooling_request_has_actionable_error）: 三个回归用例覆盖无插件拒绝、有插件注册、普通请求报错三条路径，构成完整证据链。
• docs/models/pooling_models/specific_models.md（模块 模型文档；类别 docs；类型 documentation）: 明确 BGE-M3 三任务映射与插件使用契约，是 noooop 评审中要求补充的关键文档。

关键符号：UnsupportedCombinedTaskIOProcessor.create_pooling_params, init_pooling_io_processors, test_combined_task_without_plugin_uses_rejection_processor, test_combined_task_with_plugin_uses_plugin_processor, test_combined_task_plain_pooling_request_has_actionable_error

关键源码片段

vllm/entrypoints/pooling/pooling/io_processor.py

核心逻辑所在：新增 UnsupportedCombinedTaskIOProcessor，在 create_pooling_params 阶段给出可操作错误，避免未捕获 KeyError。

# vllm/entrypoints/pooling/pooling/io_processor.py
​
class UnsupportedCombinedTaskIOProcessor(PoolingIOProcessor):
    """BGE-M3 的 embed&token_classify 组合任务只属于稀疏插件。
​
    通用 Pooling API 没有对应的输出转换逻辑（无法把模型内部输出转成
    dense/sparse 响应），因此这个处理器只负责在请求进入时给出
    可操作的 ValueError，而不是把内部输出直接暴露给用户。
    """
​
    name = "embed&token_classify"
​
    def create_pooling_params(self, request):
        # 提示用户走插件请求（带 data 字段）或改用具体任务
        raise ValueError(
            "The 'embed&token_classify' pooling task is only available "
            "through an IO processor plugin. Send a plugin request with "
            "a 'data' field, "
            "or select a concrete task with --pooler-config.task."
        )
​
​
class PluginWithIOProcessorPlugins(PoolingIOProcessor):
    """IO Processor plugins are a feature that allows pre- and post-processing
    of the model input and output for pooling models."""
​
    name = "plugin"
​
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
​
        # 从插件系统取出真正的 IO processor，负责输入预处理与输出格式化
        io_processor = get_io_processor(
            self.vllm_config,
            self.renderer,
            self.model_config.io_processor_plugin,
        )
​
        assert io_processor is not None
        self.io_processor = io_processor

vllm/entrypoints/pooling/factories.py

组合任务的分发入口：init_pooling_io_processors 新增 embedding&token_classify 分支并保持 ServingPooling task-agnostic。

# vllm/entrypoints/pooling/factories.py
​
# 根据 pooling task 注册对应的 IO Processor。
# 关键点：embed&token_classify 是 BGE-M3 稀疏插件的内部组合契约，
# 不是通用的 Pooling API 输出格式，因此这里注册一个“拒绝型”处理器，
# 而不是让 ServingPooling 去感知任务特化逻辑。
​
def init_pooling_io_processors(
    supported_tasks: tuple[SupportedTask, ...],
    vllm_config: VllmConfig,
    renderer: BaseRenderer,
    chat_template_config: ChatTemplateConfig,
) -> dict[str, PoolingIOProcessor]:
    model_config = vllm_config.model_config
    processors: dict[str, type[PoolingIOProcessor]] = {}
    pooling_task = model_config.get_pooling_task(supported_tasks)
​
    # ... 其他 task（classify / token_classify / embed / token_embed）的注册此处省略 ...
​
    # 组合任务无法在通用 API 下输出正确结果，注册拒绝处理器，
    # 在 create_pooling_params 阶段给出可操作的错误信息。
    if pooling_task == "embed&token_classify":
        from .pooling.io_processor import UnsupportedCombinedTaskIOProcessor
​
        processors[pooling_task] = UnsupportedCombinedTaskIOProcessor
​
    # 插件存在时额外注册 plugin 处理器，正确处理组合任务；
    # 否则仅当 pooling_task 本身就是 plugin 时才注册空实现。
    has_plugin = has_io_processor(
        vllm_config,
        model_config.io_processor_plugin,
    )
    if has_plugin:
        from .pooling.io_processor import PluginWithIOProcessorPlugins
​
        processors["plugin"] = PluginWithIOProcessorPlugins
    elif pooling_task == "plugin":
        from .pooling.io_processor import PluginWithoutIOProcessorPlugins
​
        processors["plugin"] = PluginWithoutIOProcessorPlugins
​
    return {
        task: processor_cls(
            vllm_config=vllm_config,
            renderer=renderer,
            chat_template_config=chat_template_config,
        )
        for task, processor_cls in processors.items()
    }

评论区精华

本 PR 的评审交锋集中且质量高，核心有四轮：

• CRLF 行尾导致 diff 不可评审（avm-trev）：“931 of 931 added lines end with \r；0 of 859 removed lines do……实质变更约 10 行，埋在 931 行里。”作者随后强制改为 LF，diff 变为 +90/-4。
• 插件已安装时 KeyError 仍然幸存（avm-trev）：原始方案只把无插件场景转成启动错误，有插件时普通 pooling 请求路径不变。作者改为请求级 guard。
• 热路径性能（noooop）：“We'd better not put this test on the hot path, to avoid executing it for every request. It would be better to run it at load time.” 作者将判断从每请求的 get_io_processor 移到初始化，最终放入工厂注册。
• 任务所有权（noooop）：“The embedding & token_classify pooling task is only used in the bge_m3_sparse_io_processor_plugins.” 这是方案从 pass-through 转向校验的根本原因。

另外 avm-trev 在真实 GPU 容器中做了 before/after 端到端验证（插件存在时对比状态码与逐 bit 输出），补足了作者 Windows 环境无法收集 serving 模块的缺口。

• CRLF 行尾导致全部文件显示为整文件重写 (style): 作者强制将四个文件归一化为 LF，diff 变为 +90/-4，可正常评审。
• 插件已安装时普通 pooling 请求仍会触发 KeyError (correctness): 作者在 7824b11 改为请求级 guard，普通请求经拒绝处理器得到可操作 ValueError；后续将该逻辑移入工厂注册。
• 组合任务判断不应放在每请求热路径 (performance): 作者先移到 ServingPooling 初始化，最终在 5dbca17 移到工厂注册，每请求路径只剩普通字典查找。
• embed&token_classify 任务所有权归属 (design): 方案定为：组合任务保持插件所有，无插件时拒绝型处理器报错，有插件时仅注册插件处理器。
• 拒绝处理器安放位置与 ServingPooling 重构方向 (design): 作者将特化逻辑封装进 init_pooling_io_processors，ServingPooling 恢复 task-agnostic；文档成为后续重构依据。
• BGE-M3 三任务与插件用法文档补充 (documentation): 作者新增三任务映射表、load-time 参数示例、插件安装与 {task:plugin, data:...} 请求示例，并明确组合任务为内部契约。

风险与影响

• 风险：风险点集中在行为契约变更而非代码本身：

• 前端行为变更：无插件使用 embed&token_classify 时从 KeyError/HTTP 500 变为带指引的 ValueError（4xx）。任何依赖旧行为（哪怕错误行为）的客户端都需要调整。

• 插件路径依赖外部安装：正确路径依赖 tests/plugins/bge_m3_sparse_plugin 的安装；若插件缺失但模型配置仍指向组合任务，只能得到错误提示而非功能。
• 文档契约收紧：文档明确组合任务不是通用 API 格式，可能影响现有按组合任务配置的部署脚本。
• 回归面较小：改动仅在工厂注册与请求参数构造阶段，未触碰 ServingPooling 的 task 分发主逻辑，也完全不涉及模型执行路径，性能无影响（检查在初始化/工厂层完成，不在每请求热路径）。

• 影响：影响范围集中在 Pooling 前端与 BGE-M3 用户：

• 用户：BGE-M3 在 /pooling 下不再遇到难以理解的 KeyError/500，而是获得指明“装插件或选具体任务”的错误；需要改用插件请求格式或三个具体任务之一。

• 系统：工厂处理器注册表多一个条目，PoolingIOProcessor 子类多一个拒绝型变体，无运行时性能开销。
• 团队：文档明确了 BGE-M3 三任务与插件契约，为后续 ServingPooling 的进一步重构提供了依据；noooop 在评审中明确表示依赖该文档来决策重构方向。
• 风险标记：前端协议行为变更, 依赖外部插件安装, 文档契约收紧, 无性能影响但回归面窄

关联脉络

• PR #52528 [Bugfix][Frontend] Guard remaining before-validators against non-object JSON bodies: 同为前端协议层错误处理加固（把未捕获异常转为可读 4xx），与本次把 KeyError/500 转为可操作 ValueError 是同一类健壮性改进，涉及部分重叠的 entrypoints 路径（pooling / tokenize / transcription 等 protocol.py）。
• PR #52309 [Frontend] Consolidate entrypoint middleware: 同为 entrypoints/serve 路径的重构，与本次将 pooling 特化逻辑收敛进工厂、保持 serving 层 task-agnostic 的趋势一致，反映前端 entrypoint 层正在系统性整合与简化。