Если вы гоняете transformers, diffusers или свой код на базе huggingface_hub на удалённом Mac или self-hosted runner, типичный поисковый запрос звучит так: включать ли HF_TRANSFER, как задать зеркальный HF_ENDPOINT, не смешаются ли каталоги кеша и как составить ключ кеша CI без сюрпризов. Ниже — исполняемые переменные окружения и таблица решений; семантика переменных сверяйте с официальной справкой huggingface_hub. Критично: все export — до строки import huggingface_hub. Точки входа на сайте: главная, список блога. Для смежного ускорения загрузок: многоуровневый кеш моделей (OpenClaw), Git и Docker pull, Python CI, uv и PyPI.

Сценарии и чеклист узких мест

Сначала сопоставьте симптом с «ручкой» регулировки: на удалённом узле бессмысленно крутить только параллелизм Xet, если метаданные падают по таймауту или несколько джобов пишут в один кеш.

  • Долгий этап ETag / проверка ревизии: при трансграничном RTT значение по умолчанию HF_HUB_ETAG_TIMEOUT=10 часто даёт ложные отказы; сначала поднимайте этот порог, а не полосу пропускания.
  • Обрыв крупного файла на середине: для чекпоинтов на десятки гигабайт дефолтный HF_HUB_DOWNLOAD_TIMEOUT=10 обычно мал; до диагностики диска повышайте именно его.
  • Параллельные джобы в один HF_HUB_CACHE: временные файлы и жёсткие ссылки в кеше Hub плохо переносят одновременную запись; выделяйте подпапку на пайплайн, отдельный HF_HOME или серийный префетч-стейдж.
  • Смена зеркала после частичной загрузки: новый HF_ENDPOINT требует нового корня кеша или чистого HF_HUB_CACHE, иначе растут «необъяснимые» checksum-ошибки.
  • 403 / gated-репозитории: нужен валидный HF_TOKEN в секретах CI; зеркало должно поддерживать ту же модель авторизации.
  • NAS или смешанные ОС: задайте HF_HUB_DISABLE_SYMLINKS=1, чтобы не ловить битые symlink при SMB/APFS; цена — больший расход места на диске.
Сигнал Первый шаг Чего избегать
Медленные list/metadata ↑ HF_HUB_ETAG_TIMEOUT; при разрешённом зеркале — HF_ENDPOINT Максимальный Xet-параллелизм до исправления метаданных
Обрыв большого блоба ↑ HF_HUB_DOWNLOAD_TIMEOUT; повтор только шага загрузки Массовый параллельный рестарт всего пайплайна без бэкоффа
Есть канал, но CPU на 100% HF_XET_HIGH_PERFORMANCE=1 + умеренный HF_XET_NUM_CONCURRENT_RANGE_GETS Делить одно ядро раннера между тяжёлым Xet и Xcode-сборкой без лимитов

Таблица переменных: HF_HUB_ENABLE_HF_TRANSFER, HF_ENDPOINT, каталоги кеша и параллельная загрузка

Переменная Назначение Дефолт / суть Рекомендация для Mac CI
HF_ENDPOINT Базовый URL API и артефактов Hub https://huggingface.co Для зеркала — origin вашего зеркала; смена ⇒ новый корень кеша
HF_HOME Корень токенов и кешей Зависит от ОС / XDG_CACHE_HOME Явный путь на SSD, напр. $HOME/.cache/hf-ci-$CI_PIPELINE_ID
HF_HUB_CACHE Снимки моделей/датасетов $HF_HOME/hub Совпадайте с path в шаге restore/save кеша CI
HF_XET_CACHE Чанки Xet $HF_HOME/xet Кешируйте вместе с HF_HUB_CACHE при смене endpoint
HF_HUB_ENABLE_HF_TRANSFER Исторический fast-path «hf_transfer» Помечен как устаревший в документации Не опирайтесь в новых пайплайнах; сравнение со старыми логами
HF_XET_HIGH_PERFORMANCE Агрессивный режим Xet Выше CPU и IO 1 на выделенном джобе с запасом по CPU
HF_XET_NUM_CONCURRENT_RANGE_GETS Параллельные range-GET на файл Часто 16 в свежих версиях Слабый канал или шумная сеть: 6–12
HF_HUB_DOWNLOAD_TIMEOUT Таймаут чтения при скачивании (с) ≈10 Трансгранично: 120–300
HF_HUB_ETAG_TIMEOUT Ожидание метаданных (с) ≈10 30–120
HF_HUB_OFFLINE Запрет исходящих HTTP, только кеш 0/1 После префетча — для тестовых стейджей
HF_TOKEN Токен доступа Файл в HF_HOME или env Только секреты CI, минимальные права read

Готовый блок для shell-стейджа (адаптируйте HF_ENDPOINT под своё зеркало и путь диска под APFS/NVMe):

# Удалённый Mac / CI: до запуска Python export HF_ENDPOINT="${HF_ENDPOINT:-https://huggingface.co}" export HF_HOME="${HF_HOME:-$HOME/Library/Caches/huggingface-ci}" export HF_HUB_CACHE="${HF_HUB_CACHE:-$HF_HOME/hub}" export HF_XET_CACHE="${HF_XET_CACHE:-$HF_HOME/xet}" export HF_HUB_DOWNLOAD_TIMEOUT="${HF_HUB_DOWNLOAD_TIMEOUT:-180}" export HF_HUB_ETAG_TIMEOUT="${HF_HUB_ETAG_TIMEOUT:-60}" export HF_XET_NUM_CONCURRENT_RANGE_GETS="${HF_XET_NUM_CONCURRENT_RANGE_GETS:-10}" # export HF_XET_HIGH_PERFORMANCE=1 # включать, если есть запас CPU и стабильный канал # export HF_HUB_DISABLE_SYMLINKS=1 # при NAS / смешанных клиентах # Легаси (не ядро стратегии 2026): HF_HUB_ENABLE_HF_TRANSFER=1 python -c "import huggingface_hub; print('hub', huggingface_hub.__version__)"

Докачка (resume) и проектирование ключей кеша CI

Докачка: huggingface_hub переиспользует частично загруженные объекты в пределах одного согласованного каталога кеша и той же ревизии. Условие — отсутствие гонок записи из параллельных джобов. Практичный шаблон: отдельный префетч-стейдж, который тянет веса, а downstream-джобы либо читают тот же путь в режиме «только чтение», либо ставят HF_HUB_OFFLINE=1, чтобы не платить за лишние round-trip метаданных.

Факторы ключа кеша (склеить и захешировать)
  • repo_id (например org/model)
  • Закреплённый revision (commit SHA), а не плавающее имя ветки
  • Хост из HF_ENDPOINT (обязательно при чередовании зеркала и origin)
  • Минорная версия huggingface_hub и Python (при смене поведения API)
  • Опционально: флаги Xet, если меняете стратегию упаковки/скорости и делите артефакт между ветками

В механизмах вроде GitHub Actions поле path должно указывать на тот же HF_HUB_CACHE (и при необходимости HF_XET_CACHE); restore-keys делайте уже основного ключа, если готовы к редким промахам целостности. На общем пуле удалённых Mac надёжнее отдельный HF_HOME на пайплайн плюс синхронизация «тяжёлого» кеша через администрируемый снимок, а не общая запись с нескольких runner’ов.

Повторы при сбоях, пороги таймаутов и FAQ

Порядок настройки таймаутов: при TimeoutError на скачивании сначала увеличьте HF_HUB_DOWNLOAD_TIMEOUT; если зависание на этапе «узнать актуальную ревизию», добавьте HF_HUB_ETAG_TIMEOUT. Оба дефолта около 10 с плохо коррелируют с трансграничными маршрутами и файлами >10–50 ГБ.

Повторы: оборачивайте только шаг загрузки весов (2–3 попытки) с экспоненциальным бэкоффом и джиттером, например пауза sleep $((16 + RANDOM % 17)) между попытками; при 429 читайте Retry-After. Не перезапускайте весь пайплайн десять раз подряд без паузы — вы упрётесь в лимиты Hub и в очередь раннера.

Прокси и TLS: корпоративные MITM требуют явного доверия к корневому CA в окружении Python/requests; используйте HTTPS_PROXY / NO_PROXY согласно политике egress. Для проверки «всё ли уже в кеше» поднимите краткий смоук с HF_HUB_OFFLINE=1.

HDD и джиттер записи Xet: при медленных дисках рассмотрите HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY=1 (последовательная запись чанков); для кеша весов предпочтительны NVMe на удалённом Mac.

Внутренние ссылки: главная, блог и материалы про ускорение pull

Итог: в 2026 году на удалённом Mac трансграничный pull весов с Hub начинается с выравнивания HF_HUB_DOWNLOAD_TIMEOUT и HF_HUB_ETAG_TIMEOUT под реальную сеть, затем с жёсткой границы каталогов HF_HOME / HF_HUB_CACHE / HF_XET_CACHE и ключей кеша с хостом endpoint и SHA ревизии. Скорость отдаётся стеку Xet (HF_XET_HIGH_PERFORMANCE, HF_XET_NUM_CONCURRENT_RANGE_GETS), а HF_HUB_ENABLE_HF_TRANSFER оставьте лишь как историческую отсылку. Нужен стабильный Apple Silicon-раннер с быстрым диском под кеш — без обязательного входа можно открыть главную, тарифы, оформление аренды и центр помощи.

Сначала стабильный pull весов — потом тренировка и инференс

Аренда удалённого Mac Mini M4 снижает расхождение «локально работало / в CI упало»: тот же macOS, APFS и привычные пути кеша. Ознакомьтесь с продуктом на главной, подберите пакет на странице цен, оформите доступ через покупку / аренду; ответы на типовые вопросы — в центре помощи. Дополнительно по кешу моделей: гайд по многоуровневому кешу.

Тарифы Центр помощи Блог
Быстрая выдача
SSH / VNC
Кеш на NVMe