PR 分析报告: [CI] Bump huggingface-hub from v1.10.2 to v1.22.0

执行摘要

本 PR 将 huggingface-hub 依赖从 v1.10.2 升级至 v1.22.0，利用新版磁盘缓存机制大幅提升模型重下载性能。同时修复了离线路径检查、更新了已失效的模型名称引用，并解决了 LoRA 测试的稳定性问题。整体变更涉及 25 个文件，以测试项修改为主，核心逻辑调整较小且安全。

功能与动机

旧版 huggingface-hub 在重新下载缓存模型时需对每个文件发起元数据请求，网络开销大。新版本 (v1.22.0) 引入了 trees/ 文件夹磁盘缓存，文件列表按 commit 不可变存储并被 snapshot_download 和 hf_hub_download 共享，重新下载仅需一次网络调用。此外，Hub 上的 gpt2 别名已被移除，继续使用会导致测试失败；原有的 lm-evaluation-harness fork 与新 huggingface-hub 不兼容，需迁至 vLLM 自有 fork。

实现拆解

1. 依赖升级 — 修改 requirements/ 中的版本约束，引入 huggingface-hub v1.22.0。
2. 离线路径修复 — 在 vllm/transformers_utils/repo_utils.py 的 get_model_path() 中添加 ignore_patterns="*" 参数，防止离线时触发不必要的文件匹配。
3. 模型名称统一 — 将分布在各测试文件中的 "gpt2" 替换为 "openai-community/gpt2"，保持与 Hub 实际模型 ID 一致。
4. 评价框架迁移 — lm-evaluation-harness 指向 vLLM 维护的兼容性 fork，支持流式 API。
5. LoRA 测试修复 — 在 test_chatglm3_tp.py 中限制 max_num_seqs，避免 FULL CUDA graph capture 时 OOM。

vllm/transformers_utils/repo_utils.py

核心源码变更：修复离线模型路径检查，添加 ignore_patterns="*" 参数，适配新版本 huggingface-hub API。

def get_model_path(model: str | Path, revision: str | None = None):
    if os.path.exists(model):
        return model
    assert huggingface_hub.constants.HF_HUB_OFFLINE
    common_kwargs = dict(
        local_files_only=huggingface_hub.constants.HF_HUB_OFFLINE,
        ignore_patterns="*", # 新增：跳过文件匹配，避免离线时触发不必要下载
        revision=revision,
    )
​
    if envs.VLLM_USE_MODELSCOPE:
        from modelscope.hub.snapshot_download import snapshot_download
        return snapshot_download(model_id=model, **common_kwargs)
​
    return hf_api().snapshot_download(
        repo_id=model,
        **common_kwargs,
    )

评论区精华

• AndreasKaratzas 观察到 LoRA 测试组运行超时并手动重启，怀疑是基础设施间歇性不稳定。
• hmellor 指出测试失败后不会终止 CI Runner，导致 GitHub 侧显示为“持续运行”，最终通过设置 max_num_seqs 修复。
• hmellor 还说明已创建兼容 huggingface-hub 新版的 lm-evaluation-harness vLLM fork，并应用了流式 API 补丁。

风险与影响

• 离线兼容性风险：新版 snapshot_download 在本地缓存不完整且网络不可达时抛出 IncompleteSnapshotError，旧版则静默返回部分文件。已部署离线服务的团队需确保缓存完整。
• 模型名称一致性：所有 gpt2 引用已更新，但用户脚本或第三方库可能仍使用旧别名，需同步通知。
• fork 迁移风险：lm-evaluation-harness 切换到 vLLM 自有 fork，需监控是否出现功能回归。
• 测试覆盖：25 个文件中绝大多数为测试调整，核心源码仅 1 处改动，影响面可控。

关联脉络

本 PR 是 huggingface-hub 常规依赖升级，但与近期多个 PR 存在协同：如 #47379 涉及 parser 工具调用、#45877 涉及 DeepSeek 流式解析，均依赖稳定的模型下载路径。长期来看，huggingface-hub 的磁盘缓存优化为大型模型重复加载场景（如 CI、A/B 测试）带来了显著性能提升。