Hugging Face's logo

Hub Python Library documentation

Создание и обмен карточками моделей

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v2.4.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Создание и обмен карточками моделей

Библиотека huggingface_hub предоставляет интерфейс на Python для создания, обмена и обновления Model Cards. Ознакомьтесь с специальной страницей документации, чтобы подробнее узнать о том, что такое Model Cards на Hub и как они работают.

Загрузка карточки модели из Hub

Чтобы загрузить существующую карточку с Hub, можно использовать функцию ModelCard.load(). Здесь мы загрузим карточку из nateraw/vit-base-beans.

from huggingface_hub import ModelCard

card = ModelCard.load('nateraw/vit-base-beans')

Эта карточка содержит полезные атрибуты, к которым вы можете обратиться или которые можно использовать:

  • card.data: возвращает экземпляр ModelCardData с метаданными карточки модели. Вызовите .to_dict() для этого экземпляра, чтобы получить представление в виде словаря.
  • card.text: возвращает текст карточки, за исключением заголовка метаданных.
  • card.content: возвращает текстовое содержимое карточки, включая заголовок метаданных.

Создание карточек моделей

Из текста

Чтобы инициализировать Model Card из текста, просто передайте текстовое содержимое карточки в ModelCard при инициализации.

content = """
---
language: en
license: mit
---

# My Model Card
"""

card = ModelCard(content)
card.data.to_dict() == {'language': 'en', 'license': 'mit'}  # True

Ещё один способ сделать это — использовать f-строки. В следующем примере мы:

  • Используйте ModelCardData.to_yaml(), чтобы преобразовать определённые нами метаданные в YAML, что позволит вставить YAML-блок в карточку модели.
  • Покажите, как можно использовать переменную шаблона с помощью f-строк Python.
card_data = ModelCardData(language='en', license='mit', library='timm')

example_template_var = 'nateraw'
content = f"""
---
{ card_data.to_yaml() }
---

# My Model Card

This model created by [@{example_template_var}](https://github.com/{example_template_var})
"""

card = ModelCard(content)
print(card)

Приведённый выше пример оставил бы нам карточку, выглядящую следующим образом:

---
language: en
license: mit
library: timm
---

# My Model Card

This model created by [@nateraw](https://github.com/nateraw)

Из шаблона Jinja

Если у вас установлен Jinja2, вы можете создавать Model Cards из файла шаблона jinja. Рассмотрим базовый пример:

from pathlib import Path

from huggingface_hub import ModelCard, ModelCardData

# Define your jinja template
template_text = """
---
{{ card_data }}
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@{{ author }}](https://hf.co/{{author}}).
""".strip()

# Write the template to a file
Path('custom_template.md').write_text(template_text)

# Define card metadata
card_data = ModelCardData(language='en', license='mit', library_name='keras')

# Create card from template, passing it any jinja template variables you want.
# In our case, we'll pass author
card = ModelCard.from_template(card_data, template_path='custom_template.md', author='nateraw')
card.save('my_model_card_1.md')
print(card)

Markdown-код полученной карточки выглядит так:

---
language: en
license: mit
library_name: keras
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@nateraw](https://hf.co/nateraw).

Если вы обновите card.data, изменения отобразятся в самой карточке.

card.data.library_name = 'timm'
card.data.language = 'fr'
card.data.license = 'apache-2.0'
print(card)

Теперь, как вы видите, заголовок метаданных был обновлён:

---
language: fr
license: apache-2.0
library_name: timm
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@nateraw](https://hf.co/nateraw).

По мере обновления данных карточки вы можете проверить её валидность на Hub, вызвав ModelCard.validate(). Это гарантирует, что карточка соответствует всем правилам валидации, установленным на Hugging Face Hub.

Из шаблона по умолчанию

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

Обратите внимание, что для использования from_template необходимо установить Jinja2. Сделать это можно с помощью pip install Jinja2.

card_data = ModelCardData(language='en', license='mit', library_name='keras')
card = ModelCard.from_template(
    card_data,
    model_id='my-cool-model',
    model_description="this model does this and that",
    developers="Nate Raw",
    repo="https://github.com/huggingface/huggingface_hub",
)
card.save('my_model_card_2.md')
print(card)

Общие карточки моделей

Если вы аутентифицированы в Hugging Face Hub (с помощью hf auth login или login()), вы можете отправить карточки в Hub, просто вызвав ModelCard.push_to_hub(). Давайте посмотрим, как это сделать…

Сначала мы создадим новый репозиторий с именем ‘hf-hub-modelcards-pr-test’ в пространстве имён аутентифицированного пользователя:

from huggingface_hub import whoami, create_repo

user = whoami()['name']
repo_id = f'{user}/hf-hub-modelcards-pr-test'
url = create_repo(repo_id, exist_ok=True)

Затем мы создадим карточку из шаблона по умолчанию (такого же, как определён в разделе выше):

card_data = ModelCardData(language='en', license='mit', library_name='keras')
card = ModelCard.from_template(
    card_data,
    model_id='my-cool-model',
    model_description="this model does this and that",
    developers="Nate Raw",
    repo="https://github.com/huggingface/huggingface_hub",
)

Наконец, мы загрузим его на хаб

card.push_to_hub(repo_id)

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

Если же вы хотите отправить карточку в виде pull request, просто укажите create_pr=True при вызове push_to_hub:

card.push_to_hub(repo_id, create_pr=True)

Созданную с помощью этой команды PR можно посмотреть здесь.

Обновить метаданные

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

metadata — это хеш-карта (или контекст пар «ключ-значение»), содержащая высокоуровневую информацию о модели, наборе данных или Space. Эта информация может включать такие детали, как pipeline type, model_id или model_description. Более подробную информацию вы можете найти в этих руководствах: Model Card, Dataset Card и Spaces Settings. Теперь рассмотрим несколько примеров того, как обновлять эти метаданные.

Начнем с первого примера:

>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "image-classification"})

С помощью этих двух строк кода вы обновите метаданные, задав новое значение pipeline_tag.

По умолчанию вы не можете обновить ключ, который уже существует на карте. Если вы хотите это сделать, необходимо явно передать overwrite=True:

>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "text-generation"}, overwrite=True)

Часто возникает необходимость предложить изменения в репозиторий, на который у вас нет прав на запись. Вы можете сделать это, создав PR в этом репозитории, что позволит владельцам просмотреть и объединить ваши предложения.

>>> from huggingface_hub import metadata_update
>>> metadata_update("someone/model", {"pipeline_tag": "text-classification"}, create_pr=True)

Включить результаты оценки

Чтобы включить результаты оценки в метаданные model-index, вы можете передать EvalResult или список EvalResult с соответствующими результатами оценки. При вызове card.data.to_dict() под капотом создаётся model-index. Подробнее о том, как это работает, можно узнать в этом разделе документации Hub.

Обратите внимание, что для использования этой функции необходимо включить атрибут model_name в ModelCardData.

card_data = ModelCardData(
    language='en',
    license='mit',
    model_name='my-cool-model',
    eval_results = EvalResult(
        task_type='image-classification',
        dataset_type='beans',
        dataset_name='Beans',
        metric_type='accuracy',
        metric_value=0.7
    )
)

card = ModelCard.from_template(card_data)
print(card.data)

Полученный card.data должен выглядеть так:

language: en
license: mit
model-index:
- name: my-cool-model
  results:
  - task:
      type: image-classification
    dataset:
      name: Beans
      type: beans
    metrics:
    - type: accuracy
      value: 0.7

Если у вас есть несколько результатов оценки, которые вы хотите опубликовать, просто передайте список EvalResult:

card_data = ModelCardData(
    language='en',
    license='mit',
    model_name='my-cool-model',
    eval_results = [
        EvalResult(
            task_type='image-classification',
            dataset_type='beans',
            dataset_name='Beans',
            metric_type='accuracy',
            metric_value=0.7
        ),
        EvalResult(
            task_type='image-classification',
            dataset_type='beans',
            dataset_name='Beans',
            metric_type='f1',
            metric_value=0.65
        )
    ]
)
card = ModelCard.from_template(card_data)
card.data

В результате у вас должна получиться следующая card.data:

language: en
license: mit
model-index:
- name: my-cool-model
  results:
  - task:
      type: image-classification
    dataset:
      name: Beans
      type: beans
    metrics:
    - type: accuracy
      value: 0.7
    - type: f1
      value: 0.65
Update on GitHub

←Кэш Управление вашим Space→