huggingface_hub 或下游框架拉取權重；所有變數須在 import huggingface_hub 之前匯出，否則不生效。
場景與瓶頸清單
適用對象：在遠端 Mac 上跑推理預熱、評測腳本、小型微調流水線，或將 Hub 快照納入建置產物的工作負載。瓶頸清單（對號入座）：（1）跨境直連 huggingface.co RTT 高、TLS 握手與中繼資料輪詢耗時；（2）單檔數 GB～百 GB，預設逾時 10 秒導致頻繁 TimeoutError；（3）預設快取落在互動使用者家目錄，CI 使用者與互動 SSH 會話不一致造成重拉；（4）共享 Mac 多 Job 同寫快取目錄，與符號連結／NFS 行為衝突；（5）誤以為開啟 HF_HUB_ENABLE_HF_TRANSFER 即可加速，但新版已遷移 Xet，需改評估 HF_XET_HIGH_PERFORMANCE 與節點頻寬匹配度。
| 場景 | 端點策略 | 快取根策略 | 吞吐模式 | 首要風險 |
|---|---|---|---|---|
| 跨境弱網＋公開鏡像 | HF_ENDPOINT=https://hf-mirror.com（或貴司核准鏡像） | 掛卷 /usr/local/ci/hf，顯式 HF_HOME＋HF_HUB_CACHE | 先關 Xet 高效能試跑，再逐步升 HF_XET_NUM_CONCURRENT_RANGE_GETS | 鏡像與官方修訂不同步、快取鍵未含端點後綴 |
| 高頻寬專線／同區域 | 預設官方端點或企業 API Gateway | 本機 NVMe 路徑；必要時 HF_HUB_DISABLE_SYMLINKS=1（NAS 跨 OS） | HF_XET_HIGH_PERFORMANCE=1，併發 24～64 試探 | CPU／磁碟飽和拖垮同機其他 Job |
| 鎖舊版 hub／遺留腳本 | 與當年文件一致的端點 | 與舊行為對齊的 HF_HUB_CACHE | 仍可用 HF_HUB_ENABLE_HF_TRANSFER=1＋huggingface_hub[hf_transfer] | 代理相容差、錯誤訊息較不友善 |
環境變數對照表（HF_TRANSFER、端點、快取目錄、併發下載）
| 變數 | 建議值或範例 | 決策要點 |
|---|---|---|
HF_ENDPOINT | https://hf-mirror.com 或企業反代基底 URL | 鏡像僅替換 Hub REST／下載主機；合規與修訂一致性須自行驗證；切端點後快取鍵應帶端點指紋。 |
HF_HUB_ENABLE_HF_TRANSFER | 1 啟用（新版文件標示棄用） | 僅在鎖舊版 huggingface_hub、仍走 hf_transfer 路徑時列入 Runbook；新環境優先改評估 Xet。 |
HF_XET_HIGH_PERFORMANCE | 1 | 官方描述近似舊版「吃滿頻寬／核心」；共享 Mac 先關閉，單 Job 大檔再開。 |
HF_XET_NUM_CONCURRENT_RANGE_GETS | 預設 16；弱網試 8，專線試 32～64 | 單檔分塊併發；與其他 Job 的磁碟與出口頻寬競爭時往下降。 |
HF_HOME | /usr/local/ci/hf | 統一 token、hub、xet、assets 上層根；未設且走 Linux 慣例時可改靠 XDG_CACHE_HOME。 |
HF_HUB_CACHE | /usr/local/ci/hf/hub | 模型／資料集快照目錄；CI 與本機分離可降低誤刪與權限問題。 |
HF_XET_CACHE | /usr/local/ci/hf/xet | Xet 分塊快取；與 hub 目錄分開便於分別做配額與清理策略。 |
HF_HUB_DOWNLOAD_TIMEOUT | 600～1800（秒） | 預設 10 秒對大檔通常過短；與 HF_HUB_ETAG_TIMEOUT 一併調整。 |
HF_HUB_ETAG_TIMEOUT | 30～120（秒） | 控制拉檔前中繼資料／ETag 請求等待；已快取本機快照時可適度縮短換取更快 fail-soft。 |
可複製骨架（zsh／bash，置於 python -c "import huggingface_hub" 之前）：
export HF_ENDPOINT="${HF_ENDPOINT:-https://huggingface.co}"
export HF_HOME="${HF_HOME:-/usr/local/ci/hf}"
export HF_HUB_CACHE="${HF_HUB_CACHE:-$HF_HOME/hub}"
export HF_XET_CACHE="${HF_XET_CACHE:-$HF_HOME/xet}"
export HF_HUB_DOWNLOAD_TIMEOUT="${HF_HUB_DOWNLOAD_TIMEOUT:-600}"
export HF_HUB_ETAG_TIMEOUT="${HF_HUB_ETAG_TIMEOUT:-60}"
# 共享 Mac：先維持預設併發；專線單 Job 再開下列兩行
# export HF_XET_HIGH_PERFORMANCE=1
# export HF_XET_NUM_CONCURRENT_RANGE_GETS=32
# 僅舊版鎖依賴時保留：
# export HF_HUB_ENABLE_HF_TRANSFER=1
斷點續傳與 CI 快取鍵設計
斷點續傳行為：huggingface_hub 會在快取結構內寫入未完成檔案並於成功後原子替換；同一修訂（snapshot）重跑下載通常可接續已寫入的區塊，無需整檔重拉。若你在步驟間清理了 HF_HUB_CACHE 或更換 HF_ENDPOINT，視為新快取命名空間。啟用 HF_HUB_OFFLINE=1 可強制只讀本地快照並略過線上 ETag 檢查，適合「已預拉＋可重現建置」關卡。
CI 快取鍵（GitHub Actions 語意範例）：將作業系統、鎖檔與模型修訂綁在一起；鏡像端點改變時必須讓鍵跟著變，避免「鍵命中但實際來源不同」。
# actions/cache 的 key／restore-keys 概念示例（請替換為實際路徑）
key: hf-${{ runner.os }}-${{ hashFiles('requirements.txt','pyproject.toml') }}-${{ env.MODEL_REVISION }}-${{ env.HF_ENDPOINT_SLUG }}
path: |
/usr/local/ci/hf/hub
/usr/local/ci/hf/xet
MODEL_REVISION 建議直接餵 Hub commit SHA（或你凍結的 tag 對應 SHA）；僅寫 main 會讓快取在無效化策略上難以推理。HF_ENDPOINT_SLUG 可用簡短字面值（例如 official／mirror-hf-mirror）由 pipeline 注入。
失敗重試與超時閾值 FAQ
先拉高 HF_HUB_DOWNLOAD_TIMEOUT 與 HF_HUB_ETAG_TIMEOUT，再把 HF_XET_NUM_CONCURRENT_RANGE_GETS 自 32 降到 8（弱網或共享出口時常立即見效）。若錯誤集中在 TLS／DNS，優先換區域節點或合規鏡像，而不是無限加大併發。
關閉 HF_XET_HIGH_PERFORMANCE，限制同機平行下載 Job 數，並將快取目錄放在本機 NVMe；HDD 可評估官方建議的 HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY=1 以降低磁頭抖動。
HF_TOKEN 需對目標端點有效；企業反代常要求額外標頭或路徑前綴，請以實際閘道文件為準，不在此硬編假設 URL。快取鍵中加入「租戶／專案」避免不同團隊誤用同一 tarball。
下載步驟外包 3～5 次、底數 2 的指數退避（例如 2／4／8／16 秒）並帶抖動；每次失敗保留最後 200 行日誌與當時 HF_ENDPOINT、修訂與逾時環境列印，方便對照是否為 429／5xx／TLS。