# Windows 上的 Hugging Face 快取：檢查、清理與搬移

Hugging Face 的下載可能因為多個模型修訂版本、資料集與中斷的下載，而佔滿 Windows 磁碟機。請從實際執行下載的環境中既有的快取工具開始。任意刪除 `blobs` 資料夾，可能損壞仍共用這些檔案的修訂版本，而刪除整個 `HF_HOME` 也可能一併移除驗證狀態。

## 找出應用程式實際使用的快取

一般 Hub 快取位於 `%USERPROFILE%\.cache\huggingface\hub`，但應用程式可能使用不同的帳號、環境變數或明確指定的快取目錄。[環境變數參考文件](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables)說明了 `HF_HOME`、`HF_HUB_CACHE` 與 `HF_XET_CACHE` 的差別。`HF_HOME` 的範圍比模型快取更廣，還包含儲存的驗證權杖。

開啟該 AI 應用程式使用的終端機或 Python 環境，檢查它安裝的指令：

```
hf cache --help
hf cache ls
hf cache ls --revisions
```

這些是盤點指令。如果該環境中沒有 `hf` 或某個子指令，請檢查該環境中的 `huggingface_hub` 版本，以及該工具支援的升級方式。不要升級不相關的全域 Python 安裝，就假設應用程式的私有環境會跟著改變。

若 Hub 快取設定在別處，請用 `--cache-dir` 指定實際路徑。從預設位置列出的清單，不能證明較大的自訂位置是空的。

## 信任總量前先檢查指令與路徑

在 PowerShell 中，這些檢查會顯示目前呼叫的是哪個可執行檔，以及目前程序的路徑覆寫。它們不會顯示驗證權杖：

```powershell
Get-Command hf | Select-Object Source
$env:HF_HOME
$env:HF_HUB_CACHE
$env:HF_XET_CACHE
```

空白行表示該變數未在這個 PowerShell 程序中設定。這不能證明桌面啟動器、虛擬環境或服務沒有使用任何覆寫。請把這些讀數與實際執行下載的應用程式比對，尤其在電腦上存在多個 Python 安裝時。

以一個自訂快取為例，請在盤點與預覽兩者中都使用它的明確路徑：

```powershell
hf cache ls --cache-dir "D:\AI\huggingface\hub" --revisions
hf cache rm model/OWNER/REPOSITORY --cache-dir "D:\AI\huggingface\hub" --dry-run
```

請把路徑與儲存庫 ID 換成在電腦上找到的值。如果已安裝的指令拒絕某個選項，請停下來閱讀它的說明。不要因為語法錯誤就變成手動刪除資料夾。在剛輸入的新路徑下列出零筆項目，也不能證明實際快取是空的。

## 了解為何多個修訂版本在 Windows 上可能佔用更多空間

Hugging Face 的[快取說明](https://huggingface.co/docs/huggingface_hub/guides/manage-cache)描述了共用 blob 與修訂版本快照。在不支援符號連結的 Windows 上，檔案可能直接存放在快照中，因此同一個檔案可能在不同修訂版本之間重複佔用空間。

在政策允許的情況下，開發人員模式可以啟用較有效率的符號連結行為。隱藏符號連結警告並不會啟用符號連結，也不會回溯去重複刪除舊的下載。不要只為了消掉該訊息，就以系統管理員身分執行整個 AI 應用程式。

另外要區分 Hub 快取與複製到應用程式專屬資料夾的模型檔案。快取指令不會盤點電腦上所有的 `.safetensors` 或 GGUF 檔案。

## 避免把共用的模型檔重複計算

目前的快取文件說明，符合條件的 Xet 下載不只會在修訂版本之間共用，也會跨儲存庫共用。儲存庫回報的大小可能是邏輯大小，而快取整體的實體大小只把共用檔案計算一次。因此把每個儲存庫的大小相加，可能會高估刪除它們所能回收的空間。

當兩個模型名稱看起來一樣大時，這點很重要。它們可能包含不同的權重、共用檔案或各自獨立的副本，取決於下載方式與檔案系統。請讓相容的快取工具計算刪除計畫，不要假設清單上的每一 GB 都各自獨立。

同一份文件也警告，較舊的用戶端並非都能正確管理較新的共用儲存區。如果快取是由比即將用來移除的版本更新的程式庫所建立，請在清理前確認應用程式支援的版本。請保留現有環境，或刻意使用相容且持續維護的工具，不要盲目更新應用程式鎖定的相依套件。

Hub 快取只是其中一個位置。Xet 資料、資料集處理輸出，以及明確下載到本機模型資料夾的檔案，可能存放在別處。如果 Hub 預覽只佔磁碟用量的一小部分，請找出這些其他佔用者，而不是讓 Hub 的刪除變得更激進。

## 預覽移除某個已知的儲存庫

請停止使用目標快取的下載、訓練與推論。找出不再需要的儲存庫，並確認若需要復原時，其確切修訂版本仍可取得。受限的存取權、上游檔案被刪除與離線使用，都可能讓名義上可下載的模型變得難以取代。

目前的 [CLI 指南](https://huggingface.co/docs/huggingface_hub/guides/cli)支援預覽：

```
hf cache rm model/OWNER/REPOSITORY --dry-run
```

將 `model/OWNER/REPOSITORY` 替換為清單中的確切 ID。閱讀受影響的修訂版本與大小。只有在檢視之後，才執行相同指令但去掉 `--dry-run`，並回答其確認提示。這是刪除，不是移到資源回收筒。

若要清理未被引用的快取資料，請另外預覽已安裝工具的計畫：

```
hf cache prune --dry-run
```

指定特定 commit 的腳本仍可能需要這個未被引用的修訂版本。在接受 prune 之前，請先檢查這些專案。不要用一概確認的旗標來跳過這項檢視。

## 用實際專案檢查 prune 計畫

快取中的分支或標籤參照，並不是專案所需內容的完整清單。指令稿可能指名某個已不再是快取分支最新版本的確切修訂雜湊。在接受 prune 之前，請搜尋使用中專案的設定，找出模型 ID 與鎖定的修訂版本，並保留任何離線或可重現工作所需的副本。

目前的 CLI 文件也把中斷的 `.incomplete` 下載納入 prune 行為。請在檢閱計畫前完成或停止擁有該下載的程序。中斷的下載留下的部分檔案，與另一個執行中程序仍在寫入的檔案並不相同。

在一次經過檢閱的移除之後，請針對同一個明確快取路徑重新執行盤點，並比較同一個磁碟上的可用空間。接著執行一個小型的代表性工作負載。如果它立刻又下載大型模型，表示該工作負載仍需要已移除的資料，重複清理只會用磁碟用量換取下載時間。

若要搬移，除非本來就打算重新定位，否則請讓驗證狀態不涉入這項操作。只把 `HF_HUB_CACHE` 指向不同磁碟，範圍比搬移整個 `HF_HOME` 更窄。變更前請記錄舊值，重新啟動擁有該設定的應用程式，並檢查它下一次實際下載出現在哪裡。如果應用程式仍使用舊目錄，請先調查它的明確快取路徑，再刪除任一份副本。

## 搬移未來的下載，同時不混淆位置

若要將 Hub 快取放到另一個磁碟機，請為擁有該快取的應用程式設定 `HF_HUB_CACHE`，然後將該應用程式完整重新啟動。環境變更必須在程式庫匯入之前就已存在。應用程式專屬的 `cache_dir` 仍可能指向別處，因此請確認下一次下載的實際目的地。

變更環境變數不會搬移舊檔案。在新位置經過測試，且所需的僅本機資料都已保留之前，請保留舊快取。如果舊目錄仍然很大，請用快取工具及其路徑明確檢視。

清理之後，測試一項重要的工作負載，並比較同一磁碟區的可用空間。至於 Ollama 另外的模型存放區，請使用 [Ollama 移轉指南](/tw/windows/blog/move-ollama-models-windows)。同樣掛著 AI 品牌，並不代表這些工具共用同一個快取或同一個安全的刪除指令。


Canonical: https://mole.fit/tw/windows/blog/huggingface-cache-windows