执行摘要

• 一句话：chat_utils.py 剩余 ValueError 统一改为 VLLMValidationError
• 推荐动作：值得精读，改动量小但展示了错误类型迁移中容易被忽略的边界：启动期校验与请求期校验的语义区分。关注点包括 VLLMValidationError 的 parameter 语义、VLLMError 非 ValueError 子类带来的兼容性影响，以及 error_response.py fallback 处理器的后续移除方向。

功能与动机

关联 Issue #50253 指出：PR #49665 完成 VLLMError 层级迁移后，vllm/entrypoints/chat_utils.py 中 7 处用户可见校验错误仍抛出裸 ValueError，被 error_response.py 中带 TODO(zqzten) 的 fallback 处理器捕获后 param 字段置为 null，导致依赖 error.param 的客户端逻辑失效。Issue 明确要求补完迁移。作者在 PR body 中也确认了这一点，并强调 VLLMValidationError 不是 ValueError 子类。

实现拆解

1. 背景确认：以 #50253 中列出的 7 个出错点为清单，逐一核对 vllm/entrypoints/chat_utils.py 中对应的 raise 语句，确认它们都绕过了 VLLMValidationError 的结构化错误处理。
2. 首轮转换（commit 046b6e8）：将 7 处 ValueError 全部替换为 VLLMValidationError，其中 validate_chat_template 与 _load_chat_template 带 parameter="chat_template"，_resolve_items 的 image/audio 混合输入分别带 parameter="image_embeds" 与 parameter="audio_embeds"；_merge_embeds、_get_full_multimodal_text_prompt、_reject_reserved_placeholder_in_text 因无单一明确请求字段而暂不传 parameter。
3. Review 纠偏后回退（commit 939435d）：DarkLight1337 指出 validate_chat_template 是启动期（从 cli_args 的 args.chat_template）检查，不应使用请求期语义的 VLLMValidationError；作者按同样推理把 _load_chat_template（经 LLM.init 与 API server 启动路径调用）也回退为 ValueError，最终只保留请求解析路径上的 5 个转换。
4. 测试配套：tests/entrypoints/unit_tests/test_chat_utils.py 的 placeholder 计数用例与 tests/renderers/test_chat_utils_prompt_embeds.py 的保留占位符拒绝用例，均把 pytest.raises 的断言从 ValueError 改为 VLLMValidationError；两个文件此前已导入 VLLMValidationError。

关键文件：

• vllm/entrypoints/chat_utils.py（模块 入口层；类别 source；类型 core-logic；符号 _merge_embeds, _resolve_items, _get_full_multimodal_text_prompt, _reject_reserved_placeholder_in_text）: 核心变更文件：将请求解析路径上 5 处用户可见 ValueError 转换为 VLLMValidationError，并为 image_embeds/audio_embeds 混合输入补充 parameter 字段；validate_chat_template 与 _load_chat_template 按 review 意见回退为 ValueError。
• tests/entrypoints/unit_tests/test_chat_utils.py（模块 单元测试；类别 test；类型 test-coverage；符号 test_parse_chat_messages_multiple_images_interleave_with_placeholders）: placeholder 数量超限用例的异常断言从 ValueError 更新为 VLLMValidationError，是核心行为变更的直接回归保护。
• tests/renderers/test_chat_utils_prompt_embeds.py（模块 渲染测试；类别 test；类型 test-coverage；符号 test_parse_chat_messages_rejects_placeholder_in_user_text）: 保留占位符拒绝用例的异常断言同步更新，覆盖 prompt_embeds 安全护栏路径的新异常类型。

关键符号：_merge_embeds, _resolve_items, _get_full_multimodal_text_prompt, _reject_reserved_placeholder_in_text, validate_chat_template, _load_chat_template

关键源码片段

vllm/entrypoints/chat_utils.py

核心变更文件：将请求解析路径上 5 处用户可见 ValueError 转换为 VLLMValidationError，并为 image_embeds/audio_embeds 混合输入补充 parameter 字段；validate_chat_template 与 _load_chat_template 按 review 意见回退为 ValueError。

def _resolve_items(
    items_by_modality: dict[str, list[tuple[object, str | None]]],
    mm_processor: BaseMultiModalProcessor | None,
    modality_order: dict[str, list[str]],
) -> tuple[MultiModalDataDict, MultiModalUUIDDict]:
    # 同一请求内禁止混用 raw 输入与预计算 embeds。
    # 使用 VLLMValidationError 并带 parameter，让 API 响应中的
    # error.param 返回 "image_embeds" / "audio_embeds" 而非 null。
    if "image" in items_by_modality and "image_embeds" in items_by_modality:
        raise VLLMValidationError(
            "Mixing raw image and embedding inputs is not allowed",
            parameter="image_embeds",
        )
    if "audio" in items_by_modality and "audio_embeds" in items_by_modality:
        raise VLLMValidationError(
            "Mixing raw audio and embedding inputs is not allowed",
            parameter="audio_embeds",
        )
    # prompt_embeds 绕过 HF MM 处理器；其余 modality 必须有 processor。
    processor_modalities = items_by_modality.keys() - {"prompt_embeds"}
    if processor_modalities and mm_processor is None:
        raise RuntimeError(
            _REQUIRE_MM_PROCESSOR_ERROR.format(modality=processor_modalities)
        )

def _reject_reserved_placeholder_in_text(text: str, model_config: ModelConfig) -> None:
    # 启用 prompt_embeds 时，占位符被注册为不可切分的特殊 token。
    # 用户文本若包含该字面量会被误当成 splice 点，解析期直接拒绝。
    if model_config.enable_prompt_embeds and PROMPT_EMBEDS_PLACEHOLDER_TOKEN in text:
        raise VLLMValidationError(
            _RESERVED_PLACEHOLDER_IN_TEXT_ERROR.format(
                token=PROMPT_EMBEDS_PLACEHOLDER_TOKEN
            )
        )

评论区精华

核心争论是启动期错误与请求期错误的语义边界。DarkLight1337 在 validate_chat_template 的 diff hunk 上评论："This shouldn't be a validation error because it's checked at startup time, not when the API is called"。作者据此回退 validate_chat_template 与 _load_chat_template 两处，并说明剩余转换都在 per-request message-parsing 路径上。此外，作者两次反馈 entrypoints-integration-multimodal CI job 失败与本 PR 无关（diff 仅触及 chat_utils.py 与两个单测，且 entrypoints-unit-tests 已通过），请求维护者重试；PR 最终仍被批准合并。

• 启动期 chat template 检查是否应使用 VLLMValidationError (design): 回退 validate_chat_template 与 _load_chat_template 为 ValueError，只保留 per-request 路径上的 5 个转换。
• entrypoints-integration-multimodal CI job 反复失败是否与本 PR 相关 (other): 维护者批准并合并 PR，但该 job 失败的根因未在本 PR 内确认。

风险与影响

• 风险：主要回归风险是异常类型契约变更：VLLMValidationError 不是 ValueError 子类，任何在请求解析路径上 catch ValueError 的内部调用方或第三方包装层都会漏接这 5 个错误；需确认 vllm 内部（如 openai 协议层之外的工具链）没有依赖旧类型。其次，parameter 取值与 issue 建议不同：issue 建议混合输入报错归到 messages，本 PR 实际返回 image_embeds/audio_embeds，虽更精确，但依赖 error.param 的客户端若按 issue 预期实现会短暂不匹配。最后，启动期路径（validate_chat_template/_load_chat_template）保留 ValueError，使启动错误仍走 fallback 处理器，属于有意为之，但错误响应结构不一致，后续迁移时应单独处理启动期错误通道。CI 集成 job 的两次失败未在本 PR 内定位根因，存在环境性 flaky 的残余不确定性。
• 影响：影响面集中在 Chat/多模态 API 的请求校验路径：混合 raw 输入与 embeds、embeds 键不一致、占位符数量超限、保留占位符注入等 5 类错误现在会返回带有正确 param 字段的结构化错误响应，修复依赖 error.param 的客户端逻辑；启动期 chat_template 行为不变。对团队而言，本 PR 是 VLLMError 层级迁移的收尾，缩小了 error_response.py 中 fallback 处理器的适用范围，为彻底移除 TODO(zqzten) 的 fallback 逻辑铺路。影响程度中等偏低，无性能与安全影响。
• 风险标记：VLLMValidationError 非 ValueError 子类，依赖方可能漏接, parameter 取值与 issue 建议不一致（image_embeds vs messages）, 启动期与请求期异常类型分裂，错误结构不统一, CI 集成 job 反复失败未完全归因

关联脉络

• PR #49665 VLLMError hierarchy migration（issue #50253 中引用）: 该 PR 引入 VLLMError 层级并迁移 serving 层，但遗漏 chat_utils.py，是本次 bugfix 的直接起因；error_response.py 中对应的 fallback 处理器仍留有 TODO 待后续移除。