如何更改 Hugging Face 快取目錄

如果要同時移動 Hugging Face 主目錄及其預設快取，請設定 HF_HOME。如果只想重定位已下載的 Hub 儲存庫，請設定 HF_HUB_CACHE。在下載停止時複製現有快取，為使用快取的處理程序持久設定變數，然後在刪除任何內容之前驗證一個保留的模型。

HF_HOME 與 HF_HUB_CACHE 不可互換

Hugging Face 提供多個快取變數，因為本機資料並不完全相同。預設值由 HF_HOME 派生，通常為 ~/.cache/huggingface，除非 XDG_CACHE_HOME 對其進行更改。

• HF_HOME 會移動用於儲存本機權杖狀態和預設快取子目錄的 Hugging Face 主目錄。
• HF_HUB_CACHE 會移動 Hub 儲存庫快取——包括模型、資料集和 Spaces——其預設位置為 $HF_HOME/hub。
• HF_XET_CACHE 控制 Xet 分塊快取，預設為 $HF_HOME/xet。
• HF_ASSETS_CACHE 控制下游庫資源，預設為 $HF_HOME/assets。

如果問題在於下載模型的儲存，HF_HUB_CACHE 是範圍最窄的覆寫項。如果希望在另一塊磁碟上建立一個自含式的 Hugging Face 根目錄，HF_HOME 更容易理解——但請記住，憑證和其他狀態也可能隨該根目錄遷移。

選擇目標位置前先檢查目前路徑

使用Hugging Face 快取位置指南確認現有環境變數和特定庫的覆寫項。筆記本、服務、容器和互動式 shell 可能不會繼承相同環境。實際工作負載內列印的路徑，比它從未使用的 shell 中的值更有用。

hf cache ls

# Python：檢視此環境解析到的 Hub 快取
python -c "from huggingface_hub.constants import HF_HUB_CACHE; print(HF_HUB_CACHE)"

複製前停止活動下載和訓練作業。快取包含快照和共享Blob；複製穩定的目錄樹，要比在另一個處理程序持續修改時追逐新連結更可靠。

在正確環境中持久儲存新路徑

一次性測試時，可在目前 shell 中設定變數。日常使用時，請將其放入啟動工作負載的環境設定：shell 設定檔案、服務單元、容器定義、筆記本核心或應用程式啟動器。

# macOS 或 Linux：僅移動 Hub 儲存庫快取
export HF_HUB_CACHE="/mnt/ai-cache/huggingface/hub"

# 或者移動整個 Hugging Face 主目錄
export HF_HOME="/mnt/ai-cache/huggingface"

# PowerShell 使用者環境變數
[Environment]::SetEnvironmentVariable(
  "HF_HUB_CACHE",
  "D:\AI-Cache\huggingface\hub",
  "User"
)

更改持久變數後重啟應用程式。Python 庫通常在匯入時解析快取常數；在處理程序中途更改環境，可能不會重新導向已經開始的工作。

複製、指向、驗證，然後清理

1. 在支援工作負載所需連結和權限的檔案系統上建立目標位置。
2. 將舊快取複製到其中，不要重新排列 refs、snapshots 或 blobs。
3. 設定所選環境變數並重啟工作負載。
4. 執行 hf cache ls --revisions，確認預期的儲存庫和修訂版本存在。
5. 離線載入一個已知模型，或對保留的儲存庫使用 hf cache verify <repo>。
6. 執行一次新的小型下載，確認發生變化的是目標位置，而不是來源。

至少在一次無錯誤重啟後仍保留原快取。如果驗證失敗，請復原先前的變數，並調查複製過程或權限。不要試圖透過手動合併兩個不完整快取來“修復”失敗的遷移。

只有在此之後才決定是否清除舊快取

目標位置經證明可用後，舊副本可能變為冗餘。如果還想移除新快取中的過時儲存庫或修訂版本，請使用有文件依據的流程安全清除 Hugging Face 快取。重定位和修剪是不同操作；混在一起會更難判斷哪個操作導致模型缺失。

對於不可替代的模型系列，請在活動快取之外維護有意保留的封存。Tensor Archive 可以保留相關本機產出物、對其進行驗證並精確還原。它不會修改 Hub 快取，也不會選擇程式碼應載入哪個修訂版本。

相關儲存解答

如果壓力來自多個執行環境而非一個快取，請閱讀如何整理一個基礎模型及多個適配器。如需作出更廣泛的保留或刪除決策，請使用本機模型庫保留清單。