라이브러리

라이브러리 (Libraries)

Datasets Hub는 오픈소스 생태계의 여러 라이브러리를 지원해요. huggingface_hub Python 라이브러리 덕분에 Hub에 데이터셋을 공유하기가 아주 쉬워졌습니다.

출처: 문서

본문

Datasets Hub는 오픈소스 생태계의 여러 라이브러리를 지원합니다. huggingface_hub Python 라이브러리 덕분에 Hub에 데이터셋을 공유하는 것을 쉽게 활성화할 수 있어요. 머신러닝을 앞당기고 있는 여러 오픈소스 라이브러리를 Hub에 환영하게 되어 기쁩니다.

라이브러리 테이블 (Libraries table)

아래 테이블은 지원되는 라이브러리와 통합 수준을 요약합니다.

Library	Description	Download from Hub	Stream from Hub	Push to Hub	Stream to Hub	Optimized Parquet files
Argilla	고품질 데이터를 중시하는 AI 엔지니어와 도메인 전문가를 위한 협업 도구	✅	❌	✅	❌	❌
Daft	Python 네이티브 인터페이스를 갖춘 대규모 멀티모달 데이터 처리를 위한 데이터 엔진	✅	✅	✅	✅	✅
Dask	기존 Python 및 PyData 생태계를 확장하는 병렬·분산 컴퓨팅 라이브러리	✅	✅	✅	✅	✅*
Data Designer	LLM을 사용해 합성 데이터셋을 생성하는 NVIDIA NeMo 프레임워크	✅	❌	✅	❌	❌
Datasets	🤗 Datasets는 오디오, 컴퓨터 비전, 자연어 처리(NLP)를 위한 데이터셋 접근·공유 라이브러리	✅	✅	✅	✅	✅
Distilabel	합성 데이터 생성과 AI 피드백을 위한 프레임워크	✅	❌	✅	❌	❌
DuckDB	인프로세스 SQL OLAP 데이터베이스 관리 시스템	✅	✅	❌	❌	❌
Embedding Atlas	대규모 임베딩을 위한 대화형 시각화·탐색 도구	✅	✅	❌	❌	❌
Fenic	프로덕션 AI 및 에이전틱 애플리케이션 구축용 PySpark 영감 DataFrame 프레임워크	✅	✅	❌	❌	❌
FiftyOne	이미지·비디오·3D 데이터의 큐레이션과 시각화를 위한 라이브러리	✅	✅	✅	❌	❌
Lance	멀티모달 AI를 위한 오픈 레이크하우스 포맷	✅	✅	❌	❌	❌
Pandas	Python 데이터 분석 툴킷	✅	❌	✅	❌	✅*
Polars	OLAP 쿼리 엔진 위의 DataFrame 라이브러리	✅	✅	✅	❌	❌
PyArrow	Apache Arrow는 빠른 데이터 교환과 인메모리 분석을 위한 컬럼형 포맷이자 도구상자	✅	✅	✅	❌	✅*
Spark	분산 환경에서의 실시간·대규모 데이터 처리 도구	✅	✅	✅	✅	✅
WebDataset	대규모 데이터셋용 I/O 파이프라인 작성 라이브러리	✅	✅	❌	❌	❌

_ * 최적화된 Parquet 파일을 쓰려면 추가 인자를 전달해야 함_

데이터 처리 라이브러리 (Data Processing Libraries)

스트리밍 (Streaming)

데이터셋 스트리밍을 쓰면 데이터셋 전체를 다운로드하지 않고도 Hugging Face 데이터셋을 점진적으로 반복할 수 있어요. 데이터가 디스크에 저장되지 않으므로 로컬 디스크 공간을 아끼고, 한 번에 데이터셋의 일부만 사용하므로 메모리를 절약하며, CPU/GPU 워크로드 전에 데이터를 다운로드할 필요가 없으므로 시간도 절약됩니다.

Hugging Face 에서 스트리밍하는 것에 더해, 많은 라이브러리는 Hugging Face 로 스트리밍하는 것도 지원해요. 따라서 다운로드·업로드·처리 단계를 겹치면서 소스에서 스트리밍하고 Hugging Face에 점진적으로 쓰는 엔드투엔드 스트리밍 파이프라인을 실행할 수 있습니다.

스트리밍 방법에 대한 자세한 내용은 스트리밍을 지원하는 라이브러리의 문서(위 테이블 참고)나, Hugging Face에서 직접 스트리밍을 원한다면 streaming datasets 문서를 확인하세요.

최적화된 Parquet 파일 (Optimized Parquet files)

Hugging Face의 Parquet 파일은 저장 효율을 높이고 업로드·다운로드를 가속화하며 효율적인 데이터셋 스트리밍과 편집을 가능하게 하도록 최적화되어 있어요.

최적화된 Parquet 파일은 추가 기능이 있는 Parquet 파일입니다:

• Parquet Content Defined Chunking은 Hugging Face의 저장 백엔드인 Xet에 맞춰 Parquet을 최적화합니다. 청크 기반 중복 제거로 업로드·다운로드를 가속화하고 효율적인 파일 편집을 가능하게 해요.
• 페이지 인덱스(page index)는 스트리밍 시 필터를 가속화하고 Dataset Viewer 같은 효율적인 랜덤 접근을 가능하게 합니다.

Pandas와 PyArrow처럼 일부 라이브러리는 최적화된 Parquet 파일을 쓰려면 추가 인자가 필요합니다:

• use_content_defined_chunking=True — 중복 제거와 편집을 위한 Parquet Content Defined Chunking 활성화
• write_page_index=True — 스트리밍과 랜덤 접근을 위한 Parquet 메타데이터에 페이지 인덱스 포함

훈련 라이브러리 (Training Libraries)

Hub 데이터셋과 통합되어 모델 훈련을 지원하는 훈련 라이브러리. 아래 테이블은 데이터셋을 먼저 다운로드하지 않고도 훈련할 수 있는 스트리밍 능력을 보여줍니다.

Library	Description	Stream from Hub
Axolotl	로우코드 LLM 파인튜닝 프레임워크	✅
LlamaFactory	100+ LLM을 위한 통합 파인튜닝	✅
Sentence Transformers	텍스트 임베딩과 시맨틱 유사도	✅
Transformers	🤗 Transformers Trainer 모델 파인튜닝	✅
TRL	강화학습으로 LLM 훈련 (SFT, DPO, GRPO)	⚠️*
Unsloth	빠른 LLM 파인튜닝 (2배 속도, 70% 적은 메모리)	✅

* SFTTrainer와 DPOTrainer는 스트리밍을 지원하지만 GRPOTrainer는 아직 스트리밍 입력을 지원하지 않음

Hub에서 스트리밍하기 (Streaming from Hub)

스트리밍을 쓰면 데이터셋을 먼저 다운로드하지 않고도 대규모 데이터셋을 훈련할 수 있어요. 다음과 같은 경우에 유용합니다:

• 데이터셋이 디스크에 들어가기 너무 클 때
• 바로 훈련을 시작하고 싶을 때
• 계산 리소스가 함께 위치해 더 빠른 스트리밍을 제공하는 HF Jobs를 사용할 때

최근 개선으로 스트리밍은 더 빠른 시작, 프리페칭, 더 나은 worker 확장으로 최대 100배 더 효율적이 됐어요.

Note: 스트리밍은 데이터셋 길이를 알 수 없으므로 훈련 인자에 max_steps가 필요하고, 버퍼 기반 셔플링을 사용합니다. 자세한 내용은 streaming datasets을 참고하세요.

Hub에 로깅하기 (Logging to Hub)

일부 도구는 훈련 중 훈련 데이터를 Hub로 다시 스트리밍할 수 있어요:

• Trackio: 훈련 메트릭을 실시간으로 Hub 데이터셋에 스트리밍

데이터 라이브러리·도구를 Hub와 통합하기 (Integrating data libraries and tools with the Hub)

이 가이드는 Hugging Face Hub와 통합하려는 데이터 라이브러리·도구의 개발자와 유지보수자를 위해 설계됐어요. 데이터 처리 라이브러리, 분석 도구, 데이터셋과 상호작용해야 하는 어떤 소프트웨어든 Hub 통합을 구현하는 데 도움이 됩니다.

가이드에서 다루는 내용:

• Hub에서 라이브러리/도구로 데이터를 불러오는 가능한 접근법
• 라이브러리/도구에서 Hub로 데이터를 업로드하는 가능한 접근법

Hub에서 데이터 불러오기 (Loading data from the Hub)

데이터를 다루는 라이브러리가 있다면 사용자가 Hub에서 데이터를 불러오는 것이 도움이 될 수 있어요.

일반적으로 직접 구현할 특별한 이유가 없다면 datasets, pandas, polars 같은 기존 라이브러리에 의존하는 것을 권장합니다. 불러오는 과정을 더 제어해야 한다면 huggingface_hub을 사용할 수 있어요. 예를 들어 리포지토리의 특정 하위 파일 집합을 다운로드할 수 있습니다.

Hub에서 데이터를 불러오는 방법에 대한 자세한 내용은 여기에서 확인할 수 있어요.

Dataset Viewer와 Parquet 파일로 통합하기 (Integrating via the Dataset Viewer and Parquet Files)

Hub의 dataset viewer와 Parquet 변환 시스템은 원본 포맷에 관계없이 데이터셋과 통합하는 표준화된 방법을 제공합니다. 이 인프라는 Hub와 외부 라이브러리 사이의 신뢰할 수 있는 통합 계층이에요.

데이터셋이 아직 Parquet이 아니라면 Hub가 자동으로 모든 데이터셋의 첫 5GB를 Parquet 포맷으로 변환해 dataset viewer를 구동하고 일관된 접근 패턴을 제공합니다. 이 표준화는 라이브러리 통합에 여러 이점을 줍니다:

• 원본 포맷에 관계없이 일관된 데이터 접근 패턴
• Hub의 dataset viewer를 통한 내장 데이터셋 미리보기와 탐색. dataset viewer는 애플리케이션에 iframe으로도 임베드할 수 있어 풍부한 데이터셋 미리보기를 제공하기 쉽습니다. 임베드에 대한 자세한 내용은 dataset viewer embedding 문서를 참고하세요.
• 쿼리에 최적화된 효율적인 컬럼형 저장. 예를 들어 DuckDB 같은 도구로 특정 데이터 하위 집합을 쿼리하거나 필터링할 수 있어요.
• Parquet은 머신러닝과 데이터 과학 생태계 전반에서 잘 지원됩니다.

Dataset Viewer API 작업에 대한 자세한 내용은 Dataset Viewer API 문서를 참고하세요.

Hub에 데이터 업로드하기 (Uploading data to the Hub)

이 섹션은 라이브러리에 Hub로 데이터를 업로드하는 기능을 추가하는 가능한 접근법, 즉 push_to_hub 메서드를 구현하는 방법을 다룹니다.

이 가이드는 Hub에 데이터를 업로드하는 세 가지 주요 방법을 다룹니다:

• datasets 라이브러리와 push_to_hub 메서드 사용
• pandas로 Hub에 쓰기
• huggingface_hub 라이브러리와 hf_hub_download 메서드 사용
• API 또는 git-xet을 사용한 Git으로 직접 업로드

datasets 라이브러리 사용하기 (Use the datasets library)

Hub에 데이터를 올리는 가장 간단한 방법은 datasets 라이브러리의 기존 push_to_hub 메서드를 사용하는 것입니다. push_to_hub 메서드는 자동으로 다음을 처리합니다:

• 리포지토리 생성
• 데이터셋의 Parquet 변환
• 데이터셋을 적절한 부분으로 청킹
• 데이터 업로드

예를 들어 딕셔너리 리스트를 반환하는 합성 데이터 생성 라이브러리가 있다면 다음과 같이 할 수 있어요:

from datasets import Dataset

data = [{"prompt": "Write a cake recipe", "response": "Measure 1 cup ..."}]
ds = Dataset.from_list(data)
ds.push_to_hub("USERNAME_OR_ORG/repo_ID")

이런 종류의 통합 예시:

• Distilabel

기존 라이브러리의 Hub 통합에 의존하기 (Rely on an existing libraries integration with the Hub)

Polars, Pandas, Dask, Spark, DuckDB, Daft 모두 Hugging Face Hub 리포지토리에 쓸 수 있어요. 자세한 내용은 datasets libraries를 참고하세요.

코드에서 이미 이 라이브러리 중 하나를 사용하고 있다면 Hub에 푸시하는 기능을 추가하는 것은 간단합니다. 예를 들어 Pandas DataFrame을 반환하는 합성 데이터 생성 라이브러리가 있다면 Hub에 쓰는 코드는 다음과 같아요:

from huggingface_hub import HfApi

# Initialize the Hub API
hf_api = HfApi(token=os.getenv("HF_TOKEN"))

# Create a repository (if it doesn't exist)
hf_api.create_repo(repo_id="username/my-dataset", repo_type="dataset")

# Convert your data to a DataFrame and save directly to the Hub
df.to_parquet("hf://datasets/username/my-dataset/data.parquet")

huggingface_hub Python 라이브러리 사용하기 (Using the huggingface_hub Python library)

huggingface_hub Python 라이브러리는 Hub에 데이터를 업로드하는 더 유연한 방법을 제공합니다. 이 라이브러리는 리포지토리에 특정 파일이나 파일 하위 집합을 업로드할 수 있게 해줘요. Parquet으로 변환하고 싶지 않은 대규모 데이터셋이 있거나, 특정 파일 하위 집합을 업로드하고 싶거나, repo 구조를 더 제어하고 싶을 때 유용합니다.

사용 사례에 따라 코드의 특정 시점에 파일이나 폴더를 업로드할 수 있어요. 예를 들어 사용자가 "push to Hub"를 클릭할 때 도구에서 Hub로 주석을 내보내는 경우입니다. 예시:

from huggingface_hub import HfApi
api = HfApi(token=HF_TOKEN)

api.upload_folder(
    folder_path="/my-cool-library/data-folder",
    repo_id="username/my-cool-space",
    repo_type="dataset",
    commit_message="Push annotations to Hub"
    allow_patterns="*.jsonl",
)

Hub에 데이터를 업로드하는 방법에 대한 자세한 내용은 여기에서 확인할 수 있어요.

또한 10분마다 생성되는 합성 데이터처럼 백그라운드에서 데이터를 업로드하고 싶은 상황이 있을 수 있어요. 이 경우 huggingface_hub 라이브러리의 scheduled_uploads 기능을 사용할 수 있습니다. 자세한 내용은 scheduled uploads 문서를 참고하세요.

이 접근법으로 Hub에 데이터를 업로드하는 예시는 다음에서 볼 수 있어요:

• fastdata 라이브러리
• 이 magpie 데모 Space

더 많은 지원 (More support)

통합에 대한 기술적인 질문이 있으면 datasets 팀([email protected])에 연락해 주세요.

더 알아보기 (Learn more)

데이터셋 라이브러리별 상세 사용법은 각 라이브러리 문서 페이지(Argilla, Dask, DuckDB, Pandas 등)를, 스트리밍은 datasets-streaming을 참고하세요. Hub에 데이터를 올리는 push_to_hub 패턴은 datasets와 huggingface_hub 문서에서 자세히 다룹니다.