Hub documentation

버킷 통합

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

버킷 통합

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은 파일당 파티션 하나씩 지연 평가 방식으로 읽기 및 쓰기를 수행하므로, 버킷에서 메모리보다 큰 데이터셋을 바로 처리할 수 있습니다:

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-accelerated reads가 기본적으로 활성화되어 있습니다:

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 로그 가이드를 참조하세요.

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/my-data@v1.0   # 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 토큰을 모든 클라우드에 전달하므로, 버킷과 리포지토리 마운트가 자동으로 인증됩니다:

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

사용자의 run 코드가 게이트된 리포지토리를 가져오는 경우, 토큰을 환경 변수로도 노출하려면 런치 명령에 --secret HF_TOKEN를 추가하세요.

MOUNT와 MOUNT_CACHED는 hf의 경우 동일한 방식으로 동작하며, glibc ≥ 2.34와 /dev/fuse가 포함된 베이스 이미지를 요구하는 hf-mount FUSE 백엔드를 사용합니다. 베어 VM 클라우드에서는 이 두 가지가 모두 제공됩니다. SkyPilot의 기본 Kubernetes 이미지는 구버전의 glibc를 포함하고 있으므로, 더 새로운 image_id(예: docker:mirror.gcr.io/ubuntu:22.04)를 설정해야 합니다. 최신 환경 요구 사항은 SkyPilot 스토리지 문서를 참고하세요.

벤치마크와 전체 가이드는 SkyPilot + Hugging Face 스토리지 블로그 게시물을 참고하세요.

파일 시스템 작업

직접적인 파일 작업을 위해 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")

DuckDB

DuckDB 2.0 이상에서는 httpfs 확장(쓰기에는 hf 확장)을 통해 hf://buckets/ 경로를 CLI 및 모든 클라이언트에서 네이티브로 읽을 수 있습니다:

SELECT * FROM 'hf://buckets/username/my-bucket/data/**/*.parquet' LIMIT 10;
COPY tbl TO 'hf://buckets/username/my-bucket/out.parquet';

비공개 버킷 및 이전 DuckDB 버전에 대해서는 DuckDB로 쿼리를 참조하세요.

기타 언어

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

곧 출시 예정

더 많은 라이브러리, 즉 Polars와 WebDataset를 포함하여 네이티브 hf:// URL 지원이 곧 제공됩니다. 그 동안에도 이 모든 것은 이미 S3 호환 API를 통해 작동합니다.

Update on GitHub