# Cache do Hugging Face no Windows: inspecionar, limpar e realocar

Os downloads do Hugging Face podem encher uma unidade do Windows por meio de várias revisões de modelos, datasets e downloads interrompidos. Comece pelas ferramentas de cache no ambiente que fez os downloads. Excluir uma pasta `blobs` arbitrária pode danificar revisões que ainda compartilham esses arquivos, enquanto excluir todo o `HF_HOME` também pode remover o estado de autenticação.

## Encontre o cache que sua aplicação realmente usa

O cache usual do Hub é `%USERPROFILE%\.cache\huggingface\hub`, mas uma aplicação pode usar outra conta, variável de ambiente ou diretório de cache explícito. A [referência de variáveis de ambiente](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables) distingue `HF_HOME`, `HF_HUB_CACHE` e `HF_XET_CACHE`. `HF_HOME` é mais amplo que o cache de modelos e inclui o token de autenticação armazenado.

Abra o terminal ou ambiente Python usado pela aplicação de IA e inspecione o comando instalado:

```
hf cache --help
hf cache ls
hf cache ls --revisions
```

Estes são comandos de inventário. Se `hf` ou um subcomando não estiver disponível, verifique a versão do `huggingface_hub` nesse ambiente e o caminho de atualização suportado pela ferramenta. Não atualize uma instalação global de Python não relacionada e presuma que isso altera o ambiente privado da aplicação.

Para um cache do Hub configurado em outro local, passe o caminho real com `--cache-dir`. Uma listagem do local padrão não prova que o local personalizado maior está vazio.

## Verifique o comando e o caminho antes de confiar no total

No PowerShell, essas verificações mostram qual executável está sendo chamado e as substituições de caminho do processo atual. Elas não exibem o token de autenticação:

```powershell
Get-Command hf | Select-Object Source
$env:HF_HOME
$env:HF_HUB_CACHE
$env:HF_XET_CACHE
```

Uma linha vazia significa que a variável não está definida neste processo do PowerShell. Isso não prova que um inicializador da área de trabalho, um ambiente virtual ou um serviço não use alguma substituição. Compare essas leituras com o aplicativo que fez o download, especialmente quando há várias instalações do Python presentes.

Para um exemplo de cache personalizado, use o caminho explícito dele tanto no inventário quanto na pré-visualização:

```powershell
hf cache ls --cache-dir "D:\AI\huggingface\hub" --revisions
hf cache rm model/OWNER/REPOSITORY --cache-dir "D:\AI\huggingface\hub" --dry-run
```

Substitua o caminho e o ID do repositório pelos valores encontrados no PC. Se o comando instalado rejeitar uma opção, pare e leia a ajuda dele. Não transforme uma falha de sintaxe em exclusão manual de pasta. Uma listagem com zero entradas em um caminho recém-digitado também não é prova de que o cache real esteja vazio.

## Entenda por que várias revisões podem custar mais no Windows

A [explicação do cache](https://huggingface.co/docs/huggingface_hub/guides/manage-cache) do Hugging Face descreve blobs compartilhados e snapshots de revisão. No Windows sem suporte a links simbólicos, os arquivos podem ser armazenados diretamente nos snapshots, de modo que o mesmo arquivo pode ocupar espaço mais de uma vez entre revisões.

O Modo de Desenvolvedor pode habilitar o comportamento mais eficiente de links simbólicos onde a política permitir. Ocultar o aviso de link simbólico não habilita links simbólicos nem elimina retroativamente a duplicação de downloads antigos. Não execute uma aplicação de IA inteira como administrador apenas para silenciar essa mensagem.

Também diferencie o cache do Hub dos arquivos de modelo copiados para a pasta própria de uma aplicação. Um comando de cache não inventaria todos os arquivos `.safetensors` ou GGUF do PC.

## Evite contar arquivos de modelo compartilhados duas vezes

A documentação atual do cache descreve o compartilhamento não apenas entre revisões, mas também entre repositórios, para downloads Xet elegíveis. O tamanho informado de um repositório pode ser lógico, enquanto o tamanho físico do cache como um todo conta arquivos compartilhados uma única vez. Somar o tamanho de cada repositório pode, portanto, superestimar o espaço que a exclusão deles liberaria.

Isso importa quando dois nomes de modelo parecem igualmente grandes. Eles podem conter pesos diferentes, arquivos compartilhados ou cópias separadas, dependendo do método de download e do sistema de arquivos. Deixe a ferramenta de cache compatível calcular um plano de exclusão em vez de presumir que cada gigabyte listado é independente.

A mesma documentação alerta que clientes mais antigos não gerenciam todos corretamente o armazenamento compartilhado mais recente. Se o cache foi criado por uma biblioteca mais nova do que a ferramenta que você está prestes a usar para remoção, verifique a versão suportada pelo aplicativo antes da limpeza. Preserve o ambiente existente ou use deliberadamente uma ferramenta compatível e mantida; não atualize às cegas as dependências fixadas de um aplicativo.

O cache do Hub é apenas um local. Dados Xet, saída de processamento de conjuntos de dados e arquivos baixados explicitamente para um diretório de modelo local podem estar em outro lugar. Se a pré-visualização do Hub responde por apenas uma pequena parte do uso de disco, identifique esses outros responsáveis em vez de tornar a exclusão no Hub mais agressiva.

## Pré-visualize a remoção de um repositório conhecido

Pare downloads, treinamento e inferência que usam o cache alvo. Identifique um repositório de que você não precisa mais e confirme que a revisão exata dele está disponível novamente caso a recuperação importe. Acesso restrito, arquivos removidos na origem e uso offline podem tornar difícil substituir um modelo nominalmente baixável.

O [guia da CLI](https://huggingface.co/docs/huggingface_hub/guides/cli) atual oferece uma pré-visualização:

```
hf cache rm model/OWNER/REPOSITORY --dry-run
```

Substitua `model/OWNER/REPOSITORY` pelo ID exato da listagem. Leia as revisões afetadas e o tamanho. Somente após essa revisão, execute o mesmo comando sem `--dry-run` e responda à confirmação. Isso é exclusão, não uma movimentação para a Lixeira.

Para a limpeza de material de cache não referenciado, pré-visualize separadamente o plano da ferramenta instalada:

```
hf cache prune --dry-run
```

Uma revisão não referenciada ainda pode ser necessária para um script fixado no commit dela. Verifique esses projetos antes de aceitar uma remoção. Não use um sinalizador de confirmação abrangente para ignorar essa revisão.

## Confira um plano de poda com projetos reais

Uma referência de branch ou tag no cache não é um inventário completo do que seus projetos precisam. Um script pode indicar um hash de revisão exato que não é mais a ponta da branch em cache. Antes de aceitar uma poda, procure o ID do modelo e a revisão fixada na configuração dos projetos ativos e mantenha uma cópia de tudo que for necessário para trabalho offline ou reproduzível.

A documentação atual da CLI também inclui downloads `.incomplete` interrompidos no comportamento de poda. Conclua ou interrompa o download responsável antes de revisar o plano. Um arquivo parcial deixado por um download interrompido é diferente de um arquivo que outro processo em execução ainda está gravando.

Após uma remoção revisada, execute novamente o inventário para o mesmo caminho de cache explícito e compare o espaço disponível na mesma unidade. Em seguida, execute uma pequena carga de trabalho representativa. Se ela baixar imediatamente um modelo grande de novo, essa carga de trabalho ainda exige os dados removidos; repetir a limpeza apenas trocará uso de disco por tempo de download.

Para uma movimentação, mantenha o estado de autenticação fora da operação, a menos que realocá-lo seja intencional. Apontar apenas `HF_HUB_CACHE` para outra unidade é mais restrito do que mover todo o `HF_HOME`. Registre o valor antigo antes de alterá-lo, reinicie o aplicativo responsável e verifique onde aparece o próximo download real dele. Se o aplicativo continuar usando o diretório antigo, investigue o caminho de cache explícito dele antes de remover qualquer uma das cópias.

## Mova downloads futuros sem confundir os locais

Para colocar o cache do Hub em outra unidade, configure `HF_HUB_CACHE` para a aplicação que o possui e então reinicie totalmente essa aplicação. As alterações de ambiente devem estar presentes antes da importação da biblioteca. Um `cache_dir` específico da aplicação ainda pode apontar para outro local, então verifique o destino real do próximo download.

Alterar a variável não move os arquivos antigos. Mantenha o cache antigo até o novo local ser testado e qualquer material necessário apenas local ser preservado. Se o diretório antigo ainda estiver grande, revise-o explicitamente com a ferramenta de cache e o caminho dele.

Após a limpeza, teste uma carga de trabalho importante e compare o espaço livre no mesmo volume. Para o armazenamento de modelos separado do Ollama, use o [guia de migração do Ollama](/pt-br/windows/blog/move-ollama-models-windows). O uso compartilhado da marca em torno de IA não significa que as ferramentas compartilham um único cache ou um único comando de exclusão seguro.


Canonical: https://mole.fit/pt-br/windows/blog/huggingface-cache-windows