Patrones de acceso

Además de la CLI y el SDK de Python, hay varias formas de acceder a los datos del bucket desde tus herramientas y flujos de trabajo existentes.

Elegir un método de acceso

Para las herramientas que usan cubos como backend (SkyPilot, Inspect, …), consulte Integraciones. Para mantener un cliente sincronizado con un cubo sin realizar sondeos, consulte Seguimiento de cambios.

Montar como un sistema de archivos local

hf-mount permite montar cubos (y repositorios) como sistemas de archivos locales mediante NFS (recomendado) o FUSE. Los archivos se obtienen de forma perezosa: solo los bytes que tu código lee pasan por la red.

Instalar con Homebrew:

brew install hf-mount

Montar un bucket:

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

Una vez montado, cualquier herramienta que lea o escriba archivos funciona con tu bucket: pandas, DuckDB, vLLM, scripts de entrenamiento, comandos de shell, etc.

Los buckets se montan en modo lectura-escritura; los repositorios son de solo lectura. Consulte el repositorio hf-mount para obtener la documentación completa, incluidas las opciones de backend, la caché y los modos de escritura.

Montajes de volúmenes en Jobs y Spaces

Las monturas de volúmenes en Jobs y Spaces son la misma idea que hf-mount, gestionadas por la plataforma para ti, sin necesidad de configuración adicional. Los buckets se montan de forma predeterminada en modo lectura y escritura.

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

Los trabajos también pueden tomar un directorio local como origen del volumen (-v ./training-data:/data): el directorio se sincroniza con su cubo privado jobs-artifacts y se monta desde allí, por lo que las re-sincronizaciones incrementales y la recuperación de la salida se realizan sin coste adicional.

Para la sintaxis completa de montaje de volúmenes y la API de Python, consulte la documentación de configuración de Jobs y la guía de montaje de volúmenes de Spaces.

Consultar con DuckDB

DuckDB 2.0 y versiones posteriores usan rutas hf://buckets/ de forma nativa a través de la extensión httpfs (lectura) o la extensión hf (lectura/escritura). Desde la CLI de DuckDB o cualquier cliente, instale y cargue httpfs y luego consulte un bucket:

INSTALL httpfs;
LOAD httpfs;

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

Los patrones glob funcionan de la misma manera que para los conjuntos de datos, por ejemplo, 'hf://buckets/username/my-bucket/data/**/*.parquet'. Los buckets no tienen versiones, por lo que la sintaxis @revision no se aplica a las rutas de bucket. httpfs solo lee; para escribir los resultados de una consulta en un bucket, cargue la extensión hf (vea más abajo).

Baldes privados: cree primero un secreto de Hugging Face. Obtiene el token de hf auth login o de la variable de entorno HF_TOKEN:

CREATE SECRET hf (TYPE huggingface, PROVIDER credential_chain);

Escribir en Hugging Face requiere la extensión 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';

En DuckDB 1.x, httpfs no reconoce las rutas hf://buckets/. En su lugar, registre HfFileSystem desde Python, o use la API compatible con S3 desde la CLI y otros clientes.

Herramientas de datos de Python

El HfFileSystem proporciona acceso compatible con fsspec a los buckets mediante rutas hf://buckets/. Cualquier biblioteca de Python que admita fsspec puede leer y escribir datos de buckets directamente.

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 más información sobre las rutas hf:// y las operaciones admitidas, consulte la guía de HfFileSystem y la guía de Python de Buckets.