Hub Python Library documentation
キャッシュシステムのリファレンス
キャッシュシステムのリファレンス
キャッシュシステムガイドでは、HFにおけるキャッシュの詳細な説明が記載されています。v0.8.0でキャッシュシステムが更新され、Hubに依存するライブラリ全体で共有される中央キャッシュシステムとなりました。
ヘルパー
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
パラメータ
- cache_dir (
strまたはos.PathLike) — キャッシュされたファイルが保存されているフォルダ。 - repo_id (
str) — huggingface.co 上のリポジトリの ID。 - filename (
str) —repo_id内で検索するファイル名です。 - revision (
str, 省略可) — 使用する特定のモデルのバージョンです。指定されず、commit_hashも指定されていない場合は、"main"がデフォルトとして使用されます。 - repo_type (
str、省略可) — リポジトリの種類です。デフォルトは"model"です。
戻り値
Optional[str] または _CACHED_NO_EXIST
ファイルがキャッシュされていなかった場合はNoneを返します。それ以外の場合は:
- キャッシュ内で見つかった場合の、キャッシュされたファイルの正確なパス
- 指定されたコミットハッシュでファイルが存在せず、その事実がキャッシュされている場合の特別な値
_CACHED_NO_EXIST。
与えられたリビジョンの最新のカッシュ済みファイルを、見つかった場合、カッシュを探索して返します。
この関数は、ファイルがキャッシュされていない場合でも、例外を発生させません。
cached_assets_path
huggingface_hub.cached_assets_path
< source >( library_name: strnamespace: str = 'default'subfolder: str = 'default'assets_dir: str | pathlib.Path | None = None )
パラメータ
- library_name (
str) — キャッシュフォルダを管理するライブラリの名前。例:"dataset"。 - namespace (
str, optional, デフォルト値は “default”) — データが属する名前空間です。例:"SQuAD"。 - subfolder (
str、任意、デフォルトは “default”) — データを保存するサブフォルダーです。例:extracted。 - assets_dir (
str,Path, 省略可) — アセットがキャッシュされるフォルダへのパスです。これは、Hub ファイルがキャッシュされるフォルダと同じであってはなりません。指定されない場合、デフォルトでHF_HOME / "assets"が使用されます。HF_ASSETS_CACHE環境変数でも設定できます。
任意のファイルをキャッシュするためのフォルダパスを返します。
huggingface_hub は、アセットを保存するための正規のフォルダパスを提供します。これは、キャッシュをスキャンして適切に削除する組み込みツールを利用できるため、下流のライブラリにキャッシュを統合する際の推奨方法です。
Hubからキャッシュされたファイルとアセットの区別がなされています。Hubからのファイルはgitを考慮した方法でキャッシュされ、huggingface_hubによって完全に管理されます。関連ドキュメントを参照してください。下流のライブラリがキャッシュするその他のすべてのファイルは「アセット」（外部ソースからダウンロードされたファイル、.tarアーカイブから展開されたファイル、トレーニング用に前処理されたファイルなど）とみなされます。
フォルダパスが生成されると、そのパスが存在し、ディレクトリであることが保証されます。
パスは3つの階層で構成されます: ライブラリ名、名前空間、サブフォルダです。これら3つの階層により、柔軟性を確保しつつ、huggingface_hubがアセットキャッシュの一部をスキャン/削除する際にフォルダを想定できるようになります。ライブラリ内では、すべての名前空間が同じサブフォルダ名のサブセットを共有することが期待されますが、これは必須のルールではありません。したがって、下流のライブラリは、そのキャッシュ内で採用するファイル構造を完全に制御できます。名前空間とサブフォルダは任意です(デフォルトでは"default/"サブフォルダになります)が、すべての下流ライブラリが独自のキャッシュを管理できるようにするため、ライブラリ名は必須です。
期待されるツリー:
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/
└── (...)例:
>>> 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 )
HFキャッシュシステム全体をスキャンし、~HFCacheInfo構造を返します。
scan_cache_dir を使用して、キャッシュシステムをプログラム的にスキャンできます。スキャンはリポジトリ単位で実行されます。リポジトリが破損している場合、~CorruptedCacheException が内部でスローされますが、捕捉されて ~HFCacheInfo 構造体として返されます。適切なレポートは、有効なリポジトリに対してのみ生成されます。
>>> 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(...),
...
],
)hf コマンドラインから、次のコマンドを使用して詳細なレポートを直接出力することもできます。
> 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.
例外:
CacheNotFoundキャッシュディレクトリが存在しない場合。
ValueErrorキャッシュディレクトリがディレクトリではなくファイルの場合。
戻り値: ~HFCacheInfoオブジェクト。
データ構造
すべての構造はscan_cache_dir()によって構築され、返されます。また、これらは不変です。
HFCacheInfo
クラス huggingface_hub.HFCacheInfo
< source >( size_on_disk: intrepos: frozensetincomplete_files: frozensetwarnings: listcache_dir: pathlib.Path | None = None )
パラメータ
- size_on_disk (
int) — キャッシュシステムの物理サイズ（バイト単位）です。リポジトリ間で共有されているブロブは1回のみカウントされ、どのリポジトリからも参照されなくなったストア専用の共有ブロブも含まれます。リポジトリごとのサイズの合計よりも小さくなる場合があります。 - repos (
frozenset[CachedRepoInfo]) — スキャン中にキャッシュシステム上で見つかったすべての有効なキャッシュリポジトリを説明する~CachedRepoInfoの集合。 - incomplete_files (
frozenset[CachedIncompleteFileInfo]) — 中断されたダウンロードによって残された孤立した*.incompleteファイルを説明する~CachedIncompleteFileInfoの集合。 - warnings (
list[CorruptedCacheException]) — キャッシュをスキャン中に発生した~CorruptedCacheExceptionのリストです。 スキャンを継続できるように、これらの例外は捕捉されます。破損したリポジトリはスキャンからスキップされます。 - cache_dir (
PathまたはNone) — スキャンされたキャッシュディレクトリ。
キャッシュシステム全体に関する情報を保持する不変のデータ構造。
このデータ構造はscan_cache_dir()によって返され、不変です。
size_on_diskはブロブのみを計算対象とし、破損したリポジトリはスキップされます。これは物理サイズであり、共有ブロブを参照しているすべてのリポジトリにそのブロブを帰属させるCachedRepoInfo.size_on_diskとは異なり、ここでは共有ブロブは1回のみカウントされます。
個々のキャッシュファイルを削除する戦略を準備します。
スナップショットのエントリのみが削除されます。ブロブは、他のキャッシュされたファイルが参照していない場合のみ削除されるため、他のリビジョンと共有されているブロブは保持されます。また、スナップショットが空になった場合でも、リファレンスおよびスナップショットディレクトリは保持されます。リビジョン全体やリポジトリを削除するには、delete_revisions()を使用してください。
例:
>>> 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()ローカルにキャッシュされた1つ以上のリビジョンを削除する戦略を準備します。
入力リビジョンは、任意のリビジョンハッシュを指定できます。リビジョンハッシュがローカルキャッシュに見つからない場合、警告は出力されますが、エラーは発生しません。ハッシュはリポジトリ間で一意であるため、リビジョンは異なるキャッシュ済みリポジトリからのものであっても構いません。
例:
>>> 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は実行する必要がある DeleteCacheStrategy オブジェクトを返します。DeleteCacheStrategy は変更することを意図していませんが、実際の削除を実行する前にドライランを行うことを許可します。
export_as_table
< source >( verbosity: int = 0 ) → str
HFCacheInfoオブジェクトからテーブルを生成します。
verbosity=0 を渡すと、リポジトリごとに1行の表が返され、列には “repo_id”、“repo_type”、“size_on_disk”、“nb_files”、“last_accessed”、“last_modified”、“refs”、“local_path” が含まれます。
verbosity=1 を渡すと、リポジトリとリビジョンごとに1行ずつ（1つのリポジトリに対して複数の行が表示されることがあります）の表が返され、列には “repo_id”、“repo_type”、“revision”、“size_on_disk”、“nb_files”、“last_modified”、“refs”、“local_path” が含まれます。
例:
>>> 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
クラス 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 )
パラメータ
- repo_id (
str) — Hub 上のリポジトリのリポジトリ ID。例:"google/fleurs"。 - repo_type (
Literal["dataset", "model", "space", "kernel"]) — キャッシュされたリポジトリの種類。 - repo_path (
Path) — キャッシュされたリポジトリのローカルパス。 - size_on_disk (
int) — キャッシュされたリポジトリ内のブロブファイルサイズの合計。 - nb_files (
int) — キャッシュされたリポジトリ内のブロブファイルの総数。 - revisions (
frozenset[CachedRevisionInfo]) — リポジトリにキャッシュされているすべてのリビジョンを説明する~CachedRevisionInfoのセット。 - last_accessed (
float) — リポジトリのブロブファイルが最後にアクセスされた時刻のタイムスタンプ。 - last_modified (
float) — リポジトリのブロブファイルが最後に修正/作成されたタイムスタンプ。
キャッシュされたリポジトリに関する情報を保持する不変データ構造。
size_on_diskは、重複するファイルが存在するため、すべてのリビジョンのサイズの合計とは限りません。また、フォルダやシンボリックリンクの（無視できるほど小さい）サイズではなく、ブロブのみが考慮されます。
last_accessedおよびlast_modifiedの信頼性は、使用している OS に依存する場合があります。 詳細については、python のドキュメントを参照してください。
refsとリビジョンデータ構造の間のマッピング。
CachedRevisionInfo
クラス huggingface_hub.CachedRevisionInfo
< source >( commit_hash: strsnapshot_path: Pathsize_on_disk: intfiles: frozensetrefs: frozensetlast_modified: float )
パラメータ
- commit_hash (
str) — リビジョンのハッシュ（一意）。 例:"9338f7b671827df886678df2bdd7cc7b4f36dffd"。 - snapshot_path (
Path) —snapshotsフォルダ内のリビジョンディレクトリへのパスです。Hub上のリポジトリと完全に同じツリー構造が含まれています。 - files — (
frozenset[CachedFileInfo]): スナップショットに含まれるすべてのファイルを記述する~CachedFileInfoの集合。 - refs (
frozenset[str]) — このリビジョンを指すrefsの集合です。リビジョンにrefsが存在しない場合、デタッチ状態とみなされます。 例:{"main", "2.4.0"}または{"refs/pr/1"}。 - size_on_disk (
int) — リビジョンがシンボリックリンクで参照しているブロブファイルサイズの合計。 - last_modified (
float) — リビジョンが最後に作成/変更された時刻のタイムスタンプ。
リビジョンに関する情報を保持する不変データ構造。
リビジョンはsnapshotsフォルダ内のフォルダに対応し、Hub上のリポジトリと完全に同じツリー構造を持ちますが、シンボリックリンクのみが含まれます。リビジョンは1つ以上のrefsによって参照されるか、「detached」（refsなし）のいずれかになります。
last_accessedは、blob ファイルがリビジョン間で共有されるため、単一のリビジョンでは正しく判定できません。
size_on_diskは、重複するファイルが存在する可能性があるため、必ずしもすべてのファイルサイズの合計とはなりません。また、考慮されるのは blob のみであり、フォルダやシンボリックリンクの（無視できるほど小さい）サイズは含まれません。
(property) リビジョン内のファイルの総数。
CachedFileInfo
クラス huggingface_hub.CachedFileInfo
< source >( file_name: strfile_path: Pathblob_path: Pathsize_on_disk: intblob_last_accessed: floatblob_last_modified: float )
パラメータ
- file_name (
str) — ファイル名。例:config.json。 - file_path (
Path) —snapshotsディレクトリ内のファイルのパスです。ファイルパスは、blobsフォルダー内のブロブを参照するシンボリックリンクです。 - blob_path (
Path) —file_pathが参照しているリポジトリローカルの blob エントリのパスです。この blob エントリ自体は、キャッシュ全体で共有される blob ストアへのシンボリックリンクである場合があります。 - size_on_disk (
int) — バイト単位のブロブファイルのサイズ。 - blob_last_accessed (
float) — blob ファイルが最後にアクセスされたタイムスタンプ（どのリビジョンからでも）。 - blob_last_modified (
float) — blob ファイルが最後に修正/作成された時刻のタイムスタンプ。
単一のキャッシュファイルに関する情報を保持する不変データ構造。
blob_last_accessedおよびblob_last_modifiedの信頼性は、使用している OS に依存する場合があります。詳細については、python のドキュメントを参照してください。
CachedIncompleteFileInfo
クラス huggingface_hub.CachedIncompleteFileInfo
< source >( file_path: Pathsize_on_disk: int )
単一の不完全なダウンロードに関する情報を保持する不変データ構造。
中断されたダウンロードは、<cache>/<repo>/blobs/<etag>.incomplete ファイルを残します。
これらはコミットされたリビジョンの一部ではないため、scan_cache_dir() によって別に表示されます。
DeleteCacheStrategy
クラス huggingface_hub.DeleteCacheStrategy
< source >( expected_freed_size: intblobs: frozensetrefs: frozensetrepos: frozensetsnapshots: frozensetfiles: frozenset = frozenset()cache_dir: pathlib.Path | None = None )
パラメータ
- expected_freed_size (
float) — 戦略が実行された後に解放される予期されるサイズ。 - blobs (
frozenset[Path]) — 削除対象のブロブファイルパスのセット。 - refs (
frozenset[Path]) — 削除対象の参照ファイルパスのセットです。 - repos (
frozenset[Path]) — 削除対象のレポジトリ全体のパスのセット。 - snapshots (
frozenset[Path]) — 削除対象のスナップショットのセット（シンボリックリンクのディレクトリ）。 - files (
frozenset[Path]、省略可) — 削除対象のスナップショットエントリの集合です。これらのblobは、blobsに列挙されている場合のみ削除されます。 - cache_dir (
PathまたはNone) — この戦略が計算されたキャッシュディレクトリ。削除によって除去されたリポジトリローカルのシンボリックリンクが参照している共有ブロブを収集するために使用されます。
キャッシュされたリビジョンまたはファイルを削除する戦略を保持する凍結されたデータ構造。
このオブジェクトはプログラムによってインスタンス化することを意図したものではありません。delete_revisions()またはdelete_files()によって返されるものです。使用例についてはドキュメントを参照してください。
例外
CorruptedCacheException
Huggingfaceのキャッシュシステムにおける予期しない構造に対する例外。