执行摘要

本次 PR 将 Rust 渲染服务器的 --max-model-len 参数从必填改为可选，未设置时内部回退为 u32::MAX 以跳过长度验证，将检查职责完全委托给下游 vLLM 引擎。同时修复了模型卡片在未配置时错误报告巨大上下文窗口的问题。变更自包含，降低了 Rust 端维护复杂度。

功能与动机

Rust 渲染服务器是一个不运行模型的 tokenizer 服务器，其 --max-model-len 参数仅用于提示长度验证和 max_tokens 上限。根据 PR body，为避免复制复杂的 HF 配置派生逻辑（涉及 RoPE 缩放、字段优先级、tokenizer 限制），该逻辑易与 Python 实现发生漂移且容易出错，决定使该参数可选。当参数缺失时，验证被跳过，由拥有完整上下文的 vLLM 引擎在后续阶段强制执行限制。

实现拆解

1. CLI 参数定义变更：在 rust/src/cmd/src/cli.rs 中，将 RenderArgs 结构体的 max_model_len 字段类型从 u32 改为 Option<u32>，并更新其帮助文本，明确说明省略时的行为。
2. 配置与状态结构调整：在 rust/src/server/src/render.rs 中，将 RenderConfig 的 max_model_len 字段类型同步改为 Option<u32>。在 RenderState 中新增 pub(crate) max_model_len: Option<u32> 字段，用于在模型卡片接口中保留原始配置状态（None 或 Some(n)）。在 build_state 函数中，使用 config.max_model_len.unwrap_or(u32::MAX) 解包后传递给 TextRequestProcessor，确保向后兼容的长度检查逻辑。
3. 模型卡片端点修正：在 rust/src/server/src/routes/render.rs 的 list_models 路由处理器中，将模型卡片对象的 max_model_len 字段来源从 state.text.max_model_len()（总是返回解包后的值）改为 state.max_model_len（直接使用 Option 值），确保在未配置时返回 JSON null。
4. 测试配套更新：在 rust/src/cmd/src/cli/tests.rs 中，更新现有测试 render_args_build_config_without_tls 的断言以匹配新的 Option<u32> 类型，并新增测试 render_args_allow_omitted_max_model_len 验证省略参数时配置为 None。在 rust/src/server/src/routes/tests.rs 中，重构测试辅助函数 test_render_app_with_parser_selections 为 test_render_app_with，接受 Option<u32> 参数；并新增集成测试 render_list_models_reports_configured_max_model_len，验证模型卡片在两种配置下的正确输出。

rust/src/server/src/render.rs

核心配置和状态结构变更点，定义了 max_model_len 如何从可选配置转换为内部状态，并处理了回退逻辑。

// 渲染服务器核心状态构建函数，展示了如何处理可选的 max_model_len 配置。
async fn build_state(config: &RenderConfig) -> Result<Arc<RenderState>> {
    // ... 加载后端逻辑不变 ...
    let served_model_names =
        crate::effective_served_model_names(&config.model, &config.served_model_name);
​
    // 当 CLI 参数 --max-model-len 未提供时，回退为 u32::MAX。
    // 这使得后续 TextRequestProcessor 中的长度检查成为无操作，
    // 将验证责任完全委托给下游的 vLLM 推理引擎。
    let max_model_len = config.max_model_len.unwrap_or(u32::MAX);
    let text = TextRequestProcessor::new(loaded.text_backend, max_model_len)
        .with_max_logprobs(config.max_logprobs);
    let chat = ChatRequestProcessor::render_only(loaded.chat_backend).with_parser_selections(
        config.tool_call_parser.clone(),
        config.reasoning_parser.clone(),
    );
    Ok(Arc::new(RenderState {
        model: config.model.clone(),
        served_model_names,
        // 保留原始 Option<u32> 值，用于在模型卡片接口中准确反映配置状态。
        // 如果直接使用 text.max_model_len() ( 即 u32::MAX)，模型卡片会错误地
        // 报告一个巨大的上下文窗口，而不是未设置。
        max_model_len: config.max_model_len,
        text,
        chat,
    }))
}

rust/src/server/src/routes/tests.rs

包含新增和修改的测试用例，是验证新行为（可选参数、模型卡片返回 null）的关键文件。

// 新增测试：验证模型卡片接口在 max_model_len 可选配置下的正确行为。
#[tokio::test]
async fn render_list_models_reports_configured_max_model_len() {
    // 测试两种情况：显式配置 (Some(128)) 和未配置 (None)
    for (configured, expected) in [(Some(128), json!(128)), (None, serde_json::Value::Null)] {
        let mut app = test_render_app_with_max_model_len(configured);
        let response = app
            .call(Request::builder().uri("/v1/models").body(Body::empty()).expect("build request"))
            .await
            .expect("call app");
        assert_eq!(response.status(), StatusCode::OK);
        let body = to_bytes(response.into_body(), usize::MAX).await.expect("read body");
        let json: serde_json::Value = serde_json::from_slice(&body).expect("decode json");
        let card = json["data"][0].as_object().expect("card object");
        assert!(card.contains_key("max_model_len"));
        // 断言返回的值符合预期：配置时返回数字，未配置时返回 null。
        assert_eq!(
            card["max_model_len"], expected,
            "configured: {configured:?}"
        );
    }
}

评论区精华

BugenZhao (维护者): "I think it is fine to accept the case where --max-model-len is absent. However, I guess we may want to simply default it to unlimited instead of replicating the logic for inferring the default value. - the logic seems complicated and easy to drift in the future - IIUC the effective derived value on the inference server may also depends on the actual configuration or available memory, so it's not guaranteed to be the same as the one here - the downstream inference server still validates prompt length against the engine’s effective limit, and the scheduler enforces that limit during generation."
zdtsw (作者): "Agreed. the logic to get the default value from HF is really complex when I realized yetserday. probably it is good to just make it more loose by set the u32::MAX instead. so we leave the checks to vllm engine later."

风险与影响

1. 行为变更：对于依赖 Rust 渲染服务器进行提示长度预检查的用户，若未提供 --max-model-len，预检查将不再执行。错误将在更晚的引擎阶段暴露。此变更影响范围局限于 Rust 渲染服务器新用户，风险较低。
2. 配置边界条件：自动审查指出，若 HF 模型的 tokenizer_config.json 中 model_max_length 小于 config.json 中的值，且 CLI 参数未设置，渲染服务器可能使用过大的限制。这是一个已知边界情况，实际触发概率低，且引擎最终会阻止无效请求。
3. 内部值泄露：通过在 RenderState 中保留 Option<u32> 并在模型卡片端点使用它，已有效防止了 u32::MAX 泄露到客户端 API 响应中。测试已覆盖此场景。

关联脉络

本次 PR 是 Rust 前端功能完善的一部分，与近期多个 Rust 前端 PR（如 #55411 推理解析器简化、#55240 tokenizer bugfix）共同推动 Rust 渲染服务器的稳定性和易用性。它遵循了仓库中将验证职责下放到引擎层的架构趋势，例如 Python 端的 vLLM 引擎也负责最终的资源限制检查。