本文目錄
模型頁面能開啟，下載卻在大檔案開始後反覆重試，繼續增加逾時或清空快取不一定有幫助。小檔案和權重可能使用不同下載方式，帳號授權、代理出口與磁碟空間也要分別確認。保留已完成的檔案，再對照實際使用的工具排查，才能減少重新下載的次數。
Hub 小檔案、Xet 分塊與舊 Git LFS，下載方式有什麼區別？
用模型卡或 config.json 確認一般 Hub 請求；大權重通常由 Xet 分塊下載，分塊就是將大檔案拆成較小內容分別傳輸。依下表確認正在使用哪種工具，舊 Git LFS 有自己的相容方式；排查時保留已完成快取，再用小檔案核對帳號和網路。
目前下載方式
| 方式 | 實際大檔案後端 | 適合情境 |
|---|---|---|
| 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 前設定
以下範例會改用 HF_HOME。完成前一節登入後，先確認仍使用同一個 token 來源：HF_TOKEN 的值優先用於身分驗證，HF_TOKEN_PATH 可指定其他檔案位置，預設 token 檔案則隨 HF_HOME 變更。
先確定代理和快取目錄，再下載受限模型；變更目錄後用 hf auth whoami 核對目前帳號，必要時在該環境重新登入。公開模型範例不要求登入，成功也不能證明受限模型的許可有效。
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 可以連線；開始分塊下載後反覆重試，應固定一個節點，查看失敗網域、狀態碼與快取寫入錯誤。
先讓相關 Hub/Xet 請求使用同一個固定節點比較，排除不同出口的連線差異；下載結束後再恢復自動選擇。切換出口本身不能證明預簽名 URL 已失效，仍須查看狀態碼與授權資訊。不要將臨時儲存網域永久寫成過寬的 DOMAIN-KEYWORD 規則。
401 / 403
檢查儲存庫許可與 token，不增加超時。
httpx.TimeoutException / Read timed out
固定節點並確認失敗請求命中；Hub 檔案讀取慢時可調整 HF_HUB_DOWNLOAD_TIMEOUT，Xet 分塊錯誤則依 hf_xet 日誌另查，不能假定同一變數控制全部下載。
No space left on device
移動 HF_HOME/HF_HUB_CACHE，保留已完成快取，不換節點。
Permission denied 寫快取
修正目錄所有者與掛載權限，不以 root 重下整份模型。
只得到幾 KB 的指針檔案
Git 流程缺少 git-xet/git-lfs 或大檔案檢出未完成。
重用已完成的 Hub 檔案，分塊快取變數已失效
預設 Hub 快取在 ~/.cache/huggingface/hub，Xet 相關目錄為 ~/.cache/huggingface/xet。修改 HF_HOME 會改變後續使用的路徑，不會自動搬移已有檔案；先保留原目錄中的已完成檔案，再決定遷移或繼續使用哪個快取。
Hub 的 refs、blobs 與 snapshots 會重用已經完成的檔案。下載中斷後應使用相同的 repo_id、revision、使用者和快取目錄重跑。
目前官方說明已將 HF_XET_CHUNK_CACHE_SIZE_BYTES 標為無效：hf_xet 不再使用本機下載分塊快取，設定此變數也不會啟用。應重用已完成的 Hub 檔案，檢查實際請求與磁碟空間，不要為了「開啟分塊快取」刪除 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，斷點續傳和快取更容易觀察。
沒有 git xet 命令時，先按官方平台說明安裝 git-xet；macOS 可使用 Homebrew，Windows 官方文件提供 winget 安裝方式。舊用戶端仍可透過 LFS bridge 下載，但遇到速度與大檔問題時，應優先升級 Hugging Face 的相關下載工具。
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 statusGit 自己使用 git config 與環境變數，和 Python SDK 不是同一設定。hf CLI 正常、git clone 卡住時，只檢查 Git/Xet/LFS 與 Git 代理，不再改 HF_HOME。
啟用離線模式，確認模型權重和 tokenizer 能從本機載入
檢查下載結果與離線使用
再次執行同一下載命令
應快速命中相同 snapshot，而不是重新傳輸全部分塊。
載入一次模型
使用實際 transformers 或專案程式碼讀取權重與 tokenizer。
啟用離線模式測試
已快取內容可用時，設定 HF_HUB_OFFLINE=1 或使用 local_files_only，不應再存取 Hub。
檢查認證資訊與空間
Notebook、日誌和 Git 歷史沒有 token，快取盤仍有升級餘量。
記錄 revision 與 snapshot 路徑
下次更新模型時能區分新版本下載與舊快取損壞。