Hub Python Library documentation
Загрузка файлов из Hub
Загрузка файлов из Hub
Библиотека huggingface_hub предоставляет функции для загрузки файлов из репозиториев, хранящихся на Hub. Вы можете использовать эти функции независимо или интегрировать их в собственную библиотеку, чтобы сделать взаимодействие с Hub более удобным для ваших пользователей. В этом руководстве показано, как:
- Скачать и закэшировать один файл.
- Скачать и закэшировать весь репозиторий.
- Скачайте файлы в локальную папку.
Загрузка одного файла
Функция hf_hub_download() является основной для загрузки файлов с Hub. Она загружает удалённый файл, кэширует его на диске (с учётом версий) и возвращает путь к локальному файлу.
Возвращаемый путь к файлу указывает на локальный кэш HF. Поэтому важно не изменять файл, чтобы не повредить кэш. Если вы хотите узнать больше о том, как кэшируются файлы, обратитесь к нашему руководству по кэшированию.
Из последней версии
Выберите файл для загрузки с помощью параметров repo_id, repo_type и filename. По умолчанию файл считается частью репозитория 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'Из конкретной версии
По умолчанию загружается последняя версия из ветки main. Однако в некоторых случаях вам может потребоваться загрузить файл определённой версии (например, из конкретной ветки, PR, тега или хэша коммита). Для этого используйте параметр 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")Примечание: При использовании хэша коммита он должен быть полным, а не сокращённым до 7 символов.
Создание URL для загрузки
Если вам нужно составить URL, используемый для загрузки файла из репозитория, вы можете использовать hf_hub_url(), который возвращает URL. Обратите внимание, что он используется внутри hf_hub_download().
Скачать весь репозиторий
snapshot_download() загружает весь репозиторий на указанной ревизии. Внутренне он использует hf_hub_download(), что означает, что все загруженные файлы также кэшируются на вашем локальном диске. Загрузки выполняются параллельно для ускорения процесса.
Чтобы скачать весь репозиторий, просто передайте repo_id и 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() по умолчанию загружает последнюю ревизию. Если вам нужна конкретная ревизия репозитория, используйте параметр revision:
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1")Фильтр файлов для загрузки
snapshot_download() — простой способ скачать репозиторий. Однако не всегда нужно скачивать всё содержимое репозитория. Например, если вы знаете, что будете использовать только веса в формате .safetensors, можно избежать скачивания всех файлов .bin. Для этого используйте параметры allow_patterns и ignore_patterns.
Эти параметры принимают как один шаблон, так и список шаблонов. Шаблоны представляют собой стандартные подстановочные знаки (globbing-шаблоны), описанные здесь. Совпадение шаблонов основано на fnmatch.
Например, с помощью allow_patterns можно загрузить только файлы конфигурации в формате JSON:
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json")С другой стороны, ignore_patterns позволяет исключить определённые файлы из загрузки. В следующем примере игнорируются расширения файлов .msgpack и .h5:
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"])Наконец, вы можете объединить оба способа, чтобы точно отфильтровать загрузку. Ниже приведен пример загрузки всех файлов json и markdown, кроме vocab.json.
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json")Загрузка файла(ов) в локальную папку
По умолчанию мы рекомендуем использовать систему кэширования для загрузки файлов с Hub. Вы можете указать кастомное расположение кэша с помощью параметра cache_dir в hf_hub_download() и snapshot_download() или установив переменную окружения HF_HOME.
Однако, если вам нужно скачать файлы в конкретную папку, вы можете передать параметр local_dir в функцию загрузки. Это полезно, чтобы приблизить рабочий процесс к тому, что предлагает команда git. Скачанные файлы сохранят свою исходную структуру файлов внутри указанной папки. Например, если filename="data/train.csv" и local_dir="path/to/folder", то итоговый путь к файлу будет "path/to/folder/data/train.csv".
В корне вашего локального каталога создаётся папка .cache/huggingface/, содержащая метаданные о загруженных файлах. Это предотвращает повторную загрузку файлов, если они уже актуальны. Если метаданные изменились, загружается новая версия файла. Благодаря этому local_dir оптимизирован для получения только последних изменений.
После завершения загрузки вы можете безопасно удалить папку .cache/huggingface/, если она вам больше не нужна. Однако имейте в виду, что повторный запуск вашего скрипта без этой папки может привести к увеличению времени восстановления, так как метаданные будут потеряны. Ваши локальные данные останутся нетронутыми и не пострадают.
Не беспокойтесь о папке
.cache/huggingface/при отправке изменений на Hub! Эта папка автоматически игнорируется какgit, так и upload_folder().
Загрузка из CLI
Вы можете использовать команду hf download в терминале, чтобы напрямую скачать файлы с Hub.
Внутри она использует те же помощники hf_hub_download() и snapshot_download(), описанные выше, и выводит
возвращённый путь в терминал.
>>> hf download gpt2 config.json
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.jsonВы можете загрузить несколько файлов сразу, при этом будет отображаться индикатор прогресса и возвращаться путь к снимку, в котором находятся файлы:
>>> 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Также можно указать репозиторий (а при необходимости — ревизию и файл) с помощью единого URI hf://. URI следует грамматике hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (полный синтаксис описан в справочнике по HF URI) и заменяет опции --repo-type и --revision, которые нельзя использовать вместе с ним:
# 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Для получения подробной информации о команде загрузки CLI обратитесь к руководству по CLI.
Режим предварительного запуска
В некоторых случаях вы можете захотеть проверить, какие файлы будут загружены, прежде чем начать фактическую загрузку. Вы можете сделать это с помощью параметра --dry-run. Он выводит список всех файлов для загрузки в репозитории и проверяет, были ли они уже загружены. Это позволяет понять, сколько файлов необходимо загрузить и каков их размер.
Вот пример проверки одного файла:
>>> 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А если файл уже находится в кэше:
>>> 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 -Вы также можете выполнить пробный запуск (dry-run) для всего репозитория:
>>> 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 -А с фильтрацией файлов:
>>> 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 -Наконец, вы также можете выполнить dry-run программно, передав dry_run=True в hf_hub_download() и snapshot_download(). Будет возвращён объект DryRunFileInfo (соответственно, список объектов DryRunFileInfo), содержащий для каждого файла его commit hash, имя файла и размер файла, а также информацию о том, находится ли файл в кэше и будет ли он загружен. На практике файл будет загружен, если он отсутствует в кэше или если передан параметр force_download=True.
Более быстрая загрузка
Используйте более быстрое скачивание благодаря hf_xet — Python-обёртке над библиотекой xet-core, которая обеспечивает дедупликацию на основе чанков для ускорения загрузки и выгрузки. hf_xet бесшовно интегрируется с huggingface_hub, но использует Rust-библиотеку xet-core и хранилище Xet вместо LFS.
hf_xet использует систему хранения Xet, которая разбивает файлы на неизменяемые фрагменты, хранит коллекции этих фрагментов (называемые блоками или xorbs) удалённо и извлекает их для сборки файла по запросу. При загрузке, после подтверждения того, что пользователь имеет право доступа к файлам, hf_xet обращается к сервису Xet с адресацией по содержимому (CAS) с LFS-хэшем SHA256 для этого файла, чтобы получить метаданные для реконструкции (диапазоны внутри xorbs) для сборки этих файлов, а также предподписанные URL для прямой загрузки xorbs. Затем hf_xet эффективно загружает необходимые диапазоны xorbs и записывает файлы на диск.
Чтобы включить его, просто установите последнюю версию huggingface_hub:
pip install -U "huggingface_hub"Начиная с версии huggingface_hub 0.32.0, это также установит hf_xet.
Все остальные API huggingface_hub продолжат работать без каких-либо изменений. Чтобы узнать больше о преимуществах хранилища Xet и hf_xet, обратитесь к этому разделу.
Примечание: hf_transfer ранее использовался с хранилищем LFS и теперь устарел; вместо него используйте hf_xet.