# Integrações de Bucket

A maioria das ferramentas já pode usar um bucket, de uma das duas seguintes maneiras:

- **Bibliotecas Python construídas sobre o fsspec** (pandas, Dask, PyArrow, entre outras) leem e gravam caminhos `hf://buckets/` por meio da interface de sistema de arquivos do [`huggingface_hub`](/docs/huggingface_hub/guides/hf_file_system).
- **Ferramentas que se comunicam com o S3** (boto3, AWS CLI, rclone, DVC e outras) operam contra a [API compatível com S3](./storage-buckets-s3).

Esta página aborda bibliotecas com suporte nativo a buckets, além de exemplos para bibliotecas comuns de dados. Para mounts e volume mounts, consulte [Padrões de acesso](./storage-buckets-access).

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

## Dask

O Dask lê e grava de forma preguiçosa, uma partição por arquivo, permitindo processar conjuntos de dados maiores que a memória diretamente de um bucket:

```python
import dask.dataframe as dd

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

Veja [Dask no Hub](./datasets-dask) para mais informações.

## Daft

O Daft suporta nativamente caminhos `hf://buckets/`, com leituras aceleradas por [Xet](https://docs.daft.ai/en/stable/connectors/huggingface/) habilitadas por padrão:

```python
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

```python
import pyarrow.parquet as pq

table = pq.read_table("hf://buckets/username/my-bucket/data.parquet")
```

## PySpark

Com o [`pyspark_huggingface`](https://github.com/huggingface/pyspark_huggingface) instalado:

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

Veja [PySpark no Hub](./datasets-spark) para mais informações.

## 🤗 Datasets

```python
from datasets import load_dataset

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

## datatrove

Os leitores e escritores do [datatrove](https://github.com/huggingface/datatrove) aceitam caminhos `hf://buckets/`. O `HuggingFaceBucketWriter` faz upload de grandes saídas com Xet:

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

Veja o [README do datatrove](https://github.com/huggingface/datatrove#hf-storage-buckets) para mais informações.

## LeRobot

[LeRobot](https://huggingface.co/docs/lerobot/main/en/training_dataset_streaming) pode transmitir um conjunto de dados de treinamento de um bucket. O bucket deve conter o conjunto de dados completo (`meta/`, arquivos Parquet e de vídeo) na raiz:

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

## Diffusers

`diffusers-cli run` envia suas saídas para um bucket com `--push-to`. O bucket é criado caso não exista:

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

Veja o [guia da CLI do Diffusers](https://huggingface.co/docs/diffusers/using-diffusers/cli) para mais informações.

## Trackio

Quando o [Trackio](https://huggingface.co/docs/trackio) registra em um Space, ele armazena os dados de execução em um bucket criado a partir do ID do Space. Passe `bucket_id` para `trackio.init()` para usar um bucket de sua escolha.

## Inspect AI

[Inspect AI](https://inspect.aisi.org.uk/) pode gravar logs de avaliação diretamente em um bucket — aponte o diretório de logs para um caminho `hf://buckets/` (requer `huggingface_hub>=1.6.0`). Crie o bucket e autentique-se primeiro (o Inspect não o criará por você):

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

Veja o [guia de logs de avaliação do Inspect](https://inspect.aisi.org.uk/eval-logs.html#sec-hugging-face-storage-buckets) para mais detalhes.

## SkyPilot

[SkyPilot](https://docs.skypilot.co/) executa cargas de trabalho de IA em mais de 20 nuvens, Kubernetes e ambientes on-prem, e pode usar o armazenamento do Hugging Face como backend — assim, um bucket é legível de qualquer nuvem sem cópias por nuvem. Defina `store: hf` em uma entrada de `file_mounts` para montar um bucket com leitura e escrita ou um repositório somente leitura:

```yaml
# 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
```

Autentique uma vez - `hf auth login` (ou `export HF_TOKEN=<your-token>`) é tudo o que o SkyPilot precisa. Ele encaminha seu token local do Hugging Face para cada nuvem, de modo que os montes de bucket e repositório se autenticam automaticamente:

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

Se o seu próprio código de `run` acessar repositórios com controle de acesso, adicione `--secret HF_TOKEN` ao comando de inicialização para também expor o token como uma variável de ambiente.

> [!TIP]
> `MOUNT` e `MOUNT_CACHED` se comportam de forma idêntica para `hf` e usam o backend FUSE [hf-mount](https://github.com/huggingface/hf-mount), que requer uma imagem base com glibc ≥ 2.34 e `/dev/fuse`. Nuvens de VMs puras fornecem ambos. A imagem Kubernetes padrão do SkyPilot inclui uma versão mais antiga do glibc, portanto, defina um `image_id` mais recente (por exemplo, `docker:mirror.gcr.io/ubuntu:22.04`). Consulte a [documentação de armazenamento do SkyPilot](https://docs.skypilot.co/en/latest/reference/storage.html) para os requisitos de ambiente atuais.

Veja o [post no blog sobre armazenamento SkyPilot + Hugging Face](https://huggingface.co/blog/skypilot-hf-storage) para benchmarks e um guia completo.

## Operações de sistema de arquivos

Para operações de arquivo diretas, o `huggingface_hub` expõe um [objeto de sistema de arquivos](/docs/huggingface_hub/guides/hf_file_system) pré-instantiado, `hffs`:

```python
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

O DuckDB 2.0 e versões posteriores leem caminhos `hf://buckets/` nativamente por meio da extensão `httpfs` (e com a extensão `hf` para escrita), a partir da CLI e de todos os clientes:

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

Veja [Query with DuckDB](./storage-buckets-access#query-with-duckdb) para buckets privados e versões mais antigas do DuckDB.

## Outros idiomas

[OpenDAL](https://opendal.apache.org/) fornece uma interface de sistema de arquivos semelhante para Rust, Java, Go, JavaScript e outros.

## Em breve

O suporte nativo a URLs `hf://` está a caminho para mais bibliotecas — incluindo WebDataset. Enquanto isso, todas essas já funcionam hoje por meio da [API compatível com S3](./storage-buckets-s3).