Tích hợp Bucket

Hầu hết các công cụ đã có thể sử dụng một bucket, theo một trong hai cách:

• Các thư viện Python được xây dựng trên fsspec (pandas, Dask, PyArrow và các thư viện khác) đọc và ghi các đường dẫn hf://buckets/ thông qua giao diện hệ thống tệp huggingface_hub.
• Các công cụ giao tiếp với S3 (boto3, AWS CLI, rclone, DVC và các công cụ khác) hoạt động dựa trên API tương thích S3.

Trang này bao gồm các thư viện có hỗ trợ bucket tích hợp, cùng với các ví dụ cho các thư viện dữ liệu phổ biến. Đối với mounts và volume mounts, hãy xem Mô hình truy cập.

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 đọc và ghi một cách lười biếng, mỗi phân vùng tương ứng với một tệp, vì vậy bạn có thể xử lý các bộ dữ liệu lớn hơn bộ nhớ trực tiếp từ một 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/")

Xem Dask trên Hub để biết thêm.

Daft

Daft hỗ trợ các đường dẫn hf://buckets/ một cách bản địa, với đọc được tăng tốc bởi Xet được bật theo mặc định:

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

Với pyspark_huggingface đã được cài đặt:

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

Xem thêm tại PySpark trên Hub.

🤗 Datasets

from datasets import load_dataset

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

datatrove

datatrove readers và writers chấp nhận các đường dẫn hf://buckets/. HuggingFaceBucketWriter tải các kết quả đầu ra lớn lên bằng 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")

Xem README của datatrove để biết thêm.

LeRobot

LeRobot có thể phát trực tiếp bộ dữ liệu huấn luyện từ một bucket. Bucket phải chứa toàn bộ bộ dữ liệu (meta/, các tệp Parquet và tệp video) ở gốc:

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

Diffusers

diffusers-cli run tải các kết quả đầu ra lên một bucket bằng --push-to. Bucket sẽ được tạo nếu nó chưa tồn tại:

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

Xem hướng dẫn CLI của Diffusers để biết thêm.

Trackio

Khi Trackio ghi log vào một Space, nó lưu trữ dữ liệu chạy trong một bucket được tạo từ ID của Space. Truyền bucket_id vào trackio.init() để sử dụng bucket do bạn chọn.

Kiểm tra AI

Inspect AI có thể ghi nhật ký đánh giá trực tiếp vào một bucket — chỉ định thư mục log của nó đến đường dẫn hf://buckets/ (yêu cầu huggingface_hub>=1.6.0). Hãy tạo bucket và xác thực trước (Inspect sẽ không tự động tạo bucket cho bạn):

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

Xem hướng dẫn nhật ký eval của Inspect để biết thêm chi tiết.

SkyPilot

SkyPilot chạy các tác vụ AI trên hơn 20 cloud, Kubernetes và on-prem, đồng thời có thể sử dụng lưu trữ Hugging Face làm backend — nhờ đó một bucket có thể được đọc từ mọi cloud mà không cần sao chép riêng cho từng cloud. Đặt store: hf trong một mục file_mounts để gắn bucket ở chế độ đọc-ghi hoặc repo ở chế độ chỉ đọc:

# 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

Xác thực một lần - hf auth login (hoặc export HF_TOKEN=<your-token>) là tất cả những gì SkyPilot cần. Nó chuyển tiếp token Hugging Face cục bộ của bạn đến mọi cloud, nhờ đó việc gắn bucket và repo được xác thực tự động:

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

Nếu mã run của bạn kéo các kho có kiểm soát truy cập, hãy thêm --secret HF_TOKEN vào lệnh khởi chạy để cũng công khai token dưới dạng biến môi trường.

MOUNT và MOUNT_CACHED hoạt động giống hệt nhau với hf và sử dụng backend FUSE hf-mount, đòi hỏi một base image có glibc ≥ 2.34 và /dev/fuse. Các cloud dạng bare-VM cung cấp cả hai. Ảnh Kubernetes mặc định của SkyPilot đi kèm glibc cũ hơn, vì vậy hãy đặt một image_id mới hơn (ví dụ docker:mirror.gcr.io/ubuntu:22.04). Xem tài liệu lưu trữ của SkyPilot để biết các yêu cầu môi trường hiện tại.

Xem bài đăng blog về lưu trữ SkyPilot + Hugging Face để biết thêm về các bài kiểm tra hiệu năng và hướng dẫn chi tiết.

Thao tác hệ thống tệp

Đối với các thao tác tệp trực tiếp, huggingface_hub cung cấp một đối tượng hệ thống tệp đã được khởi tạo sẵn, 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 trở lên đọc các đường dẫn hf://buckets/ một cách bản địa thông qua tiện ích mở rộng httpfs (và với tiện ích mở rộng hf để ghi), từ CLI và mọi client:

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

Xem Truy vấn bằng DuckDB cho các bucket riêng tư và các phiên bản DuckDB cũ hơn.

Các ngôn ngữ khác

OpenDAL cung cấp giao diện hệ thống tệp tương tự cho Rust, Java, Go, JavaScript và nhiều ngôn ngữ khác.

Sắp ra mắt

Hỗ trợ URL hf:// bản địa đang được triển khai cho nhiều thư viện hơn — bao gồm cả WebDataset. Trong thời gian chờ đợi, tất cả những thư viện này hiện đã hoạt động thông qua API tương thích S3.