Baixar arquivos do Hub

A biblioteca huggingface_hub fornece funções para baixar arquivos dos repositórios armazenados no Hub. Você pode usar essas funções de forma independente ou integrá-las à sua própria biblioteca, tornando mais conveniente para seus usuários interagir com o Hub. Este guia mostrará como:

• Baixe e faça o cache de um único arquivo.
• Baixe e faça o cache de um repositório inteiro.
• Baixe os arquivos para uma pasta local.

Baixar um arquivo único

A função hf_hub_download() é a principal função para baixar arquivos do Hub. Ela baixa o arquivo remoto, o faz cache no disco (de uma forma consciente da versão) e retorna o caminho local do arquivo.

O caminho de arquivo retornado é um ponteiro para o cache local do HF. Portanto, é importante não modificar o arquivo para evitar ter um cache corrompido. Se você tiver interesse em saber mais sobre como os arquivos são armazenados em cache, consulte nosso guia de cache.

Da versão mais recente

Selecione o arquivo para download usando os parâmetros repo_id, repo_type e filename. Por padrão, o arquivo será considerado parte de um repositório de model.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
'/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'

# Download from a dataset
>>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset")
'/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py'

De uma versão específica

Por padrão, a versão mais recente da branch main é baixada. No entanto, em alguns casos, você pode querer baixar um arquivo em uma versão específica (por exemplo, de uma branch específica, de um PR, de uma tag ou de um hash de commit). Para isso, use o parâmetro revision:

# Download from the `v1.0` tag
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0")

# Download from the `test-branch` branch
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch")

# Download from Pull Request #3
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3")

# Download from a specific commit hash
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a")

Observação: Ao usar o hash do commit, ele deve ser o hash de comprimento completo, em vez de um hash de commit de 7 caracteres.

Construir uma URL de download

Caso queira construir a URL usada para baixar um arquivo de um repositório, você pode usar hf_hub_url(), que retorna uma URL. Observe que ela é usada internamente por hf_hub_download().

Baixar um repositório inteiro

snapshot_download() baixa um repositório inteiro em uma revisão específica. Ele usa internamente hf_hub_download(), o que significa que todos os arquivos baixados também são armazenados em cache no seu disco local. Os downloads são feitos de forma concorrente para acelerar o processo.

Para baixar um repositório inteiro, basta passar o repo_id e o repo_type:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'

# Or from a dataset
>>> snapshot_download(repo_id="google/fleurs", repo_type="dataset")
'/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34'

snapshot_download() baixa a revisão mais recente por padrão. Se você quiser uma revisão específica do repositório, use o parâmetro revision:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1")

Filtrar arquivos para download

snapshot_download() oferece uma maneira fácil de baixar um repositório. No entanto, nem sempre você deseja baixar todo o conteúdo de um repositório. Por exemplo, você pode querer evitar o download de todos os arquivos .bin se souber que usará apenas os pesos .safetensors. Você pode fazer isso usando os parâmetros allow_patterns e ignore_patterns.

Esses parâmetros aceitam um único padrão ou uma lista de padrões. Os padrões são Wildcards Padrão (padrões de globbing) conforme documentado aqui. A correspondência de padrões é baseada em fnmatch.

Por exemplo, você pode usar allow_patterns para baixar apenas arquivos de configuração JSON:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json")

Por outro lado, ignore_patterns pode excluir certos arquivos de serem baixados. O exemplo a seguir ignora as extensões de arquivo .msgpack e .h5:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"])

Por fim, você pode combinar ambos para filtrar com precisão seu download. Aqui está um exemplo para baixar todos os arquivos json e markdown, exceto vocab.json.

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json")

Baixar arquivo(s) para uma pasta local

Por padrão, recomendamos usar o sistema de cache para baixar arquivos do Hub. Você pode especificar um local de cache personalizado usando o parâmetro cache_dir em hf_hub_download() e snapshot_download(), ou definindo a variável de ambiente HF_HOME.

No entanto, se você precisar baixar arquivos para uma pasta específica, pode passar um parâmetro local_dir para a função de download. Isso é útil para tornar o fluxo de trabalho mais próximo do que o comando git oferece. Os arquivos baixados manterão sua estrutura de arquivos original dentro da pasta especificada. Por exemplo, se filename="data/train.csv" e local_dir="path/to/folder", o caminho do arquivo resultante será "path/to/folder/data/train.csv".

A pasta .cache/huggingface/ é criada na raiz do seu diretório local e contém metadados sobre os arquivos baixados. Isso impede o rebaixamento de arquivos que já estão atualizados. Se os metadados tiverem sido alterados, a nova versão do arquivo é baixada. Isso torna o local_dir otimizado para buscar apenas as alterações mais recentes.

Após concluir o download, você pode remover com segurança a pasta .cache/huggingface/ caso não a precise mais. No entanto, tenha em mente que reexecutar seu script sem essa pasta pode resultar em tempos de recuperação mais longos, pois os metadados serão perdidos. Fique tranquilo: seus dados locais permanecerão intactos e não serão afetados.

Não se preocupe com a pasta .cache/huggingface/ ao enviar alterações para o Hub! Essa pasta é ignorada automaticamente tanto pelo git quanto pelo upload_folder().

Baixar pelo CLI

Você pode usar o comando hf download no terminal para baixar arquivos diretamente do Hub. Internamente, ele usa os mesmos auxiliares hf_hub_download() e snapshot_download() descritos acima e imprime o caminho retornado no terminal.

>>> hf download gpt2 config.json
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json

Você pode baixar vários arquivos de uma vez, o que exibe uma barra de progresso e retorna o caminho do snapshot em que os arquivos estão localizados:

>>> hf download gpt2 config.json model.safetensors
Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10

Você também pode apontar para o repositório (e opcionalmente uma revisão e um arquivo) usando um único URI hf://. O URI segue a gramática hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (veja a referência de URIs do HF para a sintaxe completa) e substitui as opções --repo-type e --revision, que não podem ser definidas junto com ele:

# Download a single file from a dataset at a given revision
>>> hf download hf://datasets/google/fleurs@refs/pr/1/fleurs.py

# Download a subfolder (note the trailing slash)
>>> hf download hf://datasets/google/fleurs/data/

# Download an entire repo
>>> hf download hf://datasets/google/fleurs

Para mais detalhes sobre o comando de download da CLI, consulte o guia da CLI.

Modo de simulação

Em alguns casos, você pode querer verificar quais arquivos seriam baixados antes de efetivamente baixá-los. Você pode verificar isso usando o parâmetro --dry-run. Ele lista todos os arquivos a serem baixados no repositório e verifica se eles já foram baixados ou não. Isso dá uma ideia de quantos arquivos precisam ser baixados e de seus tamanhos.

Aqui está um exemplo, verificando em um único arquivo:

>>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run
[dry-run] Will download 1 files (out of 1) totalling 655.2M
File                           Bytes to download
------------------------------ -----------------
onnx/decoder_model_merged.onnx 655.2M

E se o arquivo já estiver em cache:

>>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run
[dry-run] Will download 0 files (out of 1) totalling 0.0.
File                           Bytes to download
------------------------------ -----------------
onnx/decoder_model_merged.onnx -

Você também pode executar uma simulação em um repositório inteiro:

>>> hf download openai-community/gpt2 --dry-run
[dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00,  6.26it/s]
[dry-run] Will download 11 files (out of 26) totalling 5.6G.
File                              Bytes to download
--------------------------------- -----------------
.gitattributes                    -
64-8bits.tflite                   125.2M
64-fp16.tflite                    248.3M
64.tflite                         495.8M
README.md                         -
config.json                       -
flax_model.msgpack                497.8M
generation_config.json            -
merges.txt                        -
model.safetensors                 548.1M
onnx/config.json                  -
onnx/decoder_model.onnx           653.7M
onnx/decoder_model_merged.onnx    655.2M
onnx/decoder_with_past_model.onnx 653.7M
onnx/generation_config.json       -
onnx/merges.txt                   -
onnx/special_tokens_map.json      -
onnx/tokenizer.json               -
onnx/tokenizer_config.json        -
onnx/vocab.json                   -
pytorch_model.bin                 548.1M
rust_model.ot                     702.5M
tf_model.h5                       497.9M
tokenizer.json                    -
tokenizer_config.json             -
vocab.json                        -

E com filtragem de arquivos:

>>> hf download openai-community/gpt2 --include "*.json"  --dry-run
[dry-run] Fetching 11 files: 100%|█████████████| 11/11 [00:00<00:00, 80518.92it/s]
[dry-run] Will download 0 files (out of 11) totalling 0.0.
File                         Bytes to download
---------------------------- -----------------
config.json                  -
generation_config.json       -
onnx/config.json             -
onnx/generation_config.json  -
onnx/special_tokens_map.json -
onnx/tokenizer.json          -
onnx/tokenizer_config.json   -
onnx/vocab.json              -
tokenizer.json               -
tokenizer_config.json        -
vocab.json                   -

Por fim, você também pode executar uma simulação (dry-run) programaticamente passando dry_run=True para hf_hub_download() e snapshot_download(). Isso retornará um DryRunFileInfo (ou uma lista de DryRunFileInfo, respectivamente) contendo, para cada arquivo, o hash do commit, o nome do arquivo e o tamanho do arquivo, além de indicar se o arquivo está em cache e se ele seria baixado. Na prática, o arquivo será baixado se não estiver em cache ou se force_download=True for passado.

Downloads mais rápidos

Aproveite downloads mais rápidos por meio do hf_xet, o binding em Python para a biblioteca xet-core que permite deduplicação baseada em chunks para downloads e uploads mais rápidos. O hf_xet se integra perfeitamente ao huggingface_hub, mas usa a biblioteca Rust xet-core e o armazenamento Xet em vez do LFS.

hf_xet usa o sistema de armazenamento Xet, que divide arquivos em blocos imutáveis, armazenando coleções desses blocos (chamados de blocks ou xorbs) remotamente e recuperando-os para reconstituir o arquivo quando solicitado. Durante o download, após confirmar que o usuário está autorizado a acessar os arquivos, o hf_xet consulta o serviço de endereçamento por conteúdo do Xet (CAS) com o hash SHA256 LFS deste arquivo para receber os metadados de reconstrução (intervalos dentro dos xorbs) para montar esses arquivos, juntamente com URLs pré-assinadas para baixar os xorbs diretamente. Em seguida, o hf_xet baixa eficientemente os intervalos de xorb necessários e grava os arquivos no disco.

Para ativá-lo, basta instalar a versão mais recente do huggingface_hub:

pip install -U "huggingface_hub"

A partir da versão 0.32.0 do huggingface_hub, isso também instalará o hf_xet.

Todas as outras APIs do huggingface_hub continuarão a funcionar sem qualquer modificação. Para saber mais sobre os benefícios do armazenamento Xet e do hf_xet, consulte esta seção.

Observação: hf_transfer era usado anteriormente com o backend de armazenamento LFS e agora está descontinuado; use hf_xet em vez disso.