Как собрать собственный датасет из метаданных Hugging Face Hub — разбор учебного пайплайна

Датасет о датасетах

Учебный разбор tegridydev показывает, как собрать датасет с нуля на метаданных Hugging Face Hub: каждая строка описывает один репозиторий датасета — имя, теги, число скачиваний, языки и прочее, то есть то, что обычно видно при просмотре Hub. Собирается до 1 000 репозиториев, отсортированных по скачиваниям за последние 30 дней: этого достаточно, чтобы увидеть разнообразие метаданных и сохранить файлы управляемого размера.

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

Запуск и структура результата

Нужен только Python 3.10 или новее и интернет: скрипт использует встроенные средства Python, поэтому дополнительных установок и авторизации на Hugging Face не требуется. Скрипт сохраняется как build_dataset.py и запускается командой python build_dataset.py — на macOS и Linux обычно python3, на Windows py -3.

Каждый запуск создаёт отдельную папку вида dataset_output/<уникальная папка> с двумя разделами: RAWDATA с response.json и collection.json, а также PROCESSED с datasets.jsonl, CSV-отчётами, insights.txt, summary.json и README.md. Итоговая папка переименовывается в PROCESSED только после записи и проверки, поэтому незавершённый прогон не выглядит готовым.

Сырые данные отдельно от обработанных

До любых преобразований скрипт сохраняет ответ API побайтово в RAWDATA/response.json — это исходный снимок, по которому можно проверить, что именно вернул Hub, если обработанные данные выглядят странно. Рядом лежит collection.json с описанием запроса, временем сбора и версией скрипта.

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

Запрос к Hub API

Данные запрашиваются у Hugging Face Hub API обычными HTTP-параметрами: sort=downloads, direction=-1 и limit со значением 1000, то есть до тысячи результатов от самых скачиваемых. Поле expand выбирает возвращаемые метаданные — downloads, likes, tags, citation и sha, — но не гарантирует, что у каждого репозитория есть значение для каждого поля.

Запрашивается только одна страница: скрипт не идёт по ссылкам дальше, а увеличение limit не заменяет пагинацию — для этого нужен официальный SDK huggingface_hub, где метод list_datasets берёт пагинацию и обработку лимитов на себя.

Поле sha хранит идентификатор ревизии репозитория и даёт дополнительную точку отсчёта, но не фиксирует число скачиваний и другие изменяющиеся метаданные — поэтому отдельно записывается время сбора.

Ошибки, повторы и лимиты

Временные проблемы с соединением и часть серверных ошибок приводят к трём попыткам; при HTTP 429 скрипт читает Retry-After и время сброса из заголовка RateLimit и уважает большую из корректных задержек. Если ожидание превышает 60 секунд, работа останавливается с указанием, сколько нужно подождать до следующего запуска.

Анонимные лимиты Hub считаются по IP-адресу, поэтому активность других устройств в той же сети тоже влияет на результат. Ошибка проверки сертификата означает, что стоит проверить часы и сертификаты Python, не отключая проверку HTTPS. Ошибки прав или места на диске оставляют неполную папку: RAWDATA сохранит ответ, если он успел записаться, а PROCESSING — незавершённые результаты, и повторный запуск создаст отдельную папку.

Обработка и честные пропуски

Обработка в этом проекте означает приведение ответа к согласованным полям: теги вида language:en, task_categories:text-classification и format:parquet сохраняются, а полезные части извлекаются в отдельные списки languages, task_categories и formats, чтобы форматы можно было считать без повторного перебора всех тегов. Категории задач и темы — разные вещи: «классификация текста» описывает действие, а «кибербезопасность» — тему, и для собственных тематических меток нужен отдельный столбец.

Пропуски не подменяются нулями: отсутствующее число скачиваний и ноль — разные значения, поэтому скрипт оставляет отсутствующие счётчики отсутствующими, а пустой список тегов формата отличается от отсутствующего списка. В прогоне на 1 000 записей 9 сентября 2026 года 369 записей обошлись без тегов формата, а 987 не вернули текст цитирования, — это не значит, что у таких репозиториев нет файлов или цитирования, это значит, что конкретный ответ их не содержал.

Проверки и отчёты

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

Основной датасет сохраняется в JSONL, где на строке один JSON-объект: так списки тегов, языков и форматов не приходится упаковывать в одну ячейку таблицы. В примере записи — репозиторий KakologArchives/KakologArchives с 2 509 960 скачиваний, 82 лайками, тегами task_categories:text-classification и language:ja, пустым списком форматов и отсутствующим текстом цитирования.

Отчёты сохраняются отдельными CSV-файлами: task_categories_counts.csv, languages_counts.csv, formats_counts.csv, tags_counts.csv и owners.csv — плюс README.md с описанием полей и метода сбора. В прогоне 9 сентября 2026 года чаще всего возвращался тег imagefolder — 328 репозиториев, у parquet — 215, что составляет 21,5% выборки; при этом по 369 репозиториям тегов формата не было вовсе, поэтому утверждать, что только 215 из них содержат Parquet, нельзя.

Что даёт такой пайплайн

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

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