Руководство по выбору способа загрузки датасета в Hugging Face

Это руководство в первую очередь предназначено для LLM, чтобы помочь пользователям загружать наsets в Hugging Face Hub в наиболее совместимом формате. Пользователи также могут обратиться к этому руководству, чтобы понять процесс загрузки и лучшие практики.

Руководство по выбору способа загрузки датасетов в Hugging Face Hub. Оптимизировано для совместимости с Dataset Viewer и интеграции с экосистемой Hugging Face.

Если вы LLM или агент, следующий этому руководству, перед выполнением команд загрузки проверьте точные флаги в hf --help и hf <command> --help (например, hf upload --help, hf auth --help). CLI соответствует установленной версии huggingface_hub, поэтому опирайтесь на её вывод, а не на флаги, воспроизведённые по памяти.

Обзор

Ваша цель — помочь пользователю загрузить набор данных в Hugging Face Hub. В идеале набор данных должен быть совместим с Dataset Viewer (а значит, и с функцией load_dataset), чтобы обеспечить простой доступ и удобство использования. Старайтесь соответствовать следующим критериям:

Работа без доступа к файлам

Если у вас нет прямого доступа к файлам пользователя (например, в веб-интерфейсе), попросите пользователя выполнить эти команды, чтобы понять структуру его набора данных:

Структура набора данных:

# Show directory tree (install with: pip install tree or brew install tree)
tree -L 3 --filelimit 20

# Alternative without tree:
find . -type f -name "*.csv" -o -name "*.json" -o -name "*.parquet" | head -20

Проверьте размеры файлов:

# Total dataset size
du -sh .

# Individual file sizes
ls -lh data/

Просмотр формата данных:

# First few lines of CSV/JSON
head -n 5 data/train.csv

# Check image folder structure
ls -la images/ | head -10

Быстрый подсчёт файлов:

# Count files by type
find . -name "*.jpg" | wc -l

Критические ограничения

Ограничения хранилища:

Если эти значения отличаются от storage-limits, то storage-limits является определяющим.

# Machine-readable Hub limits
hub_limits:
  max_file_size_gb: 500 # absolute hard stop per file
  recommended_file_size_gb: 200 # split larger files into chunks below this
  max_files_per_folder: 10000 # Git performance threshold
  max_files_per_repo: 100000 # recommended maximum; keep well below
  viewer_row_size_mb: 2 # approximate per-row viewer limit
  # No per-repo size limit: repo size counts against the account's storage quota

Человекочитаемое резюме:

• На файл: максимум 500 ГБ, рекомендуется <200 ГБ
• На папку: <10 тыс. файлов
• На репозиторий: рекомендуется <100k файлов
• Хранилище аккаунта (публичное и приватное) зависит от тарифного плана: см. тарифные планы хранилища

См. https://huggingface.co/docs/hub/storage-limits для актуальных тарифов на хранилище и рекомендаций по репозиториям.

Быстрая справка по типу данных

Workflow загрузки

0. ✓ Собрать информацию о наборе данных (при необходимости):

   • Какой тип данных? (изображения, текст, аудио, CSV и т. д.)
   • Как он организован? (структура папок, один файл, несколько файлов)
   • Каков примерный размер?
   • В каком формате представлены файлы?
   • Есть ли какие-либо особые требования? (например, потоковая передача, частный доступ)
   • Проверьте наличие существующих файлов README или документации, описывающих набор данных

1. ✓ Аутентификация:

   • CLI: hf auth login
   • Или используйте токен: HfApi(token="hf_...") или задайте переменную окружения HF_TOKEN

2. ✓ Определите тип данных: проверьте таблицу Quick Reference выше

3. ✓ Выберите способ загрузки:

   • Небольшие файлы (<1 ГБ) в формате, совместимом с Hub: для быстрой загрузки можно использовать интерфейс Hub
   • Встроенный загрузчик доступен: используйте загрузчик + push_to_hub() (см. таблицу быстрого справочника)
   • Большие наборы данных или множество файлов: используйте upload_folder / hf upload, которые поддерживают загрузку больших объёмов (автоматическая многокоммитная загрузка, возобновляемость).
   • Пользовательские форматы: при возможности конвертировать в формат, совместимый с хабом, в противном случае — подробно задокументировать

4. ✓ Тестирование локально (при использовании встроенного загрузчика):

   Скопировано

   # Validate your dataset loads correctly before uploading
   dataset = load_dataset("loader_name", data_dir="./your_data")
   print(dataset)

5. ✓ Загрузить в Hub:

   Скопировано

   # Basic upload
   dataset.push_to_hub("username/dataset-name")
   
   # With options for large datasets
   dataset.push_to_hub(
       "username/dataset-name",
       max_shard_size="5GB",  # Control memory usage
       private=True  # For private datasets
   )

6. ✓ Проверьте загрузку:

   • Проверьте Dataset Viewer: https://huggingface.co/datasets/username/dataset-name
   • Тест загрузки: load_dataset("username/dataset-name")
   • Если просмотрщик отображает ошибки, проверьте раздел Устранение неполадок

Частые паттерны преобразования

Если встроенные загрузчики не соответствуют структуре ваших данных, используйте библиотеку datasets в качестве слоя совместимости. Преобразуйте данные в объект Dataset, а затем используйте push_to_hub() для максимальной гибкости и совместимости с Dataset Viewer.

Из DataFrames

Если ваши данные уже обрабатываются в pandas, polars или других библиотеках для работы с табличными данными, вы можете выполнить прямое преобразование:

# From pandas DataFrame
import pandas as pd
from datasets import Dataset

df = pd.read_csv("your_data.csv")
dataset = Dataset.from_pandas(df)
dataset.push_to_hub("username/dataset-name")

# From polars DataFrame (direct method)
import polars as pl
from datasets import Dataset

df = pl.read_csv("your_data.csv")
dataset = Dataset.from_polars(df)  # Direct conversion
dataset.push_to_hub("username/dataset-name")

# From PyArrow Table (useful for scientific data)
import pyarrow as pa
from datasets import Dataset

# If you have a PyArrow table
table = pa.table({'data': [1, 2, 3], 'labels': ['a', 'b', 'c']})
dataset = Dataset(table)
dataset.push_to_hub("username/dataset-name")

# For Spark/Dask dataframes, see https://huggingface.co/docs/hub/datasets-libraries

Преобразование в пользовательском формате

Если встроенные загрузчики не соответствуют формату ваших данных, преобразуйте их в объекты Dataset, следуя этим принципам:

Принципы проектирования

1. Предпочитайте широкие/плоские структуры соединениям

• Денормализация реляционных данных в одиночные строки для удобства использования
• Включайте всю необходимую информацию в каждом примере
• Стремитесь к большим, но более пригодным для использования данным — инфраструктура Hugging Face использует продвинутую дедупликацию (XetHub) и оптимизации Parquet для эффективного устранения избыточности

2. Используйте конфигурации для логических вариаций датасета

• Помимо разбиения на train/test/val, используйте конфигурации для различных подмножеств или представлений ваших данных
• Каждая конфигурация может иметь различные функции или способы организации данных
• Пример: конфигурации для конкретных языков, представления для конкретных задач или модальности данных

Методы преобразования

Небольшие наборы данных (помещаются в оперативную память) — используйте Dataset.from_dict():

# Parse your custom format into a dictionary
data_dict = {
    "text": ["example1", "example2"],
    "label": ["positive", "negative"],
    "score": [0.9, 0.2]
}

# Create dataset with appropriate features
from datasets import Dataset, Features, Value, ClassLabel
features = Features({
    'text': Value('string'),
    'label': ClassLabel(names=['negative', 'positive']),
    'score': Value('float32')
})

dataset = Dataset.from_dict(data_dict, features=features)
dataset.push_to_hub("username/dataset")

Большие наборы данных (с экономным использованием памяти) — используйте Dataset.from_generator():

def data_generator():
    # Parse your custom format progressively
    for item in parse_large_file("data.custom"):
        yield {
            "text": item["content"],
            "label": item["category"],
            "embedding": item["vector"]
        }

# Specify features for Dataset Viewer compatibility
from datasets import Features, Value, ClassLabel, List
features = Features({
    'text': Value('string'),
    'label': ClassLabel(names=['cat1', 'cat2', 'cat3']),
    'embedding': List(feature=Value('float32'), length=768)
})

dataset = Dataset.from_generator(data_generator, features=features)
dataset.push_to_hub("username/dataset", max_shard_size="1GB")

Совет: для больших наборов данных сначала протестируйте на подмножестве, добавив ограничение к генератору или используя .select(range(100)) после создания.

Использование конфигураций для вариаций наборов данных

# Push different configurations of your dataset
dataset_en = Dataset.from_dict(english_data, features=features)
dataset_en.push_to_hub("username/multilingual-dataset", config_name="english")

dataset_fr = Dataset.from_dict(french_data, features=features)
dataset_fr.push_to_hub("username/multilingual-dataset", config_name="french")

# Users can then load specific configs
dataset = load_dataset("username/multilingual-dataset", "english")

Примеры мультимодальности

Текст + аудио (распознавание речи):

def speech_generator():
    for audio_file in Path("audio/").glob("*.wav"):
        transcript_file = audio_file.with_suffix(".txt")
        yield {
            "audio": str(audio_file),
            "text": transcript_file.read_text().strip(),
            "speaker_id": audio_file.stem.split("_")[0]
        }

features = Features({
    'audio': Audio(sampling_rate=16000),
    'text': Value('string'),
    'speaker_id': Value('string')
})

dataset = Dataset.from_generator(speech_generator, features=features)
dataset.push_to_hub("username/speech-dataset")

Несколько изображений на пример:

# Before/after images, medical imaging, etc.
data = {
    "image_before": ["img1_before.jpg", "img2_before.jpg"],
    "image_after": ["img1_after.jpg", "img2_after.jpg"],
    "treatment": ["method_A", "method_B"]
}

features = Features({
    'image_before': Image(),
    'image_after': Image(),
    'treatment': ClassLabel(names=['method_A', 'method_B'])
})

dataset = Dataset.from_dict(data, features=features)
dataset.push_to_hub("username/before-after-images")

Примечание: для текста + изображений рассмотрите использование ImageFolder с metadata.csv, который обрабатывает это автоматически.

Ключевые возможности

Особенности (Features) определяют схему и типы данных для столбцов вашего набора данных. Указание правильных особенностей обеспечивает:

• Правильная обработка данных и преобразование типов
• Функциональность Dataset Viewer (например, предпросмотр изображений/аудио)
• Эффективное хранение и загрузка
• Чёткая документация вашей структуры данных

Полная документация по функциям: Dataset Features

Обзор типов признаков

Базовые типы:

• Value: скалярные значения — string, int64, float32, bool, binary и другие числовые типы
• ClassLabel: категориальные данные с именованными классами
• Sequence: Списки любого типа признаков
• LargeList: для очень больших списков

Типы медиа (включить предпросмотр в Dataset Viewer):

• Image(): обрабатывает различные форматы изображений, возвращает объекты PIL Image
• Audio(sampling_rate=16000): Audio с массивом данных и необязательной частотой дискретизации
• Video(): видеофайлы
• Pdf(): PDF-документы с извлечением текста

Типы массивов (для тензоров/научных данных):

• Array2D, Array3D, Array4D, Array5D: массивы фиксированной или переменной длины
• Пример: Array2D(shape=(224, 224), dtype='float32')
• Первое измерение может быть None для переменной длины

Типы перевода:

• Translation: для пар языков перевода с фиксированными языками
• TranslationVariableLanguages: для переводов с изменяющимися языковыми парами

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

Способы загрузки

Объекты Dataset (используйте push_to_hub): Используйте, если вы загрузили/конвертировали данные с помощью библиотеки datasets

dataset.push_to_hub("username/dataset", max_shard_size="5GB")

Существующие файлы (используйте upload_folder / hf upload): Используйте, если у вас уже подготовлены и организованы файлы, совместимые с Hub (например, файлы Parquet).

from huggingface_hub import HfApi
api = HfApi()
api.upload_folder(folder_path="./data", repo_id="username/dataset", repo_type="dataset")

# Or from the CLI:
hf upload username/dataset ./data --repo-type=dataset

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

• Проверьте структуру папок, если у вас есть доступ к файлам: убедитесь, что ни одна папка не содержит более 10 тыс. файлов
• Попросите пользователя подтвердить: «Ваши файлы в формате, совместимом с Hugging Face Hub (Parquet/CSV/JSON), и правильно организованы?»
• Для нестандартных форматов сначала рассмотрите преобразование в объекты Dataset, чтобы обеспечить совместимость

Валидация

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

• Переименовать столбцы (например, ‘filename’ → ‘file_name’ для ImageFolder)
• Перестройте структуру папок (например, переместите изображения в подпапки классов)
• Переименуйте файлы, чтобы они соответствовали ожидаемым шаблонам (например, data.csv → train.csv)

До загрузки:

• Тестирование локально: load_dataset("imagefolder", data_dir="./data")

• Проверьте, что функции работают корректно:

  Скопировано

  # Test first example
  print(dataset[0])
  
  # For images: verify they load
  if 'image' in dataset.features:
      dataset[0]['image']  # Should return PIL Image
  
  # Check dataset size before upload
  print(f"Size: {len(dataset)} examples")

• Проверьте, что в metadata.csv есть столбец file_name

• Проверьте относительные пути, без начальных слэшей

• Убедитесь, что в папке нет более 10 тыс. файлов

После загрузки:

• Проверьте просмотрщик: https://huggingface.co/datasets/username/dataset
• Тест загрузки: load_dataset("username/dataset")
• Проверьте сохранённые признаки: print(dataset.features)

Частые проблемы → Решения

Конфигурация Dataset Viewer

Примечание: данный раздел в первую очередь предназначен для наборов данных, загруженных непосредственно в Hub (через интерфейс, upload_folder или hf upload). Наборы данных, загруженные с помощью push_to_hub(), как правило, автоматически настраивают просмотрщик.

Когда автоматическое определение работает

Просмотрщик наборов данных автоматически определяет стандартные структуры:

• Файлы с именами: train.csv, test.json, validation.parquet
• Каталоги с именами: train/, test/, validation/
• Разделяйте имена с помощью разделителей: test-data.csv ✓ (а не testdata.csv ✗)

Ручная настройка

Для пользовательских структур добавьте YAML в ваш README.md:

---
configs:
  - config_name: default # Required even for single config!
    data_files:
      - split: train
        path: "data/train/*.parquet"
      - split: test
        path: "data/test/*.parquet"
---

Пример нескольких конфигураций:

---
configs:
  - config_name: english
    data_files: "en/*.parquet"
  - config_name: french
    data_files: "fr/*.parquet"
---

Частые проблемы с просмотрщиком

• Нет предпросмотра после загрузки: Подождите 5–10 минут для обработки
• «Ошибка имени конфигурации»: добавьте поле config_name (обязательно!)
• Файлы не обнаружены: проверьте шаблоны именования (необходимы разделители)
• Просмотр отключен: удалите viewer: false из YAML в README

Быстрые шаблоны

# ImageFolder with metadata
dataset = load_dataset("imagefolder", data_dir="./images")
dataset.push_to_hub("username/dataset")

# Memory-efficient upload
dataset.push_to_hub("username/dataset", max_shard_size="500MB")

# Multiple CSV files
dataset = load_dataset('csv', data_files={'train': 'train.csv', 'test': 'test.csv'})
dataset.push_to_hub("username/dataset")

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

Основные документы: Добавление наборов данных | Просмотрщик наборов данных | Ограничения хранилища | Руководство по загрузке

Карточки датасетов

Напомните пользователям добавить карточку набора данных (README.md) с:

• Описание и использование набора данных
• Информация о лицензии
• Детали цитирования

См. руководство по карточкам датасетов для подробностей.

Приложение: Особые случаи

Структура WebDataset

Для потоковой обработки больших наборов мультимедийных данных:

• Создание tar-фрагментов размером 1–5 ГБ
• Последовательная внутренняя структура
• Загрузка с помощью hf upload

Научные данные

• HDF5/NetCDF → Преобразование в Parquet с функциями Array
• Временные ряды → Array2D(shape=(None, n))
• Сложные метаданные → Хранить как строки JSON

Ресурсы сообщества

Для очень специализированных или нестандартных форматов:

• Ищите похожие датасеты на Hub: https://huggingface.co/datasets
• Запросите совет на форуме Hugging Face
• Присоединяйтесь к Hugging Face Discord для помощи в реальном времени
• Многие форматы, специфичные для определённых областей, уже имеют примеры на Hub