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

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

Это руководство поможет вам перенести существующий код на новую версию. Если у вас есть вопросы или предложения, пожалуйста, сообщите нам, [создав issue на GitHub](https://github.com/huggingface/huggingface_hub/issues).

## Python 3.9+

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

## Миграция на HTTPX

Библиотека `huggingface_hub` теперь использует [`httpx`](https://www.python-httpx.org/) вместо `requests` для HTTP-запросов. Это изменение было сделано для повышения производительности и для поддержки как синхронных, так и асинхронных запросов одинаковым образом. В связи с этим мы убрали зависимости от `requests` и `aiohttp`.

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

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

- **Конфигурация прокси**: прокси «по методу» больше не поддерживаются. Прокси должны настраиваться глобально с помощью переменных окружения `HTTP_PROXY` и `HTTPS_PROXY`.
- **Пользовательский HTTP-бэкенд**: функция `configure_http_backend` была удалена. Теперь для настройки HTTP-клиентов следует использовать [set_client_factory()](/docs/huggingface_hub/v2.4.0/ru/package_reference/utilities#huggingface_hub.set_client_factory) и [set_async_client_factory()](/docs/huggingface_hub/v2.4.0/ru/package_reference/utilities#huggingface_hub.set_async_client_factory).
- **Обработка ошибок**: ошибки HTTP больше не наследуются от `requests.HTTPError`, а от `httpx.HTTPError`. Мы рекомендуем перехватывать [HfHubHTTPError](/docs/huggingface_hub/v2.4.0/ru/package_reference/utilities#huggingface_hub.errors.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()](/docs/huggingface_hub/v2.4.0/ru/package_reference/utilities#huggingface_hub.set_async_client_factory).

Для получения дополнительных сведений вы можете ознакомиться с [PR #3328](https://github.com/huggingface/huggingface_hub/pull/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`](../package_reference/environment_variables).

## Класс `Repository`

Класс `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()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.upload_file), [upload_folder()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.upload_folder), [create_commit()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.create_commit) |
| `repo.git_tag`                             | `create_tag`                                          |
| `repo.git_branch`                          | `create_branch`                                       |

## Класс `HfFolder`

`HfFolder` использовался для управления токеном доступа пользователя. Используйте [login()](/docs/huggingface_hub/v2.4.0/ru/package_reference/authentication#huggingface_hub.login), чтобы сохранить новый токен, [logout()](/docs/huggingface_hub/v2.4.0/ru/package_reference/authentication#huggingface_hub.logout) — чтобы удалить его, и [whoami()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.whoami) — чтобы проверить пользователя, связанного с текущим токеном. Наконец, используйте `get_token()`, чтобы получить токен пользователя в скрипте.

## Класс `InferenceApi`

`InferenceApi` был классом для взаимодействия с Inference API. Теперь рекомендуется использовать класс [InferenceClient](/docs/huggingface_hub/v2.4.0/ru/package_reference/inference_client#huggingface_hub.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()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.upload_file) и [upload_folder()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) теперь возвращают URL коммита, созданного на Hub. Ранее они возвращали URL файла или папки. Это сделано для согласования с возвращаемым значением функций [create_commit()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.create_commit), [delete_file()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.delete_file) и [delete_folder()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.delete_folder).