本文目錄
先確認慢的是 Hub 頁面、Xet 分塊，還是舊 Git LFS 下載
Hugging Face 模型下載慢或中斷時，先別急著清快取。模型卡和 config.json 是普通 Hub 請求，大權重通常由 Xet 分塊下載，舊儲存庫也可能繼續走 Git LFS；三條路徑使用的工具、日誌和恢復方式不同。先用小檔案確認帳號與網路，再設定 Clash 代理、超時和快取目錄。
目前下載方式
| 方式 | 實際大檔案後端 | 適合情境 |
|---|---|---|
| huggingface_hub / hf CLI | huggingface_hub 0.32+ 自動安裝 hf_xet，使用 Xet 分塊下載 | 模型與資料集下載首選 |
| git clone + git-xet | Xet，仍保留 Git 工作流 | 需要完整儲存庫與提交歷史 |
| 舊 Git LFS 用戶端 | 透過相容橋繼續工作 | 遺留流程；不是目前效能首選 |
| 瀏覽器單檔案 | Hub 產生的下載網址 | 查看小檔案或臨時下載 |
Hugging Face 官方文件說明，Hub 已採用 Xet；Git LFS 仍相容，但 hf_transfer 已棄用，應改用 hf_xet。舊教學讓使用者只安裝 Git LFS、開啟 HF_HUB_ENABLE_HF_TRANSFER，已經不適合作為 2026 年預設方案。
先下載 config.json，把許可和網路分開
python -m pip install -U huggingface_hub
hf auth login
hf download gpt2 config.json
# 查看版本
python -c "import huggingface_hub; print(huggingface_hub.__version__)"公開模型的小檔案成功，說明 Hub 元資料、基本 HTTPS 和本機快取目錄可用。受限模型回傳 401/403 時，在瀏覽器用同一帳號接受許可並檢查 token 的 read 權限；換節點不會讓帳號自動獲批。
token 由 hf auth login 儲存，不寫進 Clash YAML、Notebook 單元格或公共指令碼。團隊伺服器使用自己的 secrets 管理，不複製個人 token。
環境變數必須在匯入 huggingface_hub 前設定
CLASH_PORT=7890
export HTTPS_PROXY="http://127.0.0.1:$CLASH_PORT"
export HTTP_PROXY="http://127.0.0.1:$CLASH_PORT"
export HF_HOME="$HOME/hf-cache"
export HF_HUB_DOWNLOAD_TIMEOUT=30
mkdir -p "$HF_HOME"
hf download openai-community/gpt2 --include '*.json'
hf download openai-community/gpt2 --cache-dir "$HF_HOME/hub"官方文件註明 huggingface_hub 在 import 時讀取環境變數。Notebook 已經匯入庫後再修改變數，目前核心可能繼續使用舊值；應重啟 kernel 或在啟動前設定。HF_HUB_DOWNLOAD_TIMEOUT 預設 10 秒，只有連線已經建立但讀取慢時才適合提高。
HF_HOME 同時影響 token 和快取根目錄；只想移動儲存庫快取可以使用 HF_HUB_CACHE 或命令的 --cache-dir。目錄必須由目前使用者可寫，並為臨時分塊、模型 revision 與解壓縮留出空間。
網頁能開、模型分塊超時，要在連線頁找 Xet 請求
模型卡和 README 是短請求，Xet 大檔案下載還會存取內容尋址與預簽名儲存位址。網頁正常只證明 huggingface.co 可達；分塊開始後反覆重試，應固定一個節點，查看失敗網域、狀態碼與快取寫入錯誤。
自動策略在下載中途換出口，預簽名 URL 與併發連線可能一起失效。把相關 Hub/Xet 請求放進一個固定策略群組，完整下載結束後再恢復自動選擇。不要把臨時儲存網域永久寫成一條過寬的 DOMAIN-KEYWORD 規則。
401 / 403
檢查儲存庫許可與 token，不增加超時。
httpx.TimeoutException / Read timed out
固定節點、檢查 Xet 請求命中，再適度增加 HF_HUB_DOWNLOAD_TIMEOUT。
No space left on device
移動 HF_HOME/HF_HUB_CACHE，保留已完成快取，不換節點。
Permission denied 寫快取
修正目錄所有者與掛載權限，不以 root 重下整份模型。
只得到幾 KB 的指針檔案
Git 流程缺少 git-xet/git-lfs 或大檔案檢出未完成。
重跑同一 revision，先重用 Hub 快取，再決定是否開啟 Xet 分塊快取
預設 Hub 快取在 ~/.cache/huggingface/hub，Xet 的相關檔案位於 ~/.cache/huggingface/xet；設定 HF_HOME 後兩者會一起移動。
Hub 的 refs、blobs 與 snapshots 會重用已經完成的檔案。下載中斷後應使用相同的 repo_id、revision、使用者和快取目錄重跑。
目前官方文件說明 Xet chunk cache 預設大小為 0，也就是預設關閉。只有經常下載相同內容範圍、並且磁碟空間足夠時，才考慮設定 HF_XET_CHUNK_CACHE_SIZE_BYTES。單次下載慢時先固定節點和增加下載超時，不要為了試快取先刪除已經完成的 blobs。
from pathlib import Path
from huggingface_hub import snapshot_download
cache_dir = Path.home() / "hf-cache" / "hub"
path = snapshot_download(
repo_id="openai-community/gpt2",
revision="main",
cache_dir=cache_dir,
)
print(path)必須使用 Git 時，安裝 git-xet 並保留 LFS 相容
只有專案確實依賴 Git 歷史或分支操作時，才需要走這條路徑。普通模型下載優先使用 hf download，斷點續傳和快取更容易觀察。
HF_REPO='OWNER/MODEL'
# 例如 HF_REPO='openai-community/gpt2'
git lfs install
git xet install
git clone "https://huggingface.co/$HF_REPO"
cd "${HF_REPO##*/}"
git xet --version
git lfs version
git status沒有 git xet 命令時，先按官方平台說明安裝 git-xet；macOS 可使用 Homebrew，Windows 官方文件提供 winget 安裝方式。舊用戶端仍可經 LFS bridge 下載，但遇到速度與大檔案問題時，應優先升級 Hugging Face 工具鏈。
Git 自己使用 git config 與環境變數，和 Python SDK 不是同一設定。hf CLI 正常、git clone 卡住時，只檢查 Git/Xet/LFS 與 Git 代理，不再改 HF_HOME。
下載完成後斷開網路，確認模型真的在本機
進度條走完後，專案仍可能在載入 tokenizer、設定或自訂程式碼時存取 Hub。最後要用實際專案做一次斷網測試，確認所有必需檔案都已進入本機快取。
交付驗證
再次執行同一下載命令
應快速命中相同 snapshot，而不是重新傳輸全部分塊。
載入一次模型
使用實際 transformers 或專案程式碼讀取權重與 tokenizer。
啟用離線模式測試
已快取內容可用時，設定 HF_HUB_OFFLINE=1 或使用 local_files_only，不應再存取 Hub。
檢查認證資訊與空間
Notebook、日誌和 Git 歷史沒有 token，快取盤仍有升級餘量。
記錄 revision 與 snapshot 路徑
下次更新模型時能區分新版本下載與舊快取損壞。