데이터셋 인제스트하기

데이터셋 인제스트하기 (Ingesting Datasets)

데이터는 일반적으로 AI 워크플로에 적합하지 않은 형태로 데이터베이스나 클라우드 스토리지에 저장돼 있어요. 데이터를 허브에 인제스트하는 것은 데이터를 AI-ready 데이터셋으로 게시하는 좋은 방법이에요. 이렇게 하면 데이터 로딩·처리, 모델 학습·평가가 쉽고 효율적으로 이뤄져요.

출처: 문서

본문

`huggingface_hub` 사용하기

데이터를 인제스트하는 가장 간단한 방법은 huggingface_hub으로 데이터 파일을 업로드하는 것이에요.

huggingface_hub Python 라이브러리는 저장소 생성, 데이터셋 업로드 등 저장소를 관리할 수 있는 풍부한 기능을 제공해요. 자세한 내용은 클라이언트 라이브러리 문서를 참고하세요.

이는 데이터가 정적/고정(frozen)이고, 허브가 지원하는 형식(예: Parquet, JSON Lines)의 로컬 덤프를 유용한 구조(예: 학습·평가용으로 잘 정의된 필드)로 쉽게 얻을 수 있을 때 적합해요.

`dlt` 사용하기

dlt는 데이터 이동(ETL)을 위한 오픈소스 Python 라이브러리로, 데이터 파이프라인을 구축하는 개발자(및 그들의 에이전트)에게 유용해요. 다양한 소스 유형에서 데이터를 인제스트할 수 있어요:

클라우드 스토리지 또는 파일
REST API
SQL 데이터베이스
Python 제너레이터

소스 유형의 예:

filesystem(s3, gs, az, abff 등 포함)
sql_database, mongodb, google_sheets
notion, hubspot, rest_api

소스 목록에서 내 소스 유형을 찾아 dlt 프로젝트를 만드세요:

dlt init <source-type> filesystem

그런 다음 dlt 프로젝트 루트에 설정 파일 .dlt/secrets.toml을 만들어 허브를 데이터셋의 filesystem 목적지로 정의할 수 있어요(hf:// 프로토콜 기반):

[destination.filesystem]
bucket_url = "hf://datasets/<namespace>"

[destination.filesystem.credentials]
hf_token = "hf_..."  # Your Hugging Face Access Token

namespace는 데이터셋을 인제스트하려는 사용자 이름 또는 조직/팀 이름이어야 해요.

그러면 각 dlt 데이터셋은 Hugging Face 데이터셋 저장소를 만들거나 업데이트해요. 저장소 이름은 / 입니다. 여기서 <org or team>은 bucket_url에서 사용한 것(조직 또는 팀)과 같고, <dataset_name>은 파이프라인의 dataset_name이에요.

다음은 예시 파이프라인이에요:

import dlt

@dlt.resource
def my_data():
    # One of the functions auto-generated by `dlt init` that you can customize,
    # or you can define your own python generator function.

    # Here is an example from the `chess` source type:
    for player in ['magnuscarlsen', 'rpragchess']:
        response = requests.get(f'https://api.chess.com/pub/player/{player}')
        response.raise_for_status()
        yield response.json()

# Requires bucket_url = "hf://datasets/<namespace>" in .dlt/secrets.toml
pipeline = dlt.pipeline(
    pipeline_name="my_pipeline",
    destination="filesystem",
    dataset_name="dataset_name",
)

pipeline.run(my_data())

dlt 리소스를 커스터마이즈해 원하는 데이터를 로드하고 데이터셋에 게시하고 싶은 필드(예: 학습·평가에 필요한 텍스트)를 파싱하세요.

다른 라이브러리 사용하기

🤗 Datasets, Pandas, Polars, Dask, DuckDB, Spark, Daft 같은 일부 라이브러리는 다양한 곳에서 허브로 데이터를 인제스트할 수 있어요. 자세한 내용은 Datasets Hub가 지원하는 라이브러리 목록을 참고하세요.

원시 데이터 인제스트

AI-ready 데이터셋으로 게시되기 전에 추가 큐레이션이 필요한 원시 데이터를 인제스트하거나, S3 같은 경험을 원한다면 Hugging Face Storage Buckets로 인제스트하는 것을 고려해 보세요.

데이터가 이미 데이터셋, 모델, 또는 Space 저장소에 있다면 hf buckets cp로 서버 측에서 버킷으로 복사할 수 있어요(다운로드나 재업로드 없음):

hf cp hf://datasets/username/my-dataset/ hf://buckets/username/my-bucket/

Xet 콘텐츠 해시만 마이그레이션되므로 아주 큰 파일도 즉시 복사돼요. 저장소와 버킷 간 파일 복사를 참고하세요.

예약 인제스트 (Scheduled ingestion)

허브에서 같은 파일을 수천 번 업데이트할 때 몇 가지 제한이 있어요. 예를 들어 실행 중인 LLM 추론 서버의 생성 결과, 라이브 에이전트 트레이스, 실행 중인 모델 학습의 로그를 인제스트하고 싶을 수 있어요. 이런 경우 데이터를 허브의 데이터셋으로 업로드하는 것이 합리적이지만, 제대로 하기 어려울 수 있어요. 주된 이유는 데이터의 매 업데이트를 버전 관리하고 싶지 않기 때문이에요. git 저장소를 사용할 수 없게 만들 거예요.

세 가지 옵션이 있어요:

Dataset 저장소 대신 Storage Bucket 사용: Storage Buckets은 S3 같은 경험을 제공하며 git 기반이 아니므로 파일을 매우 자주 업데이트할 수 있어요. 아직 데이터셋으로 게시할 준비가 되지 않은 데이터(예: 아직 진화 중이거나 더 많은 큐레이션이 필요한 데이터)에 특히 유용해요.
CommitScheduler 사용: huggingface_hub의 CommitScheduler는 Dataset 저장소의 git 히스토리를 관리 가능하게 유지하면서 거의 실시간 인제스트를 제공해요. 분 단위 간격으로 git 커밋을 하도록 설정할 수 있어요.
Hugging Face Jobs로 인제스트 스크립트 스케줄링: Hugging Face Jobs는 Hugging Face 인프라에서 Python 스크립트를 실행하고 스케줄링하는 방법을 제공해요. Cron 구문으로 정의된 간격으로 인제스트 스크립트를 실행하도록 스케줄링하세요.

Storage Buckets로 고빈도 인제스트

git 기반인 Dataset 저장소와 달리, Storage Buckets의 파일은 매우 높은 빈도로 업데이트할 수 있어 거의 실시간 인제스트를 제공해요.

huggingface_hub의 batch_bucket_files()로 버킷의 파일을 업데이트하세요:

from huggingface_hub import batch_bucket_files

def update_bucket(local_files):
    destinations = [os.path.basename(local_file) for local_file in local_file]
    batch_bucket_files(bucket_id="username/bucket_name", add=[(local_file, dst) for local_file, dst in zip(local_files, destinations)])

또는 버킷의 파일에 추가(append)하고 새 항목마다 flush()할 수 있어요:

from huggingface_hub import hffs

with hffs.open("buckets/username/bucket_name/texts.jsonl", "a") as f:
    for text in live_texts_stream:
        f.write(json.dumps({"text": text}) + "\n")
        f.flush()

HfFileSystem은 기본 블록 크기가 5MiB인 fsspec 기반이므로, 실제로 flush는 새 데이터를 5MiB만큼 추가했을 때 업로드해요. 더 자주 업로드하려면 hffs.open()에서 blocksize를 낮추거나(예: 100 kiB용 hffs.open(..., blocksize=100 * 2 ** 10)), f.flush(force=True)를 사용하세요.

Hugging Face 스토리지는 Xet 기반이라 파일에 추가할 때 효율적인 I/O가 가능해요: 업로드는 중복 제거되고 새 데이터만 업로드돼요. 버킷에서 동적 데이터 인제스트에 대한 자세한 내용은 버킷 업로드 문서와 데이터셋 편집 문서를 참고하세요.

`CommitScheduler`로 거의 실시간 인제스트

아이디어는 로컬 폴더를 정기적으로 허브에 푸시하는 백그라운드 작업을 실행하는 것이에요. 데이터를 허브에 저장하고 싶지만(잠재적으로 수백만 항목), 각 사용자 입력을 실시간으로 저장할 필요는 없어요. 대신 데이터를 로컬 JSON 파일에 저장하고 10분마다 업로드할 수 있어요. 예를 들어:

import json
from huggingface_hub import CommitScheduler

folder_path = "path/to/files/to/ingest"
every = 10  # ingest every 10min

with CommitScheduler(repo_id="username/dataset_name", repo_type="dataset", folder_path=folder_path, every=every) as scheduler:
    # Write to the folder to ingest every 10min
    # For example:
    with open(folder_path + "/texts.jsonl", "a") as f:
        f.write(json.dumps({"text": text}) + "\n")
    ...

매번 전체를 재업로드하지 않고 동적 데이터를 인제스트하는 방법은 데이터셋 편집 문서에서 확인하세요.

예약 업로드에 대한 자세한 내용은 huggingface_hub 문서를 참고하세요.

Hugging Face Jobs로 Cron 기반 인제스트

스케줄에 따라 데이터를 인제스트하는 Python 스크립트를 실행하세요.

예를 들어 ingest.py 스크립트를 5분마다 실행하려면:

hf jobs scheduled uv run "*/5 * * * *" ingest.py

스크립트 의존성은 스크립트 헤더에 선언하거나 --with를 사용하세요. 예를 들어 dlt 파이프라인을 매일 자정에 실행하려면:

hf jobs scheduled uv run --with "dlt[hf]" "0 0 * * *" pipeline.py

각 실행의 로그는 hf jobs logs로 또는 Hugging Face 계정의 Jobs 페이지에서 직접 확인할 수 있어요.

Hugging Face Jobs에 대한 자세한 내용은 Jobs 문서를 참고하세요.

더 알아보기 (Learn more)

Storage Buckets 문서에서 S3 같은 데이터 인제스트 경험을 배울 수 있어요.
Datasets Hub가 지원하는 라이브러리에서 데이터 인제스트에 쓸 수 있는 다른 라이브러리를 확인하세요.

데이터셋 인제스트하기