执行摘要

• 一句话：协议类型移出 openai 目录，194 文件导入重构
• 推荐动作：值得精读。重点关注三个设计决策：(1) 按“通用基础类型”与“生成流程专属类型”拆分协议模块，避免公共类型长期悬挂在 openai 目录下；(2) 异常类下沉到 vllm/exceptions.py，让 500 语义脱离请求协议；(3) import 重构中 TYPE_CHECKING 与 re-export 的陷阱——本 PR 的三处回归是很好的反面教材。另可留意 claude[bot] 提出的 Buildkite source_file_dependencies 需随文件移动同步更新的运维要点。

功能与动机

PR body 明确说明这是跟随 #41907 #52131 #53500 #53659 的系列演进：早期 vLLM（2023）只有 OpenAI 一种服务，因此在线服务被称为 OpenAI-Compatible Server；进入 2026 年后生成式 AI 发展迅速，vLLM 在线服务增加了大量非 OpenAI 特性，因此应把 engine/protocol.py 移出 openai 文件夹，让共享协议类型不再隶属 OpenAI 专属目录。

实现拆解

1. 新增共享协议基座 vllm/entrypoints/serve/engine/protocol.py：把原 vllm/entrypoints/openai/engine/protocol.py 中最通用的 OpenAI 风格类型（OpenAIBaseModel、ErrorInfo/ErrorResponse、ModelCard/ModelList/ModelPermission、PromptTokenUsageInfo/CompletionTokenUsageInfo/UsageInfo）整体迁入，并保留 __log_extra_fields__ 校验器与 field_names 缓存逻辑，供所有前端复用。
2. 文件重命名与职责收窄：原 vllm/entrypoints/openai/engine/protocol.py 重命名为 vllm/entrypoints/generate/base/protocol.py，只保留与生成流程强相关的类型（SpeculativeDecodingMetrics、PerRequestMetrics、DeltaMessage、ToolCall、FunctionCall 等），改为从 serve/engine/protocol 导入 OpenAIBaseModel 与 UsageInfo，删除本地重复定义，消除两处定义漂移的风险。
3. 异常下沉：GenerationError 从协议模块移入 vllm/exceptions.py，作为 VLLMServerError 子类并在 __init__ 中固定 status_code = HTTPStatus.INTERNAL_SERVER_ERROR，使“生成失败映射 500”的语义与请求协议解耦。
4. 全量导入路径刷新：chat_completion/serving.py、completion/serving.py、responses/serving.py、generate/base/serving.py、scale_out、anthropic、cohere、run_batch 等入口，以及 vllm/reasoning、vllm/tool_parsers、vllm/parser 系列模块统一改写 import；仅用于注解的类型（如 ResponsesRequest）移入 if TYPE_CHECKING: 延迟导入，减少运行时导入链；同时更新至少 54 个测试文件的导入来源。
5. 配套与回归修复：更新 Rust 端 structured_outputs.rs 的文档链接（DarkLight1337 指出）；修复 claude[bot] 发现的 cohere parser 运行时 NameError、测试文件 ErrorResponse 导入错误、step3_reasoning_parser.py 重复导入等问题，并跑通 Buildkite CI（#86307、#86320）后合并。

关键文件：

• vllm/entrypoints/serve/engine/protocol.py（模块 协议层；类别 source；类型 core-logic；符号 OpenAIBaseModel, log_extra_fields, ErrorInfo, ErrorResponse）: 新增的共享协议基座，承载 OpenAIBaseModel、ErrorResponse、UsageInfo 等原本挂在 openai 目录下的通用类型，是本 PR 的迁移目标。
• vllm/entrypoints/generate/base/protocol.py（模块 生成协议；类别 source；类型 rename-or-move；符号 SpeculativeDecodingMetrics, PerRequestMetrics, DeltaMessage, DeltaToolCall）: 由 vllm/entrypoints/openai/engine/protocol.py 重命名而来，保留生成流程专属协议（DeltaMessage、PerRequestMetrics 等），改为从共享模块导入基础类型，是本 PR 的结构核心。
• vllm/exceptions.py（模块 异常模块；类别 source；类型 core-logic；符号 GenerationError, init）: GenerationError 从协议模块下沉到全局异常模块，并固定 500 状态码，使异常语义与请求协议解耦，是本 PR 除文件移动外的少量逻辑变更。
• vllm/entrypoints/generate/base/serving.py（模块 服务层；类别 source；类型 dependency-wiring）: 生成服务基座的导入来源全面切换：PerRequestMetrics 等改从新协议模块导入，ErrorResponse 与 GenerationError 分别指向共享模块与 exceptions，是验证重构正确性的关键接线点。
• vllm/reasoning/cohere_command_reasoning_parser.py（模块 推理解析；类别 source；类型 dependency-wiring；符号 adjust_request）: review 中 claude[bot] 在此发现最高危回归：ChatCompletionRequest 被误移入 TYPE_CHECKING 导致运行时 NameError，修复后成为 import 重构陷阱的典型样本。
• rust/src/server/src/routes/openai/utils/structured_outputs.rs（模块 Rust 路由；类别 source；类型 documentation；符号 JsonSchemaFormat）: DarkLight1337 以 suggestion 要求同步更新文档注释中的 Python 协议定义链接，跨语言一致性配套，避免链接指向已删除文件。

关键符号：GenerationError.init, OpenAIBaseModel.log_extra_fields, DeltaMessage._serialize, CohereCommandReasoningParser.adjust_request

关键源码片段

vllm/entrypoints/serve/engine/protocol.py

新增的共享协议基座，承载 OpenAIBaseModel、ErrorResponse、UsageInfo 等原本挂在 openai 目录下的通用类型，是本 PR 的迁移目标。

# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
#
# 本文件由 vllm/entrypoints/openai/engine/protocol.py 拆分而来，
# 承载所有前端共享的 OpenAI 风格基础类型，避免继续放在 openai 专属目录。
​
import time
from typing import ClassVar
​
from pydantic import BaseModel, ConfigDict, Field, model_validator
​
from vllm.logger import init_logger
from vllm.utils import random_uuid
​
logger = init_logger(__name__)
​
​
class OpenAIBaseModel(BaseModel):
    # OpenAI API 允许请求携带未声明字段，这里显式放行而不是拒绝
    model_config = ConfigDict(extra="allow")
​
    # 缓存类字段名，避免每个实例都重复遍历 model_fields 收集一次
    field_names: ClassVar[set[str] | None] = None
​
    @model_validator(mode="wrap")
    @classmethod
    def __log_extra_fields__(cls, data, handler):
        result = handler(data)
        if not isinstance(data, dict):
            return result
        # 首次调用时收集字段名与别名，之后复用，降低校验开销
        field_names = cls.field_names
        if field_names is None:
            field_names = set()
            for field_name, field in cls.model_fields.items():
                field_names.add(field_name)
                if alias := getattr(field, "alias", None):
                    field_names.add(alias)
            cls.field_names = field_names
​
        # 请求中携带但未被任何字段消费的键，只在 debug 级别记录，避免刷屏
        if any(k not in field_names for k in data):
            logger.debug(
                "The following fields were present in the request but ignored: %s",
                data.keys() - field_names,
            )
        return result
​
​
class UsageInfo(OpenAIBaseModel):
    prompt_tokens: int = 0
    total_tokens: int = 0
    completion_tokens: int | None = 0
    prompt_tokens_details: PromptTokenUsageInfo | None = None
    completion_tokens_details: CompletionTokenUsageInfo | None = None

vllm/entrypoints/generate/base/protocol.py

由 vllm/entrypoints/openai/engine/protocol.py 重命名而来，保留生成流程专属协议（DeltaMessage、PerRequestMetrics 等），改为从共享模块导入基础类型，是本 PR 的结构核心。

# 从 vllm/entrypoints/openai/engine/protocol.py 重命名而来，聚焦“生成流程”相关协议。
# OpenAI 基础类型（OpenAIBaseModel、UsageInfo 等）改从共享模块导入，
# 不再在此重复定义，避免两处定义漂移。
​
import json
from typing import Annotated, Any, Literal, TypeAlias
​
import regex as re
from pydantic import BaseModel, ConfigDict, Field, model_serializer
​
import vllm.envs as envs
from vllm.config.utils import replace
from vllm.entrypoints.chat_utils import make_tool_call_id
from vllm.entrypoints.serve.engine.protocol import OpenAIBaseModel, UsageInfo
from vllm.exceptions import VLLMValidationError
from vllm.logger import init_logger
from vllm.sampling_params import StructuredOutputsParams
from vllm.utils.import_utils import resolve_obj_by_qualname
​
logger = init_logger(__name__)
​
​
class DeltaMessage(OpenAIBaseModel):
    role: str | None = None
    content: str | None = None
    reasoning: str | None = None
    tool_calls: list[DeltaToolCall] = Field(default_factory=list)
​
    @model_serializer(mode="wrap")
    def _serialize(self, handler):
        data = handler(self)
        # 流式 delta 中没有工具调用时省略该字段，保持与 OpenAI 协议一致；
        # 空列表会导致部分客户端把 tool_calls 误判为“发生调用”
        if len(data.get("tool_calls", [])) == 0:
            data.pop("tool_calls", None)
        return data

vllm/exceptions.py

GenerationError 从协议模块下沉到全局异常模块，并固定 500 状态码，使异常语义与请求协议解耦，是本 PR 除文件移动外的少量逻辑变更。

# 从协议模块下沉到全局异常模块，使“生成失败产生 500”的语义
# 与请求 / 响应协议解耦，任何调用方都可以直接复用。
​
from http import HTTPStatus
​
​
class GenerationError(VLLMServerError):
    """finish_reason 表示内部服务错误（500）时抛出"""
​
    def __init__(self, message: str = "Internal server error"):
        super().__init__(message)
        # 显式固定 500，供上层 exception handler 直接映射 HTTP 状态码
        self.status_code = HTTPStatus.INTERNAL_SERVER_ERROR

评论区精华

核心讨论集中在 claude[bot] 的三轮 review，发现并验证修复了 3 处高风险回归：

• 针对 vllm/reasoning/cohere_command_reasoning_parser.py：claude[bot] 指出 ChatCompletionRequest 被错误移入 TYPE_CHECKING，但 adjust_request 在运行时执行 isinstance(request, ChatCompletionRequest)，会导致 NameError: name 'ChatCompletionRequest' is not defined，任何带 reasoning parser 的请求都会崩溃；结论是恢复为顶层运行时导入，仅 ResponsesRequest 保留在 TYPE_CHECKING 下。
• 针对 tests/entrypoints/openai/completion/test_lora_resolvers.py 等三个测试文件：它们从 generate.base.protocol 导入 ErrorResponse，但该模块只 re-export 了 OpenAIBaseModel 与 UsageInfo，测试收集阶段会 ImportError；结论是改从 serve.engine.protocol 导入。
• 针对 vllm/reasoning/step3_reasoning_parser.py：DeltaMessage 在顶层与 TYPE_CHECKING 内重复导入，会触发 ruff F811 导致 CI 失败；结论是删除冗余的 TYPE_CHECKING 导入。
• 附带发现（🟡 可选）：.buildkite/test_areas/misc.yaml 的 source_file_dependencies 仍指向已删除的 vllm/entrypoints/openai/engine/protocol.py，后续编辑新路径的 PR 将静默不触发对应 Buildkite 步骤，当前未确认是否已修复。

• DarkLight1337 在 rust/src/server/src/routes/openai/utils/structured_outputs.rs 上以 suggestion 形式要求把文档注释中的 Python 定义链接更新到新路径，已在 commit 091c4aea 中落实；最终 DarkLight1337 给出 APPROVED。

• cohere parser 运行时 NameError：ChatCompletionRequest 被误收进 TYPE_CHECKING (correctness): 恢复 ChatCompletionRequest 为顶层运行时导入，仅注解用到的 ResponsesRequest 保留在 TYPE_CHECKING 下；后续 review 确认已修复。

• 测试文件从 generate.base.protocol 导入 ErrorResponse 导致 ImportError (testing): 三个测试文件改从 vllm.entrypoints.serve.engine.protocol 导入 ErrorResponse；后续 review 确认已修复。
• step3_reasoning_parser.py 重复导入 DeltaMessage 触发 ruff F811 (style): 删除 TYPE_CHECKING 块内的重复导入；后续 review 确认已修复。
• Buildkite misc.yaml 的 source_file_dependencies 仍指向已删除路径 (infra): 建议把新路径加入该步骤的 source_file_dependencies；当前提交列表与变更摘要中未见 .buildkite 文件改动，状态未确认。
• DarkLight1337 要求更新 Rust 端结构化输出文档链接 (documentation): 作者按 suggestion 更新，提交 091c4aeaeb54 包含该变更。

风险与影响

• 风险：
  1. 回归风险（高）：194 个文件的机械 import 改写中，任何“被移入 TYPE_CHECKING 但运行时仍被引用”或“re-export 缺失”都会直接变成 NameError/ImportError。本 PR 实际已发生 3 例（cohere parser、3 个测试文件、重复导入），虽已修复，但长尾文件仍可能存在未被测试覆盖的同类问题。
  2. CI 配置风险（中）：.buildkite/test_areas/misc.yaml 的 source_file_dependencies 仍指向已删除路径，未来编辑 generate/base/protocol.py 或 serve/engine/protocol.py 的 PR 可能静默漏跑“Async Engine, Inputs, Utils, Worker, Config”步骤。
  3. 兼容性风险（中）：vllm.entrypoints.openai.engine.protocol 是内部模块，但第三方插件、分支或运维脚本若直接导入其中的类型（UsageInfo、ErrorResponse、DeltaMessage 等）将立即断裂。
  4. 运行时开销（低）：纯导入路径变化对性能无实质影响；将注解专用类型移入 TYPE_CHECKING 反而减少了部分运行时导入链。
     - 影响：对最终用户：HTTP API 行为与响应结构完全不变，无感知。对开发者/插件：内部 import 契约被打破，需按新路径迁移；但目录职责更清晰，serve/engine/protocol.py 成为多前端（OpenAI、Anthropic、Cohere、scale_out 等）共享协议基座。对 vLLM 架构演进：这是“去 OpenAI 中心化”系列重构的关键一步，为后续非 OpenAI 前端继续扩展协议类型提供稳定的公共位置。对团队：194 文件的大范围改动需要 CI 全量验证，并建议把 .buildkite/test_areas 的依赖路径同步纳入此类移动的检查清单。
     - 风险标记：194 文件 import 重构, 曾发生运行时 NameError 回归, CI 依赖路径未同步, 外部导入路径破坏

关联脉络

• PR #41907 系列重构：OpenAI 专属概念泛化（PR body 引用）: PR body 列为本 PR 的前置依赖，同属“把 OpenAI 专属概念逐步泛化”的目录与命名重构系列。
• PR #52131 系列重构：OpenAI 专属概念泛化（PR body 引用）: PR body 列为本 PR 的前置依赖，同属“把 OpenAI 专属概念逐步泛化”的目录与命名重构系列。
• PR #53500 系列重构：OpenAI 专属概念泛化（PR body 引用）: PR body 列为本 PR 的前置依赖，同属“把 OpenAI 专属概念逐步泛化”的目录与命名重构系列。
• PR #53659 系列重构：OpenAI 专属概念泛化（PR body 引用）: PR body 列为本 PR 的前置依赖，同属“把 OpenAI 专属概念逐步泛化”的目录与命名重构系列。
• PR #54315 [Frontend] Forward cache salt for content parts: 与本 PR 同样修改 vllm/entrypoints/scale_out/token_in_token_out/serving.py 的导入依赖，证明该文件处于多 PR 并行的 frontend 重构带上。