执行摘要

本 PR 为 vLLM 的 Rust 前端添加了 --lora-modules 启动参数支持，实现了在服务器启动时静态加载 LoRA 适配器的功能，使其与 Python 前端行为对齐。核心变更包括新增 LoraModulePath 配置解析、load_static_lora 加载逻辑、启动流程集成以及全面的测试覆盖。该功能对于需要固定适配器集的生产部署至关重要。

功能与动机

当前 Rust 前端将 --lora-modules 标记为不支持，导致使用该功能的部署只能在启动后通过运行时端点加载适配器。这造成了两个问题：

1) 服务启动后到适配器加载完成前，/v1/models 端点不包含这些适配器；
2) 每个副本都必须暴露运行时更新端点。本 PR 旨在修复此限制，允许在启动时一次性加载所有静态配置的适配器，提供与 Python init_static_loras 一致的语义。

实现拆解

1. 配置解析与数据结构：在 rust/src/server/src/config.rs 中新增 LoraModulePath 结构体及其实现 FromStr trait。该 trait 通过检测输入字符串是否以 { 开头来区分 JSON 对象和 name=path 简写格式，并进行相应的解析和验证。在 rust/src/cmd/src/cli.rs 的 SharedRuntimeArgs 中添加了 lora_modules 字段，使其可通过 --lora-modules 重复指定。
2. 核心加载逻辑：在 rust/src/server/src/lora.rs 的 LoraManager 中新增 load_static_lora 方法。该方法直接调用内部的 register 方法，但不执行路径前缀检查，体现了静态配置（操作员信任）与动态加载（运行时安全）的语义区别。register 方法负责验证适配器名称和路径非空、检查与基础模型名称冲突、分配递增 ID，并通过引擎客户端发起加载。
3. 启动流程集成：在 rust/src/server/src/lib.rs 的 build_state 函数中，于构建 AppState 之后、返回之前，调用新增的 load_static_loras 辅助函数。该函数遍历 config.lora_modules，逐一调用 state.load_static_lora，并将成功的加载信息记录到日志。任何失败都会导致 build_state 返回错误，从而中止服务器启动。
4. 错误处理与 API 适配：将 LoadLoraError::InvalidRequest 变体重构为 InvalidAdapter { message: String }，并在 register 方法内直接进行适配器验证。同步更新了所有错误处理点（routes/lora.rs 和 grpc/control.rs）。动态加载端点 state.load_lora 的签名也更新为接受 LoraModulePath 结构体，以统一参数传递。
5. 测试覆盖：在 config.rs 中添加了 lora_module_path_tests 单元测试，覆盖所有解析场景。在 cli/tests.rs 中添加测试验证 CLI 和 --args-json 路径。在 routes/tests.rs 中添加四个集成测试，使用 mock 引擎验证静态加载、模型列表展示、引擎禁用和拒绝等场景。

rust/src/server/src/config.rs

定义了 LoraModulePath 数据结构及其 CLI/JSON 解析逻辑，是配置入口的核心。

/// 一个 LoRA 适配器，应在服务器接受流量前加载。
///
/// 镜像 Python 的 `LoRAModulePath`，这也是 Python supervisor 在
/// `--args-json` 中转发的 JSON 形状。
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LoraModulePath {
    /// 适配器公开提供的模型 ID。
    pub name: String,
    /// 适配器的本地路径或 Hugging Face 仓库 ID。
    pub path: String,
    /// 在 `/v1/models` 中报告为 `parent` 的基础模型；默认为
    /// 主服务模型名。
    #[serde(default)]
    pub base_model_name: Option<String>,
    #[serde(default)]
    pub is_3d_lora_weight: bool,
}
​
impl FromStr for LoraModulePath {
    type Err = String;
​
    /// 接受 Python `LoRAParserAction` 接受的两种 CLI 形式：
    /// `name=path`，或包含该结构体字段的 JSON 对象。
    fn from_str(value: &str) -> Result<Self, Self::Err> {
        // 如果不以 `{` 开头，则视为简写 `name=path` 格式。
        if !value.trim_start().starts_with('{') {
            let (name, path) = value
                .split_once('=')
                .filter(|(name, path)| !name.is_empty() && !path.is_empty())
                .ok_or_else(|| format!("expected `name=path`, got `{value}`"))?;
            return Ok(Self {
                name: name.to_string(),
                path: path.to_string(),
                base_model_name: None,
                is_3d_lora_weight: false,
            });
        }
        // 否则，尝试按 JSON 对象解析。
        serde_json::from_str(value)
            .map_err(|e| format!("expected `name=path` or a JSON object: {e}"))
    }
}

rust/src/server/src/lora.rs

包含 LoRA 管理核心逻辑，新增 load_static_lora 方法实现了静态加载路径信任、跳过前缀检查的语义。

    /// 加载操作员配置的适配器（`--lora-modules`）。与运行时端点不同，
    /// 路径被直接信任：不应用允许前缀检查。
    pub async fn load_static_lora(
        &self,
        engine_core_client: &EngineCoreClient,
        base_model_names: &[String],
        module: &LoraModulePath,
    ) -> Result<LoraRequest, LoadLoraError> {
        // 静态加载不检查路径前缀，直接委托给 register。
        self.register(engine_core_client, base_model_names, module.clone(), false).await
    }
​
    async fn register(
        &self,
        engine_core_client: &EngineCoreClient,
        base_model_names: &[String],
        module: LoraModulePath,
        load_inplace: bool,
    ) -> Result<LoraRequest, LoadLoraError> {
        let LoraModulePath {
            name: lora_name,
            path: lora_path,
            base_model_name,
            is_3d_lora_weight,
        } = module;
        // 在注册前验证基本字段非空。
        if lora_name.trim().is_empty() {
            bail_invalid_adapter!("lora_name must not be empty");
        }
        if lora_path.trim().is_empty() {
            bail_invalid_adapter!("lora_path must not be empty");
        }
        let _guard = self.update_lock.lock().await;
        // ... 后续逻辑：检查冲突、分配 ID、构建请求、调用引擎 ...
    }

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

添加了关键的集成测试，验证了静态加载、模型列表、错误处理等端到端行为，是功能正确性的重要保障。

#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
#[serial]
async fn static_lora_module_loads_and_lists_with_parent() {
    // 设置一个支持 LoRA 的就绪响应。
    let mut ready = default_ready_response();
    ready.supports_lora = true;
    ready.max_loras = 4;
    // 创建带有 mock 引擎的测试状态，该引擎脚本会验证 add_lora 调用参数。
    let (state, _engine_task) = test_admin_state_with_ready_and_engine_script(
        ready,
        add_lora_script(true, |lora| {
            assert_eq!(lora[0], Value::from("alice"));
            assert_eq!(lora[1], Value::from(1));
            assert_eq!(lora[2], Value::from("/adapters/alice"));
            assert_eq!(lora[3], Value::from("base-model"));
        }),
    )
    .await;
​
    // 构造静态 LoRA 模块配置并调用加载。
    let module = LoraModulePath {
        name: "alice".to_string(),
        path: "/adapters/alice".to_string(),
        base_model_name: Some("base-model".to_string()),
        is_3d_lora_weight: false,
    };
    let request = state.load_static_lora(&module).await.expect("load static lora");
    assert_eq!(request.lora_name, "alice");
    assert_eq!(request.lora_int_id, 1);
​
    // 构建路由并调用 /v1/models，验证返回的模型列表包含静态加载的适配器及其 parent。
    let mut app = build_router_with_dev_mode_and_lora(state, true, false);
    let models = app
        .call(Request::builder().uri("/v1/models").body(Body::empty()).expect("build request"))
        .await
        .expect("call app");
    let body = to_bytes(models.into_body(), usize::MAX).await.expect("read body");
    let json: serde_json::Value = serde_json::from_slice(&body).expect("decode json");
    assert_eq!(json["data"][1]["id"], "alice");
    assert_eq!(json["data"][1]["root"], "/adapters/alice");
    assert_eq!(json["data"][1]["parent"], "base-model");
}

评论区精华

• 设计优化：BugenZhao 提出“将 LoraModulePath 作为参数传递给 load_lora 和 register”，作者 wseaton 回应“tried it, and it's much cleaner so done!”，这统一了 API，使代码更清晰。
• 正确性修正：coderabbitai 指出初始解析逻辑可能错误处理含逗号的路径（alice=/adapters,a,b），并建议通过检测首字符 { 来修复。此建议被采纳并实现。
• 稳定性增强：coderabbitai 发现静态加载循环未与关闭信号 select，可能导致关闭时阻塞。作者将加载逻辑移入 build_state，使其与引擎握手一同响应关闭信号，解决了此问题。

风险与影响

• 风险：主要风险在于配置解析的边界情况，但已有单元测试覆盖。静态加载失败（路径错误、引擎拒绝）会直接导致启动失败，这是符合预期的严格行为。
• 影响：显著提升了 Rust 前端在生产环境中的可用性，使其能够支持需要预配置适配器集的部署模式。对用户透明，提供了与 Python 前端一致的功能体验。

关联脉络

本 PR 是 Rust 前端功能完善的一部分，直接关联 Issue #54836。它与近期仓库中其他 LoRA 相关变更（如 #54833、#54830）共同推进了 LoRA 功能在 Rust 实现中的成熟度。通过支持启动时静态加载，为后续可能的 LoRA 运行时管理功能（如动态加载、卸载）奠定了更完整的基础。