执行摘要

• 一句话：修复 Prometheus 指标将 4xx 错误记录为 5xx
• 推荐动作：值得阅读。本 PR 展示了 FastAPI 中间件层级与 Prometheus 集成的微妙交互，对理解 vLLM 入口错误处理架构有参考价值。测试文件的设计也可以作为组件测试的模板。

功能与动机

在 Starlette 中间件架构中，为特定异常注册的处理程序位于 ExceptionMiddleware，而为通用 Exception 注册的处理程序被移至外层的 ServerErrorMiddleware。由于 prometheus-fastapi-instrumentator 位于两者之间，诸如 ValueError、TypeError、VLLMValidationError 等异常会未处理地经过 Prometheus 中间件，导致指标默认记录为 5xx，即使客户端实际收到正确的 4xx 响应。此问题在生产监控中造成了干扰，需要对齐指标与实际 HTTP 状态码。

实现拆解

步骤 1：导入新增异常类

在 vllm/entrypoints/openai/api_server.py 中补充导入 VLLMNotFoundError，用于处理 404 场景。

步骤 2：注册显式异常处理程序

在 build_app 函数中，除了已有的 VLLMValidationError 和 VLLMUnprocessableEntityError，额外调用 app.exception_handler 注册 VLLMNotFoundError、ValueError、TypeError、OverflowError、NotImplementedError，使其统一由 exception_handler 处理。这样这些异常会被 ExceptionMiddleware（位于 Prometheus 中间件内部）捕获，从而 Prometheus 能正确记录状态码。

步骤 3：新增回归测试

创建 tests/entrypoints/serve/instrumentator/test_http_status_metrics.py，模拟与生产环境完全一致的 FastAPI 应用配置（包括异常处理注册和 Prometheus 仪表化），覆盖：

• 应记录为 4xx 的异常（ValueError、TypeError、OverflowError、VLLMValidationError、VLLMNotFoundError、HTTPException(400)、HTTPException(404)）
• 应记录为 5xx 的异常（NotImplementedError、RuntimeError）
• 正常请求记录为 2xx
  验证 Prometheus http_requests_total 的状态码分组与预期一致。

关键文件：

• vllm/entrypoints/openai/api_server.py（模块 入口；类别 source；类型 entrypoint；符号 build_app）: 核心修复文件，在 build_app 中注册额外的异常处理程序以纠正指标状态码。
• tests/entrypoints/serve/instrumentator/test_http_status_metrics.py（模块 监控测试；类别 test；类型 test-coverage；符号 registry, app, raise_value_error, raise_type_error）: 新增回归测试，覆盖所有受影响及未受影响的异常类型，确保 Prometheus 状态码正确。

关键符号：build_app

评论区精华

争议点：是否将 ValueError 等视作客户端错误过于宽泛？

• markmc 提出 ValueError 等异常并不总是客户端错误，建议先封装为 vLLM 特定错误再处理。
• zqzten 回应称本 PR 仅对齐指标与实际返回码，不改变错误处理语义；错误类型标准化可后续 RFC 讨论。

• noooop 指出 vLLM 入口错误目前碎片化严重，希望标准化。
  最终达成一致：先合并此修复，随后再讨论错误标准化。

• 是否将 ValueError 等视作客户端错误过于宽泛 (design): 决定保持现状，仅修复指标问题，后续再讨论错误标准化。

风险与影响

• 风险：
  • 中间件顺序敏感：修复依赖于 FastAPI 中间件层级顺序，若未来重构中间件堆栈可能会再次破坏指标正确性，但当前策略与框架设计一致，风险低。
  • 异常映射准确性：注册 NotImplementedError 为 exception_handler 可能将部分 5xx 错误映射为 4xx？但实际上 exception_handler 逻辑会返回适当的错误响应（通常映射为 500 或其他），不影响记录；测试已验证 NotImplementedError 仍记录为 5xx。
  • 无回归风险：添加的处理程序与原有兜底处理逻辑一致，仅改变捕获层级，不会影响客户端响应。
• 影响：
  • 用户影响：Prometheus 监控指标更精确，避免运维误判。客户端响应无变化。
  • 系统影响：无性能影响，仅增加少量异常注册语句。
  • 团队影响：为后续错误标准化提供了测试基础和讨论起点。
  • 风险标记：中间件顺序敏感, 异常映射准确性

关联脉络

• PR #44051 [CI] Stabilize the multi-audio OpenAI server path: 该 PR 修复了 VLLMValidationError 情形下的指标记录，为本 PR 提供了基础；本 PR 在此基础上进一步覆盖其他异常类型。