Hugging Face 데이터셋 업로드 결정 가이드

[!TIP] 이 가이드는 주로 LLM이 사용자들이 데이터셋을 Hugging Face 허브에 가장 호환성이 좋은 형식으로 업로드하도록 돕기 위해 설계되었어요. 사용자도 업로드 과정과 모범 사례를 이해하기 위해 이 가이드를 참고할 수 있어요.

Hugging Face 허브에 데이터셋을 업로드하기 위한 결정 가이드. Dataset Viewer 호환성과 Hugging Face 생태계 통합에 최적화되어 있어요.

[!TIP] 이 가이드를 따르는 LLM이나 에이전트라면, 업로드 명령을 실행하기 전에 hf --help와 hf <command> --help(예: hf upload --help, hf auth --help)로 정확한 플래그를 확인하세요. CLI는 설치된 huggingface_hub 버전과 일치하므로, 기억에서 떠올린 플래그보다 CLI 출력을 우선하세요.

출처: 문서

본문

개요 (Overview)

여러분의 목표는 사용자가 데이터셋을 Hugging Face 허브에 업로드하도록 돕는 것이에요. 이상적으로 데이터셋은 Dataset Viewer(따라서 load_dataset 함수)와 호환되어야 쉽게 접근하고 활용할 수 있어요. 다음 기준을 충족하는 것을 목표로 해야 해요:

기준	설명	우선순위
저장소 제한 준수	데이터셋이 Hugging Face의 파일 크기, 저장소 크기, 파일 수 저장 제한을 따르도록 하세요. 구체적인 제한은 아래 Critical Constraints 섹션을 참고하세요.	필수(Required)
허브 호환 형식 사용	가능하면 Parquet 형식을 사용하세요(가장 좋은 압축, 풍부한 타이핑, 대용량 데이터셋 지원). 더 작은 데이터셋(<몇 GB)은 JSON/JSONL 또는 CSV가 괜찮아요. 원시 파일은 더 작은 데이터셋의 이미지/오디오에 잘 동작하며 저장소 제한을 준수해요. 대용량 미디어 컬렉션에는 WebDataset(.tar)를 사용하세요. 변환이 비현실적일 때는 도메인별 형식도 쓸 수 있어요.	바람직(Desired)
Dataset Viewer 호환성	자동 Dataset Viewer와 동작하도록 데이터를 구조화해 미리보기와 쉬운 탐색을 가능하게 하세요. 보통 지원 형식을 사용하고 적절한 파일 구성을 의미해요. 검증 단계는 이 가이드 뒷부분에 제공돼요.	바람직(Desired)
데이터를 합리적으로 구성	Hub 규칙(예: train/test split)과 일치하는 논리적 폴더 구조를 사용하세요. Config를 사용해 데이터셋의 다른 구성을 정의할 수 있어요. 이는 사람의 이해와 자동 데이터 로딩을 모두 돕습니다.	바람직(Desired)
적절한 Features 사용	datasets 라이브러리를 쓸 때 올바른 피처 타입(예: Image(), Audio(), ClassLabel())을 지정해 올바른 데이터 처리와 뷰어 기능을 보장하세요. 이는 타입별 최적화와 미리보기를 가능하게 해요.	필수(datasets 라이브러리 사용 시)
비표준 데이터셋 문서화	허브 호환 형식으로의 변환이 불가능하고 커스텀 형식을 써야 한다면, 저장소 제한을 엄격히 따르고 데이터셋 다운로드·로드 방법을 명확히 문서화하세요. 사용 예시와 특별 요구 사항을 포함하세요.	필수(datasets 라이브러리가 호환되지 않을 때)

파일 접근 없이 작업하기

사용자 파일에 직접 접근할 수 없을 때(예: 웹 인터페이스), 사용자에게 다음 명령을 실행해 데이터셋을 파악하게 해 달라고 요청하세요.

데이터셋 구조:

# 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

핵심 제약 (Critical Constraints)

저장 제한 (Storage Limits):

# Machine-readable Hub limits
hub_limits:
  max_file_size_gb: 200 # absolute hard stop enforced by LFS
  recommended_file_size_gb: 50 # best-practice shard size
  max_files_per_folder: 10000 # Git performance threshold
  max_files_per_repo: 100000 # Repository file count limit
  recommended_repo_size_gb: 300 # public-repo soft cap; contact HF if larger
  viewer_row_size_mb: 2 # approximate per-row viewer limit

사람이 읽기 쉬운 요약:

무료: 100GB 비공개 데이터셋
Pro(개인) | Team 또는 Enterprise(조직): 시트당 1TB+ 비공개 스토리지(가격 참고)
공개: 1TB(더 큰 경우 [email protected]로 연락)
파일당: 최대 200GB, <50GB 권장
폴더당: <10k 파일

저장소 크기와 파일 수에 대한 현재 권장 사항은 https://huggingface.co/docs/hub/storage-limits#repository-limitations-and-recommendations 를 참고하세요.

데이터 유형별 빠른 참조 (Quick Reference by Data Type)

내 데이터	권장 접근법	빠른 명령
CSV/JSON 파일	내장 로더 사용(메모리 매핑으로 어떤 크기도 처리)	`load_dataset("csv", data_files="data.csv").push_to_hub("username/dataset")`
폴더의 이미지	자동 클래스 감지를 위해 imagefolder 사용	`load_dataset("imagefolder", data_dir="./images").push_to_hub("username/dataset")`
오디오 파일	자동 구성을 위해 audiofolder 사용	`load_dataset("audiofolder", data_dir="./audio").push_to_hub("username/dataset")`
비디오 파일	자동 구성을 위해 videofolder 사용	`load_dataset("videofolder", data_dir="./videos").push_to_hub("username/dataset")`
PDF 문서	텍스트 추출을 위해 pdffolder 사용	`load_dataset("pdffolder", data_dir="./pdfs").push_to_hub("username/dataset")`
매우 큰 데이터셋(100GB+)	메모리 사용 제어를 위해 `max_shard_size` 사용	`dataset.push_to_hub("username/dataset", max_shard_size="5GB")`
많은 파일 / 디렉터리(>10k)	`upload_folder`/`hf upload` 사용(크고 많은 파일 업로드 처리)	`hf upload username/dataset ./data --repo-type=dataset`
대용량 미디어 스트리밍	효율적 스트리밍을 위한 WebDataset 형식	.tar 샤드 생성 후 `hf upload`
과학 데이터(HDF5, NetCDF)	Array features로 Parquet 변환	Scientific Data 섹션 참고
커스텀/독점 형식	변환이 불가능하면 철저히 문서화	포괄적 README와 `hf upload`

업로드 워크플로

✓ 데이터셋 정보 수집(필요 시):
- 어떤 유형의 데이터인가?(이미지, 텍스트, 오디오, CSV 등)
- 어떻게 구성되어 있나?(폴더 구조, 단일 파일, 여러 파일)
- 대략적인 크기는?
- 파일 형식은?
- 특별 요구 사항이 있나?(예: 스트리밍, 비공개 접근)
- 데이터셋을 설명하는 기존 README 또는 문서 파일이 있는지 확인
✓ 인증:
- CLI: hf auth login
- 또는 토큰 사용: HfApi(token="hf_...") 또는 HF_TOKEN 환경 변수 설정
✓ 데이터 유형 식별: 위 빠른 참조 표 확인
✓ 업로드 방법 선택:
- 허브 호환 형식의 작은 파일(<1GB): Hub UI로 빠른 업로드 가능
- 내장 로더 사용 가능: 로더 + push_to_hub() 사용(빠른 참조 표 참고)
- 대용량 데이터셋 또는 많은 파일: 대규모 업로드를 처리하는 upload_folder / hf upload 사용(자동 다중 커밋, 이어올리기 가능)
- 커스텀 형식: 가능하면 허브 호환 형식으로 변환, 아니면 철저히 문서화

✓ 로컬에서 테스트(내장 로더 사용 시):

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

✓ 허브에 업로드:

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

✓ 업로드 검증:
- Dataset Viewer 확인: https://huggingface.co/datasets/username/dataset-name
- 로딩 테스트: load_dataset("username/dataset-name")
- 뷰어에 오류가 보이면 Troubleshooting 섹션 확인

일반 변환 패턴 (Common Conversion Patterns)

내장 로더가 내 데이터 구조와 맞지 않을 때는 datasets 라이브러리를 호환성 레이어로 사용하세요. 데이터를 Dataset 객체로 변환한 뒤 push_to_hub()를 사용해 최대 유연성과 Dataset Viewer 호환성을 얻으세요.

DataFrame에서 변환

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

커스텀 형식 변환 (Custom Format Conversion)

내장 로더가 데이터 형식과 맞지 않을 때는 다음 원칙에 따라 Dataset 객체로 변환하세요.

설계 원칙

1. 조인보다 넓은/플랫 구조를 선호하세요

더 나은 사용성을 위해 관계형 데이터를 단일 행으로 비정규화
각 예시에 관련 정보를 모두 포함
더 크지만 더 유용한 데이터를 지향하세요 — Hugging Face 인프라는 고급 중복 제거(XetHub)와 Parquet 최적화로 중복을 효율적으로 처리해요

2. 논리적 데이터셋 변형에 config 사용

train/test/val split 외에도 데이터의 다른 서브셋이나 뷰에 config 사용
각 config는 다른 피처나 데이터 구성을 가질 수 있음
예: 언어별 config, 태스크별 뷰, 데이터 모달리티

변환 방법

작은 데이터셋(메모리에 들어가는 크기) — 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))를 사용해 먼저 서브셋으로 테스트하세요.

데이터셋 변형에 Config 사용하기

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

참고: 텍스트 + 이미지의 경우 metadata.csv와 함께 ImageFolder를 사용하는 것을 고려하세요. 이는 자동으로 처리해 줘요.

핵심 Features (Essential Features)

Features는 데이터셋 컬럼의 스키마와 데이터 타입을 정의해요. 올바른 features를 지정하면 다음이 보장됩니다:

올바른 데이터 처리와 타입 변환
Dataset Viewer 기능(예: 이미지/오디오 미리보기)
효율적인 저장과 로딩
데이터 구조의 명확한 문서화

전체 features 문서는 Dataset Features에서 확인하세요.

피처 타입 개요

기본 타입:

Value: 스칼라 값 — string, int64, float32, bool, binary 및 기타 숫자 타입
ClassLabel: 이름이 있는 클래스를 가진 범주형 데이터
Sequence: 모든 피처 타입의 리스트
LargeList: 매우 큰 리스트용

미디어 타입(Dataset Viewer 미리보기 활성화):

Image(): 다양한 이미지 형식을 처리하고 PIL Image 객체를 반환
Audio(sampling_rate=16000): 배열 데이터와 선택적 샘플링 레이트가 있는 오디오
Video(): 비디오 파일
Pdf(): 텍스트 추출이 있는 PDF 문서

배열 타입(텐서/과학 데이터용):

Array2D, Array3D, Array4D, Array5D: 고정 또는 가변 길이 배열
예: Array2D(shape=(224, 224), dtype='float32')
첫 번째 차원은 가변 길이를 위해 None일 수 있음

번역(Translation) 타입:

Translation: 고정 언어의 번역 쌍용
TranslationVariableLanguages: 다양한 언어 쌍의 번역용

참고: 새 피처 타입이 정기적으로 추가됩니다. 최신 추가 사항은 문서를 확인하세요.

업로드 방법 (Upload Methods)

Dataset 객체(push_to_hub 사용): datasets 라이브러리로 데이터를 로드/변환했을 때 사용

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

기존 파일(upload_folder / hf upload 사용): 이미 준비되고 조직된 허브 호환 파일(예: 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

중요: 업로드 전에 파일이 저장소 제한을 충족하는지 확인하세요:

파일 접근이 있다면 폴더 구조 확인: 어떤 폴더도 >10k 파일을 포함하지 않도록
사용자에게 확인: "파일이 허브 호환 형식(Parquet/CSV/JSON)이고 적절히 조직되었나요?"
비표준 형식의 경우 호환성을 보장하기 위해 먼저 Dataset 객체로 변환을 고려

검증 (Validation)

작은 재구성 고려: 데이터가 내장 로더 형식에 가깝다면 사소한 변경을 제안하세요:

컬럼 이름 바꾸기(예: ImageFolder용 'filename' → 'file_name')
폴더 재구성(예: 이미지를 클래스 하위 폴더로 이동)
예상 패턴에 맞게 파일 이름 변경(예: 'data.csv' → 'train.csv')

업로드 전:

로컬 테스트: load_dataset("imagefolder", data_dir="./data")

features가 올바르게 동작하는지 확인:

# 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' 컬럼이 있는지 확인
상대 경로 확인, 선행 슬래시 없음
폴더에 >10k 파일이 없는지 확인

업로드 후:

뷰어 확인: https://huggingface.co/datasets/username/dataset
로딩 테스트: load_dataset("username/dataset")
features 보존 확인: print(dataset.features)

일반 문제 → 해결책 (Common Issues → Solutions)

문제	해결책
"Repository not found"	`hf auth login` 실행
메모리 오류	`max_shard_size="500MB"` 사용
Dataset viewer가 안 됨	5-10분 기다리고 README.md config 확인
>50GB 파일	더 작은 파일로 분할
"File not found"	metadata에서 상대 경로 사용

Dataset Viewer 구성

참고: 이 섹션은 주로 허브에 직접 업로드(UI 또는 upload_large_folder 사용)된 데이터셋을 위한 것이에요. push_to_hub()로 업로드된 데이터셋은 보통 뷰어를 자동으로 구성해요.

자동 감지가 동작할 때

Dataset Viewer는 표준 구조를 자동으로 감지해요:

파일 이름: train.csv, test.json, validation.parquet
디렉터리 이름: train/, test/, validation/
구분자가 있는 split 이름: test-data.csv ✓ (testdata.csv ✗)

수동 구성

커스텀 구조의 경우 README.md에 YAML을 추가하세요:

---
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 names error": config_name 필드 추가(필수!)
파일이 감지되지 않음: 이름 패턴 확인(구분자 필요)
뷰어 비활성화: README YAML에서 viewer: false 제거

빠른 템플릿 (Quick Templates)

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

문서 (Documentation)

핵심 문서: Adding datasets | Dataset viewer | Storage limits | Upload guide

Dataset Cards

사용자에게 다음을 포함한 데이터셋 카드(README.md)를 추가하라고 알려 주세요:

데이터셋 설명과 사용법
라이선스 정보
인용 세부 정보

자세한 내용은 Dataset Cards 가이드를 참고하세요.

부록: 특별 사례 (Appendix: Special Cases)

WebDataset 구조

대용량 미디어 데이터셋 스트리밍용:

1-5GB tar 샤드 생성
일관된 내부 구조
hf upload로 업로드

과학 데이터 (Scientific Data)

HDF5/NetCDF → Array features로 Parquet 변환
시계열 → Array2D(shape=(None, n))
복잡한 메타데이터 → JSON 문자열로 저장

커뮤니티 리소스

매우 특수하거나 주문 제작된 형식의 경우:

허브에서 유사한 데이터셋 검색: https://huggingface.co/datasets
Hugging Face 포럼에서 조언 구하기
실시간 도움을 위해 Hugging Face Discord 참여
많은 도메인별 형식이 이미 허브에 예시가 있음

더 알아보기 (Learn more)

Adding datasets에서 데이터셋 추가의 기본을 배울 수 있어요.
Datasets 업로드 가이드에서 datasets 라이브러리 업로드 전 과정을 확인하세요.