라이브러리

Datasets Hub는 오픈 소스 생태계의 여러 라이브러리를 지원합니다. huggingface_hub Python 라이브러리 덕분에 Hub에서 데이터셋을 공유하도록 설정하는 것이 쉽습니다. 머신러닝을 앞당기는 오픈 소스 라이브러리들을 Hub에 맞이하게 되어 기쁩니다.

라이브러리 표

아래 표는 지원되는 라이브러리와 해당 통합 수준을 요약합니다.

* 최적화된 Parquet 파일을 작성하려면 추가 인자를 전달해야 합니다

데이터 처리 라이브러리

스트리밍

Dataset streaming은 Hugging Face의 데이터셋을 완전히 다운로드하지 않고도 점진적으로 반복할 수 있게 합니다. 데이터가 디스크에 저장되지 않으므로 로컬 디스크 공간을 절약합니다. 한 번에 데이터셋의 일부만 사용되므로 메모리도 절약됩니다. CPU 또는 GPU 워크로드 전에 데이터를 다운로드할 필요가 없으므로 시간도 절약됩니다.

Hugging Face에서 스트리밍하는 것 외에도, 많은 라이브러리가 Hugging Face로 스트리밍하는 기능도 지원합니다. 따라서 이러한 라이브러리는 끝에서 끝으로(end-to-end) 스트리밍 파이프라인을 실행할 수 있습니다. 소스에서 스트리밍하여 Hugging Face에 점진적으로 기록하는 방식으로, 다운로드, 업로드, 처리 단계를 종종 겹쳐서 수행합니다.

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

최적화된 Parquet 파일

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 메타데이터에 페이지 인덱스를 포함하면 스트리밍 및 랜덤 액세스가 가능합니다.

학습 라이브러리

Hub 데이터셋과 통합되어 모델 학습을 지원하는 학습 라이브러리입니다. 아래 표는 스트리밍 기능, 즉 데이터셋을 먼저 다운로드하지 않고 학습할 수 있는 능력을 보여줍니다.

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

Hub에서 스트리밍

Streaming은 먼저 다운로드하지 않고도 대규모 데이터셋으로 학습할 수 있게 합니다. 이는 다음과 같은 경우에 유용합니다:

• 데이터셋이 디스크에 저장할 수 없을 정도로 너무 큽니다
• 즉시 학습을 시작하고 싶다면
• HF Jobs를 사용 중이며, 동일한 위치에 배치된 컴퓨트가 더 빠른 스트리밍을 제공합니다

최근 개선 사항으로 인해 시작 속도 향상, 사전 가져오기(prefetching), 다수의 워커에 대한 더 나은 확장성을 통해 스트리밍이 최대 100배 더 효율적이 되었습니다.

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

Hub에 로깅

일부 도구는 학습 중에 학습 데이터를 Hub로 스트리밍할 수 있습니다:

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

Hub에 데이터 라이브러리 및 도구 통합

이 가이드는 Hugging Face Hub와 통합을 원하는 데이터 라이브러리 및 도구의 개발자와 유지보수자를 대상으로 합니다. 데이터 처리 라이브러리, 분석 도구, 또는 데이터셋과 상호작용이 필요한 소프트웨어를 개발 중이시라면 이 문서를 통해 Hub 통합을 구현하는 데 도움을 받으실 수 있습니다.

이 가이드는 다음 내용을 다룹니다:

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

Hub에서 데이터 로드

데이터를 다루는 라이브러리가 있다면, 사용자에게 Hub에서 데이터를 로드하는 기능이 유용할 수 있습니다.

일반적으로 특별한 이유가 없는 한 datasets, pandas 또는 polars와 같은 기존 라이브러리를 사용하는 것을 권장합니다. 로딩 과정에 대한 더 세밀한 제어가 필요하면 huggingface_hub 라이브러리를 사용할 수 있으며, 이를 통해 저장소에서 특정 파일 하위 집합을 다운로드하는 등의 작업을 수행할 수 있습니다.

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

Dataset Viewer 및 Parquet 파일을 통한 통합

Hub의 데이터셋 뷰어와 Parquet 변환 시스템은 원본 형식과 관계없이 데이터셋을 통합하는 표준화된 방법을 제공합니다. 이 인프라는 Hub와 외부 라이브러리 간의 신뢰할 수 있는 통합 계층입니다.

데이터셋이 이미 Parquet 형식이 아닌 경우, Hub는 데이터셋 뷰어를 구동하고 일관된 접근 패턴을 제공하기 위해 모든 데이터셋의 처음 5GB를 자동으로 Parquet 형식으로 변환합니다. 이러한 표준화는 라이브러리 통합에 여러 가지 이점을 제공합니다:

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

Dataset Viewer API를 사용하는 방법에 대한 자세한 내용은 Dataset Viewer API 문서를 참조하세요.

Hub에 데이터 업로드

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

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

• datasets 라이브러리와 push_to_hub 메서드를 사용하여
• pandas를 사용하여 Hub에 작성
• huggingface_hub 라이브러리와 upload_folder 메서드를 사용하여

datasets 라이브러리를 사용하세요

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과 기존 라이브러리의 통합에 의존

Polars, Pandas, Dask, Spark, DuckDB, Daft는 모두 Hugging Face Hub 저장소에 쓸 수 있습니다. 자세한 내용은 위의 라이브러리 표를 참조하세요.

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

from huggingface_hub import HfApi

# Initialize the Hub API
hf_api = HfApi()

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

# 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 라이브러리 사용

huggingface_hub Python 라이브러리는 Hub에 데이터를 업로드하는 더 유연한 방법을 제공합니다. 이 라이브러리를 사용하면 저장소에 특정 파일 또는 파일의 하위 집합을 업로드할 수 있습니다. Parquet로 변환하지 않으려는 대규모 데이터셋이 있거나, 특정 파일의 하위 집합을 업로드하거나, 저장소 구조에 대한 더 세밀한 제어가 필요한 경우 유용합니다.

사용 사례에 따라 코드에서 특정 지점에서 파일 또는 폴더를 업로드할 수 있습니다. 예를 들어, 사용자가 “Hub에 push”를 클릭할 때 도구에서 어노테이션을 Hub로 내보내는 경우입니다. 예를 들어,

from huggingface_hub import HfApi
api = HfApi()

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

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

대신, 백그라운드에서 데이터를 업로드하고 싶은 상황이 있을 수 있습니다. 예를 들어, 10분마다 생성되는 합성 데이터가 있습니다. 이 경우 huggingface_hub 라이브러리의 CommitScheduler 클래스를 사용할 수 있습니다. 자세한 내용은 예약 업로드 문서를 참고하세요.

이 접근법을 사용하여 Hub에 데이터를 업로드하는 예시를

• fastdata 라이브러리
• 이 magpie 데모 스페이스

추가 지원

통합에 대한 기술적인 질문이 있으시면 datasets@huggingface.co로 datasets 팀에 문의해 주세요.