Возвращает текущий уровень для корневого логгера HuggingFace Hub.

У HuggingFace Hub следующие уровни журналирования:

• huggingface_hub.logging.CRITICAL, huggingface_hub.logging.FATAL
• huggingface_hub.logging.ERROR
• huggingface_hub.logging.WARNING, huggingface_hub.logging.WARN
• huggingface_hub.logging.INFO
• huggingface_hub.logging.DEBUG

Устанавливает уровень для корневого логгера HuggingFace Hub.

Устанавливает уровень детализации на logging.INFO.

Устанавливает уровень детализации на logging.DEBUG.

Устанавливает уровень детализации на logging.WARNING.

Устанавливает уровень детализации на logging.ERROR.

Отключите распространение логов библиотеки. Обратите внимание, что по умолчанию распространение логов отключено.

Включите распространение логов библиотеки. Отключите обработчик по умолчанию HuggingFace Hub, чтобы избежать дублирования записей в журнале, если корневой логгер был настроен.

Возвращает логгер с указанным именем. Эта функция не предназначена для прямого обращения со стороны пользователей библиотеки.

>>> from huggingface_hub import logging

>>> logger = logging.get_logger(__name__)
>>> logging.set_verbosity_info()

Проверьте, отключены ли индикаторы прогресса глобально или для конкретной группы.

Эта функция возвращает, отключены ли индикаторы прогресса для указанной группы или глобально. Сначала она проверяет переменную окружения HF_HUB_DISABLE_PROGRESS_BARS, а затем программные настройки.

Отключите полосы прогресса глобально или для указанной группы.

Эта функция обновляет состояние индикаторов прогресса на основе имени группы. Если имя группы не указано, все индикаторы прогресса отключаются. Операция учитывает значение переменной окружения HF_HUB_DISABLE_PROGRESS_BARS.

Работает и как обычный вызов, и как менеджер контекста: disable_progress_bars() # отключает до вызова enable_progress_bars() with disable_progress_bars(): # отключает на время блока, включает обратно при выходе …

Включите полосы прогресса глобально или для указанной группы.

Эта функция включает полосы прогресса для указанной группы или глобально, если группа не указана. Операция подчиняется настройке окружения HF_HUB_DISABLE_PROGRESS_BARS.

Установите фабрику HTTP-клиента, используемую huggingface_hub.

Фабрика клиента — это метод, возвращающий объект httpx2.Client. При первом вызове get_session() фабрика клиента будет использована для создания нового объекта httpx2.Client, который будет общим для всех вызовов, выполняемых huggingface_hub.

Это может быть полезно, если вы запускаете свои скрипты в конкретной среде, требующей нестандартной конфигурации (например, настраиваемого прокси или сертификатов).

Используйте get_session(), чтобы получить корректно настроенный httpx2.Client.

Получите объект httpx2.Client, используя фабрику транспорта от пользователя.

Этот клиент используется всеми вызовами, выполняемыми huggingface_hub. Поэтому не закрывайте его вручную.

Используйте set_client_factory() для настройки httpx2.Client.

Закройте глобальный httpx2.Client, используемый huggingface_hub.

Если клиент закрыт, он будет создан заново при следующем вызове get_session().

Может быть полезно, например, если сертификат SSL был обновлён.

Установите фабрику HTTP-асинхронного клиента, используемую huggingface_hub.

Фабрика асинхронного клиента — это метод, возвращающий объект httpx2.AsyncClient. Это может быть полезно, если вы запускаете свои скрипты в среде, требующей специальной конфигурации (например, настраиваемого прокси или сертификатов). Используйте get_async_session(), чтобы получить корректно настроенный httpx2.AsyncClient.

В отличие от httpx2.Client, который используется всеми вызовами, выполняемыми huggingface_hub, экземпляр httpx2.AsyncClient не является общим. Рекомендуется использовать асинхронный контекстный менеджер, чтобы гарантировать корректное закрытие клиента при выходе из контекста.

Возвращает объект httpx2.AsyncClient, используя фабрику транспорта от пользователя.

Используйте set_async_client_factory() для настройки httpx2.AsyncClient.

В отличие от httpx2.Client, который используется всеми вызовами, выполняемыми huggingface_hub, экземпляр httpx2.AsyncClient не является общим. Рекомендуется использовать асинхронный контекстный менеджер, чтобы гарантировать корректное закрытие клиента при выходе из контекста.

Внутренняя версия response.raise_for_status(), которая уточняет потенциальную HTTPError. Будет выброшено исключение, являющееся экземпляром HfHubHTTPError.

This helper is meant to be the unique method to raise_for_status when making a call to the Hugging Face Hub.

Исключение, если запрос завершился с ошибкой:

• RepositoryNotFoundError Если репозиторий, из которого выполняется загрузка, не найден. Это может произойти, если он не существует, если repo_type задан неверно или если репозиторий является private и у вас нет к нему доступа.
• GatedRepoError Если репозиторий существует, но является закрытым (gated), а пользователь не входит в список авторизованных.
• RevisionNotFoundError Если репозиторий существует, но ревизия не найдена.
• EntryNotFoundError Если репозиторий существует, но запись (например, запрошенный файл) не была найдена.
• BadRequestError Если запрос завершился ошибкой HTTP 400 BadRequest.
• HfHubHTTPError Если запрос завершился ошибкой по причине, не указанному выше.

Возвращает, находится ли мы в автономном режиме для Hub.

Когда включён автономный режим, все HTTP-запросы, выполняемые с помощью get_session, вызывают исключение OfflineModeIsEnabled.

from huggingface_hub import is_offline_mode

def list_files(repo_id: str):
    if is_offline_mode():
        ... # list files from local cache (degraded experience but still functional)
    else:
        ... # list files from Hub (complete experience)

HTTPError для наследования при создании собственных ошибок HTTP, возникающих в HF Hub.

Любая ошибка HTTPError преобразуется как минимум в HfHubHTTPError. Если сервер возвращает какую-либо информацию, она будет добавлена к сообщению об ошибке.

Добавлены подробности:

• Request ID берётся из заголовков в порядке приоритета: “X-Request-Id”, “X-Amzn-Trace-Id”, “X-Amz-Cf-Id”.
• Сообщение об ошибке сервера из заголовка X-Error-Message.
• Сообщение об ошибке сервера, если его удалось найти в теле ответа.

    import httpx2
    from huggingface_hub.utils import get_session, hf_raise_for_status, HfHubHTTPError

    response = get_session().post(...)
    try:
        hf_raise_for_status(response)
    except HfHubHTTPError as e:
        print(str(e)) # formatted message
        e.request_id, e.server_message # details returned by server

        # Complete the error message with additional information once it's raised
        e.append_to_message("
ate_commit` expects the repository to exist.")
        raise

Возникает при попытке получить доступ к URL hf.co с недействительным именем репозитория или с именем приватного репозитория, к которому у пользователя нет доступа.

>>> from huggingface_hub import model_info
>>> model_info("<non_existent_repository>")
(...)
huggingface_hub.errors.RepositoryNotFoundError: 401 Client Error. (Request ID: PvMw_VjBMjVdMz53WKIzP)

Repository Not Found for url: https://huggingface.co/api/models/%3Cnon_existent_repository%3E.
Please make sure you specified the correct `repo_id` and `repo_type`.
If the repo is private, make sure you are authenticated and your token has the required permissions.
Invalid username or password.

Возникает при попытке доступа к репозиторию с ограниченным доступом, если пользователь не входит в список авторизованных.

Примечание: наследуется от RepositoryNotFoundError для обеспечения обратной совместимости.

>>> from huggingface_hub import model_info
>>> model_info("<gated_repository>")
(...)
huggingface_hub.errors.GatedRepoError: 403 Client Error. (Request ID: ViT1Bf7O_026LGSQuVqfa)

Cannot access gated repo for url https://huggingface.co/api/models/ardent-figment/gated-model.
Access to model ardent-figment/gated-model is restricted and you are not in the authorized list.
Visit https://huggingface.co/ardent-figment/gated-model to ask for access.

Возникает при попытке доступа к URL hf.co с валидным репозиторием, но невалидной ревизией.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', 'config.json', revision='<non-existent-revision>')
(...)
huggingface_hub.errors.RevisionNotFoundError: 404 Client Error. (Request ID: Mwhe_c3Kt650GcdKEFomX)

Revision Not Found for url: https://huggingface.co/bert-base-cased/resolve/%3Cnon-existent-revision%3E/config.json.

Возникает при вызове HfApi.resolve_revision(), если ревизию не удалось сопоставить с хэшем коммита: Hub был недоступен (офлайн-режим, ошибка соединения, таймаут, простой Hub и т. д.), а соответствующая запись не была найдена в локальном кэше.

Возникает при вызове hf_raise_for_status, если сервер возвращает ошибку HTTP 400.

>>> resp = httpx2.post("hf.co/api/check", ...)
>>> hf_raise_for_status(resp, endpoint_name="check")
huggingface_hub.errors.BadRequestError: Bad request for check endpoint: {details} (Request ID: XXX)

Возникает, если запись не найдена ни локально, ни удалённо.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.RemoteEntryNotFoundError (...)
>>> hf_hub_download('bert-base-cased', '<non-existent-file>', local_files_only=True)
(...)
huggingface_hub.utils.errors.LocalEntryNotFoundError (...)

Возникает при попытке доступа к URL hf.co с валидным репозиторием и ревизией, но некорректным именем файла.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.EntryNotFoundError: 404 Client Error. (Request ID: 53pNl6M0MxsnG5Sw8JA6x)

Entry Not Found for url: https://huggingface.co/bert-base-cased/resolve/main/%3Cnon-existent-file%3E.

Возникает при попытке доступа к файлу или снимку, который отсутствует на диске, когда сеть отключена или недоступна (проблема с подключением). Запись может присутствовать на Hub.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-cached-file>',  local_files_only=True)
(...)
huggingface_hub.errors.LocalEntryNotFoundError: Cannot find the requested files in the disk cache and outgoing traffic has been disabled. To enable hf.co look-ups and downloads online, set 'local_files_only' to False.

Возникает при вызове snapshot_download(), если Hub недоступен (офлайн, проблема с подключением или local_files_only=True), а кэшированный снимок известен как неполный: некоторые файлы, перечисленные в кэшированном списке дерева репозитория, отсутствуют в локальном снимке.

Это подкласс LocalEntryNotFoundError, сохранённый для обратной совместимости.

Атрибут snapshot_path содержит путь к неполному локальному снимку, что позволяет библиотеке нижнего уровня находить последние кэшированные файлы, даже если известно, что они неполные.

Возникает при вызове get_cached_repo_tree(), если для запрошенной ревизии не кэширован список дерева.

Список дерева заполняется как побочный эффект snapshot_download().

Возникает, если запрос был отправлен, но переменная окружения HF_HUB_OFFLINE=1 установлена.

Отправляет телеметрию, которая помогает отслеживать использование различных библиотек HF.

Эти данные о использовании помогают нам отлаживать проблемы и определять приоритеты при разработке новых функций. Однако мы понимаем, что не все хотят делиться дополнительной информацией, и мы уважаем вашу конфиденциальность. Вы можете отключить сбор телеметрии, задав переменную окружения HF_HUB_DISABLE_TELEMETRY=1. Телеметрия также отключается в автономном режиме (то есть при установке HF_HUB_OFFLINE=1).

Сбор телеметрии выполняется в отдельном потоке, чтобы минимизировать влияние на пользователя.

>>> from huggingface_hub.utils import send_telemetry

# Send telemetry without library information
>>> send_telemetry("ping")

# Send telemetry to subtopic with library information
>>> send_telemetry("gradio/local_link", library_name="gradio", library_version="3.22.1")

# Send telemetry with additional data
>>> send_telemetry(
...     topic="examples",
...     library_name="transformers",
...     library_version="4.26.0",
...     user_agent={"pipeline": "text_classification", "framework": "flax"},
... )

Проверяет значения, полученные в качестве аргумента для любого публичного метода huggingface_hub.

Цель этого декоратора — согласовать валидацию аргументов, используемых повсеместно. По умолчанию проверяются все определённые валидаторы.

Валидаторы:

• validate_repo_id(): repo_id должен быть "repo_name" или "namespace/repo_name". Namespace — это имя пользователя или организации.
• ~utils.smoothly_deprecate_legacy_arguments: Игнорировать proxies при загрузке файлов (должно устанавливаться глобально).

>>> from huggingface_hub.utils import validate_hf_hub_args

>>> @validate_hf_hub_args
... def my_cool_method(repo_id: str):
...     print(repo_id)

>>> my_cool_method(repo_id="valid_repo_id")
valid_repo_id

>>> my_cool_method("other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

>>> my_cool_method(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

Общее исключение, выбрасываемое валидаторами huggingface_hub.

Наследуется от ValueError.

Проверьте, что repo_id является допустимым.

Это не заменяет полноценную валидацию, выполняемую на Hub, а лишь позволяет по возможности избегать локальных несоответствий (например, передача repo_type в repo_id запрещена).

Правила:

• От 1 до 96 символов.
• Либо «repo_name», либо «namespace/repo_name»
• [a-zA-Z0-9] или ”-”, ”_”, ”.”
• ”—” и “..” запрещены

Допустимые значения: "foo", "foo/bar", "123", "Foo-BAR_foo.bar123"

Недопустимые значения: "datasets/foo/bar", ".repo_id", "foo--bar", "foo.git"

>>> from huggingface_hub.utils import validate_repo_id
>>> validate_repo_id(repo_id="valid_repo_id")
>>> validate_repo_id(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

Обсуждалось в https://github.com/huggingface/huggingface_hub/issues/1008. В moon-landing (внутренний репозиторий):

• https://github.com/huggingface/moon-landing/blob/main/server/lib/Names.ts#L27
• https://github.com/huggingface/moon-landing/blob/main/server/views/components/NewRepoForm/NewRepoForm.svelte#L138

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

Эта функция игнорирует некоторые устаревшие аргументы из kwargs и предупреждает пользователя об их игнорировании. Цель — не ломать существующий код, направляя пользователя к новому способу работы.

Список устаревших аргументов:

• proxies: Для настройки прокси пользователь должен либо использовать переменную окружения HTTP_PROXY, либо вручную настроить httpx2.Client с помощью функции set_client_factory().

  В huggingface_hub 0.x proxies был словарём, который передавался напрямую в requests.request. Начиная с huggingface_hub 1.x, поддержка proxies для отдельных запросов больше не предоставляется. В частности, невозможно настроить прокси для каждого запроса отдельно. Решение — настроить это глобально с помощью функции set_client_factory() или переменной окружения HTTP_PROXY.

  Подробнее см.:

  • https://httpx2.pydantic.dev/advanced/proxies/

• resume_download: устарело без замены. huggingface_hub всегда возобновляет загрузку, когда это возможно.

• force_filename: устарело без замены. Имя файла всегда совпадает с именем на Hub.

• local_dir_use_symlinks: устарело без замены. Загрузка в локальный каталог больше не использует символьные ссылки.