파일 다운로드

Download a single file

hf_hub_download

huggingface_hub.hf_hub_download

매개변수

repo_id (str) — /로 구분된 사용자 또는 조직 이름과 저장소 이름.
filename (str) — 리포지토리 내 파일 이름.
subfolder (str, 선택 사항) — 모델 저장소 안의 폴더에 해당하는 선택 값입니다.
repo_type (str, 선택 사항) — dataset, space 또는 kernel 저장소에서 다운로드하는 경우 "dataset", "space" 또는 "kernel"로 설정하고, 모델에서 다운로드하는 경우 None 또는 "model"로 설정합니다. 기본값은 None입니다.
revision (str, 선택 사항) — 브랜치 이름, 태그 또는 커밋 해시일 수 있는 선택적 Git 리비전 ID입니다.
library_name (str, 선택 사항) — 해당 객체가 대응하는 라이브러리의 이름입니다.
library_version (str, 선택 사항) — 라이브러리의 버전입니다.
cache_dir (str, Path, 선택 사항) — 캐시된 파일이 저장되는 폴더의 경로입니다.
local_dir (str 또는 Path, 선택 사항) — 제공된 경우, 다운로드된 파일은 이 디렉터리 아래에 저장됩니다.
user_agent (dict, str, 선택 사항) — 사전 또는 문자열 형태의 user-agent 정보입니다.
force_download (bool, 선택 사항, 기본값 False) — 로컬 캐시에 이미 존재하더라도 파일을 다운로드할지 여부.
etag_timeout (float, 선택 사항, 기본값 10) — ETag를 가져올 때 서버가 데이터를 보내기까지 대기할 초 수입니다. 이 값은 httpx2.request에 전달됩니다.
token (str, bool, 선택 사항) — 다운로드에 사용할 토큰입니다. True인 경우 HuggingFace 설정 폴더에서 토큰을 읽습니다. 문자열인 경우 인증 토큰으로 사용됩니다.
- True인 경우, 토큰은 HuggingFace config 폴더에서 읽힙니다.
- 문자열인 경우 인증 토큰으로 사용됩니다.
local_files_only (bool, 선택 사항, 기본값 False) — True인 경우, 파일을 다운로드하지 않고 로컬 캐시 파일이 존재하면 해당 파일의 경로를 반환합니다.
headers (dict, 선택) — 요청과 함께 전송할 추가 헤더입니다.
endpoint (str, 선택 사항) — 요청을 보낼 Hub 엔드포인트입니다. 기본값은 HF_ENDPOINT 값입니다.
tqdm_class (tqdm, 선택 사항) — 지정하면 진행 표시줄의 기본 동작을 덮어씁니다. 전달된 인수는 tqdm.auto.tqdm을 상속하거나 최소한 그 동작을 모방해야 합니다. 기본값은 HF_HUB_DISABLE_PROGRESS_BARS 환경 변수를 설정하여 비활성화할 수 있는 HF의 사용자 정의 진행 표시줄입니다.
dry_run (bool, 선택 사항, 기본값 False) — True인 경우, 파일을 실제로 다운로드하지 않고 dry run을 수행합니다. 다운로드될 내용에 대한 정보를 포함하는 DryRunFileInfo 객체를 반환합니다.

반환값

str 또는 DryRunFileInfo

dry_run=False인 경우: 파일의 로컬 경로 또는 네트워크가 꺼져 있는 경우 디스크에 캐시된 파일의 마지막 버전.
dry_run=True인 경우: 다운로드 정보를 포함하는 DryRunFileInfo 객체.

다음 예외가 발생합니다

RepositoryNotFoundError 또는 RevisionNotFoundError 또는 ~utils.RemoteEntryNotFoundError 또는 LocalEntryNotFoundError 또는 EnvironmentError 또는 OSError 또는 ValueError

RepositoryNotFoundError — 다운로드할 저장소를 찾을 수 없는 경우. 저장소가 존재하지 않거나, private로 설정되어 있어 접근 권한이 없는 경우일 수 있습니다.
RevisionNotFoundError — 다운로드할 리비전이 찾을 수 없는 경우.
~utils.RemoteEntryNotFoundError — 다운로드할 파일을 찾을 수 없는 경우.
LocalEntryNotFoundError — 네트워크가 비활성화되었거나 사용할 수 없고 캐시에서 파일을 찾을 수 없는 경우.
EnvironmentError — token=True이지만 토큰을 찾을 수 없는 경우.
OSError — ETag을 결정할 수 없는 경우.
ValueError — 일부 매개변수 값이 잘못된 경우.

local cache에 이미 존재하지 않는 경우 주어진 파일을 다운로드합니다.

새로운 캐시 파일 레이아웃은 다음과 같습니다:

캐시 디렉터리에는 repo_id별로(리포 유형으로 네임스페이스가 지정된) 하위 폴더가 하나씩 포함되어 있습니다
각 저장소 폴더 안에는:
- refs는 최신 알려진 revision => commit_hash 쌍의 목록입니다
- blobs에는 실제 파일 blobs가 포함됩니다(LFS 파일인지 여부에 따라 git-sha 또는 sha256으로 식별됩니다).
- snapshots에는 커밋별로 하나의 하위 폴더가 포함되어 있으며, 각 “commit”에는 해당 특정 커밋에서 해결된 파일의 부분 집합이 들어 있습니다. 각 파일 이름은 해당 특정 커밋의 blob으로 향하는 심볼릭 링크입니다.

[  96]  .
└── [ 160]  models--julien-c--EsperBERTo-small
    ├── [ 160]  blobs
    │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
    │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
    ├── [  96]  refs
    │   └── [  40]  main
    └── [ 128]  snapshots
        ├── [ 128]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f
        │   ├── [  52]  README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
        │   └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        └── [ 128]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48
            ├── [  52]  README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
            └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd

local_dir가 제공되면, 저장소의 파일 구조가 해당 위치에 복제됩니다. 이 옵션을 사용할 경우 cache_dir은 사용되지 않으며, 다운로드된 파일과 관련된 일부 메타데이터를 저장하기 위해 local_dir의 루트에 .cache/huggingface/ 폴더가 생성됩니다. 이 메커니즘은 메인 캐시 시스템만큼 견고하지는 않지만, 저장소의 최신 버전을 정기적으로 가져오는 작업에 최적화되어 있습니다.

hf_hub_url

huggingface_hub.hf_hub_url

< source >

( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Noneendpoint: str | None = None )

매개변수

repo_id (str) — /로 구분된 네임스페이스(사용자 또는 조직) 이름과 저장소 이름
filename (str) — 리포지토리 내 파일 이름.
subfolder (str, 선택 사항) — 리포지토리 내부의 폴더에 해당하는 선택적 값입니다.
repo_type (str, 선택 사항) — dataset, space 또는 kernel 저장소에서 다운로드하는 경우 "dataset", "space" 또는 "kernel"로 설정하고, 모델에서 다운로드하는 경우 None 또는 "model"로 설정합니다. 기본값은 None입니다.
revision (str, 선택 사항) — 브랜치 이름, 태그 또는 커밋 해시일 수 있는 선택적 Git 리비전 ID입니다.
endpoint (str, 선택 사항) — 요청을 보낼 Hub 엔드포인트입니다. 기본값은 HF_ENDPOINT 값입니다.

주어진 정보로부터 파일의 URL을 구성합니다.

해결된 주소는 huggingface.co에서 호스팅되는 URL이거나, 몇 MB를 초과하는 대용량 파일에 대한 Cloudfront(콘텐츠 전송 네트워크, CDN) 링크일 수 있습니다.

예:

>>> from huggingface_hub import hf_hub_url

>>> hf_hub_url(
...     repo_id="julien-c/EsperBERTo-small", filename="pytorch_model.bin"
... )
'https://huggingface.co/julien-c/EsperBERTo-small/resolve/main/pytorch_model.bin'

참고:

Cloudfront은 전 세계에 복제되어 있어 최종 사용자의 다운로드 속도가 훨씬 빠릅니다(또는 대역폭 비용을 줄여줍니다).

Cloudfront은 기본적으로 파일을 공격적으로 캐시합니다(기본 TTL은 24시간) 하지만, huggingface.co에서 git 기반 버전 관리 시스템을 구현하고 있기 때문에 여기서는 문제가 되지 않습니다. 이는 S3/Cloudfront에 파일을 콘텐츠 주소 방식으로 저장한다는 것을 의미하며(즉, 파일 이름이 해당 파일의 해시값임), 콘텐츠 주소 방식의 파일 이름을 사용하면 캐시가 절대 오래된 상태로 남지 않습니다.

이 라이브러리의 클라이언트 측 캐싱은 리소스의 특정 버전을 식별하는 객체의 엔티티 태그(ETag)를 기반으로 합니다 [1]_. 객체의 ETag는 git에 저장된 경우 git-sha1, git-lfs에 저장된 경우 sha256입니다.

참고 문헌:

[1] https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag

레포지토리의 스냅샷 다운로드

huggingface_hub.snapshot_download

< source >

매개변수

repo_id (str) — /로 구분된 사용자 또는 조직 이름과 저장소 이름.
repo_type (str, 선택 사항) — dataset, space 또는 kernel 저장소에서 다운로드하는 경우 "dataset", "space" 또는 "kernel"로 설정하고, 모델에서 다운로드하는 경우 None 또는 "model"로 설정합니다. 기본값은 None입니다.
revision (str, 선택 사항) — 분기 이름, 태그 또는 커밋 해시일 수 있는 선택적 Git 리비전 ID입니다.
cache_dir (str, Path, 선택 사항) — 캐시된 파일이 저장되는 폴더의 경로입니다.
local_dir (str 또는 Path, 선택 사항) — 지정된 경우, 다운로드된 파일은 이 디렉터리 아래에 저장됩니다.
library_name (str, 선택 사항) — 해당 객체가 대응하는 라이브러리의 이름입니다.
library_version (str, 선택 사항) — 라이브러리의 버전입니다.
user_agent (str, dict, 선택 사항) — 사전 또는 문자열 형태의 user-agent 정보입니다.
etag_timeout (float, 선택 사항, 기본값 10) — ETag를 가져올 때 서버가 데이터를 보내기까지 대기할 초 수입니다. 이 값은 httpx2.request에 전달됩니다.
force_download (bool, 선택 사항, 기본값 False) — 로컬 캐시에 이미 존재하더라도 파일을 다운로드할지 여부입니다.
token (str, bool, 선택 사항) — 다운로드에 사용할 토큰입니다. True인 경우 HuggingFace 설정 폴더에서 토큰을 읽습니다. 문자열인 경우 인증 토큰으로 사용됩니다.
- True인 경우, 토큰은 HuggingFace config 폴더에서 읽힙니다.
- 문자열인 경우 인증 토큰으로 사용됩니다.
headers (dict, 선택) — 요청에 포함할 추가 헤더입니다. 이 헤더들은 다른 헤더보다 우선합니다.
endpoint (str, 선택 사항) — 요청을 보낼 Hub 엔드포인트입니다. 기본값은 HF_ENDPOINT 값입니다.
local_files_only (bool, 선택 사항, 기본값 False) — True인 경우, cache_dir 또는 local_dir에 파일이 없더라도 파일을 다운로드하지 않습니다.
allow_patterns (list[str] 또는 str, 선택 사항) — 제공된 경우, 하나 이상의 패턴과 일치하는 파일만 다운로드됩니다.
ignore_patterns (list[str] 또는 str, 선택 사항) — 제공된 경우, 해당 패턴 중 하나와 일치하는 파일은 다운로드되지 않습니다.
max_workers (int, 선택 사항) — 파일을 다운로드할 동시 실행 스레드 수(1 스레드 = 1개 파일 다운로드)입니다. 기본값은 8입니다.
tqdm_class (tqdm, 선택 사항) — 지정하면 진행 표시줄의 기본 동작을 덮어씁니다. 전달된 인수는 tqdm.auto.tqdm에서 상속되거나 최소한 그 동작을 모방해야 합니다. tqdm_class는 각 개별 다운로드에 전달되지 않는다는 점에 유의하세요. HF_HUB_DISABLE_PROGRESS_BARS 환경 변수를 설정하여 비활성화할 수 있는 커스텀 HF 진행 표시줄이 기본값입니다.
dry_run (bool, 선택 사항, 기본값 False) — True인 경우, 파일을 실제로 다운로드하지 않고 dry run을 수행합니다. 다운로드될 내용에 대한 정보를 포함하는 DryRunFileInfo 객체의 목록을 반환합니다.

반환값

str 또는 DryRunFileInfo의 목록

dry_run=False인 경우: 로컬 스냅샷 경로.
dry_run=True인 경우: 다운로드 정보를 포함하는 DryRunFileInfo 객체의 목록을 반환합니다.

다음 예외가 발생합니다

RepositoryNotFoundError 또는 RevisionNotFoundError 또는 IncompleteSnapshotError 또는 EnvironmentError 또는 OSError 또는 ValueError

RepositoryNotFoundError — 다운로드할 저장소를 찾을 수 없는 경우 발생합니다. 저장소가 존재하지 않거나, private로 설정되어 있어 접근 권한이 없는 경우일 수 있습니다.
RevisionNotFoundError — 다운로드할 리비전이 찾을 수 없는 경우.
IncompleteSnapshotError — Hub에 연결할 수 없는 경우(오프라인, 연결 문제 또는 local_files_only=True)에 캐시된 스냅샷에 요청한 파일 중 일부가 없는 경우.
EnvironmentError — token=True이고 토큰을 찾을 수 없는 경우.
OSError — ETag을 결정할 수 없는 경우.
ValueError — 일부 매개변수 값이 잘못된 경우.

Download repo files.

지정된 리비전에서 저장소의 파일 전체 스냅샷을 다운로드합니다. 사전에 어떤 파일이 필요한지 알 수 없는 경우, 저장소의 모든 파일이 필요할 때 유용합니다. 모든 파일은 해당 폴더에 대한 상대 경로와 파일명을 유지하도록 폴더 안에 중첩됩니다. allow_patterns와 ignore_patterns를 사용하여 다운로드할 파일을 필터링할 수도 있습니다.

대안으로 저장소를 클론하는 방법이 있지만, 이 경우 git과 git-lfs가 설치되어 올바르게 구성되어야 합니다. 또한 git을 사용하여 저장소를 클론할 때 다운로드할 파일을 필터링하는 것은 불가능합니다.

캐시된 저장소 트리를 읽습니다

huggingface_hub.get_cached_repo_tree

< source >

매개변수

repo_id (str) — /로 구분된 사용자 또는 조직 이름과 저장소 이름.
repo_type (str, 선택 사항) — dataset, space 또는 kernel 리포에서 목록을 가져오는 경우 "dataset", "space" 또는 "kernel"로 설정하고, 모델에서 목록을 가져오는 경우 None 또는 "model"로 설정합니다. 기본값은 None입니다.
revision (str, 선택 사항) — 분기 이름, 태그 또는 커밋 해시일 수 있는 선택적 Git 리비전 ID입니다. 기본값은 기본 분기입니다. 분기/태그 이름은 로컬 캐시(refs/)를 사용하여 커밋 해시로 해석됩니다.
cache_dir (str, Path, 선택 사항) — 캐시된 파일이 저장되는 폴더의 경로입니다. 기본값은 HF_HUB_CACHE의 값입니다.
local_dir (str 또는 Path, 선택 사항) — 지정된 경우, 메인 캐시 대신 local_dir 다운로드에 의해 캐시된 트리 목록(local_dir/.cache/huggingface/에서)을 읽습니다. 브랜치/태그 리비전은 여전히 메인 캐시(cache_dir)를 사용하여 커밋 해시로 해석됩니다.

반환값

list[RepoFile]

이 리비전에서 캐시된 RepoFile 객체의 목록입니다.

다음 예외가 발생합니다

CachedRepoTreeNotFoundError

CachedRepoTreeNotFoundError — 요청된 리비전(예: 해당 리비전으로 저장소가 다운로드된 적이 없는 경우)에 대해 트리 목록이 캐시에 없으면 발생합니다.

…

트리 목록은 특정 커밋 시점의 저장소 파일 집합(다운로드 메타데이터 포함)입니다. snapshot_download() 실행 시 부수 효과로 디스크에 저장되며(trees/<commit_hash>.json 캐시 파일 참조), 이후 다운로드 시 네트워크 호출을 건너뛰는 데 사용됩니다. 이 함수는 해당 캐시를 직접 노출합니다.

Hub의 저장소에서 현재 트리 목록이 필요하면 list_repo_tree()를 대신 사용하세요.

예:

>>> from huggingface_hub import get_cached_repo_tree
>>> files = get_cached_repo_tree("openai-community/gpt2")
>>> [f.path for f in files]
['.gitattributes', 'config.json', 'model.safetensors', ...]

리비전 해결

브랜치/태그 이름을 커밋 해시로 한 번만 해석한 후, 그 결과를 전달하여 모든 다운로드를 동일한 커밋에 고정하세요. HfApi.resolve_revision() 및 cache-system 가이드를 참조하세요.

ResolvedRevision

클래스 huggingface_hub.ResolvedRevision

< source >

( resolved: strinitial: str | None = Nonerepo_id: str | None = Nonerepo_type: str | None = None )

매개변수

initial (str 또는 None) — 사용자가 처음 요청한 revision입니다. None인 경우, 문자열 값은 기본적으로 "main"으로 설정됩니다.
resolved (str) — initial이(가) 해석되는 커밋 해시입니다.

이미 커밋 해시로 해석된 git 리비전입니다.

ResolvedRevision은 str의 하위 클래스이므로, revision 인수를 받는 모든 huggingface_hub 메서드에 전달할 수 있습니다. 문자열 값은 사용자가 처음 요청한 리비전(예: "main", "refs/pr/4")으로, URL과 오류 메시지의 가독성을 유지하는 반면, .resolved에는 해당 리비전이 가리키는 커밋 해시가 저장됩니다.

Instances는 revision -> commit hash 매핑을 로컬 캐시(refs/ 폴더)에 캐시하는 HfApi.resolve_revision()을 통해 생성됩니다.

커밋 해시는 해당 해시가 해석된 저장소에서만 의미를 가지므로, 인스턴스는 해당 저장소도 함께 기억합니다. 다른 저장소에 대해 다시 해석하는 것은 오류가 아닙니다. 처음 요청된 리비전이 다시 해석됩니다(HfApi.resolve_revision() 참조).

예:

>>> from huggingface_hub import resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')
>>> revision == "main"  # it's a string
True
>>> revision.resolved
'607a30d783dfa663caf39e06633721c8d4cfcd7e'

파일 메타데이터 가져오기

get_hf_file_metadata

huggingface_hub.get_hf_file_metadata

< source >

매개변수

url (str) — hf_hub_url()에서 반환된 것과 같은 파일 URL
token (str 또는 bool, 선택 사항) — 다운로드에 사용할 토큰입니다. True인 경우 HuggingFace 설정 폴더에서 토큰을 읽습니다. False 또는 None인 경우 토큰을 제공하지 않습니다. 문자열인 경우 인증 토큰으로 사용됩니다.
- True인 경우, 토큰은 HuggingFace config 폴더에서 읽힙니다.
- False 또는 None인 경우, 토큰이 제공되지 않습니다.
- 문자열인 경우 인증 토큰으로 사용됩니다.
timeout (float, 선택 사항, 기본값 10) — 서버가 메타데이터를 보내기까지 대기할 초 단위입니다.
library_name (str, 선택 사항) — 해당 객체가 대응하는 라이브러리의 이름입니다.
library_version (str, 선택 사항) — 라이브러리의 버전입니다.
user_agent (dict, str, 선택 사항) — 사전 또는 문자열 형태의 user-agent 정보입니다.
headers (dict, 선택) — 요청과 함께 전송할 추가 헤더입니다.
endpoint (str, 선택 사항) — Hub의 엔드포인트입니다. 기본값은 https://huggingface.co입니다.
retry_on_errors (bool, 선택 사항, 기본값 False) — 오류(429, 5xx, 타임아웃, 네트워크 오류) 발생 시 재시도할지 여부입니다. False인 경우 로컬 캐시로 빠르게 폴백하기 위해 재시도를 하지 않습니다.

주어진 url에 대해 Hub에서 버전 관리된 파일의 메타데이터를 가져옵니다.

HfFileMetadata

class huggingface_hub.HfFileMetadata

< source >

( commit_hash: str | Noneetag: str | Nonelocation: strsize: int | Nonexet_file_data: huggingface_hub.utils._xet.XetFileData | None )

매개변수

commit_hash (str, 선택 사항) — 해당 파일과 관련된 commit_hash입니다.
etag (str, 선택 사항) — 서버에 있는 파일의 Etag입니다.
location (str) — 파일을 다운로드할 위치입니다. Hub URL이거나 (CDN) 아닐 수 있습니다.
size (size) — 파일의 크기입니다. LFS 파일인 경우 포인터가 아닌 실제 LFS 파일의 크기를 포함합니다.
xet_file_data (XetFileData, 선택 사항) — 해당 파일의 Xet 정보입니다. 파일이 Xet 스토리지에 저장된 경우에만 설정됩니다.

Hub에서 버전 관리되는 파일에 대한 정보를 포함하는 데이터 구조입니다.

URL을 기반으로 get_hf_file_metadata()가 반환합니다.

캐싱

위에서 표시된 메서드는 파일을 다시 다운로드하는 것을 방지하는 캐싱 시스템과 함께 작동하도록 설계되었습니다. 이 캐싱 시스템은 v0.8.0에서 업데이트되어 Hub에 의존하는 라이브러리 전체에서 공유되는 중앙 캐싱 시스템이 되었습니다.

HF의 캐싱에 대한 자세한 설명은 cache-system 가이드를 참고하세요.

Update on GitHub

Hub Python Library

파일 다운로드

Download a single file

hf_hub_download

huggingface_hub.hf_hub_download

hf_hub_url

huggingface_hub.hf_hub_url

레포지토리의 스냅샷 다운로드

huggingface_hub.snapshot_download

캐시된 저장소 트리를 읽습니다

huggingface_hub.get_cached_repo_tree

리비전 해결

ResolvedRevision

클래스 huggingface_hub.ResolvedRevision

파일 메타데이터 가져오기

get_hf_file_metadata

huggingface_hub.get_hf_file_metadata

HfFileMetadata

class huggingface_hub.HfFileMetadata

캐싱