Hub documentation
Integrações de Bucket
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 dohuggingface_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=actDiffusers
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/outputsVeja 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 viewVeja 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 /checkpointsAutentique 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.yamlSe 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.
MOUNTeMOUNT_CACHEDse comportam de forma idêntica parahfe 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 umimage_idmais 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.