透過 Filesystem API 與 Hub 互動

除了 HfApi 之外，huggingface_hub 程式庫還提供了 HfFileSystem，這是一個針對 Hugging Face Hub 的 Python 風格 fsspec 相容檔案介面。HfFileSystem 建構於 HfApi 之上，並提供常見的檔案系統風格操作，如 cp、mv、ls、du、glob、get_file 和 put_file。

[!WARNING][HfFileSystem](/docs/huggingface_hub/v1.16.2/en/package_reference/hf_file_system#huggingface_hub.HfFileSystem) 提供了 fsspec 相容性，對於需要此功能的程式庫非常有用（例如直接使用 pandas 讀取 Hugging Face 資料集和儲存貯體/buckets）。然而，由於此相容層的存在，它會引入額外的負載。為了獲得更好的效能與可靠性，建議盡可能使用 HfApi 方法。

使用方式

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

可以傳遞選用的 revision 引數，以執行來自特定提交（例如分支、標籤名稱或提交雜湊值）的操作。請注意，revision 與儲存貯體 (Buckets) 不相容。

與 Python 內建的 open 不同，fsspec 的 open 預設為二進位模式 "rb"。這意味著如果您要在文字模式下進行讀取和寫入，必須明確將模式設定為 "r" 和 "w"。目前尚未支援附加到檔案（模式 "a" 和 "ab"）。

整合

HfFileSystem 可以與任何整合了 fsspec 的程式庫搭配使用，前提是 URL 遵循以下架構：

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

repo_type_prefix 對於資料集為 datasets/，對於 Spaces 為 spaces/，而模型在 URL 中不需要前綴。

除了儲存庫之外，HfFileSystem 也支援 Hugging Face 儲存貯體 (Buckets)，這是一種類似 S3 的物件儲存空間（請參閱此指南以了解更多詳情）。

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

以下列出了一些 HfFileSystem 可簡化與 Hub 互動的有趣整合範例：

• 從 Hub 儲存庫讀取/寫入 Pandas DataFrame

  已複製

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

相同的工作流程也可用於 Dask 和 Polars DataFrames。

• 使用 DuckDB 查詢 (遠端) Hub 檔案

  已複製

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

• 使用 Zarr 將 Hub 用作陣列儲存 (Array Store)

  已複製

  >>> import numpy as np
  >>> import zarr
  
  >>> embeddings = np.random.randn(50000, 1000).astype("float32")
  
  >>> # Write an array to a repo
  >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="w") as root:
  ...    foo = root.create_group("embeddings")
  ...    foobar = foo.zeros('experiment_0', shape=(50000, 1000), chunks=(10000, 1000), dtype='f4')
  ...    foobar[:] = embeddings
  
  >>> # Read an array from a repo
  >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="r") as root:
  ...    first_row = root["embeddings/experiment_0"][0]

身份驗證

在許多情況下，您必須登入 Hugging Face 帳戶才能與 Hub 互動。請參閱說明文件的身份驗證 (Authentication) 章節，以了解更多關於 Hub 上的身份驗證方法。

您也可以透過將 token 作為引數傳遞給 HfFileSystem，以程式化的方式登入。

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

如果採用此方式登入，請務必小心，以免在分享原始碼時不慎外洩 Token！