Hub documentation

Integrações de Bucket

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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.

OpenRouter

OpenRouter Broadcast pode enviar rastros das solicitações que você roteia pelo OpenRouter para um bucket, cada um salvo como um arquivo JSON separado, usando credenciais S3. Os rastros contêm prompts completos e saída de ferramentas, então use um bucket privado. Consulte OpenRouter Broadcast traces para ver como o Hub os exibe.

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.

Update on GitHub