Panduan Keputusan Unggah Dataset Hugging Face

Panduan ini terutama dirancang untuk LLM guna membantu pengguna mengunggah dataset ke Hugging Face Hub dalam format yang paling kompatibel. Pengguna juga dapat merujuk pada panduan ini untuk memahami proses pengunggahan dan praktik terbaik.

Panduan pengambilan keputusan untuk mengunggah dataset ke Hugging Face Hub. Dioptimalkan untuk kompatibilitas Dataset Viewer dan integrasi dengan ekosistem Hugging Face.

Jika Anda adalah LLM atau agen yang mengikuti panduan ini, periksa hf --help dan hf <command> --help (misalnya hf upload --help, hf auth --help) untuk flag yang tepat sebelum menjalankan perintah upload. CLI sesuai dengan versi huggingface_hub yang terinstal, jadi lebih utamakan outputnya daripada flag yang diingat dari memori.

Ikhtisar

Tujuan Anda adalah membantu pengguna mengunggah dataset ke Hugging Face Hub. Idealnya, dataset tersebut harus kompatibel dengan Dataset Viewer (dan dengan demikian fungsi load_dataset) untuk memastikan akses dan kegunaan yang mudah. Anda harus berusaha memenuhi kriteria berikut:

Bekerja Tanpa Akses File

Ketika Anda tidak memiliki akses langsung ke file pengguna (misalnya, antarmuka web), minta pengguna untuk menjalankan perintah-perintah ini untuk memahami dataset mereka:

Struktur 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

Periksa ukuran file:

# Total dataset size
du -sh .

# Individual file sizes
ls -lh data/

Intip format data:

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

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

Jumlah file cepat:

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

Batasan Kritis

Batas Penyimpanan:

Jika ini berbeda dari storage-limits, maka storage-limits yang berlaku.

# 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

Ringkasan yang dapat dibaca manusia:

• Per file: maks 500GB, <200GB disarankan
• Per folder: <10k file
• Per repo: <100k file disarankan
• Penyimpanan akun (publik dan privat) bergantung pada paket: lihat penyimpanan paket

Lihat https://huggingface.co/docs/hub/storage-limits untuk rencana penyimpanan saat ini dan rekomendasi repositori.

Referensi Cepat Berdasarkan Tipe Data

Alur Kerja Unggah

0. ✓ Kumpulkan informasi dataset (jika diperlukan):

   • Jenis data apa? (gambar, teks, audio, CSV, dll.)
   • Bagaimana strukturnya? (struktur folder, satu file, beberapa file)
   • Berapa perkiraan ukurannya?
   • Format apa dari file-file tersebut?
   • Apakah ada persyaratan khusus? (misalnya, streaming, akses privat)
   • Periksa file README atau dokumentasi yang ada yang menjelaskan dataset

1. ✓ Autentikasi:

   • CLI: hf auth login
   • Atau gunakan token: HfApi(token="hf_...") atau setel variabel lingkungan HF_TOKEN

2. ✓ Identifikasi tipe data Anda: Periksa tabel Quick Reference di atas

3. ✓ Pilih metode unggah:

   • Berkas kecil (<1GB) dengan format yang kompatibel dengan hub: Dapat menggunakan Hub UI untuk unggahan cepat
   • Pemuat bawaan tersedia: Gunakan pemuat + push_to_hub() (lihat tabel Referensi Cepat)
   • Dataset besar atau banyak file: Gunakan upload_folder / hf upload yang menangani unggahan besar (multi-commit otomatis, dapat dilanjutkan).
   • Format kustom: Konversi ke format yang kompatibel dengan hub jika memungkinkan, jika tidak, dokumentasikan secara menyeluruh

4. ✓ Uji secara lokal (jika menggunakan loader bawaan):

   Disalin

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

5. ✓ Unggah ke Hub:

   Disalin

   # 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. ✓ Verifikasi unggahan Anda:

   • Periksa Dataset Viewer: https://huggingface.co/datasets/username/dataset-name
   • Uji pemuatan: load_dataset("username/dataset-name")
   • Jika viewer menampilkan error, periksa bagian Troubleshooting

Pola Konversi Umum

Saat loader bawaan tidak sesuai dengan struktur data Anda, gunakan pustaka datasets sebagai lapisan kompatibilitas. Konversi data Anda menjadi objek Dataset, lalu gunakan push_to_hub() untuk fleksibilitas maksimal dan kompatibilitas dengan Dataset Viewer.

Dari DataFrames

Jika Anda sudah memiliki data yang berfungsi di pandas, polars, atau pustaka dataframe lainnya, Anda dapat mengonversinya secara langsung:

# 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

Konversi Format Kustom

Saat loader bawaan tidak sesuai dengan format data Anda, konversi ke objek Dataset mengikuti prinsip-prinsip berikut:

Prinsip Desain

1. Utamakan struktur lebar/datar daripada join

• Denormalisasi data relasional menjadi baris tunggal untuk kegunaan yang lebih baik
• Sertakan semua informasi yang relevan dalam setiap contoh
• Cenderung ke data yang lebih besar namun lebih mudah digunakan - infrastruktur Hugging Face menggunakan deduplikasi canggih (XetHub) dan optimasi Parquet untuk menangani redundansi secara efisien

2. Gunakan config untuk variasi dataset logis

• Selain pembagian train/test/val, gunakan konfigurasi untuk subset atau tampilan data Anda yang berbeda
• Setiap config dapat memiliki fitur atau organisasi data yang berbeda
• Contoh: konfigurasi spesifik bahasa, tampilan spesifik tugas, atau modalitas data

Metode Konversi

Dataset kecil (muat di memori) - gunakan 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 besar (efisien memori) - gunakan 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")

Tips: Untuk dataset besar, uji coba dengan subset terlebih dahulu dengan menambahkan limit pada generator Anda atau menggunakan .select(range(100)) setelah pembuatan.

Menggunakan Configs untuk Variasi Dataset

# 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")

Contoh Multi-modal

Teks + Audio (pengenalan ucapan):

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")

Beberapa gambar per contoh:

# 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")

Catatan: Untuk teks + gambar, pertimbangkan untuk menggunakan ImageFolder dengan metadata.csv yang menangani ini secara otomatis.

Fitur Utama

Features mendefinisikan skema dan tipe data untuk kolom dataset Anda. Menentukan features yang benar memastikan:

• Penanganan data dan konversi tipe yang tepat
• Fungsionalitas Dataset Viewer (misalnya, pratinjau gambar/audio)
• Penyimpanan dan pemuatan yang efisien
• Dokumentasi yang jelas tentang struktur data Anda

Untuk dokumentasi fitur lengkap, lihat: Fitur Dataset

Ringkasan Jenis Fitur

Tipe Dasar:

• Value: Nilai skalar - string, int64, float32, bool, binary, dan tipe numerik lainnya
• ClassLabel: Data kategorikal dengan kelas bernama
• Sequence: Daftar dari tipe fitur apa pun
• LargeList: Untuk daftar yang sangat besar

Jenis Media (mengaktifkan pratinjau Dataset Viewer):

• Image(): Menangani berbagai format gambar, mengembalikan objek PIL Image
• Audio(sampling_rate=16000): Audio dengan data array dan sampling rate opsional
• Video(): File video
• Pdf(): dokumen PDF dengan ekstraksi teks

Jenis Array (untuk tensor/data ilmiah):

• Array2D, Array3D, Array4D, Array5D: Array dengan panjang tetap atau variabel
• Contoh: Array2D(shape=(224, 224), dtype='float32')
• Dimensi pertama dapat berupa None untuk panjang variabel

Jenis Terjemahan:

• Translation: Untuk pasangan terjemahan dengan bahasa yang tetap
• TranslationVariableLanguages: Untuk terjemahan dengan pasangan bahasa yang bervariasi

Catatan: Jenis fitur baru ditambahkan secara berkala. Periksa dokumentasi untuk penambahan terbaru.

Metode Unggah

Objek Dataset (gunakan push_to_hub): Gunakan ketika Anda telah memuat/mengonversi data menggunakan pustaka datasets

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

Berkas yang sudah ada (gunakan upload_folder / hf upload): Gunakan ini jika Anda sudah memiliki berkas yang kompatibel dengan hub (misalnya, berkas Parquet) yang telah disiapkan dan diorganisasi.

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

Penting: Sebelum mengunggah, pastikan file memenuhi batas repositori:

• Periksa struktur folder jika Anda memiliki akses file: pastikan tidak ada folder yang berisi >10k file
• Minta pengguna untuk mengonfirmasi: “Apakah file Anda dalam format yang kompatibel dengan hub (Parquet/CSV/JSON) dan tersusun dengan tepat?”
• Untuk format non-standar, pertimbangkan untuk mengonversi ke objek Dataset terlebih dahulu untuk memastikan kompatibilitas

Validasi

Pertimbangkan reformatting kecil: Jika data mendekati format loader bawaan, usulkan perubahan kecil:

• Ganti nama kolom (misalnya, ‘filename’ → ‘file_name’ untuk ImageFolder)
• Reorganisasi folder (misalnya, pindahkan gambar ke subfolder kelas)
• Ganti nama file agar sesuai dengan pola yang diharapkan (misalnya, ‘data.csv’ → ‘train.csv’)

Sebelum unggah:

• Uji secara lokal: load_dataset("imagefolder", data_dir="./data")

• Verifikasi fitur berfungsi dengan benar:

  Disalin

  # 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")

• Periksa apakah metadata.csv memiliki kolom file_name

• Verifikasi jalur relatif, tanpa garis miring di awal

• Pastikan tidak ada folder >10k file

Setelah unggah:

• Periksa viewer: https://huggingface.co/datasets/username/dataset
• Uji pemuatan: load_dataset("username/dataset")
• Verifikasi fitur yang dipertahankan: print(dataset.features)

Masalah Umum → Solusi

Konfigurasi Penampil Dataset

Catatan: Bagian ini terutama ditujukan untuk dataset yang diunggah langsung ke Hub (melalui UI, upload_folder atau hf upload). Dataset yang diunggah dengan push_to_hub() biasanya mengonfigurasi viewer secara otomatis.

Ketika deteksi otomatis berfungsi

Dataset Viewer secara otomatis mendeteksi struktur standar:

• File bernama: train.csv, test.json, validation.parquet
• Direktori bernama: train/, test/, validation/
• Pisahkan nama dengan pemisah: test-data.csv ✓ (bukan testdata.csv ✗)

Konfigurasi manual

Untuk struktur kustom, tambahkan YAML ke README.md Anda:

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

Contoh beberapa konfigurasi:

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

Masalah umum pada viewer

• Tidak ada viewer setelah upload: Tunggu 5-10 menit untuk pemrosesan
• “Config names error”: Tambahkan field config_name (wajib!)
• File tidak terdeteksi: Periksa pola penamaan (memerlukan pemisah)
• Viewer dinonaktifkan: Hapus viewer: false dari YAML README

Cetakan Cepat

# 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")

Dokumentasi

Dokumen inti: Menambahkan dataset | Penampil dataset | Batas penyimpanan | Panduan unggah

Kartu Dataset

Ingatkan pengguna untuk menambahkan kartu dataset (README.md) dengan:

• Deskripsi dan penggunaan dataset
• Informasi lisensi
• Detail sitasi

Lihat panduan Kartu Dataset untuk detailnya.

Lampiran: Kasus Khusus

Struktur WebDataset

Untuk streaming dataset media besar:

• Buat shard tar 1-5GB
• Struktur internal yang konsisten
• Unggah dengan hf upload

Data Ilmiah

• HDF5/NetCDF → Konversi ke Parquet dengan fitur Array
• Deret waktu → Array2D(shape=(None, n))
• Metadata kompleks → Simpan sebagai string JSON

Sumber Daya Komunitas

Untuk format yang sangat khusus atau dibuat khusus:

• Cari dataset serupa di Hub: https://huggingface.co/datasets
• Minta saran di Forum Hugging Face
• Bergabunglah dengan Hugging Face Discord untuk bantuan secara langsung
• Banyak format khusus domain sudah memiliki contoh di Hub