Интеграция вашей библиотеки с Hub

Hugging Face Hub призван упростить обмен моделями машинного обучения, контрольными точками и артефактами. Эта инициатива включает интеграцию Hub со многими замечательными сторонними библиотеками сообщества. Среди уже интегрированных — spaCy, Sentence Transformers, OpenCLIP и timm, а также многие другие. Интеграция означает, что пользователи могут загружать и выгружать файлы в Hub непосредственно из вашей библиотеки. Мы надеемся, что вы интегрируете свою библиотеку и присоединитесь к нам в деле демократизации искусственного интеллекта для всех.

Интеграция Hub с вашей библиотекой предоставляет множество преимуществ, в том числе:

• Бесплатное размещение моделей для вас и ваших пользователей.
• Встроенное версионирование файлов — даже для очень больших файлов — стало возможным благодаря Git-Xet.
• Возможности сообщества (обсуждения, pull requests, лайки).
• Метрики использования для всех моделей, запущенных с вашей библиотекой.

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

Прежде чем начать, рекомендуем создать аккаунт Hugging Face, с помощью которого вы сможете управлять своими репозиториями и файлами.

Если вам нужна помощь с интеграцией, не стесняйтесь открыть issue, и мы будем рады помочь.

Реализация

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

Установка

Чтобы интегрировать вашу библиотеку с Hub, необходимо добавить библиотеку huggingface_hub в зависимости:

pip install huggingface_hub

Для получения подробной информации об установке huggingface_hub ознакомьтесь с этим руководством.

В этом руководстве мы сосредоточимся на библиотеках Python. Если вы реализовали свою библиотеку на JavaScript, вы можете использовать @huggingface/hub вместо неё. Остальная логика (например, размещение файлов, примеры кода и т. д.) не зависит от языка программирования.

Скопировано

npm add @huggingface/hub

После успешной установки библиотеки huggingface_hub пользователям потребуется пройти аутентификацию. Самый простой способ — сохранить токен на машине. Это можно сделать из терминала с помощью команды login():

hf auth login

Команда сообщает, выполнен ли вход, и запрашивает токен. Затем токен проверяется и сохраняется в каталоге HF_HOME (по умолчанию ~/.cache/huggingface/token). Любой скрипт или библиотека, взаимодействующие с Hub, будут использовать этот токен при отправке запросов.

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

from huggingface_hub import login
login()

Аутентификация не требуется при загрузке файлов из публичных репозиториев на Hub.

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

Интеграции позволяют пользователям скачивать модель с Hub и создавать её экземпляр непосредственно из вашей библиотеки. Обычно это становится возможным благодаря предоставлению метода (обычно называемого from_pretrained или load_from_hf), который должен быть специфичен для вашей библиотеки. Чтобы создать экземпляр модели с Hub, ваша библиотека должна:

• загрузить файлы из Hub. Об этом мы и поговорим сейчас.
• создать Python-модель из этих файлов.

Используйте метод hf_hub_download для загрузки файлов из репозитория на Hub. Скачанные файлы сохраняются в кэше: ~/.cache/huggingface/hub. При следующем использовании пользователю не потребуется загружать файл повторно, что значительно экономит время при работе с большими файлами. Кроме того, если в репозиторий добавлена новая версия файла, huggingface_hub автоматически скачает последнюю версию и сохранит её в кэше. Пользователям не нужно беспокоиться о ручном обновлении файлов.

Например, скачайте файл config.json из репозитория lysandre/arxiv-nlp:

>>> from huggingface_hub import hf_hub_download
>>> config_path = hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
>>> config_path
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'

config_path теперь содержит путь к скачанному файлу. Гарантируется, что файл существует и актуален.

Если вашей библиотеке необходимо скачать весь репозиторий, используйте snapshot_download. Он скачает все файлы параллельно. Возвращаемое значение — путь к каталогу, содержащему скачанные файлы.

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'

Существует множество вариантов: загрузка файлов из конкретного ревизии, фильтрация загружаемых файлов, указание кастомного каталога кэша, загрузка в локальный каталог и т. д. Подробности — в руководстве по загрузке.

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

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

• create_repo создаёт репозиторий на Hub.
• upload_file и upload_folder загружают файлы в репозиторий на Hub.

Метод create_repo создаёт репозиторий на Hub. Используйте параметр repo_id, чтобы указать имя вашего репозитория:

>>> from huggingface_hub import create_repo
>>> create_repo(repo_id="test-model")
'https://huggingface.co/lysandre/test-model'

Когда вы зайдёте в свой аккаунт Hugging Face, вы должны увидеть репозиторий test-model в вашем пространстве имён.

Метод upload_file загружает файл в Hub. Для его использования необходимы:

• Путь к файлу для загрузки.
• Последний путь в репозитории.
• Репозиторий, в который вы хотите загрузить файлы.

Например:

>>> from huggingface_hub import upload_file
>>> upload_file(
...    path_or_fileobj="/home/lysandre/dummy-test/README.md", 
...    path_in_repo="README.md", 
...    repo_id="lysandre/test-model"
... )
'https://huggingface.co/lysandre/test-model/blob/main/README.md'

Если вы заглянете в свой аккаунт Hugging Face, вы должны увидеть файл внутри вашего репозитория.

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

>>> from huggingface_hub import upload_folder
>>> upload_folder(
...     folder_path="/home/lysandre/dummy-test",
...     repo_id="lysandre/test-model",
... )

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

Карточки моделей

Карточки моделей — это файлы, сопровождающие модели и содержащие полезную информацию. По сути, карточки моделей — это простые файлы Markdown с дополнительными метаданными. Карточки моделей необходимы для обнаружения, воспроизводимости и обмена! Карточку модели можно найти в виде файла README.md в любом репозитории модели. Подробнее о том, как создать хорошую карточку модели, см. в руководстве по карточкам моделей.

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

Зарегистрируйте вашу библиотеку

Отлично! Теперь у вас есть библиотека, способная загружать модели с Hub и при необходимости публиковать новые. Следующий шаг — убедиться, что ваши модели на Hub хорошо документированы и интегрированы с платформой. Для этого библиотеки можно зарегистрировать на Hub, что приносит пользователям ряд преимуществ:

• на странице модели может отображаться красивая подпись (например, KerasNLP вместо keras-nlp)
• ссылка на репозиторий и документацию вашей библиотеки добавляется на каждую страницу модели
• можно определить собственное правило подсчёта загрузок
• code snippets могут быть сгенерированы, чтобы показать, как загрузить модель с помощью вашей библиотеки

Чтобы зарегистрировать новую библиотеку, создайте Pull Request здесь, следуя инструкциям ниже:

• Идентификатор библиотеки должен быть в нижнем регистре и разделён дефисами (пример: "adapter-transformers"). Убедитесь, что при создании PR сохраняется алфавитный порядок.
• Укажите repoName и prettyLabel с удобной для пользователя регистрацией (пример: DeepForest).
• Укажите repoUrl со ссылкой на исходный код библиотеки (обычно это репозиторий на GitHub).
• (необязательно) задайте docsUrl со ссылкой на документацию библиотеки. Если документация находится в репозитории GitHub, указанном выше, нет необходимости задавать её повторно.
• Установите filter в false.
• (необязательно) задайте способ подсчёта загрузок, установив countDownload. Загрузки можно отслеживать по расширениям файлов или именам файлов. Убедитесь, что подсчёт не дублируется. Например, если для загрузки модели требуется 3 файла, правило подсчёта загрузок должно учитывать загрузку только одного из этих трёх файлов. В противном случае количество загрузок будет завышено. Примечание: если библиотека использует один из файлов конфигурации по умолчанию (config.json, config.yaml, hyperparams.yaml, params.json и meta.yaml, см. здесь), нет необходимости вручную определять правило подсчёта загрузок.
• (необязательно) определите snippets, чтобы пользователь понимал, как быстро создать экземпляр модели. Подробнее ниже.

Перед созданием PR убедитесь, что хотя бы одна модель указана на https://huggingface.co/models?other=my-library-name. Если это не так, метаданные карточек соответствующих моделей необходимо обновить, добавив library_name: my-library-name (см. пример). Если вы не являетесь владельцем моделей на Hub, создайте PR (см. пример).

Вот минимальный пример добавления интеграции для VFIMamba.

Фрагменты кода

Мы рекомендуем добавить фрагмент кода, объясняющий, как использовать модель в вашей библиотеке для прикладных задач.

Чтобы добавить фрагмент кода, необходимо обновить файл model-libraries-snippets.ts с инструкциями для вашей модели. Например, интеграция Asteroid включает краткий фрагмент кода с примером загрузки и использования модели Asteroid:

const asteroid = (model: ModelData) =>
`from asteroid.models import BaseModel
  
model = BaseModel.from_pretrained("${model.id}")`;

Это также добавит тег к вашей модели, чтобы пользователи могли быстро определить модели из вашей библиотеки.

После того как ваш фрагмент будет добавлен в model-libraries-snippets.ts, вы можете сослаться на него в model-libraries.ts, как описано выше.

Документируйте вашу библиотеку

Наконец, вы можете добавить свою библиотеку в документацию Hub. Например, посмотрите на PR Setfit, в котором SetFit была добавлена в документацию.