Jak změnit adresář mezipaměti Hugging Face

Nastavte HF_HOME, chcete-li společně přesunout domovský adresář Hugging Face a jeho výchozí mezipaměti. Nastavte HF_HUB_CACHE, chcete-li přemístit pouze stažené repozitáře Hub. Stávající mezipaměť zkopírujte při zastaveném stahování, nastavte proměnnou trvale pro proces, který ji používá, a před odstraněním čehokoli ověřte zachovaný model.

HF_HOME a HF_HUB_CACHE nejsou zaměnitelné

Hugging Face poskytuje několik proměnných mezipaměti, protože místní data nejsou všechna stejná. Výchozí hodnoty se odvozují od HF_HOME, obvykle ~/.cache/huggingface, pokud je nezmění XDG_CACHE_HOME.

• HF_HOME přesune domovský adresář Hugging Face používaný pro místně uložený stav tokenů a výchozí podadresáře mezipaměti.
• HF_HUB_CACHE přesune mezipaměť repozitářů Hub — modely, datasety a Spaces — jejíž výchozí umístění je $HF_HOME/hub.
• HF_XET_CACHE řídí mezipaměť bloků Xet, jejíž výchozí umístění je $HF_HOME/xet.
• HF_ASSETS_CACHE řídí prostředky navazujících knihoven, jejichž výchozí umístění je $HF_HOME/assets.

Pokud je vaším problémem úložiště stažených modelů, HF_HUB_CACHE je nejužší přepis. Chcete-li jeden samostatný kořen Hugging Face na jiném disku, HF_HOME je přehlednější — nezapomeňte však, že přihlašovací údaje a další stav pak mohou následovat tento kořen.

Před výběrem cíle zkontrolujte aktivní cestu

Pomocí průvodce umístěním mezipaměti Hugging Face ověřte stávající proměnné prostředí a přepisy konkrétních knihoven. Notebook, služba, kontejner a interaktivní shell nemusí dědit stejné prostředí. Cesta vypsaná ve skutečné pracovní úloze je užitečnější než hodnota v shellu, který tato úloha nikdy nepoužívá.

hf cache ls

# Python: zobrazení mezipaměti Hub, kterou toto prostředí používá
python -c "from huggingface_hub.constants import HF_HUB_CACHE; print(HF_HUB_CACHE)"

Před kopírováním zastavte aktivní stahování a úlohy trénování. Mezipaměť obsahuje snapshoty a sdílené bloby; je lepší zkopírovat stabilní strom než dohánět nové odkazy, zatímco jej jiný proces mění.

Nastavte novou cestu trvale ve správném prostředí

Při jednorázovém testu nastavte proměnnou v aktuálním shellu. K běžnému použití ji vložte do konfigurace prostředí, která spouští pracovní úlohu: profilu shellu, jednotky služby, definice kontejneru, jádra notebooku nebo spouštěče aplikace.

# macOS nebo Linux: přesuňte pouze mezipaměť repozitářů Hub
export HF_HUB_CACHE="/mnt/ai-cache/huggingface/hub"

# Nebo přesuňte celý domovský adresář Hugging Face
export HF_HOME="/mnt/ai-cache/huggingface"

# Uživatelská proměnná prostředí PowerShell
[Environment]::SetEnvironmentVariable(
  "HF_HUB_CACHE",
  "D:\AI-Cache\huggingface\hub",
  "User"
)

Po změně trvalé proměnné aplikaci restartujte. Knihovny Python často určují konstanty mezipaměti při importu; změna prostředí uprostřed procesu nemusí přesměrovat již probíhající práci.

Zkopírujte, nasměrujte, ověřte a až poté vyčistěte

1. Vytvořte cíl na souborovém systému, který podporuje odkazy a oprávnění vyžadovaná vašimi pracovními úlohami.
2. Zkopírujte do něj starou mezipaměť bez přeuspořádání refs, snapshots nebo blobs.
3. Nastavte zvolenou proměnnou prostředí a restartujte pracovní úlohu.
4. Spusťte hf cache ls --revisions a potvrďte, že se zobrazí očekávaný repozitář a revize.
5. Načtěte jeden známý model offline nebo použijte hf cache verify <repo> pro zachovaný repozitář.
6. Proveďte nové malé stažení a potvrďte, že se mění cíl, nikoli zdroj.

Původní mezipaměť zachovejte alespoň do jednoho bezproblémového restartu. Pokud se ověření nezdaří, obnovte předchozí proměnnou a prověřte kopii nebo oprávnění. Neopravujte neúspěšnou migraci ručním sloučením dvou neúplných mezipamětí.

Teprve potom rozhodněte, zda vyčistit starou mezipaměť

Jakmile je cíl ověřen, může být stará kopie nadbytečná. Chcete-li také odstranit zastaralé repozitáře nebo revize v nové mezipaměti, použijte zdokumentovaný postup pro bezpečné vyčištění mezipaměti Hugging Face. Přemístění a prořezání jsou různé operace; jejich spojení ztěžuje zjištění, která z nich způsobila chybějící model.

U nenahraditelných rodin modelů udržujte záměrný archiv mimo živou mezipaměť. Tensor Archive dokáže související místní artefakty zachovat, ověřit a přesně obnovit. Nemění mezipaměť Hub ani nevybírá revizi, kterou má váš kód načíst.

Související odpovědi o úložišti

Pokud tlak na úložiště způsobuje několik běhových prostředí namísto jedné mezipaměti, přečtěte si, jak uspořádat jeden základní model s mnoha adaptéry. Při širším rozhodování, co zachovat a co odstranit, použijte kontrolní seznam uchování místní knihovny modelů.