Come modificare la directory della cache di Hugging Face

Imposta HF_HOME quando vuoi spostare insieme la home di Hugging Face e le relative cache predefinite. Imposta HF_HUB_CACHE quando vuoi spostare soltanto i repository Hub scaricati. Copia la cache esistente mentre i download sono fermi, rendi persistente la variabile per il processo che la usa, quindi verifica un modello conservato prima di eliminare qualsiasi cosa.

HF_HOME e HF_HUB_CACHE non sono intercambiabili

Hugging Face espone più variabili della cache perché i dati locali non sono tutti uguali. I valori predefiniti derivano da HF_HOME, normalmente ~/.cache/huggingface, salvo che XDG_CACHE_HOME li modifichi.

• HF_HOME sposta la home di Hugging Face utilizzata per lo stato del token archiviato localmente e le sottodirectory predefinite della cache.
• HF_HUB_CACHE sposta la cache dei repository Hub, ossia modelli, dataset e Spaces, il cui valore predefinito è $HF_HOME/hub.
• HF_XET_CACHE controlla la cache dei chunk Xet, con valore predefinito $HF_HOME/xet.
• HF_ASSETS_CACHE controlla gli asset delle librerie a valle, con valore predefinito $HF_HOME/assets.

Se il problema riguarda l'archiviazione dei modelli scaricati, HF_HUB_CACHE è l'override più ristretto. Se vuoi un'unica radice Hugging Face autonoma su un altro disco, HF_HOME è più facile da comprendere, ma ricorda che anche le credenziali e altro stato potrebbero seguire tale radice.

Controlla il percorso attivo prima di scegliere una destinazione

Usa la guida alla posizione della cache di Hugging Face per confermare le variabili d'ambiente esistenti e gli override specifici delle librerie. Notebook, servizio, container e shell interattiva possono non ereditare lo stesso ambiente. Il percorso stampato nel carico di lavoro effettivo è più utile del valore in una shell che non viene mai usata.

hf cache ls

# Python: visualizza la cache Hub risolta da questo ambiente
python -c "from huggingface_hub.constants import HF_HUB_CACHE; print(HF_HUB_CACHE)"

Arresta i download e i processi di addestramento attivi prima di copiare. La cache contiene snapshot e blob condivisi; è meglio copiare un albero stabile che inseguire nuovi collegamenti mentre un altro processo lo modifica.

Rendi persistente il nuovo percorso nell'ambiente corretto

Per una prova occasionale, imposta la variabile nella shell corrente. Per l'uso normale, inseriscila nella configurazione d'ambiente che avvia il carico di lavoro: un profilo shell, un'unità di servizio, una definizione del container, un kernel notebook o l'avvio dell'applicazione.

# macOS o Linux: sposta soltanto la cache dei repository Hub
export HF_HUB_CACHE="/mnt/ai-cache/huggingface/hub"

# Oppure sposta l'intera home di Hugging Face
export HF_HOME="/mnt/ai-cache/huggingface"

# Variabile d'ambiente utente di PowerShell
[Environment]::SetEnvironmentVariable(
  "HF_HUB_CACHE",
  "D:\AI-Cache\huggingface\hub",
  "User"
)

Riavvia l'applicazione dopo aver modificato una variabile persistente. Le librerie Python spesso risolvono le costanti della cache al momento dell'importazione; la modifica dell'ambiente a metà di un processo potrebbe non reindirizzare il lavoro già in corso.

Copia, indirizza, verifica, quindi pulisci

1. Crea la destinazione su un filesystem che supporti i collegamenti e le autorizzazioni richiesti dai tuoi carichi di lavoro.
2. Copia la vecchia cache al suo interno senza riorganizzare refs, snapshots o blobs.
3. Imposta la variabile d'ambiente scelta e riavvia il carico di lavoro.
4. Esegui hf cache ls --revisions e conferma che compaiano il repository e la revisione previsti.
5. Carica offline un modello noto oppure usa hf cache verify <repo> per un repository conservato.
6. Esegui un nuovo piccolo download e conferma che cambi la destinazione, non la fonte.

Conserva la cache originale per almeno un riavvio senza errori. Se la verifica non riesce, ripristina la variabile precedente e indaga sulla copia o sulle autorizzazioni. Non «correggere» una migrazione non riuscita unendo manualmente due cache parziali.

Solo allora decidi se cancellare la vecchia cache

Quando la destinazione è stata dimostrata, la vecchia copia può essere ridondante. Se vuoi anche rimuovere repository o revisioni obsolete nella nuova cache, usa il flusso documentato per cancellare in sicurezza la cache di Hugging Face. Spostamento e potatura sono operazioni diverse; combinarle rende più difficile capire quale azione abbia causato l'assenza di un modello.

Per le famiglie di modelli insostituibili, mantieni un archivio creato deliberatamente fuori dalla cache attiva. Tensor Archive può conservare artefatti locali correlati, verificarli e ripristinarli esattamente. Non modifica la cache Hub né sceglie quale revisione debba caricare il tuo codice.

Risposte correlate sull'archiviazione

Se la pressione deriva da più runtime anziché da una sola cache, leggi come organizzare un modello di base con molti adapter. Per una decisione più ampia su cosa conservare o eliminare, usa la checklist di conservazione della libreria locale di modelli.