Pola Akses

Selain CLI dan SDK Python, ada beberapa cara untuk mengakses data bucket dari alat dan alur kerja yang sudah ada.

Memilih Metode Akses

Untuk alat yang menggunakan bucket sebagai backend (SkyPilot, Inspect, …), lihat Integrasi. Untuk menjaga sinkronisasi klien dengan bucket tanpa melakukan polling, lihat Melacak Perubahan.

Mount sebagai Filesystem Lokal

hf-mount memungkinkan Anda memetakan bucket (dan repositori) sebagai sistem file lokal melalui NFS (disarankan) atau FUSE. File diambil secara malas — hanya byte yang dibaca oleh kode Anda yang melewati jaringan.

Instal dengan Homebrew:

brew install hf-mount

Mount sebuah bucket:

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

Setelah dimount, semua alat yang membaca atau menulis file dapat bekerja dengan bucket Anda — pandas, DuckDB, vLLM, skrip pelatihan, perintah shell, dll.

Buckets dipasang dengan mode baca-tulis; repositori bersifat hanya-baca. Lihat repositori hf-mount untuk dokumentasi lengkap termasuk opsi backend, caching, dan mode tulis.

Volume Mounts di Jobs dan Spaces

Volume mounts di Jobs dan Spaces memiliki konsep yang sama dengan hf-mount, dikelola oleh platform untuk Anda — tidak perlu pengaturan tambahan. Bucket dipasang secara read-write secara default.

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

Jobs juga dapat mengambil direktori lokal sebagai sumber volume (-v ./training-data:/data): direktori tersebut disinkronkan ke bucket jobs-artifacts privat Anda dan dimuat dari sana, sehingga re-sinkronisasi inkremental dan penarikan output menjadi gratis.

Untuk sintaks mount volume lengkap dan API Python, lihat dokumen konfigurasi Jobs dan panduan mount volume Spaces.

Query dengan DuckDB

DuckDB 2.0 dan versi selanjutnya menggunakan jalur hf://buckets/ secara native melalui ekstensi httpfs (baca) atau ekstensi hf (baca/tulis). Dari CLI DuckDB atau klien apa pun, instal dan muat httpfs, lalu kueri sebuah bucket:

INSTALL httpfs;
LOAD httpfs;

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

Glob patterns bekerja seperti yang dilakukan untuk dataset, misalnya 'hf://buckets/username/my-bucket/data/**/*.parquet'. Buckets tidak memiliki versi, sehingga sintaks @revision tidak berlaku untuk path bucket. httpfs hanya membaca; untuk menulis hasil query ke bucket, muat ekstensi hf (lihat di bawah).

Bucket privat: buat rahasia Hugging Face terlebih dahulu. Token diambil dari hf auth login atau variabel lingkungan HF_TOKEN:

CREATE SECRET hf (TYPE huggingface, PROVIDER credential_chain);

Menulis ke Hugging Face memerlukan ekstensi 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';

Pada DuckDB 1.x, httpfs tidak mengenali path hf://buckets/. Daftarkan HfFileSystem dari Python sebagai gantinya, atau gunakan API yang kompatibel dengan S3 dari CLI dan klien lainnya.

Alat Data Python

HfFileSystem menyediakan akses yang kompatibel dengan fsspec ke bucket menggunakan path hf://buckets/. Setiap pustaka Python yang mendukung fsspec dapat membaca dan menulis data bucket secara langsung.

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

Untuk informasi lebih lanjut tentang jalur hf:// dan operasi yang didukung, lihat panduan HfFileSystem dan panduan Python Buckets.