Bucket Entegrasyonları

Çoğu araç, bir kovayı şu iki yoldan biriyle kullanabilir:

• fsspec üzerine kurulu Python kütüphaneleri (pandas, Dask, PyArrow ve diğerleri), hf://buckets/ yollarını huggingface_hub dosya sistemi arayüzü üzerinden okur ve yazar.
• S3 ile iletişim kuran araçlar (boto3, AWS CLI, rclone, DVC ve diğerleri) S3 uyumlu API üzerinde çalışır.

Bu sayfa, yerleşik sepet (bucket) desteğine sahip kütüphaneleri ve yaygın veri kütüphaneleri için örnekleri kapsar. Bağlamalar (mounts) ve hacim bağlamaları (volume mounts) için bkz. Erişim Desenleri.

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, tembel (lazy) okuma ve yazma yapar; dosya başına bir bölüm (partition) işler, böylece bellekten büyük veri setlerini doğrudan bir depodan (bucket) işleyebilirsiniz:

import dask.dataframe as dd

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

Daha fazlası için Hub'daki Dask sayfasına bakın.

Daft

Daft, hf://buckets/ yollarını yerel olarak destekler ve Xet hızlandırmalı okumalar varsayılan olarak etkinleştirilir:

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 yüklü olduğunda:

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

Daha fazlası için Hub'daki PySpark sayfasına bakın.

🤗 Datasets

from datasets import load_dataset

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

datatrove

datatrove okuyucuları ve yazıcıları hf://buckets/ yollarını kabul eder. HuggingFaceBucketWriter, büyük çıktıları Xet ile yükler:

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")

Daha fazla bilgi için datatrove README'sine bakın.

LeRobot

LeRobot, bir depodan eğitim veri setini akış olarak alabilir. Depo, kök dizininde tam veri setini (meta/, Parquet ve video dosyaları) içermelidir:

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

Diffusers

diffusers-cli run, çıktıları --push-to ile bir kovaya yükler. Kovak var değilse oluşturulur:

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

Daha fazla bilgi için Diffusers CLI kılavuzuna bakın.

Trackio

Trackio bir Space'e kayıt yaptığında, çalıştırma verilerini Space kimliğinden oluşturulan bir kovada saklar. Kendi seçtiğiniz kovayı kullanmak için bucket_id değerini trackio.init() fonksiyonuna iletin.

Inspect AI

Inspect AI, değerlendirme günlüklerini doğrudan bir kovaya yazabilir — günlük dizinini bir hf://buckets/ yoluna yönlendirin (huggingface_hub>=1.6.0 gerektirir). Kovayı oluşturun ve önce kimlik doğrulamasını yapın (Inspect bunu sizin yerinize yapmaz):

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

Detaylar için Inspect'in eval günlükleri kılavuzuna bakın.

SkyPilot

SkyPilot, 20'den fazla bulut, Kubernetes ve yerinde (on-prem) ortamlarda yapay zeka iş yüklerini çalıştırır ve Hugging Face depolamayı bir arka uç olarak kullanabilir; böylece tek bir bucket, bulut başına kopya oluşturulmadan her buluttan okunabilir. Bir file_mounts girdisinde store: hf ayarlayarak bir bucket'ı okuma-yazma veya bir repoyu salt okunur olarak bağlayabilirsiniz:

# 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

Bir kez kimlik doğrulaması yapın - hf auth login (veya export HF_TOKEN=<your-token>) SkyPilot için yeterlidir. Yerel Hugging Face token'ınızı her buluta iletir, böylece bucket ve repo bağlamaları otomatik olarak kimlik doğrulaması yapar:

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

Kendi run kodunuz kapalı depoları çekiyorsa, token'ı bir ortam değişkeni olarak da açığa çıkarmak için başlatma komutuna --secret HF_TOKEN ekleyin.

MOUNT ve MOUNT_CACHED, hf için aynı şekilde davranır ve glibc ≥ 2.34 ile /dev/fuse gerektiren hf-mount FUSE arka ucunu kullanır. Sadece sanal makine bulutları her ikisini de sağlar. SkyPilot’ın varsayılan Kubernetes görüntüsü daha eski bir glibc ile gelir, bu nedenle daha yeni bir image_id ayarlayın (ör. docker:mirror.gcr.io/ubuntu:22.04). Güncel ortam gereksinimleri için SkyPilot depolama belgelerine bakın.

Benchmarks ve tam bir uygulama rehberi için SkyPilot + Hugging Face depolama blog yazısını inceleyin.

Dosya sistemi işlemleri

Doğrudan dosya işlemleri için huggingface_hub, önceden örneklenmiş bir dosya sistemi nesnesi olan hffs’i sunar:

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 ve sonraki sürümler, httpfs eklentisi (ve yazma için hf eklentisi) aracılığıyla hf://buckets/ yollarını CLI ve tüm istemcilerden yerel olarak okur:

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

Özel depolar ve eski DuckDB sürümleri için DuckDB ile Sorgu bölümüne bakın.

Diğer diller

OpenDAL, Rust, Java, Go, JavaScript ve daha fazlası için benzer bir dosya sistemi arayüzü sağlar.

Yakında

Daha fazla kütüphane için yerel hf:// URL desteği yolda — WebDataset dahil. Bu arada, tüm bunlar bugün zaten S3-uyumlu API üzerinden çalışıyor.