Como alterar o diretório da cache do Hugging Face

Defina HF_HOME quando pretender mover em conjunto a pasta principal do Hugging Face e as suas caches predefinidas. Defina HF_HUB_CACHE quando apenas pretender mudar o local dos repositórios do Hub descarregados. Copie a cache existente enquanto as descargas estiverem paradas, torne a variável persistente para o processo que a utiliza e depois verifique um modelo conservado antes de eliminar qualquer elemento.

HF_HOME e HF_HUB_CACHE não são intercambiáveis

O Hugging Face disponibiliza várias variáveis de cache porque os dados locais não são todos iguais. As predefinições derivam de HF_HOME, normalmente ~/.cache/huggingface, salvo alteração por XDG_CACHE_HOME.

• HF_HOME move a pasta principal do Hugging Face utilizada para o estado dos tokens armazenados localmente e para os subdiretórios predefinidos da cache.
• HF_HUB_CACHE move a cache de repositórios do Hub — modelos, conjuntos de dados e Spaces — cuja predefinição é $HF_HOME/hub.
• HF_XET_CACHE controla a cache de blocos do Xet, cuja predefinição é $HF_HOME/xet.
• HF_ASSETS_CACHE controla os recursos de bibliotecas dependentes, cuja predefinição é $HF_HOME/assets.

Se o seu problema for o armazenamento de modelos descarregados, HF_HUB_CACHE é a substituição mais limitada. Se pretende uma única raiz autónoma do Hugging Face noutro disco, HF_HOME é mais fácil de compreender — mas lembre-se de que as credenciais e outros estados poderão acompanhar essa raiz.

Inspecione o caminho ativo antes de escolher um destino

Utilize o guia de localização da cache do Hugging Face para confirmar as variáveis de ambiente existentes e as substituições específicas das bibliotecas. Um notebook, serviço, contentor e shell interativa podem não herdar o mesmo ambiente. O caminho apresentado dentro da carga de trabalho real é mais útil do que o valor de uma shell que esta nunca utiliza.

hf cache ls

# Python: veja a cache do Hub resolvida por este ambiente
python -c "from huggingface_hub.constants import HF_HUB_CACHE; print(HF_HUB_CACHE)"

Pare as descargas ativas e as tarefas de treino antes de copiar. A cache contém snapshots e blobs partilhados; é preferível copiar uma árvore estável a perseguir novos links enquanto outro processo a altera.

Torne o novo caminho persistente no ambiente certo

Para um teste pontual, defina a variável na shell atual. Para utilização normal, coloque-a na configuração de ambiente que inicia a carga de trabalho: um perfil da shell, unidade de serviço, definição do contentor, kernel do notebook ou iniciador da aplicação.

# macOS ou Linux: mova apenas a cache de repositórios do Hub
export HF_HUB_CACHE="/mnt/ai-cache/huggingface/hub"

# Ou mova toda a pasta principal do Hugging Face
export HF_HOME="/mnt/ai-cache/huggingface"

# Variável de ambiente do utilizador no PowerShell
[Environment]::SetEnvironmentVariable(
  "HF_HUB_CACHE",
  "D:\AI-Cache\huggingface\hub",
  "User"
)

Reinicie a aplicação depois de alterar uma variável persistente. As bibliotecas Python resolvem frequentemente as constantes da cache quando são importadas; alterar o ambiente a meio de um processo pode não redirecionar o trabalho já em curso.

Copie, aponte, verifique e só depois limpe

1. Crie o destino num sistema de ficheiros compatível com os links e permissões exigidos pelas suas cargas de trabalho.
2. Copie a cache antiga para o novo local sem reorganizar refs, snapshots ou blobs.
3. Defina a variável de ambiente escolhida e reinicie a carga de trabalho.
4. Execute hf cache ls --revisions e confirme que são apresentados o repositório e a revisão esperados.
5. Carregue offline um modelo conhecido ou utilize hf cache verify <repo> para um repositório conservado.
6. Faça uma nova descarga pequena e confirme que muda o destino, não a origem.

Conserve a cache original durante pelo menos um reinício sem problemas. Se a verificação falhar, restaure a variável anterior e investigue a cópia ou as permissões. Não «corrija» uma migração falhada fundindo manualmente duas caches parciais.

Só depois decida se deve limpar a cache antiga

Depois de comprovar o destino, a cópia antiga pode ser redundante. Se também pretender remover repositórios ou revisões obsoletos da nova cache, utilize o processo documentado para limpar a cache do Hugging Face em segurança. A mudança de local e a poda são operações distintas; combiná-las torna mais difícil saber que ação causou a falta de um modelo.

Para famílias de modelos insubstituíveis, mantenha um arquivo intencional fora da cache ativa. O Tensor Archive pode conservar artefactos locais relacionados, verificá-los e restaurá-los exatamente. Não altera a cache do Hub nem escolhe que revisão o seu código deve carregar.

Respostas de armazenamento relacionadas

Se a pressão provier de vários ambientes de execução e não de uma única cache, leia como organizar um modelo base com muitos adaptadores. Para uma decisão mais ampla sobre o que conservar ou eliminar, utilize a lista de verificação para conservação da biblioteca local de modelos.