Integrações de Bucket

Os Storage Buckets podem ser lidos e gravados por muitas bibliotecas de dados em Python usando caminhos hf://buckets/, com base na interface de sistema de arquivos huggingface_hub.

Para os mecanismos de acesso subjacentes — montagens, montagens de volume e fsspec — 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"])

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 Polars e WebDataset. Enquanto isso, todas essas já funcionam hoje por meio da API compatível com S3.