Referência do sistema de cache

O sistema de cache foi atualizado na v0.8.0 para se tornar o sistema de cache central compartilhado entre as bibliotecas que dependem do Hub. Leia o guia do sistema de cache para uma apresentação detalhada do cache no HF.

Auxiliares

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

Parâmetros

cache_dir (str ou os.PathLike) — A pasta onde os arquivos em cache estão localizados.
repo_id (str) — O ID do repositório no huggingface.co.
filename (str) — O nome do arquivo a ser procurado dentro de repo_id.
revision (str, opcional) — A versão específica do modelo a ser usada. O padrão será "main" se não for fornecida e nenhum commit_hash for fornecido também.
repo_type (str, opcional) — O tipo do repositório. O padrão é "model".

Retorna

Optional[str] ou _CACHED_NO_EXIST

Retornará None se o arquivo não estiver em cache. Caso contrário:

O caminho exato para o arquivo em cache, caso ele seja encontrado no cache
Um valor especial _CACHED_NO_EXIST se o arquivo não existir no hash de commit fornecido e esse fato tiver sido cacheado.

Explora o cache para retornar o arquivo em cache mais recente para uma revisão específica, se encontrado.

Esta função não lançará nenhuma exceção se o arquivo não estiver em cache.

Exemplo:

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 )

Parâmetros

library_name (str) — Nome da biblioteca que gerenciará a pasta de cache. Exemplo: "dataset".
namespace (str, opcional, padrão “default”) — Namespace ao qual os dados pertencem. Exemplo: "SQuAD".
subfolder (str, opcional, padrão “default”) — Subpasta na qual os dados serão armazenados. Exemplo: extracted.
assets_dir (str, Path, opcional) — Caminho para a pasta onde os assets são armazenados em cache. Este não deve ser a mesma pasta onde os arquivos do Hub são armazenados em cache. O padrão é HF_HOME / "assets" se não for fornecido. Também pode ser definido com a variável de ambiente HF_ASSETS_CACHE.

Retorna um caminho de pasta para armazenar em cache arquivos arbitrários.

huggingface_hub fornece um caminho de pasta canônico para armazenar ativos. Esta é a maneira recomendada de integrar o cache em uma biblioteca downstream, pois ela se beneficiará das ferramentas nativas para varrer e excluir o cache corretamente.

A distinção é feita entre arquivos em cache do Hub e ativos. Os arquivos do Hub são armazenados em cache de forma consciente do git e gerenciados inteiramente por huggingface_hub. Consulte a documentação relacionada. Todos os outros arquivos que uma biblioteca de nível inferior armazena em cache são considerados “ativos” (arquivos baixados de fontes externas, extraídos de um arquivo .tar, pré-processados para treinamento, …).

Uma vez que o caminho da pasta é gerado, é garantido que ele exista e que seja um diretório. O caminho é baseado em 3 níveis de profundidade: o nome da biblioteca, um namespace e uma subpasta. Esses 3 níveis concedem flexibilidade, ao mesmo tempo em que permitem que o huggingface_hub espere encontrar pastas ao varrer/excluir partes do cache de assets. Dentro de uma biblioteca, espera-se que todos os namespaces compartilhem o mesmo subconjunto de nomes de subpastas, mas isso não é uma regra obrigatória. A biblioteca de nível inferior tem, portanto, controle total sobre qual estrutura de arquivos adotar dentro do seu cache. Namespace e subpasta são opcionais (teriam como padrão uma subpasta "default/"), mas o nome da biblioteca é obrigatório, pois queremos que cada biblioteca de nível inferior gerencie o próprio cache.

Árvore esperada:

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

Exemplo:

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

Parâmetros

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

Varra todo o sistema de cache do HF e retorne uma estrutura ~HFCacheInfo.

Use scan_cache_dir para escanear seu sistema de cache de forma programática. O cache será escaneado repositório por repositório. Se um repositório estiver corrompido, uma ~CorruptedCacheException será lançada internamente, mas capturada e retornada na estrutura ~HFCacheInfo. Apenas repositórios válidos recebem um relatório adequado.

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

Você também pode imprimir um relatório detalhado diretamente da linha de comando hf usando:

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

Exceções:

CacheNotFound Se o diretório de cache não existir.

ValueError Se o diretório de cache for um arquivo, em vez de um diretório.

Retorna: um objeto ~HFCacheInfo.

Estruturas de dados

Todas as estruturas são construídas e retornadas por scan_cache_dir() e são imutáveis.

HFCacheInfo

classe huggingface_hub.HFCacheInfo

< source >

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

Parâmetros

size_on_disk (int) — Tamanho físico do sistema de cache em bytes. Um blob compartilhado entre repositórios é contado uma única vez, e blobs compartilhados apenas no armazenamento que não são mais referenciados por nenhum repositório são incluídos. Pode ser menor que a soma dos tamanhos por repositório.
repos (frozenset[CachedRepoInfo]) — Conjunto de ~CachedRepoInfo descrevendo todos os repositórios em cache válidos encontrados no sistema de cache durante a varredura.
incomplete_files (frozenset[CachedIncompleteFileInfo]) — Conjunto de ~CachedIncompleteFileInfo descrevendo arquivos órfãos *.incomplete deixados para trás por downloads interrompidos.
warnings (list[CorruptedCacheException]) — Lista de ~CorruptedCacheException que ocorreram durante a varredura do cache. Essas exceções são capturadas para que a varredura possa continuar. Repositórios corrompidos são ignorados na varredura.
cache_dir (Path ou None) — Diretório de cache que foi verificado.

Estrutura de dados imutável que armazena informações sobre todo o sistema de cache.

Esta estrutura de dados é retornada por scan_cache_dir() e é imutável.

size_on_disk considera apenas blobs e repositórios corrompidos são ignorados. Trata-se de um tamanho físico: diferentemente de CachedRepoInfo.size_on_disk, que atribui um blob compartilhado a todos os repositórios que o referenciam, um blob compartilhado é contado apenas uma vez aqui.

delete_files

< source >

( *files: CachedFileInfo )

Prepare a estratégia para excluir arquivos em cache individuais.

Apenas as entradas de snapshot são removidas. Um blob é excluído somente se nenhum outro arquivo em cache o referenciar, de modo que blobs compartilhados com outras revisões são mantidos. As refs e os diretórios de snapshot também são mantidos, mesmo que um snapshot acabe ficando vazio. Para excluir revisões ou repositórios inteiros, use delete_revisions().

Exemplo:

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

Prepare a estratégia para excluir uma ou mais revisões em cache localmente.

As revisões de entrada podem ser qualquer hash de revisão. Se um hash de revisão não for encontrado no cache local, um aviso é emitido, mas nenhum erro é lançado. As revisões podem ser de repositórios em cache diferentes, pois os hashes são únicos entre repositórios,

Exemplos:

>>> 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 retorna um objeto DeleteCacheStrategy que precisa ser executado. O DeleteCacheStrategy não deve ser modificado, mas permite realizar uma simulação antes de executar a exclusão de fato.

export_as_table

< source >

( verbosity: int = 0 ) → str

Parâmetros

verbosity (int, opcional) — O nível de verbosidade. O padrão é 0.

Retorna

str

A tabela como uma string.

Gere uma tabela a partir do objeto HFCacheInfo.

Pass verbosity=0 para obter uma tabela com uma linha por repositório, com as colunas “repo_id”, “repo_type”, “size_on_disk”, “nb_files”, “last_accessed”, “last_modified”, “refs”, “local_path”.

Pass verbosity=1 para obter uma tabela com uma linha por repositório e revisão (assim, várias linhas podem aparecer para um único repositório), com as colunas “repo_id”, “repo_type”, “revision”, “size_on_disk”, “nb_files”, “last_modified”, “refs”, “local_path”.

Exemplo:

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

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

Parâmetros

repo_id (str) — ID do repositório no Hub. Exemplo: "google/fleurs".
repo_type (Literal["dataset", "model", "space", "kernel"]) — Tipo do repositório em cache.
repo_path (Path) — Caminho local para o repositório em cache.
size_on_disk (int) — Soma dos tamanhos dos arquivos de blob no repositório em cache.
nb_files (int) — Número total de arquivos blob no repositório em cache.
revisions (frozenset[CachedRevisionInfo]) — Conjunto de ~CachedRevisionInfo descrevendo todas as revisões em cache no repositório.
last_accessed (float) — Carimbo de data/hora da última vez que um arquivo blob do repositório foi acessado.
last_modified (float) — Carimbo de data/hora da última vez que um arquivo blob do repositório foi modificado/criado.

Estrutura de dados imutável que armazena informações sobre um repositório em cache.

size_on_disk não é necessariamente a soma dos tamanhos de todas as revisões devido a arquivos duplicados. Além disso, apenas os blobs são considerados, e não o tamanho (negligível) das pastas e dos links simbólicos.

A confiabilidade de last_accessed e last_modified pode depender do sistema operacional que você está usando. Veja a documentação do Python para mais detalhes.

size_on_disk_str

< source >

( )

(property) Soma dos tamanhos dos arquivos blob como uma string legível por humanos.

Exemplo: “42.2K”.

refs

< source >

( )

(property) Mapeamento entre refs e estruturas de dados de revisão.

CachedRevisionInfo

classe huggingface_hub.CachedRevisionInfo

< source >

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

Parâmetros

commit_hash (str) — Hash da revisão (único). Exemplo: "9338f7b671827df886678df2bdd7cc7b4f36dffd".
snapshot_path (Path) — Caminho para o diretório da revisão na pasta snapshots. Ele contém a estrutura exata da árvore como o repositório no Hub.
files — (frozenset[CachedFileInfo]): Conjunto de ~CachedFileInfo descrevendo todos os arquivos contidos no snapshot.
refs (frozenset[str]) — Conjunto de refs que apontam para esta revisão. Se a revisão não tiver refs, ela é considerada desanexada. Exemplo: {"main", "2.4.0"} ou {"refs/pr/1"}.
size_on_disk (int) — Soma dos tamanhos dos arquivos de blob que são vinculados por meio de links simbólicos pela revisão.
last_modified (float) — Carimbo de data/hora da última vez em que a revisão foi criada/modificada.

Estrutura de dados imutável que armazena informações sobre uma revisão.

Uma revisão corresponde a uma pasta na pasta snapshots e é preenchida com a estrutura de árvore exata do repositório no Hub, mas contém apenas links simbólicos. Uma revisão pode ser referenciada por 1 ou mais refs ou estar “desanexada” (sem refs).

last_accessed não pode ser determinado corretamente em uma única revisão, pois os arquivos blob são compartilhados entre revisões.

size_on_disk não é necessariamente a soma de todos os tamanhos de arquivo devido a possíveis arquivos duplicados. Além disso, apenas blobs são considerados, e não o tamanho (negligível) de pastas e links simbólicos.

size_on_disk_str

< source >

( )

(property) Soma dos tamanhos dos arquivos blob como uma string legível por humanos.

Exemplo: “42.2K”.

nb_files

< source >

( )

(property) Número total de arquivos na revisão.

CachedFileInfo

classe huggingface_hub.CachedFileInfo

< source >

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

Parâmetros

file_name (str) — Nome do arquivo. Exemplo: config.json.
file_path (Path) — Caminho do arquivo no diretório snapshots. O caminho do arquivo é um link simbólico que se refere a um blob na pasta blobs.
blob_path (Path) — Caminho da entrada de blob local do repositório referenciada por file_path. A entrada de blob pode ser, ela mesma, um link simbólico para o armazenamento de blobs compartilhado em todo o cache.
size_on_disk (int) — Tamanho do arquivo blob em bytes.
blob_last_accessed (float) — Carimbo de data/hora da última vez que o arquivo blob foi acessado (de qualquer revisão).
blob_last_modified (float) — Carimbo de data/hora da última vez em que o arquivo blob foi modificado/criado.

Estrutura de dados imutável que armazena informações sobre um único arquivo em cache.

A confiabilidade de blob_last_accessed e blob_last_modified pode depender do sistema operacional que você está usando. Consulte a documentação do Python para mais detalhes.

size_on_disk_str

< source >

( )

(property) Tamanho do arquivo blob como uma string legível por humanos.

Exemplo: “42.2K”.

CachedIncompleteFileInfo

classe huggingface_hub.CachedIncompleteFileInfo

< source >

( file_path: Pathsize_on_disk: int )

Parâmetros

file_path (Path) — Caminho do arquivo .incomplete na pasta blobs.
size_on_disk (int) — Tamanho do arquivo parcialmente baixado em bytes.

Estrutura de dados imutável que armazena informações sobre um único download incompleto.

Downloads interrompidos deixam para trás arquivos <cache>/<repo>/blobs/<etag>.incomplete. Como eles não fazem parte de nenhuma revisão commitada, são exibidos separadamente por scan_cache_dir().

DeleteCacheStrategy

classe huggingface_hub.DeleteCacheStrategy

< source >

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

Parâmetros

expected_freed_size (float) — Tamanho esperado liberado após a execução da estratégia.
blobs (frozenset[Path]) — Conjunto de caminhos de arquivos de blob a serem excluídos.
refs (frozenset[Path]) — Conjunto de caminhos de arquivos de referência a serem excluídos.
repos (frozenset[Path]) — Set of entire repo paths to be deleted.
snapshots (frozenset[Path]) — Conjunto de snapshots a serem excluídos (diretório de links simbólicos).
files (frozenset[Path], opcional) — Conjunto de entradas individuais de snapshot a serem excluídas. Seus blobs são excluídos apenas se listados em blobs.
cache_dir (Path ou None) — Diretório de cache a partir do qual a estratégia foi calculada. Usado para coletar blobs compartilhados referenciados por links simbólicos locais do repositório removidos pela exclusão.

Estrutura de dados imutável que armazena a estratégia para excluir revisões ou arquivos em cache.

Este objeto não deve ser instanciado programaticamente, mas sim retornado por delete_revisions() ou delete_files(). Consulte a documentação para um exemplo de uso.

expected_freed_size_str

< source >

( )

(property) Tamanho esperado que será liberado, como uma string legível por humanos.

Exemplo: “42.2K”.

Exceções

CorruptedCacheException

classe huggingface_hub.CorruptedCacheException

< source >

( )

Exceção para qualquer estrutura inesperada no sistema de cache do Huggingface.

Update on GitHub

Hub Python Library

Referência do sistema de cache

Auxiliares

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

Estruturas de dados

HFCacheInfo

classe huggingface_hub.HFCacheInfo

delete_files

delete_revisions

export_as_table

CachedRepoInfo

classe huggingface_hub.CachedRepoInfo

size_on_disk_str

refs

CachedRevisionInfo

classe huggingface_hub.CachedRevisionInfo

size_on_disk_str

nb_files

CachedFileInfo

classe huggingface_hub.CachedFileInfo

size_on_disk_str

CachedIncompleteFileInfo

classe huggingface_hub.CachedIncompleteFileInfo

DeleteCacheStrategy

classe huggingface_hub.DeleteCacheStrategy

expected_freed_size_str

Exceções

CorruptedCacheException

classe huggingface_hub.CorruptedCacheException