Filesystem API

HfFileSystem 클래스는 fsspec 기반의 Hugging Face Hub에 대한 파이썬 스타일의 파일 인터페이스를 제공합니다.

HfFileSystem

HfFileSystem은 fsspec 기반으로 만들어졌기 때문에 fsspec이 제공하는 대부분의 API와 호환됩니다. 자세한 내용은 우리 가이드와 fsspec의 API Reference를 참고하세요.

class huggingface_hub.HfFileSystem

< source >

( *args**kwargs )

매개변수

endpoint (str, 선택 사항) — Hub의 엔드포인트입니다. 기본값은 https://huggingface.co입니다.
token (bool 또는 str, 선택) — 유효한 사용자 액세스 토큰(문자열)입니다. 기본값은 로컬에 저장된 토큰이며, 이는 인증을 위한 권장 방법입니다( https://huggingface.co/docs/huggingface_hub/quick-start#authentication 참조). 인증을 비활성화하려면 False를 전달하세요.
block_size (int, 선택 사항) — 파일 읽기 및 쓰기에 사용되는 블록 크기.
expand_info (bool, 선택 사항) — 파일의 정보를 확장할지 여부입니다.
max_workers (int, 선택) — 대형 디렉토리를 병렬로 나열할 때 사용되는 동시 요청의 최대 수( find() 참조). 기본값은 16입니다. 병렬 나열을 비활성화하려면 1로 설정하세요.
live_follow (bool, 선택 사항) — Hub에서 버킷의 파일 변경 사항이 발생하는 대로 이를 추적하여 수동 HfFileSystem.invalidate_cache() 호출 없이 캐시된 목록이 최신 상태를 유지할지 여부입니다. 활성화하면 버킷 목록을 조회할 때 해당 버킷의 Hub 이벤트 피드에 대한 백그라운드 연결이 열립니다. 모델, 데이터셋 및 스페이스 저장소에는 영향을 미치지 않습니다(Hub는 이러한 저장소의 변경 사항을 피드하지 않음).
**storage_options (dict, 선택 사항) — 파일 시스템에 대한 추가 옵션입니다. fsspec 문서를 참조하세요.

원격 Hugging Face Hub 저장소를 로컬 파일 시스템인 것처럼 액세스합니다.

HfFileSystem은 fsspec 호환성을 제공하며, 이를 요구하는 라이브러리(예: pandas로 Hugging Face datasets를 직접 읽는 경우)에 유용합니다. 그러나 이러한 호환성 레이어로 인해 추가 오버헤드가 발생합니다. 더 나은 성능과 안정성을 위해 가능할 경우 HfApi 메서드를 사용하는 것이 권장됩니다.

파일 시스템은 hf:// 프로토콜의 경로를 지원하며, 해당 URL 스킴을 따릅니다:

Models, Datasets, Spaces 저장소:

hf://<repo-id>[@<revision>]/<path/in/repo>
hf://datasets/<repo-id>[@<revision>]/<path/in/repo>
hf://spaces/<repo-id>[@<revision>]/<path/in/repo>

버킷(일반 저장소):

hf://buckets/<bucket-id>/<path/in/bucket>

참고: HfFileSystem를 직접 사용할 때, 경로에서 hf:// 프로토콜 접두사를 전달하는 것은 선택 사항입니다.

사용법:

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

인증에 사용할 토큰을 지정합니다:

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

cp_file

< source >

( path1: strpath2: strrevision: str | None = None**kwargs )

매개변수

path1 (str) — 복사할 소스 경로.
path2 (str) — 복사할 대상 경로.
revision (str, 선택 사항) — 복사할 git revision입니다.

리포지토리 내부 또는 리포지토리 간, 또는 버킷으로 파일을 복사합니다.

참고: 가능할 경우 더 나은 성능을 위해 HfApi.upload_file()를 사용하세요.

exists

< source >

( path**kwargs ) → bool

매개변수

path (str) — 확인할 경로.

반환값

bool

파일이 존재하면 True, 그렇지 않으면 False를 반환합니다.

파일이 존재하는지 확인합니다.

자세한 내용은 fsspec 문서를 참조하세요.

참고: 가능할 경우 더 나은 성능을 위해 HfApi.file_exists()를 사용하세요.

find

< source >

( path: strmaxdepth: int | None = Nonewithdirs: bool = Falsedetail: bool = Falserefresh: bool = Falserevision: str | None = None**kwargs ) → Union[list[str], dict[str, dict[str, Any]]]

매개변수

path (str) — 파일 목록을 가져올 루트 경로.
maxdepth (int, 선택 사항) — 하위 디렉터리로 내려갈 최대 깊이.
withdirs (bool, 선택 사항) — 출력에 디렉터리 경로를 포함합니다. 기본값은 False입니다.
detail (bool, 선택 사항) — True인 경우, 경로와 파일 정보를 매핑하는 dict를 반환합니다. 기본값은 False입니다.
refresh (bool, 선택 사항) — True인 경우 캐시를 우회하고 최신 데이터를 가져옵니다. 기본값은 False입니다.
revision (str, 선택 사항) — 목록을 가져올 git revision입니다.

반환값

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

경로의 목록 또는 파일 정보의 dict

경로 아래에 있는 모든 파일을 나열합니다.

자세한 내용은 fsspec 문서를 참조하세요.

대형 저장소는 Hub의 tree 엔드포인트가 사용하는 커서 기반 페이지네이션을 우회하기 위해 디렉터리별로 병렬로 나열됩니다. 이 동작은 HfFileSystem의 max_workers 인수로 조정할 수 있습니다.

get_file

< source >

( rpathlpath = Nonecallback = <fsspec.callbacks.NoOpCallback object at 0x7f9673955c90>outfile = None**kwargs )

매개변수

rpath (str) — 다운로드할 원격 경로.
lpath (str, 선택 사항) — 다운로드할 로컬 경로입니다. outfile이 제공된 경우 생략할 수 있습니다.
callback (Callback, 선택 사항) — 다운로드 진행 상황을 추적하기 위한 선택적 콜백입니다. 기본값은 콜백이 없는 것입니다.
outfile (IO, 선택 사항) — 쓰기 대상 파일 유사 객체입니다. 제공된 경우 lpath는 무시됩니다.

원격 파일 하나를 로컬로 복사합니다.

참고: 가능할 경우 더 나은 성능을 위해 HfApi.hf_hub_download() 또는 HfApi.download_bucket_files를 사용하세요.

glob

< source >

( path: strmaxdepth: int | None = None**kwargs ) → list[str]

매개변수

path (str) — 일치시킬 경로 패턴.
maxdepth (int, 선택 사항) — 디렉터리로 내려갈 최대 깊이입니다. 기본적으로 제한이 없습니다.

반환값

list[str]

패턴과 일치하는 경로 목록.

glob 매칭을 통해 파일을 찾습니다.

자세한 내용은 fsspec 문서를 참조하세요.

정보

< source >

( path: strrefresh: bool = Falserevision: str | None = None**kwargs ) → dict[str, Any]

매개변수

path (str) — 정보를 가져올 경로.
refresh (bool, 선택 사항) — True인 경우 캐시를 우회하고 최신 데이터를 가져옵니다. 기본값은 False입니다.
revision (str, 선택 사항) — 정보를 가져올 git revision입니다.

반환값

dict[str, Any]

파일 정보(유형, 크기, 커밋 정보 등)를 포함하는 사전입니다.

파일 또는 디렉토리에 대한 정보를 가져옵니다.

자세한 내용은 fsspec 문서를 참조하세요.

참고: 가능할 경우, 더 나은 성능을 위해 HfApi.get_paths_info() 또는 HfApi.repo_info()를 사용하세요 (버킷의 경우 HfApi.get_bucket_paths_info() 또는 HfApi.bucket_info() 사용)

invalidate_cache

< source >

( path: str | None = None )

매개변수

path (str, 선택 사항) — 캐시에서 지울 경로입니다. 제공되지 않으면 전체 캐시를 지웁니다.

지정된 경로에 대한 캐시를 지웁니다.

자세한 내용은 fsspec 문서를 참조하세요.

isdir

< source >

( path ) → bool

매개변수

path (str) — 확인할 경로.

반환값

bool

path가 디렉터리인 경우 True, 그렇지 않은 경우 False.

경로가 디렉터리인지 확인합니다.

자세한 내용은 fsspec 문서를 참조하세요.

isfile

< source >

( path ) → bool

매개변수

path (str) — 확인할 경로.

반환값

bool

path가 파일이면 True, 그렇지 않으면 False입니다.

경로가 파일인지 확인합니다.

자세한 내용은 fsspec 문서를 참조하세요.

ls

< source >

( path: strdetail: bool = Truerefresh: bool = Falserevision: str | None = None**kwargs ) → list[Union[str, dict[str, Any]]]

매개변수

path (str) — 디렉터리의 경로.
detail (bool, 선택 사항) — True인 경우 파일 정보를 포함하는 딕셔너리의 목록을 반환합니다. False인 경우 파일 경로 목록을 반환합니다. 기본값은 True입니다.
refresh (bool, 선택 사항) — True인 경우 캐시를 우회하고 최신 데이터를 가져옵니다. 기본값은 False입니다.
revision (str, 선택 사항) — 목록을 가져올 git revision입니다.

반환값

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

detail=False인 경우 파일 경로 목록 또는 detail=True인 경우 파일 정보 딕셔너리 목록

디렉터리의 내용을 나열합니다.

자세한 내용은 fsspec 문서를 참조하세요.

참고: 가능할 경우 더 나은 성능을 위해 HfApi.list_repo_tree()를 사용하세요.

수정됨

< source >

( path: str**kwargs ) → datetime

매개변수

path (str) — 파일 경로.

반환값

datetime

파일의 마지막 수정 시간.

파일의 마지막 수정 시간을 가져옵니다.

자세한 내용은 fsspec 문서를 참조하세요.

resolve_path

< source >

( path: strrevision: str | None = None ) → HfFileSystemResolvedPath

매개변수

path (str) — 해결할 경로.
revision (str, 선택 사항) — 해결할 리포지토리의 리비전입니다. 기본값은 경로에 지정된 리비전입니다.

반환값

HfFileSystemResolvedPath

repo_type, repo_id, revision, path_in_repo를 포함하는 해결된 경로 정보.

다음 예외가 발생합니다

ValueError 또는 NotImplementedError

ValueError — path에 충돌하는 revision 정보가 포함된 경우.
NotImplementedError — 리포지토리 목록을 가져오려고 할 때 발생합니다.

Hugging Face 파일 시스템 경로를 구성 요소로 분해합니다.

rm

< source >

( path: strrecursive: bool = Falsemaxdepth: int | None = Nonerevision: str | None = None**kwargs )

매개변수

path (str) — 삭제할 경로.
recursive (bool, 선택 사항) — True인 경우, 디렉터리와 그 모든 내용을 삭제합니다. 기본값은 False입니다.
maxdepth (int, 선택 사항) — 재귀적으로 삭제할 때 방문할 하위 디렉터리의 최대 개수.
revision (str, 선택 사항) — 삭제할 git revision입니다.

리포지토리에서 파일을 삭제합니다.

자세한 내용은 fsspec 문서를 참조하세요.

참고: 가능할 경우 더 나은 성능을 위해 HfApi.delete_file()를 사용하세요.

url

< source >

( path: str ) → str

매개변수

path (str) — URL을 가져올 경로.

반환값

str

Hub에서 파일 또는 디렉터리에 액세스하기 위한 HTTP URL.

주어진 경로의 HTTP URL을 가져옵니다.

걸음

< source >

( path: str*args**kwargs ) → Iterator[tuple[str, list[str], list[str]]]

매개변수

path (str) — 파일 목록을 가져올 루트 경로.

반환값

Iterator[tuple[str, list[str], list[str]]]

(path, 디렉터리 이름 목록, 파일 이름 목록) 튜플의 반복자입니다.

…

자세한 내용은 fsspec 문서를 참조하세요.

Update on GitHub

Hub Python Library

Filesystem API

HfFileSystem

class huggingface_hub.HfFileSystem

cp_file

exists

find

get_file

glob

정보

invalidate_cache

isdir

isfile

ls

수정됨

resolve_path

rm

url

걸음