Модели Hugging Face скачиваются медленно или обрываются

Веса современной модели легко занимают десятки гигабайт. Скачивать их через браузер или git clone неудобно: при обрыве часто приходится начинать сначала. Инструменты Hugging Face умеют пропускать уже скачанное, брать только нужные файлы и использовать быстрый бэкенд хранения. Ниже актуальные команды и переменные окружения.

Сначала обновите CLI

Многие инструкции в интернете устарели. Команда huggingface-cli заменена на hf: новая появилась в huggingface_hub 0.34, а в версии 1.0 старое имя убрали. Если команда hf не находится, обновите пакет:

pip install -U huggingface_hub
hf env
hf auth login   # нужен для закрытых и gated-моделей

Есть и другие способы установки: brew install hf на macOS или запуск без установки через uvx hf. Проверить результат можно командой hf --help.

hf env выводит версии библиотеки и связанных пакетов. Вместе с актуальным huggingface_hub ставится hf_xet: клиент хранилища Xet, на котором сейчас работает Hub. Он делит файлы на части и качает их параллельно.

Базовая загрузка

hf download meta-llama/Llama-3.2-1B-Instruct

Без дополнительных флагов файлы попадают в общий кэш, по умолчанию ~/.cache/huggingface/hub, а команда печатает путь к снимку репозитория. Если оборвать загрузку и запустить ту же команду снова, уже скачанные файлы повторно не качаются.

В скриптах удобен флаг --quiet: команда печатает только итоговый путь, и его можно сразу сохранить в переменную, например MODEL_DIR=$(hf download <репозиторий> --quiet). В логах CI полосы прогресса отключает HF_HUB_DISABLE_PROGRESS_BARS=1.

Для воспроизводимости закрепляйте версию: --revision принимает ветку, тег или полный хэш коммита. Датасеты качаются той же командой с флагом --repo-type dataset.

Крупные модели обычно разбиты на несколько файлов вида model-00001-of-00004.safetensors, так что обрыв затрагивает только тот файл, который качался в этот момент. Недокачанные куски остаются в кэше с расширением .incomplete. Если от загрузки отказались насовсем, их убирает hf cache prune.

Качайте только нужное

В репозитории модели часто лежат одни и те же веса в нескольких форматах: safetensors, pytorch_model.bin, ONNX, TensorFlow, Flax, а у квантованных сборок ещё и несколько вариантов GGUF. Скачать всё подряд значит качать в разы больше, чем нужно. Сначала посмотрите список файлов с размерами:

hf download openai-community/gpt2 --dry-run

--dry-run ничего не скачивает: он показывает, какие файлы будут загружены, сколько они весят и какие уже есть в кэше. Затем отфильтруйте шаблонами, повторяя флаг для каждого шаблона:

hf download meta-llama/Llama-3.2-1B-Instruct \
  --include "*.safetensors" --include "*.json" \
  --exclude "*.bin"

Не отсекайте JSON-файлы: веса из нескольких частей сопровождаются файлом вида model.safetensors.index.json, где записано, какой тензор в какой части лежит. Без него библиотека не соберёт модель, а вместе с ним нужны config.json и файлы токенизатора. Перед загрузкой большой модели сверьте итог из --dry-run со свободным местом на диске: df -h.

Для GGUF-сборок берите один нужный файл по имени, а не весь репозиторий: hf download <репозиторий> <имя файла>.gguf.

Формат safetensors предпочтительнее .bin. Файл .bin обычно сохранён через pickle, и загрузка недоверенного pickle может выполнить произвольный код. safetensors хранит только тензоры и метаданные.

В Python то же самое делают параметры allow_patterns и ignore_patterns:

from huggingface_hub import snapshot_download

snapshot_download(
    "meta-llama/Llama-3.2-1B-Instruct",
    allow_patterns=["*.safetensors", "*.json"],
    max_workers=8,
)

Ускорение: Xet вместо hf_transfer

Старые советы предлагают поставить hf_transfer и включить HF_HUB_ENABLE_HF_TRANSFER=1. В актуальных версиях это не работает: переменная помечена устаревшей, потому что все передачи идут через hf_xet. Аналог старого режима теперь такой:

export HF_XET_HIGH_PERFORMANCE=1
hf download meta-llama/Llama-3.2-1B-Instruct

В этом режиме hf_xet старается занять всю полосу канала и все ядра процессора. На общем сервере или рабочем ноутбуке он будет мешать остальным задачам, поэтому включайте его для разовых больших загрузок.

Если файлы пишутся на обычный жёсткий диск, а не на SSD, попробуйте HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY=1. hf_xet по умолчанию пишет на диск параллельно, а для HDD последовательная запись бывает быстрее.

У hf download есть ещё --max-workers, по умолчанию 8: сколько файлов качать одновременно. Для репозитория из множества файлов увеличение помогает, для одного большого файла нет.

Таймауты и нестабильная сеть

export HF_HUB_DOWNLOAD_TIMEOUT=60
export HF_HUB_ETAG_TIMEOUT=30

Офлайн-режим полезен не только без сети. Даже когда файл уже в кэше, загрузчик по умолчанию делает HTTP-запрос, чтобы проверить, нет ли новой версии. На плохом канале каждый такой запрос может ждать до таймаута, а HF_HUB_OFFLINE=1 убирает эти проверки и ускоряет запуск.

Переменные читаются при импорте библиотеки, поэтому задавайте их до запуска скрипта, а не внутри уже работающего Python. Для отладки есть HF_DEBUG=1: библиотека выведет каждый запрос в виде эквивалентной команды curl. Прежде чем отправлять такой лог коллегам, проверьте, что в нём нет вашего токена.

Ошибка 429 означает, что Hub ограничил число запросов за окно в пять минут. Свежие версии huggingface_hub читают из ответа, сколько осталось до сброса лимита, и сами повторяют запрос после паузы. Ошибки 401 и 403 на gated-моделях к сети отношения не имеют: примите условия лицензии на странице модели и войдите через hf auth login. В CI вместо входа задайте токен в переменной HF_TOKEN.

Где хранится кэш

Корневой каталог задаёт HF_HOME, по умолчанию ~/.cache/huggingface. Внутри лежат токен, кэш моделей hub и служебные данные Xet. Если домашний раздел маленький, перенесите всё на большой диск одной переменной:

export HF_HOME=/data/huggingface

Этот же кэш используют transformers, diffusers и другие библиотеки экосистемы. Удобная схема для серверов: заранее скачать модель через hf download, а в рабочем процессе загружать её с HF_HUB_OFFLINE=1, чтобы запуск не зависел от сети.

На Windows кэш опирается на символические ссылки. Без режима разработчика или прав администратора они не создаются, и одинаковые файлы разных ревизий хранятся копиями. Включите режим разработчика, если моделей много.

Только кэш моделей переносится через HF_HUB_CACHE. Посмотреть, что занимает место, и удалить лишнее помогают hf cache ls, hf cache rm и hf cache prune.

Флаг --local-dir кладёт файлы в обычную папку с исходной структурой репозитория. Это удобно, когда другой инструмент ждёт модель по конкретному пути. Метаданные загрузки хранятся в .cache/huggingface внутри этой папки: благодаря им повторный запуск не качает заново файлы, которые не изменились.

Выбор между кэшем и --local-dir влияет на место на диске. Общий кэш хранит одинаковые файлы один раз для всех проектов и ревизий. Отдельные папки дублируют веса в каждом проекте, зато их проще копировать и удалять.

Почему не git clone

• Обычный клон тянет все файлы всех форматов, выбрать только safetensors можно лишь ручной работой с Git LFS.
• Без установленного git-lfs вместо весов вы получите маленькие текстовые файлы-указатели, и ошибка всплывёт только при загрузке модели в код.
• Большие файлы хранятся дважды: в .git/lfs и в рабочей копии, поэтому места на диске уходит примерно вдвое больше.
• Если git всё же нужен, клонируйте с GIT_LFS_SKIP_SMUDGE=1, а нужные веса подтягивайте командой git lfs pull --include="*.safetensors".

Проверка целостности

После загрузки сверьте файлы с контрольными суммами на Hub:

hf cache verify meta-llama/Llama-3.2-1B-Instruct
hf cache verify meta-llama/Llama-3.2-1B-Instruct --local-dir ./llama

Первая команда проверяет снимок в кэше, вторая папку, скачанную через --local-dir. Флаг --fail-on-missing-files дополнительно сообщит, если каких-то файлов из репозитория у вас нет.

Переменная HF_ENDPOINT меняет адрес Hub для всех инструментов на базе huggingface_hub. Её задают, когда в компании есть свой прокси-репозиторий моделей, например в Artifactory. Указывайте только адреса, которым доверяете: через них к вам приходят веса и файлы конфигурации.

Если всё равно медленно

Для замера возьмите один крупный файл, чтобы не смешивать скорость канала с накладными расходами на множество мелких: time hf download <репозиторий> <файл> --local-dir /tmp/hf-test. Сравните скорость с HF_XET_HIGH_PERFORMANCE=1 и без него. Если канал всё равно не заполняется, а из другой сети загрузка идёт нормально, узкое место в маршруте до серверов Hugging Face. Если проблема в маршруте до репозитория, помогает защищённое подключение через ближайшую к нему локацию.

Коротко

• Используйте hf download, а не huggingface-cli и не git clone.
• Смотрите размер через --dry-run и качайте только нужный формат через --include.
• Вместо hf_transfer включайте HF_XET_HIGH_PERFORMANCE=1.
• На медленном канале поднимите HF_HUB_DOWNLOAD_TIMEOUT.
• Перенесите кэш на большой диск через HF_HOME.
• Проверяйте результат командой hf cache verify.