# 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()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.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. > [!TIP] > 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é](./manage-cache). ### 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`. ```python >>> 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`: ```python # 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 deseas construir la URL utilizada para descargar un archivo de un repositorio, puedes usar [hf_hub_url()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.hf_hub_url), que devuelve una URL. Ten en cuenta que se utiliza internamente en [hf_hub_download()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.hf_hub_download). ## Descargar un repositorio completo [snapshot_download()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.snapshot_download) descarga un repositorio completo en una revisión dada. Utiliza internamente [hf_hub_download()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.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`: ```python >>> 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()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.snapshot_download) descarga la última revisión de forma predeterminada. Si deseas una revisión específica del repositorio, usa el parámetro `revision`: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1") ``` ### Filtrar archivos para descargar [snapshot_download()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.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í](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). La coincidencia de patrones se basa en [`fnmatch`](https://docs.python.org/3/library/fnmatch.html). Por ejemplo, puede usar `allow_patterns` para descargar solo archivos de configuración JSON: ```python >>> 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`: ```python >>> 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. A continuación, se muestra un ejemplo para descargar todos los archivos json y markdown excepto `vocab.json`. ```python >>> 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é](./manage-cache) para descargar archivos del Hub. Puede especificar una ubicación de caché personalizada usando el parámetro `cache_dir` en [hf_hub_download()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.hf_hub_download) y [snapshot_download()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.snapshot_download), o configurando la variable de entorno [`HF_HOME`](../package_reference/environment_variables#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. > [!TIP] > 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()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_api#huggingface_hub.HfApi.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()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.hf_hub_download) y [snapshot_download()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.snapshot_download) descritos anteriormente e imprime la ruta devuelta en la terminal. ```bash >>> 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: ```bash >>> 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://[/][@][/]` (consulte la [referencia de URIs de HF](../package_reference/hf_uris) para la sintaxis completa) y reemplaza las opciones `--repo-type` y `--revision`, que no pueden establecerse junto con él: ```bash # 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](./cli#hf-download). ## 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: ```sh >>> 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é: ```sh >>> 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: ```sh >>> 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: ```sh >>> 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()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.hf_hub_download) y [snapshot_download()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.snapshot_download). Devolverá un [DryRunFileInfo](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_api#huggingface_hub.DryRunFileInfo) (o una lista de [DryRunFileInfo](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_api#huggingface_hub.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`](https://github.com/huggingface/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`: ```bash 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](https://huggingface.co/docs/hub/xet/index). Nota: `hf_transfer` se usaba anteriormente con el backend de almacenamiento LFS y ahora está en desuso; usa `hf_xet` en su lugar.