Referensi sistem cache

Sistem cache diperbarui di v0.8.0 untuk menjadi sistem cache pusat yang dibagikan di antara pustaka yang bergantung pada Hub. Baca panduan sistem cache untuk presentasi terperinci tentang caching di HF.

Helper

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

Parameter

cache_dir (str atau os.PathLike) — Folder tempat file yang di-cache berada.
repo_id (str) — ID repo di huggingface.co.
filename (str) — Nama file yang akan dicari di dalam repo_id.
revision (str, opsional) — Versi model spesifik yang akan digunakan. Akan secara default menjadi "main" jika tidak diberikan dan tidak ada commit_hash yang diberikan juga.
repo_type (str, opsional) — Jenis repositori. Secara default akan menjadi "model".

Mengembalikan

Optional[str] atau _CACHED_NO_EXIST

Akan mengembalikan None jika file tidak di-cache. Jika tidak:

Path persis ke file yang di-cache jika ditemukan di cache
Nilai khusus _CACHED_NO_EXIST jika file tidak ada pada hash commit yang diberikan dan fakta ini telah di-cache.

Mengeksplorasi cache untuk mengembalikan file cache terbaru untuk revisi tertentu jika ditemukan.

Fungsi ini tidak akan melempar pengecualian apa pun jika file tidak di-cache.

Contoh:

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
    ...

cached_assets_path

huggingface_hub.cached_assets_path

< source >

( library_name: strnamespace: str = 'default'subfolder: str = 'default'assets_dir: str | pathlib.Path | None = None )

Parameter

library_name (str) — Nama pustaka yang akan mengelola folder cache. Contoh: "dataset".
namespace (str, opsional, default “default”) — Namespace tempat data tersebut berada. Contoh: "SQuAD".
subfolder (str, opsional, default “default”) — Subfolder tempat data akan disimpan. Contoh: extracted.
assets_dir (str, Path, opsional) — Path ke folder tempat aset di-cache. Ini tidak boleh menjadi folder yang sama di mana file Hub di-cache. Bawaan adalah HF_HOME / "assets" jika tidak diberikan. Juga dapat diatur dengan variabel lingkungan HF_ASSETS_CACHE.

Kembalikan jalur folder untuk meng-cache file arbitrer.

huggingface_hub menyediakan jalur folder kanonik untuk menyimpan aset. Ini adalah cara yang direkomendasikan untuk mengintegrasikan cache di pustaka hilir karena akan memanfaatkan alat bawaan untuk memindai dan menghapus cache dengan benar.

Pembedaan dibuat antara file yang di-cache dari Hub dan aset. File dari Hub di-cache dengan cara yang sadar-git dan sepenuhnya dikelola oleh huggingface_hub. Lihat dokumentasi terkait. Semua file lain yang di-cache oleh pustaka hilir dianggap sebagai “aset” (file yang diunduh dari sumber eksternal, diekstrak dari arsip .tar, dipreproses untuk pelatihan,…).

Setelah jalur folder dihasilkan, dijamin bahwa folder tersebut ada dan merupakan direktori. Jalur ini didasarkan pada 3 tingkat kedalaman: nama pustaka, namespace, dan subfolder. Ketiga tingkat ini memberikan fleksibilitas sekaligus memungkinkan huggingface_hub untuk mengharapkan folder saat memindai/menghapus bagian dari cache aset. Di dalam sebuah pustaka, diharapkan bahwa semua namespace berbagi subset nama subfolder yang sama, tetapi ini bukan aturan yang wajib. Pustaka downstream kemudian memiliki kendali penuh atas struktur file yang diadopsi di dalam cache-nya. Namespace dan subfolder bersifat opsional (akan default ke subfolder "default/") tetapi nama pustaka bersifat wajib karena kami ingin setiap pustaka downstream mengelola cache-nya sendiri.

Pohon yang diharapkan:

    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/
                └── (...)

Contoh:

>>> 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 )

Parameter

cache_dir (str or Path, optional) — Cache directory to cache. Defaults to the default HF cache directory.

Pindai seluruh sistem cache HF dan kembalikan struktur ~HFCacheInfo.

Gunakan scan_cache_dir untuk memindai sistem cache Anda secara programatik. Cache akan dipindai per repo. Jika sebuah repo rusak, ~CorruptedCacheException akan dilempar secara internal tetapi ditangkap dan dikembalikan dalam struktur ~HFCacheInfo. Hanya repo yang valid yang mendapatkan laporan yang tepat.

>>> 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(...),
        ...
    ],
)

Anda juga dapat mencetak laporan terperinci langsung dari baris perintah hf menggunakan:

> 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.

Membuang:

CacheNotFound Jika direktori cache tidak ada.

ValueError Jika direktori cache adalah file, bukan direktori.

Mengembalikan: objek ~HFCacheInfo.

Struktur data

Semua struktur dibangun dan dikembalikan oleh scan_cache_dir() dan bersifat tidak dapat diubah.

HFCacheInfo

kelas huggingface_hub.HFCacheInfo

< source >

( size_on_disk: intrepos: frozensetincomplete_files: frozensetwarnings: listcache_dir: pathlib.Path | None = None )

Parameter

size_on_disk (int) — Ukuran fisik sistem cache dalam byte. Blob yang dibagikan di antara repositori dihitung sekali, dan blob bersama yang hanya disimpan dan tidak lagi dirujuk oleh repositori mana pun tetap disertakan. Nilainya bisa lebih kecil daripada jumlah ukuran per repositori.
repos (frozenset[CachedRepoInfo]) — Kumpulan ~CachedRepoInfo yang menjelaskan semua repositori cache valid yang ditemukan pada sistem cache selama pemindaian.
incomplete_files (frozenset[CachedIncompleteFileInfo]) — Kumpulan ~CachedIncompleteFileInfo yang menjelaskan file *.incomplete yatim piatu yang ditinggalkan oleh unduhan yang terputus.
warnings (list[CorruptedCacheException]) — Daftar ~CorruptedCacheException yang terjadi saat memindai cache. Pengecualian tersebut ditangkap agar pemindaian dapat dilanjutkan. Repo yang rusak dilewati dari pemindaian.
cache_dir (Path atau None) — Direktori cache yang dipindai.

Struktur data beku yang menyimpan informasi tentang seluruh sistem cache.

Struktur data ini dikembalikan oleh scan_cache_dir() dan bersifat tidak dapat diubah.

size_on_disk hanya memperhitungkan blob, dan repositori yang rusak akan dilewati. Ini adalah ukuran fisik: berbeda dengan CachedRepoInfo.size_on_disk, yang mengaitkan blob bersama ke setiap repositori yang merujuknya, blob bersama hanya dihitung sekali di sini.

delete_files

< source >

( *files: CachedFileInfo )

Siapkan strategi untuk menghapus file cache individual.

Hanya entri snapshot yang dihapus. Blob dihapus hanya jika tidak ada file cache lain yang merujuknya, sehingga blob yang dibagikan dengan revisi lain tetap dipertahankan. Refs dan direktori snapshot juga dipertahankan, bahkan jika snapshot berakhir kosong. Untuk menghapus revisi atau repositori secara keseluruhan, gunakan delete_revisions().

Contoh:

>>> 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()

delete_revisions

< source >

( *revisions: str )

Siapkan strategi untuk menghapus satu atau lebih revisi yang di-cache secara lokal.

Revisi input dapat berupa hash revisi apa pun. Jika hash revisi tidak ditemukan di cache lokal, peringatan akan dilempar tetapi tidak ada error yang muncul. Revisi dapat berasal dari repositori cache yang berbeda karena hash bersifat unik di seluruh repositori,

Contoh:

>>> 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 mengembalikan objek DeleteCacheStrategy yang perlu dieksekusi. DeleteCacheStrategy tidak dimaksudkan untuk dimodifikasi, tetapi memungkinkan dry run sebelum eksekusi penghapusan dilakukan.

export_as_table

< source >

( verbosity: int = 0 ) → str

Parameter

verbosity (int, opsional) — Tingkat verbosity. Defaultnya 0.

Mengembalikan

str

Tabel sebagai string.

Buat tabel dari objek HFCacheInfo.

Lewati verbosity=0 untuk mendapatkan tabel dengan satu baris per repo, dengan kolom “repo_id”, “repo_type”, “size_on_disk”, “nb_files”, “last_accessed”, “last_modified”, “refs”, “local_path”.

Lewati verbosity=1 untuk mendapatkan tabel dengan satu baris per repo dan revisi (sehingga beberapa baris dapat muncul untuk satu repo), dengan kolom “repo_id”, “repo_type”, “revision”, “size_on_disk”, “nb_files”, “last_modified”, “refs”, “local_path”.

Contoh:

>>> 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/150ebc2c4b72291e770f58e6057481c8d2ed331a

CachedRepoInfo

kelas 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 )

Parameter

repo_id (str) — Repo id dari repo di Hub. Contoh: "google/fleurs".
repo_type (Literal["dataset", "model", "space", "kernel"]) — Jenis repo yang di-cache.
repo_path (Path) — Jalur lokal ke repo yang di-cache.
size_on_disk (int) — Total ukuran file blob di repo yang di-cache.
nb_files (int) — Jumlah total file blob di repo yang di-cache.
revisions (frozenset[CachedRevisionInfo]) — Kumpulan ~CachedRevisionInfo yang menjelaskan semua revisi yang di-cache di repo.
last_accessed (float) — Timestamp dari waktu terakhir file blob di repo diakses.
last_modified (float) — Timestamp dari waktu terakhir file blob di repo dimodifikasi/dibuat.

Struktur data beku yang menyimpan informasi tentang repositori yang di-cache.

size_on_disk tidak selalu merupakan jumlah dari ukuran semua revisi karena adanya file yang duplikat. Selain itu, hanya blob yang diperhitungkan, bukan ukuran (yang dapat diabaikan) dari folder dan symlink.

Keandalan last_accessed dan last_modified dapat bergantung pada OS yang Anda gunakan. Lihat dokumentasi python untuk detail lebih lanjut.

size_on_disk_str

< source >

( )

(property) Jumlah ukuran file blob sebagai string yang mudah dibaca manusia.

Contoh: “42,2K”.

rujukan

< source >

( )

(property) Pemetaan antara refs dan struktur data revisi.

CachedRevisionInfo

kelas huggingface_hub.CachedRevisionInfo

< source >

( commit_hash: strsnapshot_path: Pathsize_on_disk: intfiles: frozensetrefs: frozensetlast_modified: float )

Parameter

commit_hash (str) — Hash dari revisi (unik). Contoh: "9338f7b671827df886678df2bdd7cc7b4f36dffd".
snapshot_path (Path) — Path ke direktori revisi di folder snapshots. Berisi struktur pohon yang persis sama dengan repo di Hub.
files — (frozenset[CachedFileInfo]): Kumpulan ~CachedFileInfo yang menjelaskan semua file yang terkandung dalam snapshot.
refs (frozenset[str]) — Kumpulan refs yang menunjuk ke revisi ini. Jika revisi tidak memiliki refs, maka dianggap terputus (detached). Contoh: {"main", "2.4.0"} atau {"refs/pr/1"}.
size_on_disk (int) — Jumlah ukuran file blob yang di-simlink oleh revisi tersebut.
last_modified (float) — Timestamp dari waktu terakhir revisi dibuat/diubah.

Struktur data beku yang menyimpan informasi tentang revisi.

Revisi berkorespondensi dengan folder di folder snapshots dan diisi dengan struktur pohon yang persis sama dengan repo di Hub, tetapi hanya berisi symlink. Sebuah revisi dapat dirujuk oleh 1 atau lebih refs atau berada dalam keadaan “detached” (tanpa refs).

last_accessed tidak dapat ditentukan dengan benar pada satu revisi karena file blob dibagikan di antara revisi.

size_on_disk tidak selalu sama dengan jumlah total ukuran semua file karena kemungkinan adanya file duplikat. Selain itu, hanya blob yang diperhitungkan, bukan ukuran (yang dapat diabaikan) dari folder dan symlink.

size_on_disk_str

< source >

( )

(property) Jumlah ukuran file blob sebagai string yang mudah dibaca manusia.

Contoh: “42,2K”.

nb_files

< source >

( )

(property) Total jumlah file dalam revisi.

CachedFileInfo

kelas huggingface_hub.CachedFileInfo

< source >

( file_name: strfile_path: Pathblob_path: Pathsize_on_disk: intblob_last_accessed: floatblob_last_modified: float )

Parameter

file_name (str) — Nama file. Contoh: config.json.
file_path (Path) — Lokasi file di direktori snapshots. Lokasi file ini adalah symlink yang merujuk ke blob di folder blobs.
blob_path (Path) — Path dari entri blob lokal repo yang dirujuk oleh file_path. Entri blob ini sendiri dapat berupa symlink ke blob store bersama yang mencakup seluruh cache.
size_on_disk (int) — Ukuran file blob dalam byte.
blob_last_accessed (float) — Timestamp dari waktu terakhir file blob diakses (dari revisi apa pun).
blob_last_modified (float) — Timestamp dari waktu terakhir file blob dimodifikasi/dibuat.

Struktur data beku yang menyimpan informasi tentang satu file cache.

Keandalan blob_last_accessed dan blob_last_modified dapat bergantung pada OS yang Anda gunakan. Lihat dokumentasi python untuk detail lebih lanjut.

size_on_disk_str

< source >

( )

(property) Ukuran file blob sebagai string yang dapat dibaca manusia.

Contoh: “42,2K”.

CachedIncompleteFileInfo

kelas huggingface_hub.CachedIncompleteFileInfo

< source >

( file_path: Pathsize_on_disk: int )

Parameter

file_path (Path) — Path file .incomplete di folder blobs.
size_on_disk (int) — Ukuran file yang sedang diunduh sebagian dalam byte.

Struktur data beku yang menyimpan informasi tentang satu unduhan yang belum selesai.

Unduhan yang terputus meninggalkan berkas <cache>/<repo>/blobs/<etag>.incomplete. Berkas ini bukan bagian dari revisi yang dikomit, sehingga ditampilkan secara terpisah oleh scan_cache_dir().

DeleteCacheStrategy

kelas huggingface_hub.DeleteCacheStrategy

< source >

( expected_freed_size: intblobs: frozensetrefs: frozensetrepos: frozensetsnapshots: frozensetfiles: frozenset = frozenset()cache_dir: pathlib.Path | None = None )

Parameter

expected_freed_size (float) — Ukuran bebas yang diharapkan setelah strategi dieksekusi.
blobs (frozenset[Path]) — Kumpulan jalur file blob yang akan dihapus.
refs (frozenset[Path]) — Set dari path file referensi yang akan dihapus.
repos (frozenset[Path]) — Set dari seluruh path repo yang akan dihapus.
snapshots (frozenset[Path]) — Kumpulan snapshot yang akan dihapus (direktori symlink).
files (frozenset[Path], opsional) — Kumpulan entri snapshot individual yang akan dihapus. Blob mereka hanya dihapus jika tercantum dalam blobs.
cache_dir (Path atau None) — Direktori cache tempat strategi tersebut dihitung. Digunakan untuk mengumpulkan blob bersama yang dirujuk oleh symlink lokal repo yang dihapus oleh penghapusan tersebut.

Struktur data beku yang menyimpan strategi untuk menghapus revisi atau file yang di-cache.

Objek ini tidak dimaksudkan untuk diinstansiasi secara programatis, melainkan untuk dikembalikan oleh delete_revisions() atau delete_files(). Lihat dokumentasi untuk contoh penggunaan.

expected_freed_size_str

< source >

( )

(property) Ukuran yang diharapkan akan dibebaskan sebagai string yang dapat dibaca manusia.

Contoh: “42,2K”.

Pengecualian

CorruptedCacheException

kelas huggingface_hub.CorruptedCacheException

< source >

( )

Pengecualian untuk struktur tak terduga apa pun dalam sistem cache Huggingface.

Update on GitHub

Hub Python Library

Referensi sistem cache

Helper

try_to_load_from_cache

huggingface_hub.try_to_load_from_cache

cached_assets_path

huggingface_hub.cached_assets_path

scan_cache_dir

huggingface_hub.scan_cache_dir

Struktur data

HFCacheInfo

kelas huggingface_hub.HFCacheInfo

delete_files

delete_revisions

export_as_table

CachedRepoInfo

kelas huggingface_hub.CachedRepoInfo

size_on_disk_str

rujukan

CachedRevisionInfo

kelas huggingface_hub.CachedRevisionInfo

size_on_disk_str

nb_files

CachedFileInfo

kelas huggingface_hub.CachedFileInfo

size_on_disk_str

CachedIncompleteFileInfo

kelas huggingface_hub.CachedIncompleteFileInfo

DeleteCacheStrategy

kelas huggingface_hub.DeleteCacheStrategy

expected_freed_size_str

Pengecualian

CorruptedCacheException

kelas huggingface_hub.CorruptedCacheException