执行摘要

• 一句话：统一 vllm_xargs 类型支持列表值
• 推荐动作：变更简单清晰，但为保持 API 一致性值得合并。建议在合并后关注是否有用户反馈列表值处理异常。

功能与动机

部分 OpenAI 请求 schema（如 chat completions）已允许 vllm_xargs 字段传入列表值，但 completion 和 transcription 请求只接受标量值，造成 API 行为不一致。PR #48252 将此类型对齐，以支持自定义扩展需要传递多个值的情况。

实现拆解

1. 修改 vllm/entrypoints/openai/completion/protocol.py 中 CompletionRequest 类的 vllm_xargs 字段类型注解，从 dict[str, str | int | float] 扩展为 dict[str, str | int | float | list[str | int | float]]，并更新字段描述，添加 "(list of)" 提示。
2. 同步修改 vllm/entrypoints/speech_to_text/transcription/protocol.py 中 TranscriptionRequest 类的相同字段，保持一致。
3. 仅涉及类型注解和文档字符串的调整，无运行时代码逻辑变更。

关键文件：

• vllm/entrypoints/openai/completion/protocol.py（模块 入口层；类别 source；类型 data-contract；符号 CompletionRequest）: 核心变更文件，修改 CompletionRequest 中 vllm_xargs 字段的类型，允许标量或列表值。
• vllm/entrypoints/speech_to_text/transcription/protocol.py（模块 入口层；类别 source；类型 data-contract；符号 TranscriptionRequest）: 同步修改 TranscriptionRequest 中 vllm_xargs 字段类型，保持全端统一。

关键符号：未识别

关键源码片段

vllm/entrypoints/openai/completion/protocol.py

核心变更文件，修改 CompletionRequest 中 vllm_xargs 字段的类型，允许标量或列表值。

# vllm/entrypoints/openai/completion/protocol.py
# CompletionRequest 类的 vllm_xargs 字段定义
​
vllm_xargs: dict[str, str | int | float | list[str | int | float]] | None = Field(
    default=None,
    description=(
        "Additional request parameters with (list of) string or "
        "numeric values, used by custom extensions."
    ),
)

评论区精华

Review 中，维护者 DarkLight1337 发现 speech_to_text 协议中也存在相同的 vllm_xargs 字段，建议一并更新。提交者 sagearc 立即响应并完成同步修改，该线程已解决。

• 遗漏 speech_to_text 中的同类字段 (question): sagearc 回复 'done' 并提交了同步修改，该问题已解决。

风险与影响

• 风险：风险极低。变更仅修改了 Pydantic 模型字段的类型注解和描述，不涉及运行时逻辑。由于 Python 动态类型特性，这类注解不会影响现有请求的处理。但需注意，若下游代码依赖 vllm_xargs 值类型判断（例如仅处理标量），传入列表值可能引发未预期行为。不过该改动为向后兼容（原标量仍可用），且列表值已在其他 schema 中支持，整体风险可控。
• 影响：影响范围限定在通过 completion 和 transcription API 端点传入 vllm_xargs 参数的用户。现在这些端点也支持传入列表值，与 chat 和 response 端点行为一致。对系统性能、安全无影响，无需配置或部署变更。
• 风险标记：低风险, 类型注解变更, 向后兼容

关联脉络

• PR #47922 （源 PR）可能涉及 vllm_xargs 其他改动: 本 PR 从中拆分出来，专注于对齐 completion schema。