Tương tác với Hub thông qua Filesystem API

Ngoài HfApi, thư viện huggingface_hub còn cung cấp HfFileSystem, một giao diện tệp theo phong cách Python và tương thích fsspec cho Hugging Face Hub. HfFileSystem được xây dựng dựa trên HfApi và cung cấp các thao tác kiểu hệ thống tệp thông thường như cp, mv, ls, du, glob, get_file và put_file.

HfFileSystem cung cấp khả năng tương thích với fsspec, hữu ích cho các thư viện yêu cầu điều này (ví dụ: đọc trực tiếp datasets và buckets của Hugging Face bằng pandas). Tuy nhiên, lớp tương thích này gây ra thêm chi phí xử lý. Để đạt hiệu suất và độ tin cậy tốt hơn, nên sử dụng các phương thức của HfApi khi có thể.

Cách sử dụng

>>> from huggingface_hub import hffs

>>> # List all files in a dataset directory
>>> hffs.ls("datasets/my-username/my-dataset-repo/data", detail=False)
['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv']

>>> # List all files in a bucket directory
>>> hffs.ls("buckets/my-username/my-bucket/experiment-data", detail=False)
['bucket/my-username/my-bucket/data/train-0000.parquet', 'bucket/my-username/my-bucket/data/train-0001.parquet', ...]

>>> # List all ".csv" files in a dataset repository
>>> hffs.glob("datasets/my-username/my-dataset-repo/**/*.csv")
['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv']

>>> # Read a remote file
>>> with hffs.open("datasets/my-username/my-dataset-repo/data/train.csv", "r") as f:
...     train_data = f.readlines()

>>> # Read the content of a remote file as a string
>>> train_data = hffs.read_text("datasets/my-username/my-dataset-repo/data/train.csv", revision="dev")

>>> # Write a remote file
>>> with hffs.open("datasets/my-username/my-dataset-repo/data/validation.csv", "w") as f:
...     f.write("text,label")
...     f.write("Fantastic movie!,good")

Tham số tùy chọn revision có thể được truyền vào để thực hiện một thao tác từ một commit cụ thể, chẳng hạn như tên nhánh, tên tag, hoặc hash của commit. Lưu ý rằng revision không tương thích với Buckets.

Khác với open tích hợp sẵn của Python, open của fsspec mặc định ở chế độ nhị phân, "rb". Điều này có nghĩa là bạn phải đặt rõ mode là "r" để đọc và "w" để ghi ở chế độ văn bản. Việc thêm vào một tệp (các mode "a" và "ab") hiện chưa được hỗ trợ.

Liệt kê các kho lớn

Các thao tác liệt kê tệp đệ quy, chẳng hạn như find và glob, cần lấy toàn bộ nội dung của kho. Hub trả về các mục đó theo từng trang, và một trang chỉ có thể được yêu cầu sau khi trang trước đó đã được nhận: việc liệt kê một kho chứa 800k tệp yêu cầu ~800 yêu cầu tuần tự, và do đó mất khoảng 30 phút.

Để tránh điều đó, HfFileSystem liệt kê các kho lớn theo từng thư mục, song song:

>>> from huggingface_hub import hffs

>>> # Takes ~30s on a repository holding 800k files
>>> files = hffs.glob("datasets/allenai/objaverse/**/*.glb", maxdepth=3)

Số lượng yêu cầu đồng thời được kiểm soát bởi đối số max_workers của HfFileSystem. Giá trị mặc định là 16 và có thể đặt thành 1 để tắt việc liệt kê song song. Lưu ý rằng việc truyền maxdepth cũng giúp tăng tốc đáng kể quá trình liệt kê, vì khi đó Hub chỉ trả về các mục thực sự được yêu cầu.

Giữ cho danh sách luôn cập nhật

Các thư mục được liệt kê một lần và nội dung của chúng được lưu vào bộ nhớ đệm, do đó một thư mục vừa được người khác thay đổi sẽ không được tự động nhận ra. HfFileSystem.invalidate_cache() xóa các danh sách đã được lưu trong bộ nhớ đệm, cho một đường dẫn (và các thư mục cha của nó) hoặc cho toàn bộ khi được gọi không có đối số:

>>> hffs.ls("buckets/my-username/my-bucket/data", detail=False)  # listing is cached
>>> # ... another process uploads a file to the bucket ...
>>> hffs.invalidate_cache("buckets/my-username/my-bucket/data")
>>> hffs.ls("buckets/my-username/my-bucket/data", detail=False)  # listed again
['buckets/my-username/my-bucket/data/train.csv', 'buckets/my-username/my-bucket/data/new-file.csv']

Đối với bucket, huggingface_hub có thể thực hiện điều đó cho bạn: Hub sẽ stream các thay đổi tệp của bucket ngay khi chúng xảy ra và HfFileSystem sẽ loại bỏ các danh sách bị ảnh hưởng bởi một thay đổi ngay khi thay đổi đó đến. Bật tính năng này bằng live_follow=True:

>>> from huggingface_hub import HfFileSystem
>>> hffs = HfFileSystem(live_follow=True)
>>> hffs.ls("buckets/my-username/my-bucket/data", detail=False)  # starts following that bucket
>>> # ... another process uploads a file to the bucket ...
>>> hffs.ls("buckets/my-username/my-bucket/data", detail=False)  # refreshed as changes arrive
['buckets/my-username/my-bucket/data/train.csv', 'buckets/my-username/my-bucket/data/new-file.csv']

Nó cũng có thể được truyền qua fsspec, với fsspec.filesystem("hf", live_follow=True) hoặc thông qua đối số storage_options của các thư viện chấp nhận đối số này (pandas, arrow, …).

Một vài điều cần biết về nó:

Chỉ có Buckets. Các kho model, dataset và space là các kho git và Hub không stream các thay đổi của chúng: hãy truyền refresh=True vào HfFileSystem.ls() (hoặc dùng HfApi.list_repo_tree()) để xem một commit mới.
Chỉ danh sách và metadata đi kèm được làm mới. Việc đọc một tệp luôn yêu cầu nội dung của nó từ Hub, do đó việc theo dõi trực tiếp chỉ ảnh hưởng đến những gì ls, info, exists, glob, … báo cáo.
Quá trình theo dõi bắt đầu ngay khi một bucket được liệt kê, và một kết nối nền duy trì mở cho mỗi bucket được theo dõi, được chia sẻ bởi tất cả các instance HfFileSystem. Đó là lý do tùy chọn này là opt-in.

Tích hợp

HfFileSystem có thể được sử dụng với bất kỳ thư viện nào tích hợp fsspec, miễn là URL tuân theo sơ đồ:

hf://[<repo_type_prefix>]<repo_id>[@<revision>]/<path/in/repo>

repo_type_prefix là datasets/ cho datasets, spaces/ cho Spaces, và models không cần tiền tố trong URL.

Ngoài các kho lưu trữ, HfFileSystem còn hỗ trợ Hugging Face Buckets, một hệ thống lưu trữ đối tượng tương tự S3 (xem hướng dẫn này để biết thêm chi tiết):

hf://buckets/<bucket_id>/<path/in/bucket>

Một số tích hợp thú vị mà HfFileSystem giúp đơn giản hóa việc tương tác với Hub được liệt kê bên dưới:

Đọc/ghi DataFrame Pandas từ/vào kho Hub:

>>> import pandas as pd

>>> # Read a remote CSV file into a dataframe
>>> df = pd.read_csv("hf://datasets/my-username/my-dataset-repo/train.csv")
>>> df = pd.read_csv("hf://buckets/my-username/my-bucket/train.csv")

>>> # Write a dataframe to a remote CSV file
>>> df.to_csv("hf://datasets/my-username/my-dataset-repo/test.csv")
>>> df.to_csv("hf://buckets/my-username/my-bucket/test.csv")

Quy trình làm việc tương tự cũng có thể được sử dụng cho các DataFrame của Dask và Polars.

Truy vấn tệp Hub (từ xa) bằng DuckDB:

>>> from huggingface_hub import HfFileSystem
>>> import duckdb

>>> fs = HfFileSystem()
>>> duckdb.register_filesystem(fs)
>>> # Query a remote file and get the result back as a dataframe
>>> fs_query_file = "hf://datasets/my-username/my-dataset-repo/data_dir/data.parquet"
>>> df = duckdb.query(f"SELECT * FROM '{fs_query_file}' LIMIT 10").df()

Sử dụng Hub như một kho lưu trữ mảng với Zarr:

>>> import numpy as np
>>> import zarr

>>> embeddings = np.random.randn(50000, 1000).astype("float32")

>>> # Write an array to a repo
>>> root = zarr.open_group("hf://my-username/my-model-repo/array-store", mode="w")
>>> foo = root.create_group("embeddings")
>>> foobar = foo.zeros(name="experiment_0", shape=(50000, 1000), chunks=(10000, 1000), dtype="f4")
>>> foobar[:] = embeddings

>>> # Read an array from a repo
>>> root = zarr.open_group("hf://my-username/my-model-repo/array-store", mode="r")
>>> first_row = root["embeddings/experiment_0"][0]

Xác thực

Trong nhiều trường hợp, bạn phải đăng nhập bằng tài khoản Hugging Face để tương tác với Hub. Hãy tham khảo phần Authentication trong tài liệu để tìm hiểu thêm về các phương thức xác thực trên Hub.

Bạn cũng có thể đăng nhập theo cách lập trình bằng cách truyền token của bạn làm đối số cho HfFileSystem:

>>> from huggingface_hub import HfFileSystem
>>> hffs = HfFileSystem(token=token)

Nếu bạn đăng nhập theo cách này, hãy cẩn thận không vô tình lộ token khi chia sẻ mã nguồn của bạn!