Integrasi Bucket

Sebagian besar alat sudah dapat menggunakan bucket, dengan salah satu dari dua cara berikut:

• Perpustakaan Python yang dibangun di atas fsspec (pandas, Dask, PyArrow, dan lainnya) membaca dan menulis jalur hf://buckets/ melalui antarmuka sistem berkas huggingface_hub.
• Alat yang berkomunikasi dengan S3 (boto3, AWS CLI, rclone, DVC, dan lainnya) bekerja terhadap API yang kompatibel dengan S3.

Halaman ini membahas pustaka dengan dukungan bucket bawaan, serta contoh untuk pustaka data umum. Untuk mount dan volume mount, lihat Pola Akses.

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 membaca dan menulis secara lazy, satu partisi per file, sehingga Anda dapat memproses dataset yang lebih besar dari memori langsung dari sebuah bucket:

import dask.dataframe as dd

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

Lihat Dask di Hub untuk informasi lebih lanjut.

Daft

Daft mendukung jalur hf://buckets/ secara native, dengan read yang dipercepat Xet diaktifkan secara default:

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

Dengan pyspark_huggingface terinstal:

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

Lihat PySpark di Hub untuk informasi lebih lanjut.

🤗 Datasets

from datasets import load_dataset

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

datatrove

datatrove readers dan writers menerima path hf://buckets/. HuggingFaceBucketWriter mengunggah output besar dengan Xet:

from datatrove.pipeline.readers import ParquetReader
from datatrove.pipeline.writers import HuggingFaceBucketWriter

reader = ParquetReader(data_folder="hf://buckets/username/my-bucket/raw/")
writer = HuggingFaceBucketWriter(bucket="username/my-bucket", prefix="filtered")

Lihat README datatrove untuk informasi lebih lanjut.

LeRobot

LeRobot dapat mengalirkan dataset pelatihan dari sebuah bucket. Bucket tersebut harus menyimpan dataset lengkap (meta/, file Parquet dan video) di akarnya:

lerobot-train \
  --dataset.repo_id=username/my-bucket \
  --dataset.repo_type=bucket \
  --dataset.streaming=true \
  --policy.type=act

Diffusers

diffusers-cli run mengunggah output-nya ke bucket dengan --push-to. Bucket akan dibuat jika belum ada:

diffusers-cli run --model black-forest-labs/FLUX.1-dev --dtype bf16 \
  --pipeline-kwargs '{"prompt": "an astronaut riding a horse"}' \
  --push-to hf://buckets/username/my-bucket/outputs

Lihat panduan CLI Diffusers untuk informasi lebih lanjut.

Trackio

Ketika Trackio mencatat ke sebuah Space, data run disimpan dalam bucket yang dibuat dari ID Space. Sampaikan bucket_id ke trackio.init() untuk menggunakan bucket yang Anda pilih.

Inspect AI

Inspect AI dapat menulis log evaluasi langsung ke bucket — arahkan direktori log-nya ke path hf://buckets/ (memerlukan huggingface_hub>=1.6.0). Buat bucket dan autentikasi terlebih dahulu (Inspect tidak akan membuatnya untuk Anda):

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

Lihat panduan log eval Inspect untuk detailnya.

SkyPilot

SkyPilot menjalankan workload AI di lebih dari 20 cloud, Kubernetes, dan on-prem, serta dapat menggunakan penyimpanan Hugging Face sebagai backend — sehingga satu bucket dapat dibaca dari setiap cloud tanpa salinan per-cloud. Atur store: hf pada entri file_mounts untuk memount bucket secara read-write atau repo secara read-only:

# 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

Autentikasi sekali - hf auth login (atau export HF_TOKEN=<your-token>) adalah semua yang dibutuhkan SkyPilot. Token Hugging Face lokal Anda diteruskan ke setiap cloud, sehingga mount bucket dan repo terautentikasi secara otomatis:

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

Jika kode run Anda menarik repositori bergerbang, tambahkan --secret HF_TOKEN ke perintah peluncuran untuk juga mengekspos token sebagai variabel lingkungan.

MOUNT dan MOUNT_CACHED berperilaku identik untuk hf dan menggunakan backend FUSE hf-mount, yang membutuhkan image dasar dengan glibc ≥ 2.34 dan /dev/fuse. Cloud bare-VM menyediakan keduanya. Image Kubernetes bawaan SkyPilot menyertakan glibc yang lebih lama, sehingga atur image_id yang lebih baru (mis. docker:mirror.gcr.io/ubuntu:22.04). Lihat dokumentasi penyimpanan SkyPilot untuk persyaratan lingkungan terkini.

Lihat artikel blog SkyPilot + Hugging Face tentang penyimpanan untuk benchmark dan panduan lengkap.

Operasi sistem file

Untuk operasi file langsung, huggingface_hub mengekspos objek filesystem yang sudah diinstansiasi sebelumnya, 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 dan versi selanjutnya membaca jalur hf://buckets/ secara native melalui ekstensi httpfs (dan dengan ekstensi hf untuk penulisan), baik dari CLI maupun setiap klien:

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

Lihat Query with DuckDB untuk bucket privat dan versi DuckDB yang lebih lama.

Bahasa lain

OpenDAL menyediakan antarmuka sistem berkas yang serupa untuk Rust, Java, Go, JavaScript, dan lainnya.

Segera hadir

Dukungan URL hf:// native sedang dalam pengembangan untuk lebih banyak pustaka — termasuk WebDataset. Sementara itu, semuanya sudah dapat berfungsi saat ini melalui API yang kompatibel dengan S3.