huggingface_hub/pr_4113/ko/package_reference/hf_file_system.md

파일 시스템 API[[filesystem-api]]

HfFileSystem 클래스는 fsspec을 기반으로 Hugging Face Hub에 Python 파일 인터페이스를 제공합니다.

HfFileSystem[[huggingface_hub.HfFileSystem]]

HfFileSystem은 fsspec을 기반으로 하므로 제공되는 대부분의 API와 호환됩니다. 자세한 내용은 가이드 및 fsspec의 API 레퍼런스를 확인하세요.

huggingface_hub.HfFileSystem[[huggingface_hub.HfFileSystem]]

Source

Access a remote Hugging Face Hub repository as if were a local file system.

HfFileSystem provides fsspec compatibility, which is useful for libraries that require it (e.g., reading Hugging Face datasets directly with pandas). However, it introduces additional overhead due to this compatibility layer. For better performance and reliability, it's recommended to use HfApi methods when possible.

The file system supports paths for the hf:// protocol, which follows those URL schemes:

• Models, Datasets and Spaces repositories:

hf://[@]/
hf://datasets/[@]/
hf://spaces/[@]/

• Buckets (generic storage):

hf://buckets//

Note: when using the HfFileSystem directly, passing the hf:// protocol prefix is optional in paths.

Usage:

>>> from huggingface_hub import hffs

>>> # List files
>>> hffs.glob("my-username/my-model/*.bin")
['my-username/my-model/pytorch_model.bin']
>>> hffs.ls("datasets/my-username/my-dataset", detail=False)
['datasets/my-username/my-dataset/.gitattributes', 'datasets/my-username/my-dataset/README.md', 'datasets/my-username/my-dataset/data.json']

>>> # Read/write files
>>> with hffs.open("my-username/my-model/pytorch_model.bin") as f:
...     data = f.read()
>>> with hffs.open("my-username/my-model/pytorch_model.bin", "wb") as f:
...     f.write(data)

Specify a token for authentication:

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

__init__huggingface_hub.HfFileSystem.__init__https://github.com/huggingface/huggingface_hub/blob/vr_4113/src/huggingface_hub/hf_file_system.py#L206[{"name": "*args", "val": ""}, {"name": "endpoint", "val": ": str | None = None"}, {"name": "token", "val": ": bool | str | None = None"}, {"name": "block_size", "val": ": int | None = None"}, {"name": "expand_info", "val": ": bool | None = None"}, {"name": "**storage_options", "val": ""}]

Parameters:

endpoint (str, optional) : Endpoint of the Hub. Defaults to .

token (bool or str, optional) : A valid user access token (string). Defaults to the locally saved token, which is the recommended method for authentication (see https://huggingface.co/docs/huggingface_hub/quick-start#authentication). To disable authentication, pass False.

block_size (int, optional) : Block size for reading and writing files.

expand_info (bool, optional) : Whether to expand the information of the files.

• **storage_options (dict, optional) : Additional options for the filesystem. See fsspec documentation.

resolve_path[[huggingface_hub.HfFileSystem.resolve_path]]

Source

Resolve a Hugging Face file system path into its components.

Parameters:

path (str) : Path to resolve.

revision (str, optional) : The revision of the repo to resolve. Defaults to the revision specified in the path.

Returns:

HfFileSystemResolvedPath

Resolved path information containing repo_type, repo_id, revision and path_in_repo.

ls[[huggingface_hub.HfFileSystem.ls]]

Source

List the contents of a directory.

For more details, refer to fsspec documentation.

Note: When possible, use HfApi.list_repo_tree() for better performance.

Parameters:

path (str) : Path to the directory.

detail (bool, optional) : If True, returns a list of dictionaries containing file information. If False, returns a list of file paths. Defaults to True.

refresh (bool, optional) : If True, bypass the cache and fetch the latest data. Defaults to False.

revision (str, optional) : The git revision to list from.

Returns:

list[Union[str, dict[str, Any]]]

List of file paths (if detail=False) or list of file information dictionaries (if detail=True).