若你在远程 Mac或自托管 Runner 上跑 transformers / diffusers / 自定义 hf_hub_download，搜索意图通常是：要不要开 HF_TRANSFER、镜像端点怎么设、缓存目录会不会串、CI 缓存键怎么写才不翻车。下文按可执行环境变量给决策表，并附官方默认超时与Xet 并发对照。站内入口：首页、博客列表；拉取加速延伸阅读：OpenClaw 模型拉取与环境同步、Git/npm CI 缓存策略、Python CI 与 PyPI 镜像矩阵。变量含义以 huggingface_hub 环境变量文档为准；请在import huggingface_hub 之前导出环境变量。

场景与瓶颈清单

先把症状映射到动作，避免在远程 Mac 上「只加并发」却越跑越抖。

  • 元数据 / ETag 阶段卡住：跨境 RTT 放大，默认 HF_HUB_ETAG_TIMEOUT=10 容易误判；应先提 ETAG 超时再谈带宽。
  • 单文件下到一半 TimeoutError：默认 HF_HUB_DOWNLOAD_TIMEOUT=10 对大权重过短；与磁盘无关时优先调该值。
  • 多 Job 同时 snapshot 同一 revision：Hub 缓存含未完成临时文件与硬链接语义，并发写同一 HF_HUB_CACHE易出现诡异损坏或锁竞争；应用流水线级子目录或串行预拉 Job。
  • 切换镜像端点后校验失败：HF_ENDPOINT 变更等价于换源，旧 blob 元数据不可混用，必须换新 HF_HOME 或清理缓存根。
  • 403 / gated：与超时无关；需要有效 HF_TOKEN（只读令牌进 CI 密钥库），镜像亦须支持相同授权模型。
瓶颈信号 首选旋钮 回退 / 禁忌
握手慢、list repo 慢 提高 HF_HUB_ETAG_TIMEOUT；合规镜像则设 HF_ENDPOINT 未改超时先开满 Xet 并发
大文件中途断 提高 HF_HUB_DOWNLOAD_TIMEOUT；失败 Job 单步重试 多 Job 共享同一缓存根狂重试
带宽充足但 CPU 飙高 HF_XET_HIGH_PERFORMANCE=1 与适度 HF_XET_NUM_CONCURRENT_RANGE_GETS 在共享小核 Mac 上拉满导致调度饿死其它 Step

环境变量对照表（端点、缓存、HF_TRANSFER、并发与超时）

变量 作用 默认 / 文档要点 远程 Mac CI 建议
HF_ENDPOINT Hub API 与资源基址 默认 https://huggingface.co 合规第三方镜像时设为镜像 origin；切换则换新缓存根
HF_HOME 令牌、缓存总根 ~/.cache/huggingface（受 XDG_CACHE_HOME 影响） ${HOME}/.cache/hf-ci-${CI_PIPELINE_ID:-local}
HF_HUB_CACHE 模型/数据集/Space 快照 $HF_HOME/hub 显式 export，避免与交互式登录用户家目录混用
HF_XET_CACHE Xet 分块缓存 $HF_HOME/xet SSD 上单独路径；与 HF_HUB_CACHE 同步换根
HF_HUB_ENABLE_HF_TRANSFER 历史「hf_transfer」高速路径 官方文档标为弃用，新后端走 Xet 新栈勿依赖；对照旧日志时知道「曾用此开关」即可
HF_XET_HIGH_PERFORMANCE 拉高 Xet 吞吐与 CPU 占用 类比旧版「全力传输」意图 大带宽专线 Job 设 1；共享 Runner 谨慎
HF_XET_NUM_CONCURRENT_RANGE_GETS 每文件并发 range 下载数 默认 16 弱网或高并发 Job 降到 6–10
HF_HUB_DOWNLOAD_TIMEOUT 单文件下载读超时（秒） 默认 10 跨境大文件：60–300
HF_HUB_ETAG_TIMEOUT 取最新元数据等待（秒） 默认 10 跨境：20–45
HF_HUB_OFFLINE 禁止出站，仅读缓存 布尔 预拉 Job 成功后，测试 Job 可开以省元数据往返
HF_TOKEN 访问令牌 可覆盖磁盘 token CI 密钥变量注入；勿写入仓库
# 远程 Mac / CI：在 python 前导出（示例） export HF_ENDPOINT="${HF_ENDPOINT:-https://huggingface.co}" export HF_HOME="${HOME}/.cache/hf-ci-${CI_PIPELINE_ID:-local}" export HF_HUB_CACHE="${HF_HOME}/hub" export HF_XET_CACHE="${HF_HOME}/xet" export HF_HUB_DOWNLOAD_TIMEOUT="${HF_HUB_DOWNLOAD_TIMEOUT:-120}" export HF_HUB_ETAG_TIMEOUT="${HF_HUB_ETAG_TIMEOUT:-30}" # 新栈（Xet）：按需打开；弱网请先降并发再开高性能 export HF_XET_NUM_CONCURRENT_RANGE_GETS="${HF_XET_NUM_CONCURRENT_RANGE_GETS:-8}" # export HF_XET_HIGH_PERFORMANCE=1 # 历史对照（官方已弃用，勿当作新方案核心）：HF_HUB_ENABLE_HF_TRANSFER=1

断点续传与 CI 缓存键设计

断点续传：huggingface_hub 在缓存目录内使用临时文件与校验流程，失败重跑同一 revision 时通常可继续写入，前提是未被并行 Job 破坏同一快照路径。实践上把「重下大模型」放在单独预拉 Stage，测试 Stage 只读缓存或设 HF_HUB_OFFLINE=1，可显著减少长尾分钟数。

CI 远程缓存键（推荐拼接）：将下列段用固定分隔符连接后做哈希或路径名即可：

缓存键因子
  • repo_id（如 org/name）
  • 解析后的 revision（commit SHA，勿只用浮动 branch 名）
  • HF_ENDPOINT 的主机名（镜像与官方混用必加）
  • huggingface_hub 次版本与 Python 次版本（API 行为差异时防串）
  • 可选：HF_XET_HIGH_PERFORMANCE / HF_XET_NUM_CONCURRENT_RANGE_GETS 是否变更（影响是否复用 tarball 缓存策略时）

若你在同一台远程 Mac 上混跑多条流水线，仍建议每条流水线独立 HF_HOME，再把「可复用的大缓存」通过只读挂载或预同步给测试 Job，而不是让并行 Job 直接写同一目录。

失败重试与超时阈值 FAQ

Q：流水线级重试怎么设才不浪费队列？ A：对「下载 Step」单独 retry: 2（或等价 shell 循环 2–3 次），退避 sleep $((16 + RANDOM % 17)) 秒级即可；避免整流水线无退避重跑。

Q：TimeoutError 先改哪个数？ A：先改 HF_HUB_DOWNLOAD_TIMEOUT；若卡在「检查新版本」阶段，再改 HF_HUB_ETAG_TIMEOUT。二者默认均为 10 秒，对大权重与跨境不友好。

Q：HF_HUB_ENABLE_HF_TRANSFER 还要写进 Dockerfile 吗？ A：仅当你锁定旧版依赖且确认仍走旧传输路径时有历史意义；新镜像应优先保证安装 hf-xet，用 HF_XET_* 调优，并把弃用说明写进团队 Runbook，避免新人抄过期博客。

Q：磁盘是 HDD 时 Xet 抖？ A：官方提供 HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY 让写入顺序化；远程 Mac 尽量选 SSD/NVMe 机型承载模型缓存。

内链规划（首页 / 博客列表 / 拉取加速延伸阅读）

总结：2026 年在远程 Mac 上拉 Hugging Face 权重，先用HF_HUB_DOWNLOAD_TIMEOUT / HF_HUB_ETAG_TIMEOUT对齐跨境现实延迟，再用HF_HOME + HF_HUB_CACHE + HF_XET_CACHE隔离多 Job；高速路径请转向Xet（HF_XET_HIGH_PERFORMANCE、HF_XET_NUM_CONCURRENT_RANGE_GETS），把 HF_HUB_ENABLE_HF_TRANSFER 仅当历史对照。需要Apple Silicon 同构、磁盘与出口稳定的常驻算力时，可免登录查看 MacPull 首页、套餐定价、购买说明 与 帮助中心 后租用远程 Mac。

远程 Mac × ML / CI

稳定拉权重，再跑推理与评测

MacPull 提供 Apple Silicon 远程 Mac，适合与本地一致的 PyTorch / MPS 与缓存布局。请从 首页 了解产品，套餐定价 与 购买说明 免登录可阅；文档与常见问题见 帮助中心。博客延伸：分层模型缓存 HowTo。

查看套餐定价 帮助与文档
多节点可选
SSH 与桌面访问
弹性租期
7×24 支持