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.
• Ferramentas que se comunicam com o S3 (boto3, AWS CLI, rclone, DVC e outras) operam contra a API compatível com 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.

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

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:

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 para mais informações.

Daft

O Daft suporta nativamente caminhos hf://buckets/, com leituras aceleradas por Xet habilitadas por padrão:

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

Com o pyspark_huggingface instalado:

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

Veja PySpark no Hub para mais informações.

🤗 Datasets

from datasets import load_dataset

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

datatrove

Os leitores e escritores do datatrove aceitam caminhos hf://buckets/. O HuggingFaceBucketWriter faz upload de grandes saídas com 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")

Veja o README do datatrove para mais informações.

LeRobot

LeRobot 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:

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:

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 para mais informações.

Trackio

Quando o 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 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ê):

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 para mais detalhes.

SkyPilot

SkyPilot 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:

# 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:

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.

MOUNT e MOUNT_CACHED se comportam de forma idêntica para hf e usam o backend FUSE 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 para os requisitos de ambiente atuais.

Veja o post no blog sobre armazenamento SkyPilot + Hugging Face 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 pré-instantiado, 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

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:

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 para buckets privados e versões mais antigas do DuckDB.

Outros idiomas

OpenDAL 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.