Como limpar a cache do Hugging Face em segurança

Utilize os comandos atuais de hf cache para inspecionar a cache antes de eliminar qualquer dado. Remova um repositório ou uma revisão conhecidos com hf cache rm; utilize hf cache prune para as revisões que deixaram de ter referências. Não trate o diretório da cache como uma pilha de ficheiros independentes: os instantâneos podem partilhar os mesmos blobs.

Por que motivo a eliminação manual é enganosamente arriscada

A cache do Hub foi concebida para evitar descarregar duas vezes conteúdo idêntico. Na cache hub, um repositório tem normalmente refs, snapshots e blobs. Um instantâneo apresenta uma revisão como diretório utilizável, enquanto os respetivos ficheiros podem remeter para conteúdo partilhado em blobs. Por conseguinte, duas revisões podem aparentar conter o mesmo ficheiro de pesos grande sem consumirem duas cópias completas.

Essa estrutura é eficiente, mas torna «eliminar a pasta que parece maior» uma regra inadequada. Remover manualmente um blob ativo pode danificar mais do que um instantâneo. Remover um instantâneo pode libertar muito menos espaço do que o seu tamanho aparente porque outras revisões ainda fazem referência ao mesmo conteúdo.

Meça a cache que utiliza realmente

Primeiro, encontre o diretório ativo da cache do Hugging Face. HF_HOME, HF_HUB_CACHE e variáveis relacionadas podem tê-lo afastado do valor predefinido. Em seguida, peça à CLI a sua visão da cache:

hf cache ls
hf cache ls --revisions

O primeiro comando enumera os repositórios em cache; o segundo apresenta as revisões individuais. Utilize os filtros ou a ordenação da CLI atual quando a lista for extensa. A decisão necessária não é apenas «o que é antigo?», mas «que repositório ou revisão exatos podem voltar a ser obtidos e quais suportam o trabalho atual?».

Remova deliberadamente um repositório ou uma revisão

Quando souber que todo um repositório em cache é dispensável, passe o respetivo identificador de cache a hf cache rm. A documentação atual utiliza um identificador de repositório como:

hf cache rm model/gpt2

Para uma limpeza mais restrita, selecione o identificador específico da revisão comunicado por hf cache ls --revisions. Leia atentamente a pré-visualização e a confirmação. A CLI consegue calcular o que fica sem referências; uma seleção no sistema de ficheiros não lhe consegue explicar essas relações.

Pode as revisões desvinculadas, não o seu conjunto de trabalho

hf cache prune seleciona revisões que deixaram de ter referências. É a ferramenta certa para dados de revisões obsoletas deixados para trás à medida que as referências de ramos ou etiquetas mudam, mas não promete que todos os modelos antigos de que já não se lembra desapareçam. Execute-a depois de inspecionar a remoção proposta, não como reflexo automático no fim de cada sessão.

hf cache prune

Se a cache for gerida por vários utilizadores, contentores ou tarefas agendadas, interrompa primeiro as transferências ativas. Uma limpeza efetuada enquanto outro processo materializa um instantâneo cria ambiguidade desnecessária, mesmo quando a implementação da cache foi concebida para recuperar.

Verifique o que resta

1. Execute novamente hf cache ls e registe o novo tamanho.
2. Utilize hf cache verify <repo> para um repositório conservado que seja importante.
3. Inicie um fluxo de trabalho real que carregue um modelo conservado.
4. Esteja atento a uma nova transferência: um modelo que volta a ser obtido silenciosamente não estava totalmente disponível em local.

Voltar a descarregar nem sempre significa uma falha —uma cache é uma cache—, mas é importante quando trabalha sem ligação, fixa uma revisão específica ou depende de um ficheiro a montante que pode desaparecer.

A limpeza da cache e a conservação a longo prazo resolvem problemas diferentes

A cache do Hub está otimizada para reutilização e nova obtenção. Não é um registo selecionado dos motivos pelos quais um modelo, tokenizador, configuração ou adaptador pertenciam ao mesmo conjunto. Antes de limpar uma revisão difícil de reproduzir, identifique a família completa necessária para a utilizar. Para um adaptador PEFT, isso pode incluir um modelo base compatível e uma configuração; para um resultado de treino, pode incluir mais do que apenas os pesos.

É neste lado deliberado da divisão que o Tensor Archive se enquadra. Conserve uma família local terminada, verifique o arquivo e comprove uma restauração exata. Depois, a cache pode voltar a ser infraestrutura dispensável em vez de um museu acidental.

Guias relacionados

Se a cache atual estiver simplesmente no disco errado, siga o guia separado para alterar o diretório da cache do Hugging Face com a variável de ambiente correta. Se a biblioteca abranger vários ambientes de execução, utilize a lista de verificação de conservação antes de decidir o que é apenas um estado de cache substituível.