Hub Python Library documentation
Önbellek sistemi referansı
Önbellek sistemi referansı
Önbellekleme sistemi, Hub'a bağımlı kütüphaneler arasında paylaşılan merkezi önbellek sistemi haline gelmesi için v0.8.0 sürümünde güncellendi. HF'de önbellekleme hakkında ayrıntılı bir sunum için önbellek sistemi kılavuzunu okuyun.
Yardımcılar
try_to_load_from_cache
huggingface_hub.try_to_load_from_cache
< source >( repo_id: strfilename: strcache_dir: str | pathlib.Path | None = Nonerevision: str | None = Nonerepo_type: str | None = None ) → Optional[str] or _CACHED_NO_EXIST
Parametreler
- cache_dir (
strveyaos.PathLike) — Önbelleğe alınan dosyaların bulunduğu klasör. - repo_id (
str) — huggingface.co üzerindeki depoyun kimliği. - filename (
str) —repo_idiçinde aranacak dosya adı. - revision (
str, isteğe bağlı) — Kullanılacak belirli model sürümü. Sağlanmazsa vecommit_hashde sağlanmazsa varsayılan olarak"main"kullanılır. - repo_type (
str, isteğe bağlı) — Deponun türü. Varsayılan olarak"model"olur.
Dönüş değeri
Optional[str] veya _CACHED_NO_EXIST
Dosya önbelleğe alınmadıysa None döndürülür. Aksi halde:
- Önbellekte bulunursa önbelleğe alınmış dosyanın tam yolu
- Belirtilen commit hash'inde dosya yoksa ve bu durum önbelleğe alındıysa özel bir değer olan
_CACHED_NO_EXIST.
Belirtilen bir revizyon için en son önbelleğe alınmış dosyayı, bulunursa, önbelleği tarayarak döndürür.
Bu fonksiyon, dosya önbelleğe alınmamışsa herhangi bir istisna yükseltmez.
cached_assets_path
huggingface_hub.cached_assets_path
< source >( library_name: strnamespace: str = 'default'subfolder: str = 'default'assets_dir: str | pathlib.Path | None = None )
Parametreler
- library_name (
str) — Önbellek klasörünü yönetecek kütüphanenin adı. Örnek:"dataset". - namespace (
str, isteğe bağlı, varsayılan “default”) — Verinin ait olduğu ad alanı. Örnek:"SQuAD". - subfolder (
str, isteğe bağlı, varsayılan “default”) — Verilerin depolanacağı alt klasör. Örnek:extracted. - assets_dir (
str,Path, isteğe bağlı) — Varlıkların önbelleğe alındığı klasöre giden yol. Bu, Hub dosyalarının önbelleğe alındığı klasörle aynı olmamalıdır. Verilmezse varsayılan olarakHF_HOME / "assets"kullanılır. AyrıcaHF_ASSETS_CACHEortam değişkeniyle de ayarlanabilir.
Arbitrary dosyaları önbelleğe almak için bir klasör yolu döndürür.
huggingface_hub, varlıkları depolamak için standart bir klasör yolu sağlar. Bu, önbelleği aşağı akış kütüphanesine entegre etmenin önerilen yoludur; çünkü önbelleğin taranması ve doğru şekilde silinmesi için yerleşik araçlardan yararlanılır.
Hub'dan önbelleğe alınan dosyalar ile varlıklar (assets) arasında bir ayrım yapılır. Hub'dan gelen dosyalar git-bilinçli bir şekilde önbelleğe alınır ve tamamen huggingface_hub tarafından yönetilir. ilgili belgelere bakın. Aşağı akış kütüphanesinin önbelleğe aldığı diğer tüm dosyalar “varlık” (asset) olarak kabul edilir (dış kaynaklardan indirilen dosyalar, .tar arşivinden çıkarılan dosyalar, eğitim için ön işleme tabi tutulan dosyalar, …).
Klasör yolu oluşturulduğunda, var olduğu ve bir dizin olduğu garanti edilir.
Yol, 3 derinlik seviyesine dayanır: kütüphane adı, bir ad alanı (namespace) ve bir
alt klasör. Bu 3 seviye, huggingface_hub'ün varlıklar önbelleğinin (assets cache)
bölümlerini tarama/silme sırasında klasörler beklemesine olanak tanıyarak esneklik
sağlar. Bir kütüphane içinde, tüm ad alanlarının alt klasör adlarının aynı alt
kümesini paylaşması beklenir ancak bu zorunlu bir kural değildir. Aşağı akış
(downstream) kütüphanesi, önbelleği içinde hangi dosya yapısını benimseyeceğine
tamamen kendisi karar verir. Ad alanı ve alt klasör isteğe bağlıdır (varsayılan
olarak bir "default/" alt klasörü kullanılır) ancak her aşağı akış
kütüphanesinin kendi önbelleğini yönetmesini istediğimiz için kütüphane adı
zorunludur.
Beklenen ağaç:
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/
└── (...)Örnek:
>>> from huggingface_hub import cached_assets_path
>>> cached_assets_path(library_name="datasets", namespace="SQuAD", subfolder="download")
PosixPath('/home/wauplin/.cache/huggingface/extra/datasets/SQuAD/download')
>>> cached_assets_path(library_name="datasets", namespace="SQuAD", subfolder="extracted")
PosixPath('/home/wauplin/.cache/huggingface/extra/datasets/SQuAD/extracted')
>>> cached_assets_path(library_name="datasets", namespace="Helsinki-NLP/tatoeba_mt")
PosixPath('/home/wauplin/.cache/huggingface/extra/datasets/Helsinki-NLP--tatoeba_mt/default')
>>> cached_assets_path(library_name="datasets", assets_dir="/tmp/tmp123456")
PosixPath('/tmp/tmp123456/datasets/default/default')scan_cache_dir
huggingface_hub.scan_cache_dir
< source >( cache_dir: str | pathlib.Path | None = None )
Tüm HF önbellek sistemini tarayın ve bir ~HFCacheInfo yapısı döndürün.
Önbellek sisteminizi programatik olarak taramak için scan_cache_dir kullanın. Önbellek, depo depo taranır. Bir depo bozuksa, ~CorruptedCacheException içsel olarak atılır ancak yakalanır ve ~HFCacheInfo yapısında döndürülür. Yalnızca geçerli depolar için uygun bir rapor oluşturulur.
>>> 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,
revisions=frozenset({
CachedRevisionInfo(
commit_hash='d78aea13fa7ecd06c29e3e46195d6341255065d5',
size_on_disk=970726339,
snapshot_path=PosixPath(...),
files=frozenset({
CachedFileInfo(
file_name='config.json',
size_on_disk=1197
file_path=PosixPath(...),
blob_path=PosixPath(...),
),
CachedFileInfo(...),
...
}),
),
CachedRevisionInfo(...),
...
}),
),
CachedRepoInfo(...),
...
}),
warnings=[
CorruptedCacheException("Snapshots dir doesn't exist in cached repo: ..."),
CorruptedCacheException(...),
...
],
)Ayrıca hf komut satırından şu komutu kullanarak ayrıntılı bir raporu doğrudan yazdırabilirsiniz:
> hf cache ls ID SIZE LAST_ACCESSED LAST_MODIFIED REFS --------------------------- -------- ------------- ------------- ----------- dataset/nyu-mll/glue 157.4M 2 days ago 2 days ago main script model/LiquidAI/LFM2-VL-1.6B 3.2G 4 days ago 4 days ago main model/microsoft/UserLM-8b 32.1G 4 days ago 4 days ago main Done in 0.0s. Scanned 6 repo(s) for a total of 3.4G. Got 1 warning(s) while scanning. Use -vvv to print details.
Şunları yükseltir:
CacheNotFoundÖnbellek dizini mevcut değilse.
ValueErrorÖnbellek dizini bir dizin yerine bir dosya ise.
Dönüş: ~HFCacheInfo nesnesi.
Veri yapıları
Tüm yapılar scan_cache_dir() tarafından oluşturulur ve döndürülür ve değiştirilemezdir.
HFCacheInfo
sınıf huggingface_hub.HFCacheInfo
< source >( size_on_disk: intrepos: frozensetincomplete_files: frozensetwarnings: listcache_dir: pathlib.Path | None = None )
Parametreler
- size_on_disk (
int) — Önbellek sisteminin bayt cinsinden fiziksel boyutu. Depolar arasında paylaşılan bir blob bir kez sayılır ve hiçbir depo tarafından artık referanslanmayan, yalnızca depolanan paylaşılan bloblar dahil edilir. Depo başına boyutların toplamından küçük olabilir. - repos (
frozenset[CachedRepoInfo]) — Tarama sırasında önbellek sisteminde bulunan tüm geçerli önbelleğe alınmış depoları tanımlayan ~CachedRepoInfo kümesi. - incomplete_files (
frozenset[CachedIncompleteFileInfo]) — Kesintiye uğrayan indirmeler tarafından geride bırakılan yetim*.incompletedosyalarını açıklayan ~CachedIncompleteFileInfo kümesi. - warnings (
list[CorruptedCacheException]) — Önbelleği tararken oluşan ~CorruptedCacheException listesi. Bu istisnalar, taramanın devam edebilmesi için yakalanır. Bozuk depolar taramadan atlanır. - cache_dir (
PathveyaNone) — Taranan önbellek dizini.
Tüm önbellek sistemi hakkında bilgi tutan donmuş veri yapısı.
Bu veri yapısı scan_cache_dir() tarafından döndürülür ve değiştirilemezdir.
size_on_diskyalnızca blobları hesaba katar ve bozuk depolar atlanır. Bu, fiziksel bir boyuttur: bir paylaşılan blobu onu referans veren her depoya atfedenCachedRepoInfo.size_on_disk'in aksine, paylaşılan bir blob burada yalnızca bir kez sayılır.
Bireysel önbelleğe alınmış dosyaları silmek için stratejiyi hazırlayın.
Yalnızca snapshot girdileri kaldırılır. Bir blob, başka bir önbelleğe alınmış dosya tarafından referanslanmıyorsa silinir; bu nedenle diğer revizyonlarla paylaşılan bloblar korunur. Ref'ler ve snapshot dizinleri de, bir snapshot boş kalsa bile korunur. Tüm revizyonları veya depoları silmek için delete_revisions() kullanın.
Örnek:
>>> from huggingface_hub import scan_cache_dir
>>> cache_info = scan_cache_dir()
>>> files = [
... file
... for repo in cache_info.repos
... if repo.repo_id == "org/model"
... for revision in repo.revisions
... for file in revision.files
... if file.file_name == "model-Q4_K_M.gguf"
... ]
>>> delete_strategy = cache_info.delete_files(*files)
>>> print(f"Will free {delete_strategy.expected_freed_size_str}.")
Will free 4.9G.
>>> delete_strategy.execute()Yerel olarak önbelleğe alınmış bir veya daha fazla revizyonu silmek için stratejiyi hazırlayın.
Girdi revizyonları herhangi bir revizyon hash'i olabilir. Bir revizyon hash'i yerel önbellekte bulunamazsa bir uyarı oluşturulur ancak bir hata fırlatılmaz. Hash'ler depolar arasında benzersiz olduğundan, revizyonlar farklı önbelleğe alınmış depolardan gelebilir.
Örnekler:
>>> from huggingface_hub import scan_cache_dir
>>> cache_info = scan_cache_dir()
>>> delete_strategy = cache_info.delete_revisions(
... "81fd1d6e7847c99f5862c9fb81387956d99ec7aa"
... )
>>> print(f"Will free {delete_strategy.expected_freed_size_str}.")
Will free 7.9K.
>>> delete_strategy.execute()>>> from huggingface_hub import scan_cache_dir
>>> scan_cache_dir().delete_revisions(
... "81fd1d6e7847c99f5862c9fb81387956d99ec7aa",
... "e2983b237dccf3ab4937c97fa717319a9ca1a96d",
... "6c0e6080953db56375760c0471a8c5f2929baf11",
... ).execute()
delete_revisions, çalıştırılması gereken bir DeleteCacheStrategy nesnesi döndürür. DeleteCacheStrategy değiştirilmek üzere tasarlanmamıştır, ancak silme işlemini fiilen çalıştırmadan önce bir kuru çalıştırma (dry run) yapılmasına olanak tanır.
export_as_table
< source >( verbosity: int = 0 ) → str
HFCacheInfo nesnesinden bir tablo oluşturun.
Her depo için tek satırlı bir tablo almak için verbosity=0 parametresini geçirin; sütunlar “repo_id”, “repo_type”, “size_on_disk”, “nb_files”, “last_accessed”, “last_modified”, “refs”, “local_path” olacaktır.
Her depo ve revizyon için bir satır içeren (bu nedenle tek bir depo için birden fazla satır görünebilir) bir tablo almak için verbosity=1 parametresini geçirin; sütunlar “repo_id”, “repo_type”, “revision”, “size_on_disk”, “nb_files”, “last_modified”, “refs”, “local_path” şeklindedir.
Örnek:
>>> from huggingface_hub.utils import scan_cache_dir
>>> hf_cache_info = scan_cache_dir()
HFCacheInfo(...)
>>> print(hf_cache_info.export_as_table())
REPO ID REPO TYPE SIZE ON DISK NB FILES LAST_ACCESSED LAST_MODIFIED REFS LOCAL PATH
--------------------------------------------------- --------- ------------ -------- ------------- ------------- ---- --------------------------------------------------------------------------------------------------
roberta-base model 2.7M 5 1 day ago 1 week ago main ~/.cache/huggingface/hub/models--roberta-base
suno/bark model 8.8K 1 1 week ago 1 week ago main ~/.cache/huggingface/hub/models--suno--bark
t5-base model 893.8M 4 4 days ago 7 months ago main ~/.cache/huggingface/hub/models--t5-base
t5-large model 3.0G 4 5 weeks ago 5 months ago main ~/.cache/huggingface/hub/models--t5-large
>>> print(hf_cache_info.export_as_table(verbosity=1))
REPO ID REPO TYPE REVISION SIZE ON DISK NB FILES LAST_MODIFIED REFS LOCAL PATH
--------------------------------------------------- --------- ---------------------------------------- ------------ -------- ------------- ---- -----------------------------------------------------------------------------------------------------------------------------------------------------
roberta-base model e2da8e2f811d1448a5b465c236feacd80ffbac7b 2.7M 5 1 week ago main ~/.cache/huggingface/hub/models--roberta-base/snapshots/e2da8e2f811d1448a5b465c236feacd80ffbac7b
suno/bark model 70a8a7d34168586dc5d028fa9666aceade177992 8.8K 1 1 week ago main ~/.cache/huggingface/hub/models--suno--bark/snapshots/70a8a7d34168586dc5d028fa9666aceade177992
t5-base model a9723ea7f1b39c1eae772870f3b547bf6ef7e6c1 893.8M 4 7 months ago main ~/.cache/huggingface/hub/models--t5-base/snapshots/a9723ea7f1b39c1eae772870f3b547bf6ef7e6c1
t5-large model 150ebc2c4b72291e770f58e6057481c8d2ed331a 3.0G 4 5 months ago main ~/.cache/huggingface/hub/models--t5-large/snapshots/150ebc2c4b72291e770f58e6057481c8d2ed331aCachedRepoInfo
sınıf huggingface_hub.CachedRepoInfo
< source >( repo_id: strrepo_type: typing.Literal['model', 'dataset', 'space', 'kernel']repo_path: Pathsize_on_disk: intnb_files: intrevisions: frozensetlast_accessed: floatlast_modified: float )
Parametreler
- repo_id (
str) — Hub'daki repozituarın repo kimliği. Örnek:"google/fleurs". - repo_type (
Literal["dataset", "model", "space", "kernel"]) — Önbelleğe alınan depoyun türü. - repo_path (
Path) — Önbelleğe alınmış depoya yerel yol. - size_on_disk (
int) — Önbelleğe alınan depodaki blob dosya boyutlarının toplamı. - nb_files (
int) — Önbelleğe alınmış depodaki blob dosyalarının toplam sayısı. - revisions (
frozenset[CachedRevisionInfo]) — Depoda önbelleğe alınan tüm revizyonları açıklayan ~CachedRevisionInfo kümesi. - last_accessed (
float) — Depodaki bir blob dosyasının son erişim zaman damgası. - last_modified (
float) — Depodaki bir blob dosyasının son değiştirilme/oluşturulma zaman damgası.
Önbelleğe alınmış bir depoyla ilgili bilgileri tutan donmuş veri yapısı.
size_on_disk, yinelenen dosyalar nedeniyle tüm revizyon boyutlarının toplamı olmak zorunda değildir. Ayrıca, klasörlerin ve sembolik bağlantıların (ihmal edilebilir) boyutu değil, yalnızca blob'lar hesaba katılır.
last_accessedvelast_modifiedgüvenilirliği, kullandığınız işletim sistemine bağlı olabilir. Daha fazla ayrıntı için python belgelerini inceleyin.
(property) Blob dosya boyutlarının toplamı, insan tarafından okunabilir bir dize olarak.
Örnek: “42.2K”.
(property) refs ile revizyon veri yapıları arasındaki eşleme.
CachedRevisionInfo
sınıf huggingface_hub.CachedRevisionInfo
< source >( commit_hash: strsnapshot_path: Pathsize_on_disk: intfiles: frozensetrefs: frozensetlast_modified: float )
Parametreler
- commit_hash (
str) — Revizyonun hash'i (benzersiz). Örnek:"9338f7b671827df886678df2bdd7cc7b4f36dffd". - snapshot_path (
Path) —snapshotsklasöründeki revizyon dizinine giden yol. Hub'daki depodaki tam ağaç yapısını içerir. - files — (
frozenset[CachedFileInfo]): Anlık görüntüde bulunan tüm dosyaları açıklayan ~CachedFileInfo kümesi. - refs (
frozenset[str]) — Bu revizyona işaret edenrefskümesi. Revizyonunrefs’i yoksa, kopuk (detached) olarak kabul edilir. Örnek:{"main", "2.4.0"}veya{"refs/pr/1"}. - size_on_disk (
int) — Revizyonun sembolik bağlantı yaptığı blob dosya boyutlarının toplamı. - last_modified (
float) — Revizyonun son oluşturulma/değiştirilme zaman damgası.
Bir revizyon hakkında bilgi tutan donmuş veri yapısı.
A revision correspond to a folder in the snapshots folder and is populated with
the exact tree structure as the repo on the Hub but contains only symlinks. A
revision can be either referenced by 1 or more refs or be “detached” (no refs).
last_accessed, blob dosyalarının revizyonlar arasında paylaşıldığı için tek bir revizyon üzerinde doğru olarak belirlenemez.
size_on_disk, olası yinelenen dosyalar nedeniyle tüm dosya boyutlarının toplamı olmak zorunda değildir. Ayrıca, klasörlerin ve sembolik bağlantıların (ihmal edilebilir) boyutu dikkate alınmaz, yalnızca blob'lar hesaba katılır.
(property) Blob dosya boyutlarının toplamı, insan tarafından okunabilir bir dize olarak.
Örnek: “42.2K”.
(property) Revizyondaki dosyaların toplam sayısı.
CachedFileInfo
sınıf huggingface_hub.CachedFileInfo
< source >( file_name: strfile_path: Pathblob_path: Pathsize_on_disk: intblob_last_accessed: floatblob_last_modified: float )
Parametreler
- file_name (
str) — Dosyanın adı. Örnek:config.json. - file_path (
Path) —snapshotsdizinindeki dosyanın yolu. Dosya yolu,blobsklasöründeki bir blob'a işaret eden sembolik bir bağlantıdır. - blob_path (
Path) —file_pathtarafından referans verilen, repoya özgü blob girdisinin yolu. Blob girdisi, önbellek genelinde paylaşılan blob deposuna bir sembolik bağlantı olabilir. - size_on_disk (
int) — Blob dosyasının bayt cinsinden boyutu. - blob_last_accessed (
float) — Blob dosyasının son erişim zaman damgası (herhangi bir revizyondan). - blob_last_modified (
float) — Blob dosyasının son değiştirilme/oluşturulma zaman damgası.
Tek bir önbelleğe alınmış dosya hakkında bilgi tutan donmuş veri yapısı.
blob_last_accessedveblob_last_modifiedgüvenilirliği, kullandığınız işletim sistemine bağlı olabilir. Daha fazla ayrıntı için python belgelerine bakın.
(property) Blob dosyasının boyutu, insan tarafından okunabilir bir dize olarak.
Örnek: “42.2K”.
CachedIncompleteFileInfo
sınıf huggingface_hub.CachedIncompleteFileInfo
< source >( file_path: Pathsize_on_disk: int )
Tek bir eksik indirme hakkında bilgi tutan donmuş veri yapısı.
Kesilen indirmeler <cache>/<repo>/blobs/<etag>.incomplete dosyalarını geride bırakır.
Bunlar taahhüt edilmiş bir revizyonun parçası olmadığından, scan_cache_dir() tarafından ayrı olarak listelenir.
DeleteCacheStrategy
sınıf huggingface_hub.DeleteCacheStrategy
< source >( expected_freed_size: intblobs: frozensetrefs: frozensetrepos: frozensetsnapshots: frozensetfiles: frozenset = frozenset()cache_dir: pathlib.Path | None = None )
Parametreler
- expected_freed_size (
float) — Strateji uygulandığında serbest bırakılacak beklenen boyut. - blobs (
frozenset[Path]) — Silinecek blob dosya yollarının kümesi. - refs (
frozenset[Path]) — Silinecek referans dosya yollarının kümesi. - repos (
frozenset[Path]) — Silinecek tüm depo yollarının kümesi. - snapshots (
frozenset[Path]) — Silinecek snapshot kümesi (sembolik bağlantılar dizini). - files (
frozenset[Path], isteğe bağlı) — Silinecek bireysel görüntü girdilerinin kümesi. Blobları yalnızcablobsiçinde listelenmişse silinir. - cache_dir (
PathveyaNone) — Stratejinin hesaplandığı önbellek dizini. Silme işlemiyle kaldırılan, depoya yerel sembolik bağlantılarla referans verilen paylaşımlı blob'ları toplamak için kullanılır.
Önbelleğe alınmış sürümleri veya dosyaları silme stratejisini tutan donmuş veri yapısı.
Bu nesne programatik olarak örneklenmek için değil, delete_revisions() veya delete_files() tarafından döndürülmek üzere tasarlanmıştır. Kullanım örneği için dokümantasyona bakın.
(property) Serbest bırakılacak beklenen boyut, insan tarafından okunabilir bir dize olarak.
Örnek: “42.2K”.
İstisnalar
CorruptedCacheException
Huggingface önbellek sistemindeki beklenmeyen herhangi bir yapı için istisna.