Быстрый старт

Hugging Face Hub — это основная площадка для обмена моделями машинного обучения, демо, наборами данных и метриками. Библиотека huggingface_hub позволяет взаимодействовать с Hub, не покидая среду разработки. Вы можете легко создавать и управлять репозиториями, загружать и скачивать файлы, а также получать полезную метаданную информацию о моделях и наборах данных из Hub.

Установка

Для начала установите библиотеку huggingface_hub:

pip install --upgrade huggingface_hub

Подробнее см. в руководстве по установке.

Библиотека huggingface_hub также поставляется с CLI hf, которая позволяет взаимодействовать с Hub непосредственно из терминала. Если вы используете ИИ-агентов (Claude Code, Codex, Cursor, …), установите Skill, чтобы ваш агент мог использовать CLI:

Скопировано

# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
hf skills add

Подробнее см. в руководстве CLI Hugging Face для ИИ-агентов.

Загрузка файлов

Репозитории на Hub управляются системой контроля версий git, и пользователи могут скачать отдельный файл или весь репозиторий. Для скачивания файлов можно использовать функцию hf_hub_download(). Эта функция скачивает файл и сохраняет его в кэше на локальном диске. В следующий раз, когда вам понадобится этот файл, он будет загружен из кэша, поэтому повторное скачивание не требуется.

Вам понадобится идентификатор репозитория и имя файла, который вы хотите скачать. Например, чтобы скачать файл конфигурации модели Pegasus:

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json")

Чтобы скачать конкретную версию файла, используйте параметр revision, чтобы указать имя ветки, тег или хеш коммита. Если вы решите использовать хеш коммита, он должен быть полным, а не сокращённым 7-символьным:

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(
...     repo_id="google/pegasus-xsum",
...     filename="config.json",
...     revision="4d33b01d79672f27f001f6abade33f22d993b151"
... )

Подробнее об опциях см. в справочнике API для hf_hub_download().

Аутентификация

Во многих случаях для взаимодействия с Hub требуется аутентификация через аккаунт Hugging Face: загрузка частных репозиториев, загрузка файлов, создание PR и т. д. Создайте аккаунт, если у вас его ещё нет.

Команда входа

Самый простой способ аутентификации — команда login():

hf auth login

Если вы уже вошли в систему, команда завершится немедленно. Чтобы принудительно выполнить повторный вход, используйте hf auth login --force. Если вы не вошли в систему, вам будет предложено войти через браузер: откройте напечатанный URL, введите короткий код, подтвердите запрос, после чего токен доступа будет получен и сохранён в вашем каталоге HF_HOME (по умолчанию ~/.cache/huggingface/token). Токен истекает через некоторое время, но обновляется автоматически, пока вы продолжаете его использовать. Любой скрипт или библиотека, взаимодействующие с Hub, будут использовать этот токен при отправке запросов. В качестве альтернативы вы можете вставить User Access Token, сгенерированный на вашей Settings page.

Токены доступа пользователя могут иметь разрешения read или write. Если вы хотите создавать или редактировать репозиторий, убедитесь, что у вас есть токен доступа с правом write. В противном случае лучше сгенерировать токен read, чтобы снизить риски в случае случайной утечки токена.

В качестве альтернативы вы можете выполнить вход в систему программно с помощью login() в ноутбуке или скрипте:

>>> from huggingface_hub import login
>>> login()

Вы можете быть авторизованы только в одном аккаунте одновременно. Вход в новый аккаунт автоматически завершает сессию в предыдущем. Чтобы узнать, в каком аккаунте вы сейчас авторизованы, выполните команду hf auth whoami.

После входа в систему все запросы к Hub — даже методы, для которых аутентификация не требуется, — по умолчанию будут использовать ваш токен доступа. Если вы хотите отключить неявное использование токена, установите переменную окружения HF_HUB_DISABLE_IMPLICIT_TOKEN=1 (см. справку).

Управление несколькими токенами локально

Вы можете сохранить несколько токенов на вашем компьютере, просто выполнив вход с помощью команды login() для каждого токена. Если вам нужно переключаться между этими токенами локально, используйте команду auth switch:

hf auth switch

Эта команда предложит выбрать токен по имени из списка сохранённых токенов. После выбора выбранный токен становится активным и будет использоваться для всех взаимодействий с Hub.

Вы можете получить список всех доступных токенов доступа на вашем компьютере с помощью hf auth list.

Переменная окружения

Переменная окружения HF_TOKEN также может использоваться для аутентификации. Это особенно полезно в Space, где HF_TOKEN можно задать как секрет Space.

НОВОЕ: Google Colaboratory позволяет определять приватные ключи для ваших блокнотов. Определите секрет HF_TOKEN, чтобы автоматически проходить аутентификацию!

Аутентификация через переменную окружения или секрет имеет приоритет над токеном, сохраненным на вашем компьютере.

Параметры метода

Наконец, аутентификацию также можно выполнить, передав ваш токен в любой метод, который принимает token в качестве параметра.

from huggingface_hub import whoami

user = whoami(token=...)

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

Будьте осторожны при передаче токенов в качестве параметра. Лучшая практика — загружать токен из защищённого хранилища, а не хардкодить его в вашем коде или ноутбуке. Хардкодированные токены представляют серьёзный риск утечки, если вы случайно поделитесь своим кодом.

Создать репозиторий

После регистрации и входа в систему создайте репозиторий с помощью функции create_repo():

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model")

Если вы хотите, чтобы ваш репозиторий был закрытым, то:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model", private=True)

Приватные репозитории будут видны только вам.

Чтобы создать репозиторий или отправить содержимое на Hub, необходимо предоставить User Access Token с разрешением write. Вы можете выбрать это разрешение при создании токена на своей странице настроек.

Загрузка файлов

Используйте функцию upload_file(), чтобы добавить файл в только что созданный репозиторий. Необходимо указать:

1. Путь к файлу для загрузки.
2. Путь к файлу в репозитории.
3. Идентификатор репозитория, в который вы хотите добавить файл.

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.upload_file(
...     path_or_fileobj="/home/lysandre/dummy-test/README.md",
...     path_in_repo="README.md",
...     repo_id="lysandre/test-model",
... )

Чтобы загрузить несколько файлов за один раз, обратитесь к руководству Upload, в котором описаны различные способы загрузки файлов (с использованием git и без него).

Дальнейшие шаги

Библиотека huggingface_hub предоставляет удобный способ взаимодействия с Hub на Python. Чтобы узнать, как управлять файлами и репозиториями на Hub, мы рекомендуем ознакомиться с нашими инструкциями:

• Управление репозиторием.
• Скачать файлы с Hub.
• Загрузите файлы в Hub.
• Найдите нужную модель или набор данных, воспользовавшись поиском на Hub.
• Запуск вывода на нескольких сервисах для моделей, размещённых на Hugging Face Hub.