Intégrations de buckets

La plupart des outils peuvent déjà utiliser un seau, de l'une des deux manières suivantes :

• Les bibliothèques Python construites sur fsspec (pandas, Dask, PyArrow et autres) lisent et écrivent les chemins hf://buckets/ via l’interface système de fichiers huggingface_hub.
• Les outils qui communiquent avec S3 (boto3, l’AWS CLI, rclone, DVC et d’autres) fonctionnent avec l’API compatible S3.

Cette page présente les bibliothèques avec prise en charge intégrée des buckets, ainsi que des exemples pour les bibliothèques de données courantes. Pour les montages et les montages de volumes, consultez Modèles d'accès.

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 lit et écrit de manière paresseuse, une partition par fichier, ce qui vous permet de traiter des jeux de données plus volumineux que la mémoire directement depuis un 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/")

Voir Dask sur le Hub pour en savoir plus.

Daft

Daft prend en charge les chemins hf://buckets/ de manière native, avec des lectures accélérées par Xet activées par défaut :

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

Avec pyspark_huggingface installé :

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

Voir PySpark sur le Hub pour en savoir plus.

🤗 Datasets

from datasets import load_dataset

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

datatrove

Les lecteurs et écrivains datatrove acceptent les chemins hf://buckets/. HuggingFaceBucketWriter téléverse les grandes sorties avec 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")

Voir le README de datatrove pour plus de détails.

LeRobot

LeRobot peut diffuser un jeu de données d’entraînement depuis un bucket. Le bucket doit contenir l’intégralité du jeu de données (meta/, fichiers Parquet et vidéos) à sa racine :

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

Diffusers

diffusers-cli run téléverse ses sorties vers un bucket avec --push-to. Le bucket est créé s’il n’existe pas :

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

Voir le guide de l’interface en ligne de commande de Diffusers pour en savoir plus.

Trackio

Lorsque Trackio enregistre des données dans un Space, il stocke les données d’exécution dans un bucket créé à partir de l’ID du Space. Passez bucket_id à trackio.init() pour utiliser un bucket de votre choix.

Inspect AI

Inspect AI peut écrire des journaux d’évaluation directement dans un bucket — il suffit de définir son répertoire de journaux sur un chemin hf://buckets/ (nécessite huggingface_hub>=1.6.0). Créez d’abord le bucket et authentifiez-vous (Inspect ne le créera pas à votre place) :

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

Consultez le guide des journaux d’évaluation d’Inspect pour plus de détails.

SkyPilot

SkyPilot exécute des charges de travail IA sur plus de 20 clouds, Kubernetes et en local, et peut utiliser le stockage Hugging Face comme backend — un seul bucket est donc lisible depuis tous les clouds sans copies par cloud. Définissez store: hf sur une entrée file_mounts pour monter un bucket en lecture-écriture ou un dépôt en lecture seule :

# 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

Authentifiez-vous une seule fois - hf auth login (ou export HF_TOKEN=<your-token>) est tout ce dont SkyPilot a besoin. Il transmet votre jeton Hugging Face local à chaque cloud, de sorte que les montages de bucket et de dépôt s’authentifient automatiquement :

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

Si votre propre code run récupère des dépôts sous licence, ajoutez --secret HF_TOKEN à la commande de lancement pour exposer également le jeton en tant que variable d’environnement.

MOUNT et MOUNT_CACHED se comportent de manière identique pour hf et utilisent le backend FUSE hf-mount, qui nécessite une image de base avec glibc ≥ 2.34 et /dev/fuse. Les clouds de VM nues fournissent les deux. L’image Kubernetes par défaut de SkyPilot embarque une version plus ancienne de glibc, il faut donc définir un image_id plus récent (par ex. docker:mirror.gcr.io/ubuntu:22.04). Consultez la documentation de stockage SkyPilot pour les exigences environnementales actuelles.

Consultez le article de blog SkyPilot + Hugging Face sur le stockage pour les benchmarks et un guide complet.

Opérations sur le système de fichiers

Pour les opérations de fichiers directes, huggingface_hub expose un objet système de fichiers pré-instantié, 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 et les versions ultérieures lisent les chemins hf://buckets/ nativement via l’extension httpfs (et avec l’extension hf pour l’écriture), depuis l’interface en ligne de commande et tous les clients :

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

Voir Query with DuckDB pour les buckets privés et les anciennes versions de DuckDB.

Autres langues

OpenDAL fournit une interface système de fichiers similaire pour Rust, Java, Go, JavaScript et d’autres.

Bientôt disponible

La prise en charge native des URL hf:// est en cours de développement pour d'autres bibliothèques, y compris WebDataset. En attendant, toutes ces bibliothèques fonctionnent déjà aujourd'hui via l'API compatible S3.