Descargar archivos del Hub

La biblioteca huggingface_hub ofrece funciones para descargar archivos de los repositorios almacenados en el Hub. Puedes usar estas funciones de forma independiente o integrarlas en tu propia biblioteca, lo que facilita a tus usuarios la interacción con el Hub. Esta guía te mostrará cómo:

• Descarga y almacena en caché un archivo individual.
• Descargar y almacenar en caché un repositorio completo.
• Descarga archivos a una carpeta local.

Descargar un solo archivo

La función hf_hub_download() es la función principal para descargar archivos del Hub. Descarga el archivo remoto, lo almacena en caché en el disco (de una manera consciente de la versión) y devuelve su ruta de archivo local.

La ruta de archivo devuelta es un puntero a la caché local de HF. Por lo tanto, es importante no modificar el archivo para evitar tener una caché corrupta. Si te interesa conocer más sobre cómo se almacenan en caché los archivos, consulta nuestra guía de caché.

Desde la última versión

Seleccione el archivo para descargar usando los parámetros repo_id, repo_type y filename. De forma predeterminada, el archivo se considerará parte de un repositorio 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'

Desde una versión específica

Por defecto, se descarga la última versión de la rama main. Sin embargo, en algunos casos es posible que desee descargar un archivo en una versión específica (por ejemplo, de una rama concreta, una PR, una etiqueta o un hash de commit). Para ello, use el 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")

Nota: Al usar el hash de commit, debe ser el hash de longitud completa en lugar de un hash de commit de 7 caracteres.

Construir una URL de descarga

Si desea construir la URL utilizada para descargar un archivo de un repositorio, puede usar hf_hub_url(), que devuelve una URL. Tenga en cuenta que se utiliza internamente en hf_hub_download().

Descargar un repositorio completo

snapshot_download() descarga un repositorio completo en una revisión dada. Utiliza internamente hf_hub_download(), lo que significa que todos los archivos descargados también se almacenan en caché en tu disco local. Las descargas se realizan de forma concurrente para acelerar el proceso.

Para descargar un repositorio completo, solo pasa repo_id y 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() descarga la última revisión de forma predeterminada. Si deseas una revisión específica del repositorio, usa el parámetro revision:

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

Filtrar archivos para descargar

snapshot_download() ofrece una forma sencilla de descargar un repositorio. Sin embargo, no siempre se desea descargar todo el contenido de un repositorio. Por ejemplo, si se sabe que solo se usarán los pesos .safetensors, se puede evitar la descarga de todos los archivos .bin. Para hacerlo, se pueden usar los parámetros allow_patterns y ignore_patterns.

Estos parámetros aceptan un único patrón o una lista de patrones. Los patrones son comodines estándar (patrones de globbing) tal como se documenta aquí. La coincidencia de patrones se basa en fnmatch.

Por ejemplo, puede usar allow_patterns para descargar solo archivos de configuración JSON:

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

Por otro lado, ignore_patterns puede excluir ciertos archivos de la descarga. El siguiente ejemplo ignora las extensiones de archivo .msgpack y .h5:

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

Por último, puedes combinar ambos para filtrar con precisión tu descarga. Aquí tienes un ejemplo para descargar todos los archivos json y markdown excepto vocab.json.

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

Descargar archivo(s) a una carpeta local

Por defecto, recomendamos usar el sistema de caché para descargar archivos del Hub. Puede especificar una ubicación de caché personalizada usando el parámetro cache_dir en hf_hub_download() y snapshot_download(), o configurando la variable de entorno HF_HOME.

Sin embargo, si necesitas descargar archivos en una carpeta específica, puedes pasar un parámetro local_dir a la función de descarga. Esto es útil para acercar el flujo de trabajo a lo que ofrece el comando git. Los archivos descargados mantendrán su estructura de archivos original dentro de la carpeta especificada. Por ejemplo, si filename="data/train.csv" y local_dir="path/to/folder", la ruta de archivo resultante será "path/to/folder/data/train.csv".

Se crea una carpeta .cache/huggingface/ en la raíz de tu directorio local que contiene metadatos sobre los archivos descargados. Esto evita volver a descargar archivos si ya están actualizados. Si los metadatos han cambiado, se descarga la nueva versión del archivo. Esto optimiza local_dir para obtener solo los cambios más recientes.

Tras completar la descarga, puedes eliminar con seguridad la carpeta .cache/huggingface/ si ya no la necesitas. Ten en cuenta, sin embargo, que volver a ejecutar tu script sin esta carpeta puede resultar en tiempos de recuperación más largos, ya que se perderán los metadatos. No te preocupes: tus datos locales permanecerán intactos y sin cambios.

No te preocupes por la carpeta .cache/huggingface/ al enviar cambios al Hub. Esta carpeta se ignora automáticamente tanto por git como por upload_folder().

Descargar desde la CLI

Puede usar el comando hf download desde la terminal para descargar directamente archivos del Hub. Internamente, utiliza los mismos helpers hf_hub_download() y snapshot_download() descritos anteriormente e imprime la ruta devuelta en la terminal.

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

Puede descargar varios archivos a la vez, lo que muestra una barra de progreso y devuelve la ruta de la instantánea en la que se encuentran los archivos:

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

También puede apuntar al repositorio (y opcionalmente a una revisión y un archivo) usando un único URI hf://. El URI sigue la gramática hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (consulte la referencia de URIs de HF para la sintaxis completa) y reemplaza las opciones --repo-type y --revision, que no pueden establecerse junto con él:

# 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 más detalles sobre el comando de descarga de la CLI, consulte la guía de la CLI.

Modo de simulación

En algunos casos, es posible que desee verificar qué archivos se descargarían antes de realizar la descarga. Puede comprobarlo utilizando el parámetro --dry-run. Este parámetro enumera todos los archivos a descargar en el repositorio y verifica si ya están descargados o no. Esto proporciona una idea de cuántos archivos deben descargarse y de sus tamaños.

Aquí hay un ejemplo, comprobando en un solo archivo:

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

Y si el archivo ya está en caché:

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

También puede ejecutar una simulación en un repositorio completo:

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

Y con filtrado de archivos:

>>> 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 último, también puedes realizar una ejecución de prueba de forma programática pasando dry_run=True a hf_hub_download() y snapshot_download(). Devolverá un DryRunFileInfo (o una lista de DryRunFileInfo, respectivamente) con, para cada archivo, su hash de commit, nombre de archivo y tamaño, si el archivo está en caché y si se descargaría. En la práctica, el archivo se descargará si no está en caché o si se pasa force_download=True.

Descargas más rápidas

Aprovecha descargas más rápidas gracias a hf_xet, el enlace de Python para la biblioteca xet-core que permite la deduplicación basada en fragmentos para descargas y cargas más rápidas. hf_xet se integra a la perfección con huggingface_hub, pero utiliza la biblioteca Rust xet-core y el almacenamiento Xet en lugar de LFS.

hf_xet utiliza el sistema de almacenamiento Xet, que divide los archivos en bloques inmutables, almacena colecciones de estos bloques (llamados blocks o xorbs) de forma remota y los recupera para reensamblar el archivo cuando se solicita. Al descargar, después de confirmar que el usuario está autorizado para acceder a los archivos, hf_xet consultará el servicio de direccionamiento por contenido de Xet (CAS) con el hash SHA256 de LFS de este archivo para recibir los metadatos de reconstrucción (rangos dentro de los xorbs) para ensamblar estos archivos, junto con URLs prefirmadas para descargar los xorbs directamente. Luego, hf_xet descargará de manera eficiente los rangos de xorb necesarios y escribirá los archivos en el disco.

Para habilitarlo, simplemente instala la última versión de huggingface_hub:

pip install -U "huggingface_hub"

A partir de huggingface_hub 0.32.0, esto también instalará hf_xet.

Todas las demás APIs de huggingface_hub seguirán funcionando sin ninguna modificación. Para conocer más sobre los beneficios del almacenamiento Xet y hf_xet, consulte esta sección.

Nota: hf_transfer se usaba anteriormente con el backend de almacenamiento LFS y ahora está en desuso; usa hf_xet en su lugar.