Hugging Face キャッシュを安全に消去する方法

削除前に現在の hf cache コマンドでキャッシュを確認します。既知のリポジトリまたはリビジョンは hf cache rm で削除し、参照されなくなったリビジョンには hf cache prune を使います。キャッシュディレクトリを独立したファイルの山として扱わないでください。複数のスナップショットが同じブロブを共有する場合があります。

手動削除が見かけ以上に危険な理由

Hub キャッシュは同じ内容を二重にダウンロードしないよう設計されています。hub キャッシュ内のリポジトリには通常、refs、snapshots、blobs があります。スナップショットはリビジョンを利用可能なディレクトリとして示しますが、そのファイルは blobs の共有内容へリンクしている場合があります。そのため、二つのリビジョンに同じ大きな重みファイルがあるように見えても、完全なコピー二つ分の容量を消費するとは限りません。

この構成は効率的ですが、「最も大きく見えるフォルダーを削除する」という基準は危険です。使用中のブロブを手動で削除すると、複数のスナップショットが壊れる場合があります。一つのスナップショットを削除しても、他のリビジョンが同じ内容を参照しているため、見かけのサイズよりはるかに少ない容量しか空かないことがあります。

実際に使用中のキャッシュを測定する

まず有効な 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 キャッシュディレクトリを変更するガイドを参照してください。ライブラリが複数の実行環境にまたがる場合は、単なる置換可能なキャッシュ状態を判断する前に保持チェックリストを使います。