Các mẫu truy cập

Ngoài CLI và Python SDK, có một số cách để truy cập dữ liệu bucket từ các công cụ và quy trình làm việc hiện có của bạn.

Chọn phương pháp truy cập

Đối với các công cụ sử dụng bucket làm backend (SkyPilot, Inspect, …), xem Tích hợp. Để đồng bộ hóa một client với bucket mà không cần polling, xem Theo dõi các thay đổi.

Gắn như một Hệ thống tệp cục bộ

hf-mount cho phép bạn gắn các bucket (và repo) dưới dạng hệ thống tệp cục bộ qua NFS (khuyến nghị) hoặc FUSE. Các tệp được tải theo kiểu lười — chỉ những byte mà mã của bạn đọc mới đi qua mạng.

Cài đặt bằng Homebrew:

brew install hf-mount

Gắn một bucket:

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

Sau khi được gắn, bất kỳ công cụ nào đọc hoặc ghi tệp đều hoạt động với bucket của bạn — pandas, DuckDB, vLLM, các script huấn luyện, lệnh shell, v.v.

Buckets được gắn ở chế độ đọc-ghi; các repo chỉ đọc. Xem hf-mount repository để biết tài liệu đầy đủ, bao gồm các tùy chọn backend, bộ nhớ đệm và chế độ ghi.

Volume Mounts trong Jobs và Spaces

Volume mounts trong Jobs và Spaces có cùng ý tưởng với hf-mount, được nền tảng quản lý cho bạn — không cần thiết lập thêm. Các bucket được gắn ở chế độ đọc-ghi theo mặc định.

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

Jobs cũng có thể nhận một thư mục cục bộ làm nguồn volume (-v ./training-data:/data): thư mục sẽ được đồng bộ hóa vào bucket jobs-artifacts riêng tư của bạn và được gắn từ đó, nhờ vậy các lần đồng bộ hóa tăng dần và việc kéo dữ liệu đầu ra về được thực hiện miễn phí.

Để biết cú pháp gắn volume đầy đủ và API Python, hãy xem tài liệu cấu hình Jobs và hướng dẫn gắn volume cho Spaces.

Truy vấn bằng DuckDB

DuckDB 2.0 trở lên sử dụng đường dẫn hf://buckets/ một cách bản địa thông qua tiện ích mở rộng httpfs (đọc) hoặc tiện ích mở rộng hf (đọc/ghi). Từ CLI của DuckDB hoặc bất kỳ client nào, hãy cài đặt và nạp httpfs, sau đó truy vấn một bucket:

INSTALL httpfs;
LOAD httpfs;

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

Glob patterns hoạt động tương tự như với datasets, ví dụ 'hf://buckets/username/my-bucket/data/**/*.parquet'. Buckets không được versioned, nên cú pháp @revision không áp dụng cho bucket paths. httpfs chỉ đọc; để ghi kết quả truy vấn vào bucket, hãy load extension hf (xem bên dưới).

Thư mục riêng tư: hãy tạo một bí mật Hugging Face trước. Nó sẽ lấy token từ hf auth login hoặc biến môi trường HF_TOKEN:

CREATE SECRET hf (TYPE huggingface, PROVIDER credential_chain);

Viết vào Hugging Face yêu cầu extension 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';

Trên DuckDB 1.x, httpfs không nhận diện các đường dẫn hf://buckets/. Thay vào đó, hãy đăng ký HfFileSystem từ Python, hoặc sử dụng API tương thích S3 từ CLI và các client khác.

Công cụ dữ liệu Python

HfFileSystem cung cấp khả năng truy cập bucket tương thích với fsspec bằng cách sử dụng đường dẫn hf://buckets/. Bất kỳ thư viện Python nào hỗ trợ fsspec đều có thể đọc và ghi dữ liệu bucket trực tiếp.

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

Để biết thêm về đường dẫn hf:// và các thao tác được hỗ trợ, hãy xem hướng dẫn HfFileSystem và hướng dẫn Python về Buckets.