[CI Failure]: Repo-wide job failures from HuggingFace Hub 504 outage (model downloads)

快速结论：该报错由 HuggingFace Hub 服务端返回 504 Gateway Timeout 导致，并非 vLLM 本身或具体 PR 代码问题。优先检查 HuggingFace Hub 服务状态；如果 CI 作业因模型下载超时而失败，只需在 Hub 恢复后重新触发作业即可。

问题场景

vLLM CI 构建（Build #78354，对应 PR #48150）中，多个无关测试套件同时出现失败，包括 basic-correctness、language-models-tests-standard、entrypoints-integration-api-server-generate、lm-eval-kv-offload-1xh200、rust-frontend-distributed、metrics-tracing-2-gpus、distributed-* 以及 AMD 作业等，共 13 个作业失败（统计时还有更多失败待完成）。问题发生在 2026-07-16 07:50 UTC 左右开始的时间窗口内。

报错原文

HTTP Error 504 thrown while requesting HEAD https://huggingface.co/nvidia/Nemotron-H-8B-Base-8K/resolve/main/processor_config.json
Retrying in 8s [Retry 4/5].

ERROR [repo_utils.py:66] Error retrieving file list: Server error '504 Gateway Timeout' for url 'https://huggingface.co/api/models/google/gemma-4-E4B-it/tree/main?...'

原因分析

问题由 HuggingFace Hub 服务端临时故障（504 Gateway Timeout）引起。vLLM CI 作业在拉取或校验模型文件时，向 HuggingFace Hub 发起 HEAD 请求或元数据 API 请求，均收到 504 错误，导致下载或校验失败。即使模型文件已被本地缓存（通过共享 HF_HOME 挂载），作业仍然会向 Hub 发起 HEAD 请求（例如请求 processor_config.json），从而陷入重试循环，直到测试框架超时。

环境排查

HuggingFace Hub 状态：确认 Hub 是否出现服务中断或限流（可通过 Hub status page 或社区公告核实）。
CI 构建 ID：检查是否在指定时间窗口内（如 2026-07-16 07:50 UTC 起）触发了大量失败。
本地缓存配置：确认 CI 环境是否已正确挂载 HF_HOME 缓存目录；若模型已在缓存中，仍可能因 HEAD 请求失败而受影响。

解决步骤

等待 HuggingFace Hub 服务恢复：该问题属于外部基础设施故障，无需修改代码或配置。
重新触发 CI 作业：在 Hub 恢复正常后，对受影响的 PR 重新运行 CI 即可。
可选加固措施（后续优化）：根据 Issue 讨论，可考虑在 CI 脚本中为已缓存的模型设置 HF_HUB_OFFLINE=1，或在遇到 5xx 错误时回退到本地缓存，以提高对 Hub 故障的韧性。但此操作尚未在 Issue 中作为已验证的解决方案。

验证方法

重新运行 CI 作业后，检查对应构建日志中是否不再出现 504 Gateway Timeout 错误，且测试套件全部通过。可以对比原始失败构建（Build #78354）中的日志与重试后的日志。

参考来源

vllm-project/vllm #48830

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

[CI Failure]: Repo-wide job failures from HuggingFace Hub 504 outage (model downloads)