버킷 통합

버킷 통합 (Bucket Integrations)

Storage Buckets는 huggingface_hub 파일시스템 인터페이스로 지원되는 hf://buckets/ 경로를 사용해 많은 Python 데이터 라이브러리에서 읽고 쓸 수 있어요.

출처: 문서

본문

Storage Buckets는 huggingface_hub 파일시스템 인터페이스로 지원되는 hf://buckets/ 경로를 사용해 많은 Python 데이터 라이브러리에서 읽고 쓸 수 있습니다.

기본 접근 메커니즘(마운트, 볼륨 마운트, fsspec)은 Access Patterns를 참고하세요.

pandas

import pandas as pd

df = pd.read_parquet("hf://buckets/username/my-bucket/data.parquet")
df.to_parquet("hf://buckets/username/my-bucket/output.parquet")

Dask

Dask는 파일당 하나의 파티션으로 lazily 읽고 씁니다. 그래서 메모리보다 큰 데이터셋을 버킷에서 직접 처리할 수 있어요:

import dask.dataframe as dd

df = dd.read_parquet("hf://buckets/username/my-bucket/data/")
df.to_parquet("hf://buckets/username/my-bucket/output/")

자세한 내용은 Hub에서의 Dask를 참고하세요.

Daft

Daft는 hf://buckets/ 경로를 네이티브로 지원하며, 기본적으로 Xet 가속 읽기가 활성화됩니다:

import daft
from daft.io import IOConfig, HuggingFaceConfig
from huggingface_hub import get_token

io_config = IOConfig(hf=HuggingFaceConfig(token=get_token()))
df = daft.read_parquet("hf://buckets/username/my-bucket/data.parquet", io_config=io_config)

PyArrow

import pyarrow.parquet as pq

table = pq.read_table("hf://buckets/username/my-bucket/data.parquet")

PySpark

pyspark_huggingface과 함께:

df = (
    spark.read.format("huggingface")
    .option("data_files", '["data.parquet"]')
    .load("buckets/username/my-bucket")
)

자세한 내용은 Hub에서의 PySpark를 참고하세요.

🤗 Datasets

from datasets import load_dataset

ds = load_dataset("buckets/username/my-bucket", data_files=["data.parquet"])

Inspect AI

Inspect AI는 평가 로그를 버킷에 직접 쓸 수 있어요 — 로그 디렉터리를 hf://buckets/ 경로로 지정하면 됩니다(huggingface_hub>=1.6.0 필요). 먼저 버킷을 만들고 인증하세요(Inspect가 자동으로 만들지 않습니다):

hf auth login
hf buckets create username/my-bucket --private

export INSPECT_LOG_DIR=hf://buckets/username/my-bucket/eval-logs
inspect eval popularity.py --model openai/gpt-4
inspect view

자세한 내용은 Inspect의 eval logs 가이드를 참고하세요.

SkyPilot

SkyPilot은 20개 이상의 클라우드, Kubernetes, 온프레미스에서 AI 워크로드를 실행하며, Hugging Face 스토리지를 백엔드로 사용할 수 있어요 — 그래서 하나의 버킷을 클라우드마다 사본을 두지 않고 모든 클라우드에서 읽을 수 있습니다. file_mounts 항목에 store: hf를 설정하면 버킷을 읽기-쓰기로, 리포지토리를 읽기 전용으로 마운트합니다:

# qwen-sft.yaml — launch anywhere: sky launch qwen-sft.yaml --infra aws|gcp|...
resources:
  accelerators: H100:1

file_mounts:
  /base-model:
    source: hf://Qwen/Qwen2.5-3B           # model repo, read-only
    store: hf
    mode: MOUNT
  /data:
    source: hf://datasets/username/[email protected]   # dataset repo, pinned to a tag, read-only
    store: hf
    mode: MOUNT
  /checkpoints:
    source: hf://buckets/username/qwen-sft   # bucket, read-write — checkpoints sync back
    store: hf
    mode: MOUNT

run: | python train.py --model /base-model --output_dir /checkpoints

한 번 인증 — `hf auth login`(또는 `export HF_TOKEN=<your-token>`)이면 SkyPilot에 충분합니다. 로컬 Hugging Face 토큰을 모든 클라우드로 전달하므로 버킷과 리포지토리 마운트가 자동으로 인증됩니다:

```bash
pip install "skypilot[huggingface]"
hf auth login                              # or: export HF_TOKEN=<your-token>
sky launch qwen-sft.yaml

자체 run 코드가 gated 리포지토리를 가져오면 launch 명령에 --secret HF_TOKEN을 추가해 env var로도 토큰을 노출하세요.

[!TIP] MOUNT와 MOUNT_CACHED는 hf에 대해 동일하게 동작하며 hf-mount FUSE 백엔드를 사용합니다. 이 백엔드는 glibc ≥ 2.34와 /dev/fuse가 있는 베이스 이미지가 필요해요. Bare-VM 클라우드는 둘 다 제공합니다. SkyPilot 기본 Kubernetes 이미지는 더 오래된 glibc를 제공하므로 더 새로운 image_id(예: docker:mirror.gcr.io/ubuntu:22.04)를 설정하세요. 현재 환경 요구사항은 SkyPilot storage 문서를 참고하세요.

벤치마크와 전체 워크스루는 SkyPilot + Hugging Face storage 블로그 포스트를 참고하세요.

파일시스템 연산 (Filesystem operations)

직접 파일 연산을 위해 huggingface_hub은 사전 인스턴스화된 파일시스템 객체 hffs를 노출합니다:

from huggingface_hub import hffs

with hffs.open("buckets/username/my-bucket/hello.txt", "w") as f:
    f.write("Hello world!")

hffs.cp("buckets/username/my-bucket/hello.txt", "buckets/username/my-bucket/hello2.txt")
hffs.rm("buckets/username/my-bucket/hello2.txt")
files = hffs.ls("buckets/username/my-bucket")
text_files = hffs.glob("buckets/username/my-bucket/*.txt")

다른 언어 (Other languages)

OpenDAL은 Rust, Java, Go, JavaScript 등에 대한 유사한 파일시스템 인터페이스를 제공합니다.

곧 제공 (Coming soon)

Polars, DuckDB, webdataset를 포함한 더 많은 라이브러리에 네이티브 hf:// URL 지원이 준비 중입니다. 그동안 이 모든 것은 S3 호환 API를 통해 이미 동작합니다.

더 알아보기 (Learn more)

hf://buckets/ 경로는 pandas·Dask·Daft·PyArrow·PySpark·🤗 Datasets 등 많은 라이브러리와 바로 연동돼요. Inspect AI는 평가 로그를, SkyPilot은 store: hf 마운트로 버킷을 활용하며, hffs 파일시스템으로 직접 파일 연산도 가능합니다. 마운트·fsspec 접근 패턴은 storage-buckets-access를 참고하세요.