Hugging Face's logo

Hub Python Library documentation

Önbellekleme işlevini anlama

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Önbellekleme işlevini anlama

huggingface_hub, Hub'dan indirilen bireysel dosyaları depolamak ve bir depo güncellendiğinde değişmemiş dosyaları tekrar indirmekten kaçınmak için yerel, dosya tabanlı bir önbellek kullanır. Ayrıca hf_xet, yüklemeleri optimize etmek için bir shard önbelleği ve geçici verileri saklar (bkz. Xet önbellekleme).

Bu kılavuz, huggingface_hub tarafından sağlanan Python'a özgü önbellek yönetimi araçlarını kapsar. Hugging Face Hub önbellek sisteminin nasıl çalıştığına dair dil bağımsız bir genel bakış için Hub'ın yerel önbellekleme belgelerini inceleyin.

Dosya tabanlı önbellekleme

Hugging Face Hub önbellek sistemi, Hub'a bağımlı kütüphaneler arasında paylaşılan merkezi önbellek olarak tasarlanmıştır. v0.8.0 sürümünde, revizyonlar arasında aynı dosyaların yeniden indirilmesini önlemek amacıyla güncellenmiştir.

Önbellekleme sistemi şu şekilde tasarlanmıştır:

<CACHE_DIR>
├─ <MODELS>
├─ <DATASETS>
├─ <SPACES>
├─ <KERNELS>

Varsayılan <CACHE_DIR>, ~/.cache/huggingface/hub'dir. Ancak, tüm yöntemlerdeki cache_dir argümanı ile veya HF_HOME ya da HF_HUB_CACHE ortam değişkenlerinden birini belirleyerek özelleştirilebilir.

Modeller, veri setleri, uzaylar ve çekirdekler ortak bir kök paylaşır. Bu depoların her biri, varsa depo türünü, ad alanını (kuruluş veya kullanıcı adı) ve depo adını içerir:

<CACHE_DIR>
├─ models--julien-c--EsperBERTo-small
├─ models--lysandrejik--arxiv-nlp
├─ models--bert-base-cased
├─ datasets--glue
├─ datasets--huggingface--DataMeasurementsFiles
├─ spaces--dalle-mini--dalle-mini

Tüm dosyalar artık Hub'dan bu klasörlere indirilir. Önbellekleme, bir dosya zaten mevcut ve güncellenmediyse iki kez indirilmesini önler; ancak dosya güncellendiyse ve en son dosyayı istiyorsanız, en son dosya indirilir (tekrar ihtiyacınız olması durumunda önceki dosya olduğu gibi korunur).

Bunu başarmak için tüm klasörler aynı iskeleti içerir:

<CACHE_DIR>
├─ datasets--glue
│  ├─ refs
│  ├─ blobs
│  ├─ snapshots
│  ├─ trees
...

Her klasör aşağıdakileri içerecek şekilde tasarlanmıştır:

Referanslar

refs klasörü, verilen referansın en son revizyonunu gösteren dosyaları içerir. Örneğin, bir depodan main dalından bir dosya daha önce alındıysa, refs klasörü, içinde mevcut başın commit tanımlayıcısını barındıran main adında bir dosya içerir.

main'in en son commit'i aaaaaa kimliğine sahipse, aaaaaa içerecektir.

Aynı dal, bbbbbb kimlik numarasına sahip yeni bir commit ile güncellenirse, o referans dosyasından yeniden indirilen dosya, refs/main dosyasını bbbbbb içerecek şekilde günceller.

Blobs

blobs klasörü, indirdiğimiz gerçek dosyaları içerir. Her dosyanın adı, o dosyanın hash'idir.

Anlık görüntüler

snapshots klasörü, yukarıda bahsedilen blob'lara sembolik bağlantılar içerir. Kendisi de birkaç klasörden oluşur: bilinen her revizyon için bir tane!

Yukarıdaki açıklamada, bbbbbb revizyonundan bir dosya getirmeden önce başlangıçta aaaaaa revizyonundan bir dosya getirmiştik. Bu durumda, snapshots klasöründe artık aaaaaa ve bbbbbb olmak üzere iki klasör bulunur.

Bu klasörlerin her birinde, indirdiğimiz dosyaların adlarını taşıyan canlı sembolik bağlantılar bulunur. Örneğin, README.md dosyasını aaaaaa revizyonunda indirmiş olsaydık, aşağıdaki yola sahip olurduk:

<CACHE_DIR>/<REPO_NAME>/snapshots/aaaaaa/README.md

O README.md dosyası aslında, dosyanın hash'ine sahip blob'a bağlanan bir sembolik bağlantıdır.

İskeleti bu şekilde oluşturarak dosya paylaşımı mekanizmasını açarız: aynı dosya bbbbbb revizyonunda alınmış olsaydı, aynı hash değerine sahip olur ve dosyanın yeniden indirilmesine gerek kalmazdı.

Ağaçlar

trees klasörü, bir depodaki belirli bir commit anındaki dosya listesini önbelleğe alır. Bir commit değiştirilemez olduğundan, dosya listesi asla değişmez. Bu, listenin Hub ile tekrar karşılaştırılmasına hiç gerek kalmadan sonsuza kadar önbellekte tutulabileceği anlamına gelir.

Her önbelleğe alınmış liste, bir commit hash'i adıyla adlandırılır ve bir JSON dosyası olarak saklanır, örneğin trees/aaaaaa.json. O commit'teki depodaki her dosya için, dosyanın indirilmesi için gereken bilgiler kaydedilir: yolu, boyutu ve hash'i. Bu, Hub'ın normalde döndüreceği aynı bilgidir, ancak bunu almak genellikle dosya başına bir ağ çağrısı gerektirir.

Bu önbellek snapshot_download() tarafından yazılır. Bir commit'i ilk kez indirdiğinizde dosya listesi bir kez alınır ve burada saklanır. Aynı commit'i bir sonraki sefer indirdiğinizde liste yeniden alınmak yerine diskten okunur. Sonuç olarak, her şey zaten önbellekteyken bir indirme işlemini yeniden çalıştırmak tek bir ağ çağrısı maliyetine çıkar: dal veya etiket adını bir commit hash'ine dönüştürmek için gereken çağrı.

Both snapshot_download() and hf_hub_download() read this cache to avoid network calls. When you download a file with a commit hash as revision (this is exactly what snapshot_download() does internally for every file), the download metadata is read from the cached file list and the per-file network call is skipped. This means a hf_hub_download() for a single file also benefits from a file list that an earlier snapshot_download() saved for the same commit.

Önbelleğe alınan dosya listesi, bir commit'in tam olarak ne içermesi gerektiğini tanımladığı için snapshot_download(), yerel bir görüntünün (snapshot) eksiksiz olup olmadığını da belirleyebilir. Hub'a ulaşılamıyorsa (çevrimdışısınız, bağlantı başarısız oldu veya local_files_only=True parametresini geçirdiniz) ve beklenen bazı dosyalar yerel görüntüde eksikse, snapshot_download() kısmi bir klasör döndürmek yerine IncompleteSnapshotError hatası fırlatır. Bu davranıştan önce, eksik bir görüntü sessizce döndürülüyordu; bu da eksik dosyalarla çalıştığınızı fark etmeden devam etmenize neden olabilirdi. allow_patterns veya ignore_patterns ile hariç tutulan dosyalar eksik olarak sayılmaz. İstisna, snapshot_path özniteliği aracılığıyla eksik görüntünün yolunu açığa çıkarır, böylece gerekirse kısmi olarak önbelleğe alınan dosyaları yine de bulabilirsiniz.

.no_exist (ileri düzey)

blobs, refs ve snapshots klasörlerinin yanı sıra, önbelleğinizde bir .no_exist klasörü de görebilirsiniz. Bu klasör, bir kez indirmeye çalıştığınız ancak Hub üzerinde bulunmayan dosyaları takip eder. Yapısı, bilinen her revizyon için 1 alt klasör içeren snapshots klasörüyle aynıdır:

<CACHE_DIR>/<REPO_NAME>/.no_exist/aaaaaa/config_that_does_not_exist.json

snapshots klasörünün aksine, dosyalar basit boş dosyalardır (sembolik bağlantı yoktur). Bu örnekte, "config_that_does_not_exist.json" dosyası Hub'da "aaaaaa" revizyonu için mevcut değildir. Sadece boş dosyalar sakladığı için bu klasör, disk kullanımı açısından ihmal edilebilir düzeydedir.

Peki bu bilgi neden önemli olabilir? Bazı durumlarda bir çerçeve, bir model için isteğe bağlı dosyaları yüklemeye çalışır. İsteğe bağlı dosyaların mevcut olmaması bilgisi kaydedildiğinde, olası her isteğe bağlı dosya için 1 HTTP çağrısı yapılmadığından modelin yüklenmesi hızlanır. Örneğin transformers kütüphanesinde her tokenizer ek dosyaları destekleyebilir. Tokenizer'ı makinenizde ilk kez yüklediğinizde, sonraki başlatmalarda yükleme süresini hızlandırmak için hangi isteğe bağlı dosyaların mevcut olduğu (ve hangilerinin olmadığı) önbelleğe alınır.

Bir dosyanın yerel olarak önbelleğe alınıp alınmadığını test etmek için (hiçbir HTTP isteği yapmadan) try_to_load_from_cache() yardımcı işlevini kullanabilirsiniz. Bu işlev, dosya yolu (varsa ve önbelleğe alınmışsa), _CACHED_NO_EXIST nesnesi (var olmaması önbelleğe alınmışsa) veya None (bilgi yoksa) döndürür.

from huggingface_hub import try_to_load_from_cache, _CACHED_NO_EXIST

filepath = try_to_load_from_cache()
if isinstance(filepath, str):
    # file exists and is cached
    ...
elif filepath is _CACHED_NO_EXIST:
    # non-existence of file is cached
    ...
else:
    # file is not cached
    ...

Uygulamada

Uygulamada, önbelleğiniz aşağıdaki ağaca benzer görünmelidir:

    [  96]  .
    └── [ 160]  models--julien-c--EsperBERTo-small
        ├── [ 160]  blobs
        │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
        │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
        ├── [  96]  refs
        │   └── [  40]  main
        ├── [ 128]  snapshots
        │   ├── [ 128]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f
        │   │   ├── [  52]  README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
        │   │   └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        │   └── [ 128]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48
        │       ├── [  52]  README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
        │       └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        └── [  96]  trees
            ├── [ 521]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f.json
            └── [ 521]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48.json

CACHEDIR.TAG

huggingface_hub, önbellek dizininin içinde CACHEDIR.TAG dosyasını otomatik olarak oluşturur. Bu etiket Cache Directory Tagging Standard standardını izler ve yedekleme araçlarına (ör. Borg, restic, rsync) dizinin yeniden indirilebilir önbellek verisi içerdiğini ve yedeklemelerden güvenle hariç tutulabileceğini bildirir.

Kısıtlamalar

Verimli bir önbellek sistemi için huggingface-hub sembolik bağlantılar (symlink) kullanır. Ancak sembolik bağlantılar tüm makinelerde desteklenmez. Bu, özellikle Windows'ta bilinen bir kısıtlamadır. Bu durumda huggingface_hub, blobs/ dizinini kullanmak yerine dosyaları doğrudan snapshots/ dizinine kaydeder. Bu çözüm, kullanıcılara Hub'dan dosyaları indirmelerini ve önbelleğe almalarını tam olarak aynı şekilde yapmalarına olanak tanır. Önbelleği denetlemek ve silmek için kullanılan araçlar (aşağıda bkz.) de desteklenir. Ancak, aynı repodan birden çok revizyon indirildiğinde tek bir dosyanın birden fazla kez indirilebileceği için önbellek sistemi daha az verimli hale gelir.

Windows makinesinde sembolik bağlantı tabanlı önbellek sisteminden yararlanmak istiyorsanız, Geliştirici Modunu etkinleştirmeniz veya Python'ı yönetici olarak çalıştırmanız gerekir.

no-symlink önbellek modunu proaktif olarak kullanmak isterseniz (ör. sembolik bağlantıları iyi yönetmeyen paylaşımlı bir dosya sisteminde), HF_HUB_DISABLE_SYMLINKS ortam değişkenini 1 olarak ayarlayabilirsiniz. Dosyalar, blobs/ dizinine sembolik bağlantı oluşturmak yerine doğrudan snapshots/ dizinine kopyalanır.

Sembolik bağlantılar desteklenmediğinde, kullanıcının önbellek sisteminin yetersiz bir sürümünü kullandığına dikkat çekmek için bir uyarı mesajı görüntülenir. Bu uyarı, HF_HUB_DISABLE_SYMLINKS_WARNING ortam değişkenini true olarak ayarlayarak devre dışı bırakılabilir.

Depolar arasında paylaşılan bloblar

Varsayılan olarak Xet dosyaları, depolar arasında da tekilleştirilir. hf_xet üzerinden indirilen bir Xet dosyası, <CACHE_DIR>/blobs/<prefix>/<xet_hash> konumunda bir kez saklanır ve depodaki blobs/<etag> girdisi, bu konuma göreli bir sembolik bağlantıdır. Başka bir depo aynı dosyaya ihtiyaç duyduğunda, indirme yerine bir sembolik bağlantı alır: hiçbir bayt aktarılmaz ve ek alan kullanılmaz. Anlık görüntü düzeni değişmez. Bir işaretçi dosyası depoyu tanımlar, bu nedenle huggingface_hub tarafından oluşturulmamış bir blobs dizinine asla dokunulmaz.

Her paylaşılan dosyanın, onu kullanan depo bloblarını listeleyen bir <xet_hash>.refs manifesti vardır. hf cache rm, bir silme işleminden etkilenen paylaşılan dosyaları kontrol etmek için bunu okur ve hf cache prune, artık önbelleğe alınmış hiçbir depo tarafından kullanılmayan paylaşılan dosyaları kaldırır. Manifest yalnızca bir ipucudur: her kayıt dosya sistemiyle karşılaştırılır ve eksik veya okunamayan meta verisi olan dosya korunur. Temizlik, geçerli bir önbellek girdisini bozmak yerine geri kazanılabilir verinin geride bırakılmasını tercih eder.

Depo başına boyutlar mantıksal olarak kalır, bu nedenle paylaşılan bir dosya onu kullanan her depo için sayılır. Önbellek genelindeki size_on_disk ise fizikseldir: artık hiçbir depo tarafından kullanılmayan dosyalar dahil olmak üzere her paylaşılan dosya bir kez sayılır.

Eski istemciler (huggingface_hub, huggingface.js, hf-hub, llama.cpp ve sembolik bağlantıları takip eden her şey) aynı depo klasörlerinde okumaya ve indirmeye normal şekilde devam eder. İki kısıtlama:

  • huggingface_hub<=1.31, silinen bir repodaki paylaşılan dosyaları depoda bırakır; bu dosyalar hf cache ls ile işaretlenir ve hf cache prune ile kaldırılır. Diğer istemcilerin önbellek silme araçları, başka repolar tarafından hâlâ kullanılan bir paylaşılan dosyayı silebilir; etkilenen dosyalar bir sonraki kullanımda yeniden indirilir. hf cache rm, hf cache prune ve programatik silme işlemleri için güncel bir huggingface_hub sürümü kullanın.
  • Önbellek tarayıcıları, üst düzey blobs dizinini bilinmeyen bir giriş olarak raporlayabilir.

Store, symlink tabanlı önbellek düzenini gerektirir ve HF_HUB_DISABLE_XET=1 ile devre dışı bırakılır. Dosya paylaşımındaki herhangi bir hata, örneğin desteklenmeyen bir dosya sistemi, izin hatası veya önceden var olan işaretlenmemiş bir blobs dizini, sessizce normal depo yerel depolamasına geri düşer. Tamamen vazgeçmek için HF_HUB_DISABLE_SHARED_BLOBS=1 değerini ayarlayın.

Bir revizyonu sabitle (ileri düzey)

Hub'u bir ML kütüphanesine entegre ediyorsanız, tek bir snapshot_download() çağrısı hâlâ önerilen yaklaşımdır: revizyonu bir kez çözer, her şeyi paralel olarak indirir ve dosya listesini önbelleğe alır. Aşağıdaki bilgiler yalnızca ayrı ayrı birçok bileşeni (config, weights, tokenizer, processor, adapters, …) indirip yükleyen ve tek bir çağrı kullanamayan karmaşık kütüphaneler için faydalıdır.

Bir kütüphane birden fazla dosyayı tek tek indirirken, her çağrı revision="main" değerini yeniden bir commit hash'ine çözmek zorundadır. Bu, dosya başına bir HTTP çağrısı maliyeti getirir ve daha da kötüsü, aralarında birkaç saniye olan iki çağrı, depo bu arada güncellenirse iki farklı commit'e ulaşabilir.

HfApi.resolve_revision() revizyonu bir kez çözümler ve bir ResolvedRevision döndürür:

>>> from huggingface_hub import resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')

ResolvedRevision, bir str alt sınıfıdır; bu nedenle revision argümanı alan herhangi bir huggingface_hub yöntemine iletilebilir. Dize değeri, kullanıcının başlangıçta istediği değerdir (burada "main", bu yüzden okunabilir hata mesajları), .resolved ise commit hash'ini içerir:

>>> revision == "main"
True
>>> revision.resolved
'607a30d783dfa663caf39e06633721c8d4cfcd7e'

İndirme yardımcıları (hf_hub_download(), snapshot_download(), get_cached_repo_tree()) bir ResolvedRevision algılar ve commit hash'ini doğrudan kullanır. Her dosyanın aynı commit'ten geldiği garanti edilir ve dosyalar önbelleğe alındıktan sonra hiçbir HTTP çağrısına gerek kalmaz:

>>> from huggingface_hub import hf_hub_download
>>> config = hf_hub_download("openai-community/gpt2", "config.json", revision=revision)
>>> weights = hf_hub_download("openai-community/gpt2", "model.safetensors", revision=revision)

revision -> commit hash eşlemesi, önbelleğin refs/ klasörüne de yazılır (bkz. Refs). Bu, Hub'a daha sonra ulaşılamaması durumunda (çevrimdışı mod, bağlantı hatası, zaman aşımı, Hub kesintisi) HfApi.resolve_revision() işlevinin şeffaf bir şekilde önbellekteki değere geri dönmesi anlamına gelir. Önbellekte de hiçbir şey yoksa RevisionResolutionError hatası oluşturulur.

Bir commit hash, yalnızca çözümlendiği depo için bir anlam taşır ve indirme yardımcıları onu olduğu gibi kullanır. Bu nedenle bir ResolvedRevision, yalnızca çözümlendiği depoya iletilmelidir. Bir kütüphane başka bir depodan da (bir temel model, bir adaptör, kendi deposunda barınan bir bileşen, …) indirme yapıyorsa, o depo için çözümlenmiş bir revizyona ihtiyaç duyar. ResolvedRevision'i HfApi.resolve_revision()'ye geri iletmeniz yeterlidir: hangi depoya ait olduğunu hatırlar ve başlangıçta istenen revizyonu ("main" burada) yeni depo için yeniden çözer.

>>> other_revision = resolve_revision("openai-community/gpt2-medium", revision=revision)  # resolves "main" again
>>> other_revision.resolved
'6dcaa7a952f72f9298047fd5137cd6e4f05f41da'
>>> config = hf_hub_download("openai-community/gpt2-medium", "config.json", revision=other_revision)

Xet önbellekleme

Daha verimli yüklemeler sağlamak için hf_xet, mevcut huggingface_hub önbelleğine bir xet dizini ekler. Bu dizin, dosyaları parçalara eşleyen bir veri yapısı olan shard'ları (parçaları) ve yükleme sırasında kopya önleme ile devam etme için kullanılan geçici verileri saklar. Xet Storage sistemi hakkında daha fazla bilgi için bu bölüme bakın.

hf_xet, indirme işlemleri için yerel bir parça önbelleği kullanmaz. HF_XET_CHUNK_CACHE_SIZE_BYTES ayarını yapmak, böyle bir önbelleği etkinleştirmez. İndirilen dosyalar hâlâ dosya tabanlı önbellekte saklanır.

Varsayılan olarak ~/.cache/huggingface/xet konumunda bulunan xet dizini, HF_XET_CACHE ile yapılandırılabilir. Yapısı aşağıdaki gibidir:

<CACHE_DIR>
├─ xet
│  ├─ environment_identifier
│  │  ├─ shard-cache
│  │  ├─ staging

environment_identifier dizini kodlanmış bir dizedir (sisteminizde https___cas_serv-tGqkUaZf_CBPHQ6h gibi görünebilir). Bu, geliştirme sırasında yerel ve üretim sürümlerindeki önbelleğin aynı anda var olmasına olanak tanır. Ayrıca farklı depolama bölgelerinde bulunan depolardan indirme yapıldığında da kullanılır. xet dizininde birden fazla bu tür girdi görebilirsiniz; bunların her biri farklı bir ortama karşılık gelir ancak iç yapıları aynıdır.

Dahili dizinler aşağıdaki amaçlara hizmet eder:

  • shard-cache, yükleme yolunda kullanılan önbelleğe alınmış parçaları içerir.
  • staging, yeniden başlatılabilir yüklemeleri desteklemek üzere tasarlanmış bir çalışma alanıdır.

Bunlar aşağıda belgelenmiştir.

Parça önbelleği ve geçici veriler, yüklemeler için bir optimizasyon katmanı olarak hf_xet tarafından yönetilir. İndirilen dosyaları yönetmek için huggingface_hub dosya tabanlı önbellek API'lerini kullanın.

shard-cache

Bu önbellek, içerik Hub'a yüklendiğinde kullanılır. Düz bir dizindir ve yalnızca shard dosyalarından oluşur; her shard dosyası, shard adı olarak bir kimlik (ID) kullanır.

<CACHE_DIR>
├─ xet
│  ├─ environment_identifier
│  │  ├─ shard-cache
│  │  │  ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb
│  │  │  ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│  │  │  ├─ ceeeb7ea4cf6c0a8d395a2cf9c08871211fbbd17b9b5dc1005811845307e6b8f.mdb
│  │  │  ├─ e8535155b1b11ebd894c908e91a1e14e3461dddd1392695ddc90ae54a548d8b2.mdb

shard-cache, aşağıdaki özelliklere sahip shard'ları içerir:

  • Yerel olarak oluşturuldu ve CAS'a başarıyla yüklendi
  • Küresel yinelenen veri kaldırma algoritmasının bir parçası olarak CAS'tan indirildi

Shard'lar, dosyalar ile parçalar (chunk) arasındaki eşlemeyi sağlar. Yüklemeler sırasında her dosya parçalara ayrılır ve parçanın hash'i kaydedilir. Ardından önbellekteki her shard sorgulanır. Bir shard, yüklenmekte olan yerel dosyada bulunan bir parça hash'ini içeriyorsa, o parça CAS'ta zaten saklandığı için atılabilir.

Tüm parçaların, indirildikleri andan itibaren 3-4 hafta geçerlilik süresi vardır. Süresi dolmuş parçalar, yükleme sırasında yüklenmez ve süresi dolduktan bir hafta sonra silinir.

staging

Yükleme, yeni içerik depoya taahhüt edilmeden önce sonlandığında, dosya aktarımını yeniden başlatmanız gerekir. Ancak, kesinti öncesinde bazı parçaların başarıyla yüklendiği mümkündür.

Baştan başlamak zorunda kalmamanız için staging dizini, yükleme sırasında bir çalışma alanı olarak görev yapar ve başarıyla yüklenen parçaların meta verilerini saklar. staging dizininin yapısı şu şekildedir:

<CACHE_DIR>
├─ xet
│  ├─ environment_identifier
│  │  ├─ staging
│  │  │  ├─ shard-session
│  │  │  │  ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│  │  │  │  ├─ xorb-metadata
│  │  │  │  │  ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb

Dosyalar işlendikçe ve parçalar başarıyla yüklendikçe, bu parçaların meta verileri xorb-metadata dizininde bir shard olarak saklanır. Bir yükleme oturumu devam ettirilirse, her dosya yeniden işlenir ve bu dizindeki shard'lar kontrol edilir. Başarıyla yüklenen içerikler atlanır, yeni içerikler ise yüklenir (ve meta verileri kaydedilir).

Öte yandan, shard-session, işlenen dosyalar için dosya ve parça bilgilerini saklar. Bir yükleme başarıyla tamamlandığında, bu parçalardaki içerik daha kalıcı olan shard-cache alanına taşınır.

Sınırlar ve Kısıtlamalar

shard-cache için 16GB'lık bir yumuşak sınır vardır ve bu sınır HF_XET_SHARD_CACHE_SIZE_LIMIT ortam değişkeni üzerinden yapılandırılabilir. Bu önbelleği yönetmek için yüksek düzey bir API yoktur.

Shard önbelleği ve geçici veriler, yüklemeleri optimize etmek için kullanılır. Varlıkların kendileriyle etkileşime geçmek için huggingface_hub önbellek sistemi API'lerini kullanmanız önerilir.

Xet tarafından kullanılan alanı geri kazanmanız veya olası önbellekle ilgili sorunları ayıklamanız gerekiyorsa, <cache_dir> Hugging Face önbelleğinizin konumu olan (genellikle ~/.cache/huggingface) rm -rf ~/<cache_dir>/xet komutunu çalıştırarak xet önbelleğini tamamen kaldırmanız yeterlidir.

Örnek xet önbellek dizin ağacı:

<CACHE_DIR>
├─ xet
│  ├─ environment_identifier
│  │  ├─ shard-cache
│  │  │  ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb
│  │  │  ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│  │  │  ├─ ceeeb7ea4cf6c0a8d395a2cf9c08871211fbbd17b9b5dc1005811845307e6b8f.mdb
│  │  │  ├─ e8535155b1b11ebd894c908e91a1e14e3461dddd1392695ddc90ae54a548d8b2.mdb
│  │  ├─ staging
│  │  │  ├─ shard-session
│  │  │  │  ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│  │  │  │  ├─ xorb-metadata
│  │  │  │  │  ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb

Xet Storage hakkında daha fazla bilgi için bu bölüme bakın.

Varlıkları önbelleğe alma

In addition to caching files from the Hub, downstream libraries often requires to cache other files related to HF but not handled directly by huggingface_hub (example: file downloaded from GitHub, preprocessed data, logs,…). In order to cache those files, called assets, one can use cached_assets_path(). This small helper generates paths in the HF cache in a unified way based on the name of the library requesting it and optionally on a namespace and a subfolder name. The goal is to let every downstream libraries manage its assets its own way (e.g. no rule on the structure) as long as it stays in the right assets folder. Those libraries can then leverage tools from huggingface_hub to manage the cache, in particular scanning and deleting parts of the assets from a CLI command.

from huggingface_hub import cached_assets_path

assets_path = cached_assets_path(library_name="datasets", namespace="SQuAD", subfolder="download")
something_path = assets_path / "something.json" # Do anything you like in your assets folder !

cached_assets_path() varlıkları depolamak için önerilen yöntemdir ancak zorunlu değildir. Kütüphaneniz zaten kendi önbelleğini kullanıyorsa, onu kullanmaktan çekinmeyin!

Uygulamada varlıklar

Uygulamada, varlıklar önbelleğiniz aşağıdaki ağaca benzer görünmelidir:

    assets/
    └── datasets/
    │   ├── SQuAD/
    │   │   ├── downloaded/
    │   │   ├── extracted/
    │   │   └── processed/
    │   ├── Helsinki-NLP--tatoeba_mt/
    │       ├── downloaded/
    │       ├── extracted/
    │       └── processed/
    └── transformers/
        ├── default/
        │   ├── something/
        ├── bert-base-cased/
        │   ├── default/
        │   └── training/
    hub/
    └── models--julien-c--EsperBERTo-small/
        ├── blobs/
        │   ├── (...)
        │   ├── (...)
        ├── refs/
        │   └── (...)
        └── [ 128]  snapshots/
            ├── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/
            │   ├── (...)
            └── bbc77c8132af1cc5cf678da3f1ddf2de43606d48/
                └── (...)

Dosya tabanlı önbelleğinizi yönetin

Önbelleğinizi denetleyin

Şu anda önbelleğe alınan dosyalar yerel dizininizden asla silinmez: bir dalın yeni bir revizyonunu indirdiğinizde, tekrar ihtiyaç duymanız halinde önceki dosyalar korunur. Bu nedenle, hangi depoların ve revizyonların en fazla disk alanını kapladığını bilmek için önbellek dizininizi denetlemek faydalı olabilir. huggingface_hub, hf CLI'dan veya Python'dan kullanabileceğiniz yardımcıları sağlar.

Önbelleği terminalden denetleyin

Yerel olarak depolananları incelemek için hf cache ls komutunu çalıştırın. Varsayılan olarak komut, bilgileri depoya göre toplar:

➜ hf cache ls
ID                                   SIZE   LAST_ACCESSED LAST_MODIFIED REFS
------------------------------------ ------- ------------- ------------- -------------------
dataset/glue                         116.3K 4 days ago     4 days ago     2.4.0 main 1.17.0
dataset/google/fleurs                 64.9M 1 week ago     1 week ago     main refs/pr/1
model/Jean-Baptiste/camembert-ner    441.0M 2 weeks ago    16 hours ago   main
model/bert-base-cased                  1.9G 1 week ago     2 years ago
model/t5-base                          10.1K 3 months ago   3 months ago   main
model/t5-small                        970.7M 3 days ago     3 days ago     main refs/pr/1

Found 6 repo(s) for a total of 12 revision(s) and 3.4G on disk.

Önbelleğe alınmış tüm anlık görüntüleri listelemek için --revisions ekleyin ve önemli olanlara odaklanmak için filtreleri zincirleyin. Filtreler, kullanıcı dostu boyut ve süreleri anladığından size>1GB veya accessed>30d gibi ifadeler hazır olarak çalışır:

➜ hf cache ls --revisions --filter "size>1GB" --filter "accessed>30d"
ID                                   REVISION            SIZE   LAST_MODIFIED REFS
------------------------------------ ------------------ ------- ------------- -------------------
model/bert-base-cased                6d1d7a1a2a6cf4c2    1.9G  2 years ago
model/t5-small                       1c610f6b3f5e7d8a    1.1G  3 months ago  main

Found 2 repo(s) for a total of 2 revision(s) and 3.0G on disk.

Makine dostu çıktıya mı ihtiyacınız var? Yapılandırılmış nesneler için --format json veya tablolar için --format csv kullanın. Alternatif olarak --quiet yalnızca tanımlayıcıları (satır başına bir tane) yazdırır, böylece bunları diğer araçlara aktarabilirsiniz. Girdileri accessed, modified, name veya size (sıralamayı kontrol etmek için :asc veya :desc ekleyin) göre sıralamak için --sort ve sonuçları en üst N girdiyle sınırlamak için --limit kullanın. HF_HOME dışında depolanan bir önbelleği denetlemeniz gerektiğinde bu seçenekleri --cache-dir ile birleştirin.

Ortak kabuk araçlarıyla filtrele

Tablo çıktısı, zaten bildiğiniz araçları kullanmaya devam edebileceğiniz anlamına gelir. Örneğin, aşağıdaki parça t5-small ile ilgili önbelleğe alınmış tüm sürümleri bulur:

➜ eval "hf cache ls --revisions" | grep "t5-small"
model/t5-small                       1c610f6b3f5e7d8a    1.1G  3 months ago  main
model/t5-small                       8f3ad1c90fed7a62    820.1M 2 weeks ago   refs/pr/1

Önbelleği Python'dan denetleyin

Daha gelişmiş bir kullanım için, CLI aracının çağırdığı python yardımcı programı olan scan_cache_dir() işlevini kullanın.

4 veri sınıfı etrafında yapılandırılmış ayrıntılı bir rapor almak için kullanabilirsiniz:

İşte basit bir kullanım örneği. Ayrıntılar için referansa bakın.

>>> from huggingface_hub import scan_cache_dir

>>> hf_cache_info = scan_cache_dir()
HFCacheInfo(
    size_on_disk=3398085269,
    repos=frozenset({
        CachedRepoInfo(
            repo_id='t5-small',
            repo_type='model',
            repo_path=PosixPath(...),
            size_on_disk=970726914,
            nb_files=11,
            last_accessed=1662971707.3567169,
            last_modified=1662971107.3567169,
            revisions=frozenset({
                CachedRevisionInfo(
                    commit_hash='d78aea13fa7ecd06c29e3e46195d6341255065d5',
                    size_on_disk=970726339,
                    snapshot_path=PosixPath(...),
                    # No `last_accessed` as blobs are shared among revisions
                    last_modified=1662971107.3567169,
                    files=frozenset({
                        CachedFileInfo(
                            file_name='config.json',
                            size_on_disk=1197
                            file_path=PosixPath(...),
                            blob_path=PosixPath(...),
                            blob_last_accessed=1662971707.3567169,
                            blob_last_modified=1662971107.3567169,
                        ),
                        CachedFileInfo(...),
                        ...
                    }),
                ),
                CachedRevisionInfo(...),
                ...
            }),
        ),
        CachedRepoInfo(...),
        ...
    }),
    warnings=[
        CorruptedCacheException("Snapshots dir doesn't exist in cached repo: ..."),
        CorruptedCacheException(...),
        ...
    ],
)

Önbelleğinizi doğrulayın

huggingface_hub, önbellekteki dosyalarınızın Hub’daki kontrol toplamalarıyla eşleşip eşleşmediğini doğrulayabilir. Belirli bir depoyun belirli bir revizyonu için dosya tutarlılığını doğrulamak için hf cache verify CLI’ını kullanın:

>>> hf cache verify meta-llama/Llama-3.2-1B-Instruct
✅ Verified 13 file(s) for 'meta-llama/Llama-3.2-1B-Instruct' (model) in ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct/snapshots/9213176726f574b556790deb65791e0c5aa438b6
  All checksums match.

Belirli bir önbelleğe alınmış revizyonu doğrulayın:

>>> hf cache verify meta-llama/Llama-3.1-8B-Instruct --revision 0e9e39f249a16976918f6564b8830bc894c89659

Kullanım hakkında daha fazla ayrıntı ve seçeneklerin tam listesi için hf cache verify CLI referansını kontrol edin.

Önbelleğinizi temizleyin

Önbelleğinizi taramak ilginçtir ancak bir sonraki adımınız genellikle sürücünüzde yer açmak için bazı bölümleri silmektir. Bunu hf cache rm ve hf cache prune komut satırı komutları ile yapmak mümkündür. Ayrıca, önbelleği tararken döndürülen HFCacheInfo nesnesindeki delete_revisions() ve delete_files() yardımcı işlevlerini programatik olarak da kullanabilirsiniz.

Silme stratejisi

Bazı önbelleği silmek için, silinecek revizyonların bir listesini iletmeniz gerekir. Araç, bu listeye dayanarak boş alan açmak için bir strateji tanımlar. Hangi dosyaların ve klasörlerin silineceğini açıklayan bir DeleteCacheStrategy nesnesi döndürür. DeleteCacheStrategy, serbest bırakılması beklenen alan miktarını size bildirir. Silme işlemine onay verdiğinizde, silmenin etkili olması için onu çalıştırmalısınız. Uyuşmazlıkları önlemek için bir strateji nesnesini manuel olarak düzenleyemezsiniz.

Revizyonları silme stratejisi şu şekildedir:

  • revizyon sembolik bağlantılarını içeren snapshot klasörü silinir.
  • sadece silinecek revizyonlar tarafından hedeflenen blob dosyaları da silinir.
  • bir revizyon 1 veya daha fazla refs'e bağlıysa, referanslar silinir.
  • Bir depodaki tüm revizyonlar silinirse, önbelleğe alınmış tüm depo silinir.

delete_files() ile bireysel dosyaları silme aynı mantığı izler: snapshot girdileri kaldırılır ve blob'ları yalnızca onlara başka bir önbelleğe alınmış dosyanın referans vermediği durumda silinir. Ref'ler ve snapshot klasörleri korunur.

Revizyon özetleri tüm depolar arasında benzersizdir. hf cache rm bu nedenle bir depo tanımlayıcısını (örneğin model/bert-base-uncased) veya yalnızca bir revizyon özetini kabul eder; bir özet geçerken depoyu ayrı belirtmenize gerek yoktur.

Eğer bir revizyon önbellekte bulunamazsa, sessizce yok sayılır. Ayrıca, bir dosya veya klasör silinmeye çalışılırken bulunamazsa, bir uyarı günlüğe kaydedilir ancak bir hata fırlatılmaz. Silme işlemi, DeleteCacheStrategy nesnesinde yer alan diğer yollar için devam eder.

Önbelleği terminalden temizle

Önbelleğinizden depoları veya revizyonları kalıcı olarak silmek için hf cache rm komutunu kullanın. Bir veya birden fazla depo tanımlayıcısı (örneğin model/bert-base-uncased) veya revizyon özetlerini iletin:

➜ hf cache rm model/bert-base-cased
About to delete 1 repo(s) totalling 1.9G.
  - model/bert-base-cased (entire repo)
Proceed with deletion? [y/N]: y
Deleted 1 repo(s) and 1 revision(s); freed 1.9G.

Ayrıca, bir filtreyle belirlenen girdileri toplu olarak silmek için hf cache rm komutunu hf cache ls --quiet ile birlikte kullanabilirsiniz:

>>> hf cache rm $(hf cache ls --filter "accessed>1y" -q) -y
About to delete 2 repo(s) totalling 5.31G.
  - model/meta-llama/Llama-3.2-1B-Instruct (entire repo)
  - model/hexgrad/Kokoro-82M (entire repo)
Deleted 2 repo(s) and 2 revision(s); freed 5.31G.

Aynı çağrıda depoları ve revizyonları karıştırın. Etkiyi önizlemek için --dry-run ekleyin veya betik yazarken onay istemini atlamak için --yes kullanın:

➜ hf cache rm model/t5-small 8f3ad1c --dry-run
About to delete 1 repo(s) and 1 revision(s) totalling 1.1G.
  - model/t5-small:
      8f3ad1c [main] 1.1G
Dry run: no files were deleted.

Tüm bir depoyu değil de tek bir dosyayı, örneğin bir GGUF kuantizasyonunu kaldırmak için bir hf:// dosya URI'si geçirin. Dosya, depodaki önbelleğe alınmış tüm revizyonlardan kaldırılır ve blob'u, başka önbelleğe alınmış bir dosya hâlâ ona referans vermiyorsa silinir. Revizyon kullanılabilir durumda kalır ve silinen dosya, bir sonraki ihtiyaç duyulduğunda yeniden indirilir. Yollar tam olarak eşleşmelidir: klasörler ve glob desenleri desteklenmez.

➜ hf cache rm hf://models/unsloth/gemma-3-27b-it-GGUF/gemma-3-27b-it-Q4_K_M.gguf --dry-run
About to delete 1 file(s) totalling 16.5G.
  - model/unsloth/gemma-3-27b-it-GGUF@3f4b5c1d2e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c/gemma-3-27b-it-Q4_K_M.gguf
Dry run: no files were deleted.

Varsayılan önbellek konumu dışında çalışırken, komutu --cache-dir PATH ile eşleştirin.

Önbellek çöpünü toplu olarak temizlemek için hf cache prune komutunu çalıştırın. Bu komut, bir dal veya etiket tarafından artık referanslanmayan revizyonları, yarıda kesilen indirmelerden kalan .incomplete dosyalarını ve önbellekteki hiçbir depo tarafından artık referanslanmayan paylaşılan blob'ları otomatik olarak siler:

➜ hf cache prune
About to delete 3 unreferenced revision(s) and 2 incomplete download(s) (2.4G total).
  - model/t5-small:
      1c610f6b [refs/pr/1] 820.1M
      d4ec9b72 [(detached)] 640.5M
  - dataset/google/fleurs:
      2b91c8dd [(detached)] 937.6M
Proceed? [y/N]: y
Deleted 3 unreferenced revision(s) and 2 incomplete download(s); freed 2.4G.

.incomplete dosyaları, bir indirme yarıda kesildiğinde geride kalan kısmi blob'lardır. Revizyon tabanlı tarama tarafından takip edilmedikleri için hf cache ls bunları yalnızca bir ipucuyla (Found X incomplete download(s) ...) işaretlerken, bunları fiilen kaldıran komut hf cache prune'tür. hf cache rm, tüm bir repoyu sildiği durumlar dışında bunlara asla dokunmaz.

Her iki komut da --dry-run, --yes ve --cache-dir seçeneklerini destekler; böylece gerektiğinde önizleme yapabilir, otomatikleştirebilir ve alternatif önbellek dizinlerini hedefleyebilirsiniz.

Önbelleği Python'dan temizle

Daha fazla esneklik için delete_revisions() yöntemini programatik olarak da kullanabilirsiniz. İşte basit bir örnek. Ayrıntılar için referansa bakın.

>>> from huggingface_hub import scan_cache_dir

>>> delete_strategy = scan_cache_dir().delete_revisions(
...     "81fd1d6e7847c99f5862c9fb81387956d99ec7aa"
...     "e2983b237dccf3ab4937c97fa717319a9ca1a96d",
...     "6c0e6080953db56375760c0471a8c5f2929baf11",
... )
>>> print("Will free " + delete_strategy.expected_freed_size_str)
Will free 8.6G

>>> delete_strategy.execute()
Update on GitHub

←Koleksiyonlar Model Kartları→