Hugging Face Dataset 업로드 결정 가이드

이 가이드는 LLM이 사용자에게 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 버전과 일치하므로, 기억에서 떠올린 플래그보다 CLI의 출력을 우선적으로 사용하세요.

개요

사용자가 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

사람이 읽을 수 있는 요약:

• 파일당: 최대 500GB, 200GB 미만 권장
• 폴더당: <10k 파일
• 리포지토리당: <100k 파일 권장
• 계정 저장소(공개 및 비공개)는 플랜에 따라 달라집니다: 저장소 플랜을 참조하세요.

현재 저장소 플랜 및 저장소 권장 사항에 대해서는 https://huggingface.co/docs/hub/storage-limits를 참조하세요.

데이터 유형별 빠른 참고

업로드 워크플로

0. ✓ (필요한 경우) 데이터셋 정보 수집:

   • 어떤 유형의 데이터인가요? (이미지, 텍스트, 오디오, CSV 등)
   • 어떻게 구성되어 있나요? (폴더 구조, 단일 파일, 여러 파일)
   • 대략적인 크기는 얼마인가요?
   • 파일 형식은 무엇인가요?
   • 특별한 요구 사항이 있나요? (예: 스트리밍, 비공개 액세스)
   • 데이터셋을 설명하는 기존 README 또는 문서 파일이 있는지 확인합니다

1. ✓ 인증:

   • CLI: hf auth login
   • 또는 토큰을 사용하세요: HfApi(token="hf_...") 또는 HF_TOKEN 환경 변수를 설정하세요

2. ✓ 데이터 유형 확인: 위의 빠른 참고 표를 확인하세요

3. ✓ 업로드 방법 선택:

   • 허브 호환 형식의 작은 파일(<1GB): 빠른 업로드를 위해 Hub UI를 사용할 수 있습니다
   • 내장 로더 사용 가능: 로더 + push_to_hub() 사용 (Quick Reference 표 참조)
   • 대용량 데이터셋 또는 파일이 많은 경우: 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 호환성을 확보합니다.

DataFrame에서

이미 pandas, polars 또는 다른 dataframe 라이브러리에서 데이터를 처리하고 있다면, 직접 변환할 수 있습니다:

# 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. 논리적 데이터셋 변형을 위해 config 사용

• train/test/val 분할 외에도, 데이터의 다른 하위 집합이나 뷰에 대한 설정을 사용하세요
• 각 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")

팁: 대규모 데이터셋의 경우, 생성기에 limit를 추가하거나 생성 후 .select(range(100))를 사용하여 먼저 부분 집합으로 테스트해 보세요.

데이터셋 변형을 위한 Configs 사용

# 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는 데이터셋 컬럼의 스키마와 데이터 타입을 정의합니다. 올바른 Features를 지정하면 다음을 보장할 수 있습니다:

• 적절한 데이터 처리 및 타입 변환
• Dataset Viewer 기능(예: 이미지/오디오 미리보기)
• 효율적인 저장 및 로드
• 데이터 구조에 대한 명확한 문서

전체 기능 문서에 대한 자세한 내용은 Dataset Features를 참조하세요.

Feature Types 개요

기본 유형:

• 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

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

• 파일 접근 권한이 있는 경우 폴더 구조를 확인하세요: 폴더에 10k개 이상의 파일이 포함되지 않도록 합니다
• 사용자에게 확인을 요청합니다: “파일이 허브 호환 형식(Parquet/CSV/JSON)으로 되어 있고 적절하게 정리되어 있습니까?”
• 비표준 형식의 경우 호환성을 보장하기 위해 먼저 Dataset 객체로 변환하는 것을 고려해 보세요

검증

작은 형식 변경 고려: 데이터가 내장된 로더 형식과 유사한 경우, 다음과 같은 작은 변경 사항을 제안합니다:

• 열 이름 변경 (예: ImageFolder의 경우 ‘filename’ → ‘file_name’)
• 폴더 재구성(예: 이미지를 클래스 하위 폴더로 이동)
• 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’ 열이 있는지 확인

• 상대 경로 확인, 앞선 슬래시 없음

• 폴더당 파일 수가 10k를 초과하지 않도록 확인

업로드 후:

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

자주 발생하는 문제 → 해결 방법

Dataset Viewer 구성

참고: 이 섹션은 주로 Hub에 직접 업로드된 데이터셋(UI, upload_folder 또는 hf upload를 통해)에 해당합니다. push_to_hub()로 업로드된 데이터셋은 뷰어가 자동으로 설정되는 것이 일반적입니다.

자동 감지가 작동하는 경우

Dataset Viewer는 표준 구조를 자동으로 감지합니다:

• 이름이 train.csv, test.json, validation.parquet인 파일
• 이름이 train/, test/, validation/인 디렉터리
• 구분자를 사용하여 이름을 분리: 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를 제거

빠른 템플릿

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

문서

핵심 문서: 데이터셋 추가 | 데이터셋 뷰어 | 저장 용량 제한 | 업로드 가이드

Dataset Cards

사용자에게 다음을 포함하여 데이터셋 카드(README.md)를 추가하도록 상기시킵니다:

• 데이터셋 설명 및 사용
• 라이선스 정보
• 인용 정보

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

부록: 특수한 경우

WebDataset 구조

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

• 1~5GB의 tar 샤드를 생성합니다
• 일관된 내부 구조
• hf upload로 업로드

과학 데이터

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

커뮤니티 리소스

매우 전문적이거나 맞춤형 형식의 경우:

• Hub에서 유사한 데이터셋을 검색하세요: https://huggingface.co/datasets
• Hugging Face 포럼에서 조언을 구해 보세요
• 실시간 도움을 받으려면 Hugging Face Discord에 참여하세요
• 많은 도메인별 형식에 이미 Hub에 예제가 있습니다