Modèles d'accès

En plus de la CLI et du SDK Python, il existe plusieurs façons d'accéder aux données du bucket depuis vos outils et flux de travail existants.

Choisir une méthode d'accès

Pour les outils qui utilisent des buckets comme backend (SkyPilot, Inspect, …), voir Intégrations. Pour maintenir un client synchronisé avec un bucket sans le sonder, voir Suivi des modifications.

Monter en tant que système de fichiers local

hf-mount permet de monter des buckets (et des dépôts) comme des systèmes de fichiers locaux via NFS (recommandé) ou FUSE. Les fichiers sont récupérés de manière paresseuse — seules les octets lus par votre code passent par le réseau.

Installer avec Homebrew :

brew install hf-mount

Monter un bucket :

hf-mount start bucket username/my-bucket /mnt/data

Une fois monté, tout outil qui lit ou écrit des fichiers fonctionne avec votre bucket — pandas, DuckDB, vLLM, scripts d’entraînement, commandes shell, etc.

Les buckets sont montés en lecture-écriture ; les dépôts sont en lecture seule. Consultez le dépôt hf-mount pour la documentation complète, y compris les options de backend, la mise en cache et les modes d'écriture.

Volumes montés dans les Jobs et les Spaces

Les montages de volumes dans Jobs et Spaces reposent sur le même principe que hf-mount, géré pour vous par la plateforme — aucune configuration supplémentaire n'est requise. Les buckets sont montés en lecture-écriture par défaut.

hf jobs run -v hf://buckets/username/my-bucket:/data python:3.12 python script.py

Les jobs peuvent également prendre un dossier local comme source de volume (-v ./training-data:/data) : le dossier est synchronisé vers votre bucket privé jobs-artifacts et monté depuis celui-ci, ce qui permet des re-synchronisations incrémentielles et un rapatriement des sorties sans effort supplémentaire.

Pour la syntaxe complète de montage de volume et l’API Python, consultez la documentation sur la configuration des Jobs et le guide de montage de volume pour Spaces.

Interroger avec DuckDB

DuckDB 2.0 et les versions ultérieures utilisent les chemins hf://buckets/ de manière native via l’extension httpfs (lecture) ou l’extension hf (lecture/écriture). Depuis l’interface en ligne de commande DuckDB ou tout client, installez et chargez httpfs, puis interrogez un bucket :

INSTALL httpfs;
LOAD httpfs;

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

Les motifs glob fonctionnent comme pour les jeux de données, par exemple 'hf://buckets/username/my-bucket/data/**/*.parquet'. Les buckets ne sont pas versionnés, la syntaxe @revision ne s'applique donc pas aux chemins de bucket. httpfs ne fait que lire ; pour écrire les résultats de requête dans un bucket, chargez l'extension hf (voir ci-dessous).

Buckets privés : créez d’abord un secret Hugging Face. Il récupère le jeton depuis hf auth login ou la variable d’environnement HF_TOKEN :

CREATE SECRET hf (TYPE huggingface, PROVIDER credential_chain);

L'écriture sur Hugging Face nécessite l'extension hf :

SET allow_extension_repositories = 'allowed';
CREATE OR REPLACE EXTENSION REPOSITORY hf_repo WITH PREFIX 'https://hf.co/buckets/duckdb-extensions/builds/resolve';
INSTALL hf FROM hf_repo;
LOAD hf FROM hf_repo;

COPY tbl TO 'hf://buckets/username/my-bucket/out.parquet';

Sur DuckDB 1.x, httpfs ne reconnaît pas les chemins hf://buckets/. Enregistrez plutôt HfFileSystem depuis Python, ou utilisez l'API compatible S3 depuis l'interface en ligne de commande et d'autres clients.

Outils de données Python

Le HfFileSystem fournit un accès compatible fsspec aux buckets en utilisant des chemins hf://buckets/. Toute bibliothèque Python prenant en charge fsspec peut lire et écrire directement les données des buckets.

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

Pour en savoir plus sur les chemins hf:// et les opérations prises en charge, consultez le guide HfFileSystem et le guide Python Buckets.