执行摘要

本 PR 修复了 Rust 前端 /v1/completions 端点中一个边缘 case：当客户端发送显式 "max_tokens": null 时（OpenAI Python SDK 的默认行为），请求会被当作无限制处理，导致生成到整个上下文窗口用完。修复通过在 CompletionRequest 中实现 Normalizable::normalize()，将 None 在反序列化后自动转换为默认值 Some(16)，与 Python vLLM 的行为对齐。新增回归测试验证此逻辑。

功能与动机

OpenAI 兼容 API 中，/v1/completions 的 max_tokens 参数在文档中默认值为 16。然而，当客户端（如官方 OpenAI Python SDK）未设置此参数时，它会序列化为 {"max_tokens": null}，而非省略该字段。Serde 的 #[serde(default)] 仅在 JSON 中缺失键时生效——显式的 null 导致 Option<u32> 反序列化为 None。这个 None 随后通过 resolve_max_tokens 使用整个剩余上下文窗口（max_model_len - prompt_len）作为生成长度，而非文档中的默认 16，导致意外的长生成，增加延迟和成本。此前 Python 端已通过 #45491 修复此问题。

实现拆解

1. 在 types.rs 中实现 Normalizable trait
   - 文件：rust/src/server/src/routes/openai/completions/types.rs
   - 将空实现 impl Normalizable for CompletionRequest {} 替换为显式实现 fn normalize(&mut self)。
   - 在 normalize 内部检查 self.max_tokens.is_none()，若为真，则赋值为 default_completion_max_tokens() 的返回值（即 Some(16)）。
   - 该 normalize 方法由 ValidatedJson 提取器在请求反序列化后自动调用，无需额外注册。

2. 在 convert.rs 中添加回归测试
   - 文件：rust/src/server/src/routes/openai/completions/convert.rs
   - 添加导入 crate::routes::openai::utils::types::Normalizable。
   - 新增测试 normalize_coerces_null_max_tokens_to_default：

   • 验证省略 max_tokens 的请求获得默认 Some(16)（Serde 字段默认）。
   • 验证显式 {"max_tokens": null} 的请求反序列化为 None。
   • 调用 request.normalize() 后，验证 max_tokens 变为 Some(16)。

3. CI/测试验证
   - 运行 cargo test -p vllm-server --lib completions::，85 个测试通过。
   - cargo clippy 和 cargo fmt 无问题。

rust/src/server/src/routes/openai/completions/types.rs

核心修复：实现 Normalizable trait 的 normalize 方法，处理 max_tokens: None 回退到默认值。

impl Normalizable for CompletionRequest {
    /// Normalize the request by applying defaults.
    fn normalize(&mut self) {
        // An explicit `"max_tokens": null` deserializes to `None`, bypassing the
        // serde field default. Coerce it back to the default so it behaves like
        // an absent field, matching Python vLLM's `normalize_null_max_tokens`.
        if self.max_tokens.is_none() {
            self.max_tokens = default_completion_max_tokens();
        }
    }
}

评论区精华

• BugenZhao: LGTM. Thanks for the alignment!
  审核者直接批准，强调与 Python 端行为对齐的重要性。

• chatgpt-codex-connector: Codex Review: Didn't find any major issues. Bravo.
  自动化审查未发现重大问题。

风险与影响

风险：极低。改动仅影响 CompletionRequest 的 normalize 流程，与 Python 端逻辑一致，且由单元测试覆盖。ChatCompletion 不受影响，其使用 max_completion_tokens 字段。

影响：修复了使用 OpenAI Python SDK 客户端时生成无限制的潜在问题，提升与 OpenAI API 的行为兼容性。用户感知：使用 max_tokens: null 的请求现在会回退到默认 16，而非无限生成。

关联脉络

本 PR 是 Python 端修复 #45491 的 Rust 对应部分，实现了跨前端的语义一致性。与历史 PR 无直接冲突或依赖，是一个独立的修复。