Переход на huggingface_hub v1.0

Выпуск v1.0 является важной вехой для библиотеки huggingface_hub. Он подтверждает нашу приверженность стабильности API и зрелости библиотеки. Мы внесли ряд улучшений и несовместимых изменений, чтобы сделать библиотеку более надёжной и удобной в использовании.

Это руководство поможет вам перенести существующий код на новую версию. Если у вас есть вопросы или предложения, пожалуйста, сообщите нам, создав issue на GitHub.

Python 3.9+

huggingface_hub теперь требует Python 3.9 или более позднюю версию. Поддержка Python 3.8 прекращена.

Миграция на HTTPX

Библиотека huggingface_hub теперь использует httpx вместо requests для HTTP-запросов. Это изменение было сделано для повышения производительности и для поддержки как синхронных, так и асинхронных запросов одинаковым образом. В связи с этим мы убрали зависимости от requests и aiohttp.

Критические изменения

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

• Конфигурация прокси: прокси «по методу» больше не поддерживаются. Прокси должны настраиваться глобально с помощью переменных окружения HTTP_PROXY и HTTPS_PROXY.
• Пользовательский HTTP-бэкенд: функция configure_http_backend была удалена. Теперь для настройки HTTP-клиентов следует использовать set_client_factory() и set_async_client_factory().
• Обработка ошибок: ошибки HTTP больше не наследуются от requests.HTTPError, а от httpx.HTTPError. Мы рекомендуем перехватывать HfHubHTTPError (импортируется с помощью from huggingface_hub.utils import HfHubHTTPError), который является подклассом requests.HTTPError в v0.x и httpx.HTTPError в v1.x. Перехват ошибок из huggingface_hub гарантирует, что ваш код будет совместим как со старой, так и с новой версиями библиотеки.
• SSLError: в httpx нет понятия SSLError. Теперь это общий httpx.ConnectError.
• LocalEntryNotFoundError: эта ошибка больше не наследуется от HTTPError. Теперь мы определяем EntryNotFoundError (новый), от которого наследуются как LocalEntryNotFoundError (если файл не найден в локальном кэше), так и RemoteEntryNotFoundError (если файл не найден в репозитории на Hub). Только удалённая ошибка наследуется от HTTPError.
• InferenceClient: теперь InferenceClient можно использовать как менеджер контекста. Это особенно полезно при потоковой передаче токенов от языковой модели, чтобы гарантировать корректное закрытие соединения.
• AsyncInferenceClient: параметр trust_env был удалён из конструктора AsyncInferenceClient. Переменные окружения по умолчанию доверяются httpx. Если вы явно не хотите доверять окружению, необходимо настроить это с помощью set_async_client_factory().

Для получения дополнительных сведений вы можете ознакомиться с PR #3328, в котором было добавлено httpx.

Зачем httpx?

Переход с requests на httpx обеспечивает несколько ключевых улучшений, повышающих производительность, надёжность и поддерживаемость библиотеки:

Потокобезопасность и повторное использование соединений: httpx потокобезопасен по своей конструкции, что позволяет безопасно использовать один и тот же клиент в нескольких потоках. Повторное использование соединений снижает накладные расходы на создание новых соединений для каждого HTTP-запроса, что повышает производительность, особенно при частых запросах к Hub.

Поддержка HTTP/2: httpx обеспечивает нативную поддержку HTTP/2, что повышает эффективность при выполнении нескольких запросов к одному серверу (именно наш случай). Это приводит к снижению задержки и уменьшению потребления ресурсов по сравнению с HTTP/1.1.

Единый синхронный и асинхронный API: В отличие от нашей предыдущей конфигурации с отдельными зависимостями requests (синхронная) и aiohttp (асинхронная), httpx предоставляет синхронный и асинхронный клиенты с идентичным поведением. Это гарантирует, что InferenceClient и AsyncInferenceClient обладают согласованным функционалом и устраняет тонкие различия в поведении, которые ранее существовали между двумя реализациями.

Улучшенная обработка ошибок SSL: httpx более корректно обрабатывает ошибки SSL, что упрощает и делает более надёжным отладку проблем с подключением.

Архитектура с заделом на будущее: httpx активно поддерживается и разработан для современных Python-приложений. В отличие от него, requests находится в режиме поддержки и не будет получать крупные обновления, такие как улучшения потоковой безопасности или поддержка HTTP/2.

Улучшенная обработка переменных окружения: httpx обеспечивает более последовательную обработку переменных окружения как в синхронном, так и в асинхронном контекстах, устраняя прежние несоответствия, при которых requests по умолчанию читал локальные переменные окружения, а aiohttp — нет.

Переход на httpx обеспечивает huggingface_hub современный, эффективный и поддерживаемый HTTP-бэкенд. Хотя большинство пользователей не заметят изменений в работе, эти улучшения повышают производительность и надежность всех взаимодействий с Hub.

hf_transfer

Теперь, когда все репозитории на Hub поддерживают Xet, а hf_xet является стандартным способом загрузки и выгрузки файлов, мы убрали поддержку необязательного пакета hf_transfer. Переменная окружения HF_HUB_ENABLE_HF_TRANSFER теперь игнорируется. Вместо этого используйте HF_XET_HIGH_PERFORMANCE.

Класс репозитория

Класс Repository был удалён в версии 1.0. Он представлял собой тонкую обёртку над CLI git для управления репозиториями. Вы по-прежнему можете использовать git напрямую в терминале, но рекомендуемый подход — использовать HTTP-базированный API в библиотеке huggingface_hub для более плавного опыта, особенно при работе с большими файлами.

Ниже приведено соответствие между устаревшим классом Repository и новым классом HfApi:

Метод Repository	метод HfApi
repo.clone_from	snapshot_download
repo.git_add + git_commit + git_push	upload_file(), upload_folder(), create_commit()
repo.git_tag	create_tag
repo.git_branch	create_branch

Класс HfFolder

HfFolder использовался для управления токеном доступа пользователя. Используйте login(), чтобы сохранить новый токен, logout(), чтобы удалить его, и whoami(), чтобы проверить пользователя, связанного с текущим токеном. Наконец, используйте get_token(), чтобы получить токен пользователя в скрипте.

Класс InferenceApi

InferenceApi был классом для взаимодействия с Inference API. Теперь рекомендуется использовать класс InferenceClient.

Другие устаревшие функции

Некоторые методы и параметры были удалены в v1.0. Перечисленные ниже уже были объявлены устаревшими с предупреждением в v0.x.

• constants.hf_cache_home был удалён. Используйте HF_HOME вместо него.
• Параметры use_auth_token были удалены из всех методов. Используйте вместо них token.
• Метод get_token_permission был удалён.
• Метод update_repo_visibility был удалён. Используйте вместо него update_repo_settings.
• Параметр is_write_action был удалён из build_hf_headers, а write_permission — из login. Понятие «write permission» было упразднено и более не актуально, поскольку сейчас рекомендуемым подходом являются токены с детализированными правами.
• Параметр new_session в login переименован в skip_if_logged_in для большей ясности.
• Параметры resume_download, force_filename и local_dir_use_symlinks были удалены из hf_hub_download и snapshot_download.
• Параметры library, language, tags и task были удалены из list_models.

Команды кэша CLI

Управление кэшем из CLI было переработано в соответствии с рабочим процессом, вдохновлённым Docker. Устаревший huggingface-cli был удалён, а hf (представленный в v0.34) заменяет его более понятным CLI с моделью «ресурс-действие». Устаревшие команды hf cache scan и hf cache delete также удалены в v1.0 и заменены на новую тройку команд, приведённую ниже:

• hf cache ls выводит список записей кэша в виде краткой таблицы, JSON или CSV. Используйте --revisions, чтобы просмотреть отдельные ревизии, добавляйте выражения --filter, например size>1GB или accessed>30d, и комбинируйте их с --quiet, если нужны только идентификаторы.
• hf cache rm удаляет выбранные записи кэша. Укажите один или несколько идентификаторов репозиториев (например, model/bert-base-uncased) или хеши ревизий, а при необходимости добавьте --dry-run для предварительного просмотра или --yes, чтобы пропустить запрос подтверждения. Эта команда заменяет как интерактивный TUI, так и сценарии с --disable-tui из предыдущей команды.
• hf cache prune выполняет типовую задачу очистки, удаляя все не используемые ревизии за один раз. Добавьте --dry-run или --yes так же, как при использовании hf cache rm.

Наконец, дополнительный пакет [cli] был удалён — CLI теперь поставляется в составе основного пакета huggingface_hub.

Поддержка TensorFlow и Keras 2.x

Всё код и зависимости, связанные с TensorFlow, были удалены в v1.0. Это включает следующие несовместимые изменения:

• huggingface_hub[tensorflow] больше не является поддерживаемой дополнительной зависимостью
• Утилитарные функции split_tf_state_dict_into_shards и get_tf_storage_size были удалены.
• Версии tensorflow, fastai и fastcore больше не включены в встроенные заголовки.

Интеграция с Keras 2.x также была удалена. Это включает класс KerasModelHubMixin и утилиты save_pretrained_keras, from_pretrained_keras и push_to_hub_keras. Keras 2.x — это устаревшая библиотека, поддержка которой прекращена. Рекомендуемый подход — использовать Keras 3.x, который тесно интегрирован с Hub (то есть содержит встроенный метод для загрузки/отправки в Hub). Если вы всё же хотите работать с Keras 2.x, вам следует откатить huggingface_hub до версии v0.x.

Возвращаемые значения upload_file и upload_folder

Функции upload_file() и upload_folder() теперь возвращают URL коммита, созданного на Hub. Ранее они возвращали URL файла или папки. Это сделано для согласования с возвращаемым значением функций create_commit(), delete_file() и delete_folder().

Update on GitHub