Hugging Face-cache op Windows: inspecteren, opschonen en verplaatsen

Hugging Face-downloads kunnen een Windows-schijf vullen met meerdere modelrevisies, datasets en onderbroken downloads. Begin met de cache-tools in de omgeving die ze heeft gedownload. Het verwijderen van een willekeurige blobs-map kan revisies beschadigen die die bestanden nog delen, terwijl het verwijderen van heel HF_HOME ook de authenticatiestatus kan wissen.

Vind de cache die je applicatie echt gebruikt

De gebruikelijke Hub-cache is %USERPROFILE%\.cache\huggingface\hub, maar een applicatie kan een ander account, een andere omgevingsvariabele of een expliciete cachemap gebruiken. De referentiegids voor omgevingsvariabelen maakt onderscheid tussen HF_HOME, HF_HUB_CACHE en HF_XET_CACHE. HF_HOME is breder dan de modelcache en bevat het opgeslagen authenticatietoken.

Open de terminal of Python-omgeving die de AI-applicatie gebruikt en inspecteer het geïnstalleerde commando:

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

Dit zijn inventarisatiecommando's. Als hf of een subcommando niet beschikbaar is, controleer dan de huggingface_hub-versie in die omgeving en het ondersteunde upgradepad van de tool. Werk geen losstaande globale Python-installatie bij en ga er niet van uit dat dit de privéomgeving van de app verandert.

Voor een geconfigureerde Hub-cache op een andere locatie geef je het werkelijke pad mee met --cache-dir. Een lijst van de standaardlocatie bewijst niet dat de grotere aangepaste locatie leeg is.

Controleer de opdracht en het pad voordat je op het totaal vertrouwt

In PowerShell laten deze controles zien welk uitvoerbaar bestand wordt aangeroepen en welke padoverschrijvingen de huidige procesomgeving heeft. Ze tonen niet het authenticatietoken:

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

Een lege regel betekent dat die variabele niet is ingesteld in dit PowerShell-proces. Het bewijst niet dat een desktoplauncher, virtuele omgeving of service geen overschrijving gebruikt. Vergelijk deze waarden met de applicatie die de download heeft uitgevoerd, vooral wanneer er meerdere Python-installaties aanwezig zijn.

Gebruik voor een voorbeeld van een aangepaste cache het expliciete pad ervan zowel in de inventarisatie als in de voorbeeldweergave:

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

Vervang het pad en de repository-ID door waarden die op de pc te vinden zijn. Als de geïnstalleerde opdracht een optie weigert, stop dan en lees de help ervan. Maak van een syntaxisfout geen handmatige mapverwijdering. Een lijst met nul items op een nieuw getypt pad is ook geen bewijs dat de werkelijke cache leeg is.

Begrijp waarom meerdere revisies op Windows meer kunnen kosten

De cache-uitleg van Hugging Face beschrijft gedeelde blobs en revisiemomentopnamen. Op Windows zonder symlink-ondersteuning kunnen bestanden rechtstreeks in momentopnamen worden opgeslagen, waardoor hetzelfde bestand in meerdere revisies ruimte kan innemen.

Ontwikkelaarsmodus kan het efficiëntere symlink-gedrag inschakelen waar het beleid dat toestaat. De symlink-waarschuwing verbergen schakelt geen symlinks in en ontdupliceert oude downloads niet achteraf. Voer niet een hele AI-applicatie als administrator uit alleen om die melding te dempen.

Onderscheid ook de Hub-cache van modellen die naar de eigen map van een applicatie zijn gekopieerd. Een cache-commando inventariseert niet elk .safetensors- of GGUF-bestand op de pc.

Voorkom dat gedeelde modelbestanden dubbel worden geteld

De huidige cachedocumentatie beschrijft dat eligible Xet-downloads niet alleen tussen revisies worden gedeeld, maar ook tussen repositories. De gerapporteerde grootte van een repository kan logisch zijn, terwijl de fysieke grootte van de hele cache gedeelde bestanden slechts één keer telt. Het optellen van elke repositorygrootte kan daardoor meer suggereren dan je door ze te verwijderen zou vrijmaken.

Dit is van belang wanneer twee modelnamen even groot lijken. Ze kunnen verschillende gewichten, gedeelde bestanden of afzonderlijke kopieën bevatten, afhankelijk van de downloadmethode en het bestandssysteem. Laat de compatibele cachetool een verwijderplan berekenen in plaats van aan te nemen dat elke vermelde gigabyte onafhankelijk is.

Dezelfde documentatie waarschuwt dat oudere clients niet allemaal goed met de nieuwere gedeelde opslag omgaan. Als de cache is gemaakt door een nieuwere bibliotheek dan de tool die je voor verwijdering wilt gebruiken, controleer dan de ondersteunde versie van de applicatie voordat je opruimt. Behoud de bestaande omgeving of gebruik bewust een compatibele, onderhouden tool; werk vastgezette afhankelijkheden van een applicatie niet blind bij.

De Hub-cache is slechts één locatie. Xet-gegevens, uitvoer van datasetverwerking en bestanden die expliciet in een lokale modelmap zijn gedownload, kunnen elders staan. Als de Hub-voorbeeldweergave maar een klein deel van het schijfgebruik verklaart, zoek dan die andere eigenaren op in plaats van de Hub-verwijdering agressiever te maken.

Bekijk het verwijderen van één bekende repository vooraf

Stop downloads, training en inferentie die de doelcache gebruiken. Kies een repository die je niet meer nodig hebt en bevestig dat de exacte revisie weer beschikbaar is als herstel belangrijk is. Toegang met een poortwachter, verwijderde upstream-bestanden en offline gebruik kunnen een nominaal downloadbaar model moeilijk vervangbaar maken.

De huidige CLI-gids ondersteunt een voorbeeldweergave:

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

Vervang model/OWNER/REPOSITORY door de exacte ID uit de lijst. Lees de betrokken revisies en de grootte. Voer pas na die controle hetzelfde commando uit zonder --dry-run en beantwoord de bevestiging. Dit is verwijderen, niet verplaatsen naar de Prullenmand.

Voor het opschonen van cachemateriaal waarnaar niet wordt verwezen, bekijk je het plan van de geïnstalleerde tool apart:

hf cache prune --dry-run

Een revisie waarnaar niet wordt verwezen kan nog nodig zijn voor een script dat aan de bijbehorende commit is vastgezet. Controleer die projecten voordat je een prune accepteert. Gebruik geen algemene bevestigingsoptie om die controle over te slaan.

Controleer een prune-plan tegen echte projecten

Een branch- of tagverwijzing in de cache is geen volledige inventaris van wat je projecten nodig hebben. Een script kan een exacte revisiehash noemen die niet langer de tip van de gecachte branch is. Zoek voordat je een prune accepteert in de configuratie van actieve projecten naar de model-ID en de vastgezette revisie, en bewaar een kopie van alles wat nodig is voor offline of reproduceerbaar werk.

De huidige CLI-documentatie betrekt ook onderbroken .incomplete-downloads bij het prune-gedrag. Rond de download die er eigenaar van is af of stop deze voordat je het plan beoordeelt. Een gedeeltelijk bestand van een onderbroken download is iets anders dan een bestand waarnaar een ander lopend proces nog schrijft.

Voer na één gecontroleerde verwijdering opnieuw de inventarisatie uit voor hetzelfde expliciete cachepad en vergelijk de beschikbare ruimte op dezelfde schijf. Draai daarna een kleine representatieve workload. Als die meteen weer een groot model downloadt, heeft die workload de verwijderde gegevens nog nodig; de opruiming herhalen ruilt alleen schijfgebruik in voor downloadtijd.

Houd bij een verplaatsing de authenticatiestatus buiten de handeling, tenzij je die bewust wilt verplaatsen. Alleen HF_HUB_CACHE naar een andere schijf laten wijzen is beperkter dan heel HF_HOME verplaatsen. Noteer de oude waarde voordat je die wijzigt, herstart de eigenaar-app en controleer waar de volgende daadwerkelijke download verschijnt. Als de app de oude map blijft gebruiken, onderzoek dan het expliciete cachepad ervan voordat je een van beide kopieën verwijdert.

Verplaats toekomstige downloads zonder de locaties te verwarren

Om de Hub-cache op een andere schijf te plaatsen, stel je HF_HUB_CACHE in voor de applicatie die er eigenaar van is en herstart je die applicatie volledig. Wijzigingen in de omgeving moeten aanwezig zijn voordat de bibliotheek wordt geïmporteerd. Een cache_dir die specifiek is voor de app kan nog steeds ergens anders naar wijzen, dus controleer de werkelijke bestemming van de volgende download.

Het wijzigen van de variabele verplaatst de oude bestanden niet. Behoud de oude cache totdat de nieuwe locatie is getest en eventueel vereist lokaal materiaal is veiliggesteld. Als de oude map nog steeds groot is, bekijk je die expliciet met de cache-tool en het bijbehorende pad.

Test na het opschonen één belangrijke workload en vergelijk de vrije ruimte op hetzelfde volume. Voor de aparte modelopslag van Ollama gebruik je de migratiegids voor Ollama. Gedeelde AI-branding betekent niet dat de tools één cache of één veilig verwijdercommando delen.