执行摘要

本 PR 为 Rust 前端补齐了 Hugging Face 模型解析的三项关键行为：--revision 的端到端传递、HF_HUB_OFFLINE 的离线短路、HF_HUB_CACHE 的自定义缓存目录接管。核心改动集中在 rust/src/text/src/backend/hf/model_files.rs，通过启发式识别 commit SHA 并直接读取 snapshots/<sha> 目录，绕开了 hf-hub 0.5 不兼容 Python 缓存布局的问题。改动横跨 cmd/text/chat/server/managed-engine 五个 crate，以过渡 shim 方式落在 hf-hub 0.5 之上，为 PR#48575 的 1.0 迁移扫清主要行为缺口。已由 njhill 批准合并，测试覆盖缓存解析与 CLI 参数链路，未覆盖 GPU 推理。

功能与动机

PR body 明确指出：Rust 前端解析 HF 模型文件时此前忽略 --revision、HF_HUB_OFFLINE 与 HF_HUB_CACHE，导致指定 revision 时前端与托管 Python 引擎加载不同版本、离线部署仍会发起 Hub 请求、自定义缓存目录不生效。由于 hf-hub 1.0.0 迁移（PR#48575）受两个硬阻塞（rustls/AWS-LC 违反依赖禁运、Xet 冷缓存下载在 GCP 上卡死）无法推进，本 PR 选择在 0.5 上做聚焦修复：1.0 已原生支持 HF_HUB_CACHE 与 SHA 直查，升级后即可移除这些临时 shim。作者在 body 中明确划出边界——tokenizer 独立 revision、更广泛的认证选项、legacy/Transformers 环境别名均不在本 PR 范围。

实现拆解

1. CLI 与配置链路打通：rust/src/cmd/src/cli.rs 为 RenderArgs 与 SharedRuntimeArgs 新增 revision: Option<String>（clap --revision + serde default），并写入 Config、RenderConfig；rust/src/server/src/config.rs、server/src/lib.rs、server/src/render.rs 与示例程序 external_engine_openai_qwen.rs 同步透传，保证 external-frontend、managed-serve、render 三条路径一致。

2. HF 文件解析核心改造：rust/src/text/src/backend/hf/model_files.rs 中 ResolvedModelFiles::new 签名扩展为 (model_id, revision)。解析顺序为：本地目录 → 缓存命中 → 离线报错 → 远程下载。远端路径使用 Repo::with_revision + api.repo() 确保 revision 生效，缓存目录通过 Cache::new 手动接管 HF_HUB_CACHE。关键技巧是缓存解析中对 40 位十六进制 revision 直接构造 snapshots/<sha> 路径，避免 hf-hub 0.5 走 refs/<sha> 失败。

3. 托管引擎转发：rust/src/managed-engine/src/cli.rs 的 ManagedEngineArgs::into_config 新增 revision: Option<String>，存在时向 python_args 注入 --revision。这使得 Rust 托管的 Python 引擎与前端文件解析使用同一模型版本，修复此前前端与引擎可能加载不同分支的问题。

4. 测试配套：model_files.rs 测试模块用 tempdir 构造 mock HF 缓存，覆盖 main 分支、tag、commit SHA 与缺失 revision 四种解析场景（cached_model_files_respect_branch_tag_and_commit_revisions），并验证离线缓存 miss 报错（offline_resolution_uses_hub_cache_and_reports_cache_misses）；rust/src/cmd/src/cli/tests.rs 新增 serve_revision_reaches_frontend_and_managed_engine 断言 revision 同时到达前端 Config 与引擎 python_args，既有快照测试同步更新。PR body 声明格式检查、全部选中测试与严格 Clippy 均通过，五组本地 mock-Hub 场景均实现零 HTTP 请求。

rust/src/cmd/src/cli.rs

定义 revision 的 CLI 入口：RenderArgs 与 SharedRuntimeArgs 均新增 --revision，并透传到 Config/RenderConfig 及 ManagedEngineConfig 构建调用，是参数链路的起点。

/// 运行时参数：外部引擎（Python 引导）与托管引擎（Rust 引导）共用。
pub struct SharedRuntimeArgs {
    /// Model identifier or local model directory used for backend loading and
    /// public model ID.
    pub model: String,
​
    // 新字段：分支、tag 或 commit SHA，clap 与 serde 双通道都支持。
    /// Model revision on the Hugging Face Hub (branch, tag, or commit SHA).
    #[arg(long)]
    #[serde(default)]
    pub revision: Option<String>,
    // ... 其余字段不变
}
​
impl ServeArgs {
    /// 构建托管 Python 引擎配置时把 revision 显式传给 into_config，
    /// 由后者注入 `--revision`，保证引擎与前端加载同一版本。
    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);
        let profiler_config = self.runtime.profiler_config_json();
​
        self.managed_engine.clone().into_config(
            self.runtime.model.clone(),
            self.runtime.revision.clone(),
            self.runtime.max_logprobs,
            profiler_config,
            reasoning_parser.as_deref(),
            self.runtime.language_model_only,
            self.runtime.disable_log_stats,
            self.runtime.shutdown_timeout,
            handshake_port,
            self.runtime.limit_mm_per_prompt_json(),
        )
    }
}

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

托管引擎转发逻辑：into_config 新增 revision 参数并在 python_args 中注入 --revision，确保 Python 引擎与 Rust 前端使用同一模型版本。

/// 构建托管 Python 引擎的启动参数；手动转发的参数在此统一追加。
pub fn into_config(
    self,
    model: String,
    revision: Option<String>, // 本 PR 新增
    max_logprobs: Option<i32>,
    profiler_config: Option<String>,
    reasoning_parser: Option<&str>,
    language_model_only: bool,
    disable_log_stats: bool,
    shutdown_timeout: u64,
    handshake_port: u16,
    limit_mm_per_prompt: Option<String>,
) -> ManagedEngineConfig {
    let mut python_args = self.python_args;
    // revision 必须显式透传，否则 Python 引擎会加载默认 main 分支，
    // 与前端解析到的文件版本不一致。
    if let Some(revision) = revision {
        python_args.push("--revision".to_string());
        python_args.push(revision);
    }
    // 其余参数转发逻辑保持不变 ...
    if let Some(max_model_len) = self.max_model_len {
        python_args.push("--max-model-len".to_string());
        python_args.push(max_model_len);
    }
    // ...
}

评论区精华

本 PR 没有实质性的 review 讨论：claude[bot] 因 PR 来自 fork 而跳过自动评审，njhill 直接 APPROVED。值得记录的要点来自 PR body 的边界声明：

范围刻意限定在这三个设置与 SHA 查找上。独立的 tokenizer revision、更广泛的认证选项、legacy/Transformers 环境别名均为独立工作。

1.0.0 已处理 HF_HUB_CACHE 与直接 SHA 缓存查找；升级后将允许我们移除这些临时 shim。

这体现了作者对过渡方案与长期迁移之间关系的清晰把握。

风险与影响

• offline 语义可能不一致：is_hf_hub_offline() 只认 1/ON/YES/TRUE，而 Python huggingface_hub 只要变量存在即离线；同一环境下前端与引擎的离线判定可能出现偏差，建议后续与 PR#48575 一并对齐。
• 启发式 SHA 判定：40 位纯十六进制判定在极端情况下（分支名恰为 40 位 hex）会误判，但实践中风险很低。
• 重复 --revision：into_config 转发 --revision 后，若用户同时在 -- 透传段传入同名参数，Python argparse 以最后出现的值为准，行为依赖参数顺序。
• 过渡 shim 维护：HF_HUB_CACHE 手动读取、SHA snapshot 直查、offline 判定都是 hf-hub 0.5 的修补，1.0 升级时必须同步移除，否则新旧逻辑叠加会掩盖 1.0 原生行为。
• 测试盲区：Mock 缓存场景验证了解析逻辑，但真实 Hub 下载不同 revision 的端到端用例与 GPU 推理未覆盖（PR body 已声明）。

影响面：用户侧，离线/内网部署与多版本模型切换在 Rust 前端下首次可用；系统侧，缓存优先 + 离线短路的加载路径显著改善启动确定性；团队侧，五个 crate 的配置链路全部带上 revision 字段，后续新增入口需保持一致。

关联脉络

• PR#48575（hf-hub 1.0 迁移）：本 PR 的直接上游方向。1.0 原生支持 HF_HUB_CACHE、SHA 直查、HF_TOKEN_PATH 与 per-download local_files_only，届时本 PR 的 shim 可整体移除；认证与离线策略的扩展也明确留给该 PR。
• PR#56405（gRPC 错误暴露）：同属 Rust 前端行为一致性补课，与本 PR 一起改善前端与引擎交互的可靠性。
• PR#56378（generation 块渲染）：同处 Rust chat/renderer 与模型文件解析链路，说明 Rust 前端正在系统性地补齐 Python 前端已有的能力，从模板渲染到模型解析再到错误语义逐项对齐。