执行摘要

• 一句话：清理 pooling 模型的 build_tok_params 逻辑，提取到 Mixin 类
• 推荐动作：该 PR 是典型的重构，值得关注其 Mixin 设计模式。建议审核时重点关注 EmbeddingTokenizeParamsMixin 中是否保留了 max_output_tokens_param 的原始语义。整体上推荐合并，但需确认行为差异点。

功能与动机

消除 pooling 相关协议类（Embedding、Classification、Scoring、通用 Pooling）中 TokenizeParams 构建逻辑的重复。PR body 说明目的是清理 build_tok_params 逻辑，提取到 Mixins。现有的重复代码导致维护困难，且容易在添加新协议时遗漏或引入不一致。

实现拆解

1. 在 vllm/entrypoints/pooling/base/protocol.py 中新增 _build_pooling_tok_params 方法作为核心构建函数，接收所有可变参数，并依据 max_output_tokens_param 是否为 None 输出是否包含该字段；新增抽象基类 PoolingTokenizeParamsMixin 声明 add_special_tokens 字段并声明抽象方法 _build_pooling_tok_params；新增两个具体 Mixin：FixedMaxLenTokenizeParamsMixin（用于分类、通用池化、评分等固定 max_model_len 的场景）和 EmbeddingTokenizeParamsMixin（用于嵌入场景，需处理 pooler_config 中的 enable_chunked_processing 和 max_embed_len）。

2. 修改 embed/protocol.py：移除独立的 _get_max_total_output_tokens 函数和两个请求类中的 build_tok_params 方法；改为继承 EmbeddingTokenizeParamsMixin，并删除不再需要的导入（ModelConfig、TokenizeParams）。

3. 修改 classify/protocol.py：移除两个请求类中的 build_tok_params 方法，改为继承 FixedMaxLenTokenizeParamsMixin；调整导入。

4. 修改 pooling/protocol.py：将 PoolingCompletionRequest 和 PoolingChatRequest 中的 build_tok_params 移除，改为继承 FixedMaxLenTokenizeParamsMixin；保留 IOProcessorRequest.build_tok_params 但改为调用 self._build_pooling_tok_params。

5. 修改 scoring/protocol.py：将 ScoringRequestMixin.build_tok_params 简化为直接调用 self._build_pooling_tok_params。

6. 测试配套：CI 通过了现有单元测试，无需新增测试。

关键文件：

• vllm/entrypoints/pooling/base/protocol.py（模块 池化基类；类别 source；类型 dependency-wiring；符号 _build_pooling_tok_params, PoolingTokenizeParamsMixin, FixedMaxLenTokenizeParamsMixin, build_tok_params）: 核心变更文件：新增 _build_pooling_tok_params 基础方法、PoolingTokenizeParamsMixin 抽象基类，以及 FixedMaxLenTokenizeParamsMixin 和 EmbeddingTokenizeParamsMixin 两个具体 Mixin，是所有 pooling 协议类 token 参数构建的公共基础设施。
• vllm/entrypoints/pooling/embed/protocol.py（模块 嵌入；类别 source；类型 core-logic；符号 _get_max_total_output_tokens, build_tok_params）: 移除了独立的 _get_max_total_output_tokens 函数和两个请求类中的 build_tok_params 方法，改为继承 EmbeddingTokenizeParamsMixin，大幅化简代码。
• vllm/entrypoints/pooling/classify/protocol.py（模块 分类；类别 source；类型 core-logic；符号 build_tok_params）: 两个请求类移除重复的 build_tok_params，改为继承 FixedMaxLenTokenizeParamsMixin。
• vllm/entrypoints/pooling/pooling/protocol.py（模块 通用池化；类别 source；类型 core-logic；符号 build_tok_params）: PoolingCompletionRequest 和 PoolingChatRequest 移除 build_tok_params 并继承 FixedMaxLenTokenizeParamsMixin；IOProcessorRequest 的 build_tok_params 简化为调用 _build_pooling_tok_params。
• vllm/entrypoints/pooling/scoring/protocol.py（模块 评分；类别 source；类型 core-logic；符号 build_tok_params）: ScoringRequestMixin 原本 inline 构建 TokenizeParams，现在改为调用 _build_pooling_tok_params。

关键符号：_build_pooling_tok_params, PoolingTokenizeParamsMixin._build_pooling_tok_params, FixedMaxLenTokenizeParamsMixin.build_tok_params, EmbeddingTokenizeParamsMixin.build_tok_params, _get_max_total_output_tokens

关键源码片段

vllm/entrypoints/pooling/base/protocol.py

核心变更文件：新增 _build_pooling_tok_params 基础方法、PoolingTokenizeParamsMixin 抽象基类，以及 FixedMaxLenTokenizeParamsMixin 和 EmbeddingTokenizeParamsMixin 两个具体 Mixin，是所有 pooling 协议类 token 参数构建的公共基础设施。

# 集中构建 TokenizeParams 的基础方法，供各 Mixin 使用
def _build_pooling_tok_params(
    self,
    model_config: ModelConfig,
    *,
    add_special_tokens: bool,
    max_total_tokens: int | None,
    max_output_tokens: int,
    max_total_tokens_param: str = "max_model_len",
    max_output_tokens_param: str | None = None,
) -> TokenizeParams:
    encoder_config = model_config.encoder_config or {}
    # 当不需要 max_output_tokens_param 时，构造不包含该字段的 TokenizeParams
    if max_output_tokens_param is None:
        return TokenizeParams(
            max_total_tokens=max_total_tokens,
            max_output_tokens=max_output_tokens,
            truncate_prompt_tokens=self.truncate_prompt_tokens,
            truncation_side=self.truncation_side,
            do_lower_case=encoder_config.get("do_lower_case", False),
            add_special_tokens=add_special_tokens,
            max_total_tokens_param=max_total_tokens_param,
        )
    return TokenizeParams(
        max_total_tokens=max_total_tokens,
        max_output_tokens=max_output_tokens,
        truncate_prompt_tokens=self.truncate_prompt_tokens,
        truncation_side=self.truncation_side,
        do_lower_case=encoder_config.get("do_lower_case", False),
        add_special_tokens=add_special_tokens,
        max_total_tokens_param=max_total_tokens_param,
        max_output_tokens_param=max_output_tokens_param,
    )
​
​
class FixedMaxLenTokenizeParamsMixin(PoolingTokenizeParamsMixin):
    # 用于分类、评分、通用池化等固定 max_model_len 的场景
    def build_tok_params(self, model_config: ModelConfig) -> TokenizeParams:
        return self._build_pooling_tok_params(
            model_config,
            add_special_tokens=self.add_special_tokens,
            max_total_tokens=model_config.max_model_len,
            max_output_tokens=0,
        )

评论区精华

1. Mixin 类型安全争议：gemini-code-assist[bot] 指出 Mixin 中访问 self._build_pooling_tok_params 和 self.add_special_tokens 未在类中定义，可能导致类型检查问题，建议使用 Protocol。作者最初回应称有意避免大量 mypy 改动。随后 DarkLight1337 要求不要在 Mixin 中使用 type: ignore，而是直接在类中声明字段和抽象方法。作者最终采纳，在 PoolingTokenizeParamsMixin 中声明了 add_special_tokens: bool 和 _build_pooling_tok_params（raise NotImplementedError），消除了 type: ignore。

2. 变量阴影问题：gemini-code-assist[bot] 指出 FixedMaxLenTokenizeParamsMixin.build_tok_params 中局部变量与方法名同名，建议直接返回。作者采纳后消除了阴影。

• Mixin 类型安全设计：是否应为缺失的属性和方法提供显式声明 (design): 作者已按 DarkLight1337 的要求修复，消除了 type: ignore，并在基类中声明抽象方法。
• 变量阴影：build_tok_params 方法中局部变量与方法同名 (style): 作者采纳建议，消除了变量阴影。

风险与影响

• 风险：
  1. Embedding 行为差异：原有的 embed/protocol.py 中 build_tok_params 会设置 max_output_tokens_param='max_model_len - max_embed_len'，该字段用于渲染日志。新的 EmbeddingTokenizeParamsMixin.build_tok_params 在调用 _build_pooling_tok_params 时没有显式传递 max_output_tokens_param，导致该参数为 None，从而构建的 TokenizeParams 中不包含该字段。这可能影响依赖该字段的渲染或日志输出，需要确认是否预期行为。

1. 类型安全：虽然已修复 type: ignore，但 Mixin 类仍依赖于调用它的请求类提供 truncate_prompt_tokens、truncation_side 等属性，这些属性来自 PoolingBasicRequestMixin。如果未来 Mixin 被用于不包含这些属性的类，会出现运行时错误。

2. 回归风险：重构涉及 5 个文件，虽然代码量减少但涉及多处导入调整和逻辑移动，若测试覆盖不完全，可能存在未发现的回归。CI 通过可降低风险。
   - 影响：对用户无直接影响，功能等价。对开发者而言，代码更易维护，新增 pooling 请求类型时只需继承相应 Mixin 并实现 to_pooling_params，无需重复编写 build_tok_params。对系统无性能影响。
   - 风险标记：Embedding tokenize 参数行为可能差异, Mixin 依赖外部属性未强约束

关联脉络

• 暂无明显关联 PR