如何安全清理 Hugging Face 快取

刪除任何內容前，使用目前 hf cache 命令檢查快取。用 hf cache rm 刪除已知儲存庫或修訂版；對不再被引用的修訂版使用 hf cache prune。不要把快取目錄視為一堆獨立檔案——多個快照可以共享同一批Blob。

為什麼手動刪除看似簡單，實則危險

Hub 快取旨在避免重複下載相同內容。在 hub 快取下，一個儲存庫通常包含 refs、snapshots 和 blobs。快照把修訂版呈現為可用目錄，而其檔案可能連結回 blobs 中的共享內容。因此，兩個修訂版看似各自含式同一個大型權重檔案，但不一定佔用兩份完整空間。

該佈局效率很高，但這意味著“刪除看起來最大的資料夾”並不是好規則。手動刪除一個仍在使用的Blob可能破壞多個快照。刪除一個快照釋放的空間可能遠小於其表面大小，因為其他修訂版仍引用相同內容。

測量你實際使用的快取

首先找到正在使用的Hugging Face 快取目錄。HF_HOME、HF_HUB_CACHE 和相關變數可能已將其移出預設位置。然後透過 CLI 檢視快取：

hf cache ls
hf cache ls --revisions

第一個命令列出快取儲存庫；第二個顯示各個修訂版。清單很長時，請使用目前 CLI 提供的篩選或排序功能。你需要決定的並非簡單的“哪些內容舊了？”，而是“哪個確切儲存庫或修訂版可以重新取得，哪個仍支撐目前工作？”

有意刪除某個儲存庫或修訂版

如果你知道整個快取儲存庫都可以丟棄，請將其快取識別碼傳給 hf cache rm。目前文件使用如下儲存庫識別碼：

hf cache rm model/gpt2

若要進行更精細的清理，請選擇 hf cache ls --revisions 報告的特定修訂識別碼。仔細閱讀預覽和確認內容。CLI 可以計算哪些內容會失去引用；檔案系統選擇無法解釋這些關係。

修剪已分離的修訂版，而不是工作集

hf cache prune 以不再被引用的修訂版為目標。它適合清理分支或標籤引用變化後留下的舊修訂資料，但並不承諾每個你已忘記的舊模型都會消失。請在檢查擬刪除內容後執行它，不要把它當作每次會話結束時的自動反射動作。

hf cache prune

如果快取由多個使用者、容器或排程工作管理，請先停止正在進行的下載。即使快取機制支援復原，在另一個處理程序正在產生快照時執行清理也會造成不必要的歧義。

驗證保留的內容

1. 再次執行 hf cache ls 並記錄新大小。
2. 對你關心且要保留的儲存庫使用 hf cache verify <repo>。
3. 啟動一個會載入所保留模型的真實工作流程。
4. 留意新的下載：悄然重新取得的模型此前並未完整儲存在本機。

重新下載並不總是失敗——快取就是快取——但當你離線工作、固定特定修訂版，或依賴可能消失的上游檔案時，它會很重要。

快取清理與長期保留解決不同問題

Hub 快取針對重複使用和重新取得進行了最佳化。它不是用於記錄模型、分詞器、設定或適配器為何應當歸為一組的精選目錄。在清理難以重現的修訂版前，請確定使用它所需的完整模型系列。對於 PEFT 適配器，這可能包括相容的基礎模型和設定；對於訓練結果，可能不只是權重。

Tensor Archive 屬於這條界線中需要深思熟慮的一側。保留一個已完成的本機模型系列，驗證封存並證實可以精確還原。然後，快取可以重新成為可丟棄的基礎設施，而不是意外形成的博物館。

相關指南

如果目前快取只是位於錯誤的硬碟上，請按照單獨指南更改 Hugging Face 快取目錄。如果模型庫橫跨多個執行環境，請在判斷哪些只是可替換的快取狀態前使用保留清單。