Hub Python Library documentation

캐시 시스템 참조

Hub Python Library

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v2.4.0).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

캐시 시스템 참조

캐싱 시스템은 v0.8.0에서 업데이트되어 Hub에 의존하는 라이브러리 간에 공유되는 중앙 캐싱 시스템이 되었습니다. HF의 캐싱에 대한 자세한 내용은 cache-system 가이드를 참고하세요.

헬퍼

try_to_load_from_cache

huggingface_hub.try_to_load_from_cache

( 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는 주어진 커밋 해시에서 파일이 존재하지 않는다는 사실이 캐시된 경우의 특수 값입니다.

Explores the cache to return the latest cached file for a given revision if found.

…

예:

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

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

매개변수

library_name (str) — 캐시 폴더를 관리할 라이브러리의 이름입니다. 예: "dataset".
namespace (str, 선택 사항, 기본값 “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

( cache_dir: str | pathlib.Path | None = None )

매개변수

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

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 캐시 디렉터리가 디렉터리가 아닌 파일인 경우.

Returns: ~HFCacheInfo 객체를 반환합니다.

데이터 구조

모든 구조는 scan_cache_dir()에 의해 생성되고 반환되며 불변입니다.

HFCacheInfo

class huggingface_hub.HFCacheInfo

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

매개변수

size_on_disk (int) — 캐시 시스템의 물리적 크기(바이트 단위). 저장소 간에 공유되는 blob은 한 번만 계산되며, 더 이상 어떤 저장소에서도 참조되지 않는 store-only 공유 blob도 포함됩니다. 저장소별 크기의 합보다 작을 수 있습니다.
repos (frozenset[CachedRepoInfo]) — 캐시 시스템에서 스캔하는 동안 발견된 모든 유효한 캐시된 저장소를 설명하는 ~CachedRepoInfo의 집합.
incomplete_files (frozenset[CachedIncompleteFileInfo]) — 중단된 다운로드에 의해 남겨진 고아 *.incomplete 파일들을 설명하는 ~CachedIncompleteFileInfo의 집합
warnings (list[CorruptedCacheException]) — 캐시를 스캔하는 동안 발생한 ~CorruptedCacheException 목록입니다. 해당 예외는 스캔이 계속 진행될 수 있도록 캡처됩니다. 손상된 저장소는 스캔에서 건너뜁니다.
cache_dir (Path 또는 None) — 스캔된 캐시 디렉터리입니다.

전체 캐시 시스템에 대한 정보를 포함하는 동결 데이터 구조입니다.

이 데이터 구조는 scan_cache_dir()에 의해 반환되며 변경 불가능합니다.

size_on_disk은 blob만 계산하며, 손상된 저장소는 건너뜁니다. 이는 물리적 크기입니다. 공유 blob을 참조하는 모든 저장소에 해당 blob을 할당하는 CachedRepoInfo.size_on_disk와 달리, 여기서는 공유 blob이 한 번만 계산됩니다.

delete_files

( *files: CachedFileInfo )

개별 캐시 파일을 삭제하기 위한 전략을 준비합니다.

스냅샷 항목만 삭제됩니다. 다른 캐시된 파일이 해당 blob을 참조하지 않는 경우에만 blob이 삭제되므로, 다른 리비전과 공유되는 blob은 유지됩니다. 스냅샷이 비어 있게 되더라도 Refs와 스냅샷 디렉터리는 유지됩니다. 리비전이나 리포지토리를 전체적으로 삭제하려면 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()

delete_revisions

( *revisions: str )

로컬에 캐시된 하나 이상의 리비전을 삭제하기 위한 전략을 준비합니다.

입력 revision은 어떤 revision 해시든 될 수 있습니다. 로컬 캐시에서 revision 해시를 찾지 못하면 경고가 발생하지만 오류는 발생하지 않습니다. 해시는 저장소 간에 고유하므로, revision은 서로 다른 캐시된 저장소에서 가져온 것일 수 있습니다.

예:

>>> 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는 수정하도록 설계되지 않았지만, 실제 삭제를 실행하기 전에 dry run을 수행할 수 있습니다.

export_as_table

( verbosity: int = 0 ) → str

매개변수

verbosity (int, 선택 사항) — 세부 정보 수준입니다. 기본값은 0입니다.

반환값

str

문자열 형태의 테이블.

HFCacheInfo 객체에서 테이블을 생성합니다.

verbosity=0를 전달하면 “repo_id”, “repo_type”, “size_on_disk”, “nb_files”, “last_accessed”, “last_modified”, “refs”, “local_path” 열을 가진 레포당 한 줄씩의 테이블을 얻을 수 있습니다.

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

CachedRepoInfo

클래스 huggingface_hub.CachedRepoInfo

( 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) — 캐시된 저장소의 blob 파일 크기 합계.
nb_files (int) — 캐시된 저장소의 blob 파일 총 개수.
revisions (frozenset[CachedRevisionInfo]) — 리포지토리에 캐시된 모든 리비전을 설명하는 ~CachedRevisionInfo의 집합입니다.
last_accessed (float) — 리포지토리의 blob 파일이 마지막으로 액세스된 시각의 타임스탬프입니다.
last_modified (float) — 리포지토리의 blob 파일이 마지막으로 수정/생성된 시각의 타임스탬프입니다.

캐시된 저장소에 대한 정보를 포함하는 불변 데이터 구조입니다.

size_on_disk은 중복된 파일이 존재하기 때문에 모든 리비전의 크기의 합과 반드시 같지 않습니다. 또한, 폴더와 심볼릭 링크의 (무시할 수 있는) 크기는 계산에 포함되지 않고 블롭만 고려됩니다.

last_accessed와 last_modified의 신뢰성은 사용하는 OS에 따라 달라질 수 있습니다. 자세한 내용은 python 문서를 참고하세요.

size_on_disk_str

( )

(property) blob 파일 크기의 합을 사람이 읽기 쉬운 문자열로 나타낸 값.

예: “42.2K”.

참조

( )

refs와 리비전 데이터 구조 간의 매핑을 나타내는 속성입니다.

CachedRevisionInfo

클래스 huggingface_hub.CachedRevisionInfo

( 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가 없으면 detached 상태로 간주됩니다. 예: {"main", "2.4.0"} 또는 {"refs/pr/1"}.
size_on_disk (int) — 해당 리비전이 심볼릭 링크로 연결하는 블롭 파일 크기의 합계입니다.
last_modified (float) — 해당 리비전이 마지막으로 생성/수정된 시각의 타임스탬프입니다.

리비전에 대한 정보를 포함하는 불변 데이터 구조입니다.

수정은 snapshots 폴더 안의 폴더에 해당하며, Hub의 저장소와 동일한 트리 구조를 가지지만 심볼릭 링크만 포함합니다. 수정은 하나 이상의 refs에 의해 참조되거나, “detached”(refs 없음) 상태일 수 있습니다.

last_accessed는 blob 파일이 여러 리비전 간에 공유되므로 단일 리비전에서는 정확하게 결정할 수 없습니다.

size_on_disk은 중복된 파일이 존재할 수 있으므로 모든 파일 크기의 합과 반드시 같지 않습니다. 또한, 폴더와 심볼릭 링크의 (무시할 수 있는) 크기는 계산에 포함되지 않고 blob만 고려됩니다.

size_on_disk_str

( )

(property) blob 파일 크기의 합을 사람이 읽기 쉬운 문자열로 나타낸 값.

예: “42.2K”.

nb_files

( )

(property) 리비전의 총 파일 수.

CachedFileInfo

class huggingface_hub.CachedFileInfo

( 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을 가리키는 심볼릭 링크입니다.
blob_path (Path) — file_path가 참조하는 저장소 로컬 blob 항목의 경로입니다. blob 항목은 캐시 전체의 공유 blob 스토어로 향하는 심볼릭 링크일 수도 있습니다.
size_on_disk (int) — 바이트 단위의 blob 파일 크기.
blob_last_accessed (float) — Blob 파일이 마지막으로 접근된 시각(모든 리비전 기준).
blob_last_modified (float) — Blob 파일이 마지막으로 수정/생성된 시각입니다.

단일 캐시 파일에 대한 정보를 포함하는 불변 데이터 구조입니다.

blob_last_accessed 및 blob_last_modified의 신뢰성은 사용하는 OS에 따라 달라질 수 있습니다. 자세한 내용은 python 문서를 참조하세요.

size_on_disk_str

( )

(property) blob 파일 크기를 사람이 읽기 쉬운 문자열로 나타냅니다.

예: “42.2K”.

CachedIncompleteFileInfo

class huggingface_hub.CachedIncompleteFileInfo

( file_path: Pathsize_on_disk: int )

매개변수

file_path (Path) — blobs 폴더 내 .incomplete 파일의 경로.
size_on_disk (int) — 부분적으로 다운로드된 파일의 바이트 단위 크기.

…

중단된 다운로드에서는 <cache>/<repo>/blobs/<etag>.incomplete 파일이 남습니다. 이 파일들은 커밋된 어떤 리비전에도 속하지 않으므로 scan_cache_dir()에 의해 별도로 표시됩니다.

DeleteCacheStrategy

class huggingface_hub.DeleteCacheStrategy

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

매개변수

expected_freed_size (float) — 전략이 실행된 후 예상되는 해제 크기.
blobs (frozenset[Path]) — 삭제할 blob 파일 경로 집합.
refs (frozenset[Path]) — 삭제할 참조 파일 경로 집합.
repos (frozenset[Path]) — 삭제할 전체 저장소 경로 집합.
snapshots (frozenset[Path]) — 삭제할 스냅샷의 집합(심볼릭 링크 디렉터리).
files (frozenset[Path], 선택 사항) — 삭제할 개별 스냅샷 항목의 집합. blobs에 나열된 경우에만 해당 항목의 blob이 삭제됩니다.
cache_dir (Path 또는 None) — 전략이 계산된 캐시 디렉터리입니다. 삭제 과정에서 제거된 리포지토리 로컬 심볼릭 링크가 참조하는 공유 블롭을 수집하는 데 사용됩니다.

캐시된 리비전 또는 파일을 삭제하는 전략을 담고 있는 동결 데이터 구조입니다.

이 객체는 프로그래밍 방식으로 인스턴스화하도록 설계된 것이 아니라 delete_revisions() 또는 delete_files()에 의해 반환되도록 설계되었습니다. 사용 예제는 문서를 참조하세요.

expected_freed_size_str

( )

(property) 사람이 읽을 수 있는 문자열로 표시되는 해제될 예상 크기입니다.

예: “42.2K”.

예외

CorruptedCacheException

class huggingface_hub.CorruptedCacheException

( )

Huggingface 캐시 시스템에서 예상치 못한 구조에 대한 예외.

Update on GitHub

←토론 및 Pull Request Repo Cards 및 Repo Card 데이터→