执行摘要

• 一句话：统一文档化 pooling 配置解析优先级
• 推荐动作：值得阅读：该文档清晰地解释了 pooling 配置的优先级链，对于使用 vLLM 部署 pooling 模型的用户是重要的参考。

功能与动机

PR body 说明：Pooling 配置优先级目前仅在高层有描述且分散在模型特定指引中。此文档变更将当前解析链集中记录在一个位置：用户提供的 --pooler-config 字段、支持的 Sentence Transformers 元数据以及架构或任务默认值。同时区分嵌入归一化与分类激活，说明标准 DispatchPooler 适配器与自定义 pooler 的行为，并提供无权重加载的检查片段。这是对 PR #48030 中 pooling 日志配置的跟进。

实现拆解

1. 重构文档表格：原 README 中描述默认属性的表格后增加了“Resolution precedence”章节，详细列出各字段（pooling_type、use_activation、分类激活函数）的优先级来源与覆盖方式。
2. 定义解析链：明确 --pooler-config > Sentence Transformers modules.json > 架构/任务默认值的三级优先级。同时澄清当前 PoolerConfig 没有 normalize 或 activation 字段，use_activation 控制归一化或分类激活是否应用。
3. 补充注意事项：指出 Sentence Transformers 新版本紧凑格式 pooling_mode 字符串目前无法解析（关联 issue #45995），以及标准 DispatchPooler 适配器与自定义 pooler 的行为差异。
4. 提供检查代码片段：新增 Python 代码示例 inspect() 函数，展示如何使用 ModelConfig 和 PoolerConfig 在无权重加载时检查解析后的 pooling 配置。

关键文件：

• docs/models/pooling_models/README.md（模块 文档；类别 docs；类型 documentation；符号 inspect）: 唯一变更文件，文档化 pooling 配置的完整解析优先级、字段覆盖方式和检查代码。

关键符号：inspect

关键源码片段

docs/models/pooling_models/README.md

唯一变更文件，文档化 pooling 配置的完整解析优先级、字段覆盖方式和检查代码。

# 轻量级函数：在不加载模型权重的情况下检查解析后的 pooling 配置
from vllm.config import ModelConfig, PoolerConfig
from vllm.model_executor.layers.pooler.activations import get_act_fn
​
def inspect(requested: PoolerConfig) -> None:
    model_config = ModelConfig(
        "intfloat/e5-small",
        runner="pooling",
        pooler_config=requested
    )
    # 通过构造 ModelConfig 触发配置解析，但不加载权重
    resolved = model_config.pooler_config
    print(f"Resolved pooler config: {resolved}")

评论区精华

审核者 yewentao256 在第一次评论中表示“LGTM, let's wait until previous PR got landed”，随后在依赖的 PR #48030 合并后批准了本 PR。无其他 review 评论或争议。

• 暂无高价值评论线程

风险与影响

• 风险：纯文档变更，无任何代码修改，风险极低。
• 影响：仅影响文档页面 docs/models/pooling_models/README.md。对用户理解 pooling 配置的解析逻辑有显著帮助，尤其是使用 Sentence Transformers 模型的用户。对系统功能无任何影响。
• 风险标记：暂无

关联脉络

• PR #48030 Add pooling logging config: 本 PR 是 PR #48030 的跟进，文档化该 PR 中引入的 pooling 日志配置的解析链。