Тихий апокалипсис: почему v1.0 ломает всё, что вы знали

Вы обновили transformers до последней версии и внезапно все ваши скрипты падают с криптографическими ошибками. Или пытаетесь запустить huggingface-cli и получаете сообщение, что команда не найдена. Поздравляю, вы столкнулись с переходом на huggingface_hub v1.0.

Это не просто очередное обновление. Это фундаментальный пересмотр того, как библиотека работает с сетью, аутентификацией и CLI. И если вы не подготовитесь, это обновление съест ваш день.

Ваши продакшн-скрипты, которые годами работали без проблем, перестанут работать после pip install --upgrade huggingface_hub. Не делайте этого вслепую.

Что сломали и зачем

Команда Hugging Face решила, что старый код превратился в монстра. requests устарел, urllib3 тормозил, а CLI был написан на click, который уже не в моде. Решение? Полный рефакторинг.

Главное изменение: библиотека теперь использует httpx вместо requests. Это не просто замена одной зависимости на другую. httpx — асинхронная по умолчанию, что меняет все паттерны работы с сетью.

💡

httpx даёт реальное ускорение на больших моделях и датасетах. Особенно заметно при скачивании файлов по частям или при работе с медленными соединениями.

1Первое, что убьёт ваш день: новый CLI

Старый добрый huggingface-cli мёртв. Вместо него теперь hf. И это не просто переименование.

Как НЕ надо делать:

# Это больше не работает
huggingface-cli login
huggingface-cli upload ...

Правильный путь:

# Установите новую версию
pip install huggingface_hub>=1.0.0

# Используйте новую команду
hf login
hf upload ...

Почему так? Старый CLI был на click, новый — на Typer. Typer даёт лучшее автодополнение, более чистый вывод help и проще расширяется. Но главное — он теперь часть основного пакета, а не отдельный инструмент.

Старая команда	Новая команда	Что изменилось
huggingface-cli login	hf login	Тот же функционал
huggingface-cli upload	hf upload	Новые флаги, другой синтаксис
huggingface-cli download	hf download	Асинхронная загрузка через httpx
huggingface-cli repo-create	hf repo create	Подкоманды вместо дефисов

2httpx backend: асинхронность везде

Самое болезненное изменение для тех, кто писал низкоуровневый код. Раньше вы могли делать так:

from huggingface_hub import HfApi
api = HfApi()
# Синхронный запрос
repo_info = api.repo_info("gpt2")

Теперь под капотом всё асинхронное. Если вы запускаете этот код в синхронном контексте — всё работает. Но если у вас своя event loop (например, в FastAPI приложении), начинаются проблемы.

Решение — явно указывать, какой клиент использовать:

import asyncio
from huggingface_hub import AsyncHfApi

async def main():
    api = AsyncHfApi()
    repo_info = await api.repo_info("gpt2")
    print(repo_info)

# Или в синхронном коде
from huggingface_hub import HfApi
api = HfApi()
repo_info = api.repo_info("gpt2")  # Работает, но под капотом — async/await

Почему это важно? Если вы делаете batch-загрузку нескольких моделей или датасетов, асинхронность даёт 3-5x ускорение. Особенно если вы работаете с Swift-клиентом для Hugging Face или другими не-Python инструментами.

Совместимость с transformers: минное поле

Если вы используете transformers (а кто нет?), вот где начинается настоящая боль. huggingface_hub v1.0 совместим ТОЛЬКО с transformers v4.40.0 и выше.

Не обновляйте huggingface_hub, если у вас transformers ниже 4.40.0. Сначала обновите transformers, проверьте, что всё работает, только потом обновляйте huggingface_hub.

Типичный сценарий катастрофы:

Вы делаете pip install --upgrade transformers huggingface_hub
pip сначала обновляет huggingface_hub до v1.0
Потом пытается обновить transformers
Но новая версия huggingface_hub уже установлена и ломает старый transformers
Ваш CI/CD падает, продакшн ложится, день испорчен

Правильная последовательность:

# Сначала transformers
pip install transformers>=4.40.0
# Проверяем, что всё работает
python -c "from transformers import pipeline; print('OK')"
# Теперь huggingface_hub
pip install huggingface_hub>=1.0.0

3Миграция кода: пошаговый разбор

Давайте пройдём через реальные изменения, которые нужно сделать в вашем коде.

Шаг 1: Импорты

Старый код:

from huggingface_hub import snapshot_download
from huggingface_hub import HfFolder
from huggingface_hub import Repository

Новый код:

from huggingface_hub import snapshot_download  # Осталось
from huggingface_hub import HfFolder  # Устарело!
from huggingface_hub import Repository  # Осторожно, API изменилось

HfFolder больше не существует. Вместо него используйте hf_api.token или переменные окружения.

Шаг 2: Загрузка моделей

Раньше:

from transformers import AutoModel
model = AutoModel.from_pretrained("bert-base-uncased")
# Всё просто

Теперь под капотом работает новый кэш. Если у вас были проблемы с кэшем — они могут исчезнуть. Или появиться новые.

Особенно внимательно проверяйте код, где вы вручную управляете кэшем:

# Старый способ очистки кэша больше не работает
import shutil
shutil.rmtree("~/.cache/huggingface")  # Не делайте так!

Вместо этого используйте официальный API:

from huggingface_hub import scan_cache_dir, delete_cache_entries

# Посмотреть, что в кэше
cache_info = scan_cache_dir()
print(cache_info.entries)

# Удалить конкретную модель
delete_cache_entries(["model_name"])

# Или через новый CLI
# hf cache scan
# hf cache delete [pattern]

Шаг 3: Работа с репозиториями

Класс Repository сильно изменился. Если вы делали так:

repo = Repository(
    local_dir="./my-model",
    clone_from="username/my-model",
    use_auth_token=True
)

Теперь нужно явно указывать тип репозитория:

from huggingface_hub import Repository

repo = Repository(
    local_dir="./my-model",
    repo_type="model",  # Обязательно!
    clone_from="username/my-model"
)

# Или для датасетов
repo = Repository(
    local_dir="./my-dataset",
    repo_type="dataset",
    clone_from="username/my-dataset"
)

Если вы публикуете модели через скрипты автоматизации, проверьте этот параметр. Без него всё упадёт с непонятной ошибкой.

Новые фичи, ради которых стоит терпеть боль

После всей этой миграционной боли что мы получаем взамен?

Ускорение загрузки в 2-3 раза благодаря httpx и улучшенному кэшированию
Лучшая обработка ошибок — теперь понятные сообщения вместо stack trace
Интеграция с transformers v5 — готовьтесь к грядущим изменениям в transformers v5
Поддержка пространств (Spaces) — теперь можно управлять Spaces через API
Улучшенная работа с большими файлами — resume download работает стабильнее

💡

Новый CLI (hf) поддерживает плагины. Можно написать свою команду hf my-command и она появится в списке. Полезно для кастомных workflow в команде.

Проверка совместимости перед обновлением

Прежде чем лезть в продакшн с обновлением, сделайте вот что:

# Создайте виртуальное окружение для тестов
python -m venv test_hf_v1
source test_hf_v1/bin/activate  # или activate.fish для fish

# Установите старые версии
pip install transformers==4.39.3 huggingface_hub==0.20.3

# Запустите ваши скрипты
python your_script.py

# Теперь обновите
pip install transformers>=4.40.0 huggingface_hub>=1.0.0

# Запустите снова
python your_script.py

# Сравните вывод, проверьте логи

Особое внимание уделите:

Аутентификации (токены, переменные окружения)
Загрузке моделей (особенно больших, >5GB)
Коду, который использует huggingface_hub напрямую
CI/CD пайплайнам, которые публикуют модели

Частые ошибки и как их избежать

Ошибка	Причина	Решение
ModuleNotFoundError: No module named 'huggingface_hub.utils._errors'	Старый transformers пытается импортировать из нового huggingface_hub	Обновите transformers первым
Command 'huggingface-cli' not found	Старый CLI удалён	Используйте `hf` вместо `huggingface-cli`
TypeError: __init__() got an unexpected keyword argument 'use_auth_token'	API изменился	Используйте `token` вместо `use_auth_token`
SSLError или криптографические ошибки	httpx использует другую SSL-библиотеку	Обновите certifi: `pip install --upgrade certifi`

Что делать, если всё сломалось

Паника — плохой советчик. Если после обновления ничего не работает:

Откатитесь к старой версии: pip install huggingface_hub==0.20.3 transformers==4.39.3
Посмотрите, какие именно скрипты падают
Проверьте документацию на GitHub — там есть migration guide
Посмотрите issues в репозитории huggingface_hub — возможно, вашу проблему уже решили
Если вы публикуете модели через автоматизацию, проверьте наше полное руководство по публикации на Hugging Face — там есть актуальные примеры кода

И последний совет: не обновляйте всё сразу в пятницу вечером. Дайте себе время на отладку. Hugging Face Hub v1.0 — это шаг вперёд, но шаг болезненный. Как и любое мажорное обновление, оно требует внимания и тестирования.

Те, кто переживут этот переход, получат более быструю и стабильную библиотеку. Те, кто проигнорирует breaking changes, получат сломанный продакшн. Выбор за вами.

Hugging Face Hub v1.0: полный гайд по переходу с v0.x, breaking changes и совместимости с transformers