So ändern Sie das Hugging Face-Cache-Verzeichnis

Legen Sie HF_HOME fest, wenn Sie das Hugging Face-Stammverzeichnis samt Standard-Caches gemeinsam verschieben möchten. Legen Sie HF_HUB_CACHE fest, wenn Sie nur heruntergeladene Hub-Repositorys verlagern möchten. Kopieren Sie den vorhandenen Cache bei angehaltenen Downloads, machen Sie die Variable für den verwendenden Prozess dauerhaft und prüfen Sie anschließend ein aufbewahrtes Modell, bevor Sie etwas löschen.

HF_HOME und HF_HUB_CACHE sind nicht austauschbar

Hugging Face stellt mehrere Cache-Variablen bereit, weil nicht alle lokalen Daten gleich sind. Die Standardwerte werden aus HF_HOME abgeleitet, normalerweise ~/.cache/huggingface, sofern XDG_CACHE_HOME dies nicht ändert.

• HF_HOME verschiebt das Hugging Face-Stammverzeichnis, das für lokal gespeicherte Tokenzustände und die Standard-Cache-Unterverzeichnisse verwendet wird.
• HF_HUB_CACHE verschiebt den Hub-Repository-Cache — Modelle, Datensätze und Spaces — mit dem Standardwert $HF_HOME/hub.
• HF_XET_CACHE steuert den Xet-Block-Cache mit dem Standardwert $HF_HOME/xet.
• HF_ASSETS_CACHE steuert Ressourcen nachgelagerter Bibliotheken mit dem Standardwert $HF_HOME/assets.

Wenn Ihr Problem der Speicherbedarf heruntergeladener Modelle ist, ist HF_HUB_CACHE die engste Überschreibung. Wenn Sie ein eigenständiges Hugging Face-Stammverzeichnis auf einer anderen Festplatte wünschen, ist HF_HOME leichter nachvollziehbar — beachten Sie jedoch, dass Zugangsdaten und anderer Zustand diesem Stammverzeichnis dann möglicherweise folgen.

Prüfen Sie den aktiven Pfad, bevor Sie ein Ziel auswählen

Verwenden Sie den Leitfaden zum Speicherort des Hugging Face-Caches, um vorhandene Umgebungsvariablen und bibliotheksspezifische Überschreibungen zu bestätigen. Ein Notebook, Dienst, Container und eine interaktive Shell erben möglicherweise nicht dieselbe Umgebung. Der im tatsächlichen Arbeitsprozess ausgegebene Pfad ist aussagekräftiger als der Wert in einer Shell, die dieser nie verwendet.

hf cache ls

# Python: den von dieser Umgebung aufgelösten Hub-Cache anzeigen
python -c "from huggingface_hub.constants import HF_HUB_CACHE; print(HF_HUB_CACHE)"

Stoppen Sie aktive Downloads und Trainingsaufträge vor dem Kopieren. Der Cache enthält Snapshots und gemeinsam genutzte Blobs; kopieren Sie besser einen stabilen Verzeichnisbaum, als neuen Verknüpfungen nachzulaufen, während ein anderer Prozess ihn verändert.

Neuen Pfad in der richtigen Umgebung dauerhaft speichern

Legen Sie die Variable für einen einmaligen Test in der aktuellen Shell fest. Für die reguläre Nutzung gehört sie in die Umgebungskonfiguration, die die Arbeitslast startet: ein Shell-Profil, eine Diensteinheit, Containerdefinition, ein Notebook-Kernel oder Anwendungsstarter.

# macOS oder Linux: nur den Hub-Repository-Cache verschieben
export HF_HUB_CACHE="/mnt/ai-cache/huggingface/hub"

# Oder das gesamte Hugging Face-Stammverzeichnis verschieben
export HF_HOME="/mnt/ai-cache/huggingface"

# PowerShell-Benutzervariable
[Environment]::SetEnvironmentVariable(
  "HF_HUB_CACHE",
  "D:\AI-Cache\huggingface\hub",
  "User"
)

Starten Sie die Anwendung nach Änderung einer dauerhaften Variable neu. Python-Bibliotheken lösen Cache-Konstanten häufig beim Import auf; eine Änderung der Umgebung in einem bereits laufenden Prozess leitet möglicherweise laufende Arbeiten nicht um.

Kopieren, verweisen, prüfen, dann bereinigen

1. Erstellen Sie das Ziel auf einem Dateisystem, das die von Ihren Arbeitslasten benötigten Verknüpfungen und Berechtigungen unterstützt.
2. Kopieren Sie den alten Cache hinein, ohne refs, snapshots oder blobs neu anzuordnen.
3. Legen Sie die gewählte Umgebungsvariable fest und starten Sie die Arbeitslast neu.
4. Führen Sie hf cache ls --revisions aus und bestätigen Sie, dass das erwartete Repository und die Revision angezeigt werden.
5. Laden Sie ein bekanntes Modell offline oder verwenden Sie hf cache verify <repo> für ein aufbewahrtes Repository.
6. Führen Sie einen kleinen neuen Download durch und bestätigen Sie, dass sich das Ziel ändert, nicht die Quelle.

Bewahren Sie den ursprünglichen Cache mindestens bis nach einem fehlerfreien Neustart auf. Schlägt die Prüfung fehl, stellen Sie die vorherige Variable wieder her und untersuchen Sie Kopie oder Berechtigungen. Versuchen Sie nicht, eine fehlgeschlagene Migration durch manuelles Zusammenführen zweier Teil-Caches zu „reparieren“.

Entscheiden Sie erst dann, ob der alte Cache geleert werden soll

Sobald das Ziel nachgewiesen ist, kann die alte Kopie redundant sein. Wenn Sie zusätzlich veraltete Repositorys oder Revisionen im neuen Cache entfernen möchten, verwenden Sie den dokumentierten Ablauf, um den Hugging Face-Cache sicher zu leeren. Verschieben und Beschneiden sind verschiedene Vorgänge; ihre Kombination erschwert die Feststellung, welche Maßnahme ein fehlendes Modell verursacht hat.

Bewahren Sie für unersetzliche Modellfamilien ein bewusst angelegtes Archiv außerhalb des aktiven Caches auf. Tensor Archive kann zusammengehörige lokale Artefakte bewahren, prüfen und exakt wiederherstellen. Es verändert weder den Hub-Cache noch entscheidet es, welche Revision Ihr Code laden soll.

Zugehörige Antworten zur Speicherung

Wenn der Speicherdruck von mehreren Laufzeitumgebungen statt einem einzelnen Cache ausgeht, lesen Sie, wie Sie ein Basismodell mit vielen Adaptern organisieren. Verwenden Sie für eine breitere Entscheidung zum Behalten oder Löschen die Prüfliste zur Aufbewahrung einer lokalen Modellbibliothek.