Padrões de Acesso

Além da CLI e do SDK em Python, existem várias maneiras de acessar os dados do bucket a partir das suas ferramentas e fluxos de trabalho existentes.

Escolhendo um método de acesso

Para ferramentas que usam buckets como backend (SkyPilot, Inspect, …), consulte Integrações. Para manter um cliente sincronizado com um bucket sem fazer polling, consulte Acompanhamento de Alterações.

Montar como um sistema de arquivos local

hf-mount permite montar buckets (e repositórios) como sistemas de arquivos locais via NFS (recomendado) ou FUSE. Os arquivos são obtidos de forma preguiçosa — apenas os bytes que seu código lê acessam a rede.

Instale com o Homebrew:

brew install hf-mount

Monte um bucket:

hf-mount start bucket username/my-bucket /mnt/data

Uma vez montado, qualquer ferramenta que leia ou escreva arquivos funciona com seu bucket — pandas, DuckDB, vLLM, scripts de treinamento, comandos de shell, etc.

Os buckets são montados com leitura e escrita; os repositórios são somente leitura. Consulte o repositório hf-mount para a documentação completa, incluindo opções de backend, cache e modos de escrita.

Montagens de volume em Jobs e Spaces

As montagens de volume em Jobs e Spaces seguem a mesma ideia do hf-mount, gerenciadas para você pela plataforma — sem necessidade de configuração adicional. Os buckets são montados com leitura e escrita por padrão.

hf jobs run -v hf://buckets/username/my-bucket:/data python:3.12 python script.py

Os jobs também podem receber um diretório local como origem do volume (-v ./training-data:/data): o diretório é sincronizado com seu bucket privado jobs-artifacts e montado a partir dele, de modo que as ressincronizações incrementais e a recuperação da saída são feitas automaticamente.

Para a sintaxe completa de montagem de volume e a API em Python, consulte a documentação de configuração de Jobs e o guia de montagem de volume do Spaces.

Consultar com DuckDB

DuckDB 2.0 e versões posteriores usam caminhos hf://buckets/ nativamente por meio da extensão httpfs (leitura) ou da extensão hf (leitura/escrita). A partir da CLI do DuckDB ou de qualquer cliente, instale e carregue o httpfs e, em seguida, consulte um bucket:

INSTALL httpfs;
LOAD httpfs;

SELECT * FROM 'hf://buckets/username/my-bucket/data.parquet' LIMIT 10;

Os padrões glob funcionam da mesma forma que para conjuntos de dados, por exemplo, 'hf://buckets/username/my-bucket/data/**/*.parquet'. Os buckets não são versionados, portanto, a sintaxe @revision não se aplica a caminhos de bucket. O httpfs apenas lê; para gravar resultados de consulta em um bucket, carregue a extensão hf (veja abaixo).

Buckets privados: crie primeiro um segredo do Hugging Face. Ele obtém o token do hf auth login ou da variável de ambiente HF_TOKEN:

CREATE SECRET hf (TYPE huggingface, PROVIDER credential_chain);

Escrever no Hugging Face requer a extensão hf:

SET allow_extension_repositories = 'allowed';
CREATE OR REPLACE EXTENSION REPOSITORY hf_repo WITH PREFIX 'https://hf.co/buckets/duckdb-extensions/builds/resolve';
INSTALL hf FROM hf_repo;
LOAD hf FROM hf_repo;

COPY tbl TO 'hf://buckets/username/my-bucket/out.parquet';

No DuckDB 1.x, o httpfs não reconhece caminhos hf://buckets/. Registre o HfFileSystem a partir do Python, ou use a API compatível com S3 a partir da CLI e de outros clientes.

Ferramentas de Dados em Python

O HfFileSystem fornece acesso compatível com fsspec a buckets usando caminhos hf://buckets/. Qualquer biblioteca Python que suporte fsspec pode ler e gravar dados de buckets diretamente.

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

Para mais informações sobre os caminhos hf:// e as operações suportadas, consulte o guia do HfFileSystem e o guia do Python para Buckets.