Формат и документация датасетов MERA

July 15, 2025 · View on GitHub

Содержание страницы:

Формат датасета
- Структура файлов
- Структура вопросов
Документация датасета
Автосборка документации
➡️ Следующий шаг: загрузка датасета на 🤗HF

Разработанный датасет нужно оформить по описанной ниже структуре. Можно идти по описанию сверху вниз как по инструкции, пользуясь кросс-ссылками на разделы, поясняющие детали каждого этапа.

Формат датасета

Структура файлов

Датасет хранится в виде папки со структурированными файлами.

❗️ В репозиторий выкладываются только некоторые файлы, в структуре ниже они отмечены восклицательным знаком. Это файлы, документирующие датасет и его параметры. Остальные файлы, хранящие сам датасет, будут загружены только на Hugging Face Hub (это следующий этап).

❗️ Часть файлов автособираемые, то есть их не нужно создавать вручную, они создаются скриптом на основе файлов с префиксом raw_ (которые создаются вручную). В структуре ниже автособираемые файлы помечены символом доллара.

Структура папки:

dataset_name (название датасета)/
├── !$README.md$!  # автособираемая документация (англ)
├── !$README_ru.md$!  # автособираемая документация (рус)
├── !$dataset_meta.json$!  # автособираемая метаинформация
├── !raw_readme_en.json!  # документация вручную (англ)
├── !raw_readme_ru.json!  # документация вручную (рус)
├── !raw_dataset_meta.json!  # метаинформация вручную
├── test.json  # основные вопросы теста (не класть в репо, только на HF)
├── shots.json  # вопросы для few-shot примеров (не класть в репо, только на HF)

Все вопросы датасета хранятся в двух файлах:

test.json — основные вопросы теста
shots.json — вопросы-примеры для few-shot режима (❗️не должны повторять ни вопросы, ни медиа из основного теста❗️)

Структура файлов:

test.json
{
    "access": "", //"private" у приватного датасета, "public" у публичного
    "data": [
        // вопросы датасета, их структура описана ниже (см. Структура вопросов)
    ]
}

shots.json
{
    "data": [
        // вопросы датасета, их структура описана ниже (см. Структура вопросов)
    ]
}

Структура вопросов

В этом разделе рассмотрена структура вопросов, хранящихся в поле data файлов test.json и shots.json. Описание каждого поля приведено ниже.

{
    "instruction": int, // int в исходном файле датасета, str при загрузке на HF Hub
    "inputs": {
        // все поля, необходимые для генерации в вашем датасете
    },
    "outputs": str | list,
    "meta": {
        "id": int,
        // все дополнительные поля из вашего датасета
    }
}

`instruction` — промпт-инструкция

Индекс одного из заданных для датасета промптов с плейсхолдерами. Промпты хранятся в метаданных датасета в поле prompts. Подробно о подготовке промптов написано здесь.

На следующем этапе, когда датасет будет выгружаться в HF Hub, по этому индексу промпт будет вставлен автоматически из списка в метаданных датасета в поле prompts. Таким образом, если в дальнейшем потребуется внести изменения в формулировки промптов, менять их нужно только в метаданных, а затем заново выгружать датасет.

❗️Промпты должны быть равномерно распределены по вопросам датасета.

`inputs` — входные данные для вопроса

Словарь с полями, набор которых должен соответствовать набору плейсхолдеров в соответствующем промпте.

`meta` — метаинформация об элементах вопроса

В это поле включается вся сопровождающая информация к вопросу и используемым в нем мультимодальным элементам. Эта информация ни в коем случае не используется в самом вопросе и промпте, а нужна для анализа статистик датасета и детальной оценки ответов моделей. Если какое-то поле может давать потенциальный ключ к ответу (например, в метаинформации есть поле с hints для CoT), это нужно указать в описании поля в метаинформации.

`id` — номер вопроса

Вопросы нумеруются с 1, нумерация сквозная для всех вопросов, включая вопросы для shots.

Другие поля

Внутри meta можно добавлять любые другие поля.

Документация датасета

Написание документации для датасетов MERA автоматизировано, так что автор датасета заполняет только информацию, которая уникальна для этого датасета, а все универсальные описания автоматически подтягиваются из шаблона.

Документация состоит из двух частей:

raw_readme_ru.json и raw_readme_en.json – текстовые описания (описание задачи и методология создания датасета) на русском и английском в отдельных файлах;
raw_dataset_meta.json – JSON с формальными характеристиками датасета.

Файлы должны соответствовать требованиям к формату json, таким как отсутствие trailing commas и trailing whitespaces. Отступ (indent) – 4 символа, ensure_ascii=False (файл должен быть человекочитаемым).

Текстовые описания (`raw_readme_ru.md`и `raw_readme_en.md`)

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

Каждый из двух файлов должен содержать словарь с заголовками и текстами следующих разделов документации:

Поле ru	Поле en	Описание поля
Описание задачи	Task description	Описание датасета с кратким саммари по мотивации и методологии создания. Самая основная информация, сопроводительный текст к датасету. Обязательно нужно указать количество семплов в датасете.
Мотивация	Motivation	Этот раздел должен разносторонне отвечать на вопрос "зачем эта задача?". Вопросы для ориентира: - На оценку каких моделей ориентирован этот датасет? Для каких моделей он НЕ подходит (limitations)? - На каких пользователей ориентированы результаты оценки на данной задаче? Как эти пользователи будут интерпретировать результаты, полученные при оценке на этом датасете? - Какие способности моделей оценивает задача? Что подразумевается под этими способностями? Не просто language understanding, а что именно и в какой постановке. Зачем оценивать именно эти способности? - Как устроены вопросы в датасете, и почему они устроены именно так? Как понять, что именно такой дизайн задачи оценивает те способности моделей, которые нужно оценить? Валидность эксперимента. - Как выбраны метрики (особенно когда метрика не просто доля правильных ответов) и почему они именно такие? Как такой выбор метрик помогает пользователю интерпретировать результаты?
Создание датасета	Dataset creation	Подробное описание методологии сбора датасета, источников данных, отбора данных, процесса валидации вопросов.
Авторы	Contributors	Список строк-имен разработчиков датасета в формате "Имя Фамилия".

Формат файла:

raw_readme_ru.json
{
    "Заголовок раздела 1": "текст раздела\nсо\nвсеми\nпереносами",
    "Заголовок раздела 2": "текст с\n\n### вложенными\nзаголовками"
}

Добавление верхнеуровневых полей помимо перечисленных в таблице не предусмотрено. Внутри разделов можно использовать любую структуру в формате MD с подзаголовками уровня "### Заголовок" и ниже. Формат: ровно 1 пустая строка (\n\n) между заголовком и телом раздела, не более одной пустой строки внутри раздела.

Метаданные датасета (`raw_dataset_meta.json`)

Этот файл содержит словарь с формальными признаками датасета, используемыми для автособираемой документации (карточки датасета). Словарь содержит рассчитываемые поля (как, например, "len(DATA)"), которые будут пересчитаны на основе файлов датасета.

❗️ Этот файл — "истина в последней инстанции" по датасету. В нем должны отражаться все вносимые изменения. Например, название датасета во всех случаях берется именно из файла с метаданными.

Название поля	Описание поля
`dataset_name`	Название датасета. Пишется в CamelCase или CAPITALS, за исключением случаев адаптации других датасетов для русского языка – в этом случае называются в виде ruCamelCase / ruCAPITALS.
`description`	Короткое описание задачи (на английском языке), общая идея (максимум 200 символов).
`license`	Для публичного датасета: лицензия на материалы из оригинального датасета. Даже если из него переиспользована только часть (например, только картинки или только вопросы), лицензия все равно должна сохраняться. Формат: строка с md-форматированием, то есть если у лицензии помимо названия есть страница с описанием, пишем в виде [license name](url). Для приватного датасета: "MERA_private".
`dataset_size`	Рассчитываемое поле. Оставить `"len(DATA)"`, будет рассчитано и вставлено при автосборке карточки.
`modalities`	Список модальностей из ["text", "image", "audio", "video"]. Текстовая модальность включается всегда, если в случае конкретного датасета не оговорено иное.
`skills`	Список навыков, на которые ориентирован тест. Список может быть скорректирован в процессе ревью датасета.
`domains`	Домены датасета в случае разделения на домены-папки, иначе пустой список.
`data_example`	Пример данных из оформленного по инструкции датасета с точным соблюдением формата и набора полей. Пример не должен дублировать никакие вопросы из основного теста. Мультимодальные данные для примера нельзя брать из теста.
`data_field_descriptions`	Описания полей `data_example`. Тип данных поля в описании указывать не нужно, он автоматически берется из значений в `data_example`. Описание для каждого поля на русском и английском в формате `{"field_name": {"en": "Description.", "ru": "Описание."}}`. Если подходящее датасету описание такого поля есть в term_dictionary.json, то пишется `"en": "default"` и `"ru": "default"` соответственно, иное значение описания только если дефолтное не подходит.
`prompts`	Промпты с плейсхолдерами. Набор плейсхолдеров в каждом промпте должен соответствовать набору полей в `data_example["inputs"]`. В общем случае промптов должно быть не менее 10. В случае датасетов с доменами — не менее 10 промптов на каждый домен. Как оформлять промпты?
`metrics`	Словарь из названий и описаний метрик, используемых для оценки. Есть словарь с дефолтными описаниями метрик `term_dictionary.json` – в случае, когда в этом словаре есть нужная метрика с подходящим описанием, описание дублировать не нужно, достаточно вместо него написать "default" (`{"metric_name": {"en": "default", "ru": "default"}}`). Соответственно, иное значение описания нужно писать только в случае если дефолтное не подходит.

Как оформлять промпты

Формат:

Промпт задается в виде строки с плейсхолдерами. Набор плейсхолдеров должен в точности соответствовать набору поле в поле inputs вопросов датасета. Текстовые плейсхолдеры (то есть куда будут вставляться текстовые элементы) пишутся в фигурных скобках {} ({question}).

Пример валидного промпта:

"На вход подается функция(ии) с описанием в виде строки docstring. В соответствии с описанием вам необходимо реализовать функцию(ии)\n{function}"

Требования к промптам:

Промпты-инструкции должны быть достаточно разнообразны и однозначны. Разнообразие может достигаться разными способами: например, можно чередовать в промптах обращения на ВЫ и на ТЫ или менять порядок мест вопроса / описания формата.
Инструкция должна точно описывать формат вывода ответа. Его в дальнейшем нам необходимо парсить, и инструктивная модель должна знать в каком виде писать ответ.
В инструкциях не должно быть опечаток, странных форм слов, отсутствия согласования и тд. Советуем проверять проверкой орфографии.
Если промпт предполагает какое-то прямое продолжение, например, заканчивается на "Ответ:", то убедитесь, что там нет пробелов, переносов строк и других лишних символов, которые могут помешать модели продолжать промпт.

Автосборка документации

Для автосборки документации нужно подготовить 3 файла:

raw_dataset_meta.json
raw_readme_en.json
raw_readme_ru.json

Далее сложить их в папку datasets/ в репо и запустить скрипт, который провалидирует формат полей и, если все корректно, соберет 3 чистовых файла:

dataset_meta.json
README.md
README_ru.md

Запускать скрипт из корня репо, подставить название папки с датасетом вместо YOUR_DATASET:

python scripts/autocollect_docs.py "YOUR_DATASET"

В результате будут созданы следующие файлы:

datasets/YOUR_DATASET/dataset_meta.json
datasets/YOUR_DATASET/README.md
datasets/YOUR_DATASET/README_ru.md

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

Следующий шаг

Оформленный датасет нужно выложить на 🤗 Hugging Face Hub и отправить организаторам MERA, этот процесс описан в отдельной инструкции.