# Modèles d'accès

En plus de la [CLI et du SDK Python](./storage-buckets#managing-files), 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

| Méthode | Idéal pour | Détails |
|--------|----------|---------|
| **hf-mount** | Monter en tant que système de fichiers local — tout outil fonctionne | [Voir ci-dessous](#mount-as-a-local-filesystem) |
| **Montages de volumes** | HF Jobs & Spaces (même idée, gérés pour vous) | [Voir ci-dessous](#volume-mounts-in-jobs-and-spaces) |
| **DuckDB** | Requêtes SQL sur les fichiers de bucket, depuis l’interface en ligne de commande ou n’importe quel client | [Voir ci-dessous](#query-with-duckdb) |
| **chemins hf://** (fsspec) | Outils de données Python (pandas et autres bibliothèques compatibles fsspec) | [Voir ci-dessous](#python-data-tools) |
| **Synchronisation CLI** | Transferts par lots, sauvegardes | [Synchroniser la documentation](./storage-buckets#syncing-directories) |
| **API S3** | Outils S3 existants (AWS CLI, boto3, s5cmd) | [API compatible avec S3](./storage-buckets-s3) |

Pour les outils qui utilisent des buckets comme backend (SkyPilot, Inspect, Trackio, …), voir [Intégrations](./storage-buckets-integrations). Pour maintenir un client synchronisé avec un bucket sans le sonder, voir [Suivi des modifications](./storage-buckets#tracking-changes).

## Monter en tant que système de fichiers local

[hf-mount](https://github.com/huggingface/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](https://brew.sh/) :

```bash
brew install hf-mount
```

Monter un bucket :

```bash
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.

> [!TIP]
> Les buckets sont montés en lecture-écriture ; les dépôts sont en lecture seule. Consultez le [dépôt hf-mount](https://github.com/huggingface/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](./jobs) et [Spaces](./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.

```bash
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](./jobs-configuration#volumes) et le [guide de montage de volume pour Spaces](/docs/huggingface_hub/guides/manage-spaces#mount-volumes-in-your-space).

## Interroger avec DuckDB

[DuckDB](https://duckdb.org/) 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 :

```sql
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` :

```sql
CREATE SECRET hf (TYPE huggingface, PROVIDER credential_chain);
```

L'écriture sur Hugging Face nécessite l'[extension](https://huggingface.co/duckdb-extensions) `hf` :

```sql
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';
```

> [!NOTE]
> Sur DuckDB 1.x, `httpfs` ne reconnaît pas les chemins `hf://buckets/`. Enregistrez plutôt [`HfFileSystem`](/docs/huggingface_hub/guides/hf_file_system) depuis Python, ou utilisez l'[API compatible S3](./storage-buckets-s3#query-a-bucket-with-duckdb) depuis l'interface en ligne de commande et d'autres clients.

## Outils de données Python

Le [`HfFileSystem`](/docs/huggingface_hub/guides/hf_file_system) fournit un accès compatible [fsspec](https://filesystem-spec.readthedocs.io) 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 :**

```python
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`](/docs/huggingface_hub/guides/hf_file_system) et le [guide Python Buckets](/docs/huggingface_hub/guides/buckets).