执行摘要

• 一句话：标准化VLLM异常层次，统一错误响应与状态码
• 推荐动作：建议所有 vLLM 贡献者阅读此 PR 以理解新的异常层次设计，并在后续开发中遵循 VLLMClientError / VLLMServerError 的划分创建新异常。特别推荐关注 vllm/exceptions.py 和 vllm/entrypoints/openai/api_server.py 中的异常处理注册方式。

功能与动机

根据 RFC #48227，目前 vLLM 的错误处理碎片化：代码库中 2000 多个 raise ValueError 被用于各种场景（输入校验、内部断言、模型执行），导致 AsyncLLM.generate 将内部 ValueError 误当作客户端错误（HTTP 400），而本应是 5xx 的服务器错误却被记录为 4xx。同时 Prometheus 中间件因异常未在 ExceptionMiddleware 中被处理而记录错误状态码。需要引入语义化的异常层次来正确映射状态码。

实现拆解

1. 扩展异常层次：在 vllm/exceptions.py 创建 VLLMError 基类，分裂 VLLMClientError（4xx）与 VLLMServerError（5xx）。将 VLLMValidationError、VLLMUnprocessableEntityError、VLLMNotFoundError 的父类改为 VLLMClientError（而非 ValueError/Exception）。

2. 迁移引擎/请求验证中的 ValueError：在 vllm/v1/engine/input_processor.py、vllm/sampling_params.py、vllm/pooling_params.py、vllm/inputs/engine.py 等处，将参数校验、任务支持检查等场景的 raise ValueError 改为 raise VLLMValidationError。同时保留少数确属类型错误的 TypeError 不变。

3. 统一 API 异常处理：在 vllm/entrypoints/openai/api_server.py 中，移除原来对各具体异常（EngineGenerateError、EngineDeadError、VLLMValidationError 等）的独立 handler 注册，改为只注册一个 app.exception_handler(VLLMError)，并由 create_error_response 根据异常层次自动分派状态码。同时更新 server_utils.py，引入 vllm_error_handler 替换原有的多个 handler。

4. 调整测试配套：修改 40+ 个测试文件中的 pytest.raises(ValueError, ...) 为 pytest.raises(VLLMValidationError, ...)。重构了 HTTP 状态码指标测试，改为使用真实的 build_app 构建应用，保证 Prometheus 回归覆盖。

5. 修复边角错误：在 vllm/inputs/engine.py 中将 encoder-decoder prompt_embeds 被误转 500 的问题修复（通过迁移到 VLLMValidationError 使其成为 400）。

关键文件：

• vllm/exceptions.py（模块 异常层次；类别 source；类型 core-logic；符号 VLLMError, VLLMClientError, VLLMServerError, VLLMValidationError）: 异常层次核心定义，新增 VLLMError、VLLMClientError、VLLMServerError 并重新继承现有异常，是整个 PR 的基础。
• vllm/v1/engine/exceptions.py（模块 引擎异常；类别 source；类型 core-logic；符号 EngineGenerateError, EngineDeadError）: 引擎级别的异常 EngineGenerateError 和 EngineDeadError 改为继承 VLLMServerError，确保它们映射到 500 状态码。
• vllm/sampling_params.py（模块 参数验证；类别 source；类型 core-logic；符号 _verify_args）: 大量采样参数验证逻辑中的 ValueError 被替换为 VLLMValidationError，是主要迁移之一。
• vllm/entrypoints/openai/api_server.py（模块 API入口；类别 source；类型 entrypoint；符号 build_app）: API 入口点，移除多异常 handler 注册，改用统一的 VLLMError handler，简化异常处理配置。
• vllm/entrypoints/serve/utils/error_response.py（模块 错误响应；类别 source；类型 core-logic；符号 create_error_response）: create_error_response 根据异常层次映射 HTTP 状态码，是状态码分发的核心逻辑。
• tests/entrypoints/serve/instrumentator/test_http_status_metrics.py（模块 测试；类别 test；类型 test-coverage；符号 should_do_global_cleanup_after_test, _build_args, raise_http_exception_400, raise_http_exception_404）: 测试重构为使用真实 build_app，确保 Prometheus 指标覆盖，是回归测试的关键保障。
• vllm/v1/engine/input_processor.py（模块 输入处理；类别 source；类型 dependency-wiring；符号 _validate_params, _validate_lora, process_inputs, _validate_prompt_len）: 引擎输入处理器中的多个 ValueError 改为 VLLMValidationError，影响所有请求验证路径。

关键符号：VLLMError, VLLMClientError, VLLMServerError, VLLMValidationError, VLLMNotFoundError, VLLMUnprocessableEntityError, EngineGenerateError, EngineDeadError, vllm_error_handler, create_error_response, build_app, _verify_args, _validate_params

关键源码片段

vllm/exceptions.py

异常层次核心定义，新增 VLLMError、VLLMClientError、VLLMServerError 并重新继承现有异常，是整个 PR 的基础。

from typing import Any
​
class VLLMError(Exception):
    """Base class for all vLLM-specific errors.
    Subclasses are split into `VLLMClientError` (4xx) and `VLLMServerError` (5xx).
    """
​
​
class VLLMClientError(VLLMError):
    """Base class for errors caused by the client request (4xx)."""
​
​
class VLLMServerError(VLLMError):
    """Base class for errors caused by the server (5xx)."""
​
​
class VLLMValidationError(VLLMClientError):
    """Validation error (400). Supports `parameter` and `value` fields."""
​
    def __init__(
        self,
        message: str,
        *,
        parameter: str | None = None,
        value: Any = None,
    ) -> None:
        super().__init__(message)
        self.parameter = parameter
        self.value = value
​
    def __str__(self):
        base = super().__str__()
        extras = []
        if self.parameter is not None:
            extras.append(f"parameter={self.parameter}")
        if self.value is not None:
            extras.append(f"value={self.value}")
        return f"{base} ({', '.join(extras)})" if extras else base
​
​
class VLLMNotFoundError(VLLMClientError):
    """Not Found (404)."""
    pass
​
​
class VLLMUnprocessableEntityError(VLLMClientError):
    """Unprocessable Entity (422)."""
    # __init__ and __str__ same as VLLMValidationError
​
​
# 原有的 EngineGenerateError 和 EngineDeadError 继承 VLLMServerError（见 vllm/v1/engine/exceptions.py）

评论区精华

• 异常类型迁移的范围讨论：noooop 质疑是否所有 ValueError 都要改为 VLLMValidationError，DarkLight1337 回应使用特定异常使错误处理更容易。作者 zqzten 坚持全改，因为标准化正是此 PR 的目标。

• 测试覆盖保护：euisuh 指出删除 test_http_status_metrics.py 会失去对 Prometheus 状态码回归的防护，要求保留等价覆盖。作者回应称该测试被保留并重构为使用真实 build_app，继续提供覆盖。

  • 是否将所有 ValueError 改为 VLLMValidationError (design): 作者坚持全改以达成标准化，得到 reviewer 认可。
  • 删除 test_http_status_metrics.py 后的测试覆盖保护 (testing): 测试文件保留并重构，覆盖依然存在。

风险与影响

• 风险：

  • 兼容性风险：VLLMValidationError 从继承 ValueError 变为继承 VLLMClientError，外部代码如果使用 except ValueError 捕获原先的 VLLMValidationError / VLLMUnprocessableEntityError 将失效。虽影响面可能很小，但需要文档说明。

• 回归风险：改动涉及 46 个文件，大量原有 ValueError 被替换，如果某处 ValueError 本应被当作服务器错误（5xx），现在变为 VLLMValidationError 会变成 4xx，可能改变业务预期。但按照 RFC，所有 ValueError 在生成路径中原本就会被当作 400，所以实际不会改变。

• 测试覆盖风险：虽然大部分测试已更新，但可能遗漏某些边缘路径的异常类型。

• 影响：
  • 用户面：API 响应状态码无变化。正确类型的错误依然返回原有状态码。唯一潜在感知是，如果用户代码依赖捕获 ValueError 来捕获 VLLMValidationError（例如自定义中间件），需要改为捕获 VLLMClientError。
  • 系统面：Prometheus http_requests_total 指标现在能正确记录 4xx/5xx；根据位置更早的 ExceptionMiddleware 处理，不再错误记录为 5xx。
  • 团队面：后续新增错误类型只需继承 VLLMClientError 或 VLLMServerError，无需再为 API handler 注册。错误处理代码更集中。
  • 风险标记：兼容性 breakage, 大规模改动, ValueError 捕获依赖, 测试覆盖不足风险

关联脉络

• 暂无明显关联 PR