透過檔案系統 API 與 Hub 互動

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

[!WARNING][HfFileSystem](/docs/huggingface_hub/v1.4.0/en/package_reference/hf_file_system#huggingface_hub.HfFileSystem) 提供 fsspec 相容性，這對於需要它的庫很有用（例如，直接使用 pandas 讀取 Hugging Face 資料集）。但是，由於這個相容層，它會引入額外的開銷。為了獲得更好的效能和可靠性，建議在可能的情況下使用 HfApi 方法。

用法

>>> from huggingface_hub import hffs

>>> # List all files in a 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 ".csv" files in a repo
>>> 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 引數可以傳遞給操作，以從特定的提交執行操作，例如分支、標籤名稱或提交雜湊。

與 Python 內建的 open 不同，fsspec 的 open 預設為二進位制模式 "rb"。這意味著您必須顯式地將模式設定為 "r" 來讀取，或設定為 "w" 來寫入文字模式。追加到檔案（模式 "a" 和 "ab"）尚不支援。

整合

HfFileSystem 可與任何集成了 fsspec 的庫一起使用，前提是 URL 遵循以下 scheme：

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

repo_type_prefix 對於資料集是 datasets/，對於 Space 是 spaces/，而模型不需要 URL 字首。

以下是一些 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")
  
  >>> # Write a dataframe to a remote CSV file
  >>> df.to_csv("hf://datasets/my-username/my-dataset-repo/test.csv")

相同的流程也可用於 Dask 和 Polars DataFrame。

• 使用 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 用作陣列儲存

  已複製

  >>> 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 互動。有關 Hub 上的身份驗證方法的更多資訊，請參閱文件的 身份驗證部分。

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

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

如果您以這種方式登入，請注意不要在共享原始碼時意外洩露令牌！