스토리지 버킷(Storage Buckets)

스토리지 버킷(Storage Buckets)

Storage Buckets는 Xet 스토리지 백엔드로 구동되는 S3 유사 객체 스토리지를 제공하는 Hugging Face Hub의 저장소 유형이에요. Git 기반 저장소(모델, 데이터셋, Spaces)와 달리 버킷은 버전 관리되지 않고(비버전) 수정 가능하며(mutable), 학습 체크포인트, 로그, 중간 아티팩트처럼 버전 관리가 필요 없는 단순·빠른 스토리지가 필요한 사용 사례를 위해 설계됐어요.

출처: 문서

본문

버킷과 상호작용하려면 Hub 웹 인터페이스, hf CLI, 또는 Python API를 사용할 수 있어요.

[!TIP] 버킷은 모든 사용자와 조직이 이용할 수 있어요. 가격은 hf.co/storage를 참고하세요.

[!TIP] 도구에서 버킷 데이터에 접근하는 방법(파일시스템으로 마운트, hf:// 경로, Jobs/Spaces의 볼륨 마운트)은 Access Patterns, 기존 S3 툴링(AWS CLI, boto3, s5cmd) 사용은 S3-Compatible API, pandas, Dask, Spark 같은 인기 데이터 라이브러리의 바로 사용 가능한 스니펫은 Bucket Integrations를 참고하세요.

버킷 vs 저장소

Hub는 두 가지 스토리지 유형을 제공해요: 버전 관리·협업 작업용 Git 기반 저장소와 빠르고 수정 가능한 객체 스토리지용 버킷.

기능	저장소 (Git 기반)	스토리지 버킷
버전 관리	전체 Git 이력	없음 (수정 가능, 제자리 덮어쓰기)
유형	모델, 데이터셋, Spaces	독립 버킷
주요 용도	완성된 아티팩트 게시	작업 스토리지 / 중간 데이터
작업	Hub API, Git push/pull	S3 유사 sync, cp, rm
중복 제거	Xet chunk 수준	Xet chunk 수준
풀 리퀘스트	예	아니요
모델/데이터셋 카드	예	아니요 (하지만 일반 README 렌더링)

버전 이력, 협업 기능(PR, 토론), 라이브러리 통합을 원하면 저장소를 사용하세요. 자주 바뀌는 데이터를 위한 빠르고 수정 가능한 스토리지가 필요하면 버킷을 사용하세요 — 파일을 제자리에서 덮어쓰거나 삭제할 수 있어요.

버킷 만들기

Hub UI에서

1. huggingface.co/new-bucket로 이동한다.
2. 버킷 소유자를 지정한다: 당신 또는 소속된 조직.
3. 버킷 이름을 입력한다.
4. 버킷을 public 또는 private으로 할지 선택한다.
5. 선택적으로, 시작부터 데이터를 컴퓨트에 가깝게 캐시하도록 CDN pre-warming 리전을 미리 선택한다.

버킷을 만들면 버킷 페이지가 보여요.

CLI에서

# Create a bucket under your namespace
hf buckets create my-bucket

# Create a private bucket
hf buckets create my-bucket --private

# Create a bucket under an organization
hf buckets create my-org/shared-bucket

Python에서

from huggingface_hub import create_bucket

# Create a bucket under your namespace
create_bucket("my-bucket")

# Create a private bucket
create_bucket("my-bucket", private=True)

# Create a bucket under an organization
create_bucket("my-org/shared-bucket")

공개 여부 변경

생성 후 버킷의 공개 여부를 바꿀 수 있어요:

# Make a bucket private
hf buckets settings username/my-bucket --private

# Make it public again
hf buckets settings username/my-bucket --public

from huggingface_hub import update_bucket_settings

update_bucket_settings("username/my-bucket", private=True)
update_bucket_settings("username/my-bucket", private=False)

삭제, 이동, 목록을 포함한 전체 Python API 레퍼런스는 huggingface_hub Buckets 가이드를 참고하세요.

Hub에서 버킷 둘러보기

모든 버킷에는 Hub에 페이지가 있어 내용을 탐색하고, 디렉터리를 이동하고, 파일 세부 정보를 볼 수 있어요. 버킷 페이지는 https://huggingface.co/buckets/<owner>/<bucket-name>에서 확인할 수 있어요.

README 렌더링

버킷의 디렉터리에 README.md 파일이 있으면 Hub가 해당 디렉터리 페이지의 파일 목록 아래에 렌더링해요. 버킷 루트와 하위 디렉터리 안 어디서든 작동해요 — 버킷에 무엇이 있는지, 데이터가 어떻게 정리됐는지, 다운스트림 도구가 어떻게 소비해야 하는지 문서화하는 데 유용해요.

CLI에서 목록 보기

CLI에서 버킷 내용을 나열할 수도 있어요:

# List files in a bucket (with human-readable sizes)
hf buckets list julien-c/my-training-bucket -h
                     Feb 17 14:46  art/
                     Feb 17 14:58  arxivqa/
                     Feb 17 15:02  arxivqa2/
                     Feb 17 15:04  arxivqa3/
                     Feb 17 14:47  captcha/
                     Feb 17 14:53  captcha2/
                     Feb 24 17:22  julien/

# Recursive listing
hf buckets list julien-c/my-training-bucket/art -h -R
    423.6 MB         Feb 17 14:29  art/train-00000-of-00011.parquet
    441.0 MB         Feb 17 14:29  art/train-00001-of-00011.parquet
    521.7 MB         Feb 17 14:29  art/train-00002-of-00011.parquet
    481.4 MB         Feb 17 14:29  art/train-00003-of-00011.parquet
    444.6 MB         Feb 17 14:29  art/train-00004-of-00011.parquet
    461.6 MB         Feb 17 14:29  art/train-00005-of-00011.parquet
    466.4 MB         Feb 17 14:29  art/train-00006-of-00011.parquet
    486.3 MB         Feb 17 14:29  art/train-00007-of-00011.parquet
    477.0 MB         Feb 17 14:29  art/train-00008-of-00011.parquet
    454.0 MB         Feb 17 14:29  art/train-00009-of-00011.parquet
    483.1 MB         Feb 17 14:29  art/train-00010-of-00011.parquet

# Tree view
hf buckets list julien-c/my-training-bucket --tree -h -R
                        ├── art/
423.6 MB  Feb 17 14:29  │   ├── train-00000-of-00011.parquet
441.0 MB  Feb 17 14:29  │   ├── train-00001-of-00011.parquet
...

파일 관리

Hub의 버킷 페이지에서 직접 파일을 업로드·다운로드하거나 CLI와 Python API를 프로그래밍 방식으로 쓸 수 있어요. 버킷 파일은 hf://buckets/ 경로로 참조돼요(예: hf://buckets/username/my-bucket/path/to/file). hf buckets cp 명령은 개별 파일 전송을, hf buckets sync는 디렉터리 전송에 더 적합해요. 모든 명령은 양방향(로컬→원격, 원격→로컬)으로 작동해요.

데이터가 이미 모델·데이터셋·Space 저장소(또는 다른 버킷)에 있다면 hf buckets cp로 서버 측 복사를 할 수 있어요 — 다운로드나 재업로드가 필요 없어요. 저장소와 버킷 간 파일 복사를 참고하세요.

파일 업로드

빠른 업로드는 브라우저의 버킷 페이지에 파일을 직접 드래그 앤 드롭하면 돼요. 프로그래밍 방식으로는 hf buckets cp가 개별 파일을 버킷에 복사해요. 소스는 로컬 경로, 대상은 hf://buckets/ 경로예요. stdin에서 데이터를 파이프할 수도 있는데, 프로그래밍 방식으로 생성된 콘텐츠에 유용해요.

CLI:

# Upload a single file
hf buckets cp ./model.safetensors hf://buckets/username/my-bucket/models/model.safetensors

# Upload from stdin
cat config.json | hf buckets cp - hf://buckets/username/my-bucket/config.json

Python에서는 batch_bucket_files로 한 번의 호출에 여러 파일을 업로드해요. 각 항목은 (local_path, remote_path) 튜플이에요.

Python:

from huggingface_hub import batch_bucket_files

batch_bucket_files(
    "username/my-bucket",
    add=[
        ("./model.safetensors", "models/model.safetensors"),
        ("./config.json", "models/config.json"),
    ],
)

더 많은 업로드 옵션(원시 바이트, 업로드+삭제 결합 등)은 huggingface_hub upload 가이드를 참고하세요.

파일 다운로드

Hub의 버킷 페이지에서 파일을 클릭해 직접 다운로드할 수 있어요. 프로그래밍 방식 접근은 업로드 문법을 미러링해요 — hf buckets cp에서 소스와 대상을 바꾸면 돼요. 대상으로 -를 사용하면 파일을 stdout으로 스트리밍해 버킷 내용을 다른 도구에 직접 파이프할 수 있어요.

CLI:

# Download a single file
hf buckets cp hf://buckets/username/my-bucket/models/model.safetensors ./model.safetensors

# Download to stdout and pipe
hf buckets cp hf://buckets/username/my-bucket/config.json - | jq .

Python에서는 download_bucket_files를 (remote_path, local_path) 튜플 목록과 함께 사용해요.

Python:

from huggingface_hub import download_bucket_files

download_bucket_files(
    "username/my-bucket",
    files=[
        ("models/model.safetensors", "./local/model.safetensors"),
        ("config.json", "./local/config.json"),
    ],
)

미리 가져온 메타데이터로 더 빠른 다운로드를 하려면 huggingface_hub download 가이드를 참고하세요.

디렉터리 동기화

sync 명령은 rsync나 aws s3 sync처럼 작동해요 — 소스와 대상을 비교해 변경된 파일만 전송해요. 로컬 디렉터리와 버킷을 동기화 상태로 유지하는 가장 효율적인 방법이에요. 기본적으로 sync는 파일을 추가·업데이트만 해요. 소스에 더 이상 없어 대상에서 제거할 파일도 삭제하려면 --delete를 전달하세요. 실제로 전송하지 않고 무엇이 일어날지 미리 보려면 --dry-run을 사용하세요.

CLI:

# Upload a local directory to a bucket
hf buckets sync ./data hf://buckets/username/my-bucket/data

# Download from a bucket to a local directory
hf buckets sync hf://buckets/username/my-bucket/data ./data

# Sync with deletion of extraneous files
hf buckets sync ./data hf://buckets/username/my-bucket/data --delete

# Preview what would be synced without executing
hf buckets sync ./data hf://buckets/username/my-bucket/data --dry-run

# Plan and apply: review the sync plan before executing
hf buckets sync ./data hf://buckets/username/my-bucket/data --plan sync-plan.jsonl
# ... review the plan file, then apply it
hf buckets sync --apply sync-plan.jsonl

[!TIP] hf sync는 hf buckets sync의 편리한 별칭이에요.

Python:

from huggingface_hub import sync_bucket

# Upload a local directory to a bucket
sync_bucket("./data", "hf://buckets/username/my-bucket/data")

# Download from a bucket to a local directory
sync_bucket("hf://buckets/username/my-bucket/data", "./data")

sync 명령은 필터링(--include, --exclude), 비교 모드(--ignore-times, --existing), 실행 전 작업을 검토하는 plan-and-apply 워크플로를 지원해요. 전체 옵션은 huggingface_hub sync 가이드를 참고하세요.

파일 삭제

버킷은 비버전이라 삭제는 즉각적이고 영구적이에요 — 삭제된 파일을 복구할 방법이 없어요. 특히 --recursive를 쓸 때 파일을 제거하기 전에 --dry-run으로 한 번 더 확인하세요.

CLI:

# Remove a single file
hf buckets rm username/my-bucket/old-model.bin

# Remove all files under a prefix
hf buckets rm username/my-bucket/logs/ --recursive

# Preview what would be deleted
hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-run

Python:

from huggingface_hub import batch_bucket_files

batch_bucket_files("username/my-bucket", delete=["old-model.bin", "logs/debug.log"])

더 많은 삭제 옵션(패턴 기반 필터링, 재귀 제거 등)은 huggingface_hub delete 가이드를 참고하세요.

저장소와 버킷 간 파일 복사

어떤 저장소(모델, 데이터셋, Space)나 버킷의 Xet 추적 파일을 데이터를 재업로드하지 않고 대상 버킷에 복사할 수 있어요. 복사는 서버 측에서 일어나며, Xet 콘텐츠 해시만 마이그레이션되므로 chunk 수준 중복 제거 덕분에 아주 큰 파일도 즉시 복사돼요.

[!NOTE] Xet 추적 파일만 서버 간 복사돼요. 작은 비-Xet 파일(예: config 파일과 README)은 자동으로 다운로드·재업로드돼요. 서버 측 복사는 소스와 대상이 같은 스토리지 리전에 있어야 해요.

CLI:

hf buckets cp \
  hf://datasets/HuggingFaceFW/fineweb/data \
  hf://buckets/username/fineweb-data

Python:

from huggingface_hub import HfApi

api = HfApi()

api.copy_files(
    "hf://datasets/HuggingFaceFW/fineweb/data",
    "hf://buckets/username/fineweb-data",
)

소스 저장소 또는 버킷에 읽기 접근, 대상 버킷에 쓰기 접근이 필요해요.

반대 방향(버킷에서 저장소로 재업로드 없이 전송)은 아직 불가능하지만 로드맵에 있어요.

변경 추적

버킷은 수정 가능하므로 버킷 뷰를 유지하는 도구(마운트, 파일시스템 레이어, 동기화 데몬, 대시보드)는 파일이 언제 바뀌는지 알아야 해요. 두 메커니즘이 있어요:

• 웹훅: 자동화와 통합을 위해 제어하는 서버로의 HTTP 콜백.
• 라이브 팔로우: 클라이언트가 구독하는 server-sent events 스트림.

라이브 팔로우

GET https://huggingface.co/api/buckets/<owner>/<bucket-name>/events는 버킷의 파일 변경을 server-sent events로 스트리밍해요. 요청은 Accept: text/event-stream을 담아야 하고(그렇지 않으면 400 반환), 버킷 나열과 같은 읽기 접근이 필요해요 — 공개 버킷에는 토큰이 필요 없어요. 전체 파라미터와 응답 스키마는 OpenAPI spec을 참고하세요.

curl -N -H "Accept: text/event-stream" \
  -H "Authorization: Bearer ***" \
  "https://huggingface.co/api/buckets/username/my-bucket/events"

스트림은 네 가지 이벤트 유형을 발행해요:

이벤트	데이터	의미
ready	{"cursor": "..."}	요청된 replay가 완료되고 라이브 변경이 이어진다.
changes	{"cursor": "..."， "changes": [...]}	짧은 창에 걸쳐 합쳐진 파일 변경 배치.
reset	{"reason": "cursor_too_old"}	재개 지점을 replay할 수 없어 스트림이 끝나고 버킷을 다시 나열해야 한다.
reconnect	{"cursor": "..."}	서버가 의도적으로 스트림을 닫는다; 그 cursor로 재연결.

changes의 각 항목에는 path와 op(add, update, delete)가 있어요. add 또는 update는 변경된 필드도 담아요 — size, xetHash, uploadedAt, mtime, mtimeNanos — 그래서 update는 파일이 동일하게 재업로드될 때 새 uploadedAt만큼 작을 수 있어요. 변경되지 않은 필드는 생략되며, mtime/mtimeNanos는 업로드가 이를 지웠을 때 null일 수 있으니 부재와 null을 같게 취급하세요. xetHash는 버킷 콘텐츠에 읽기 접근이 있을 때만 포함돼요.

event: ready
data: {"cursor":"..."}

event: changes
data: {"cursor":"...","changes":[{"path":"data/train.txt","op":"add","size":20,"uploadedAt":"2026-09-16T09:21:45.000Z"},{"path":"data/old.txt","op":"delete"}]}

재개(Resuming). 모든 ready와 changes 이벤트는 불투명한 cursor를 담아요. ?cursor=<cursor>로 재연결해 그 이후의 변경을 받거나, ?since=<ISO timestamp>(포함, 예: 2026-09-16T09:21:45Z)로 한 시점부터 재개할 수 있어요. 두 파라미터 모두 없으면 연결 후 발생하는 변경만 받아요.

지난 약 15분의 변경만 replay할 수 있어요. cursor나 since가 그보다 오래되면 replay 대신 reset을 받아요: 버킷을 한 번 나열해 뷰를 재구축한 다음, 새 스트림 ready 이벤트의 cursor부터 다시 팔로우하세요. 재개는 끊긴 연결이나 재시작 같은 짧은 간격을 메우기 위한 것이며, 오래 떨어져 있던 클라이언트는 다시 나열해야 할 거예요.

재연결(Reconnecting). 오래 지속되는 연결은 재활용돼요: 약 20분마다(그리고 배포 중에) 서버가 reconnect를 보내고 스트림을 끝내요. 스트림의 어떤 끝이든 같은 방식으로 취급하세요 — 마지막으로 받은 cursor로 재연결해요. cursor 없는 reconnect가 오면 원래 요청한 cursor나 since로 재연결하세요. 연결을 유지하기 위해 30초마다 : ping 주석이 전송되므로, 완전히 조용해진 스트림은 죽은 것으로 간주할 수 있어요.

503 응답은 라이브 팔로우가 일시적으로 불가능하다는 뜻이에요 — Retry-After 헤더의 지연 후 재시도하세요.

Pre-warming과 CDN

버킷은 기본적으로 Hub의 글로벌 스토리지에 있어요. 스토리지 위치가 처리량에 직접 영향을 주는 워크로드의 경우 pre-warm으로 버킷 데이터를 컴퓨트에 더 가깝게 가져올 수 있어요.

Pre-warming은 특정 클라우드 프로바이더와 리전 근처의 에지 위치에 파일을 캐시해, 작업이 리전을 가로질러 데이터를 끌어오는 대신 로컬에서 읽게 해줘요. 특히 유용한 경우:

• 큰 데이터셋이나 체크포인트에 빠른 접근이 필요한 학습 클러스터.
• 파이프라인의 다른 부분이 다른 클라우드에서 실행되는 다중 리전 설정.
• 큰 아티팩트를 전 세계 많은 소비자에게 배포.

사용 가능한 리전과 pre-warming 활성화 세부 사항은 hf.co/storage를 참고하세요.

사용 사례

학습 체크포인트와 로그

학습 작업을 실행할 때(예: Jobs로), 체크포인트와 로그를 버킷에 저장하세요. Git 저장소와 달리 버전 이력을 쌓지 않고 최신 체크포인트를 덮어쓸 수 있고, sync가 변경된 데이터만 전송하게 해줘요.

# After each evaluation step, sync checkpoints to a bucket
hf sync ./checkpoints hf://buckets/my-org/training-run-42/checkpoints

버킷이 Xet 기반이므로, 모델의 큰 부분이 동결된 연속 체크포인트는 chunk 수준 중복 제거의 이점을 받아요. 변경된 chunk만 업로드돼요.

데이터 처리 파이프라인

버킷은 데이터 처리 워크플로의 스테이징 영역 역할을 해요. 원시 데이터를 처리하고 중간 출력을 버킷에 쓴 다음, 파이프라인이 완료되면 최종 아티팩트를 버전 관리되는 Dataset 저장소로 승격해요. 이렇게 하면 버전 저장소를 깨끗하게 유지하면서 파이프라인에 빠르고 수정 가능한 스토리지를 제공해요.

버킷에서 저장소로 재업로드 없이 전송하는 것은 아직 불가능하지만 로드맵에 있어요.

에이전트 스토리지

AI 에이전트는 중간 결과, 도구 출력, 트레이스, 작업 메모리를 위한 임시 스토리지가 필요해요. 버킷은 이 데이터를 위한 Hub 네이티브 장소를 제공해요: Git 오버헤드 없이 빠르고 수정 가능한 접근, 표준 Hugging Face 권한, Hub 생태계 전반에서 hf://buckets/ 경로로 주소 지정 가능.

롤링 백업

버킷은 롤링 백업 유지에 잘 맞아요. Git 기반 Dataset 저장소에서는 오래된 파일을 삭제해도 스토리지가 확보되지 않아요 — Git 이력이 과거 버전을 모두 유지하므로, 실제로 공간을 되찾으려면 커밋을 스쿼시하거나 이력을 다시 써야 해요. 버킷에서는 삭제된 옛 파일이 정말로 사라지고, 현재 저장된 것에 대해서만 비용을 내요.

# Sync today's backup, removing files that no longer exist locally
hf sync ./daily-backup hf://buckets/my-user/backups/latest --delete

모델을 버킷에 연결하기

모델 카드 메타데이터에 buckets 필드를 추가해 모델과 버킷 사이의 양방향 링크를 만들 수 있어요. 연결된 모델이 버킷 페이지에 나타나고, 버킷이 모델 페이지에 태그로 나타나요.

# In the model card YAML frontmatter
buckets:
- my-org/my-bucket

자세한 내용은 모델 카드 문서의 Specifying a bucket을 참고하세요.

가격

Storage Buckets는 저장된 데이터 양에 따라 간단한 TB당 가격으로 청구돼요. Enterprise 플랜은 파일 간 공유 chunk가 청구 대상 공간을 직접 줄여주는 중복 제거 기반 청구의 이점을 받아요.

다른 저장소처럼 버킷은 생성이 무료이고 무료 스토리지 허용량이 있어요. 무료 티어 이상의 사용량은 hf.co/storage를 참고하세요. 일반적인 청구 정보는 Billing 문서를 참고하세요.

더 알아보기 (Learn more)

• S3-Compatible API로 기존 S3 툴링을 활용해 보세요.
• huggingface_hub Buckets 가이드에서 Python API를 익혀 보세요.