Baixando arquivos

Baixar um arquivo único

hf_hub_download

huggingface_hub.hf_hub_download

Parâmetros

repo_id (str) — Nome de um usuário ou organização e nome de um repositório separados por /.
filename (str) — O nome do arquivo no repositório.
subfolder (str, opcional) — Um valor opcional correspondente a uma pasta dentro do repositório do modelo.
repo_type (str, opcional) — Defina como "dataset", "space" ou "kernel" se estiver baixando de um repositório de dataset, space ou kernel, None ou "model" se estiver baixando de um modelo. O padrão é None.
revision (str, opcional) — Um id de revisão Git opcional, que pode ser um nome de branch, uma tag ou um hash de commit.
library_name (str, opcional) — O nome da biblioteca à qual o objeto corresponde.
library_version (str, opcional) — A versão da biblioteca.
cache_dir (str, Path, opcional) — Caminho para a pasta onde os arquivos em cache são armazenados.
local_dir (str ou Path, opcional) — Se fornecido, o arquivo baixado será colocado neste diretório.
user_agent (dict, str, opcional) — As informações do user-agent na forma de um dicionário ou uma string.
force_download (bool, opcional, padrão False) — Se o arquivo deve ser baixado mesmo que já exista no cache local.
etag_timeout (float, opcional, padrão 10) — Ao buscar o ETag, quantos segundos esperar o servidor enviar dados antes de desistir, valor que é passado para httpx2.request.
token (str, bool, opcional) — Um token a ser usado para o download.
- Se True, o token é lido da pasta de configuração do HuggingFace.
- Se for uma string, ela é usada como o token de autenticação.
local_files_only (bool, opcional, padrão False) — Se True, evita o download do arquivo e retorna o caminho para o arquivo em cache local, se ele existir.
headers (dict, opcional) — Cabeçalhos adicionais a serem enviados com a solicitação.
endpoint (str, opcional) — O endpoint do Hub para onde enviar a solicitação. O valor padrão é o de HF_ENDPOINT.
tqdm_class (tqdm, opcional) — Se fornecida, sobrescreve o comportamento padrão da barra de progresso. O argumento passado deve herdar de tqdm.auto.tqdm ou, pelo menos, imitar seu comportamento. Padrão: a barra de progresso personalizada do HF, que pode ser desativada definindo a variável de ambiente HF_HUB_DISABLE_PROGRESS_BARS.
dry_run (bool, opcional, padrão False) — Se True, executa uma simulação sem efetivamente baixar o arquivo. Retorna um objeto DryRunFileInfo contendo informações sobre o que seria baixado.

Retorna

str ou DryRunFileInfo

Se dry_run=False: caminho local do arquivo ou, se a rede estiver desativada, a última versão do arquivo em cache no disco.
Se dry_run=True: um objeto DryRunFileInfo contendo informações de download.

Exceções

RepositoryNotFoundError ou RevisionNotFoundError ou ~utils.RemoteEntryNotFoundError ou LocalEntryNotFoundError ou EnvironmentError ou OSError ou ValueError

RepositoryNotFoundError — Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.
RevisionNotFoundError — Se a revisão de onde o download deve ser feito não for encontrada.
~utils.RemoteEntryNotFoundError — Se o arquivo a ser baixado não puder ser encontrado.
LocalEntryNotFoundError — Se a rede estiver desativada ou indisponível e o arquivo não for encontrado no cache.
EnvironmentError — Se token=True, mas o token não puder ser encontrado.
OSError — Se o ETag não puder ser determinado.
ValueError — Se o valor de algum parâmetro for inválido.

Baixe um arquivo específico, caso ele ainda não esteja presente no cache local.

O novo layout de arquivo de cache é o seguinte:

O diretório de cache contém uma subpasta por repo_id (namespaced por tipo de repositório)
dentro de cada pasta de repositório:
- refs é uma lista dos pares mais recentes conhecidos de revisão => commit_hash
- blobs contém os blobs de arquivo reais (identificados pelo git-sha ou sha256, dependendo de se são arquivos LFS ou não)
- snapshots contém uma subpasta por commit, e cada “commit” contém o subconjunto dos arquivos que foram resolvidos naquele commit específico. Cada nome de arquivo é um symlink para o blob naquele commit específico.

[  96]  .
└── [ 160]  models--julien-c--EsperBERTo-small
    ├── [ 160]  blobs
    │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
    │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
    ├── [  96]  refs
    │   └── [  40]  main
    └── [ 128]  snapshots
        ├── [ 128]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f
        │   ├── [  52]  README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
        │   └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        └── [ 128]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48
            ├── [  52]  README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
            └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd

Se local_dir for fornecido, a estrutura de arquivos do repositório será replicada neste local. Ao usar esta opção, o cache_dir não será utilizado e uma pasta .cache/huggingface/ será criada na raiz de local_dir para armazenar alguns metadados relacionados aos arquivos baixados. Embora esse mecanismo não seja tão robusto quanto o sistema de cache principal, ele é otimizado para buscar regularmente a versão mais recente de um repositório.

hf_hub_url

huggingface_hub.hf_hub_url

< source >

( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Noneendpoint: str | None = None )

Parâmetros

repo_id (str) — Um nome de namespace (usuário ou organização) e um nome de repositório separados por /.
filename (str) — O nome do arquivo no repositório.
subfolder (str, opcional) — Um valor opcional correspondente a uma pasta dentro do repositório.
repo_type (str, opcional) — Defina como "dataset", "space" ou "kernel" se estiver baixando de um repositório de dataset, space ou kernel, None ou "model" se estiver baixando de um modelo. O padrão é None.
revision (str, opcional) — Um id de revisão Git opcional, que pode ser um nome de branch, uma tag ou um hash de commit.
endpoint (str, opcional) — O endpoint do Hub para onde enviar a solicitação. O valor padrão é o de HF_ENDPOINT.

Construa a URL de um arquivo a partir das informações fornecidas.

O endereço resolvido pode ser uma URL hospedada no huggingface.co ou um link para o Cloudfront (uma rede de entrega de conteúdo, ou CDN) para arquivos grandes que excedem alguns MBs.

Exemplo:

>>> from huggingface_hub import hf_hub_url

>>> hf_hub_url(
...     repo_id="julien-c/EsperBERTo-small", filename="pytorch_model.bin"
... )
'https://huggingface.co/julien-c/EsperBERTo-small/resolve/main/pytorch_model.bin'

Observações:

Cloudfront é replicado globalmente, o que torna os downloads muito mais rápidos para o usuário final (e também reduz nossos custos de banda).

A Cloudfront faz o cache agressivamente dos arquivos por padrão (TTL padrão é de 24 horas), no entanto, isso não é um problema aqui, pois implementamos um sistema de versionamento baseado em git no huggingface.co, o que significa que armazenamos os arquivos no S3/Cloudfront de uma forma endereçável por conteúdo (ou seja, o nome do arquivo é o seu hash). Usar nomes de arquivos endereçáveis por conteúdo significa que o cache nunca pode ficar desatualizado.

Em termos de cache no lado do cliente a partir desta biblioteca, baseamos nosso cache na tag de entidade (ETag) dos objetos, que é um identificador de uma versão específica de um recurso [1]_. O ETag de um objeto é: seu git-sha1, se armazenado em git, ou seu sha256, se armazenado em git-lfs.

Referências:

[1] https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag

Baixe um snapshot do repositório

huggingface_hub.snapshot_download

< source >

Parâmetros

repo_id (str) — Nome de um usuário ou organização e nome de um repositório separados por /.
repo_type (str, opcional) — Defina como "dataset", "space" ou "kernel" se estiver baixando de um repositório de dataset, space ou kernel, None ou "model" se estiver baixando de um modelo. O padrão é None.
revision (str, opcional) — Um id de revisão Git opcional, que pode ser um nome de branch, uma tag ou um hash de commit.
cache_dir (str, Path, opcional) — Caminho para a pasta onde os arquivos em cache são armazenados.
local_dir (str ou Path, opcional) — Se fornecido, os arquivos baixados serão colocados sob este diretório.
library_name (str, opcional) — O nome da biblioteca à qual o objeto corresponde.
library_version (str, opcional) — A versão da biblioteca.
user_agent (str, dict, opcional) — As informações do user-agent na forma de um dicionário ou uma string.
etag_timeout (float, opcional, padrão 10) — Ao buscar o ETag, quantos segundos esperar o servidor enviar dados antes de desistir, valor que é passado para httpx2.request.
force_download (bool, opcional, padrão False) — Se o arquivo deve ser baixado mesmo que já exista no cache local.
token (str, bool, opcional) — Um token a ser usado para o download.
- Se True, o token é lido da pasta de configuração do HuggingFace.
- Se for uma string, ela é usada como o token de autenticação.
headers (dict, opcional) — Cabeçalhos adicionais a incluir na solicitação. Esses cabeçalhos têm precedência sobre os demais.
endpoint (str, opcional) — O endpoint do Hub para onde enviar a solicitação. O valor padrão é o de HF_ENDPOINT.
local_files_only (bool, opcional, padrão False) — Se True, não baixa nenhum arquivo, mesmo que ele não esteja em cache_dir ou local_dir.
allow_patterns (list[str] ou str, opcional) — Se fornecido, apenas os arquivos que corresponderem a pelo menos um padrão serão baixados.
ignore_patterns (list[str] ou str, opcional) — Se fornecido, os arquivos que corresponderem a qualquer um dos padrões não serão baixados.
max_workers (int, opcional) — Número de threads concorrentes para baixar arquivos (1 thread = 1 download de arquivo). Padrão: 8.
tqdm_class (tqdm, opcional) — Se fornecido, sobrescreve o comportamento padrão da barra de progresso. O argumento passado deve herdar de tqdm.auto.tqdm ou, pelo menos, imitar seu comportamento. Observe que a tqdm_class não é passada para cada download individual. Padrão: a barra de progresso personalizada do HF, que pode ser desativada definindo a variável de ambiente HF_HUB_DISABLE_PROGRESS_BARS.
dry_run (bool, opcional, padrão False) — Se True, executa uma simulação sem efetivamente baixar os arquivos. Retorna uma lista de objetos DryRunFileInfo contendo informações sobre o que seria baixado.

Retorna

str ou lista de DryRunFileInfo

Se dry_run=False: Caminho do snapshot local.
Se dry_run=True: uma lista de objetos DryRunFileInfo contendo informações de download.

Exceções

RepositoryNotFoundError ou RevisionNotFoundError ou IncompleteSnapshotError ou EnvironmentError ou OSError ou ValueError

RepositoryNotFoundError — Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.
RevisionNotFoundError — Se a revisão de onde o download deve ser feito não for encontrada.
IncompleteSnapshotError — Se o Hub não puder ser acessado (offline, problema de conexão ou local_files_only=True) e o snapshot em cache estiver faltando alguns dos arquivos solicitados.
EnvironmentError — Se token=True e o token não puder ser encontrado.
OSError — se o ETag não puder ser determinado.
ValueError — Se o valor de algum parâmetro for inválido.

Baixe os arquivos do repositório.

Baixe um snapshot completo dos arquivos de um repositório na revisão especificada. Isso é útil quando você deseja todos os arquivos de um repositório porque não sabe quais deles precisará a priori. Todos os arquivos são aninhados em uma pasta para manter seu caminho e nome de arquivo relativos a essa pasta. Você também pode filtrar quais arquivos baixar usando allow_patterns e ignore_patterns.

Uma alternativa seria clonar o repositório, mas isso requer que o git e o git-lfs estejam instalados e configurados corretamente. Também não é possível filtrar quais arquivos baixar ao clonar um repositório usando o git.

Leia a árvore do repositório em cache

huggingface_hub.get_cached_repo_tree

< source >

Parâmetros

repo_id (str) — Nome de um usuário ou organização e nome de um repositório separados por /.
repo_type (str, opcional) — Defina como "dataset", "space" ou "kernel" se estiver listando de um repositório de dataset, space ou kernel, None ou "model" se estiver listando de um modelo. O padrão é None.
revision (str, opcional) — Um id de revisão Git opcional, que pode ser um nome de branch, uma tag ou um hash de commit. O padrão é a branch padrão. Os nomes de branch/tag são resolvidos para um hash de commit usando o cache local (refs/).
cache_dir (str, Path, opcional) — Caminho para a pasta onde os arquivos em cache são armazenados. O padrão é o valor de HF_HUB_CACHE.
local_dir (str ou Path, opcional) — Se fornecido, lê a listagem da árvore em cache de um download de local_dir (de local_dir/.cache/huggingface/) em vez do cache principal. As revisões de branch/tag ainda são resolvidas para um hash de commit usando o cache principal (cache_dir).

Retorna

list[RepoFile]

A lista de objetos RepoFile em cache para esta revisão.

Exceções

CachedRepoTreeNotFoundError

CachedRepoTreeNotFoundError — Se não houver uma listagem de árvore em cache para a revisão solicitada (por exemplo, o repositório nunca foi baixado nessa revisão).

Retorna a listagem em cache de um repositório em uma revisão específica, sem nenhuma chamada de rede.

A listagem da árvore é o conjunto de arquivos (com seus metadados de download) de um repositório em um commit. Ela é preenchida no disco como efeito colateral de snapshot_download() (veja os arquivos de cache trees/<commit_hash>.json) e é usada para evitar chamadas de rede em downloads subsequentes. Esta função expõe diretamente esse cache.

Se você precisar da listagem atual da árvore de um repositório no Hub, use list_repo_tree() em vez disso.

Exemplo:

>>> from huggingface_hub import get_cached_repo_tree
>>> files = get_cached_repo_tree("openai-community/gpt2")
>>> [f.path for f in files]
['.gitattributes', 'config.json', 'model.safetensors', ...]

Resolver uma revisão

Resolva um nome de branch/tag para um hash de commit uma única vez e, em seguida, passe o resultado para fixar todos os downloads no mesmo commit. Consulte HfApi.resolve_revision() e o guia do sistema de cache.

ResolvedRevision

classe huggingface_hub.ResolvedRevision

< source >

( resolved: strinitial: str | None = Nonerepo_id: str | None = Nonerepo_type: str | None = None )

Parâmetros

initial (str or None) — A revisão inicialmente solicitada pelo usuário. Se None, o valor da string padrão é "main".
resolved (str) — O hash do commit para o qual initial é resolvido.

Uma revisão do git que já foi resolvida para um hash de commit.

ResolvedRevision é uma subclasse de str, portanto, pode ser passada a qualquer método do huggingface_hub que aceite um argumento revision. Seu valor de string é a revisão inicialmente solicitada pelo usuário (por exemplo, "main", "refs/pr/4"), o que mantém as URLs e as mensagens de erro legíveis, enquanto .resolved contém o hash do commit para o qual ela aponta.

As instâncias são construídas por HfApi.resolve_revision(), que também faz o cache do mapeamento revision -> commit hash no cache local (pasta refs/).

Um hash de commit só tem significado para o repositório em que foi resolvido, por isso uma instância também memoriza esse repositório. Resolver novamente para outro repositório não é um erro: a revisão inicialmente solicitada é resolvida novamente (veja HfApi.resolve_revision()).

Exemplo:

>>> from huggingface_hub import resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')
>>> revision == "main"  # it's a string
True
>>> revision.resolved
'607a30d783dfa663caf39e06633721c8d4cfcd7e'

Obter metadados sobre um arquivo

get_hf_file_metadata

huggingface_hub.get_hf_file_metadata

< source >

Parâmetros

url (str) — URL do arquivo, por exemplo, retornada por hf_hub_url().
token (str ou bool, opcional) — Um token a ser usado para o download.
- Se True, o token é lido da pasta de configuração do HuggingFace.
- Se False ou None, nenhum token é fornecido.
- Se for uma string, ela é usada como o token de autenticação.
timeout (float, opcional, padrão 10) — Quantos segundos esperar o servidor enviar metadados antes de desistir.
library_name (str, opcional) — O nome da biblioteca à qual o objeto corresponde.
library_version (str, opcional) — A versão da biblioteca.
user_agent (dict, str, opcional) — As informações do user-agent na forma de um dicionário ou uma string.
headers (dict, opcional) — Cabeçalhos adicionais a serem enviados com a solicitação.
endpoint (str, opcional) — Endpoint do Hub. O padrão é https://huggingface.co.
retry_on_errors (bool, opcional, padrão False) — Se deve tentar novamente em caso de erros (429, 5xx, timeout, erros de rede). Se False, não há nova tentativa, permitindo um retorno rápido para o cache local.

Obtém os metadados de um arquivo versionado no Hub para uma URL fornecida.

HfFileMetadata

classe huggingface_hub.HfFileMetadata

< source >

( commit_hash: str | Noneetag: str | Nonelocation: strsize: int | Nonexet_file_data: huggingface_hub.utils._xet.XetFileData | None )

Parâmetros

commit_hash (str, opcional) — O commit_hash relacionado ao arquivo.
etag (str, opcional) — Etag do arquivo no servidor.
location (str) — Local para onde o arquivo será baixado. Pode ser uma URL do Hub ou não (CDN).
size (size) — Tamanho do arquivo. No caso de um arquivo LFS, contém o tamanho do arquivo LFS real, não o ponteiro.
xet_file_data (XetFileData, opcional) — Informações do Xet para o arquivo. Isso é definido apenas se o arquivo for armazenado usando o armazenamento Xet.

Estrutura de dados contendo informações sobre um arquivo versionado no Hub.

Retornado por get_hf_file_metadata() com base em uma URL.

Cache

Os métodos exibidos acima foram projetados para funcionar com um sistema de cache que impede o re-download de arquivos. 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 na HF.

Update on GitHub

Hub Python Library

Baixando arquivos

Baixar um arquivo único

hf_hub_download

huggingface_hub.hf_hub_download

hf_hub_url

huggingface_hub.hf_hub_url

Baixe um snapshot do repositório

huggingface_hub.snapshot_download

Leia a árvore do repositório em cache

huggingface_hub.get_cached_repo_tree

Resolver uma revisão

ResolvedRevision

classe huggingface_hub.ResolvedRevision

Obter metadados sobre um arquivo

get_hf_file_metadata

huggingface_hub.get_hf_file_metadata

HfFileMetadata

classe huggingface_hub.HfFileMetadata

Cache