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

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

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

Карточка модели должна описывать:

• модель
• предназначенные области применения и потенциальные ограничения, включая предвзятость и этические аспекты, подробно описанные в работе Mitchell, 2018
• параметры обучения и экспериментальная информация (можно встроить или добавить ссылку на платформу отслеживания экспериментов для справки)
• какие наборы данных использовались для обучения вашей модели
• результаты оценки модели

Шаблон карточки модели доступен здесь.

Описание того, как заполнить каждый раздел карточки модели, приведено в Annotated Model Card.

Карточки моделей на Hub состоят из двух основных частей, содержащих пересекающуюся информацию:

• Метаданные
• Текстовые описания

Метаданные карточки модели

Репозиторий модели отображает свой README.md в виде карточки модели. Карточка модели — это файл Markdown с секцией YAML в начале, содержащей метаданные о модели.

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

• Позволяет пользователям фильтровать модели на https://huggingface.co/models.
• Отображение лицензии модели.
• Добавление наборов данных в метаданные добавит на страницу вашей модели сообщение Datasets used to train: и свяжет соответствующие наборы данных, если они доступны на Hub.

Идентификаторы наборов данных и языков — это те, что перечислены на страницах Datasets и Languages.

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

Существует несколько способов добавить метаданные в вашу карточку модели, в том числе:

• Использование пользовательского интерфейса метаданных
• Прямое редактирование раздела YAML в файле README.md
• С помощью библиотеки Python huggingface_hub, подробности см. в документации.

Многие библиотеки с интеграцией с Hub автоматически добавляют метаданные в карточку модели при её загрузке.

Использование пользовательского интерфейса метаданных

Вы можете добавить метаданные в карточку модели с помощью интерфейса метаданных. Чтобы открыть этот интерфейс, перейдите на страницу модели и нажмите кнопку Edit model card в правом верхнем углу карточки модели. Откроется редактор, в котором отображается файл README.md карточки модели, а также интерфейс для редактирования метаданных.

С помощью этого интерфейса вы можете добавить ключевые метаданные в карточку вашей модели, при этом многие поля будут заполняться автоматически на основе предоставленной вами информации. Использование интерфейса — самый простой способ добавить метаданные в карточку модели, однако он не поддерживает все поля метаданных. Если вам нужно добавить метаданные, которые не поддерживаются интерфейсом, вы можете напрямую отредактировать секцию YAML в файле README.md.

Редактирование раздела YAML в файле README.md

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

---
language: 
  - "List of ISO 639-1 code for your language"
  - lang1
  - lang2
thumbnail: "url to a thumbnail used in social sharing"
tags:
- tag1
- tag2
license: "any valid license identifier"
datasets:
- dataset1
- dataset2
base_model: "base model Hub identifier"
---

Подробную спецификацию метаданных карточки модели можно найти здесь.

Указание библиотеки

Вы можете указать поддерживаемые библиотеки в разделе метаданных карточки модели. Подробнее о поддерживаемых библиотеках можно узнать здесь. Библиотека будет определена в следующем порядке приоритета:

1. Указание library_name в карточке модели (рекомендуется, если ваша модель не является моделью transformers). Эту информацию можно добавить через интерфейс метаданных или непосредственно в YAML-разделе карточки модели:

library_name: flair

2. Наличие тега с названием поддерживаемой библиотеки

tags:
- flair

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

1. Определяя наличие файлов, таких как *.nemo или *.mlmodel, Hub может установить, что модель принадлежит к NeMo или CoreML.
2. Ранее, если библиотека не определялась, а файл config.json присутствовал, предполагалось, что используется библиотека transformers. Для репозиториев моделей, созданных после августа 2024 года, это правило больше не действует, поэтому необходимо явно указать library_name: transformers.

Указание базовой модели

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

base_model: HuggingFaceH4/zephyr-7b-beta

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

Для дообученной модели:

Для адаптера (LoRA, PEFT и т. д.):

Для квантованной версии другой модели:

Для слияния двух или более моделей:

В случае слияния вы указываете список из двух или более base_models:

base_model:
- Endevor/InfinityRP-v1-7B
- l3utterfly/mistral-7b-v0.1-layla-v4

Hub определит тип связи между текущей моделью и базовой моделью ("adapter", "merge", "quantized", "finetune"), но при необходимости вы можете задать его явно, например: base_model_relation: quantized.

Указание новой версии

Если в Hub доступна новая версия вашей модели, вы можете указать её в поле new_version.

Например, на l3utterfly/mistral-7b-v0.1-layla-v3:

new_version: l3utterfly/mistral-7b-v0.1-layla-v4

Эти метаданные будут использоваться для отображения ссылки на последнюю версию модели на странице модели. Если модель, указанная в new_version, также имеет поле new_version, будет отображаться самая последняя версия.

Указание набора данных

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

datasets:
- stanfordnlp/imdb
- HuggingFaceFW/fineweb

Указание бакета

Вы можете указать storage buckets, связанные с вашей моделью, в разделе метаданных карточки модели. Эти buckets будут отображаться в виде тегов на странице модели, а на страницах связанных buckets, в свою очередь, будет показана модель. Используйте идентификатор bucket на Hub, который совпадает с именем репозитория bucket:

buckets:
- my-org/my-bucket
- my-org/another-bucket

Указание задачи (pipeline_tag)

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

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

Указание лицензии

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

При необходимости вы также можете указать собственную лицензию, добавив other в качестве значения лицензии и указав название и ссылку на лицензию в метаданных.

# Example from https://huggingface.co/coqui/XTTS-v1
---
license: other
license_name: coqui-public-model-license
license_link: https://coqui.ai/cpml
---

Если лицензия недоступна по URL, вы можете указать ссылку на файл LICENSE, хранящийся в репозитории модели.

Результаты оценки

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

The initial metadata spec was based on Papers with code’s model-index specification. This allowed us to directly index the results into Papers with code’s leaderboards when appropriate. You could also link the source from where the eval results has been computed.

NEW: У нас появился новый, более простой формат метаданных для результатов оценки. Ознакомьтесь с ним на специальной странице документации.

Ниже приведён частичный пример model-index, описывающий результат 01-ai/Yi-34B на бенчмарке ARC. Результат был получен из Open LLM Leaderboard, который указан как source:

---
model-index:
  - name: Yi-34B
    results:
      - task:
          type: text-generation
        dataset:
          name: ai2_arc
          type: ai2_arc
        metrics:
          - name: AI2 Reasoning Challenge (25-Shot)
            type: AI2 Reasoning Challenge (25-Shot)
            value: 64.59
        source:
          name: Open LLM Leaderboard
          url: https://huggingface.co/spaces/open-llm-leaderboard/open_llm_leaderboard
---

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

Выбросы CO2

Карточка модели — отличное место, чтобы показать информацию о влиянии вашей модели на уровень CO₂. Ознакомьтесь с нашим руководством по отслеживанию и отчетности выбросов CO₂, чтобы узнать больше.

Связывание статьи

Если карточка модели содержит ссылку на страницу статьи (на HF или на аннотацию/PDF в Arxiv), Hugging Face Hub извлечёт идентификатор arXiv и добавит его в теги модели в формате arxiv:<PAPER ID>. Нажатие на тег позволит вам:

• Перейдите на страницу статьи
• Фильтр для других моделей на Hub, ссылающихся на ту же статью.

Подробнее о страницах Paper можно прочитать здесь.

Текст карточки модели

Подробности о том, как заполнить часть карточки модели, предназначенную для чтения человеком (чтобы её можно было распечатать, вырезать и вставить и т. д.), доступны в Annotated Model Card.

Часто задаваемые вопросы

Как определяются теги модели?

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

Можно ли добавить пользовательские теги к моей модели?

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

Как указать, что моя модель не подходит для всех аудиторий

Вы можете добавить тег not-for-all-audiences в метаданные карточки модели. Если этот тег присутствует, на странице модели будет отображаться сообщение о том, что модель не предназначена для всех аудиторий. Пользователи могут перейти по этому сообщению, чтобы просмотреть карточку модели.

Как отобразить разные изображения для тёмной и светлой темы?

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

Для изображений, загруженных через markdown-редактор

При загрузке изображения непосредственно из редактора Markdown (с помощью перетаскивания) добавьте фрагмент URI #hf-light-mode-only или #hf-dark-mode-only в конец URL изображения, чтобы указать, в какой теме оно должно отображаться:

Image only displays when viewing in light mode
![Logo](https://huggingface.co/proxy/cdn-uploads.huggingface.co/production/uploads/logo-light.png#hf-light-mode-only)

Image only displays when viewing in dark mode
![Logo](https://huggingface.co/proxy/cdn-uploads.huggingface.co/production/uploads/logo-dark.png#hf-dark-mode-only)

Для уже размещённых изображений

Если вы хотите ссылаться на изображения, которые уже размещены, без их повторной загрузки, используйте HTML-теги <img> со следующими классами Tailwind CSS, чтобы указать, в какой теме они должны отображаться:

// Image only displays when viewing in dark mode
<img class="hidden dark:block" src="https://hf.co/logo-dark.png" alt="Logo" />

// Image only displays when viewing in light mode
<img class="dark:hidden" src="https://hf.co/logo-light.png" alt="Logo" />

Можно ли использовать LaTeX в карточке модели?

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

Вы должны использовать следующие разделители:

• $$ ... $$ для режима отображения
• \\(...\\) для режима inline (без пробелов между косыми чертами и скобками).

Затем вы сможете написать: $$\LaTeX$$ $$\mathrm{MSE} = \left(\frac{1}{n}\right)\sum_{i=1}^{n}(y_{i} - x_{i})^{2}$$ $$E=mc^2$$