Hugging Face's logo

Hub documentation

Шаблон карточки модели с аннотациями

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Шаблон карточки модели с аннотациями

Готовитесь к публикации? Ознакомьтесь с Model Release Checklist, чтобы узнать о ключевых шагах для создания краткого, информативного и удобного для пользователей релиза модели.

Шаблон

файл modelcard_template.md

Направления

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

Инструкции приведены ниже, курсивом.

Имена переменных шаблона отображаются в monospace.

Название модели

Обзор раздела: Укажите название модели и краткое описание (1–2 предложения) того, что представляет собой модель.

model_id

model_summary

Содержание

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

Детали модели

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

Описание модели

model_description

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

  • Разработано: developers

Перечислите (и по возможности добавьте ссылки на) людей, создавших модель.

  • Финансируется: funded_by

Перечислите (и по возможности укажите ссылки на) источники финансирования, которые финансово, вычислительно или иным образом поддерживали или обеспечивали создание этой модели.

  • Разделено с [необязательно]: shared_by

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

  • Тип модели: model_type

Вы можете указать «type» следующим образом:

1. Метод обучения/контроля

2. Тип машинного обучения

3. Модальность

  • Язык(и) [NLP]: language

Используйте это поле, если система использует или обрабатывает естественный (человеческий) язык.

  • Лицензия: license

Название и ссылка на используемую лицензию.

  • Модель для дообучения [необязательно]: base_model

Если у этой модели есть базовая модель, укажите ссылку на неё здесь.

Источники моделей (необязательно)

  • Репозиторий: repo
  • Статья [необязательно]: paper
  • Демо [необязательно]: demo

Укажите источники, чтобы пользователь мог напрямую увидеть модель и её детали. Дополнительные виды ресурсов — журналы обучения, извлечённые уроки и т. д. — следует размещать в разделе More Information. Если вы включаете в этот раздел только один элемент, сделайте ссылку на репозиторий.

Применение

Обзор раздела: В этом разделе рассматриваются вопросы о том, как модель предполагается использовать в различных прикладных контекстах, обсуждаются потенциальные пользователи модели (включая тех, на кого она влияет), и описываются сценарии, которые считаются вне её области применения или являются её неправомерным использованием. Обратите внимание, что в этот раздел не включаются детали лицензионных условий использования. Для этого следует напрямую ссылаться на лицензию.

Прямое использование

direct_use

Опишите, как модель можно использовать без дообучения, постобработки или подключения к конвейеру. Рекомендуется привести пример кода.

Необязательное использование в прикладных задачах

downstream_use

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

Использование вне области применения

out_of_scope_use

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

Смещение, риски и ограничения

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

  • Смещение — это стереотип или непропорционально высокое/низкое качество работы (искажение) для некоторых подгрупп населения.
  • Риск — это социально значимая проблема, которую может вызвать модель.
  • Ограничение — это вероятный сценарий сбоя, который можно устранить, следуя перечисленным рекомендациям.

bias_risks_limitations

Какие известные или предсказуемые проблемы возникают из-за этой модели?

Рекомендации

bias_recommendations

Какие рекомендации можно дать по поводу предвидимых проблем? Сюда может входить всё: от «уменьшите разрешение изображения» до фильтрации откровенного контента.

Детали обучения

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

Данные для обучения

training_data

Опишите в 1–2 предложениях, что представляет собой данные для обучения. В идеале здесь должна быть ссылка на карточку набора данных с дополнительной информацией. Ссылки на документацию, связанную с предобработкой данных или дополнительным отбором, также могут быть размещены здесь, а также в разделе Дополнительная информация.

Процедура обучения (необязательно)

Предобработка

preprocessing

Детальная токенизация, изменение размера/переписывание (в зависимости от модальности) и т. д.

Скорости, размеры, время

speeds_sizes_times

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

Оценка

Обзор раздела: В этом разделе описаны протоколы оценки, то, что измеряется в ходе оценки, и представлены результаты. Оценка, как правило, состоит как минимум из двух частей: одна из них посвящена количественному измерению общей производительности (Тестовые данные, факторы и метрики), что может осуществляться, например, с помощью бенчмаркинга; другая — оценке производительности в отношении конкретных вопросов социальной безопасности (Оценка влияния на общество), что может осуществляться, например, с помощью red-teaming. Вы также можете указать результаты оценки вашей модели в структурированном виде в метаданных карточки модели. Результаты анализируются Hub и отображаются в виджете на странице модели. См. https://huggingface.co/docs/hub/model-cards#evaluation-results.

Тестирование данных, факторов и метрик

Оценка, как правило, разбивается по различным факторам, таким как задача, область применения и подгруппы населения; при этом используются метрики, наиболее значимые для предвиденных контекстов использования. Если показатели оценки одинаковы для разных подгрупп, это считается «справедливым» по отношению к этим подгруппам; целевые метрики справедливости следует определять исходя из того, какие ошибки с большей вероятностью окажутся проблемными с учётом способа использования модели. Однако данный раздел чаще всего используется для отчёта об агрегированных показателях оценки на различных бенчмарках задач.

Тестовые данные

testing_data

Опишите данные для тестирования или укажите ссылку на их Dataset Card.

Факторы

testing_factors

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

Метрики

testing_metrics

Какие метрики будут использоваться для оценки?

Результаты

results

Результаты должны основываться на Факторах и Метриках, определенных выше.

Краткое описание

results_summary

Что говорят результаты? Это может служить своего рода кратким резюме для широкой аудитории.

Оценка воздействия на общество (необязательно)

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

  • Безопасна ли эта модель для использования детьми? Почему да или почему нет?
  • Было ли проведено тестирование этой модели для оценки рисков, связанных с интимными изображениями, созданными без согласия (включая CSEM)?
  • Проводились ли тесты модели для оценки рисков, связанных с насильственными действиями или изображением насилия? Каковы были результаты?

Также могут быть предоставлены количественные данные по каждой проблеме.

Проверка модели (необязательно)

Обзор раздела: Это экспериментальный раздел, который некоторые разработчики начинают добавлять, и в котором может вестись работа над объяснимостью/интерпретируемостью.

model_examination

Влияние на окружающую среду

Обзор раздела: Краткое описание информации, необходимой для расчёта экологического воздействия, например, потребления электроэнергии и выбросов углерода.

  • Тип оборудования: hardware_type
  • Использовано часов: hours_used
  • Поставщик облачных услуг: cloud_provider
  • Регион вычислений: cloud_region
  • Выбросы углерода: co2_emitted

Углеродные выбросы можно оценить с помощью калькулятора Machine Learning Impact, представленного в работе Lacoste et al. (2019).

Технические характеристики необязательно

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

Архитектура модели и целевая функция

model_specs

Инфраструктура вычислений

compute_infrastructure

Аппаратное обеспечение

hardware_requirements

Каковы минимальные требования к аппаратному обеспечению, например к процессору, хранилищу и памяти?

Программное обеспечение

software

Цитирование необязательно

Обзор раздела: Предпочтительная ссылка разработчиков на эту модель. Как правило, это статья.

BibTeX

citation_bibtex

APA

citation_apa

Словарь терминов (необязательно)

Обзор раздела: В этом разделе определяются общие термины и описывается, как рассчитываются метрики.

glossary

Чётко определяйте термины, чтобы текст был понятен для разных аудиторий.

Дополнительная информация (необязательно)

Обзор раздела: В этом разделе представлены ссылки на материалы о создании наборов данных, технические спецификации, извлечённые уроки и предварительные результаты.

more_information

Авторы карточки модели (необязательно)

Обзор раздела: В этом разделе перечислены люди, создавшие карточку модели, что обеспечивает признание и ответственность за детальную работу, вложенную в её создание.

model_card_authors

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

Обзор раздела: Предоставляет способ для людей, у которых есть обновления к Model Card, предложения или вопросы, связаться с авторами Model Card

model_card_contact

Как начать работу с моделью

Обзор раздела: Приводится фрагмент кода, демонстрирующий, как использовать модель.

get_started_code

Цитирование: Ozoani, Ezi and Gerchick, Marissa and Mitchell, Margaret. Model Card Guidebook. Hugging Face, 2022. https://huggingface.co/docs/hub/en/model-card-guidebook

Update on GitHub

←Часто задаваемые вопросы Руководство по карточкам моделей→