执行摘要

本 PR 修正了 Rust 前端 --reasoning-parser 在两种启动路径下的语义不一致问题。Python-supervised 路径的默认值从 auto 改为 none，以对齐 Python CLI 行为；Rust managed-engine 路径则保留 auto 默认并在启动前解析为具体值转发给 Python 引擎，确保 thinking_token_budget 等依赖 reasoning-aware 状态的特性正确工作。

功能与动机

动机来自 Rust 前端两种启动模式（Python-supervised bootstrap 和 Rust managed-engine）下 parser-selection 语义的不一致。Python-supervised 模式通过 JSON 接收参数时，省略的 tool_call_parser 和 reasoning_parser 被反序列化为 auto（与 Python CLI 的默认值不同），导致解析器默认启用；而 Rust managed-engine 模式则保留 auto 但仅在 Rust 侧使用，未通知 Python 引擎。这种不一致使得 thinking_token_budget 等功能依赖的 reasoning-aware 状态无法正确创建。

实现拆解

1. 分离两条路径的默认值：在 rust/src/cmd/src/cli.rs 中，将 SharedRuntimeArgs 的 tool_call_parser 和 reasoning_parser 字段的 serde 默认值从 default (即 ParserSelection::Auto) 改为 default = "default_py_bootstrap_parser_selection"，并新增返回 None 的默认函数。Python-supervised 路径（通过 JSON 反序列化）因此默认禁用解析器；而 clap 的 default_value_t 保持不变，故 managed-engine 路径仍默认 auto。

2. 实现 auto 解析与转发：新增 effective_engine_reasoning_parser 函数，对于 Auto 选择使用全局 ReasoningParserFactory 根据模型名解析具体 parser 名称；显式指定或禁用则直接返回。在 ServeArgs::to_managed_engine_config 中调用该函数，将解析结果作为新参数传入 into_config。

3. 修改引擎配置构建：在 rust/src/managed-engine/src/cli.rs 的 ManagedEngineArgs::into_config 中新增 reasoning_parser: Option<&str> 参数，若为 Some 则追加 --reasoning-parser 和对应值到 python_args。同时更新了 -- 转义机制的文档注释，强调 Rust 不做验证或去重。

4. 更新测试：在 rust/src/cmd/src/cli/tests.rs 中将部分断言改用 expect_test 快照测试，并新增四个测试用例覆盖 auto 解析、显式指定、禁用和 passthrough 场景。

5. CI 配置调整：在 .buildkite/test_areas/rust_frontend.yaml 中跳过两个已知暴露的测试（test_invalid_json_schema 和 test_invalid_regex），避免阻塞 CI。

rust/src/cmd/src/cli.rs

核心逻辑变更：定义默认值函数 default_py_bootstrap_parser_selection() 和解析转发函数 effective_engine_reasoning_parser()，修改 ServerArgs::to_managed_engine_config() 以传递解析后的 parser 名称。

// 为 Python-supervised 模式提供默认值 : 禁用解析器以匹配 Python CLI 行为
fn default_py_bootstrap_parser_selection() -> ParserSelection {
    ParserSelection::None
}
​
// 解析 effective reasoning parser 用于转发给 Python 引擎
fn effective_engine_reasoning_parser(
    selection: &ParserSelection,
    model: &str,
) -> Option<String> {
    match selection {
        // Auto 模式 : 使用全局工厂解析模型对应的 parser
        ParserSelection::Auto => ReasoningParserFactory::global()
            .resolve_name_for_model(model)
            .map(str::to_string),
        // 用户显式指定 None: 不转发
        ParserSelection::None => None,
        // 其他显式值 : 原样转发
        other => Some(other.to_string()),
    }
}
​
// 在 to_managed_engine_config 中调用 :
pub fn to_managed_engine_config(&self, handshake_port: u16) -> ManagedEngineConfig {
    let reasoning_parser =
        effective_engine_reasoning_parser(&self.runtime.reasoning_parser, &self.runtime.model);
    self.managed_engine.clone().into_config(
        self.runtime.model.clone(),
        self.runtime.max_model_len,
        self.runtime.max_logprobs,
        reasoning_parser.as_deref(), // 新参数
        self.runtime.language_model_only,
        self.runtime.disable_log_stats,
        self.runtime.shutdown_timeout,
        handshake_port,
    )
}

rust/src/managed-engine/src/cli.rs

引擎配置构建：into_config 方法新增 reasoning_parser 参数，将解析后的 parser 名称追加到 python_args 中，确保 Python 引擎接收到正确的 --reasoning-parser 参数。同时更新文档说明 -- 传参的转义语义。

pub fn into_config(
    self,
    model: String,
    max_model_len: Option<u32>,
    max_logprobs: Option<i32>,
    reasoning_parser: Option<&str>, // 接收解析后的 parser 名称
    language_model_only: bool,
    disable_log_stats: bool,
    shutdown_timeout: u64,
    handshake_port: u16,
) -> ManagedEngineConfig {
    let mut python_args = self.python_args;
    if let Some(max_model_len) = max_model_len {
        python_args.push("--max-model-len".to_string());
        python_args.push(max_model_len.to_string());
    }
    if let Some(max_logprobs) = max_logprobs {
        python_args.push("--max-logprobs".to_string());
        python_args.push(max_logprobs.to_string());
    }
    // 新加 : 若解析到 reasoning parser 则转发
    if let Some(reasoning_parser) = reasoning_parser {
        python_args.push("--reasoning-parser".to_string());
        python_args.push(reasoning_parser.to_string());
    }
    // 其他参数不变 ...
    ManagedEngineConfig {
        python: self.python,
        model,
        handshake_host: self.handshake_host,
        handshake_port,
        data_parallel_size: self.data_parallel_size,
        python_args,
    }
}

评论区精华

PR 由 njhill 批准，无公开讨论记录。

风险与影响

• 兼容性风险：Python-supervised 路径默认值从 auto 改为 none，依赖自动推断的用户需显式指定 parser 参数。
• 参数转发风险：managed-engine 模式新增 --reasoning-parser 转发，若 Python 引擎不识别该参数或解析器名称不匹配，将导致启动失败。
• 测试覆盖风险：CI 跳过了 test_invalid_json_schema 和 test_invalid_regex，可能掩盖参数校验相关的回归。
• 影响范围：用户在使用 vllm serve（Python-supervised）时需要注意 parser 默认不再自动启用；vllm-rs serve（managed-engine）用户无感知但后端行为更一致。团队需验证 Python 端 reasoning-aware 状态管理的完整性。

关联脉络

本 PR 是 Rust 前端语义对齐的系列工作之一。历史 PR #46219（支持 echo）和 #46051（专用 runtime）同属 Rust 前端演进。PR body 提及本 PR 是堆栈的一部分，后继 PR #46360 将进一步跟进 reasoning parser 相关调整。这些工作共同推动 Rust 前端与 Python 后端在参数处理和行为上的一致性。