Tích hợp Bucket

Storage Buckets có thể được đọc và ghi từ nhiều thư viện dữ liệu Python bằng cách sử dụng đường dẫn hf://buckets/, được hỗ trợ bởi giao diện hệ thống tệp huggingface_hub.

Đối với các cơ chế truy cập cơ bản — mounts, volume mounts và fsspec — hãy xem Mẫu 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"])

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 Polars và 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.